docs(corpus): the code-references standard (#1308) - #1480
Conversation
Plan for issue #1308, capped at 5 steps by the #605 standards-batch brief rather than by a Size line the issue does not carry. Records what was verified before drafting: HEAD, the corpus tree's contents, the schema's required fields, and the validator's measured verdicts for the citation shapes the standard will rule on. Two findings from a self-run review-plan pass are already applied: - Medium: STEP 4 ran its three verification suites before the negative control's mutate-and-revert, so an imperfect revert satisfied the literal command sequence while shipping a file nothing re-checked. The negative control now runs first, and the suites run against the reverted file. - Low: the scope-boundary section claimed four of CONTRACT.md's six shapes name code. CONTRACT.md's own table marks three of six openable. Corrected, and the fourth code-naming form -- the commit reference -- is now named as a revision pin rather than counted as openable. That review was not independent: it reviewed a plan written in the same session by the same agent. Signed-off-by: Serina Mcfall <serina.mcfall@gmail.com>
Adds launchpad/docs/corpus/standards/code-references.md, node id corpus-standard-code-references, as the canonical policy for how a corpus node cites code. Every verdict in the document was measured by running validate._classify_citation at the recorded revision, not read off prose. The measurements the standard turns on: - A bare repository path is opened; it must resolve to a real file inside the repository, from the repository root. A directory, a missing path, an absolute path and an escaping path all fail. - In path:line and path:start-end the path is checked and the line is not. Justfile:999999 returns ok against a 1005-line file. That is #1459, and it is why a bare path is preferred. - A GitHub file link is syntax only. Pinned to a full lowercase 40-character SHA with a non-empty trailing path, a link naming a file that has never existed passes. The validator never contacts GitHub. - blob/main, an abbreviated SHA, an uppercase SHA, a pinned link naming no file, and the tree, blame, commits and edit verbs are all rejected. - Commit references, graph edges, tool results and non-GitHub URLs land on the non-fatal UNVERIFIED channel. Anything matching no known form is a hard error. Definition of done, clause by clause: 1. Exactly one hand-authored corpus document. Only code-references.md is added beneath the corpus root; the plan lives outside it. No generated artifact is added -- find_ownership_violations fails closed on every non-md file there until #1316 lands. 2. Schema-valid front matter with a stable id, type, status, origin, audiences, provenance and relationships appropriate to the node. type is governance -- the only enum member describing a policy node. audiences adds developer to #636's agent and reviewer, sourced to #605's outcome line and classified TEAM_KNOWLEDGE for that reason. Provenance is a commit citation in the evidence ledger, the schema's only legal home for it. No relationships: section 8 gives the reason, which is merge order rather than an empty corpus. 3. One independently maintainable node. Section 1 draws the boundary against the evidence standard, #1314. A second concept found while drafting -- a three-way divergence between CONTRACT.md, AGENTS.md and validate.py over whether a URL is a citation form -- is reported and filed rather than folded in. 4. Every substantive claim traceable, and the three classes not conflated. The ledger carries 20 entries: 17 FACT, each citing a file that was opened; 1 INFERENCE with a confidence, for the merge-order reasoning behind declaring no relationships; 2 TEAM_KNOWLEDGE, each naming the issue that is the source, because an issue is not a file that discusses the point. 5. Links implementation, verification, specification and decision without duplicating them. Section 7, plus an explicit note that enum lists and the schema's field rules are deliberately not copied, because the validator never reads body prose and a stale copy would stay green. 6. Checked against the recorded revision and against git, PRs and issues. Revision 60d4947, confirmed present with git cat-file -e. #1459, #605, #1314 and #1316 were read. 7. Corpus validation passes locally: PASS, 0 errors, 2 unverified items, both of them the two nodes' revision citations. 8. States scope and authority. Section 1, which also states that the validator outranks this document where they disagree. 9. Separates MUST from SHOULD. Sections 3 and 4, as separate lists. 10. Defines enforcement and the exception and escalation process. Sections 5 and 6. Section 5 also names the four things a green run does not establish, and which rules only a reviewer can hold. 11. Links decisions rather than duplicating them. Section 7. Verified: the negative control was run first, injecting a blob/main link, a line:column suffix and an owner/repo#N reference into the ledger. The validator exited 1 naming this node on all three. The revert was confirmed byte-identical with diff, and the three suites then ran against that file: corpus validation exit 0; 79 corpus validator tests OK; 27 schema tests OK. Signed-off-by: Serina Mcfall <serina.mcfall@gmail.com>
Blocker from a review-final pass, confirmed at Blocker by review-adjudicate
after both measured it.
MUST 2 required "a bare repository-relative path". "Bare path" is not loose
prose in this document -- section 2's first table row defines it as the
no-position form, evidence entry 5 treats path:line as a distinct shape, and
evidence entry 14 records as a FACT that CONTRACT.md section 3 enumerates
file range, file line and bare path as three separate shapes. So MUST 2 read
as forbidding the two positional shapes that MUST 6 expressly permits, that
SHOULD 1 merely disprefers, and that section 2's own table records as ok.
It also falsified section 1's claim that "each MUST corresponds to a verdict
that command returns today". Measured -- no verdict rejects a position:
Justfile:1 -> ok
Justfile:1-99999999 -> ok
MUST 2 now requires a repository-relative path and says explicitly that the
position is MUST 6's and SHOULD 1's business, not its own. The rule it was
always trying to state -- root-relative, not document-relative -- is
unchanged.
Fixed in the same edit, because it is the same bullet and leaving a known
false sentence in place while correcting its neighbour would be perverse:
MUST 2's illustration said the citation validate.py "fails from anywhere
except the root", implying the verdict depends on the working directory.
It does not -- repo_root() resolves from the validator's own module path.
Measured from /tmp:
root = /home/serina/Launchpad/buzz/__worktrees/task-1308-corpus-standard-code-references
'validate.py' -> CitationVerdict(status='error', detail='does not resolve to a real file in the repository')
'Justfile' -> CitationVerdict(status='ok', detail='')
Evidence entry 4 is widened to carry the cwd-independence claim, with the same
citation, since repo_root() is what establishes both halves of it.
Correcting the previous commit's message while here: it said the ledger's
"17 FACT, each citing a file that was opened". Entry 1 is a FACT whose sole
citation is a commit, which MUST 9 and section 6 expressly bless as the one
permitted exception -- the same message conceded it two paragraphs later by
reporting two unverified revision citations. The count is right; that clause
was not.
Verification after the fix:
python3 launchpad/project-intelligence/corpus/validate.py
PASS corpus validation found no errors; 2 item(s) reported unverified
exit=0
python3 -m unittest discover -s launchpad/project-intelligence/corpus/tests -p "test_*.py"
Ran 79 tests -- OK
python3 -m unittest discover -s launchpad/docs/corpus/schema/tests -p "test_*.py"
Ran 27 tests -- OK
Nine further findings were confirmed at High, Medium and Low and are filed
rather than fixed here, per this task's standing policy that only Blockers are
fixed in place: #1473, #1474, #1475, #1476, #1478, #1479.
Signed-off-by: Serina Mcfall <serina.mcfall@gmail.com>
Held in draft deliberately — the cross-model gate has not runDo not mark this ready for review yet. This is not an oversight. The review pipeline for corpus work under #605 requires a cross-vendor final pass. That No alternative external provider is installed ( Same-model reviews did run and their findings were addressed — see this PR's own Decision (Serina, 2026-08-26): hold every corpus PR in draft until credits are When credits return, the sequence is: run the cross-model final on this branch's current |
Found while measuring #1472's prediction against the branches. This node reproduced AGENTS.md's "What the recorded revision means" paragraph, stating as settled that the recorded revision tracks verification rather than editing. That paragraph was deleted from AGENTS.md in a1e8bbc, after three consecutive cross-model review passes refused it as a corpus-wide policy no authorized source establishes. #1321 owns the question. This node was cut before that commit and carried the claim forward with no ledger entry behind it -- unsourced normative prose in a standards document, which is the defect class #1472 predicted, and the only place across three stale-base siblings where it actually materialised. Now states only what #636's definition of done supports and defers the rest to #1321, matching what AGENTS.md does at its current head. Neither validate.py nor CI can see this class of defect: a claim whose source is silent on the subject exits 0. It was found by diffing what the base document removed against what the siblings still said. Refs #1308 #1472 Signed-off-by: Serina Mcfall <serina.mcfall@gmail.com>
…task/1308-corpus-standard-code-references Signed-off-by: Serina Mcfall <serina.mcfall@gmail.com>
Correction: the draft hold above is liftedMy earlier comment on this PR said "do not mark this ready for review". That no longer Serina marked this PR ready for review deliberately, superseding the earlier hold. I What is still true, and is the reason the earlier comment existed: The cross-vendor final review has not run on this branch. So this PR is review-ready with a known, recorded gap in review coverage, rather than When credits return, the cross-model pass on the current head is still worth running. |
tucktuck101
left a comment
tucktuck101
left a comment
There was a problem hiding this comment.
Request changes
High — direct factual contradiction in AGENTS.md attribution
launchpad/docs/corpus/standards/code-references.md evidence entry 15 (~line 67) and §8 (lines 313-315) assert as FACT that "AGENTS.md introduces its citation table as CONTRACT.md section 3's six shapes and then lists seven rows." The AGENTS.md that ships in this branch was corrected (commit ebe2daf) and now says explicitly the seven-row table is NOT a summary of §3. The node was recorded against 60d4947 (old wording) but carries the corrected AGENTS.md, so the merged tree contradicts itself. The validator cannot catch this — checking is structural. Recast entry 15 and §8 to describe today's AGENTS.md.
Medium — ledger contradicts itself about opening files
Entry ~line 19-22 says a repository path "is opened on disk"; entry ~line 55-58 says a resolved file "is never opened." Both are present. A canonical reference standard cannot ship known-false ledger statements; reconcile them.
Medium — unverified-URL scoping
Entry ~line 43-46 says only "non-GitHub URLs" enter the unverified channel, but the standard itself records GitHub issue/PR URLs as unverified (:152-153). Align the two.
What looks good
Every verdict in §2 squares with validate.py at head; CONTRACT.md §3 genuinely has no URL form; ADR-0003 does require full-SHA pinning with never blob/main. Strong approve once the self-contradictions are reconciled. [panel: fable+codex]
…-standard-code-references Signed-off-by: Serina Mcfall <serina.mcfall@gmail.com>
Addresses all three findings from the review panel on PR #1480. Each verdict below was measured by calling validate._classify_citation directly rather than read off the document. High -- entry 15 and section 8 asserted as FACT that AGENTS.md "introduces its citation table as CONTRACT.md section 3's six shapes and then lists seven rows". The AGENTS.md this branch carries says the opposite in as many words: the table "is not a summary of section 3", because its two URL rows are forms validate.py recognises and section 3 does not enumerate. That correction landed in ebe2daf, after this node recorded its claim against 60d4947. The entry and section 8 now describe the AGENTS.md that actually ships beside them. Section 8 also now records what happened, because the node is a standard about citation discipline and this was a live instance of the failure it teaches against: a claim recorded against one revision of a moving document is not a claim about the document that finally ships. AGENTS.md records the same incident from its own side. The open CONTRACT.md-versus-validator divergence is unchanged and still points at #1478. Medium -- the ledger said a bare repository path "is opened on disk" while a later entry said a citation resolving to a real file "is never opened". Both cannot hold. Measured: a bare path returns ok on resolution alone and the file's contents are never read. The first entry now says resolved, and says explicitly that resolution establishes only that the file is there. Medium -- the ledger scoped the UNVERIFIED channel to "non-GitHub URLs", while the node's own table records GitHub issue and pull-request URLs as unverified. Measured: #1459 -> unverified #1462 -> unverified https://example.com/spec -> unverified .../blob/<full-40-sha>/path -> ok .../blob/launchpad/path -> error (mutable ref, ADR-0003) The entry now scopes the channel to external URLs that are not pinned repository links, and names GitHub issue and pull-request URLs as included -- which matches the table and the measured behaviour. Also merges origin/launchpad, which gained the corpus tree when #1468, #1469 and #1477 merged. No conflict: this branch already carried the same AGENTS.md blob. Verification: python3 launchpad/project-intelligence/corpus/validate.py PASS corpus validation found no errors; 5 item(s) reported unverified Signed-off-by: Serina Mcfall <serina.mcfall@gmail.com>
|
All three findings addressed in High — the AGENTS.md attribution. Confirmed and fixed. The §8 also now records the incident, because this node is a standard about citation Medium — opened vs never opened. Measured: a bare path returns Medium — unverified-URL scoping. Measured: So "non-GitHub URLs" was the wrong cut. The entry now scopes the channel to external URLs Also merges |
…r siblings reconcile (#1313) Serina decided #1486 on 2026-08-27: this node's built scope (a meta-standard for what a corpus standard document must itself be and contain) is the intended reading, and the four sibling standards drafted alongside it -- #1470, #1480, #1468, #1477 -- reconcile to it before merging, including the two (#1468, #1477) already merged onto launchpad. Cites the decision in scope-and-authority, states it as settled rather than provisional in Exceptions and escalation, corrects Scope and omissions' stale "pull requests are open" framing to name which two have already merged, and records the decision as a TEAM_KNOWLEDGE ledger entry attributed to #1486. This closes the Blocking finding from the review-final pass (fable+codex panel) that #1496 raised -- the node no longer publishes a binding meta-standard ahead of its authority being decided, because the authority is now decided. Signed-off-by: Serina Mcfall <serina.mcfall@gmail.com>
Per Serina's decision on #1486: this standard, drafted alongside #1313, reconciles to it rather than being grandfathered. G4 -- top-level sections were numbered ("## 1. Scope and authority" through "## 8. Scope and omissions"), which SHOULD NOT is now honoured rather than departed from silently. Removed the numbering; the relative order of D1's six required sections plus the two extras was already correct and needed no reordering. Internal cross-references that pointed at a section by its number (section "MUST N", "SHOULD N" identifiers are unaffected -- only "§5" and "§6" self-references to this document's own sections) now name the section instead: *Enforcement*, *Exceptions and escalation*. External references to CONTRACT.md's own §3 are untouched -- that numbering belongs to a different document. Recorded the reconciliation as a ledger entry attributed to #1486. Signed-off-by: Serina Mcfall <serina.mcfall@gmail.com>
New: reconciled to #1313's documentation-standardSeparate from the round-1 findings already fixed and awaiting re-review — this is new work following Serina's decision on #1486, which requires every sibling standard drafted alongside #1313 (this one included) to reconcile to it before merging. This node's only divergence was G4 (top-level sections SHOULD NOT be numbered) — its D1 section set and their relative order were already correct. Fixed at
Recorded as a ledger entry attributed to #1486. Validator passes clean; full test suite green (79 tests). Not re-requesting review again here since the round-1 re-review request is already pending — flagging this addition so the reviewer sees it alongside the earlier fixes. |
Fixed since this review by follow-up commits 9a9ebfc/91d2b3d01: the AGENTS.md attribution contradiction is corrected (with an explicit note that the earlier draft asserted the opposite), the 'opened vs never opened' ledger self-contradiction is reconciled, and the unverified-URL scoping now explicitly includes GitHub issue/PR URLs. Verified directly against current text. Dismissing as stale/resolved.
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
There was a problem hiding this comment.
Reviewed commit 1da545b4752a72d9c50252b4ead799105ef73fee against merge base dea96f837690703b1298ab3f0e49e1b82fecb8cf.
Incomplete
This review is INCOMPLETE and must not be read as a full pass:
- no dimension was actually reviewed: the pipeline ran the 'default_reviewer' stub reviewer, which reports every dimension clean without reading it (a real dimension reviewer is #116)
Containment
No containment findings.
Fetched and empty: pr_review_comments.
Automated containment covers the delimiter boundary and unambiguous injection tells only. It does not cover injection phrased as ordinary, unremarkable prose. The absence of a containment finding is not evidence that this pull request contains no injection attempt.
2 participants
Summary
Adds
launchpad/docs/corpus/standards/code-references.mdas the canonical policy node for how a corpus node cites code, node idcorpus-standard-code-references. Every verdict it states was measured by runningvalidate._classify_citation, not read off prose — which matters because the validator's real behaviour is counter-intuitive: a line number is never checked against the file, and a GitHub link is never checked at all. Nine review findings are filed rather than fixed, per this task's standing policy that only Blockers are fixed in place.Related issue
Closes #1308
Issue type
Task
Agent provenance
claude-opus-5[1m]Objective
Create the single canonical corpus node stating which code-reference forms are permitted, what each one actually proves, and how a reference stays honest as the code moves underneath it.
Impacted components
launchpad/docs/corpus/standards/code-references.mdlaunchpad/plans/2026-08-26-issue-1308-corpus-standard-code-references.mdApproach and rejected alternatives
The document's authority is executable: every MUST corresponds to a verdict the validator returns today, and section 1 states outright that where the document and the program disagree the program wins. The verdict table in section 2 separates what the validator returns from what that verdict establishes, because for three of the four code-naming forms the answer is "less than an author would assume".
Rejected — restating the schema's enums and field-combination rules in body prose. The validator never reads body prose, so a second copy stays green forever after going stale. The document links the schema and says explicitly that it is deliberately not copying it.
Rejected — declaring
references: corpus-agents. That target is loadable on this branch and would validate here, so it was a real option. Rejected becauselaunchpad/docs/corpus/AGENTS.mdis absent fromorigin/launchpad, and an unmatchedrelationships[].targetis a hard error. See Escalations — this reasoning is itself the subject of a filed finding.Rejected — folding the citation-shape reference into this node wholesale.
AGENTS.mdpre-assigns that table to the evidence standard, #1314. This node claims only the code-naming half, names the overlap in section 1 rather than resolving it, and leaves the ledger's own rules to #1314.Verification
Command run:
Raw output:
A negative control was run before those three commands, so they ran against the file as it ships. Three citations the standard forbids were injected into the ledger — an unpinned
blob/mainlink, aline:columnsuffix, and anowner/repo#Nissue reference — and the validator rejected all three:The revert was confirmed byte-identical with
diffbefore the suites ran. This is what establishes the document's MUSTs as enforced rather than asserted — and note the third message, which is the misleading rejection the document's section 5 item 4 documents.Not verified
codex execfailed withERROR: Your workspace is out of credits, twice, after consuming 93,913 tokens without producing a report. No other external model CLI is installed on this machine (gemini,agy,pi,llm,ollamaall absent). Areview-finalpass was run as a same-model substitute and is a weaker gate by construction — the recorded lesson on this is that three same-model passes on task: treat all pull request content as untrusted data #120 missed what one Codex pass caught immediately. It returnedREQUEST_CHANGESand found the Blocker that is now fixed, so it was not useless; but a genuine cross-model pass on this node has not happened and should be run before merge.git cat-file -ewas run for this node's own recorded revision only. Section 6 states that procedure from that single use.find_citation_problemstreats a corpus path specially, so no difference is expected; it was not confirmed.pull_request; local and CI run the same command, so a local pass is expected to reproduce, but that is a prediction.Security implications
None. The change adds two Markdown documents and no executable code, no configuration, and no dependency. It reduces one small exposure rather than adding any: the standard's MUST 4 pushes authors toward repository-relative paths, which the validator resolves and confines to the repository tree, and away from GitHub URLs, which it accepts on syntax alone. The validator's existing credential-path blocklist is unchanged and was not weakened; no citation added here names a credential-shaped path.
Escalations
Nine findings were confirmed by
review-code,review-finaland tworeview-adjudicatepasses and are filed rather than fixed, because this task's standing policy fixes only Blockers in place. Each was measured, not asserted:review-code, re-rated by two adjudicationsAGENTS.md, which is absent fromorigin/launchpad. Not blocking: this PR's base istask/636-corpus-agents-md, so its diff carriesAGENTS.md; merge, squash, rebase and 636-first were each executed againstorigin/launchpadand all validated exit 0. See the merge precondition below.review-finalFACTentries misdescribe measured validator behaviour: entry 9's "non-GitHub URLs" is under-inclusive (a GitHub issue URL also measuresunverified), and "opened" is used where the code only stats. Wording, in a document whose body gets both right.review-finalvalidate.py's own comment conflict on whether the unchecked line number is a defect or a deliberate deferral. Entry 19 picks one side without recording the conflict. Best fixed by resolving #1459, not by rewording.review-final, re-rated MediumCONTRACT.md§3 enumerates six citation shapes and none is a URL;validate.pyimplements a URL branch anyway;AGENTS.mdpresents a seven-row table introduced as "CONTRACT.md §3 defines the six shapes". Not this node's to reconcile: it may not editAGENTS.mdand does not ownCONTRACT.md. Adjacent to #1471 but not a duplicate.review-finalpath:line:colcase to section 5 for its explanation, but that citation matches_FILE_POSITION_REwith a truncated path rather than falling through as section 5 describes. Same message, different cause.Raised and refuted, so not filed:
review-code's Blocker that theAGENTS.mdcitations hard-fail onlaunchpad. Refuted by measurement —git diff origin/launchpad...HEAD --name-onlyshows this PR's diff addsAGENTS.md, and every merge strategy was executed and validated exit 0. Its substance survived as #1473. Also refuted: acheck-ledger.shfailure, on the evidence that no SDD ledger is tracked on any ref in this repository, so the check fires identically on every PR here.Fixed in place, as the one confirmed Blocker: MUST 2 required a "bare" repository-relative path, forbidding the
path:lineandpath:start-endshapes that MUST 6 permits, SHOULD 1 merely disprefers, and section 2's own table records asok— and no validator verdict backed it, falsifying section 1's claim that each MUST corresponds to one. Commite8db1a6bf.Merge precondition, per #1473. This PR is stacked on
task/636-corpus-agents-md(PR #1462). Merge #1462 first, or merge this PR as-is so it carriesAGENTS.mdwith it. Do not rebase this branch ontolaunchpadalone — that dropsAGENTS.mdand four of this node's citations resolve to nothing.Open questions this node deliberately did not decide, all recorded in the plan and in the node's body: whether
developerbelongs inaudiences(added here on #605's Outcome wording, classifiedTEAM_KNOWLEDGEfor that reason); whether ADR-0003's markdown-link wrapper is required on corpus evidence, which_classify_urlsays is #605's call; and whether the citation-shape table's final home is here or #1314.