@warnyin/sdlc 0.1.0

package/payload/hooks/_shared.mjs

@@ -0,0 +1,141 @@
+// Shared plumbing for installed hooks. This file lives at
+// <project>/sdlc/.hooks/_shared.mjs with lib/ as a sibling directory.
+// Every hook must be fail-open: on any unexpected condition, exit 0 silently
+// so the harness is never blocked by our tooling.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import process from 'node:process';
+import { fileURLToPath } from 'node:url';
+
+export function resolveRoots(importMetaUrl) {
+  const hooksDir = path.dirname(fileURLToPath(importMetaUrl));
+  const sdlcRoot = path.dirname(hooksDir);
+  const projectRoot = path.dirname(sdlcRoot);
+  return { hooksDir, sdlcRoot, projectRoot };
+}
+
+export async function readStdinJson() {
+  try {
+    let data = '';
+    for await (const chunk of process.stdin) data += chunk;
+    return data.trim() ? JSON.parse(data) : null;
+  } catch {
+    return null;
+  }
+}
+
+// Resolve symlinks on the deepest EXISTING ancestor, then re-attach the tail.
+// Needed because import.meta.url is symlink-resolved while tool file_paths may
+// arrive through a symlink (/tmp → /private/tmp on macOS).
+export function realResolve(p) {
+  let cur = path.resolve(p);
+  const tail = [];
+  while (!fs.existsSync(cur)) {
+    const parent = path.dirname(cur);
+    if (parent === cur) break;
+    tail.unshift(path.basename(cur));
+    cur = parent;
+  }
+  try { cur = fs.realpathSync.native(cur); } catch { /* keep as-is */ }
+  return tail.length ? path.join(cur, ...tail) : cur;
+}
+
+export function toPosixRel(projectRoot, absPath) {
+  const rel = path.relative(realResolve(projectRoot), realResolve(absPath));
+  if (rel.startsWith('..')) return null;
+  return rel.split(path.sep).join('/');
+}
+
+// Lexical (no-symlink-resolution) relative path: what the path CLAIMS to be.
+// Tried against both the raw and the realpathed project root so /tmp-style
+// root symlinks don't break matching. Guards must compare this against
+// toPosixRel — a divergence means a symlink sits inside the project.
+export function lexicalPosixRel(projectRoot, absPath) {
+  const abs = path.resolve(absPath);
+  const realRoot = realResolve(projectRoot);
+  for (const base of [path.resolve(projectRoot), realRoot]) {
+    const rel = path.relative(base, abs);
+    if (rel && !rel.startsWith('..') && !path.isAbsolute(rel)) {
+      return rel.split(path.sep).join('/');
+    }
+  }
+  // Root-level symlinks (/tmp → /private/tmp): find the SHALLOWEST ancestor of
+  // abs whose realpath IS the project root; the remaining tail is the lexical
+  // claim. In-project symlinks are deliberately not resolved here.
+  const segs = abs.split(path.sep);
+  for (let i = 1; i < segs.length; i++) {
+    const ancestor = segs.slice(0, i).join(path.sep) || path.sep;
+    let real;
+    try { real = fs.realpathSync.native(ancestor); } catch { continue; }
+    if (real === realRoot) {
+      const tail = segs.slice(i).join('/');
+      return tail || null;
+    }
+  }
+  return null;
+}
+
+// Gate state written by `journal.mjs open-<phase>` — {phase, change?, expires}.
+export function readPhase(sdlcRoot) {
+  try {
+    const raw = fs.readFileSync(path.join(sdlcRoot, '.state', 'phase.json'), 'utf8');
+    const phase = JSON.parse(raw);
+    if (phase.expires && Date.parse(phase.expires) < Date.now()) return null;
+    return phase;
+  } catch {
+    return null;
+  }
+}
+
+export function writePhase(sdlcRoot, phase, ttlMinutes = 30) {
+  const stateDir = path.join(sdlcRoot, '.state');
+  fs.mkdirSync(stateDir, { recursive: true });
+  const payload = { ...phase, expires: new Date(Date.now() + ttlMinutes * 60_000).toISOString() };
+  fs.writeFileSync(path.join(stateDir, 'phase.json'), JSON.stringify(payload));
+  return payload;
+}
+
+export function clearPhase(sdlcRoot) {
+  fs.rmSync(path.join(sdlcRoot, '.state', 'phase.json'), { force: true });
+}
+
+// Active change: explicit .state/active.json first, else the most recently
+// modified changes/*/change.md.
+export function activeChange(sdlcRoot) {
+  try {
+    const explicit = JSON.parse(fs.readFileSync(path.join(sdlcRoot, '.state', 'active.json'), 'utf8'));
+    if (explicit?.change && fs.existsSync(path.join(sdlcRoot, 'changes', explicit.change))) {
+      return explicit.change;
+    }
+  } catch { /* fall through */ }
+  const changesDir = path.join(sdlcRoot, 'changes');
+  if (!fs.existsSync(changesDir)) return null;
+  let best = null;
+  for (const d of fs.readdirSync(changesDir, { withFileTypes: true })) {
+    if (!d.isDirectory() || d.name === 'archive') continue;
+    const p = path.join(changesDir, d.name, 'change.md');
+    if (!fs.existsSync(p)) continue;
+    const mtime = fs.statSync(p).mtimeMs;
+    if (!best || mtime > best.mtime) best = { change: d.name, mtime };
+  }
+  return best?.change ?? null;
+}
+
+// Journal: per-change ndjson when a change is active, else a global one under
+// .state/ so no signal is lost. Hook-written only — agents never hand-edit.
+export function appendJournal(sdlcRoot, change, event) {
+  try {
+    const line = JSON.stringify({ ts: new Date().toISOString(), ...event }) + '\n';
+    if (change) {
+      const dir = path.join(sdlcRoot, 'changes', change);
+      if (fs.existsSync(dir)) {
+        fs.appendFileSync(path.join(dir, 'journal.ndjson'), line);
+        return;
+      }
+    }
+    const stateDir = path.join(sdlcRoot, '.state');
+    fs.mkdirSync(stateDir, { recursive: true });
+    fs.appendFileSync(path.join(stateDir, 'journal.ndjson'), line);
+  } catch { /* fail open */ }
+}

