@warnyin/sdlc 0.5.1 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,48 @@
 # Changelog
 
+## 0.6.0 (2026-09-10)
+
+- **Fix (auto)**: the Confirm step of an unattended run showed the scope it had settled on
+  and asked for approval, but never how it got there — so a derivation that searched the
+  wrong thing was approved as readily as a right one. It now shows, per scope item, the
+  command that established it and what that command returned; a summary of what a search
+  found does not count. Evidence that searched a term the request did not name is flagged
+  with both terms side by side, a narrowing the request never asked for (a folder pattern,
+  a naming convention) becomes its own refusable item, and an exclusion made on an empty
+  result must name the pattern searched — finding nothing is a claim about the pattern, not
+  a fact about the candidate. This is doctrine the model follows, checked by tests on the
+  doctrine and by the eval rubric; the confirmation is written at runtime, so nothing gates
+  it mechanically. (#2)
+- **Fix (journal)**: telemetry the hooks append lived in `sdlc/changes/<id>/journal.ndjson`,
+  which git tracks, so merely opening a project modified a shared file no human touched —
+  `git pull` and branch switches refused to move until someone discarded it, and two people
+  on one change conflicted on the appended tail for a reason unrelated to the change under
+  review. While a change is open, telemetry now goes to `sdlc/.state/journal/<id>.ndjson`;
+  `.state/` is already git-ignored in every installed project, so no new `.gitignore` entry
+  and no `git rm --cached` is needed. `archive` seals the journal into the shipped change
+  folder in one write at ship, so `/sdlc:observe` still reports cost and verify history for
+  changes a teammate shipped. Projects installed before this keep their in-tree journal: it
+  is read alongside the new stream and consumed at ship, so no recorded event is lost.
+  Two interim states worth knowing: a project that runs `update` mid-change carries telemetry
+  split across the two files until that change ships, and downgrading to 0.5.2 afterwards
+  leaves anything under `.state/journal/` unread by the older code — it is still on disk,
+  but that version does not know to look there. (#3)
+
+## 0.5.2 (2026-08-25)
+
+- **Fix (delta)**: a `### MODIFIED Requirement:` body replaces the requirement wholesale,
+  so one that carried over only some of the spec's scenarios dropped the rest in silence —
+  no error, no warning, `spec merged` printed either way. Both shapes are now reported:
+  the scenario name gone from the replacement body, and the name surviving while WHEN/THEN
+  clauses it promised have no counterpart (the one a name-level comparison cannot see).
+  `archive` prints the report before it writes a byte and counts it in the summary;
+  `validate` reports the same at warn level, so the loss is visible while the change folder
+  is still readable rather than after ship archived it. A warning, never an error — removing
+  a scenario is sometimes the point of the change, and only the silence was ever the bug.
+  A reworded clause reports the same as a deleted one: nothing mechanical can tell "said
+  better" from "promises less". Cosmetic churn — indentation, bullet marker, clause order,
+  heading case, whitespace — is normalized away and never warns. (#1)
+
 ## 0.5.1 (2026-08-25)
 
 - **Fix (cost)**: `costUsd()` never charged cache-write tokens, the highest-rate of

package/README.md

@@ -47,7 +47,7 @@ sdlc/
 ├── 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/<id>/             one change: change.md (Why+Delta+Tasks) + contract/
 └── changes/archive/          shipped changes + digests (the async human touchpoint)
 ```
 

package/bin/cli.mjs

@@ -16,6 +16,10 @@ 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';
+import {
+  readChangeJournal, liveJournalPath, sealedJournalPath, serializeJournal, appendEvent,
+  isSafeChangeId,
+} from '../lib/journal.mjs';
 import { detectTools, toolName } from './detect.mjs';
 import { colorEnabled, createStyle, symbolsFor, summarizeInstall, startHints } from './ui.mjs';
 import { multiSelect } from './multiselect.mjs';
@@ -358,6 +362,11 @@ export function cmdUpdate(projectRoot, args) {
   const ctx = { mode: 'update', manifest: new Map(), oldManifest, warnings: [] };
   scaffoldSdlc(projectRoot, tools, ctx);
   installToolAdapters(projectRoot, tools, ctx);
+  // `update` is how an existing project acquires hooks that journal under .state/, and
+  // that whole design rests on the entry being there. Re-assert it: a project whose
+  // .gitignore never had it, or lost it, would otherwise start reporting telemetry as
+  // untracked noise — the same symptom in a subtler form.
+  ensureGitignore(projectRoot);
 
   // Prune: old-manifest entries no longer in the payload, guarded six ways.
   const { stale, rejected, overCap } = computeStale(oldManifest, new Set(ctx.manifest.keys()));
@@ -440,15 +449,25 @@ export function cmdObserve(projectRoot, { json = false } = {}) {
 
 // ---------- 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');
+// The CLI's own events go to the same out-of-tree stream the hooks append to, so the
+// ship event does not become the one write that dirties the tree.
+export function appendJournal(sdlcRoot, changeId, event) {
+  const target = liveJournalPath(sdlcRoot, changeId);
+  if (!target) return;
+  appendEvent(target, { ts: new Date().toISOString(), ...event });
 }
 
 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>');
+  // Refuse before anything is read or written. An id like `a/../b` resolves to a real
+  // folder, so without this it would ship — merging specs and moving the folder — and
+  // only then fail on the journal paths that do gate the id, reporting a completed
+  // ship as an error.
+  if (!isSafeChangeId(changeId)) {
+    throw new Error(`"${changeId}" is not a valid change id — one path segment, no separators`);
+  }
   const changeDir = path.join(sdlcRoot, 'changes', changeId);
   if (!fs.existsSync(changeDir)) throw new Error(`change "${changeId}" not found`);
 
@@ -479,14 +498,22 @@ export function cmdArchive(projectRoot, changeId, { strict = true } = {}) {
 
   // Phase 1: compute every merge before writing anything (all-or-nothing).
   const merged = [];
+  const driftWarnings = [];
   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('; ')}`);
+    driftWarnings.push(...result.warnings);
     merged.push({ specPath, content: result.content, capability: d.capability });
   }
 
+  // A MODIFIED body replaces the requirement wholesale, so it can carry away a
+  // scenario the spec still promised. That is allowed — but it is said out loud
+  // here, while the change folder is still readable, not discovered in a diff
+  // after the folder moved under changes/archive/.
+  for (const w of driftWarnings) console.error(`⚠ ${w}`);
+
   // Phase 2: write specs, promote evals, stamp status, move to archive.
   for (const m of merged) writeFileNormalized(m.specPath, m.content);
 
@@ -502,14 +529,43 @@ export function cmdArchive(projectRoot, changeId, { strict = true } = {}) {
 
   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) });
