refactor(scripts): tighten contributor claim policy

Author: FelixTJDietrich

.github/workflows/ci-security-scan.yml

@@ -191,8 +191,9 @@ jobs:
           if grep -rEnI 'docker/agent-image-pin(\.local)?\.env' \
                 --exclude-dir=node_modules --exclude-dir=target --exclude-dir=.git \
                 . \
-              | grep -vE '^\./(MIGRATION\.md|docs/admin/agent-image-digests\.md|scripts/check-agent-instructions\.ts):' ; then
-            echo "::error::The legacy pin file was removed in v0.10.0; new references must live in MIGRATION.md only."
+              | grep -vE '^\./(MIGRATION\.md|docs/admin/agent-image-digests\.md):' \
+              | grep -vE '^\./scripts/check-agent-instructions\.ts:[0-9]+:[[:space:]]*value: "docker/agent-image-pin(\.local)?\.env",$' ; then
+            echo "::error::Legacy pin-file names are allowed only in migration history, the digest guide, and exact instruction-checker exceptions."
             exit 1
           fi
 

scripts/check-agent-instructions.test.ts

@@ -26,6 +26,7 @@ function only(failures: readonly string[]): string {
 
 /** A symlink to `target`, as an override value. */
 const symlinkTo = (target: string): { readonly target: string } => ({ target });
+const markdownSpans = (markdown: string): readonly string[] => codeSpans(markdown, "markdown");
 
 type Override = string | { readonly target: string } | { readonly kind: "opaque" } | null;
 
@@ -181,27 +182,30 @@ await test("code is not prose: a reference inside a span, a fence or a comment i
 });
 
 await test("the markdown scanner extracts code spans, not fences or comments", () => {
-	assert.deepEqual(codeSpans("Use `scripts/check.ts` and ``a ` b``."), [
+	assert.deepEqual(markdownSpans("Use `scripts/check.ts` and ``a ` b``."), [
 		"scripts/check.ts",
 		"a ` b",
 	]);
-	assert.deepEqual(codeSpans("A `line\nwrap` is one span."), ["line wrap"]);
-	assert.deepEqual(codeSpans("A `CRLF\r\nwrap` is one span."), ["CRLF wrap"]);
-	assert.deepEqual(codeSpans("A `CR\rwrap` is one span."), ["CR wrap"]);
-	assert.deepEqual(codeSpans("` padded ` and `   `"), ["padded", "   "]);
-	assert.deepEqual(codeSpans("<!-- `hidden.md` -->\n```md\n`fenced.md`\n```\n`shown.md`"), [
+	assert.deepEqual(markdownSpans("A `line\nwrap` is one span."), ["line wrap"]);
+	assert.deepEqual(markdownSpans("A `CRLF\r\nwrap` is one span."), ["CRLF wrap"]);
+	assert.deepEqual(markdownSpans("A `CR\rwrap` is one span."), ["CR wrap"]);
+	assert.deepEqual(markdownSpans("` padded ` and `   `"), ["padded", "   "]);
+	assert.deepEqual(markdownSpans("<!-- `hidden.md` -->\n```md\n`fenced.md`\n```\n`shown.md`"), [
 		"shown.md",
 	]);
-	assert.deepEqual(codeSpans("\\`escaped.md\\`\n\n    `indented.md`"), []);
-	assert.deepEqual(codeSpans("`a <!-- literal --> span`"), ["a <!-- literal --> span"]);
-	assert.deepEqual(codeSpans("> ```md\n> `quoted.md`\n> ```\n`shown.md`"), ["shown.md"]);
-	assert.deepEqual(codeSpans("<Tabs>\n<TabItem>\nUse `inside.md`\n</TabItem>\n</Tabs>", true), [
+	assert.deepEqual(markdownSpans("\\`escaped.md\\`\n\n    `indented.md`"), []);
+	assert.deepEqual(markdownSpans("`a <!-- literal --> span`"), ["a <!-- literal --> span"]);
+	assert.deepEqual(markdownSpans("> ```md\n> `quoted.md`\n> ```\n`shown.md`"), ["shown.md"]);
+	assert.deepEqual(codeSpans("<Tabs>\n<TabItem>\nUse `inside.md`\n</TabItem>\n</Tabs>", "mdx"), [
 		"inside.md",
 	]);
-	assert.deepEqual(codeSpans("`not closed``"), []);
-	assert.deepEqual(codeSpans("```md\n`hidden.md`\n``` not a close\n`still-hidden.md`\n```"), []);
-	assert.deepEqual(codeSpans("```md\n<!--\n```\n`shown.md`"), ["shown.md"]);
-	assert.deepEqual(codeSpans("<!--\n```md\n-->\n`shown.md`"), ["shown.md"]);
+	assert.deepEqual(markdownSpans("`not closed``"), []);
+	assert.deepEqual(
+		markdownSpans("```md\n`hidden.md`\n``` not a close\n`still-hidden.md`\n```"),
+		[],
+	);
+	assert.deepEqual(markdownSpans("```md\n<!--\n```\n`shown.md`"), ["shown.md"]);
+	assert.deepEqual(markdownSpans("<!--\n```md\n-->\n`shown.md`"), ["shown.md"]);
 });
 
 await test("contributor docs reject missing repository paths and npm packages", () => {
@@ -229,16 +233,6 @@ await test("an intentional non-checkout path is allowed only in the document tha
 		),
 		[],
 	);
-	assert.deepEqual(
-		analyse(
-			snapshot({
-				"webapp/src/features/a.ts": { kind: "opaque" },
-				"webapp/src/features/b.ts": { kind: "opaque" },
-				"docs/contributor/setup.md": "Use `src/features/`.\n",
-			}),
-		),
-		[],
-	);
 	assert.match(
 		only(
 			analyse(
@@ -252,6 +246,26 @@ await test("an intentional non-checkout path is allowed only in the document tha
 	);
 });
 
+await test("a unique shorthand directory resolves independently of its descendant count", () => {
+	assert.deepEqual(
+		analyse(
+			snapshot({
+				"webapp/src/features/a.ts": { kind: "opaque" },
+				"webapp/src/features/b.ts": { kind: "opaque" },
+				"docs/contributor/setup.md": "Use `src/features/`.\n",
+			}),
+		),
+		[],
+	);
+});
+
+await test("an invalid contributor MDX document is reported with its path", () => {
+	assert.throws(
+		() => analyse(snapshot({ "docs/contributor/broken.mdx": "<Component/ name>" })),
+		/docs\/contributor\/broken\.mdx:/,
+	);
+});
+
 await test("path claims cannot escape through a typo, basename, or unrelated suffix match", () => {
 	for (const claim of ["scrips/missing.ts", "missing.md", "./config.md"]) {
 		const failure = only(

scripts/check-agent-instructions.ts

@@ -14,9 +14,7 @@
  *   uncommanded — a typed-only skill with no opencode command to type.
  *   unmirrored  — a Codex copy of a skill that has drifted from the Claude Code original.
  *   duplicated  — two agent files with one body.
- *
- * Contributor docs are checked separately for inline-code paths and npm packages that resolve to
- * nothing in the checkout.
+ *   stale       — a contributor document names a repository path or npm package that does not resolve.
  *
  * `unread` runs before all of them and reports this gate's own blind spot: an agent file the
  * classifier never opened, which every check below would otherwise read as a file that says nothing.
@@ -178,12 +176,41 @@ const INTENTIONALLY_MISSING_PATHS = [
 		value: "webapp/.env",
 		reason: "a developer-local environment file that must stay untracked",
 	},
+	{
+		document: "docs/contributor/agent/workspace-abi.mdx",
+		value: "inputs/manifest.json",
+		reason: "a path inside the staged agent workspace, not the repository checkout",
+	},
+	{
+		document: "docs/contributor/agent/workspace-abi.mdx",
+		value: "out/result.json",
+		reason: "a path inside the staged agent workspace, not the repository checkout",
+	},
+	{
+		document: "docs/contributor/agent/workspace-abi.mdx",
+		value: "out/watchdog-killed.json",
+		reason: "a path inside the staged agent workspace, not the repository checkout",
+	},
+	{
+		document: "docs/contributor/artifact-source-contract.mdx",
+		value: "inputs/manifest.json",
+		reason: "a path inside the staged agent workspace, not the repository checkout",
+	},
+	{
+		document: "docs/contributor/practice-review-glossary.mdx",
+		value: "inputs/history/delta.json",
+		reason: "a path inside the staged agent workspace, not the repository checkout",
+	},
+	{
+		document: "docs/contributor/practice-review-glossary.mdx",
+		value: "out/feedback.json",
+		reason: "a path inside the staged agent workspace, not the repository checkout",
+	},
 ] satisfies readonly ClaimException[];
 
 const PACKAGE_NAME = /^(?:@[a-z0-9][a-z0-9._-]*\/[a-z0-9][a-z0-9._-]*|[a-z0-9][a-z0-9._-]*)$/;
 const PACKAGE_SHAPED = /-(?:cli|config|core|js|node|package|plugin|react|sdk|test|ts)$/;
 const FILE_SHAPED = /\.(?:java|js|jsonc?|mdx?|mjs|sh|ts|tsx|xml|ya?ml)$/;
-const RUNTIME_ROOTS = new Set(["inputs", "out"]);
 const exists = (repo: Repo, path: string): boolean =>
 	repo.present.has(path) || repo.paths.some((present) => present.startsWith(`${path}/`));
 
@@ -225,9 +252,7 @@ function looksLikePath(value: string, roots: ReadonlySet<string>): boolean {
 		roots.has(first) ||
 		(first.startsWith(".") && value.includes("/")) ||
 		(value.includes("/") && basename(value).startsWith(".")) ||
-		(FILE_SHAPED.test(value) &&
-			!RUNTIME_ROOTS.has(first) &&
-			(value.includes("/") || /\.mdx?$/.test(value)))
+		(FILE_SHAPED.test(value) && (value.includes("/") || /\.mdx?$/.test(value)))
 	);
 }
 
@@ -256,7 +281,15 @@ function staleContributorClaims(repo: Repo): readonly string[] {
 	const failures: string[] = [];
 	for (const file of repo.present.values()) {
 		if (file.kind !== "text" || !isContributorDoc(file.path)) continue;
-		for (const value of new Set(codeSpans(file.content, file.path.endsWith(".mdx")))) {
+		let spans: readonly string[];
+		try {
+			spans = codeSpans(file.content, file.path.endsWith(".mdx") ? "mdx" : "markdown");
+		} catch (error) {
+			throw new Error(`${file.path}: ${error instanceof Error ? error.message : String(error)}`, {
+				cause: error,
+			});
+		}
+		for (const value of new Set(spans)) {
 			const candidate = value.replace(/[.,:;]$/, "").replace(/#.*$/, "");
 			if (candidate.includes("…") || candidate.includes("...") || /[*<>{}$\s]/.test(candidate))
 				continue;
@@ -378,7 +411,7 @@ interface MarkdownNode {
 	readonly children?: readonly MarkdownNode[];
 }
 
-export function codeSpans(markdown: string, mdx = false): readonly string[] {
+export function codeSpans(markdown: string, syntax: "markdown" | "mdx"): readonly string[] {
 	const spans: string[] = [];
 	const visit = (node: MarkdownNode): void => {
 		if (node.type === "inlineCode" && typeof node.value === "string") {
@@ -389,7 +422,9 @@ export function codeSpans(markdown: string, mdx = false): readonly string[] {
 	visit(
 		fromMarkdown(
 			markdown,
-			mdx ? { extensions: [mdxjs()], mdastExtensions: [mdxFromMarkdown()] } : undefined,
+			syntax === "mdx"
+				? { extensions: [mdxjs()], mdastExtensions: [mdxFromMarkdown()] }
+				: undefined,
 		),
 	);
 	return spans;
@@ -766,6 +801,6 @@ if (process.argv[1] === import.meta.filename) {
 	console.log(
 		`check-agent-instructions: ${repo.guides.length} AGENTS.md reach Claude Code and opencode; ` +
 			`${skills.length} skills, ${mirrored} of them mirrored for Codex, ` +
-			`${repo.commands.length} opencode commands; contributor-doc paths and packages resolve.`,
+			`${repo.commands.length} opencode commands; contributor-doc references checked.`,
 	);
 }