Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 7 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
34 changes: 33 additions & 1 deletion scripts/check-policy.py
Original file line number Diff line number Diff line change
Expand Up @@ -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"(?<![\w.-])[.]agent[/\\][^\s`\"'<>]+")
# 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())


Expand Down Expand Up @@ -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")
Expand Down
38 changes: 37 additions & 1 deletion tests/test_policy.py
Original file line number Diff line number Diff line change
Expand Up @@ -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 <noreply@anthropic.com>"
GENERATED = "Generated" + " with AI assistant"

Expand Down Expand Up @@ -115,6 +116,27 @@ def test_private_paths_and_task_references(self):
for text in ("/Users/<name>/", "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")
Expand Down Expand Up @@ -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")
Expand Down