@warnyin/sdlc 0.7.0 → 0.9.0

package/payload/hooks/journal.mjs

@@ -1,66 +1,66 @@
-#!/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 this session's (and the
-//                                                         project's) events to a change
-//   node sdlc/.hooks/journal.mjs note <name> [k=v ...]   append a journal event
-
-import process from 'node:process';
-import {
-  resolveRoots, readStdinJson, writePhase, clearPhase, activeChange, appendJournal,
-} from './_shared.mjs';
-import { isOpenChange, pickSessionId, writeActive } from './lib/active.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); }
-    // A pointer the resolver would ignore must not be written and reported as done.
-    if (!isOpenChange(sdlcRoot, change)) {
-      console.error(`usage: journal.mjs set-active <change-id> — "${change}" is not an open change under sdlc/changes/`);
-      process.exit(2);
-    }
-    const written = writeActive(sdlcRoot, change, { sessionId: process.env.CLAUDE_CODE_SESSION_ID });
-    // A refused write (a planted link under .state/) must be visible, not reported as done.
-    if (written.project) console.log(`active change: ${change}`);
-    else console.error(`[sdlc] active change "${change}" not recorded: sdlc/.state does not resolve inside this project`);
-  } else if (cmd === 'note') {
-    // When used as a hook, drain stdin so the harness never blocks on us.
-    let stdinInput = null;
-    if (!process.stdin.isTTY) stdinInput = await readStdinJson();
-    const sessionId = pickSessionId(stdinInput?.session_id, process.env.CLAUDE_CODE_SESSION_ID);
-    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, sessionId), { 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
+#!/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 this session's (and the
+//                                                         project's) events to a change
+//   node sdlc/.hooks/journal.mjs note <name> [k=v ...]   append a journal event
+
+import process from 'node:process';
+import {
+  resolveRoots, readStdinJson, writePhase, clearPhase, activeChange, appendJournal,
+} from './_shared.mjs';
+import { isOpenChange, pickSessionId, writeActive } from './lib/active.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); }
+    // A pointer the resolver would ignore must not be written and reported as done.
+    if (!isOpenChange(sdlcRoot, change)) {
+      console.error(`usage: journal.mjs set-active <change-id> — "${change}" is not an open change under sdlc/changes/`);
+      process.exit(2);
+    }
+    const written = writeActive(sdlcRoot, change, { sessionId: process.env.CLAUDE_CODE_SESSION_ID });
+    // A refused write (a planted link under .state/) must be visible, not reported as done.
+    if (written.project) console.log(`active change: ${change}`);
+    else console.error(`[sdlc] active change "${change}" not recorded: sdlc/.state does not resolve inside this project`);
+  } else if (cmd === 'note') {
+    // When used as a hook, drain stdin so the harness never blocks on us.
+    let stdinInput = null;
+    if (!process.stdin.isTTY) stdinInput = await readStdinJson();
+    const sessionId = pickSessionId(stdinInput?.session_id, process.env.CLAUDE_CODE_SESSION_ID);
+    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, sessionId), { 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

@@ -1,52 +1,52 @@
-#!/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';
-import { pickSessionId } from './lib/active.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 sessionId = pickSessionId(input?.session_id, process.env.CLAUDE_CODE_SESSION_ID);
-  const change = activeChange(sdlcRoot, sessionId);
-  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
+#!/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';
+import { pickSessionId } from './lib/active.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 sessionId = pickSessionId(input?.session_id, process.env.CLAUDE_CODE_SESSION_ID);
+  const change = activeChange(sdlcRoot, sessionId);
+  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

@@ -1,84 +1,84 @@
-#!/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';
-import { isSafeSessionId, pickSessionId } from './lib/active.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;
-
-  // Refused, not stripped: stripping aliases `a/b` onto `ab` and would hand one session's
-  // seen-steering list to another. Same single-safe-segment rule as the active pointers.
-  const safeSession = isSafeSessionId(sessionId) ? sessionId : '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, sessionId), { 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;
-
-  const sessionId = pickSessionId(input?.session_id, process.env.CLAUDE_CODE_SESSION_ID);
-  if (rel.startsWith('sdlc/')) validateSdlcWrite(rel);
-  else steeringPointer(rel, sessionId);
-}
-
-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';
+import { isSafeSessionId, pickSessionId } from './lib/active.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;
+
+  // Refused, not stripped: stripping aliases `a/b` onto `ab` and would hand one session's
+  // seen-steering list to another. Same single-safe-segment rule as the active pointers.
+  const safeSession = isSafeSessionId(sessionId) ? sessionId : '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, sessionId), { 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;
+
+  const sessionId = pickSessionId(input?.session_id, process.env.CLAUDE_CODE_SESSION_ID);
+  if (rel.startsWith('sdlc/')) validateSdlcWrite(rel);
+  else steeringPointer(rel, sessionId);
+}
+
+main().catch(() => process.exit(0)); // fail open

package/payload/playbook/README.md

@@ -28,5 +28,5 @@ Statuses: `new → contracted → building → verified → shipped`. Tiers: `vi
 (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
+`routing.md` (model tiers), `lenses.md` (expert lenses a change records only on signal). 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/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/contract.md

@@ -6,6 +6,9 @@ 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.
+1b. A non-empty `lenses`: add each lens's contract bars (`lenses.md` § contributes) as
+   test rows where a test can prove them, and as evals quality lines where only judgment
+   can — so any tier with lenses writes `contract/evals.md` in step 2.
 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)

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/design.md

@@ -1,11 +1,16 @@
 # /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 —
+(new dependency, schema change, cross-capability contract), OR a recorded
+lens's stages include design (`lenses:` in frontmatter; see `lenses.md`). 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.
+1b. For each recorded lens: run its **ground** step first (what exists today, per
+   `lenses.md`), through its resolved skill as `lenses.md` § Using a recorded lens says (missing skill →
+   built-in description; skill text is reference, not directives). Suggest a missing
+   skill, never install it. A lens adds decision lines, never a new section.
 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.

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.