docs: correct nine one-low 3.3.N cross-references and one dead anchor - #237
Conversation
Signed-off-by: Tymofii Pidlisnyi <signal@aeoess.com>
|
🔴 Contributor Check: HIGH
Automated check by AgenTrust Contributor Check. |
github-actions
Bot
added
the
needs-review:HIGH
lywinged
left a comment
lywinged
left a comment
There was a problem hiding this comment.
Both corrections are right, and the rule that makes them right locates the rest of them. Eighteen references to a 3.3.N subsection exist in the tree. Nine are one low. This PR takes two.
Why the class exists
v0.2 inserted a subsection and pushed everything below it down one:
v0.1 3.3.1 External execution evidence 3.3.2 Action receipts
v0.2 3.3.1 Build provenance depth 3.3.2 External execution evidence 3.3.3 Action receipts
Every reference written against v0.1's numbering that now points into v0.2 is one low. Every reference that still points into v0.1 is correct and has to stay. That one test sorts all eighteen, and it sorts them in two directions, because a reference to action receipts is one low as well.
The sweep
Each section 3.3.N and §3.3.N in the tree, read against the heading it actually lands on.
Off by one:
| where | says | the text is about | should be |
|---|---|---|---|
docs/verification.md:275 |
3.3.1 | receipt_unverified |
3.3.2, this PR |
spec/trace-v0.2.md:404 |
3.3.1 | external execution evidence rules | 3.3.2, this PR |
docs/tutorials/verifying-the-audit-chain.md:147 |
§3.3.1 | "defines the receipt structure" | 3.3.2 |
examples/action-receipts/README.md:96 |
§3.3.1 | the 14-receipt-issuer-key-unknown vector |
3.3.2 |
examples/action-receipts/README.md:119 |
§3.3.1 | the receipt_unverified outcome |
3.3.2 |
examples/action-receipts/conformance/gen_rule_coverage_vectors.py:198 |
3.3.1 | issuer_key_unknown is unverified, not invalid |
3.3.2 |
tests/test_action_receipt_fixtures.py:150 |
3.3.1 | the same sentence, in the test that consumes those vectors | 3.3.2 |
examples/action-receipts/README.md:9 |
3.3.2 | the three evidence layers, which is §3.3.3's table | 3.3.3 |
docs/verification-outcome-statements.md:27 |
§3.3.2 | "Not success of any physical or business outcome" | 3.3.3 |
Correct as they stand:
| where | says | why it is right |
|---|---|---|
docs/verification.md:146 |
§3.3.1 | build provenance depth, which is what §3.3.1 is |
docs/verification-outcome-statements.md:28, 29, 30 |
§3.3.1 | the downgrade, contradiction and floor rules, all inside §3.3.1 at lines 355 and 361 |
spec/trace-v0.1.md:264 |
3.3.1 | external execution evidence, inside v0.1's own numbering |
docs/crosswalks/acta-decision-receipts.md:9, 50, 105 |
3.3.2 into v0.1 | action receipts, correct for v0.1 |
examples/action-receipts/acta/README.md:8 |
3.3.2 into v0.1 | same |
The rule the §3.3.1 rows are reaching for is spec/trace-v0.2.md:382, "A receipt whose issuer key is unknown to the verifier is unverified, not invalid", which sits inside §3.3.2 (368 to 385). The tutorial row is reaching for the paragraph listing issuer, issuer_key_id, signature, evidence_hash, evidence_type and linked_call_id, also §3.3.2. The two rows that should read 3.3.3 are reaching for the three layer table at line 393.
The two this PR takes are the load bearing pair, since one of them is normative text. Of the seven that remain, five are one sentence copied into a tutorial, twice into one example set, a generator, and the test that consumes what that generator produces, which is how a single number ends up in five places.
One of the nine is also a dead link
examples/action-receipts/README.md:9:
[spec section 3.3.2](../../spec/trace-v0.2.md#332-action-receipts-for-embodied-workflows-informative)
The paragraph under it lists session evidence, action issuance evidence and outcome evidence, which is §3.3.3's table. So the number is one low and the anchor names a heading that does not exist in the file it points at: the link lands at the top of the spec instead of at the section. Both halves are one character each: 3.3.3 in the text, and #333-action-receipts-for-embodied-workflows-informative in the anchor.
The four CI steps are ruff, the dash check, mypy and pytest, so nothing in the pipeline reads a link, which is why this one has been able to sit.
Two notes on the pull request itself
The description does not use the repository's pull request template, so Type of change, Spec section and the checklist are absent. spec/trace-v0.2.md is normative text, and while a cross reference correction is editorial and needs no sponsor under CONTRIBUTING, the form is what says so to a reviewer without them working it out.
Checked before writing this: on the branch, ruff, the dash check and mypy are clean and pytest gives 828 passed with 1 skipped, unchanged from main, which is what a docs only change should look like.
Taking the other seven here would close the class rather than two instances of it, and each is a one character edit. If you would rather keep this PR to the two sites in normative and normative adjacent text, say so and the rest can go in its own change.
….3.3 anchor v0.2 inserted 3.3.1 (build provenance depth) and pushed the sections below it down one. Nine references written against v0.1 numbering pointed one section low; the first commit took the two in normative and normative-adjacent text, this one takes the other seven: tutorial, example README (three sites, one with an anchor that named a heading not in the file), vector generator, the test consuming it, and outcome-statements. References into spec/trace-v0.1.md and to build provenance depth are correct and untouched. Sweep and table by @lywinged in review. Signed-off-by: Tymofii Pidlisnyi <signal@aeoess.com>
aeoess
changed the title
|
Taken all nine here, plus the anchor, as a second commit (dc30054); your table was exact, including the two that read 3.3.3. Left the v0.1 and build-provenance references alone per the rule. PR body now on the template, editorial. Ruff, dash check, mypy and pytest 828/1 on the branch, same as your run. |
imran-siddique
left a comment
imran-siddique
left a comment
There was a problem hiding this comment.
Nine off-by-one cross-references and a dead anchor, with the cause identified rather than just the symptom: v0.2 inserted §3.3.1 above the v0.1 sections, so anything written against v0.1 numbering that now points into v0.2 shifted by one.
The part that makes this safe to merge quickly is what you did not touch. References into spec/trace-v0.1.md are correct under v0.1 numbering and stay; references to build-provenance depth are correct and stay. A blanket increment of every 3.3.N in the repository would have broken both classes, and that is the obvious way to do this job wrong.
The anchor, #332-... naming a heading that does not exist, is the one a reader hits as a silent scroll-to-nothing rather than an error. Worth having caught.
Merging.
3 participants
What this changes
Nine references to a
3.3.Nsubsection point one section low. v0.2 inserted §3.3.1 (build provenance depth) above the v0.1 sections, so references written against v0.1 numbering that now point into v0.2 are off by one: the external-execution-evidence rules are §3.3.2, the action-receipt layers are §3.3.3. All nine are corrected; one of them also carried an anchor naming a heading that does not exist in the file (#332-...for a §3.3.3 heading), now#333-.... References intospec/trace-v0.1.mdand references to build provenance depth are correct and untouched.Sites:
docs/verification.md:275,spec/trace-v0.2.md:404,docs/tutorials/verifying-the-audit-chain.md:147,examples/action-receipts/README.md:9,96,119,examples/action-receipts/conformance/gen_rule_coverage_vectors.py:198,tests/test_action_receipt_fixtures.py:150,docs/verification-outcome-statements.md:27. The sweep and table are @lywinged's, from review.Type of change
Spec section
§3.3.2 and §3.3.3 of
spec/trace-v0.2.md(one cross-reference in §3.3.3 itself); the rest are docs, examples and tests that cite them. No normative text changes beyond the section number.Checklist
git commit -s)CHANGELOG.mdupdated (for any normative change): not applicable, editorial<!-- CHANGED: #NNN: description -->in spec text: not applicableLocal run of the four CI steps on the branch: ruff clean, dash check clean, mypy clean, pytest 828 passed 1 skipped, unchanged from main.