package/payload/hooks/guard-writes.mjs

@@ -0,0 +1,83 @@
+#!/usr/bin/env node
+// PreToolUse hook — the deterministic guardrail ("things the agent should
+// never forget but often does"). Denies direct edits to:
+//   sdlc/specs/**              outside an open ship gate
+//   sdlc/changes/archive/**    outside an open ship gate
+//   sdlc/context/constitution.md (existing) outside an open steer gate
+//   sdlc/.state/** and any journal.ndjson   always (machine-owned)
+// The sanctioned paths are the CLI (`warnyin-sdlc archive`) and the gates
+// opened by `journal.mjs open-ship|open-steer`.
+
+import fs from 'node:fs';
+import process from 'node:process';
+import path from 'node:path';
+import {
+  resolveRoots, readStdinJson, readPhase, activeChange, appendJournal, toPosixRel, lexicalPosixRel,
+} from './_shared.mjs';
+
+const { sdlcRoot, projectRoot } = resolveRoots(import.meta.url);
+
+function deny(reason, rel) {
+  appendJournal(sdlcRoot, activeChange(sdlcRoot), { event: 'guard', action: 'deny', path: rel, reason });
+  console.log(JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: 'PreToolUse',
+      permissionDecision: 'deny',
+      permissionDecisionReason: reason,
+    },
+  }));
+}
+
+// Evaluate the lock rules against ONE view of the path. Returns true when a
+// deny was emitted. Rules must hold for BOTH the lexical (claimed) and the
+// realpath-resolved view — a symlink must never weaken a lock.
+function guard(rel, phase) {
+  if (rel.startsWith('sdlc/.state/') || rel.endsWith('journal.ndjson')) {
+    deny(`"${rel}" is machine-owned (hooks/CLI write it) — never edit it by hand.`, rel);
+    return true;
+  }
+  if (rel.startsWith('sdlc/specs/') || rel.startsWith('sdlc/changes/archive/')) {
+    if (phase?.phase === 'ship') return false;
+    deny(
+      `"${rel}" is write-locked outside ship. Living specs change only by merging a change's Delta: `
+      + 'run `warnyin-sdlc archive <id>` (or `node sdlc/.hooks/journal.mjs open-ship <id>` first if you must edit).',
+      rel,
+    );
+    return true;
+  }
+  if (rel === 'sdlc/context/constitution.md' && fs.existsSync(path.join(projectRoot, rel))) {
+    if (phase?.phase === 'steer' || phase?.phase === 'ship') return false;
+    deny(
+      'The constitution is always-loaded context — edits go through /sdlc:steer '
+      + '(`node sdlc/.hooks/journal.mjs open-steer` opens the gate).',
+      rel,
+    );
+    return true;
+  }
+  return false;
+}
+
+async function main() {
+  const input = await readStdinJson();
+  const filePath = input?.tool_input?.file_path ?? input?.tool_input?.notebook_path;
+  if (!filePath || !fs.existsSync(sdlcRoot)) return;
+
+  const abs = path.resolve(projectRoot, filePath);
+  const relLexical = lexicalPosixRel(projectRoot, abs);
+  const relReal = toPosixRel(projectRoot, abs);
+
+  // A path that CLAIMS to live under sdlc/ but resolves elsewhere (or out of
+  // the project) went through a symlink — deny conservatively; a symlink must
+  // never disable the write-lock.
+  if (relLexical?.startsWith('sdlc/') && relReal !== relLexical) {
+    deny(`"${relLexical}" resolves through a symlink to "${relReal ?? 'outside the project'}" — refusing to touch it.`, relLexical);
+    return;
+  }
+
+  const phase = readPhase(sdlcRoot);
+  for (const rel of new Set([relLexical, relReal].filter(Boolean))) {
+    if (rel.startsWith('sdlc/') && guard(rel, phase)) return;
+  }
+}
+
+main().catch(() => process.exit(0)); // fail open

