diff --git a/README.md b/README.md index a63ce53..2f2ef4c 100644 --- a/README.md +++ b/README.md @@ -170,6 +170,13 @@ and [Signing](https://github.com/computer-mcp/.github/blob/master/MAINTENANCE.md | No maintainer-machine paths or local task-state references | Added/modified paths, added text and messages are checked for concrete home-directory paths and local task-file references | | PR titles, added content and added/modified paths; verified default-branch commits | PR diffs use the merge base; pushes check their supplied range; removed lines are outside the added-content check | +Local task state is any path under `.agent/` except the agents CLI's tracked +instruction units in `.agent/instructions/`, its `.agent/agents.json` +declaration and its `.agent/agents.resolved` lock at the repository root. An +`.agent/` directory nested under the units or elsewhere remains task state; +references to the whole root directory, such as an ignore rule for `.agent/*`, +name no task file. + `merge_group` checks queued content and paths. Temporary queue commits are not accepted default-branch commits; final push checks verify the accepted commits. The checker reads Git blobs and forces text diffs for text files so consumer diff --git a/scripts/check-policy.py b/scripts/check-policy.py index a0659f2..017d0ed 100644 --- a/scripts/check-policy.py +++ b/scripts/check-policy.py @@ -19,6 +19,13 @@ PRIVATE_PATH = re.compile(r"/(?:Users|home)/[\w. -]+(?:/|(?=[\s`\"')]|$))|" r"[A-Za-z]:[\\/]Users[\\/][\w. -]+(?:[\\/]|(?=[\s`\"')]|$))") TASK_REFERENCE = re.compile(r"(?]+") +# The agents CLI's instruction units, declaration and lock at the repository root +# are tracked repository guidance; everything else under .agent/ is local task state. +AGENT_FILES = {".agent/agents.json", ".agent/agents.resolved"} +AGENT_INSTRUCTIONS = ".agent/instructions/" +# Ignore rules for the whole directory name no task file. +AGENT_PATTERNS = {".agent/*", ".agent/**"} +NESTED_REFERENCE = re.compile(r"[\w.:/\\-][/\\]$") TOOL_IDENTITIES = json.loads((Path(__file__).resolve().parents[1] / "data/attribution-tools.json").read_text()) @@ -66,12 +73,37 @@ def parse_path_exceptions(value): return patterns +def task_state(reference, *, path=False): + reference = reference.replace("\\", "/") + if ".." in reference.split("/"): + return True + if not path: + reference = reference.rstrip(".,;:)]") + if reference in AGENT_PATTERNS: + return False + if reference in AGENT_FILES: + return False + if reference.startswith(AGENT_INSTRUCTIONS): + return ".agent" in reference[len(AGENT_INSTRUCTIONS):].split("/") + return True + + +def task_reference(text, *, path=False): + if path and ".agent" in Path(text).parts: + return task_state(text, path=True) + # A reference inside a longer path, such as another directory's agent folder or a + # parent-directory path, is not the repository's own guidance; a lone leading slash + # anchors an ignore rule. + return any(NESTED_REFERENCE.search(text[:match.start()]) or task_state(match.group()) + for match in TASK_REFERENCE.finditer(text)) + + def content_findings(label, text, *, path=False, exempt_paths=False): findings = [] if not exempt_paths: if PRIVATE_PATH.search(text): findings.append(f"{label}: private machine path") - if TASK_REFERENCE.search(text) or (path and ".agent" in Path(text).parts): + if task_reference(text, path=path): findings.append(f"{label}: reference to local task state") if attribution(text): findings.append(f"{label}: tool or agent attribution") diff --git a/tests/test_policy.py b/tests/test_policy.py index 34c83c0..4d066e7 100644 --- a/tests/test_policy.py +++ b/tests/test_policy.py @@ -28,7 +28,8 @@ def load(name, file): TEXT = (ROOT / "fixtures/declaration/MAINTENANCE.md").read_text() RULES = declaration.source_policy(TEXT) PRIVATE = "/".join(("", "Users", "fixture-owner", "project")) -TASK = ".agent" + "/plans/task.md" +AGENT = ".agent" +TASK = AGENT + "/plans/task.md" TOOL_TRAILER = "Co-Authored" + "-By: Claude " GENERATED = "Generated" + " with AI assistant" @@ -115,6 +116,27 @@ def test_private_paths_and_task_references(self): for text in ("/Users//", "local task state", "docs/Claude.md", "PLAN.md", "file.plan.md"): self.assertEqual(policy.content_findings("file", text, path=True), []) + def test_agent_instruction_files_are_repository_guidance(self): + for text in (".agent/agents.json", ".agent/agents.resolved", ".agent/instructions/guide.md", + ".agent/instructions/shared/plugin-rules.md", "`.agent/instructions/shared/`", + "/.agent/*", "`/.agent/*`", "!/.agent/instructions/", + '"path" : ".agent/instructions/guide.md",', "Edit .agent/agents.json."): + with self.subTest(text=text): + self.assertEqual(policy.content_findings("file", text), []) + for path in (".agent/agents.json", ".agent/agents.resolved", ".agent/instructions/guide.md"): + with self.subTest(path=path): + self.assertEqual(policy.content_findings(path, path, path=True), []) + for text in (f"{AGENT}/.agents.lock", f"{AGENT}/cache/source", f"{AGENT}/agents.json.bak", + f"{AGENT}/instructions/../plans/task.md", "/.agent/* and " + TASK, + f"{AGENT}/instructions/shared/{AGENT}/cache/state", f"plugin/{AGENT}/agents.json", + f"../{AGENT}/instructions/guide.md", "https://example.org/r/blob/master/" + TASK): + with self.subTest(text=text): + self.assertTrue(policy.content_findings("file", text)) + for path in (f"plugin/{AGENT}/agents.json", f"{AGENT}/transaction.json", f"{AGENT}/instructions.md", + f"{AGENT}/instructions/shared/{AGENT}/cache/state", ".agent/*"): + with self.subTest(path=path): + self.assertTrue(policy.content_findings(path, path, path=True)) + def test_added_lines_exclude_context_and_deletions_and_include_plus_prefix(self): patch_text = "@@ -1,2 +1,2 @@\n-" + PRIVATE + "\n context\n+++ " + PRIVATE + "\n" findings = policy.added_findings(patch_text, "file") @@ -193,6 +215,20 @@ def test_pr_checks_title_messages_content_and_paths_without_signature_api(self): self.assertTrue(any("local task state" in f for f in findings)) self.api.get.assert_not_called() + def test_committed_agent_instruction_files_pass_while_task_state_fails(self): + rules = ("/.agent/*", "!/.agent/instructions/", "!/.agent/agents.json", "!/.agent/agents.resolved") + self.write(".gitignore", "\n".join(rules) + "\n") + self.write(".agent/instructions/guide.md", "# Guide\n") + self.write(".agent/agents.json", '{"instructions": {"agents": ["claude-code", "codex"], "sections": ["guide"]}}\n') + self.write(".agent/agents.resolved", '{"path" : ".agent/instructions/guide.md"}\n') + head = self.commit("docs: generate AGENTS.md from instruction units") + self.assertEqual(policy.check(self.root, self.event(head), "pull_request", RULES, self.api), []) + self.write(TASK, "private task\n") + self.git("add", "--force", TASK) + head = self.commit("docs: add a plan") + findings = policy.check(self.root, self.event(head), "pull_request", RULES, self.api) + self.assertEqual(findings, [TASK + ": reference to local task state"]) + def test_file_exceptions_cover_fixtures_and_third_party_text_but_not_leaks(self): self.write("fixtures/path.txt", PRIVATE + "\n" + TASK + "\n") self.write("vendor/upstream/README.md", PRIVATE + "\n" + TASK + "\n")