revert: remove the contract-claims gate (#997)

[drawmeanelephant]

Agent Completion Report

• Status: complete

• Branch and Worktree:

  • Branch: revert/997-contract-claims-gate
  • Worktree: primary checkout

• Commit and PR:

  • Commit: 4d0e4784 (head; 213675f1 is the revert, 576b7b0c the fragment rename)
  • Target PR / Branch: main (this PR is revert: remove the contract-claims gate (#997) #998)

• Linked Issues (auto-close convention):

  Refs Cooklang name-termination: contract's {-adjacency guard is not enforced (@salt into the {bowl} misparses) #907

  This revert does not close the Cooklang {-adjacency defect. That fix still lives in Oliver (or a contract rewrite), not in a quote-tether registry.

• Changed Files:

  • build.zig — drop test-contract-claims and its zig build test wiring
  • scripts/test-contract-claims.sh — deleted
  • test/contract-claims.txt — deleted
  • test/contract-claims.checks.sh — deleted
  • test/README.md — drop registry docs
  • docs/changelog.d/997-contract-claims-gate.md — deleted
  • docs/changelog.d/998-revert-997-contract-claims-gate.md — revert fragment
  • AGENTS.md — forbid inventing parallel verification products without an explicit user request
  • docs/AGENT-PLAYBOOK.md — standing gates are a closed ship set

• Preserved Unrelated Files:

  • Other worktrees (t3code/review-pr-994, t3code/microcopy-and-editor-polish-pass, t3code/fix-graph-fit-undo-preview, t3code/editor-four-issue-fixes, t3code/editor-aesthetic-slices, t3code/editor-graph-map-zoom) are untouched. No other dirty files on this checkout.

• Implementation Summary:

  • Reverts merge e0edad3c (PR feat(test): gate contract claims against the built binary (#907) #997). The contract-claim registry, quote-tether runner, and --audit worklist were extra process on top of existing unit, CLI, and release-gate checks.
  • They made every zig build test pay for six process spawns and invited filling 52 remaining contracts. Compiler behavior is unchanged.
  • Existing coverage for the five "enforced" claims stays: parser tests for legacy parent keys, pipeline fixtures for EPARENTMISSING, test/cli-contract.sh for usage/I/O exits, scripts/test-version-pin.sh for --version.
  • AGENTS.md now treats claim registries, quote-tether harnesses, contract-audit worklists, and known-divergence ratchets as needing an explicit user request. A silent contract/code split is a defect: fix the code or rewrite the contract.

• Known Gaps:

  • Cooklang name-termination: contract's {-adjacency guard is not enforced (@salt into the {bowl} misparses) #907 remains open. The two honest remediations are still: enforce {-adjacency in Oliver, or stop claiming it in docs/contracts/cooklang-compatibility.md.

• Exact Commands Run:

  1. git revert -m 1 --no-commit e0edad3c
  2. zig fmt --check build.zig
  3. git diff --check origin/main...HEAD
  4. zig build test

• Exact Gate Results:

  • zig fmt --check build.zig: pass
  • git diff --check origin/main...HEAD: clean
  • zig build test: pass (exit 0; ~144s). No test-contract-claims step. Policy-only follow-up did not rerun the suite.

• Determinism Result:

  • N/A. This deletes a gate and records policy; it does not change emitted artifacts.

• Generated Artifacts:

  • None committed. Zig caches only.

• Blockers and Next Card:

  • Blockers: None
  • Next Card: If Cooklang name-termination: contract's {-adjacency guard is not enforced (@salt into the {bowl} misparses) #907 is still wanted, fix Oliver or rewrite the Cooklang contract. Do not rebuild a contract-tether registry.

Summary

• Revert PR feat(test): gate contract claims against the built binary (#907) #997's contract-claims gate so zig build test is not paying for quote-tether bureaucracy.
• Record in AGENTS.md that parallel verification products need an explicit user request.
• Cooklang name-termination: contract's {-adjacency guard is not enforced (@salt into the {bowl} misparses) #907 stays open; this does not paper over the Cooklang adjacency bug with a known-divergence record.

Test plan

• zig build test green without test-contract-claims
• Confirm CI on this PR does not invoke scripts/test-contract-claims.sh
• After merge, zig build test on main has no contract-claims step

[itoqa]

Commit: 4d0e478: 10 test cases ran, 8 passed ✅, 2 additional findings ⚠️.

Summary

The run covers core verification workflows, including successful content processing, deterministic command-line behavior, version and artifact consistency, validation of invalid or incomplete content, and documentation guidance and link integrity. It also exercises edge cases and failure reporting, plus the ordering and completion behavior of the overall verification process.

Safe to merge — the reported failures are pre-existing, unrelated issues in invalid-content result reporting and documentation-link validation, with no regression or new failure attributable to this PR. They remain useful follow-up fixes but do not block merging this change.

Tests run by Ito

Result	Severity	Type	Description
✅	—	General	The verification instructions tell contributors to add focused coverage or extend an existing script. They do not accept a claim registry, quote-tether, or contract-audit runner as the normal workflow.
✅	—	General	The retained verification checks produced results before the aggregate command reported its final outcome, and the removed registry check did not run. The command later stopped on separate broken documentation links, not on an ordering problem.
✅	—	Build	Verified acceptable by independent adversarial review: the observation traces to the QA environment, and the application behavior is acceptable. Review notes: The aggregate gate and its obligation are real, but the reported diagnosis that 31 documentation links point to missing headings is contradicted by the checked source: the fragment links resolve to headings that produce the requested slugs, including the representative cross-file links cited above, and an exhaustive inspection found all 31 checker-eligible fragment occurrences valid. The all-fragm…
✅	—	Documentation	The repository guide lists the retained checks and tells contributors to add missing coverage to a focused test or existing script. It does not advertise the removed registry or a replacement parallel gate.
✅	—	Rev	The invalid fixture was rejected, and both validation paths reported EPARENTMISSING as expected.
✅	—	Rev	The command-line smoke check passed twice. It produced identical report output and kept the expected content, usage, and input/output exit codes.
✅	—	Rev	The version check passed. Both version commands returned boris/0.8.2, and the plain, Cooklang, and semantic artifact sets recorded the expected IDs.
✅	—	Rev	The changed documents exist, all 20 checked repository links resolve, and no maintained instructions mention the deleted contract-claims files or command.
⚠️		General	The invalid content check exits as expected, but no result file is available for the caller to inspect.
⚠️		Test	Running the aggregate test reaches the retained verification checks, then reports 31 broken documentation links and exits with code 1 instead of completing successfully.

Additional Findings Details

These findings are unrelated to the current changes but were observed during testing.

🟡 Invalid content does not produce a result file

• Severity: Medium
• Description: The invalid content check exits as expected, but no result file is available for the caller to inspect.
• Impact: Callers that submit invalid content receive the failure status but cannot read the structured result file with the error details. They may need to rely on raw logs or manual investigation to understand and handle the failure.
• Steps to Reproduce:
  1. Build the repository with zig build -Doptimize=ReleaseSafe.
  2. Run scripts/test-job-runner-image.sh from the repository root.
  3. Wait for the valid fixture to pass, then let the missing-parent fixture run through boris-job-runner --once with --result-json.
  4. Observe that the command exits 1 and the expected poisoned.json file is missing instead of containing the failed content result.
• Stub / mock content: No stubs, mocks, or bypasses were applied for this test in the recorded run.
• Code Analysis: The retained script creates a missing-parent archive and invokes boris-job-runner --once with --result-json "$OUT/poisoned.json" at scripts/test-job-runner-image.sh:59-65. It correctly expects exit code 1, then requires the result file and checks ok: false, runnerClass: content, an empty artifacts array, and an EPARENTMISSING diagnostic at lines 68-76. The recorded run reaches the expected exit code but the file is absent, producing FileNotFoundError in the validation step. In src/job_runner.zig:453-602, runJob executes the compiler, parses the report, and returns a structured failed JobResult for a nonzero compiler exit; in src/job_runner.zig:577-601 it preserves the failed result with no artifacts. runOnce then renders that result and writes the requested JSON at src/job_runner.zig:1179-1189 before returning the runner class exit code. The observed absence means the invalid-content CLI path is not delivering the result artifact that its own caller contract requires, despite the expected structured result being defined in the production path. The smallest fix is to make the --once failure path persist the rendered JobResult for content failures before returning exit code 1, then add or restore a CLI-level regression test for the result-json file, rather than changing the removed build integration.

Evidence Package

• text/BF-INTEGRATION-1/invalid-content-result.json.txt — 4 KB

🟡 Aggregate test stops on broken documentation links

• Severity: Medium
• Description: Running the aggregate test reaches the retained verification checks, then reports 31 broken documentation links and exits with code 1 instead of completing successfully.
• Impact: Developers and CI cannot complete the aggregate repository verification check because it stops on 31 broken documentation links. This blocks the documented ship check until the links are repaired or the documentation claim is narrowed.
• Steps to Reproduce:
  1. From the repository root, run zig build test.
  2. Wait for the aggregate checks to finish.
  3. Observe the documentation-link check report 31 missing heading anchors and the aggregate command exit with code 1.
• Stub / mock content: No stubs, mocks, or bypasses were applied for this test in the recorded run.
• Code Analysis: The aggregate step is constructed in build.zig at lines 1851-1941. It still depends directly on run_parser_tests (lines 1865-1866), run_cooklang_tests and cooklang_incremental_run (lines 1868-1870), run_pipeline_tests (line 1875), run_hardening_tests (line 1916), and doc_links_run (line 1937), along with the other retained runners. The PR diff removes only the contract-claims command definition near lines 789-809 and the contract_claims_run dependency; it does not alter the documentation-link runner or any of the retained test dependencies. scripts/test-doc-links.sh is intentionally a hard-failing gate (failures is incremented for each broken link and the script exits nonzero at the end), and its header says it runs inside zig build test. The recorded output therefore demonstrates a real failing repository verification gate, but the defect is not caused by this PR's deletion of the registry dependency. The smallest practical fix is to repair or remove the 31 stale anchors and links reported by scripts/test-doc-links.sh, or explicitly narrow the current documentation/release claim if those links are intentionally archival; no change to the removed contract-claims wiring is needed.

Evidence Package

• text/TEST-1/TEST-1-doc-links-failure.txt — 3 KB

Tip

Reply with @itoqa to send us feedback on this test run.