What happens
validate-doc-claims.py resolves every cited path against one base directory. When a learning doc cites a doc that lives in a second store, in another repo on the same machine, the checker reports it as missing. The flag says the file was not found, with no mention that the check only looked in one repo.
An agent reading that flag cannot tell "this citation is wrong" from "this citation points somewhere I did not look".
Why it matters
On my machine this produced a published false claim. A ce-compound run recorded a real citation as a fabricated one, inside a doc whose subject was not accepting unverified claims. It stood for five days. The cited file existed the whole time, in a second solutions store under a different repo root, and the repo that owns it cites the same file in its own instruction file.
In that run the checker's negative outweighed an independent subagent's positive. A scoped negative that reads as a global one wins that disagreement, and the citation then gets rewritten or removed.
I then swept my whole store to see how often an unresolvable citation is actually wrong. Across 421 docs and 767 backticked .md citations, 17 did not resolve, and on reading every one, none was a mistake. Six were correct paths on my other machine. Three pointed outside the search roots. Eight were deliberate: a supersession note naming the doc it replaces, a record of two memory files the doc proves are dead, a scratch file the sentence calls a scratch file. Every one of those eight says so in the same sentence as the citation.
That is the part the flag wording has to carry. A citation is often unresolvable on purpose, :35 already puts the call with the agent ("decides per flag: fix, annotate as historical, or confirm intentional"), and there is no persistent marker, so the flag text is the entire interface for that decision, on every run.
Mechanism
Two checks, both single-root by construction. Line numbers from main at the time of writing. The file is byte-identical under skills/ce-compound/scripts/ and skills/ce-compound-refresh/scripts/.
Backticked path tokens resolve against one base, validate-doc-claims.py:234:
base = repo_root if in_git else os.getcwd()
and the flag it produces, at :279:
f"FLAG path `{token}`{loc} — not found in {where}. Fix the "
"citation, or annotate it as historical (e.g. removed by this fix)."Markdown links resolve against the doc's own directory, :345:
if not os.path.exists(os.path.normpath(os.path.join(doc_dir, bare))):
Both are right for a single-store repo. Neither can say "exists, in a store this run did not look at".
Suggested fix
The smallest useful change is to name the search base in the flag, and to say the check is repo-scoped:
FLAG path `x.md` (line N) — not found under /path/to/repo. This check only
looks in this repository; check other stores before treating the citation as wrong.
That costs nothing and drops the false certainty. The decision stays with the agent, which is where it belongs.
Resolving across several stores is a much bigger change and I am not asking for it here. docs_root is one root per repo by design, and #1505 already covers alternate backends.
Environment
- compound-engineering 3.23.4, Claude Code on macOS 26.6.2
- Stores involved:
~/docs/solutions (repo root is ~) and ~/<second-repo>/docs/solutions, a separate git repo checked out under the first one
What happens
validate-doc-claims.pyresolves every cited path against one base directory. When a learning doc cites a doc that lives in a second store, in another repo on the same machine, the checker reports it as missing. The flag says the file was not found, with no mention that the check only looked in one repo.An agent reading that flag cannot tell "this citation is wrong" from "this citation points somewhere I did not look".
Why it matters
On my machine this produced a published false claim. A
ce-compoundrun recorded a real citation as a fabricated one, inside a doc whose subject was not accepting unverified claims. It stood for five days. The cited file existed the whole time, in a second solutions store under a different repo root, and the repo that owns it cites the same file in its own instruction file.In that run the checker's negative outweighed an independent subagent's positive. A scoped negative that reads as a global one wins that disagreement, and the citation then gets rewritten or removed.
I then swept my whole store to see how often an unresolvable citation is actually wrong. Across 421 docs and 767 backticked
.mdcitations, 17 did not resolve, and on reading every one, none was a mistake. Six were correct paths on my other machine. Three pointed outside the search roots. Eight were deliberate: a supersession note naming the doc it replaces, a record of two memory files the doc proves are dead, a scratch file the sentence calls a scratch file. Every one of those eight says so in the same sentence as the citation.That is the part the flag wording has to carry. A citation is often unresolvable on purpose,
:35already puts the call with the agent ("decides per flag: fix, annotate as historical, or confirm intentional"), and there is no persistent marker, so the flag text is the entire interface for that decision, on every run.Mechanism
Two checks, both single-root by construction. Line numbers from
mainat the time of writing. The file is byte-identical underskills/ce-compound/scripts/andskills/ce-compound-refresh/scripts/.Backticked path tokens resolve against one base,
validate-doc-claims.py:234:and the flag it produces, at
:279:Markdown links resolve against the doc's own directory,
:345:Both are right for a single-store repo. Neither can say "exists, in a store this run did not look at".
Suggested fix
The smallest useful change is to name the search base in the flag, and to say the check is repo-scoped:
That costs nothing and drops the false certainty. The decision stays with the agent, which is where it belongs.
Resolving across several stores is a much bigger change and I am not asking for it here.
docs_rootis one root per repo by design, and #1505 already covers alternate backends.Environment
~/docs/solutions(repo root is~) and~/<second-repo>/docs/solutions, a separate git repo checked out under the first one