diff --git a/.github/AGENT_MEMORY.md b/.github/AGENT_MEMORY.md index 08257eddd..6a3f81979 100644 --- a/.github/AGENT_MEMORY.md +++ b/.github/AGENT_MEMORY.md @@ -13,12 +13,15 @@ Z-Shell uses GitHub-native records as the shared memory between humans and LLM a ## Agent Workflow +External writes require explicit authorization. Without it, report the proposed issue, comment, or tracker update instead of performing it. + Before starting non-trivial work: 1. Search the owning repository for open issues and pull requests related to the task. 2. Check linked tracker items and previous handoff comments. 3. Prefer the most recent GitHub-visible state over local notes or LLM memory. -4. If no issue exists for planned or deferred work, create one in the owning repository. +4. If no issue exists for planned or deferred work, propose one. Create it only + when explicit external-write authority is present. While working: diff --git a/AGENTS.md b/AGENTS.md index f84c3fcdf..b5f71d8c2 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -13,6 +13,8 @@ This file is intentionally short. It complements, not replaces: Before non-trivial work, inspect `.github/instruction-surfaces.json`. This applies to every supported runtime. Match the current task categories and repository-relative file patterns against each manifest surface. When a surface declares both task and path dimensions, both dimensions must match before selecting it. Read every matched required surface before acting. If a runtime does not auto-load scoped guidance, open each matched required surface explicitly. Repeat this selection whenever the task, path, or repository scope changes. +Treat byte-exact instruction content already present in the active instruction context as loaded. Manifest ownership entries and repository links do not request a second read. Re-evaluate only when the task, path, repository scope, or content changes. + ## Agent-file placement Organization repository roots use `AGENTS.md` and permitted `.github/*` instruction surfaces. They must not contain root `CLAUDE.md` or `GEMINI.md`. @@ -83,7 +85,10 @@ When working in z-shell repositories, optimize for: 3. Check linked tracker items and previous handoff comments. 4. Read the relevant ADRs, patterns, and runbooks. 5. For cross-repo questions, search the organization before assuming the local repo is unique. -6. If no issue exists for non-trivial planned work, create one in the owning repository. +6. If no issue exists for non-trivial planned work, propose one. Create it only + when explicit external-write authority is present. + +Creating or updating issues, comments, pull requests, or tracker records requires explicit external-write authority. Without that authority, report the proposed external write instead. ## While editing @@ -155,7 +160,9 @@ cannot own this mandatory rule. ## When this file is wrong -Do not silently work around drift. Open or update an issue in `z-shell/.github`, explain what is wrong, and link the contradicting repository state. +Do not silently work around drift. Propose an issue in `z-shell/.github` that +explains what is wrong and links the contradicting repository state. Open or +update it only when explicit external-write authority is present. ## See also diff --git a/scripts/test_validate_agent_policy.py b/scripts/test_validate_agent_policy.py index f4e78a41d..ae4c7b510 100644 --- a/scripts/test_validate_agent_policy.py +++ b/scripts/test_validate_agent_policy.py @@ -1703,6 +1703,43 @@ def test_public_repository_requires_manifest_routing_for_all_runtimes(self) -> N for fragment in required_fragments: self.assertIn(fragment, policy) + def test_public_repository_deduplicates_loaded_content_and_gates_external_writes( + self, + ) -> None: + policy = (PUBLIC_ROOT / "AGENTS.md").read_text() + memory = (PUBLIC_ROOT / ".github/AGENT_MEMORY.md").read_text() + + policy_fragments = ( + "Treat byte-exact instruction content already present in the active " + "instruction context as loaded.", + "Manifest ownership entries and repository links do not request a " + "second read.", + "Creating or updating issues, comments, pull requests, or tracker " + "records requires explicit external-write authority.", + "Without that authority, report the proposed external write instead.", + "If no issue exists for non-trivial planned work, propose one.", + ) + for fragment in policy_fragments: + self.assertIn(fragment, policy) + + memory_fragments = ( + "External writes require explicit authorization.", + "Without it, report the proposed issue, comment, or tracker update " + "instead of performing it.", + "If no issue exists for planned or deferred work, propose one.", + ) + for fragment in memory_fragments: + self.assertIn(fragment, memory) + + self.assertNotIn( + "If no issue exists for non-trivial planned work, create one", + policy, + ) + self.assertNotIn( + "If no issue exists for planned or deferred work, create one", + memory, + ) + def test_public_repository_declares_learning_capture_surfaces(self) -> None: manifest = json.loads( (PUBLIC_ROOT / ".github/instruction-surfaces.json").read_text()