package/payload/hooks/inject-context.mjs

@@ -0,0 +1,55 @@
+#!/usr/bin/env node
+// SessionStart hook — THE static-context loader. Emits (hard cap 60 lines):
+//   constitution + every `inclusion: always` steering file + a one-line
+//   pointer to the active change. Everything else stays dynamic.
+// Journals what was injected so /sdlc:observe can price residency honestly.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import process from 'node:process';
+import { resolveRoots, readStdinJson, activeChange, appendJournal } from './_shared.mjs';
+import { parseFrontmatter } from './lib/frontmatter.mjs';
+import { CAPS } from './lib/caps.mjs';
+
+const { sdlcRoot } = resolveRoots(import.meta.url);
+
+async function main() {
+  await readStdinJson(); // drain; content not needed
+  if (!fs.existsSync(sdlcRoot)) return;
+
+  const injected = [];
+  const out = [];
+
+  const constitutionPath = path.join(sdlcRoot, 'context', 'constitution.md');
+  if (fs.existsSync(constitutionPath)) {
+    out.push(fs.readFileSync(constitutionPath, 'utf8').trim());
+    injected.push('context/constitution.md');
+  }
+
+  const steeringDir = path.join(sdlcRoot, 'context', 'steering');
+  if (fs.existsSync(steeringDir)) {
+    for (const f of fs.readdirSync(steeringDir).filter((n) => n.endsWith('.md')).sort()) {
+      const raw = fs.readFileSync(path.join(steeringDir, f), 'utf8');
+      const { data, body } = parseFrontmatter(raw);
+      if (data.inclusion !== 'always') continue;
+      out.push(body.trim());
+      injected.push(`context/steering/${f}`);
+    }
+  }
+
+  const active = activeChange(sdlcRoot);
+  if (active) out.push(`Active change: sdlc/changes/${active}/change.md — run /sdlc:next for status.`);
+
+  if (!out.length) return;
+
+  let lines = out.join('\n\n').split('\n');
+  if (lines.length > CAPS.alwaysBudget) {
+    lines = lines.slice(0, CAPS.alwaysBudget);
+    lines.push(`[sdlc] static context truncated at ${CAPS.alwaysBudget} lines — run /sdlc:steer to distill (validate also flags this).`);
+  }
+  console.log(lines.join('\n'));
+
+  appendJournal(sdlcRoot, active, { event: 'inject', files: injected, lines: lines.length });
+}
+
+main().catch(() => process.exit(0)); // fail open

