From 734b6af828e495c4d502f33eb622bc0a3c997fb6 Mon Sep 17 00:00:00 2001 From: null Date: Tue, 1 Sep 2026 21:44:00 -0500 Subject: [PATCH] feat(plan): six sections every plan must name, and the files an agent reads first WORK_CYCLE.md covered only the end of the cycle. A cycle has two ends, and the same six questions kept having to be asked out loud on every piece of work. They are now mandatory in every plan, each justified by something this household has actually paid for: unified code eight copies of secrets.sh once existed here and five of seven could not detect the most common secret shape -- INCLUDING THE TEMPLATE, so every project scaffolded from it inherited a blind scanner error handling the recurring fault is the silent pass, not the crash logging an append-only log is unbounded by construction blind spots named ones get fixed landmine fixes the trap found while passing is cheapest to fix while passing hardcode little derive it, or justify the constant GUARDS.md was five sections behind the project that has been learning; 11, 12 and 13 are backported, genericised to match the template's style. 13 is the narrow form of the sixth rule, and WORK_CYCLE now cites it -- so backporting it is what makes that citation true rather than a broken reference. Also adds the three files an agent reads BEFORE it reads docs/: CLAUDE.md short, and it POINTS at DOC_TRUST_MAP rather than repeating it -- a second copy of the map is the failure that map exists to prevent. Carries the exit-code table, the commit gates, and two standing instructions: flag what looks wrong even when it is not what you were asked about, and never print a credential -- not from a file, not from a command's output, not from a config subtree "with the secrets filtered out", because that filter has failed before by matching key NAMES while the secret sat inside an object whose name was innocent .claudeignore excludes artifacts and NEVER docs/. The Command Center reads this repository's documents at a commit; a generic ignore file that sweeps "documentation" or "data" starves both the agent and the reconcile, and everything still runs, just blind .claude/settings.json deny rules in the double-slash absolute form. A tilde-style rule looks right in review and silently matches nothing. It closes the Read TOOL only -- a shell reads a file a hundred ways -- so it catches the accidental read, not the determined one scaffold.sh gains a ROOT array for the three, kept apart from DOCS so the H1-plus-status-block check stays meaningful rather than being loosened into a warning that is always wrong (GUARDS.md 5). Verified: scaffold --dry-run into a scratch repo creates 22 files including all three, with no HEADERLESS warning; doc-claims passes with 124 claimed paths, all present. Does not touch docs/architecture/scripts/secrets.sh, which carries someone else's uncommitted improvement. --- .claude/settings.json | 24 ++++ .claudeignore | 45 +++++++ CLAUDE.md | 70 +++++++++++ START-HERE-Existing-Project.md | 5 + START-HERE-New-Project.md | 5 + docs/DOC_TRUST_MAP.md | 1 + docs/WORK_CYCLE.md | 59 +++++++-- docs/architecture/GUARDS.md | 164 ++++++++++++++++++++++++++ docs/architecture/scripts/scaffold.sh | 25 +++- 9 files changed, 386 insertions(+), 12 deletions(-) create mode 100644 .claude/settings.json create mode 100644 .claudeignore create mode 100644 CLAUDE.md diff --git a/.claude/settings.json b/.claude/settings.json new file mode 100644 index 0000000..481478f --- /dev/null +++ b/.claude/settings.json @@ -0,0 +1,24 @@ +{ + "//": "Project-scoped Claude Code settings. See CLAUDE.md and docs/WORK_CYCLE.md.", + "permissions": { + "//deny": [ + "Deny wins over allow. Paths use the DOUBLE-SLASH absolute form -- a", + "tilde-style rule looks right in review and silently matches nothing,", + "which is indistinguishable from a rule that works until it matters.", + "", + "This closes the Read TOOL only. A shell can read a file a hundred ways,", + "so this catches the accidental read, not the determined one. The real", + "protection is having a sanctioned reader that answers the question", + "without returning the value -- see CLAUDE.md." + ], + "deny": [ + "Read(//**/.env)", + "Read(//**/.env.*)", + "Read(//**/*.token)", + "Read(//**/*.pem)", + "Read(//**/id_rsa*)", + "Read(//**/credentials/**)", + "Read(//**/secrets/**)" + ] + } +} diff --git a/.claudeignore b/.claudeignore new file mode 100644 index 0000000..1bc8d11 --- /dev/null +++ b/.claudeignore @@ -0,0 +1,45 @@ +# What Claude should not spend context on. +# +# EXCLUDE ARTIFACTS, NEVER THE RECORD. `docs/` is load-bearing: the Command +# Center reads this repository's documents at a commit, `DOC_TRUST_MAP.md` says +# which document owns which answer, and `docs/qa/ClaudeReport.md` is parsed for +# the sentence shown on the project screen. A generic ignore file that sweeps +# "documentation" or "data" starves both the agent and the reconcile, and the +# failure is silent -- everything still runs, it is just working blind. +# +# Same for the tracker: nothing here is a substitute for it. + +node_modules/ +.venv/ +__pycache__/ +*.pyc + +# Build output +dist/ +build/ +.next/ +*.tsbuildinfo + +# Databases and captures — large, binary, and derived +var/*.db +var/*.db-wal +var/*.db-shm +var/archive/ +*.sqlite +*.sqlite3 + +# Logs and rotations +*.log +*.log.* + +# Media that costs context and answers nothing +*.png +*.jpg +*.jpeg +*.webp +*.mp4 +*.pdf + +# Local editor state +.idea/ +.vscode/ diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..a1f1d8e --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,70 @@ +# + + + +**Read `docs/DOC_TRUST_MAP.md` before trusting anything else in `docs/`.** It +says which document owns which answer. This file is deliberately short and +points at it rather than repeating it — a second copy of the map is the failure +that map exists to prevent. + +## What this file is for + +Only what an agent needs **before** it can read anything else, and that is not +already owned by a document. If you are about to add current state, a task list, +or a summary of `docs/`, it goes in the tracker or in `docs/` respectively. + +## Exit codes are an API + + + +| Code | Means | +| --- | --- | +| `0` | did its work | +| `1` | refused for a normal, designed reason | +| `2` | **did not run** — a precondition failed. Never a pass | +| `3` | ran and the work failed | +| `99` | a lock was held; another copy is running | + +Three states, never two: `ok` / `skipped` / `failed`. An exit code alone cannot +tell "nothing to do" from "I did nothing". + +## Before you finish + +`docs/WORK_CYCLE.md` owns this and outranks anything here. In short: + +- Run this project's own guards, not just its tests: +- **Never `git add -A`.** Stage by explicit path — <`bash scripts/commit-mine.sh` + if adopted>. A shared checkout means someone else's work is one careless + `add` away from your commit. +- Update the documents this change triggered, **in the same commit as the + code**. Check each document's `Review trigger:` line. +- Close issues with the evidence that proves them: a path, a symbol, a test + name, or the command that shows it. "Done" is not a close. + +## Before you plan + +`docs/WORK_CYCLE.md` lists six sections **every plan must name**: unified code, +error handling, logging, blind spots, rolled-in landmine fixes, and +hardcode-as-little-as-possible. Read them there. + +## Two standing instructions + +**Flag anything that looks wrong, even if it is not what you were asked about.** +Most real defects are found while looking at something else. Say so, then fix it +or ask — a known bug that ships is a decision, and it is never yours to make +silently. + +**Never print a credential.** Not from a file, not from a command's output, not +from a config subtree "with the secrets filtered out" — that filter has failed +before, because it matched key *names* and the secret sat inside an object whose +name was innocent. Name the variable or the path; never the value. To compare +two secrets, compare hashes. + +## Conventions + + + +- +- +- diff --git a/START-HERE-Existing-Project.md b/START-HERE-Existing-Project.md index c87082d..14331f8 100644 --- a/START-HERE-Existing-Project.md +++ b/START-HERE-Existing-Project.md @@ -53,6 +53,11 @@ Your plan must name, separately: - anything you will DELETE, and a migrated backlog above all - which scripts this project will adopt, and which it will not - what you will deliberately leave undone, by name, and why + - the six mandatory sections from