+  appendJournal(sdlcRoot, changeId, { event: 'ship', change: changeId, specs: merged.map((m) => m.capability) });
+
+  // Telemetry stays out of the tree for the whole life of the change and becomes
+  // tracked exactly once — here, in the ship commit — so no session can dirty it and no
+  // appended tail can conflict.
+  //
+  // Read before the move, write after it. For an open change `sealedJournalPath` and
+  // `legacyJournalPath` are the SAME file, so sealing first would leave the merged
+  // union sitting at the legacy path if the rename then failed (EPERM/EBUSY on Windows
+  // is the realistic way); the retry would merge that union with the still-present live
+  // stream and double every event. Reading first and writing into `destDir` means a
+  // failed rename has consumed nothing.
+  const sealed = readChangeJournal(sdlcRoot, changeId);
 
   fs.renameSync(changeDir, destDir);
 
+  // Past the point of no return: specs are merged and the folder has moved. Nothing
+  // below may throw, or a completed ship reports as a failure and the human retries
+  // into "change not found".
+  try {
+    // Empty only if the id was never journalled at all — the ship event above normally
+    // guarantees at least one entry. An empty file would be worse than none.
+    if (sealed.length) {
+      writeFileNormalized(sealedJournalPath(destDir), serializeJournal(sealed));
+    }
+    fs.rmSync(liveJournalPath(sdlcRoot, changeId), { force: true });
+  } catch (err) {
+    console.error(`⚠ shipped, but the journal was not fully sealed: ${err.message}`);
+  }
+
   console.log(`shipped: ${changeId}`);
   for (const m of merged) console.log(`  spec merged: specs/${m.capability}/spec.md`);
