@warnyin/sdlc 0.5.2 → 0.6.0

package/payload/hooks/validate-artifact.mjs

@@ -1,80 +1,80 @@
-#!/usr/bin/env node
-// PostToolUse hook — two token-lean feedback loops:
-//  (a) a write under sdlc/  → targeted structural validation, warnings back
-//      to the model as additionalContext (fix drift the moment it happens);
-//  (b) a source-file write matching a steering pathMatch → emit a POINTER to
-//      that steering file, once per session (a pointer, never the content —
-//      dynamic context loading at near-zero cost). Hits are journaled so the
-//      learner can expire steering that never fires.
-
-import fs from 'node:fs';
-import path from 'node:path';
-import process from 'node:process';
-import { resolveRoots, readStdinJson, activeChange, appendJournal, toPosixRel } from './_shared.mjs';
-import { parseFrontmatter } from './lib/frontmatter.mjs';
-import { matchGlob } from './lib/glob.mjs';
-import { validateChange, validateContext, formatIssues } from './lib/validate.mjs';
-
-const { sdlcRoot, projectRoot } = resolveRoots(import.meta.url);
-
-function respond(context) {
-  console.log(JSON.stringify({
-    hookSpecificOutput: { hookEventName: 'PostToolUse', additionalContext: context },
-  }));
-}
-
-function validateSdlcWrite(rel) {
-  let issues = [];
-  const changeMatch = rel.match(/^sdlc\/changes\/([^/]+)\//);
-  if (changeMatch && changeMatch[1] !== 'archive') {
-    issues = validateChange(path.join(sdlcRoot, 'changes', changeMatch[1]), {
-      specsDir: path.join(sdlcRoot, 'specs'),
-    });
-  } else if (rel.startsWith('sdlc/context/') || rel === 'sdlc/harness.md') {
-    issues = validateContext(sdlcRoot);
-  }
-  if (issues.length) {
-    respond(`[sdlc validate]\n${formatIssues(issues)}\nFix errors before moving to the next stage.`);
-  }
-}
-
-function steeringPointer(rel, sessionId) {
-  const steeringDir = path.join(sdlcRoot, 'context', 'steering');
-  if (!fs.existsSync(steeringDir)) return;
-
-  const safeSession = String(sessionId ?? '').replace(/[^A-Za-z0-9_-]/g, '') || 'nosession';
-  const seenPath = path.join(sdlcRoot, '.state', `pointers-${safeSession}.json`);
-  let seen = [];
-  try { seen = JSON.parse(fs.readFileSync(seenPath, 'utf8')); } catch { /* first hit */ }
-
-  const hits = [];
-  for (const f of fs.readdirSync(steeringDir).filter((n) => n.endsWith('.md')).sort()) {
-    const { data } = parseFrontmatter(fs.readFileSync(path.join(steeringDir, f), 'utf8'));
-    if (data.inclusion !== 'paths' || !Array.isArray(data.pathMatch)) continue;
-    if (!matchGlob(rel, data.pathMatch)) continue;
-    appendJournal(sdlcRoot, activeChange(sdlcRoot), { event: 'pointer', steering: f, file: rel });
-    if (!seen.includes(f)) hits.push(f);
-  }
-  if (!hits.length) return;
-
-  fs.mkdirSync(path.dirname(seenPath), { recursive: true });
-  fs.writeFileSync(seenPath, JSON.stringify([...seen, ...hits]));
-  respond(
-    'Steering applies to this area — read before editing further: '
-    + hits.map((f) => `sdlc/context/steering/${f}`).join(', '),
-  );
-}
-
-async function main() {
-  const input = await readStdinJson();
-  const filePath = input?.tool_input?.file_path;
-  if (!filePath || !fs.existsSync(sdlcRoot)) return;
-
-  const rel = toPosixRel(projectRoot, path.resolve(projectRoot, filePath));
-  if (!rel) return;
-
-  if (rel.startsWith('sdlc/')) validateSdlcWrite(rel);
-  else steeringPointer(rel, input?.session_id);
-}
-
-main().catch(() => process.exit(0)); // fail open
+#!/usr/bin/env node
+// PostToolUse hook — two token-lean feedback loops:
+//  (a) a write under sdlc/  → targeted structural validation, warnings back
+//      to the model as additionalContext (fix drift the moment it happens);
+//  (b) a source-file write matching a steering pathMatch → emit a POINTER to
+//      that steering file, once per session (a pointer, never the content —
+//      dynamic context loading at near-zero cost). Hits are journaled so the
+//      learner can expire steering that never fires.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import process from 'node:process';
+import { resolveRoots, readStdinJson, activeChange, appendJournal, toPosixRel } from './_shared.mjs';
+import { parseFrontmatter } from './lib/frontmatter.mjs';
+import { matchGlob } from './lib/glob.mjs';
+import { validateChange, validateContext, formatIssues } from './lib/validate.mjs';
+
+const { sdlcRoot, projectRoot } = resolveRoots(import.meta.url);
+
+function respond(context) {
+  console.log(JSON.stringify({
+    hookSpecificOutput: { hookEventName: 'PostToolUse', additionalContext: context },
+  }));
+}
+
+function validateSdlcWrite(rel) {
+  let issues = [];
+  const changeMatch = rel.match(/^sdlc\/changes\/([^/]+)\//);
+  if (changeMatch && changeMatch[1] !== 'archive') {
+    issues = validateChange(path.join(sdlcRoot, 'changes', changeMatch[1]), {
+      specsDir: path.join(sdlcRoot, 'specs'),
+    });
+  } else if (rel.startsWith('sdlc/context/') || rel === 'sdlc/harness.md') {
+    issues = validateContext(sdlcRoot);
+  }
+  if (issues.length) {
+    respond(`[sdlc validate]\n${formatIssues(issues)}\nFix errors before moving to the next stage.`);
+  }
+}
+
+function steeringPointer(rel, sessionId) {
+  const steeringDir = path.join(sdlcRoot, 'context', 'steering');
+  if (!fs.existsSync(steeringDir)) return;
+
+  const safeSession = String(sessionId ?? '').replace(/[^A-Za-z0-9_-]/g, '') || 'nosession';
+  const seenPath = path.join(sdlcRoot, '.state', `pointers-${safeSession}.json`);
+  let seen = [];
+  try { seen = JSON.parse(fs.readFileSync(seenPath, 'utf8')); } catch { /* first hit */ }
+
+  const hits = [];
+  for (const f of fs.readdirSync(steeringDir).filter((n) => n.endsWith('.md')).sort()) {
+    const { data } = parseFrontmatter(fs.readFileSync(path.join(steeringDir, f), 'utf8'));
+    if (data.inclusion !== 'paths' || !Array.isArray(data.pathMatch)) continue;
+    if (!matchGlob(rel, data.pathMatch)) continue;
+    appendJournal(sdlcRoot, activeChange(sdlcRoot), { event: 'pointer', steering: f, file: rel });
+    if (!seen.includes(f)) hits.push(f);
+  }
+  if (!hits.length) return;
+
+  fs.mkdirSync(path.dirname(seenPath), { recursive: true });
+  fs.writeFileSync(seenPath, JSON.stringify([...seen, ...hits]));
+  respond(
+    'Steering applies to this area — read before editing further: '
+    + hits.map((f) => `sdlc/context/steering/${f}`).join(', '),
+  );
+}
+
+async function main() {
+  const input = await readStdinJson();
+  const filePath = input?.tool_input?.file_path;
+  if (!filePath || !fs.existsSync(sdlcRoot)) return;
+
+  const rel = toPosixRel(projectRoot, path.resolve(projectRoot, filePath));
+  if (!rel) return;
+
+  if (rel.startsWith('sdlc/')) validateSdlcWrite(rel);
+  else steeringPointer(rel, input?.session_id);
+}
+
+main().catch(() => process.exit(0)); // fail open

package/payload/playbook/auto.md

@@ -22,6 +22,18 @@ escalation conditions — each with the choice `--auto` may pre-approve:
    pointer. A run that never gets confirmed must leave the repository unchanged.
 2. **Confirm.** One message, and it must be decidable item by item:
    - scope as you understood it, and the tier you triaged with its reason
+   - **the evidence under each scope item**: the command you ran and what it
+     returned — not the list it produced, and not your summary of it. A reader who
+     can only see the conclusion can only agree with it. Evidence goes per item:
+     one block for a whole scope buys a single yes for derivations nobody checked
+     separately. A scope you did not derive from a command says so plainly.
+   - **flag evidence that does not match the request**: name the term the request
+     used and the term you actually searched when they differ, and raise any
+     narrowing the request never asked for (a folder pattern, a naming convention)
+     as its own refusable item.
+   - **an exclusion made on an empty result names the pattern searched.** Finding
+     nothing is a claim about your pattern, not a fact about the candidate — a
+     convention you did not anticipate looks exactly like an absence.
    - every ambiguity, each with the assumption you intend to act on
    - one line per row of the escalation table above, each stating the choice you
      want pre-approved, and each refusable on its own. For the ship row, name the

package/payload/playbook/context.md

@@ -1,26 +1,26 @@
-# Context engineering
-
-Six context types: instructions, knowledge, memory, examples, tools, guardrails.
-The design decision is WHERE each lives: static (always loaded, expensive) vs
-dynamic (loaded on demand, cheap). That boundary is versioned code, reviewed in PRs.
-
-## Static (injected every session by the SessionStart hook, hard cap 60 lines total)
-- `sdlc/context/constitution.md` (≤30) — hard rules + stack facts only.
-- `sdlc/context/steering/*.md` with `inclusion: always` — should be rare.
-- One pointer line to the active change.
-
-## Dynamic (loaded only when needed)
-- `inclusion: paths` steering — the PostToolUse hook emits a POINTER when an edited
-  file matches `pathMatch`; you then read the file. Pointers cost ~1 line, not 40.
-- `inclusion: manual` — read only when a playbook or user names it.
-- `inclusion: agent` — subagents load it themselves; the main loop never pays for it.
-- Living specs — read the `## Purpose` header first; open the full spec only for
-  capabilities your change touches.
-- Playbooks — each command reads exactly one playbook file.
-
-## Budget rules
-- Always-budget (constitution + always-steering) ≤ 60 lines. Validator-enforced.
-- Adding an always rule requires removing one, or demoting something to `paths`.
-- `/sdlc:observe` reports steering that never fires — expire or demote it.
-- A `compact` event in the journal means context overflowed: treat as a defect,
-  find the resident artifact that caused it.
+# Context engineering
+
+Six context types: instructions, knowledge, memory, examples, tools, guardrails.
+The design decision is WHERE each lives: static (always loaded, expensive) vs
+dynamic (loaded on demand, cheap). That boundary is versioned code, reviewed in PRs.
+
+## Static (injected every session by the SessionStart hook, hard cap 60 lines total)
+- `sdlc/context/constitution.md` (≤30) — hard rules + stack facts only.
+- `sdlc/context/steering/*.md` with `inclusion: always` — should be rare.
+- One pointer line to the active change.
+
+## Dynamic (loaded only when needed)
+- `inclusion: paths` steering — the PostToolUse hook emits a POINTER when an edited
+  file matches `pathMatch`; you then read the file. Pointers cost ~1 line, not 40.
+- `inclusion: manual` — read only when a playbook or user names it.
+- `inclusion: agent` — subagents load it themselves; the main loop never pays for it.
+- Living specs — read the `## Purpose` header first; open the full spec only for
+  capabilities your change touches.
+- Playbooks — each command reads exactly one playbook file.
+
+## Budget rules
+- Always-budget (constitution + always-steering) ≤ 60 lines. Validator-enforced.
+- Adding an always rule requires removing one, or demoting something to `paths`.
+- `/sdlc:observe` reports steering that never fires — expire or demote it.
+- A `compact` event in the journal means context overflowed: treat as a defect,
+  find the resident artifact that caused it.

package/payload/playbook/converge.md

@@ -1,19 +1,19 @@
-# /sdlc:converge [capability] — spec ↔ code drift (Maintenance)
-
-Living specs are only useful while they are true. Converge closes the gap.
-
-1. Scope: the named capability, or the ones `/sdlc:observe` flagged.
-2. For each requirement in `sdlc/specs/<capability>/spec.md`, check the code
-   actually behaves that way (read the relevant code; run targeted tests where
-   cheap). Three outcomes per requirement:
-   - **true** — nothing to do.
-   - **code drifted** — behavior no longer matches the spec.
-   - **spec stale** — the spec describes behavior nobody wants anymore.
-3. Report the diff table in chat (requirement · outcome · evidence file:line).
-4. For every drift/stale finding the user wants fixed, open ONE change via
-   /sdlc:new whose Delta uses MODIFIED/REMOVED against the exact requirement
-   names — converge itself NEVER edits specs or code directly.
-5. If a recent rule/playbook edit correlates with worse flywheel metrics
-   (observe shows it), propose the revert here as a change too.
-
-Read-only except for creating proposed change folders.
+# /sdlc:converge [capability] — spec ↔ code drift (Maintenance)
+
+Living specs are only useful while they are true. Converge closes the gap.
+
+1. Scope: the named capability, or the ones `/sdlc:observe` flagged.
+2. For each requirement in `sdlc/specs/<capability>/spec.md`, check the code
+   actually behaves that way (read the relevant code; run targeted tests where
+   cheap). Three outcomes per requirement:
+   - **true** — nothing to do.
+   - **code drifted** — behavior no longer matches the spec.
+   - **spec stale** — the spec describes behavior nobody wants anymore.
+3. Report the diff table in chat (requirement · outcome · evidence file:line).
+4. For every drift/stale finding the user wants fixed, open ONE change via
+   /sdlc:new whose Delta uses MODIFIED/REMOVED against the exact requirement
+   names — converge itself NEVER edits specs or code directly.
+5. If a recent rule/playbook edit correlates with worse flywheel metrics
+   (observe shows it), propose the revert here as a change too.
+
+Read-only except for creating proposed change folders.

package/payload/playbook/init.md

@@ -1,22 +1,22 @@
-# /sdlc:init — configure the harness (run once per project)
-
-The only planned blocking human gate in the framework: the human approves the
-policy the AI will then drive under.
-
-1. Read `sdlc/config.yaml`, the repo README, manifest files (package.json etc.),
-   and skim the top-level structure. Do NOT deep-read the codebase.
-2. Interview the user briefly (≤6 questions): what the project is, hard rules the
-   agent must never break, test command, risk areas (security/payments/data-loss),
-   and how autonomous shipping should be (adjusts `## Autonomy policy`).
-3. Open the gate: `node sdlc/.hooks/journal.mjs open-steer`, then write:
-   - `sdlc/context/constitution.md` — replace template placeholders; ≤30 lines;
-     SHALL/SHALL NOT rules only, stack facts ≤3 lines.
-   - `sdlc/harness.md` — fill tools, test command, sandbox notes; adjust the
-     routing, triage, and Autonomy policy tables to this project.
-   - 0–3 steering seeds in `sdlc/context/steering/` for areas with real
-     conventions (prefer `inclusion: paths`; `always` needs strong justification).
-4. Run `npx @warnyin/sdlc validate` — fix every error.
-5. Show the user constitution + harness verbatim; iterate until approved.
-6. Close the gate: `node sdlc/.hooks/journal.mjs close`.
-
-Output: approved constitution + harness. No change folder is created here.
+# /sdlc:init — configure the harness (run once per project)
+
+The only planned blocking human gate in the framework: the human approves the
+policy the AI will then drive under.
+
+1. Read `sdlc/config.yaml`, the repo README, manifest files (package.json etc.),
+   and skim the top-level structure. Do NOT deep-read the codebase.
+2. Interview the user briefly (≤6 questions): what the project is, hard rules the
+   agent must never break, test command, risk areas (security/payments/data-loss),
+   and how autonomous shipping should be (adjusts `## Autonomy policy`).
+3. Open the gate: `node sdlc/.hooks/journal.mjs open-steer`, then write:
+   - `sdlc/context/constitution.md` — replace template placeholders; ≤30 lines;
+     SHALL/SHALL NOT rules only, stack facts ≤3 lines.
+   - `sdlc/harness.md` — fill tools, test command, sandbox notes; adjust the
+     routing, triage, and Autonomy policy tables to this project.
+   - 0–3 steering seeds in `sdlc/context/steering/` for areas with real
+     conventions (prefer `inclusion: paths`; `always` needs strong justification).
+4. Run `npx @warnyin/sdlc validate` — fix every error.
+5. Show the user constitution + harness verbatim; iterate until approved.
+6. Close the gate: `node sdlc/.hooks/journal.mjs close`.
+
+Output: approved constitution + harness. No change folder is created here.

package/payload/playbook/observe.md

@@ -1,20 +1,20 @@
-# /sdlc:observe — cost, flow, and drift report
-
-1. Run `npx @warnyin/sdlc observe --json` and render it for the human. Do not
-   recompute anything the CLI already computed.
-2. Report, in this order (skip empty sections):
-   - **Pending digests** — archived changes whose digest the human has not been
-     shown yet (learner proposals awaiting a decision).
-   - **Cost** — tokens/cost per active + recent change; retry waste (tokens spent
-     after the first verify fail).
-   - **Flow** — lead time per shipped change and per-phase breakdown (created →
-     contracted → built → verified → shipped timestamps from the journal);
-     AI-time vs wait-time; first-pass success trend.
-   - **Residency** — always-loaded lines vs the 60 budget.
-   - **Drift flags** — steering never hit by a pointer, rules never triggering a
-     guard event, `compact` events (context overflow = a defect), specs touched
-     by many changes (converge candidates).
-3. For each flag, offer the one-line fix (`/sdlc:steer` demotion, `/sdlc:converge`
-   on a capability, cap adjustment) — recommend, never auto-apply here.
-
-Read-only: this command changes nothing.
+# /sdlc:observe — cost, flow, and drift report
+
+1. Run `npx @warnyin/sdlc observe --json` and render it for the human. Do not
+   recompute anything the CLI already computed.
+2. Report, in this order (skip empty sections):
+   - **Pending digests** — archived changes whose digest the human has not been
+     shown yet (learner proposals awaiting a decision).
+   - **Cost** — tokens/cost per active + recent change; retry waste (tokens spent
+     after the first verify fail).
+   - **Flow** — lead time per shipped change and per-phase breakdown (created →
+     contracted → built → verified → shipped timestamps from the journal);
+     AI-time vs wait-time; first-pass success trend.
+   - **Residency** — always-loaded lines vs the 60 budget.
+   - **Drift flags** — steering never hit by a pointer, rules never triggering a
+     guard event, `compact` events (context overflow = a defect), specs touched
+     by many changes (converge candidates).
+3. For each flag, offer the one-line fix (`/sdlc:steer` demotion, `/sdlc:converge`
+   on a capability, cap adjustment) — recommend, never auto-apply here.
+
+Read-only: this command changes nothing.

package/payload/playbook/principles.md

@@ -1,28 +1,28 @@
-# Principles
-
-## Factory model
-Your output is the system that produces code — specs, contracts, gates, feedback loops,
-guardrails — not the code itself. Give agents success criteria, not step-by-step
-instructions, then let them iterate. Humans set policy once (`/sdlc:init`) and read
-ship digests asynchronously; they are interrupted only by policy-listed exceptions.
-
-## Economics (CapEx / OpEx)
-Configuration (constitution, harness, steering, contracts) is CapEx: paid once, reviewed
-like code. Every resident line of context is OpEx paid in every turn. Therefore:
-- Every mandatory artifact has a stated reason and a line cap (see template comments).
-- No artifact may restate another; deltas are merged mechanically, never re-narrated.
-- Retry loops are the expensive failure mode — contracts up front buy first-pass success.
-
-## Anti-garbage rules
-- Optional artifacts (design section, evals for standard tier) exist only on signal.
-- If a section would be empty, delete the section — never keep placeholder prose.
-- The learner may only ADD an always-loaded rule by displacing an old one (fixed budget).
-- Machine data (journals, state, learning stats) never lives in prose files.
-
-## Verification stance
-Tests verify the deterministic; evals verify trajectory and quality. Both are written
-before code — together they are the contract with the AI. "Seems to work" is not a gate.
-
-## Minimalism
-Prefer: do nothing → stdlib → existing dependency → smallest new code. Never cut:
-trust-boundary validation, data-loss handling, security controls, the contract itself.
+# Principles
+
+## Factory model
+Your output is the system that produces code — specs, contracts, gates, feedback loops,
+guardrails — not the code itself. Give agents success criteria, not step-by-step
+instructions, then let them iterate. Humans set policy once (`/sdlc:init`) and read
+ship digests asynchronously; they are interrupted only by policy-listed exceptions.
+
+## Economics (CapEx / OpEx)
+Configuration (constitution, harness, steering, contracts) is CapEx: paid once, reviewed
+like code. Every resident line of context is OpEx paid in every turn. Therefore:
+- Every mandatory artifact has a stated reason and a line cap (see template comments).
+- No artifact may restate another; deltas are merged mechanically, never re-narrated.
+- Retry loops are the expensive failure mode — contracts up front buy first-pass success.
+
+## Anti-garbage rules
+- Optional artifacts (design section, evals for standard tier) exist only on signal.
+- If a section would be empty, delete the section — never keep placeholder prose.
+- The learner may only ADD an always-loaded rule by displacing an old one (fixed budget).
+- Machine data (journals, state, learning stats) never lives in prose files.
+
+## Verification stance
+Tests verify the deterministic; evals verify trajectory and quality. Both are written
+before code — together they are the contract with the AI. "Seems to work" is not a gate.
+
+## Minimalism
+Prefer: do nothing → stdlib → existing dependency → smallest new code. Never cut:
+trust-boundary validation, data-loss handling, security controls, the contract itself.

package/payload/playbook/routing.md

@@ -1,19 +1,19 @@
-# Model routing
-
-Generic tiers only — the harness adapter maps them to real models
-(Claude Code agents: cheap→haiku, balanced→sonnet, deepest→opus).
-
-| Task kind | Tier | Why |
-|---|---|---|
-| requirements shaping, architecture, deep design | deepest | judgment-heavy, small volume |
-| standard implementation (sdlc-builder) | balanced | quality/cost sweet spot |
-| test generation (sdlc-contractor) | cheap | mechanical from the contract table |
-| eval judging (sdlc-evaluator) | cheap | rubric scoring, high volume |
-| review panel passes | cheap–balanced | parallel, bounded scope |
-| learning distillation (sdlc-learner) | cheap | summarization over journals |
-
-Rules:
-- Task lines in change.md may carry `[tier:cheap|balanced|deepest]`; default = balanced.
-- Never send a mechanical task to deepest "to be safe" — that is the waste the
-  routing table exists to prevent.
-- Escalate one tier only after a concrete failure at the current tier (journal it).
+# Model routing
+
+Generic tiers only — the harness adapter maps them to real models
+(Claude Code agents: cheap→haiku, balanced→sonnet, deepest→opus).
+
+| Task kind | Tier | Why |
+|---|---|---|
+| requirements shaping, architecture, deep design | deepest | judgment-heavy, small volume |
+| standard implementation (sdlc-builder) | balanced | quality/cost sweet spot |
+| test generation (sdlc-contractor) | cheap | mechanical from the contract table |
+| eval judging (sdlc-evaluator) | cheap | rubric scoring, high volume |
+| review panel passes | cheap–balanced | parallel, bounded scope |
+| learning distillation (sdlc-learner) | cheap | summarization over journals |
+
+Rules:
+- Task lines in change.md may carry `[tier:cheap|balanced|deepest]`; default = balanced.
+- Never send a mechanical task to deepest "to be safe" — that is the waste the
+  routing table exists to prevent.
+- Escalate one tier only after a concrete failure at the current tier (journal it).

package/payload/playbook/rules-card.md

@@ -1,16 +1,16 @@
-# sdlc rules card
-<!-- ≤40 lines · embedded verbatim in non-Claude tool adapters; Claude gets the same rules enforced by hooks. -->
-
-- Work flows through `sdlc/changes/<id>/change.md`: new → [design] → contract → build → verify → [review] → ship.
-- NEVER edit `sdlc/specs/**` or `sdlc/changes/archive/**` by hand. Living specs change only
-  via a change's `## Delta:` section, merged by `npx @warnyin/sdlc archive <id>` at ship.
-- NEVER hand-edit `journal.ndjson` or `sdlc/.state/**` — they are machine-owned.
-- Write tests + evals (`contract/`) BEFORE code. No implementation while status is `new`.
-- Ambiguity: make the safest assumption and record it under `## Assumptions`; use
-  `[NEEDS CLARIFICATION: q]` only for facts you cannot obtain — resolve all before contract.
-- Respect line caps written in each template comment; run `npx @warnyin/sdlc validate <id>`
-  before claiming any gate passed — a red validator means the gate did NOT pass.
-- Constitution edits go through /sdlc:steer only; always-loaded context ≤ 60 lines total.
-- Verify = real test run + eval rubric. Max 3 fix rounds, then escalate to the human.
-- Hard-floor (security, payments, data-loss, irreversible): tier = deep, human approves ship.
-- Before editing an area, read any steering file whose `pathMatch` covers it.
+# sdlc rules card
+<!-- ≤40 lines · embedded verbatim in non-Claude tool adapters; Claude gets the same rules enforced by hooks. -->
+
+- Work flows through `sdlc/changes/<id>/change.md`: new → [design] → contract → build → verify → [review] → ship.
+- NEVER edit `sdlc/specs/**` or `sdlc/changes/archive/**` by hand. Living specs change only
+  via a change's `## Delta:` section, merged by `npx @warnyin/sdlc archive <id>` at ship.
+- NEVER hand-edit `journal.ndjson` or `sdlc/.state/**` — they are machine-owned.
+- Write tests + evals (`contract/`) BEFORE code. No implementation while status is `new`.
+- Ambiguity: make the safest assumption and record it under `## Assumptions`; use
+  `[NEEDS CLARIFICATION: q]` only for facts you cannot obtain — resolve all before contract.
+- Respect line caps written in each template comment; run `npx @warnyin/sdlc validate <id>`
+  before claiming any gate passed — a red validator means the gate did NOT pass.
+- Constitution edits go through /sdlc:steer only; always-loaded context ≤ 60 lines total.
+- Verify = real test run + eval rubric. Max 3 fix rounds, then escalate to the human.
+- Hard-floor (security, payments, data-loss, irreversible): tier = deep, human approves ship.
+- Before editing an area, read any steering file whose `pathMatch` covers it.

package/payload/playbook/ship.md

@@ -1,35 +1,35 @@
-# /sdlc:ship <id> — merge, archive, learn, digest
-
-Precondition: `status: verified` (+ review passed when it ran).
-
-1. **Policy check** (`sdlc/harness.md § Autonomy policy`): if this change is NOT
-   auto-shippable (deep/hard-floor), show the human a 5-line summary (why, delta
-   heads, verify result, cost so far) and wait for approval. Otherwise proceed.
-2. Open the gate and archive mechanically:
-   `node sdlc/.hooks/journal.mjs open-ship <id>`
-   `npx @warnyin/sdlc archive <id>`
-   (validates --strict, merges every Delta into `sdlc/specs/`, promotes evals,
-   stamps `status: shipped`, moves the folder to `changes/archive/<date>-<id>/`).
-   Any `⚠ MODIFIED Requirement …` line means the new body carried away a scenario
-   the spec still promised: confirm it was intended and name it in the digest.
-3. **Learn** — delegate to `sdlc-learner` (cheap) with the archived change.md +
-   its journal.ndjson. It proposes ≤3 items: add-rule (with evidence pointer) /
-   expire-or-demote (rule or steering that never fired) / harness tweak.
-   Apply reductions and demotions immediately (they always save tokens).
-   Additions to always-loaded context are NOT applied — list them in the digest.
-4. **Digest** — write `sdlc/changes/archive/<date>-<id>/digest.md` (≤15 lines):
-   what shipped, spec deltas merged, assumptions made, verify rounds, tokens/cost
-   (from journal `session` events), learner proposals awaiting the human.
-   When any verify or review note carries `mode=solo`, the digest SHALL say which
-   outcomes were self-produced. A reader months from now cannot otherwise tell a
-   panel's verdict from the author's own.
-   When any `escalation` event carries `preauth=yes`, the digest SHALL list those
-   pre-authorized escalations by condition — the points where a human would normally
-   have stood and, this run, did not.
-5. Close the gate: `node sdlc/.hooks/journal.mjs close`. Tell the user in one
-   line: shipped + where the digest is.
-
-The digest is the async human touchpoint — reviewable and revertible later.
-
-`--auto`: do this stage, then continue to ship under `auto.md`'s unattended
-mode — gather, confirm once, run. The stage still does its own work first.
+# /sdlc:ship <id> — merge, archive, learn, digest
+
+Precondition: `status: verified` (+ review passed when it ran).
+
+1. **Policy check** (`sdlc/harness.md § Autonomy policy`): if this change is NOT
+   auto-shippable (deep/hard-floor), show the human a 5-line summary (why, delta
+   heads, verify result, cost so far) and wait for approval. Otherwise proceed.
+2. Open the gate and archive mechanically:
+   `node sdlc/.hooks/journal.mjs open-ship <id>`
+   `npx @warnyin/sdlc archive <id>`
+   (validates --strict, merges every Delta into `sdlc/specs/`, promotes evals,
+   stamps `status: shipped`, moves the folder to `changes/archive/<date>-<id>/`).
+   Any `⚠ MODIFIED Requirement …` line means the new body carried away a scenario
+   the spec still promised: confirm it was intended and name it in the digest.
+3. **Learn** — delegate to `sdlc-learner` (cheap) with the archived change.md +
+   its journal.ndjson. It proposes ≤3 items: add-rule (with evidence pointer) /
+   expire-or-demote (rule or steering that never fired) / harness tweak.
+   Apply reductions and demotions immediately (they always save tokens).
+   Additions to always-loaded context are NOT applied — list them in the digest.
+4. **Digest** — write `sdlc/changes/archive/<date>-<id>/digest.md` (≤15 lines):
+   what shipped, spec deltas merged, assumptions made, verify rounds, tokens/cost
+   (from journal `session` events), learner proposals awaiting the human.
+   When any verify or review note carries `mode=solo`, the digest SHALL say which
+   outcomes were self-produced. A reader months from now cannot otherwise tell a
+   panel's verdict from the author's own.
+   When any `escalation` event carries `preauth=yes`, the digest SHALL list those
+   pre-authorized escalations by condition — the points where a human would normally
+   have stood and, this run, did not.
+5. Close the gate: `node sdlc/.hooks/journal.mjs close`. Tell the user in one
+   line: shipped + where the digest is.
+
+The digest is the async human touchpoint — reviewable and revertible later.
+
+`--auto`: do this stage, then continue to ship under `auto.md`'s unattended
+mode — gather, confirm once, run. The stage still does its own work first.

package/payload/playbook/steer.md

@@ -1,21 +1,21 @@
-# /sdlc:steer — manage the static/dynamic boundary
-
-The ONLY sanctioned way to edit always-loaded context.
-
-1. `node sdlc/.hooks/journal.mjs open-steer`
-2. Apply the requested edits:
-   - New knowledge → a steering file with the LEAST resident inclusion mode that
-     works: `agent` > `manual` > `paths` > `always` (always needs justification).
-   - Constitution edits: SHALL/SHALL NOT lines only. If the always-budget
-     (60 lines) would overflow, something must be demoted or deleted first —
-     name the displaced line explicitly.
-3. Hygiene pass (do it every time, it is 30 seconds):
-   - `/sdlc:observe` data — steering never pointer-hit across the last N changes
-     → propose demote (`paths`→`manual`) or delete.
-   - Rules with no guard/journal evidence of ever mattering → propose expiry.
-   - Apply what the user agrees to (reductions may be applied without asking).
-4. `npx @warnyin/sdlc validate` — the always-budget check must be green.
-5. `node sdlc/.hooks/journal.mjs close`
-
-Learning direction is one-way by design: content flows from always → paths →
-manual → deleted as evidence accumulates. Getting leaner is the success metric.
+# /sdlc:steer — manage the static/dynamic boundary
+
+The ONLY sanctioned way to edit always-loaded context.
+
+1. `node sdlc/.hooks/journal.mjs open-steer`
+2. Apply the requested edits:
+   - New knowledge → a steering file with the LEAST resident inclusion mode that
+     works: `agent` > `manual` > `paths` > `always` (always needs justification).
+   - Constitution edits: SHALL/SHALL NOT lines only. If the always-budget
+     (60 lines) would overflow, something must be demoted or deleted first —
+     name the displaced line explicitly.
+3. Hygiene pass (do it every time, it is 30 seconds):
+   - `/sdlc:observe` data — steering never pointer-hit across the last N changes
+     → propose demote (`paths`→`manual`) or delete.
+   - Rules with no guard/journal evidence of ever mattering → propose expiry.
+   - Apply what the user agrees to (reductions may be applied without asking).
+4. `npx @warnyin/sdlc validate` — the always-budget check must be green.
+5. `node sdlc/.hooks/journal.mjs close`
+
+Learning direction is one-way by design: content flows from always → paths →
+manual → deleted as evidence accumulates. Getting leaner is the success metric.