package/payload/hooks/journal.mjs

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+// Gate + journal utility. Called by playbooks (sanctioned phase transitions)
+// and wired as the PreCompact hook (`journal.mjs note compact`).
+//
+//   node sdlc/.hooks/journal.mjs open-ship <change-id>   unlock specs/archive writes (TTL 30m)
+//   node sdlc/.hooks/journal.mjs open-steer              unlock constitution edits (TTL 30m)
+//   node sdlc/.hooks/journal.mjs close                   close any open gate
+//   node sdlc/.hooks/journal.mjs set-active <change-id>  attribute sessions/events to a change
+//   node sdlc/.hooks/journal.mjs note <name> [k=v ...]   append a journal event
+
+import fs from 'node:fs';
+import path from 'node:path';
+import process from 'node:process';
+import {
+  resolveRoots, readStdinJson, writePhase, clearPhase, activeChange, appendJournal,
+} from './_shared.mjs';
+
+const { sdlcRoot } = resolveRoots(import.meta.url);
+
+async function main() {
+  const [cmd, ...rest] = process.argv.slice(2);
+
+  if (cmd === 'open-ship') {
+    const change = rest[0];
+    if (!change) { console.error('usage: journal.mjs open-ship <change-id>'); process.exit(2); }
+    const phase = writePhase(sdlcRoot, { phase: 'ship', change });
+    appendJournal(sdlcRoot, change, { event: 'gate', gate: 'ship', action: 'open', expires: phase.expires });
+    console.log(`ship gate open for "${change}" until ${phase.expires}`);
+  } else if (cmd === 'open-steer') {
+    const phase = writePhase(sdlcRoot, { phase: 'steer' });
+    appendJournal(sdlcRoot, null, { event: 'gate', gate: 'steer', action: 'open', expires: phase.expires });
+    console.log(`steer gate open until ${phase.expires}`);
+  } else if (cmd === 'close') {
+    clearPhase(sdlcRoot);
+    console.log('gate closed');
+  } else if (cmd === 'set-active') {
+    const change = rest[0];
+    if (!change) { console.error('usage: journal.mjs set-active <change-id>'); process.exit(2); }
+    fs.mkdirSync(path.join(sdlcRoot, '.state'), { recursive: true });
+    fs.writeFileSync(path.join(sdlcRoot, '.state', 'active.json'), JSON.stringify({ change }));
+    console.log(`active change: ${change}`);
+  } else if (cmd === 'note') {
+    // When used as a hook, drain stdin so the harness never blocks on us.
+    if (!process.stdin.isTTY) await readStdinJson();
+    const name = rest[0] ?? 'note';
+    const extra = {};
+    for (const kv of rest.slice(1)) {
+      const [k, ...v] = kv.split('=');
+      if (k && v.length) extra[k] = v.join('=');
+    }
+    appendJournal(sdlcRoot, activeChange(sdlcRoot), { event: name, ...extra });
+  } else {
+    console.error('usage: journal.mjs open-ship|open-steer|close|set-active|note ...');
+    process.exit(2);
+  }
+}
+
+main().catch(() => process.exit(0)); // fail open

package/payload/hooks/session-summary.mjs

