[cgfixit]

Proposed changes

A /doc-sync manual pass over the live READMEs and reference docs, resynced
from origin/main @ 6519135. The deterministic checker
(.claude/skills/doc-sync/doc_sync.py) was already at 0 drift, so this PR is
the Step 3 prose pass it cannot do: every concrete claim in 29 files was read
against the code, config, or script it describes, drift was corrected in the
doc (never the code), and each moderate-to-large file was trimmed ~5–10% by
removing duplication and changelog prose that git already records.

.githooks/README.md is a protected path; its commit (8a92207) was made
with HOOK_OPERATOR_ACK=1 at the owner's explicit request in-session, after
the gate refused it the first time and the file was held back.

Drift fixed (claim → source of truth):

• macos/README.md, powershell/README.md — secret classification described as an inline allowlist plus _API_KEY/_TOKEN/_SECRET/_PASSWORD; the loaders read utils/secret-policy.tsv (nine suffixes incl. PAT, DSN, DB_URL, KEY, and 16 exact rows). macos/cyclaw-linux-key.sh was missing from the Scripts table.
• utils/README.md — six modules on disk had no row: secret_policy.py, child_environment.py, public_errors.py, external_budget.py, bounded_executor.py, _unicode_confusables.py.
• sync/README.md — scheduled.py (what the generated cron/plist/task runs) was undocumented.
• guardrails/README.md — verify_install.py missing from the package map.
• docs/THREAT_MODEL.md — "G1 pins 15 of these orderings" → the checker pins 14; "harness server" listed as a chokepoint although the console was removed (sixteenth amendment).
• .githooks/README.md — the protected-path check at push listed as if it blocked; _security.sh line 328 only prints a reminder there (it blocks at commit).
• README.md — "Current development" pinned to a stale commit/date; now points at the merged-PR list and docs/changelog.txt.

Scope decisions, per the owner's instruction mid-session: docs/*.md limited
to the critical references; design/plan docs for shipped-off subsystems
(channels, fsconnect enablement, DEFERRED_WORK, EVALS, POSTGRES, online-llm,
input-boundaries, numbat secondary evaluator), every dated docs/audits/
record, docs/plans/, docs/work/, zOld/, zWork/ were left untouched.
docs/THREAT_MODEL.md received the two drift fixes only — no trimming of a
security scope document.

Invariant / Governance Impact: none. Markdown only; no code, config,
tests, hook scripts, or workflows change. check_invariants.py passes on the head.

Types of changes

• Bugfix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Security (auth, privacy, injection, egress, redaction, or secrets)
• Invariant / Governance refinement (use this for changes that strengthen or evolve the 6 invariants, I6 isolation, or harness phases)
• Dependencies (added, removed, or bumped)
• CI / infrastructure (workflows, hooks, templates, or checkers)
• Refactor or tests (behavior-preserving, no new capability)
• Documentation update
• Other (none of the boxes above fit)

Scope note: Docs + audits. Three agent-instruction files changed
(.claude/README.md, .claude/skills/babysit-github-pr/README.md,
.codex/README.md) — all hand-written condensation of existing text; nothing
copied in from an external source.

Benefits / why

• Two platform READMEs told operators the wrong secret-classification rule; an operator naming a *_DSN or *_PAT variable would have expected it to stay in dotenv when the loaders actually treat it as a secret.
• Six utils/ modules and sync/scheduled.py now have a documented reason to exist, so the next reader does not grep for them.
• ~397 KB → ~376 KB across the touched set (−5.4%), with the biggest cut on .claude/README.md (−28%: dated chronology replaced by the rules it produced; history stays in git). Every ## section remains self-contained for the corpus chunker.

Risks to monitor

• A trimmed sentence may have carried a nuance a reader relied on. Mitigation: no command, table row, warning, accepted-risk note, or test reference was deleted; cuts were restatements and dated narrative. Reviewers should spot-check .claude/README.md and docs/AUTHENTICATION_DESIGN.md §2, the two largest rewrites.
• Tests pin literal README phrases (test_powershell_windows_parity.py caught two on the first CI run; restored in 18f9654). ci (3.12) on the current head is the check that proves no other phrase contract was broken.
• D12/D13 contract tables in the root README (Local records, Secret persistence) are byte-identical; test_contracts.py is green.
• Detect drift the usual way: the doc-sync CI job and python3 .claude/skills/doc-sync/doc_sync.py.

Checklist

• I have read docs/THREAT_MODEL.md, INVARIANTS.md and SECURITY.md (and any relevant Phase docs)
• This change preserves all 6 security invariants and I6 module isolation (explicit evidence or invariant matrix included for core changes)
• Full sandbox validation has been run (GROK_API_KEY=dummy pytest tests/ -q --tb=short, and bash .claude/skills/CyClaw-Sandbox/verify.sh for core RAG/agentic paths) and passes with no regressions
• No new external network dependencies or mandatory online LLM assumptions were introduced without explicit justification + offline fallback path
• For any agentic/fsconnect change: two-phase audit, quota enforcement, governed delete/trash, and write guards have been verified
• Relevant architecture docs or threat model notes have been updated if core behavior or topology changed
• Commit messages follow the title prefix convention above
• For large or complex changes: before/after invariant matrix + sandbox evidence is included in "Further comments" or linked

Further comments

Checks run directly (CLAUDE.md §5 verification policy): doc_sync.py (0
drift, all 13 checks), test_contracts.py (OK), check_invariants.py
(pass), and tests/test_powershell_windows_parity.py after the phrase fix.
The full pytest suite ran only in CI (first run: 6160 passed, 2 failed — the
two fixed in 18f9654). Numeric claims were verified by reading
config.yaml, docker-compose.yml, the scripts, and the modules named in
each doc (e.g. policy.external_call_limits 100/1000,
numbat.write_wait_sec 1.0, STALE_AFTER_DAYS 30, babysit knob defaults).

Suggested merge order of open PRs

Trial merges verified (git merge --no-commit --no-ff + abort) against main @ 6519135 on 2026-10-13.

#1636 · Safe ✅
Impact: removes the inert app.debug key and a stale agentic comment; no doc overlap with this PR.
Action: merge first (lower number). Independent.

This PR · Safe ✅
Impact: Markdown only, 29 files; no shared files with #1636.
Action: merge any time after. Clean against main.

#1640 · Safe ✅
Impact: adds one dated audit doc under docs/audits/; no shared files.
Action: merge any time; independent.

ELI5

The docs were telling the truth about the big things (the checker that counts
routes, nodes, and numbers was already green) but had drifted in the prose:
two install guides described the wrong rule for which environment variables
count as secrets, a handful of real Python modules had no entry in their
folder's README, one security doc claimed the invariant checker guards 15
import orderings when it guards 14, and the git-hook README made a
reminder-only check sound like a block. This PR fixes those in the docs — the
code is the source of truth and was not touched — and shortens the docs about
5% by cutting repeated explanations and date-by-date changelogs that git
already keeps. Nothing a reader needs to run or stay safe was removed. The
first CI run caught two README sentences a test pins word-for-word; they are
back. If something reads wrong afterward, the doc-sync CI job and
doc_sync.py are the detectors; they are green on this head.

🤖 Generated with Claude Code

https://claude.ai/code/session_019bV9ZkenamEuQAMbhuTRGz

---

Generated by Claude Code

Last updated: 2026-10-13 00:30 ET

[github-actions]

PR is a complete fill of .github/PULL_REQUEST_TEMPLATE.md (every section, ticked boxes, merge order, ELI5 last, last-updated stamp, title, branch).

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-10-13T05:37:10.131508Z	8a92207	Draft marked ready

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.