Repository navigation
docs: make the agent operating contract executable and self-adversarial + repair stale doc links - #814
Merged
Conversation
Turn CLAUDE.md and AGENTS.md from prose guidance into a checkable contract, in the repo's own "build trust, not theater" spirit: - Every non-negotiable now names the command that catches its violation, or is marked "you are the guard" where no automated check exists yet. All 16 referenced make targets and all doc paths verified to resolve; make doc-links-check passes (0 broken / 484 files). - Add a pre-PR "disconfirming pass" (cheapest-explanation, leakage, scope, certainty, uninformative-uncertainty) derived from GOAL.md's cheapest disconfirming tests — trying to prove your own change wrong before shipping it. - Add an anti-Goodhart clause: green checks are a floor, never a verdict. - Wire in AGENT_TASKS.json as the machine-readable task router (safe paths, forbidden zones, required checks) from both front doors. - Make stop conditions produce a decision-log draft handoff instead of a dead end (decision_logs/INDEX.md). - Add a "write for the agent that replaces you" durability principle so the rules get more true as models get smarter, not less. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_0151yUvpHj6wAd6JraWyChEX
The doc-link checker only scans docs/, so links in root-level files and
decision_logs/ have silently rotted since docs/ was reorganized into
subdirectories. Repair the whole class so every reference points where it
claims to:
- CONTRIBUTING.md: 11 onboarding/governance/claim links moved to their
real docs/{getting-started,trust,engineering,operations,research,
evidence}/ homes.
- decision_logs/INDEX.md: bare "DECISION_RECORD_TEMPLATE.md" now links to
the real docs/operations/DECISION_RECORD_TEMPLATE.md (no duplicate
template created).
- SAFETY.md, RESPONSIBLE_USE.md: PROOF_LADDER / CLAIM_REVIEW_CHECKLIST /
AGENT_ONBOARDING paths corrected — link targets only, no policy or
claim-strength change.
- SECURITY.md, GOVERNANCE.md, MODEL_RELEASE_POLICY.md,
DATA_LICENSE_NOTICE.md: RELEASE_CHECKLIST / SAFETY_DOC_AUDIT /
MODEL_CARD_TEMPLATE / DATA_GOVERNANCE / BENCHMARK_GOVERNANCE /
AGENT_ONBOARDING paths corrected. RELEASE_CHECKLIST points to the
canonical docs/trust/ copy (the docs/governance/ copy self-declares it
as canonical).
CHANGELOG.md left untouched (dated historical record; its links were
accurate when written). Verified: 0 broken links across all root and
decision_logs markdown; make doc-links-check still clean (484 files).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0151yUvpHj6wAd6JraWyChEX
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
Two doc-only commits that make the agent-facing operating contract sharper and repair silent link rot — in the repo's own "build trust, not theater" spirit.
1. Make CLAUDE.md + AGENTS.md executable and self-adversarial. The docs were already strong; this turns prose guidance into a checkable contract:
make claim-check-strict,make bench-cheap-enemies,make bench-leakage,make cert-quality-check, …), or is honestly marked "you are the guard" where no automated check exists yet.GOAL.md's cheapest disconfirming tests.AGENT_TASKS.jsonas the machine-readable task router from both front doors.decision_logs/INDEX.md) instead of a dead end.2. Repair stale flat-path doc links across root-level docs. The doc-link checker only scans
docs/, so links in root files anddecision_logs/silently broke whendocs/was reorganized into subdirectories. Repaired the whole class (CONTRIBUTING.md ×11, decision_logs/INDEX.md, SAFETY.md, RESPONSIBLE_USE.md, SECURITY.md, GOVERNANCE.md, MODEL_RELEASE_POLICY.md, DATA_LICENSE_NOTICE.md) — link targets only, no policy or claim-strength change.CHANGELOG.mddeliberately left intact as a dated historical record.Change class
Type of change
Safety impact
Claim discipline
docs/evidence/PROOF_LADDER.mdBaseline and benchmark discipline
Not applicable — no scorer, predictor, simulator, ranking, calibration, or benchmark behavior changed.
Verification
make doc-links-checkclean (484 files, 0 broken)make claim-check— no findings in any edited filemaketarget and doc path referenced by the new CLAUDE.md/AGENTS.md verified to resolve (16 targets, all doc paths)decision_logs/markdown re-swept: 0 broken links (CHANGELOG.md intentionally excluded)Agent disclosure
docs/getting-started/AGENT_ONBOARDING.mdboundariesEvidence
Commands run:
make doc-links-check→Files: 484, Broken: 0make claim-check→ only pre-existing finding indocs/trust/DATA_GOVERNANCE.md(not edited here); no findings in any edited fileWhat this does not prove: it does not change any scientific behavior, benchmark, or claim strength; it does not validate any of the referenced docs' contents — only that references now point where they claim to.
External or wet-lab-facing impact
Dependencies and licenses
Reviewer focus
decision_logs/INDEX.mdreferencesmake decision-log-index, a Makefile target that doesn't exist; and twoRELEASE_CHECKLIST.mdcopies exist (docs/trust/canonical,docs/governance/a cross-referenced gate-structure doc) — intentional but a sync-drift risk.🤖 Generated with Claude Code
Generated by Claude Code