@@ -0,0 +1,50 @@
+#!/usr/bin/env node
+// Stop hook — the observability tap. Parses the session transcript's real
+// usage numbers, attributes them to the active change, appends a `session`
+// journal event, and prints a one-line summary. Cost is computed only when
+// sdlc/config.yaml provides a price table — otherwise reported as n/a.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import process from 'node:process';
+import { resolveRoots, readStdinJson, activeChange, appendJournal } from './_shared.mjs';
+import { parseTranscriptUsage, costUsd } from './lib/usage.mjs';
+import { parseConfig } from './lib/config.mjs';
+
+const { sdlcRoot } = resolveRoots(import.meta.url);
+
+const fmt = (n) => (n >= 1_000_000 ? `${(n / 1_000_000).toFixed(1)}M`
+  : n >= 1_000 ? `${(n / 1_000).toFixed(1)}k` : String(n));
+
+async function main() {
+  const input = await readStdinJson();
+  const transcriptPath = input?.transcript_path;
+  if (!transcriptPath || !fs.existsSync(transcriptPath) || !fs.existsSync(sdlcRoot)) return;
+
+  const usage = parseTranscriptUsage(fs.readFileSync(transcriptPath, 'utf8'));
+  if (!usage.totals.input && !usage.totals.output) return;
+
+  let prices = null;
+  try {
+    prices = parseConfig(fs.readFileSync(path.join(sdlcRoot, 'config.yaml'), 'utf8')).prices;
+  } catch { /* no config, no cost */ }
+  const usd = costUsd(usage, prices);
+
+  const change = activeChange(sdlcRoot);
+  appendJournal(sdlcRoot, change, {
+    event: 'session',
+    session: input?.session_id ?? null,
+    totals: usage.totals,
+    models: usage.models,
+    costUsd: usd,
+  });
+
+  const t = usage.totals;
+  console.log(
+    `[sdlc] session: ${fmt(t.input)} in / ${fmt(t.output)} out / ${fmt(t.cacheRead)} cache-read`
+    + ` · cost ${usd == null ? 'n/a' : `$${usd}`}`
+    + (change ? ` · change ${change}` : ''),
+  );
+}
+
+main().catch(() => process.exit(0)); // fail open

package/payload/hooks/validate-artifact.mjs

@@ -0,0 +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

package/payload/playbook/README.md