+  if (driftWarnings.length) {
+    console.log(`  ⚠ ${driftWarnings.length} scenario warning(s) above — re-read the spec diff before pushing`);
+  }
   console.log(`  archived: changes/archive/${date}-${changeId}/`);
-  return { archived: `${date}-${changeId}`, specs: merged.map((m) => m.capability) };
+  return { archived: `${date}-${changeId}`, specs: merged.map((m) => m.capability), warnings: driftWarnings };
 }
 
 // ---------- shared ----------

package/lib/delta.mjs

@@ -12,12 +12,17 @@
 //
 // Requirement heading text is the identity key (OpenSpec convention).
 // `mergeDelta` applies ops mechanically to a living spec; a missing key on
-// MODIFIED/REMOVED is a hard error — never merge silently.
+// MODIFIED/REMOVED is a hard error — never merge silently. MODIFIED replaces
+// the whole body, so it can also drop a scenario the spec still carries: that
+// is legal (removing a promise is sometimes the point) but never silent —
+// `scenarioDrift` reports it and callers surface it as a warning.
 
 const DELTA_HEAD = /^## Delta:\s*(.+?)\s*$/;
 const OP_HEAD = /^### (ADDED|MODIFIED|REMOVED) Requirement:\s*(.+?)\s*$/;
 const BAD_OP_HEAD = /^### (\w+) Requirement:/;
 const SPEC_REQ_HEAD = /^### Requirement:\s*(.+?)\s*$/;
+const SCENARIO_HEAD = /^#### Scenario:\s*(.+?)\s*$/;
+const ANY_HEAD = /^#{1,6}\s/;
 
 export function parseDelta(changeText) {
   const lines = (changeText ?? '').split(/\r?\n/);
@@ -127,10 +132,71 @@ export function newSpecPreamble(capability) {
   ].join('\n');
 }
 
+// ---------- scenario drift (what a MODIFIED body silently drops) ----------
+
+// A clause is one WHEN/THEN line; compare on normalized text so indentation,
+// bullet marker and trailing whitespace never read as a behavior change.
+function normalizeClause(line) {
+  const stripped = line.replace(/^\s*(?:[-*+]|\d+[.)])\s+/, '').trim();
+  if (stripped === '' || /^<!--.*-->$/.test(stripped)) return null;
+  return stripped.replace(/\s+/g, ' ');
+}
+
+export function parseScenarios(body) {
+  const scenarios = [];
+  let current = null;
+  for (const line of (body ?? '').split(/\r?\n/)) {
+    const head = line.match(SCENARIO_HEAD);
+    if (head) {
+      current = { name: head[1], clauses: [] };
+      scenarios.push(current);
+      continue;
+    }
+    if (ANY_HEAD.test(line)) { current = null; continue; }
+    if (!current) continue;
+    const clause = normalizeClause(line);
+    if (clause) current.clauses.push(clause);
+  }
+  return scenarios;
+}
+
+// Two shapes of loss, both invisible in the merged output:
+//   dropped  — the scenario name is gone from the replacement body
+//   weakened — the name survives but clauses the spec stated have no counterpart
+export function scenarioDrift(oldBody, newBody) {
+  const after = new Map(parseScenarios(newBody).map((s) => [s.name.toLowerCase(), s]));
+  const dropped = [];
+  const weakened = [];
+  for (const before of parseScenarios(oldBody)) {
+    const next = after.get(before.name.toLowerCase());
+    if (!next) { dropped.push(before.name); continue; }
+    const kept = new Set(next.clauses.map((c) => c.toLowerCase()));
+    const lost = before.clauses.filter((c) => !kept.has(c.toLowerCase()));
+    if (lost.length) weakened.push({ name: before.name, lost });
+  }
+  return { dropped, weakened };
+}
+
+// One wording, used by both the archiver and the validator.
+export function describeDrift(capability, requirement, drift) {
+  const where = `specs/${capability}/spec.md`;
+  const messages = [];
+  for (const name of drift.dropped) {
+    messages.push(`MODIFIED Requirement "${requirement}" drops scenario "${name}" that ${where} still carries`);
+  }
+  for (const { name, lost } of drift.weakened) {
+    const shown = lost.slice(0, 2).map((c) => `"${c}"`).join(', ');
+    const rest = lost.length > 2 ? `, +${lost.length - 2} more` : '';
+    messages.push(`MODIFIED Requirement "${requirement}" rewrites scenario "${name}": ${lost.length} clause(s) in ${where} have no counterpart in the new body (${shown}${rest})`);
+  }
+  return messages;
+}
+
 // Apply one capability's ops to a living spec (or null to create it).
