From 4359ca27a4637460ba8d3f6461e42701f76f647a Mon Sep 17 00:00:00 2001 From: showxu <10173746+showxu@users.noreply.github.com> Date: Mon, 26 Oct 2026 19:17:38 +0800 Subject: [PATCH 1/3] fix: treat agent instruction files as repository guidance --- README.md | 5 +++++ scripts/check-policy.py | 21 ++++++++++++++++++++- tests/test_policy.py | 31 +++++++++++++++++++++++++++++++ 3 files changed, 56 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index a63ce53..af08c99 100644 --- a/README.md +++ b/README.md @@ -170,6 +170,11 @@ 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; references to the whole +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..46c3b70 100644 --- a/scripts/check-policy.py +++ b/scripts/check-policy.py @@ -19,6 +19,11 @@ 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 are tracked repository +# guidance, and a pattern for the whole directory names no task file; everything +# else under .agent/ is local task state. +AGENT_GUIDANCE = {".agent/agents.json", ".agent/agents.resolved", ".agent/*", ".agent/**"} +AGENT_INSTRUCTIONS = ".agent/instructions/" TOOL_IDENTITIES = json.loads((Path(__file__).resolve().parents[1] / "data/attribution-tools.json").read_text()) @@ -66,12 +71,26 @@ def parse_path_exceptions(value): return patterns +def task_state(reference): + reference = reference.replace("\\", "/") + if ".." in reference.split("/"): + return True + reference = reference.rstrip(".,;:)]") + return reference not in AGENT_GUIDANCE and not reference.startswith(AGENT_INSTRUCTIONS) + + +def task_reference(text, *, path=False): + if path and ".agent" in Path(text).parts: + return task_state(text) + return any(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..480f285 100644 --- a/tests/test_policy.py +++ b/tests/test_policy.py @@ -115,6 +115,24 @@ 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/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 (".agent/.agents.lock", ".agent/cache/source", ".agent/agents.json.bak", + ".agent/instructions/../plans/task.md", "/.agent/* and " + TASK): + with self.subTest(text=text): + self.assertTrue(policy.content_findings("file", text)) + for path in ("plugin/.agent/agents.json", ".agent/transaction.json", ".agent/instructions.md"): + 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 +211,19 @@ 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): + self.write(".gitignore", "/.agent/*\n!/.agent/instructions/\n!/.agent/agents.json\n!/.agent/agents.resolved\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") From 36a8e11e46fc8831397cebab54cd4657dcac7898 Mon Sep 17 00:00:00 2001 From: showxu <10173746+showxu@users.noreply.github.com> Date: Mon, 26 Oct 2026 20:13:09 +0800 Subject: [PATCH 2/3] fix: keep nested and prefixed agent paths as task state --- README.md | 6 ++++-- scripts/check-policy.py | 30 +++++++++++++++++++++--------- tests/test_policy.py | 11 +++++++---- 3 files changed, 32 insertions(+), 15 deletions(-) diff --git a/README.md b/README.md index af08c99..2f2ef4c 100644 --- a/README.md +++ b/README.md @@ -172,8 +172,10 @@ and [Signing](https://github.com/computer-mcp/.github/blob/master/MAINTENANCE.md 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; references to the whole -directory, such as an ignore rule for `.agent/*`, name no task file. +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. diff --git a/scripts/check-policy.py b/scripts/check-policy.py index 46c3b70..ef5163d 100644 --- a/scripts/check-policy.py +++ b/scripts/check-policy.py @@ -19,11 +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 are tracked repository -# guidance, and a pattern for the whole directory names no task file; everything -# else under .agent/ is local task state. -AGENT_GUIDANCE = {".agent/agents.json", ".agent/agents.resolved", ".agent/*", ".agent/**"} +# 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()) @@ -71,18 +73,28 @@ def parse_path_exceptions(value): return patterns -def task_state(reference): +def task_state(reference, *, path=False): reference = reference.replace("\\", "/") if ".." in reference.split("/"): return True - reference = reference.rstrip(".,;:)]") - return reference not in AGENT_GUIDANCE and not reference.startswith(AGENT_INSTRUCTIONS) + 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) - return any(task_state(match.group()) for match in TASK_REFERENCE.finditer(text)) + return task_state(text, path=True) + # A reference inside a longer path, such as plugin/.agent/ or ../.agent/, 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): diff --git a/tests/test_policy.py b/tests/test_policy.py index 480f285..aeb2cf3 100644 --- a/tests/test_policy.py +++ b/tests/test_policy.py @@ -118,18 +118,21 @@ def test_private_paths_and_task_references(self): 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/instructions/", '"path" : ".agent/instructions/guide.md",', - "Edit .agent/agents.json."): + "/.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 (".agent/.agents.lock", ".agent/cache/source", ".agent/agents.json.bak", - ".agent/instructions/../plans/task.md", "/.agent/* and " + TASK): + ".agent/instructions/../plans/task.md", "/.agent/* and " + TASK, + ".agent/instructions/shared/.agent/cache/state", "plugin/.agent/agents.json", + "../.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 ("plugin/.agent/agents.json", ".agent/transaction.json", ".agent/instructions.md"): + for path in ("plugin/.agent/agents.json", ".agent/transaction.json", ".agent/instructions.md", + ".agent/instructions/shared/.agent/cache/state", ".agent/*"): with self.subTest(path=path): self.assertTrue(policy.content_findings(path, path, path=True)) From 1f2ce263448bfe4eaba5bd41444f39c897eb750d Mon Sep 17 00:00:00 2001 From: showxu <10173746+showxu@users.noreply.github.com> Date: Mon, 26 Oct 2026 20:37:13 +0800 Subject: [PATCH 3/3] test: build task-state examples so the policy can scan its own diff --- scripts/check-policy.py | 5 +++-- tests/test_policy.py | 18 ++++++++++-------- 2 files changed, 13 insertions(+), 10 deletions(-) diff --git a/scripts/check-policy.py b/scripts/check-policy.py index ef5163d..017d0ed 100644 --- a/scripts/check-policy.py +++ b/scripts/check-policy.py @@ -91,8 +91,9 @@ def task_state(reference, *, path=False): 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 plugin/.agent/ or ../.agent/, is not - # the repository's own guidance; a lone leading slash anchors an ignore rule. + # 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)) diff --git a/tests/test_policy.py b/tests/test_policy.py index aeb2cf3..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" @@ -125,14 +126,14 @@ def test_agent_instruction_files_are_repository_guidance(self): 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 (".agent/.agents.lock", ".agent/cache/source", ".agent/agents.json.bak", - ".agent/instructions/../plans/task.md", "/.agent/* and " + TASK, - ".agent/instructions/shared/.agent/cache/state", "plugin/.agent/agents.json", - "../.agent/instructions/guide.md", "https://example.org/r/blob/master/" + TASK): + 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 ("plugin/.agent/agents.json", ".agent/transaction.json", ".agent/instructions.md", - ".agent/instructions/shared/.agent/cache/state", ".agent/*"): + 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)) @@ -215,7 +216,8 @@ def test_pr_checks_title_messages_content_and_paths_without_signature_api(self): self.api.get.assert_not_called() def test_committed_agent_instruction_files_pass_while_task_state_fails(self): - self.write(".gitignore", "/.agent/*\n!/.agent/instructions/\n!/.agent/agents.json\n!/.agent/agents.resolved\n") + 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')