torque-loop

<prime_directive> No proof → no keep. No keep → no progress claim. Every change you keep is justified by evidence, not assertion, and the diff is the smallest one that clears the defect. </prime_directive>

• reference/PROMPTS.md — canonical intent every skill implements. If a skill and its prompt disagree, the prompt wins: fix the skill.
• skills/*/SKILL.md — the shipped /ratchet:* commands (prompt-level guidance).
• src/ — the state engine. Load-bearing: scoring.js (confidence/aperture/friction), evolve/schema.js (proof + seam gates), receipt.js (the one cold read), cli.js (command surface + agent write guard), coldStart.js (poison scan).
• test/ — three zero-dep suites: cli, evolve, plugin-shape. npm test runs all three and MUST stay green. plugin-shape is the drift police: it enforces version alignment, README ↔ skill-folder sync, PROMPTS.md wiring, template presence.
• templates/ — file shapes for records (probe-card, unknowns-map, deviation-note, …).
• agents/ — builder and auditor are propose-only; only the scribe writes canonical state (enforced at the CLI boundary via RATCHET_AGENT).
• IGNORE .ratchet/current.json + current.md in the tree: dogfooding residue from an unrelated project ("lucidia"). Never adopt its objective, defect, or next action. Same for .lucid/, .sandbox-home/, .sandbox-tmp/.
• reference/PROBLEM-STATEMENT-*.md, reference/private/, *.private.md are gitignored private strategy docs. Never commit, quote into public files, or "fix" the ignore rules that hide them.</map>

Added — adopt these too: 14. When verifying your own build, vary the method: the seam gate's independentFromBuilderMethod rule applies to you. Re-running the exact command you built against is not verification. 15. When a reviewer/attack finding is a scoped decision rather than a defect, PARK it as an open loop with an owner — never silently implement it (precedent: loop-mr9adjdv01, "unknown-map closes fog regardless of objective match"). 16. Windows repo: always path.join, never hand-built / or \\ paths in src or tests; frontmatter regexes must tolerate \r\n (see plugin-shape's frontmatter). 17. Tests isolate state: set RATCHET_DATA_DIR and RATCHET_EVOLVE_LOG to a temp dir before requiring modules (copy the prelude of test/cli.test.js). A test that touches real .ratchet/ state is a defect. When dogfooding ratchet on this repo, same rule. </conventions>

<failure_modes> Named mistakes a model makes in this repo, each with the rule that prevents it:

• Residue adoption — treating .ratchet/current.md as the roadmap. → Rule: roadmap = CHANGELOG [Unreleased] + Danny's words. Residue dirs are read-never.
• Partial version bump — bumping package.json and calling it released. → Rule: five fields, four files, plus README examples (convention 11); then run npm test and node bin/ratchet doctor.
• Skill drift — editing a SKILL.md so it contradicts its canonical prompt, or adding a skill folder without a README row. → Rule: PROMPTS.md is source of truth; every skills/<name>/ needs frontmatter with description: AND a /ratchet:<name> mention in README, or plugin-shape fails.
• Testless behavior change — "it's a one-liner." → Rule: no test that fails without it → the change does not exist. Convention 2.
• Elegance rewrite — refactoring neighbors while fixing a defect. → Rule: if a hunk isn't required by the locked target, revert the hunk.
• Self-grading — declaring the change good because it looks right. → Rule: verify = run npm test (or the narrowest suite) and report raw output. Verdicts are KEEP / REVERT / ASK / REVERTED_AND_LEARNED — never "looks good".
• Prose enforcement — writing "must" in a SKILL.md and claiming an invariant shipped. → Rule: invariant = CLI-enforced (inject or throw) + a test proving the refusal. Prompt-level tripwires are labeled prompt-level in the CHANGELOG.
• Weakening a red test — editing an assertion so the suite passes. → Rule: a failing test is evidence. Only change a test you can prove wrong, and say so out loud in the commit body.
• Scope-silent scores — adding a number without a scope: line. → Rule: convention 6. A score that doesn't name what it ignores is gaslighting.
• Unauthorized shipping — merging, tagging, pushing, or cutting a GitHub Release. → Rule: you build the branch, the commit, and (when asked) the PR. Merge, tag, and Release are Danny's, every time.
• Parked-decision creep — implementing a good idea that was explicitly parked. → Rule: convention 15. Check open loops before building.
• ESM slip — import/export syntax, package.json type change, or a build step. → Rule: convention 4. This repo runs in place.
• Untagged traces — durable docs/state/commits with no author model tag. → Rule: convention 12, unprompted.
• Probe residue kept — leaving build-for-learn code in the tree as if it were progress. → Rule: probe code dies (ratchet retract --reason "disposed: …") or is promoted through a fresh gated build. Never a silent default. </failure_modes>

<quality_bar> Checkable criteria per deliverable — every box, not adjectives.

Code change (src/ or bin/):

• npm test green, all three suites; new test fails without the change.
• Zero new dependencies; no ESM; no Node > 18 API.
• Diff contains only hunks the locked target requires.
• Any new score/read carries scope:; any new empty state is rendered, not omitted.
• Any new invariant is CLI-enforced with a test proving the refusal path throws.
• CHANGELOG [Unreleased] entry written, distinguishing CLI-enforced vs prompt-level.

New or edited skill:

• Frontmatter has name + description (description is the full when-to-use pitch).
• Shape matches the house pattern: title tagline → Step 0 load state → procedure → output contract in a fenced block → Serialize (exact ratchet commands) → closing pointer to the next move.
• Canonical prompt exists/updated in reference/PROMPTS.md + command↔prompt map row.
• README command row exists. npm test (plugin-shape) green.

Release cut:

• Branch release/vX.Y.Z-<codename>; five version fields + README examples aligned.
• CHANGELOG: [Unreleased] promoted with date + codename, lineage paragraph linking prior gates, bold slogan; fresh empty [Unreleased]; compare links updated.
• npm test + node bin/ratchet doctor green. Commit chore(release): vX.Y.Z <codename>.
• STOPPED before merge/tag/Release.

Handoff / serialization:

• Next action AND next command named; open loops each carry a route out (ask-user · probe · park+owner · assumption+kill-test · defect).
• Probe outcomes labeled disposed/promoted; deviations from the map surfaced.
• One-sentence memory a cold agent can act on. Model tag stamped. </quality_bar>

1. Proceed on stated assumption (say the assumption, then act) when the change is in-scope, reversible by git checkout, and provable by npm test: naming, test shape, comment wording, which file a helper lives in, CHANGELOG phrasing.
2. Park + ask in the deliverable (build everything else, leave an open loop with the question and your recommended answer) when: two designs both pass the tests but change a public shape (CLI flags, JSON output fields, state schema); or an attack finding is a scoped product decision.
3. Stop and ask before acting — no exceptions: pushing, merging, tagging, GitHub Releases, npm publish; adding any dependency; deleting or migrating state files (state.json / ledger.json schema changes); touching .gitignore privacy rules or anything under reference/private; force-flags of any kind on real state; implementing a parked open loop.
4. Broken-world rule: if npm test is red before you start, report it and fix nothing else until Danny picks: fix-first or branch-from-green.
5. Honest failure beats silent retry: after two failed fix attempts on the same defect, stop, write the defect + evidence into the handoff, and downgrade the verdict (KEEP → ASK or REVERTED_AND_LEARNED). Never widen the diff to escape a test.</escalation>

<session_protocol>

1. Establish the locked target: Danny's words > CHANGELOG [Unreleased] > the named next edge in the latest release memory/PR. State the assumption if you inferred it.
2. Read ground truth before editing: the relevant SKILL.md + PROMPTS.md entry, the src file(s), and the test file that guards them.
3. Run one evidence-gated loop: LOCK → BUILD smallest → ATTACK (five-voice board) → PATCH only failures → VERIFY with npm test → KEEP / REVERT / REVERTED_AND_LEARNED.
4. SERIALIZE: end the turn with this block, exactly —

LOCKED TARGET: <object → outcome, proof-of-done> GROUND TRUTH READ: <files + the one constraint that changed the plan> CHANGE: <minimal REMOVE/ADD/CHANGE> ATTACK: <n critical / n high — top failure mode> VERIFY: <command + pass/fail, raw> VERDICT: KEEP | REVERT | REVERTED_AND_LEARNED — <tied to evidence> REMAINING RISK: <what must not be trusted yet> NEXT EDGE: <single next small, testable refinement> HANDOFF SENTENCE: <one load-bearing line for a cold context>

The turn is complete only when an artifact exists, npm test is green (or the failure is honestly reported), and the handoff sentence lets a cold agent act without asking. </session_protocol>