@warnyin/sdlc 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+## 0.1.0 (2026-08-20)
+
+Initial release — the full Day-1 SDLC loop:
+
+- CLI: `init` (multi-tool: claude/cursor/windsurf/copilot/cline/gemini/agents-md),
+  `update` (ownership-aware refresh + guarded prune), `validate`, `status`,
+  `observe`, `archive`.
+- Artifact model: constitution (≤30) + steering with inclusion modes + harness
+  (routing/triage/autonomy policy) + living specs + delta-based changes
+  (vibe/standard/deep caps 40/100/150) + contracts (tests ≤60, evals ≤40).
+- Managed Claude Code hooks: static-context injector, spec write-lock with TTL
+  gates, artifact validator + steering pointers, session token/cost journaling,
+  compact-event tracking.
+- 13 stage playbooks + 13 `/sdlc:*` commands + 3 background skills + 8 agents
+  with model routing (cheap/balanced/deepest).
+- Observability: per-change tokens/cost, first-pass rate, lead time, dead
+  steering and residency flags; post-ship learner loop (distill, never bloat).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 warnyin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,74 @@
+# @warnyin/sdlc
+
+**Spec-driven, AI-driven SDLC for coding agents — token-lean by construction.**
+
+Operationalizes the *"New SDLC with Vibe Coding"* (Day-1) work process: the human configures
+the harness once; the AI drives changes end-to-end through contract-first gates; deterministic
+hooks and a validator enforce the rules; a journal prices every change in real tokens.
+
+Inspired by OpenSpec (delta specs, archive lifecycle), spec-kit (artifact grammar), and
+Kiro (steering + enforced hooks) — tuned for minimum context residency.
+
+## Install
+
+```bash
+cd your-project
+npx @warnyin/sdlc init          # pick tools: claude, cursor, windsurf, copilot, cline, gemini, agents-md
+```
+
+Then in your coding agent:
+
+```
+/sdlc:init                      # interview → constitution + harness (the one human gate)
+/sdlc:auto Add rate limiting    # AI runs new → contract → build → verify → ship
+```
+
+## How it works
+
+```
+sdlc/
+├── context/constitution.md   ≤30 lines — the ONLY always-loaded prose (hook-injected)
+├── context/steering/*.md     scoped knowledge · inclusion: always|paths|manual|agent
+├── harness.md                tools, model routing, tier triage, autonomy policy
+├── specs/<capability>/       living specs — WHEN/THEN SHALL, merged mechanically at ship
+├── changes/<id>/             one change: change.md (Why+Delta+Tasks) + contract/ + journal
+└── changes/archive/          shipped changes + digests (the async human touchpoint)
+```
+
+- **Contract-first**: tests + evals are written *before* code and gate everything after.
+- **AI-driven, exception-only humans**: the autonomy policy in `harness.md` decides what
+  auto-ships and what escalates (hard-floor: security/payments/data-loss/irreversible).
+- **Managed hooks** (Claude Code): SessionStart injects ≤60 lines of static context;
+  PreToolUse write-locks living specs; PostToolUse validates caps and points at steering;
+  Stop journals real token usage. Other tools get the same rules as prose + the validator.
+- **Self-improving, leaner over time**: a post-ship learner proposes rules with evidence;
+  the always-loaded budget is fixed, so learning must distill, not accumulate.
+- **Measured**: `npx @warnyin/sdlc observe` — tokens/cost per change, first-pass rate,
+  lead time, dead steering, context-overflow flags.
+
+## CLI
+
+```
+warnyin-sdlc init [--tool ...]      scaffold + adapters + hooks
+warnyin-sdlc update [--force]       refresh payload, guarded prune of stale files
+warnyin-sdlc validate [id] [--strict]
+warnyin-sdlc status | observe [--json]
+warnyin-sdlc archive <id>           merge deltas into living specs + archive
+```
+
+## Commands (in your agent)
+
+`/sdlc:init` · `/sdlc:auto` · `/sdlc:new` · `/sdlc:design` · `/sdlc:contract` · `/sdlc:build`
+· `/sdlc:verify` · `/sdlc:review` · `/sdlc:ship` · `/sdlc:observe` · `/sdlc:converge`
+· `/sdlc:steer` · `/sdlc:next`
+
+Playbooks live in `sdlc/.playbook/` — behavior is defined once there; commands are thin pointers.
+
+## Development
+
+Zero dependencies, Node ≥ 20. `npm test` runs the black-box suite (temp dirs, real CLI spawns).
+This repo self-hosts: its own development flows through `sdlc/changes/`. After cloning, run
+`npm run setup:dogfood` to regenerate the installer-owned mirrors (`sdlc/.playbook/`,
+`sdlc/.hooks/`, `.claude/`).
+
+MIT