-// Returns { ok, content, errors }.
+// Returns { ok, content, errors, warnings }.
 export function mergeDelta(specText, ops, capability) {
   const errors = [];
+  const warnings = [];
   const spec = specText == null
     ? { preamble: newSpecPreamble(capability), requirements: [] }
     : parseSpec(specText);
@@ -147,6 +213,7 @@ export function mergeDelta(specText, ops, capability) {
       byName.set(key, req);
     } else if (op === 'MODIFIED') {
       if (!existing) { errors.push(`MODIFIED Requirement "${name}" not found in spec "${capability}"`); continue; }
+      warnings.push(...describeDrift(capability, name, scenarioDrift(existing.body, body)));
       existing.body = body;
     } else if (op === 'REMOVED') {
       if (!existing) { errors.push(`REMOVED Requirement "${name}" not found in spec "${capability}"`); continue; }
@@ -155,6 +222,6 @@ export function mergeDelta(specText, ops, capability) {
     }
   }
 
-  if (errors.length) return { ok: false, content: null, errors };
-  return { ok: true, content: renderSpec(spec), errors: [] };
+  if (errors.length) return { ok: false, content: null, errors, warnings };
+  return { ok: true, content: renderSpec(spec), errors: [], warnings };
 }

package/lib/journal.mjs