@@ -0,0 +1,30 @@
+# @warnyin/sdlc playbook
+
+One change = one folder in `sdlc/changes/<id>/` moving through:
+
+```
+new → [design] → contract → build → verify → [review] → ship
+```
+
+| Command | Day-1 phase | Reads | Writes | Gate (automatic unless noted) |
+|---|---|---|---|---|
+| /sdlc:init | Configure harness | interview | constitution, harness.md | human approves (once) |
+| /sdlc:auto | whole loop | — | everything below | escalation only |
+| /sdlc:new | Requirements | specs Purpose headers | change.md | validator: delta + assumptions |
+| /sdlc:design | Architecture | change + touched specs | change.md § Design | escalate irreversible only |
+| /sdlc:contract | Contract-first | change.md | contract/*, failing tests | adversarial panel + validator |
+| /sdlc:build | Run harness | change + contract + steering | code, task boxes | tasks done; specs locked by hook |
+| /sdlc:verify | Feedback loop | contract | journal events | tests green AND evals ≥ bar |
+| /sdlc:review | Review | diff + change | findings in change.md | blockers = 0 |
+| /sdlc:ship | Ship | change | specs merge, archive, digest | validate --strict; policy may require human |
+| /sdlc:observe | Observe | journals | report (chat) | — |
+| /sdlc:converge | Maintenance | specs + code | proposed change | — |
+| /sdlc:steer | Configure | context/ | steering, constitution | always-budget ≤ 60 |
+| /sdlc:next | — | status | chat only | — |
+
+Statuses: `new → contracted → building → verified → shipped`. Tiers: `vibe | standard | deep`
+(triage table + Autonomy policy live in `sdlc/harness.md`).
+
+Doctrine: `principles.md` (factory model, anti-garbage), `context.md` (static/dynamic),
+`routing.md` (model tiers). Non-Claude harnesses: `rules-card.md` is embedded in your
+tool's rules file; `npx @warnyin/sdlc validate` is the enforcement floor.

package/payload/playbook/auto.md

@@ -0,0 +1,21 @@
+# /sdlc:auto <title> — the whole pipeline, one command
+
+Runs new → [design] → contract → build → verify → [review] → ship, each stage by
+its own playbook, WITHOUT pausing for the human except on the Autonomy-policy
+escalation conditions:
+
+- hard-floor surface (security, payments, data-loss, irreversible),
+- a `[NEEDS CLARIFICATION]` the agent cannot resolve alone,
+- verify failed more than 3 rounds,
+- token budget exceeded (if the user set one),
+- ship policy requires human approval (deep tier).
+
+Rules:
+- Announce the plan in ≤3 lines after triage (id, tier, task count), then work.
+- Between stages run `npx @warnyin/sdlc validate <id>` — a red validator is a
+  hard stop for that stage, not a suggestion.
+- On escalation: stop at the exact step, state what is needed in ≤5 lines, wait.
+  When the human answers, resume from that step — never restart the pipeline.
+- On completion report one line: shipped + digest path + total cost if known.
+
+This is orchestrator mode: the human describes the outcome and walks away.

package/payload/playbook/build.md

@@ -0,0 +1,23 @@
+# /sdlc:build <id> — implement (Run the harness)
+
+Precondition: status ≥ contracted (vibe tier is exempt from contracts).
+Set `status: building`.
+
+Mode by size:
+- **Conductor** (≤2 tasks): implement in this session, task by task.
+- **Orchestrator** (>2 tasks): fan out one `sdlc-builder` subagent per task in a
+  `[P]` wave; serialize between dependent waves. Each builder receives ONLY:
+  its task line, `contract/tests.md`, the touched capability's spec, and steering
+  matching its file area — never the whole change history.
+
+Rules for whoever implements:
+- Follow steering pointers the moment the PostToolUse hook emits them.
+- Never edit `sdlc/specs/**`, archive, journals, or lint/test configs to go
+  green — hooks deny the first two; the rest is the config-protection rule.
+- Per-task self-check = that task's tests + lint only; the full test run belongs
+  to /sdlc:verify (moved, not removed).
+- Tick `- [x]` in `## Tasks` as each task lands; note surprises in one line max.
+- Honor `[tier:x]` markers when delegating (see routing.md).
+
+Done when all tasks are ticked and the code compiles/lints.
+`node sdlc/.hooks/journal.mjs note build tasks=<n>` then → /sdlc:verify.

package/payload/playbook/context.md

@@ -0,0 +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.

package/payload/playbook/contract.md

@@ -0,0 +1,23 @@
+# /sdlc:contract <id> — tests + evals before code
+
+The contract IS the handshake. Nothing in `## Tasks` may be implemented while
+status is `new`.
+
+1. From the Delta scenarios, write `contract/tests.md` (≤60 lines): one row per
+   behavior — Given/When/Then, kind, mapped requirement. List what is explicitly
+   out of scope and why.
+2. Deep tier (standard optional): write `contract/evals.md` (≤40 lines) — the
+   trajectory + quality rubric the sdlc-evaluator will score.
+3. Generate failing tests: delegate to the `sdlc-contractor` agent (cheap tier)
+   with ONLY tests.md + the delta + the project's test conventions. Run the test
+   command from `sdlc/harness.md` — every new test must FAIL (red) now; a test
+   that passes before implementation tests nothing.
+4. Adversarial check instead of human approval: ask the `sdlc-quality` agent to
+   attack the contract — uncovered scenarios, untestable rows, missing edge
+   cases vs the delta. Fix findings; one round is usually enough, two max.
+5. `npx @warnyin/sdlc validate <id>` clean → set frontmatter `status: contracted`
+   and `node sdlc/.hooks/journal.mjs note contract tests=<n>`.
+
+Escalate only if the delta itself turns out ambiguous (back to /sdlc:new step 5).
+
+Next: /sdlc:build.

package/payload/playbook/converge.md

@@ -0,0 +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.

package/payload/playbook/design.md

@@ -0,0 +1,20 @@
+# /sdlc:design <id> — decisions & trade-offs (deep tier, or on signal)
+
+Run only when: tier is deep, OR the change needs an architectural decision
+(new dependency, schema change, cross-capability contract). Otherwise skip —
+an empty Design section is garbage.
+
+1. Read `change.md`, the full spec of every touched capability, and any steering
+   whose scope matches. Nothing else by default.
+2. Gather in parallel, judge serially: fan out read-only subagents for research
+   (one per question: prior art in this repo, external constraint, data shape).
+   The DECISION is made in the main loop — never delegated, never parallel.
+3. Fill `## Design` with decision lines only:
+   `- decision: <what> · alternatives: <a/b> · because: <why>`
+   Never restate the delta. Respect the tier cap (deep total ≤150).
+4. Escalate to the human ONLY for decisions listed in
+   `sdlc/harness.md § Autonomy policy` (irreversible or hard-floor). Everything
+   else: decide, record, move on.
+5. `npx @warnyin/sdlc validate <id>`.
+
+Next: /sdlc:contract.

package/payload/playbook/init.md

@@ -0,0 +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.