package/bin/cli.mjs

@@ -0,0 +1,470 @@
+#!/usr/bin/env node
+// @warnyin/sdlc CLI — OpenSpec-style installer + lifecycle mechanics.
+// Zero-dependency, Node >= 20, cross-platform. Exported functions are pure
+// where possible so tests can exercise them; `main()` is guarded.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import process from 'node:process';
+import readline from 'node:readline';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { parseFrontmatter } from '../lib/frontmatter.mjs';
+import { parseDelta, mergeDelta } from '../lib/delta.mjs';
+import { parseConfig } from '../lib/config.mjs';
+import { mergeHookSettings } from '../lib/settings-merge.mjs';
+import { buildReport, renderReport } from '../lib/observe.mjs';
+import { parseManifest, renderManifest, computeStale, containedIn, hasSymlinkSegment, PRUNE_BLAST_CAP } from '../lib/manifest.mjs';
+import { validateAll, formatIssues, listChangeDirs } from '../lib/validate.mjs';
+
+const PKG_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const PAYLOAD = path.join(PKG_ROOT, 'payload');
+const MARKER = '<!-- sdlc:start -->';
+
+export const TOOLS = Object.freeze([
+  'claude', 'cursor', 'windsurf', 'copilot', 'cline', 'gemini', 'agents-md',
+]);
+
+const TEXT_EXT = new Set(['.md', '.mdc', '.mjs', '.json', '.yaml', '.yml', '.txt']);
+
+// ---------- small pure helpers ----------
+
+export function normalizeEol(content) {
+  return content.replace(/\r\n/g, '\n');
+}
+
+export function toPosix(p) {
+  return p.split(path.sep).join('/');
+}
+
+export function sha256(content) {
+  return crypto.createHash('sha256').update(content).digest('hex');
+}
+
+export function parseArgs(argv) {
+  const args = { _: [], tool: null, strict: false, force: false, json: false, help: false };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--tool') args.tool = (argv[++i] ?? '').split(',').map((s) => s.trim()).filter(Boolean);
+    else if (a === '--strict') args.strict = true;
+    else if (a === '--force') args.force = true;
+    else if (a === '--json') args.json = true;
+    else if (a === '--help' || a === '-h') args.help = true;
+    else if (a.startsWith('--')) console.warn(`unknown flag ${a} (ignored)`);
+    else args._.push(a);
+  }
+  return args;
+}
+
+// ---------- payload-owned file installation (ownership semantics) ----------
+// install mode: missing → write · byte-equal → claim · different → user's, keep.
+// update mode:  additionally, disk == old manifest hash (ours, unmodified) → refresh.
+
+function writeFileNormalized(dest, content) {
+  const ext = path.extname(dest);
+  const out = TEXT_EXT.has(ext) ? normalizeEol(content) : content;
+  fs.mkdirSync(path.dirname(dest), { recursive: true });
+  fs.writeFileSync(dest, out);
+  return out;
+}
+
+export function installFile(projectRoot, destRel, content, ctx) {
+  const relPosix = toPosix(destRel);
+  const dest = path.join(projectRoot, destRel);
+  const next = normalizeEol(content);
+  const nextHash = sha256(next);
+
+  if (!fs.existsSync(dest)) {
+    writeFileNormalized(dest, next);
+    ctx.manifest.set(relPosix, nextHash);
+    return 'written';
+  }
+  const current = normalizeEol(fs.readFileSync(dest, 'utf8'));
+  const currentHash = sha256(current);
+  if (currentHash === nextHash) {
+    ctx.manifest.set(relPosix, nextHash);
+    return 'current';
+  }
+  if (ctx.mode === 'update' && ctx.oldManifest?.get(relPosix) === currentHash) {
+    writeFileNormalized(dest, next);
+    ctx.manifest.set(relPosix, nextHash);
+    return 'updated';
+  }
+  ctx.warnings.push(`kept (user-modified): ${relPosix}`);
+  return 'kept';
+}
+
+function copyTree(srcDir, destDirRel, projectRoot, ctx) {
+  if (!fs.existsSync(srcDir)) return;
+  for (const entry of fs.readdirSync(srcDir, { withFileTypes: true })) {
+    const src = path.join(srcDir, entry.name);
+    const destRel = path.join(destDirRel, entry.name);
+    if (entry.isDirectory()) copyTree(src, destRel, projectRoot, ctx);
+    else installFile(projectRoot, destRel, fs.readFileSync(src, 'utf8'), ctx);
+  }
+}
+
+function payloadText(rel) {
+  return normalizeEol(fs.readFileSync(path.join(PAYLOAD, rel), 'utf8'));
+}
+
+// ---------- adapters ----------
+
+function renderAdapter(templateRel) {
+  return payloadText(templateRel).replace('{{RULES_CARD}}', payloadText('playbook/rules-card.md').trim());
+}
+
+// Marker adapters live inside user-owned files: append once, never rewrite.
+function appendWithMarker(projectRoot, destRel, content) {
+  const dest = path.join(projectRoot, destRel);
+  if (fs.existsSync(dest)) {
+    const current = fs.readFileSync(dest, 'utf8');
+    if (current.includes(MARKER)) return 'present';
+    const sep = current.endsWith('\n') ? '\n' : '\n\n';
+    fs.writeFileSync(dest, current + sep + normalizeEol(content));
+    return 'appended';
+  }
+  writeFileNormalized(dest, content);
+  return 'written';
+}
+
+export function installClaudeHooks(projectRoot) {
+  const settingsPath = path.join(projectRoot, '.claude', 'settings.json');
+  let current = {};
+  if (fs.existsSync(settingsPath)) {
+    try {
+      current = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
+    } catch {
+      throw new Error('.claude/settings.json is not valid JSON — fix it, then re-run init');
+    }
+  }
+  const merged = mergeHookSettings(current);
+  fs.mkdirSync(path.dirname(settingsPath), { recursive: true });
+  fs.writeFileSync(settingsPath, JSON.stringify(merged, null, 2) + '\n');
+}
+
+function installToolAdapters(projectRoot, tools, ctx) {
+  if (tools.includes('claude')) {
+    copyTree(path.join(PAYLOAD, 'adapters/claude/commands'), path.join('.claude', 'commands'), projectRoot, ctx);
+    copyTree(path.join(PAYLOAD, 'adapters/claude/skills'), path.join('.claude', 'skills'), projectRoot, ctx);
+    copyTree(path.join(PAYLOAD, 'adapters/claude/agents'), path.join('.claude', 'agents'), projectRoot, ctx);
+    installClaudeHooks(projectRoot);
+  }
+  if (tools.includes('cursor')) {
+    installFile(projectRoot, path.join('.cursor', 'rules', 'sdlc.mdc'), renderAdapter('adapters/cursor.mdc'), ctx);
+  }
+  if (tools.includes('windsurf')) {
+    installFile(projectRoot, path.join('.windsurf', 'rules', 'sdlc.md'), renderAdapter('adapters/windsurf.md'), ctx);
+  }
+  if (tools.includes('copilot')) {
+    appendWithMarker(projectRoot, path.join('.github', 'copilot-instructions.md'), renderAdapter('adapters/copilot.md'));
+  }
+  if (tools.includes('cline')) {
+    appendWithMarker(projectRoot, '.clinerules', renderAdapter('adapters/cline.md'));
+  }
+  if (tools.includes('gemini')) {
+    appendWithMarker(projectRoot, 'GEMINI.md', renderAdapter('adapters/gemini.md'));
+  }
+  if (tools.includes('agents-md')) {
+    appendWithMarker(projectRoot, 'AGENTS.md', renderAdapter('adapters/agents-md.md'));
+  }
+}
+
+// ---------- scaffold ----------
+
+function scaffoldSdlc(projectRoot, tools, ctx) {
+  const sdlcRoot = path.join(projectRoot, 'sdlc');
+  for (const dir of ['context/steering', 'specs', 'changes/archive', 'evals', '.state']) {
+    fs.mkdirSync(path.join(sdlcRoot, dir), { recursive: true });
+  }
+
+  // Seeds are user-owned from birth: created once, never manifested/overwritten.
+  const seed = (rel, templateName, transform = (s) => s) => {
+    const dest = path.join(sdlcRoot, rel);
+    if (fs.existsSync(dest)) return;
+    writeFileNormalized(dest, transform(payloadText(`templates/${templateName}`)));
+  };
+  seed('config.yaml', 'config.yaml', (s) => s.replace('tools: []', `tools: [${tools.join(', ')}]`));
+  seed('context/constitution.md', 'constitution.md');
+  seed('harness.md', 'harness.md');
+
+  // Payload-owned trees (manifested, refreshed by `update`).
+  copyTree(path.join(PAYLOAD, 'playbook'), path.join('sdlc', '.playbook'), projectRoot, ctx);
+  copyTree(path.join(PAYLOAD, 'templates'), path.join('sdlc', '.playbook', 'templates'), projectRoot, ctx);
+  copyTree(path.join(PAYLOAD, 'hooks'), path.join('sdlc', '.hooks'), projectRoot, ctx);
+  copyTree(path.join(PKG_ROOT, 'lib'), path.join('sdlc', '.hooks', 'lib'), projectRoot, ctx);
+}
+
+export function writeManifestFile(projectRoot, manifest) {
+  const statePath = path.join(projectRoot, 'sdlc', '.state');
+  fs.mkdirSync(statePath, { recursive: true });
+  fs.writeFileSync(path.join(statePath, 'manifest'), renderManifest(manifest));
+}
+
+export function readManifestFile(projectRoot) {
+  const p = path.join(projectRoot, 'sdlc', '.state', 'manifest');
+  return fs.existsSync(p) ? parseManifest(fs.readFileSync(p, 'utf8')) : new Map();
+}
+
+export function ensureGitignore(projectRoot) {
+  const giPath = path.join(projectRoot, '.gitignore');
+  const entry = 'sdlc/.state/';
+  let current = fs.existsSync(giPath) ? fs.readFileSync(giPath, 'utf8') : '';
+  if (current.split(/\r?\n/).some((l) => l.trim() === entry)) return;
+  if (current && !current.endsWith('\n')) current += '\n';
+  fs.writeFileSync(giPath, current + entry + '\n');
+}
+
+// ---------- init ----------
+
+export async function resolveTools(args, { interactive = process.stdin.isTTY && process.stdout.isTTY } = {}) {
+  if (args.tool?.length) {
+    const bad = args.tool.filter((t) => !TOOLS.includes(t));
+    if (bad.length) throw new Error(`unknown tool(s): ${bad.join(', ')} — valid: ${TOOLS.join(', ')}`);
+    return args.tool;
+  }
+  if (!interactive) return ['claude'];
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  const answer = await new Promise((resolve) => {
+    rl.question(`Tools to set up [${TOOLS.join(', ')}] (comma-separated, default: claude): `, resolve);
+  });
+  rl.close();
+  const picked = answer.split(',').map((s) => s.trim()).filter(Boolean);
+  if (!picked.length) return ['claude'];
+  const bad = picked.filter((t) => !TOOLS.includes(t));
+  if (bad.length) throw new Error(`unknown tool(s): ${bad.join(', ')}`);
+  return picked;
+}
+
+export async function cmdInit(projectRoot, args) {
+  const tools = await resolveTools(args);
+  const ctx = { mode: 'install', manifest: new Map(), oldManifest: readManifestFile(projectRoot), warnings: [] };
+  scaffoldSdlc(projectRoot, tools, ctx);
+  installToolAdapters(projectRoot, tools, ctx);
+  writeManifestFile(projectRoot, ctx.manifest);
+  ensureGitignore(projectRoot);
+  for (const w of ctx.warnings) console.warn(`  ${w}`);
+  console.log(`sdlc/ initialized for: ${tools.join(', ')}`);
+  console.log('Next: open your coding agent and run /sdlc:init to write your constitution and harness.');
+  return { tools };
+}
+
+// ---------- update + prune ----------
+
+export function cmdUpdate(projectRoot, args) {
+  const sdlcRoot = path.join(projectRoot, 'sdlc');
+  requireSdlc(sdlcRoot);
+  const config = parseConfig(fs.readFileSync(path.join(sdlcRoot, 'config.yaml'), 'utf8'));
+  const tools = args.tool?.length ? args.tool : (config.tools.length ? config.tools : ['claude']);
+
+  // Persist an explicit --tool override so declared and installed state never
+  // diverge (otherwise pruning tool-specific files leaves config.yaml stale).
+  if (args.tool?.length) {
+    const configPath = path.join(sdlcRoot, 'config.yaml');
+    const raw = fs.readFileSync(configPath, 'utf8');
+    fs.writeFileSync(configPath, raw.replace(/^tools:.*$/m, `tools: [${tools.join(', ')}]`));
+  }
+
+  const oldManifest = readManifestFile(projectRoot);
+  const ctx = { mode: 'update', manifest: new Map(), oldManifest, warnings: [] };
+  scaffoldSdlc(projectRoot, tools, ctx);
+  installToolAdapters(projectRoot, tools, ctx);
+
+  // Prune: old-manifest entries no longer in the payload, guarded six ways.
+  const { stale, rejected, overCap } = computeStale(oldManifest, new Set(ctx.manifest.keys()));
+  for (const r of rejected) ctx.warnings.push(`prune rejected: ${r.path} (${r.reason})`);
+  let pruned = 0;
+  if (overCap && !args.force) {
+    ctx.warnings.push(`prune skipped: ${stale.length} stale files exceed the blast cap (${PRUNE_BLAST_CAP}) — re-run with --force after reviewing`);
+  } else {
+    const realRoot = fs.realpathSync.native(projectRoot);
+    const nominalRoot = path.resolve(projectRoot);
+    for (const { path: relPath, hash } of stale) {
+      const abs = path.join(projectRoot, relPath);
+      if (!fs.existsSync(abs)) continue;
+      if (hasSymlinkSegment(nominalRoot, abs)) {
+        ctx.warnings.push(`prune rejected: ${relPath} (symlink in path)`);
+        continue;
+      }
+      const diskHash = sha256(normalizeEol(fs.readFileSync(abs, 'utf8')));
+      if (diskHash !== hash) { ctx.warnings.push(`prune kept (modified): ${relPath}`); continue; }
+      const realAbs = fs.realpathSync.native(abs);
+      if (!containedIn(realRoot, realAbs)) { ctx.warnings.push(`prune rejected: ${relPath} (escapes project)`); continue; }
+      fs.rmSync(abs);
+      pruned++;
+      let dir = path.dirname(abs);
+      while (containedIn(realRoot, dir)) {
+        try { fs.rmdirSync(dir); } catch { break; }
+        dir = path.dirname(dir);
+      }
+    }
+  }
+
+  writeManifestFile(projectRoot, ctx.manifest);
+  for (const w of ctx.warnings) console.warn(`  ${w}`);
+  console.log(`updated for: ${tools.join(', ')} · payload files: ${ctx.manifest.size} · pruned: ${pruned}`);
+  return { pruned, warnings: ctx.warnings };
+}
+
+// ---------- status ----------
+
+export function readChanges(sdlcRoot) {
+  return listChangeDirs(sdlcRoot).map((dir) => {
+    const changePath = path.join(dir, 'change.md');
+    const id = path.basename(dir);
+    if (!fs.existsSync(changePath)) return { id, tier: '?', status: '?', title: '(missing change.md)' };
+    const raw = fs.readFileSync(changePath, 'utf8');
+    const { data, body } = parseFrontmatter(raw);
+    const title = body.match(/^# Change:\s*(.+)$/m)?.[1] ?? '';
+    return { id, tier: data.tier ?? '?', status: data.status ?? '?', title };
+  });
+}
+
+export function cmdStatus(projectRoot, { json = false } = {}) {
+  const sdlcRoot = path.join(projectRoot, 'sdlc');
+  requireSdlc(sdlcRoot);
+  const changes = readChanges(sdlcRoot);
+  const archiveDir = path.join(sdlcRoot, 'changes', 'archive');
+  const archived = fs.existsSync(archiveDir)
+    ? fs.readdirSync(archiveDir, { withFileTypes: true }).filter((d) => d.isDirectory()).length
+    : 0;
+  if (json) {
+    console.log(JSON.stringify({ changes, archived }, null, 2));
+  } else if (!changes.length) {
+    console.log(`No active changes (${archived} archived). Start one with /sdlc:new or /sdlc:auto.`);
+  } else {
+    for (const c of changes) console.log(`${c.id}  [${c.tier}/${c.status}]  ${c.title}`);
+    console.log(`${changes.length} active · ${archived} archived`);
+  }
+  return { changes, archived };
+}
+
+// ---------- observe ----------
+
+export function cmdObserve(projectRoot, { json = false } = {}) {
+  const sdlcRoot = path.join(projectRoot, 'sdlc');
+  requireSdlc(sdlcRoot);
+  const report = buildReport(sdlcRoot);
+  console.log(json ? JSON.stringify(report, null, 2) : renderReport(report));
+  return report;
+}
+
+// ---------- archive (= mechanical part of ship) ----------
+
+export function appendJournal(changeDir, event) {
+  const line = JSON.stringify({ ts: new Date().toISOString(), ...event });
+  fs.appendFileSync(path.join(changeDir, 'journal.ndjson'), line + '\n');
+}
+
+export function cmdArchive(projectRoot, changeId, { strict = true } = {}) {
+  const sdlcRoot = path.join(projectRoot, 'sdlc');
+  requireSdlc(sdlcRoot);
+  if (!changeId) throw new Error('usage: warnyin-sdlc archive <change-id>');
+  const changeDir = path.join(sdlcRoot, 'changes', changeId);
+  if (!fs.existsSync(changeDir)) throw new Error(`change "${changeId}" not found`);
+
+  // Atomicity: the archive destination must be checked BEFORE any write —
+  // otherwise a same-day id collision would mutate specs and stamp the change
+  // while reporting failure.
+  const date = new Date().toISOString().slice(0, 10);
+  const destDir = path.join(sdlcRoot, 'changes', 'archive', `${date}-${changeId}`);
+  if (fs.existsSync(destDir)) {
+    throw new Error(`archive target already exists: ${toPosix(path.relative(projectRoot, destDir))} — nothing was merged`);
+  }
+
+  const issues = validateAll(sdlcRoot, { strict, changeId });
+  const errors = issues.filter((i) => i.level === 'error');
+  if (errors.length) {
+    console.error(formatIssues(errors));
+    throw new Error(`validate --strict failed with ${errors.length} error(s) — not archiving`);
+  }
+
+  const changeText = fs.readFileSync(path.join(changeDir, 'change.md'), 'utf8');
+  const { deltas, errors: parseErrors } = parseDelta(changeText);
+  if (parseErrors.length) throw new Error(`delta parse errors: ${parseErrors.join('; ')}`);
+
+  // Phase 1: compute every merge before writing anything (all-or-nothing).
+  const merged = [];
+  for (const d of deltas) {
+    const specPath = path.join(sdlcRoot, 'specs', d.capability, 'spec.md');
+    const specText = fs.existsSync(specPath) ? fs.readFileSync(specPath, 'utf8') : null;
+    const result = mergeDelta(specText, d.ops, d.capability);
+    if (!result.ok) throw new Error(`spec merge failed for "${d.capability}": ${result.errors.join('; ')}`);
+    merged.push({ specPath, content: result.content, capability: d.capability });
+  }
+
+  // Phase 2: write specs, promote evals, stamp status, move to archive.
+  for (const m of merged) writeFileNormalized(m.specPath, m.content);
+
+  const evalsSrc = path.join(changeDir, 'contract', 'evals.md');
+  if (fs.existsSync(evalsSrc)) {
+    for (const m of merged) {
+      const rubricDest = path.join(sdlcRoot, 'evals', m.capability, 'rubric.md');
+      if (!fs.existsSync(rubricDest)) {
+        writeFileNormalized(rubricDest, fs.readFileSync(evalsSrc, 'utf8'));
+      }
+    }
+  }
+
+  const stamped = changeText.replace(/^status:\s*.*$/m, 'status: shipped');
+  writeFileNormalized(path.join(changeDir, 'change.md'), stamped);
+  appendJournal(changeDir, { event: 'ship', change: changeId, specs: merged.map((m) => m.capability) });
+
+  fs.renameSync(changeDir, destDir);
+
+  console.log(`shipped: ${changeId}`);
+  for (const m of merged) console.log(`  spec merged: specs/${m.capability}/spec.md`);
+  console.log(`  archived: changes/archive/${date}-${changeId}/`);
+  return { archived: `${date}-${changeId}`, specs: merged.map((m) => m.capability) };
+}
+
+// ---------- shared ----------
+
+function requireSdlc(sdlcRoot) {
+  if (!fs.existsSync(sdlcRoot)) {
+    throw new Error('No sdlc/ directory here — run `npx @warnyin/sdlc init` first.');
+  }
+}
+
+function runValidate(projectRoot, args) {
+  const validator = path.join(PKG_ROOT, 'scripts', 'validate.mjs');
+  const spawnArgs = [validator, ...(args._.slice(1)), ...(args.strict ? ['--strict'] : []), '--root', projectRoot];
+  const res = spawnSync(process.execPath, spawnArgs, { stdio: 'inherit' });
+  process.exitCode = res.status ?? 0;
+}
+
+const HELP = `@warnyin/sdlc — spec-driven AI-SDLC framework
+
+usage: warnyin-sdlc <command> [options]
+
+  init [--tool claude,cursor,...]   scaffold sdlc/ + adapters + hooks into this project
+  update [--tool ...] [--force]     refresh payload-owned files, prune stale ones (guarded)
+  validate [id] [--strict]          structural validation (caps, delta grammar, gates)
+  status [--json]                   list active changes and their stage
+  observe [--json]                  tokens/cost per change, residency, steering hits, drift flags
+  archive <id>                      merge delta specs into living specs and archive the change
+  help                              this text
+`;
+
+export async function main(argv = process.argv.slice(2), projectRoot = process.cwd()) {
+  const args = parseArgs(argv);
+  const cmd = args._[0];
+  if (args.help || !cmd || cmd === 'help') { console.log(HELP); return; }
+  try {
+    if (cmd === 'init') await cmdInit(projectRoot, args);
+    else if (cmd === 'update') cmdUpdate(projectRoot, args);
+    else if (cmd === 'validate') runValidate(projectRoot, args);
+    else if (cmd === 'status') cmdStatus(projectRoot, { json: args.json });
+    else if (cmd === 'observe') cmdObserve(projectRoot, { json: args.json });
+    else if (cmd === 'archive') cmdArchive(projectRoot, args._[1]);
+    else { console.error(`unknown command: ${cmd}`); console.log(HELP); process.exitCode = 2; }
+  } catch (err) {
+    console.error(String(err.message ?? err));
+    process.exitCode = 1;
+  }
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  main();
+}

package/lib/caps.mjs

@@ -0,0 +1,45 @@
+// Canonical line-cap table — the single source of truth for artifact
+// residency budgets. Templates quote these numbers in HTML comments and
+// tests/caps-sync.test.mjs asserts both stay identical.
+//
+// Rationale (Day-1 economics): every resident line is paid for in every
+// turn. Caps make "learning = distilling" structural, not disciplinary.
+
+import { parseFrontmatter } from './frontmatter.mjs';
+
+export const CAPS = Object.freeze({
+  constitution: 30,     // sdlc/context/constitution.md — always loaded
+  steeringFile: 40,     // each sdlc/context/steering/*.md
+  alwaysBudget: 60,     // constitution + all `inclusion: always` steering, combined
+  harness: 60,          // sdlc/harness.md
+  spec: 150,            // sdlc/specs/<capability>/spec.md (soft — split capability beyond)
+  change: Object.freeze({ vibe: 40, standard: 100, deep: 150 }),
+  contractTests: 60,    // changes/<id>/contract/tests.md
+  contractEvals: 40,    // changes/<id>/contract/evals.md
+});
+
+export const TIERS = Object.freeze(['vibe', 'standard', 'deep']);
+
+export const STATUSES = Object.freeze([
+  'new', 'contracted', 'building', 'verified', 'shipped',
+]);
+
+// Effective lines = body lines after frontmatter, excluding blanks and
+// single-line HTML comments. Caps meter prose the model must carry, not
+// machine metadata or annotation comments.
+export function countEffectiveLines(text) {
+  const { body } = parseFrontmatter(text ?? '');
+  return body
+    .split(/\r?\n/)
+    .filter((line) => {
+      const t = line.trim();
+      if (t === '') return false;
+      if (t.startsWith('<!--') && t.endsWith('-->')) return false;
+      return true;
+    })
+    .length;
+}
+
+export function capForChange(tier) {
+  return CAPS.change[tier] ?? CAPS.change.standard;
+}

package/lib/config.mjs

@@ -0,0 +1,41 @@
+// Minimal reader for sdlc/config.yaml — supports exactly what the template
+// documents: scalar keys, inline arrays, and a `prices:` block of inline
+// objects. Anything else is ignored (never crash a hook on config).
+
+export function parseConfig(text) {
+  const config = { language: 'en', tools: [], prices: null };
+  const lines = (text ?? '').split(/\r?\n/);
+  let inPrices = false;
+  for (const raw of lines) {
+    if (!raw.trim() || raw.trim().startsWith('#')) continue;
+    const isIndented = /^\s/.test(raw);
+    if (!isIndented) inPrices = false;
+
+    if (inPrices) {
+      const m = raw.match(/^\s+([^:#]+):\s*\{(.*)\}\s*$/);
+      if (!m) continue;
+      const model = m[1].trim();
+      const obj = {};
+      for (const part of m[2].split(',')) {
+        const kv = part.split(':');
+        if (kv.length !== 2) continue;
+        const num = Number(kv[1].trim());
+        if (!Number.isNaN(num)) obj[kv[0].trim()] = num;
+      }
+      config.prices = { ...(config.prices ?? {}), [model]: obj };
+      continue;
+    }
+
+    const kv = raw.match(/^([A-Za-z0-9_-]+):\s*(.*)$/);
+    if (!kv) continue;
+    const [, key, valueRaw] = kv;
+    const value = valueRaw.replace(/\s+#.*$/, '').trim();
+    if (key === 'prices' && value === '') { inPrices = true; continue; }
+    if (value.startsWith('[') && value.endsWith(']')) {
+      config[key] = value.slice(1, -1).split(',').map((s) => s.trim()).filter(Boolean);
+    } else if (value !== '') {
+      config[key] = value;
+    }
+  }
+  return config;
+}