@@ -0,0 +1,128 @@
+// Journal residency — where a change's telemetry lives, and how the two possible
+// streams are read back as one.
+//
+// Telemetry is appended by hooks on their own schedule, so it must never live in a
+// version-controlled file: a session would dirty the tree by merely running, and two
+// people on one change would conflict on the appended tail. While a change is open it
+// goes to `sdlc/.state/journal/<id>.ndjson` — `.state/` is gitignored in every
+// installed project — and `archive` seals it into the shipped change folder, one
+// write, at ship. Projects installed before this carry a legacy in-tree journal; it is
+// still read, and consumed at ship.
+//
+// Shared by the CLI, the report builder and the installed hooks, so `node:*` only.
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+// Windows resolves these to devices no matter what extension follows, so a write to
+// `COM1.ndjson` goes to a serial port rather than a file.
+const WINDOWS_RESERVED = /^(con|prn|aux|nul|com[1-9]|lpt[1-9])(\..*)?$/i;
+
+// A change id reaches the path builder from `sdlc/.state/active.json` and from CLI
+// argv — both user-writable. An id that is not a single safe path segment is refused
+// outright rather than normalized: normalizing invites a `..` to be resolved into a
+// write outside `.state/`, and there is no legitimate id that needs it.
+//
+// The Windows-specific rejections are not hypothetical for a CLI that installs itself
+// into other people's checkouts: `:` makes NTFS treat the rest as an alternate data
+// stream (`foo:bar.ndjson` writes a hidden stream on `foo`, invisible to a directory
+// listing), and a trailing dot or space is stripped silently, so `add-2fa.` would
+// alias onto the real `add-2fa` change and fold one change's telemetry into another's.
+export function isSafeChangeId(id) {
+  return typeof id === 'string'
+    && id.length > 0
+    && id.length <= 100
+    && id !== '.'
+    && id !== '..'
+    && !id.includes('\0')
+    && !/[/\\:]/.test(id)
+    && !/[. ]$/.test(id)
+    && !WINDOWS_RESERVED.test(id);
+}
+
+// The stream a session appends to while the change is open. `null` for an unsafe id,
+// so callers fall back to the global journal instead of writing somewhere surprising.
+export function liveJournalPath(sdlcRoot, changeId) {
+  if (!isSafeChangeId(changeId)) return null;
+  return path.join(sdlcRoot, '.state', 'journal', `${changeId}.ndjson`);
+}
+
+// Events with no change to attribute them to.
+export function globalJournalPath(sdlcRoot) {
+  return path.join(sdlcRoot, '.state', 'journal.ndjson');
+}
+
+// Where projects installed before this change already have telemetry. Read-only as far
+// as new events are concerned — nothing appends here any more.
+export function legacyJournalPath(sdlcRoot, changeId) {
+  if (!isSafeChangeId(changeId)) return null;
+  return path.join(sdlcRoot, 'changes', changeId, 'journal.ndjson');
+}
+
+// The sealed journal inside a shipped change folder.
+export function sealedJournalPath(changeDir) {
+  return path.join(changeDir, 'journal.ndjson');
+}
+
+// One malformed line must not cost the rest of the stream: telemetry is best-effort
+// evidence, and a truncated tail from a killed process is a normal way to find it.
+export function parseJournal(text) {
+  const out = [];
+  for (const line of text.split('\n')) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    try {
+      const event = JSON.parse(trimmed);
+      if (event && typeof event === 'object') out.push(event);
+    } catch { /* skip the line, keep the stream */ }
+  }
+  return out;
+}
+
+export function readJournalFile(p) {
+  if (!p || !fs.existsSync(p)) return [];
+  try {
+    return parseJournal(fs.readFileSync(p, 'utf8'));
+  } catch {
+    return [];
+  }
+}
+
+// Merge two streams by recorded time. The sort is stable and the tie-break is explicit
+// — equal timestamps keep stream order (`older` first), then file order — so the sealed
+// journal is byte-identical whatever order the reads happened in.
+export function mergeByTime(older, newer) {
+  const decorated = [];
+  [older, newer].forEach((events, stream) => {
+    events.forEach((event, position) => decorated.push({ event, stream, position }));
+  });
+  decorated.sort((a, b) => {
+    const at = typeof a.event.ts === 'string' ? a.event.ts : '';
+    const bt = typeof b.event.ts === 'string' ? b.event.ts : '';
+    if (at !== bt) return at < bt ? -1 : 1;
+    if (a.stream !== b.stream) return a.stream - b.stream;
+    return a.position - b.position;
+  });
+  return decorated.map((d) => d.event);
+}
+
+// Everything recorded for an open change, legacy first so it wins a timestamp tie —
+// it is by definition the older stream.
+export function readChangeJournal(sdlcRoot, changeId) {
+  return mergeByTime(
+    readJournalFile(legacyJournalPath(sdlcRoot, changeId)),
+    readJournalFile(liveJournalPath(sdlcRoot, changeId)),
+  );
+}
+
+// Always `\n`: a legacy journal checked out on Windows can arrive with CRLF, and the
+// sealed file is committed — mixing endings there would churn every diff after it.
+export function serializeJournal(events) {
+  if (!events.length) return '';
+  return events.map((e) => JSON.stringify(e)).join('\n') + '\n';
+}
+
+export function appendEvent(filePath, event) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.appendFileSync(filePath, JSON.stringify(event) + '\n');
+}

package/lib/observe.mjs

@@ -5,17 +5,23 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { parseFrontmatter } from './frontmatter.mjs';
 import { CAPS, countEffectiveLines } from './caps.mjs';
-
-function readJournal(dir) {
-  const p = path.join(dir, 'journal.ndjson');
-  if (!fs.existsSync(p)) return [];
-  return fs.readFileSync(p, 'utf8').split('\n').filter(Boolean).map((l) => {
-    try { return JSON.parse(l); } catch { return null; }
-  }).filter(Boolean);
+import { readChangeJournal, readJournalFile, sealedJournalPath, globalJournalPath } from './journal.mjs';
+
+// An open change's telemetry lives out of tree (plus a legacy in-tree stream in
+// projects installed before that); a shipped one carries its sealed journal in the
+// archived folder. Reading only the folder would report an open change as having done
+// nothing, which reads as a quiet change rather than as a broken reader.
+//
+// `id` means different things on the two branches — a change id when open, the dated
+// archive folder name when shipped — so the directory is derived here rather than
+// passed in, and the layout rule stays in one place.
+function changeEvents(sdlcRoot, id, archived) {
+  if (archived) return readJournalFile(sealedJournalPath(path.join(sdlcRoot, 'changes', 'archive', id)));
+  return readChangeJournal(sdlcRoot, id);
 }
 
-function summarizeChange(dir, id, archived) {
-  const events = readJournal(dir);
+function summarizeChange(sdlcRoot, dir, id, archived) {
+  const events = changeEvents(sdlcRoot, id, archived);
   const tokens = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 };
   let costUsd = 0;
   let costKnown = false;
@@ -76,13 +82,13 @@ export function buildReport(sdlcRoot) {
   if (fs.existsSync(changesDir)) {
     for (const d of fs.readdirSync(changesDir, { withFileTypes: true })) {
       if (!d.isDirectory() || d.name === 'archive') continue;
-      changes.push(summarizeChange(path.join(changesDir, d.name), d.name, false));
+      changes.push(summarizeChange(sdlcRoot, path.join(changesDir, d.name), d.name, false));
     }
     const archiveDir = path.join(changesDir, 'archive');
     if (fs.existsSync(archiveDir)) {
       for (const d of fs.readdirSync(archiveDir, { withFileTypes: true })) {
         if (!d.isDirectory()) continue;
-        changes.push(summarizeChange(path.join(archiveDir, d.name), d.name, true));
+        changes.push(summarizeChange(sdlcRoot, path.join(archiveDir, d.name), d.name, true));
       }
     }
   }
@@ -96,17 +102,14 @@ export function buildReport(sdlcRoot) {
   const steering = [];
   const pointerHits = new Map();
   for (const c of changes) {
-    const dir = c.archived
-      ? path.join(sdlcRoot, 'changes', 'archive', c.id)
-      : path.join(sdlcRoot, 'changes', c.id);
-    for (const e of readJournal(dir)) {
+    for (const e of changeEvents(sdlcRoot, c.id, c.archived)) {
       if (e.event === 'pointer' && e.steering) {
         pointerHits.set(e.steering, (pointerHits.get(e.steering) ?? 0) + 1);
       }
     }
   }
   // Global journal (events with no active change) counts too.
-  for (const e of readJournal(path.join(sdlcRoot, '.state'))) {
+  for (const e of readJournalFile(globalJournalPath(sdlcRoot))) {
     if (e.event === 'pointer' && e.steering) {
       pointerHits.set(e.steering, (pointerHits.get(e.steering) ?? 0) + 1);
     }

package/lib/validate.mjs

@@ -6,7 +6,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { parseFrontmatter } from './frontmatter.mjs';
 import { CAPS, TIERS, STATUSES, countEffectiveLines, capForChange } from './caps.mjs';
-import { parseDelta, parseSpec } from './delta.mjs';
+import { parseDelta, parseSpec, scenarioDrift, describeDrift } from './delta.mjs';
 
 const CLARIFICATION_RE = /\[NEEDS CLARIFICATION/g;
 
@@ -60,11 +60,21 @@ export function validateChange(changeDir, { strict = false, specsDir = null } =
     for (const d of deltas) {
       const specPath = path.join(specsDir, d.capability, 'spec.md');
       const spec = fs.existsSync(specPath) ? parseSpec(fs.readFileSync(specPath, 'utf8')) : null;
-      const names = new Set((spec?.requirements ?? []).map((r) => r.name.toLowerCase()));
+      const byName = new Map((spec?.requirements ?? []).map((r) => [r.name.toLowerCase(), r]));
       for (const op of d.ops) {
-        if ((op.op === 'MODIFIED' || op.op === 'REMOVED') && !names.has(op.name.toLowerCase())) {
+        const target = byName.get(op.name.toLowerCase());
+        if ((op.op === 'MODIFIED' || op.op === 'REMOVED') && !target) {
           issues.push(issue(strict ? 'error' : 'warn', id,
             `${op.op} Requirement "${op.name}" not found in specs/${d.capability}/spec.md`));
+          continue;
+        }
+        // MODIFIED is a full replacement: report the scenarios it carries away
+        // before ship merges it. Always a warning — dropping a scenario can be
+        // the point of the change; doing it silently never is.
+        if (op.op === 'MODIFIED' && target) {
+          for (const msg of describeDrift(d.capability, op.name, scenarioDrift(target.body, op.body))) {
+            issues.push(issue('warn', id, msg));
+          }
         }
       }
     }

package/package.json

@@ -1,42 +1,42 @@
-{
-  "name": "@warnyin/sdlc",
-  "version": "0.5.1",
-  "description": "Spec-driven, AI-driven SDLC framework — token-lean specs, contract-first changes, autonomous pipeline with managed hooks. Operationalizes the Day-1 'New SDLC with Vibe Coding' work process.",
-  "type": "module",
-  "bin": {
-    "warnyin-sdlc": "bin/cli.mjs"
-  },
-  "files": [
-    "bin",
-    "lib",
-    "scripts",
-    "payload",
-    "README.md",
-    "CHANGELOG.md",
-    "LICENSE"
-  ],
-  "scripts": {
-    "test": "node --test",
-    "setup:dogfood": "node bin/cli.mjs init --tool claude && node bin/cli.mjs update"
-  },
-  "engines": {
-    "node": ">=20"
-  },
-  "publishConfig": {
-    "access": "public"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/warnyin/warnyin-sdlc.git"
-  },
-  "keywords": [
-    "sdlc",
-    "spec-driven",
-    "ai",
-    "agents",
-    "claude-code",
-    "context-engineering"
-  ],
-  "author": "warnyin",
-  "license": "MIT"
-}
+{
+  "name": "@warnyin/sdlc",
+  "version": "0.6.0",
+  "description": "Spec-driven, AI-driven SDLC framework — token-lean specs, contract-first changes, autonomous pipeline with managed hooks. Operationalizes the Day-1 'New SDLC with Vibe Coding' work process.",
+  "type": "module",
+  "bin": {
+    "warnyin-sdlc": "bin/cli.mjs"
+  },
+  "files": [
+    "bin",
+    "lib",
+    "scripts",
+    "payload",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test",
+    "setup:dogfood": "node bin/cli.mjs init --tool claude && node bin/cli.mjs update"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/warnyin/warnyin-sdlc.git"
+  },
+  "keywords": [
+    "sdlc",
+    "spec-driven",
+    "ai",
+    "agents",
+    "claude-code",
+    "context-engineering"
+  ],
+  "author": "warnyin",
+  "license": "MIT"
+}

package/payload/adapters/claude/skills/delta-spec-format/SKILL.md

@@ -29,5 +29,8 @@ Rules:
 - Observable behavior only; no class/function names, no implementation.
 - Every ADDED/MODIFIED requirement needs ≥1 scenario a test can be derived from.
 - Placeholders only (`<token>`, `user@example.com`) — never real secrets/PII.
+- MODIFIED replaces the whole body: a scenario the spec carries and your body
+  omits — or whose WHEN/THEN you rewrite — is reported by `validate` and `archive`
+  as a warning. Deliberate removals are fine; carry the rest over verbatim.
 - `npx @warnyin/sdlc archive <id>` merges deltas mechanically at ship; a missing
   key aborts the merge — never work around it by editing specs directly.

package/payload/adapters/claude/skills/sdlc-conventions/SKILL.md

@@ -1,26 +1,27 @@
----
-name: sdlc-conventions
-description: Cheat-sheet for the sdlc/ artifact layout, line caps, statuses, gates, and machine-owned files. Load when working with any file under sdlc/.
-user-invocable: false
----
-# sdlc/ conventions
-
-Layout: `config.yaml` · `context/{constitution.md, steering/*.md}` · `harness.md`
-· `specs/<capability>/spec.md` · `changes/<id>/{change.md, contract/, journal.ndjson}`
-· `changes/archive/<date>-<id>/` · `evals/<capability>/rubric.md` · `.state/` (machine).
-
-Line caps (validator-enforced; count = non-blank, non-comment body lines):
-constitution 30 · steering 40 each · always-budget 60 total · harness 60 ·
-change vibe/standard/deep 40/100/150 · tests.md 60 · evals.md 40 · spec soft 150.
-
-Frontmatter: `id` (= folder name) · `tier: vibe|standard|deep` ·
-`status: new|contracted|building|verified|shipped`.
-Steering: `inclusion: always|paths|manual|agent` (+ `pathMatch` for paths).
-
-Hard rules (hook-enforced):
-- `sdlc/specs/**` + `changes/archive/**`: writable only during an open ship gate.
-- `constitution.md`: writable only during an open steer gate.
-- `journal.ndjson` + `.state/**`: machine-owned, never hand-edit.
-
-Gates: `node sdlc/.hooks/journal.mjs open-ship <id> | open-steer | close | set-active <id> | note <name> [k=v]`.
-Validation: `npx @warnyin/sdlc validate [id] [--strict]` — red = the gate did not pass.
+---
+name: sdlc-conventions
+description: Cheat-sheet for the sdlc/ artifact layout, line caps, statuses, gates, and machine-owned files. Load when working with any file under sdlc/.
+user-invocable: false
+---
+# sdlc/ conventions
+
+Layout: `config.yaml` · `context/{constitution.md, steering/*.md}` · `harness.md`
+· `specs/<capability>/spec.md` · `changes/<id>/{change.md, contract/}`
+· telemetry: `.state/journal/<id>.ndjson` while open, sealed into the archived folder at ship
+· `changes/archive/<date>-<id>/` · `evals/<capability>/rubric.md` · `.state/` (machine).
+
+Line caps (validator-enforced; count = non-blank, non-comment body lines):
+constitution 30 · steering 40 each · always-budget 60 total · harness 60 ·
+change vibe/standard/deep 40/100/150 · tests.md 60 · evals.md 40 · spec soft 150.
+
+Frontmatter: `id` (= folder name) · `tier: vibe|standard|deep` ·
+`status: new|contracted|building|verified|shipped`.
+Steering: `inclusion: always|paths|manual|agent` (+ `pathMatch` for paths).
+
+Hard rules (hook-enforced):
+- `sdlc/specs/**` + `changes/archive/**`: writable only during an open ship gate.
+- `constitution.md`: writable only during an open steer gate.
+- `journal.ndjson` + `.state/**`: machine-owned, never hand-edit.
+
+Gates: `node sdlc/.hooks/journal.mjs open-ship <id> | open-steer | close | set-active <id> | note <name> [k=v]`.
+Validation: `npx @warnyin/sdlc validate [id] [--strict]` — red = the gate did not pass.

package/payload/hooks/_shared.mjs

@@ -7,6 +7,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import process from 'node:process';
 import { fileURLToPath } from 'node:url';
+import { liveJournalPath, globalJournalPath, appendEvent } from './lib/journal.mjs';
 
 export function resolveRoots(importMetaUrl) {
   const hooksDir = path.dirname(fileURLToPath(importMetaUrl));
@@ -135,20 +136,15 @@ export function activeChange(sdlcRoot) {
   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.
+// Journal: per-change ndjson when a change is active, else a global one — both under
+// .state/, which is gitignored, so a session never dirties a version-controlled file
+// just by running. Hook-written only — agents never hand-edit.
+//
+// Attribution does not depend on the change folder existing: a stale active pointer
+// still records the event under that id rather than silently reattributing it.
 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);
+    const target = (change && liveJournalPath(sdlcRoot, change)) || globalJournalPath(sdlcRoot);
+    appendEvent(target, { ts: new Date().toISOString(), ...event });
   } catch { /* 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/ship.md

@@ -1,33 +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>/`).
-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.