From a121a1d03f1d4e77e5c209fea22725f45c4d88a9 Mon Sep 17 00:00:00 2001 From: Amanjyot-P Date: Thu, 27 Aug 2026 10:35:51 +0530 Subject: [PATCH 1/2] fix(validate-doc-claims): name repo-scoped search base in path-not-found flag The 'not found in working tree' flag for a cited path implied a global search when the check only looks in one repo. An agent reading the flag could not distinguish 'this citation is wrong' from 'this citation points somewhere this check did not look' (e.g. a second docs store in another repo on the same machine). Name the search base (repo root or upstream ref) in the flag text and state that the check is repo-scoped, so the agent knows to check other stores before treating the citation as wrong. Ref: EveryInc/compound-engineering-plugin#1545 --- .../scripts/validate-doc-claims.py | 11 ++++++----- skills/ce-compound/scripts/validate-doc-claims.py | 11 ++++++----- tests/doc-claims-validator.test.ts | 8 ++++++-- 3 files changed, 18 insertions(+), 12 deletions(-) diff --git a/skills/ce-compound-refresh/scripts/validate-doc-claims.py b/skills/ce-compound-refresh/scripts/validate-doc-claims.py index 2f624bb70..b31e01a66 100644 --- a/skills/ce-compound-refresh/scripts/validate-doc-claims.py +++ b/skills/ce-compound-refresh/scripts/validate-doc-claims.py @@ -272,12 +272,13 @@ def head_has_path(path: str) -> bool: f"{upstream}: stale checkout? Annotate or verify against upstream." ) else: - where = ( - f"working tree or {upstream}" if upstream else "working tree" - ) flags.append( - f"FLAG path `{token}`{loc} — not found in {where}. Fix the " - "citation, or annotate it as historical (e.g. removed by this fix)." + f"FLAG path `{token}`{loc} — not found under {base}" + + (f" or {upstream}" if upstream else "") + + ". This check only looks in this repository; verify other " + "repos or stores before treating the citation as wrong. Fix " + "the citation, or annotate it as historical (e.g. removed " + "by this fix)." ) # --- 2. Cited commit SHAs ---------------------------------------------- diff --git a/skills/ce-compound/scripts/validate-doc-claims.py b/skills/ce-compound/scripts/validate-doc-claims.py index 2f624bb70..b31e01a66 100644 --- a/skills/ce-compound/scripts/validate-doc-claims.py +++ b/skills/ce-compound/scripts/validate-doc-claims.py @@ -272,12 +272,13 @@ def head_has_path(path: str) -> bool: f"{upstream}: stale checkout? Annotate or verify against upstream." ) else: - where = ( - f"working tree or {upstream}" if upstream else "working tree" - ) flags.append( - f"FLAG path `{token}`{loc} — not found in {where}. Fix the " - "citation, or annotate it as historical (e.g. removed by this fix)." + f"FLAG path `{token}`{loc} — not found under {base}" + + (f" or {upstream}" if upstream else "") + + ". This check only looks in this repository; verify other " + "repos or stores before treating the citation as wrong. Fix " + "the citation, or annotate it as historical (e.g. removed " + "by this fix)." ) # --- 2. Cited commit SHAs ---------------------------------------------- diff --git a/tests/doc-claims-validator.test.ts b/tests/doc-claims-validator.test.ts index c50a092df..6637dadcb 100644 --- a/tests/doc-claims-validator.test.ts +++ b/tests/doc-claims-validator.test.ts @@ -140,14 +140,18 @@ describe("validate-doc-claims script", () => { expect(result.stdout).not.toContain("FLAG") }) - test("flags a cited path that exists nowhere", () => { + test("flags a cited path that exists nowhere, naming the search base as repo-scoped", () => { const docPath = writeRepoDoc( "The handler is `src/does-not-exist.ts` in the tree.\n", ) const result = runValidator(skillDir, docPath) expect(result.code).toBe(1) expect(result.stdout).toContain("FLAG path `src/does-not-exist.ts`") - expect(result.stdout).toContain("not found") + expect(result.stdout).toContain("not found under ") + expect(result.stdout).toContain(path.basename(repo)) + expect(result.stdout).toContain( + "This check only looks in this repository", + ) }) test("classifies a path that only exists upstream as stale-checkout", () => { From 004037ced1516efb0f9e5c36963c335d8e62eedf Mon Sep 17 00:00:00 2001 From: Trevin Chow Date: Tue, 1 Sep 2026 10:28:29 -0700 Subject: [PATCH 2/2] fix(ce-compound): route the path flag's adjudication on what the check saw MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The flag text now says the search is repo-scoped, but the Step 1 table is what the adjudicating agent actually reads to decide what to do, and its row still named one conclusion — "typo, or drafted from memory" — with "fix the citation or remove the claim". That is the global reading this PR exists to stop asserting, left sitting in the deciding position. The row now states what the observation supports and routes the agent to check the other stores and the citing sentence before treating the citation as wrong. Issue #1545 measured this: across 767 backticked .md citations, 17 did not resolve and none was a mistake — six were correct paths on another machine, three pointed outside the search roots, and eight said in the same sentence that the target was gone or external. The manual-fallback sentence below the table carries the same global framing and is deliberately untouched here: it was rewritten on main in #1608, so editing it on this branch would hand this PR a conflict. Claude-Session: https://claude.ai/code/session_01HSahUJjXzZpJt5ztL7CUyt --- skills/ce-compound/references/grounding-validation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/skills/ce-compound/references/grounding-validation.md b/skills/ce-compound/references/grounding-validation.md index 62c0d70cc..2342e66d0 100644 --- a/skills/ce-compound/references/grounding-validation.md +++ b/skills/ce-compound/references/grounding-validation.md @@ -17,7 +17,7 @@ The script reports flags; you decide each one. Three resolutions — **fix**, ** | Flag | Likely meaning | Resolution | |------|----------------|------------| -| path not found anywhere | Typo, or drafted from memory | Fix the citation or remove the claim | +| path not found under the search base | Typo, or a real path this repo-scoped check cannot see — another store, or a target the citing sentence itself says is gone | Read that sentence and check stores outside this repository before treating the citation as wrong; then fix it, or annotate it as historical | | path missing here, exists at upstream | Stale checkout | Verify the claim against upstream; annotate if the doc implies the file is present locally | | path deliberately gone (doc says removed/renamed) | Historical citation | Confirm the surrounding prose marks it as historical ("removed by this fix", "pre-fix state"); add that marker if absent | | SHA does not resolve | Fabricated or from another repo | Replace with the PR number, or drop |