@warnyin/sdlc 0.5.2 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # 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,

package/LICENSE

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

@@ -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`);
 
@@ -510,10 +529,36 @@ 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) {

package/lib/caps.mjs

@@ -1,45 +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;
-}
+// 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

@@ -1,41 +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;
-}
+// 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;
+}