Skip to content

docs: make the agent operating contract executable and self-adversarial + repair stale doc links - #814

Merged
cschanhniem merged 2 commits into
mainfrom
claude/improve-claude-agents-docs-aeajch
Jul 9, 2026
Merged

cschanhniem merged 2 commits into
mainfrom
claude/improve-claude-agents-docs-aeajch

Conversation

@cschanhniem

Copy link
Copy Markdown
Collaborator

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:

  • Every non-negotiable now names the command that catches a violation (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.
  • Adds a pre-PR disconfirming pass (cheapest-explanation, leakage, scope, certainty drift, uninformative-uncertainty) derived from GOAL.md's cheapest disconfirming tests.
  • Adds an anti-Goodhart clause: green checks are a floor, never a verdict.
  • Wires in AGENT_TASKS.json as the machine-readable task router from both front doors.
  • Makes stop conditions produce a decision-log draft handoff (decision_logs/INDEX.md) instead of a dead end.
  • Adds a "write for the agent that replaces you" durability principle so the rules get more true as models get smarter.

2. Repair stale flat-path doc links across root-level docs. The doc-link checker only scans docs/, so links in root files and decision_logs/ silently broke when docs/ 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.md deliberately left intact as a dated historical record.

Change class

  • Class A — safe documentation or small bug fix

Type of change

  • Documentation update
  • Agent/onboarding improvement

Safety impact

  • No biological misuse capability added
  • No wet-lab protocol or operational biological procedure added
  • No harmful optimization objective added
  • No unscreened candidate sequences published
  • No model weights or sensitive artifacts released without policy review
  • No efficacy, safety, clinical, or therapeutic claims without evidence
  • Limitations and failure modes documented
  • Evidence is reproducible where applicable
  • Human safety review requested if this is safety-sensitive

Note: SAFETY.md, RESPONSIBLE_USE.md, SECURITY.md, GOVERNANCE.md, and MODEL_RELEASE_POLICY.md were edited — but for link-target corrections only. No policy wording, claim strength, threshold, or scope changed. Worth a reviewer's glance to confirm.

Claim discipline

  • Claims are mapped to docs/evidence/PROOF_LADDER.md
  • Dry-lab outputs are not described as biological proof
  • No "AI discovered an antibiotic" / "drug candidate" / "safe" / "clinically useful" language unless evidence level supports it
  • Unsupported claims are explicitly listed or avoided

Baseline and benchmark discipline

Not applicable — no scorer, predictor, simulator, ranking, calibration, or benchmark behavior changed.

Verification

  • Documentation updated (this PR is documentation)
  • make doc-links-check clean (484 files, 0 broken)
  • make claim-check — no findings in any edited file
  • Every make target and doc path referenced by the new CLAUDE.md/AGENTS.md verified to resolve (16 targets, all doc paths)
  • Root + decision_logs/ markdown re-swept: 0 broken links (CHANGELOG.md intentionally excluded)

Agent disclosure

  • This PR was fully or partly agent-generated and human-reviewed
  • Agent-generated changes stayed within docs/getting-started/AGENT_ONBOARDING.md boundaries

Evidence

Commands run:

  • make doc-links-check → Files: 484, Broken: 0
  • make claim-check → only pre-existing finding in docs/trust/DATA_GOVERNANCE.md (not edited here); no findings in any edited file
  • Repo-wide sweep script confirming all root/decision_logs links resolve (0 broken, CHANGELOG excluded)

What 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

  • Not applicable
  • Does not include operational experimental instructions

Dependencies and licenses

  • None

Reviewer focus

  • Confirm the link-only edits to safety/governance/release-policy docs (SAFETY.md, RESPONSIBLE_USE.md, SECURITY.md, GOVERNANCE.md, MODEL_RELEASE_POLICY.md) carry no policy/claim change — path corrections only.
  • Two loose ends found but intentionally not fixed here (candidates for follow-up issues): decision_logs/INDEX.md references make decision-log-index, a Makefile target that doesn't exist; and two RELEASE_CHECKLIST.md copies 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

claude added 2 commits July 9, 2026 10:06
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
@cschanhniem
cschanhniem merged commit 0331609 into main Jul 9, 2026
1 check failed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants