@warnyin/sdlc 0.6.0 → 0.8.0

package/lib/active.mjs

@@ -0,0 +1,199 @@
+// Active change — which change a session (and the project as a whole) is working on.
+//
+// Two pointers exist so two sessions never overwrite each other's focus: a per-session
+// file under `.state/sessions/<id>.json`, and a project-wide fallback at `.state/active.json`
+// for tools (and past sessions) that never set one. Resolution tries session, then
+// project, then the most-recently-edited open change — never an error: a pointer that
+// is missing, stale, or malformed just falls through to the next source.
+//
+// Shared by the CLI and the installed hooks, so `node:*` only.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { isSafeChangeId } from './journal.mjs';
+
+// A session id reaches us from `CLAUDE_CODE_SESSION_ID` (shell) or stdin `session_id`
+// (hooks) — both outside our control. It becomes a filename, so it is held to the same
+// single-safe-segment rule as a change id rather than a separate one: two id kinds, one
+// hazard (path traversal / device names / ADS colons), one rule to keep in sync.
+export function isSafeSessionId(id) {
+  return isSafeChangeId(id);
+}
+
+// stdin is the documented, per-invocation channel; the env var is inherited from a
+// parent process and may be stale or belong to someone else. No safety check here —
+// this is a raw pick, the caller validates before turning it into a path.
+export function pickSessionId(stdinSessionId, envSessionId) {
+  if (typeof stdinSessionId === 'string' && stdinSessionId.length > 0) return stdinSessionId;
+  if (typeof envSessionId === 'string' && envSessionId.length > 0) return envSessionId;
+  return null;
+}
+
+// `null` for an unsafe id, so callers fall back to the project pointer instead of
+// writing or reading somewhere surprising.
+export function sessionPointerPath(sdlcRoot, sessionId) {
+  if (!isSafeSessionId(sessionId)) return null;
+  return path.join(sdlcRoot, '.state', 'sessions', `${sessionId}.json`);
+}
+
+export function projectPointerPath(sdlcRoot) {
+  return path.join(sdlcRoot, '.state', 'active.json');
+}
+
+// One rule for "this id names an open change", used both when a pointer is read and before
+// one is written: a single safe segment, not the archive folder in any case (`ARCHIVE` opens
+// it on Windows and macOS), and a folder that exists.
+export function isOpenChange(sdlcRoot, change) {
+  if (typeof change !== 'string' || change.toLowerCase() === 'archive' || !isSafeChangeId(change)) return false;
+  try {
+    return fs.statSync(path.join(sdlcRoot, 'changes', change)).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+// A pointer path is trusted only when its real location is the one it claims. `.state/` is
+// gitignored but not unwritable — a repo can ship a link there — and a planted link at
+// `.state`, `.state/sessions` or the pointer file itself would otherwise carry a read or a
+// write out of the project. Missing paths fail too; callers only ask about existing ones.
+function isRealPathInside(sdlcRoot, target) {
+  try {
+    const expected = path.join(fs.realpathSync.native(sdlcRoot), path.relative(sdlcRoot, target));
+    return fs.realpathSync.native(target) === expected;
+  } catch {
+    return false;
+  }
+}
+
+// Reads a pointer file and returns the change id it names, or null if the file is
+// missing, malformed, names something unsafe/archived, the change folder is gone, or the
+// file is not really where it claims to be. A stale, corrupt or redirected pointer must
+// never throw — it is just evidence the caller ignores.
+function readPointerChange(sdlcRoot, filePath) {
+  if (!filePath || !isRealPathInside(sdlcRoot, filePath)) return null;
+  try {
+    const data = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+    return isOpenChange(sdlcRoot, data?.change) ? data.change : null;
+  } catch {
+    return null;
+  }
+}
+
+// The last-resort source: no pointer answers, so fall back to whichever open change was
+// touched most recently. Never reported as this session's or the project's own choice.
+function mostRecentOpenChange(sdlcRoot) {
+  const changesDir = path.join(sdlcRoot, 'changes');
+  let entries;
+  try {
+    entries = fs.readdirSync(changesDir, { withFileTypes: true });
+  } catch {
+    return null;
+  }
+  let best = null;
+  for (const d of entries) {
+    if (!d.isDirectory() || d.name === 'archive') continue;
+    const p = path.join(changesDir, d.name, 'change.md');
+    let mtime;
+    try {
+      mtime = fs.statSync(p).mtimeMs;
+    } catch {
+      continue;
+    }
+    if (!best || mtime > best.mtime) best = { change: d.name, mtime };
+  }
+  return best?.change ?? null;
+}
+
+// Session pointer, then project pointer, then the most-recently-edited open change.
+// Fails open at every step: a thrown error anywhere resolves to null rather than
+// surfacing to a hook, which must never block a session over a state-file glitch.
+export function resolveActive(sdlcRoot, { sessionId } = {}) {
+  try {
+    if (isSafeSessionId(sessionId)) {
+      const change = readPointerChange(sdlcRoot, sessionPointerPath(sdlcRoot, sessionId));
+      if (change) return { change, source: 'session' };
+    }
+    const projectChange = readPointerChange(sdlcRoot, projectPointerPath(sdlcRoot));
+    if (projectChange) return { change: projectChange, source: 'project' };
+    const recent = mostRecentOpenChange(sdlcRoot);
+    if (recent) return { change: recent, source: 'recent' };
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+// Creates `dir` one segment at a time below `sdlcRoot`, checking each segment before the
+// next is made: a recursive mkdir would first create `sessions/` inside whatever a planted
+// `.state` link points at, and only then could the check notice.
+function ensureRealDir(sdlcRoot, dir) {
+  let cur = sdlcRoot;
+  for (const seg of path.relative(sdlcRoot, dir).split(path.sep)) {
+    cur = path.join(cur, seg);
+    if (!hasEntry(cur)) fs.mkdirSync(cur);
+    if (!isRealPathInside(sdlcRoot, cur)) return false;
+  }
+  return true;
+}
+
+// Whether ANY directory entry sits at `p`, dangling links included. `existsSync` follows the
+// link and reports a dangling one as absent — and `writeFileSync` would then create the
+// link's target, wherever it points.
+function hasEntry(p) {
+  try {
+    fs.lstatSync(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// Writes one pointer, refusing when its directory — or any entry already at the path,
+// dangling link included — is really somewhere else. `writeFileSync` follows links, so the
+// check has to come first.
+function writePointer(sdlcRoot, filePath, change) {
+  try {
+    if (!ensureRealDir(sdlcRoot, path.dirname(filePath))) return false;
+    if (hasEntry(filePath) && !isRealPathInside(sdlcRoot, filePath)) return false;
+    fs.writeFileSync(filePath, JSON.stringify({ change }));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// Writes the project-wide fallback, and the session pointer only when the id is safe, so
+// an unsafe id can never cause a file to be created anywhere. A redirected `.state` or
+// `.state/sessions` makes the matching write a no-op rather than a write out of the project.
+export function writeActive(sdlcRoot, change, { sessionId } = {}) {
+  const project = writePointer(sdlcRoot, projectPointerPath(sdlcRoot), change);
+  const sessionPath = sessionPointerPath(sdlcRoot, sessionId);
+  const session = sessionPath ? writePointer(sdlcRoot, sessionPath, change) : false;
+  return { project, session };
+}
+
+// Releases every pointer naming `changeId`. Called at ship, after the folder has moved, so the
+// id no longer resolves and is matched by name instead. Only real files inside `.state/` are
+// read or removed — a planted link is left alone, never followed. Never throws: the ship has
+// already happened by the time this runs.
+export function clearPointersFor(sdlcRoot, changeId) {
+  const candidates = [projectPointerPath(sdlcRoot)];
+  const sessionsDir = path.join(sdlcRoot, '.state', 'sessions');
+  if (isRealPathInside(sdlcRoot, sessionsDir)) {
+    try {
+      for (const f of fs.readdirSync(sessionsDir)) {
+        if (f.endsWith('.json')) candidates.push(path.join(sessionsDir, f));
+      }
+    } catch { /* nothing to release */ }
+  }
+  let released = 0;
+  for (const p of candidates) {
+    try {
+      if (!isRealPathInside(sdlcRoot, p)) continue;
+      if (JSON.parse(fs.readFileSync(p, 'utf8'))?.change !== changeId) continue;
+      fs.rmSync(p);
+      released += 1;
+    } catch { /* missing, malformed or vanished — leave it */ }
+  }
+  return released;
+}

package/lib/caps.mjs

@@ -16,6 +16,7 @@ export const CAPS = Object.freeze({
   change: Object.freeze({ vibe: 40, standard: 100, deep: 150 }),
   contractTests: 60,    // changes/<id>/contract/tests.md
   contractEvals: 40,    // changes/<id>/contract/evals.md
+  lensCatalog: 60,      // payload/playbook/lenses.md — read by /sdlc:new on every change
 });
 
 export const TIERS = Object.freeze(['vibe', 'standard', 'deep']);

package/lib/lenses.mjs

@@ -0,0 +1,48 @@
+// Canonical lens list — the single source of truth for which expert lenses a change may
+// record. `payload/playbook/lenses.md` describes each one under `## Lens: <name>`, and
+// tests/lenses.test.mjs fails the build if the two drift.
+//
+// A change records lenses in frontmatter as `<lens>@builtin`, `<lens>@project:<skill>` or
+// `<lens>@user:<skill>`; the skill name uses the inventory's own name rule, so whatever
+// `warnyin-sdlc skills` lists is exactly what a change can record.
+
+// Names are only ever added: removing or renaming one turns open changes that recorded it
+// into validation errors, so that needs a migration, not an edit here.
+//
+// SKILL_NAME_RE is owned here (not by the inventory) so the validator, which hooks load on
+// every write, does not pull in filesystem scanning. `.` and `..` are refused so a recorded
+// name can never be a path hop.
+export const SKILL_NAME_RE = /^(?!\.{1,2}$)[A-Za-z0-9._-]{1,64}$/;
+
+export const LENSES = Object.freeze(['ux-ui', 'api', 'data']);
+
+const ENTRY_RE = /^([^@\s]+)@(builtin|project:(.*)|user:(.*))$/;
+
+// Returns error strings, each naming the offending entry. An absent or empty list is valid:
+// no lens means no stage loads one.
+export function lensErrors(value) {
+  if (value === undefined) return [];
+  if (!Array.isArray(value)) return [`lenses must be a list, got "${value}"`];
+  const errors = [];
+  const seen = new Set();
+  for (const raw of value) {
+    const entry = String(raw);
+    const m = entry.match(ENTRY_RE);
+    if (!m) {
+      errors.push(`lens entry "${entry}" must be <lens>@builtin, <lens>@project:<skill> or <lens>@user:<skill>`);
+      continue;
+    }
+    const [, lens, , projectSkill, userSkill] = m;
+    const skill = projectSkill ?? userSkill;
+    if (!LENSES.includes(lens)) {
+      errors.push(`lens entry "${entry}" names unknown lens "${lens}" (catalog: ${LENSES.join('|')})`);
+    } else if (seen.has(lens)) {
+      errors.push(`lens "${lens}" is recorded more than once — keep one source per lens`);
+    }
+    if (skill !== undefined && !SKILL_NAME_RE.test(skill)) {
+      errors.push(`lens entry "${entry}" has an invalid skill name (allowed: ${SKILL_NAME_RE.source})`);
+    }
+    seen.add(lens);
+  }
+  return errors;
+}

package/lib/skills.mjs

@@ -0,0 +1,148 @@
+// Skill/agent inventory — what expertise is already installed for this project and user.
+// Used by: CLI (`warnyin-sdlc skills`), which the opening playbook reads to resolve lenses.
+//
+// Skill files are third-party content, so the inventory is deliberately shallow: it reads a
+// bounded prefix of each file, keeps only frontmatter `name` + `description`, and never
+// emits body text. Project entries whose real location leaves the project are skipped (a
+// repo can ship a link); the user's own home may link wherever the user put their skills.
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { parseFrontmatter } from './frontmatter.mjs';
+import { containedIn } from './manifest.mjs';
+import { SKILL_NAME_RE } from './lenses.mjs';
+
+export { SKILL_NAME_RE };
+export const INVENTORY_CEILING = 200;
+// Per-directory bound on how many candidates are opened at all: a checked-out repo can plant
+// thousands of folders, and the ceiling alone would still pay to read every one of them.
+export const SCAN_LIMIT_PER_DIR = 1000;
+export const DESCRIPTION_MAX = 160;
+export const READ_PREFIX_BYTES = 8 * 1024;
+
+const KINDS = Object.freeze(['skill', 'agent']);
+// Built from code points so the source file itself carries no invisible characters: C0, DEL,
+// C1, zero-width and bidi marks/overrides, line/paragraph separators, BOM — anything that
+// can move a terminal cursor or visually reorder the line a human or model reads.
+const cp = (n) => String.fromCharCode(n);
+const CONTROL_CHARS = new RegExp(
+  `[${cp(0)}-${cp(0x1f)}${cp(0x7f)}-${cp(0x9f)}${cp(0x200b)}-${cp(0x200f)}${cp(0x2028)}-${cp(0x202e)}${cp(0x2066)}-${cp(0x2069)}${cp(0xfeff)}]+`,
+  'g');
+const LEADING_BOM = new RegExp(`^${String.fromCharCode(0xfeff)}`);
+
+// Reads at most READ_PREFIX_BYTES; a frontmatter that does not close inside that prefix is
+// treated as absent rather than read further. The open is non-blocking where the platform
+// has it, and the descriptor itself must be a regular file, so a FIFO or device swapped in
+// after the earlier checks can neither hang nor feed the read.
+function readPrefix(file) {
+  let fd;
+  try {
+    fd = fs.openSync(file, fs.constants.O_RDONLY | (fs.constants.O_NONBLOCK ?? 0));
+    if (!fs.fstatSync(fd).isFile()) return null;
+    const buf = Buffer.alloc(READ_PREFIX_BYTES);
+    const n = fs.readSync(fd, buf, 0, READ_PREFIX_BYTES, 0);
+    return buf.subarray(0, n).toString('utf8').replace(LEADING_BOM, '');
+  } catch {
+    return null;
+  } finally {
+    if (fd !== undefined) fs.closeSync(fd);
+  }
+}
+
+// One line, no control characters (terminal escapes included), cut with a visible marker.
+export function cleanDescription(raw) {
+  const flat = String(raw).replace(CONTROL_CHARS, ' ').replace(/\s+/g, ' ').trim();
+  if (flat.length <= DESCRIPTION_MAX) return { description: flat, truncated: false };
+  return { description: `${flat.slice(0, DESCRIPTION_MAX - 1).trimEnd()}…`, truncated: true };
+}
+
+function readEntry(file) {
+  const text = readPrefix(file);
+  if (text === null) return null;
+  const { data } = parseFrontmatter(text);
+  const name = typeof data.name === 'string' ? data.name.trim() : '';
+  if (!SKILL_NAME_RE.test(name)) return null;
+  if (typeof data.description !== 'string' || data.description.trim() === '') return null;
+  return { name, ...cleanDescription(data.description) };
+}
+
+function isInside(rootReal, target) {
+  try {
+    return containedIn(rootReal, fs.realpathSync.native(target));
+  } catch {
+    return false;
+  }
+}
+
+// The first SCAN_LIMIT_PER_DIR names (sorted), and how many were left unopened.
+function listDir(dir) {
+  let names;
+  try {
+    names = fs.readdirSync(dir).sort();
+  } catch {
+    return { names: [], unscanned: 0 };
+  }
+  return { names: names.slice(0, SCAN_LIMIT_PER_DIR), unscanned: Math.max(0, names.length - SCAN_LIMIT_PER_DIR) };
+}
+
+function isFile(p) {
+  try { return fs.statSync(p).isFile(); } catch { return false; }
+}
+
+// Candidate files for one `.claude` root, each paired with every path that must stay contained.
+function candidates(claudeDir, kind) {
+  if (kind === 'skill') {
+    const skillsDir = path.join(claudeDir, 'skills');
+    const { names, unscanned } = listDir(skillsDir);
+    const items = names.map((d) => {
+      const folder = path.join(skillsDir, d);
+      const file = path.join(folder, 'SKILL.md');
+      return { file, checks: [folder, file] };
+    });
+    return { items, unscanned };
+  }
+  const agentsDir = path.join(claudeDir, 'agents');
+  const { names, unscanned } = listDir(agentsDir);
+  const items = names
+    .filter((f) => f.endsWith('.md'))
+    .map((f) => ({ file: path.join(agentsDir, f), checks: [path.join(agentsDir, f)] }));
+  return { items, unscanned };
+}
+
+function scanRoot(claudeDir, source, containRoot) {
+  const entries = [];
+  let unscanned = 0;
+  for (const kind of KINDS) {
+    const found = candidates(claudeDir, kind);
+    unscanned += found.unscanned;
+    for (const { file, checks } of found.items) {
+      if (containRoot && !checks.every((c) => isInside(containRoot, c))) continue;
+      if (!isFile(file)) continue;
+      const entry = readEntry(file);
+      if (entry) entries.push({ source, kind, ...entry });
+    }
+  }
+  entries.sort((a, b) => KINDS.indexOf(a.kind) - KINDS.indexOf(b.kind) || a.name.localeCompare(b.name));
+  return { entries, unscanned };
+}
+
+export function scanInventory(projectRoot, { home = os.homedir() } = {}) {
+  let projectReal = null;
+  try { projectReal = fs.realpathSync.native(projectRoot); } catch { /* unreadable root → no project entries */ }
+  const none = { entries: [], unscanned: 0 };
+  const project = projectReal ? scanRoot(path.join(projectRoot, '.claude'), 'project', projectReal) : none;
+  const user = home ? scanRoot(path.join(home, '.claude'), 'user', null) : none;
+  const all = [...project.entries, ...user.entries];
+  // `omitted` = valid entries past the ceiling + candidates never opened (scan limit).
+  return {
+    entries: all.slice(0, INVENTORY_CEILING),
+    omitted: Math.max(0, all.length - INVENTORY_CEILING) + project.unscanned + user.unscanned,
+  };
+}
+
+export function renderInventory({ entries, omitted }) {
+  const lines = entries.map((e) => `${e.source}  ${e.kind}  ${e.name}  ${e.description}`);
+  if (omitted > 0) lines.push(`… ${omitted} more not listed`);
+  return lines.join('\n');
+}

package/lib/validate.mjs

@@ -7,6 +7,7 @@ import path from 'node:path';
 import { parseFrontmatter } from './frontmatter.mjs';
 import { CAPS, TIERS, STATUSES, countEffectiveLines, capForChange } from './caps.mjs';
 import { parseDelta, parseSpec, scenarioDrift, describeDrift } from './delta.mjs';
+import { lensErrors } from './lenses.mjs';
 
 const CLARIFICATION_RE = /\[NEEDS CLARIFICATION/g;
 
@@ -35,6 +36,7 @@ export function validateChange(changeDir, { strict = false, specsDir = null } =
   else if (data.id !== id) issues.push(issue('error', id, `frontmatter id "${data.id}" != folder name "${id}"`));
   if (!TIERS.includes(data.tier)) issues.push(issue('error', id, `frontmatter: tier must be one of ${TIERS.join('|')}`));
   if (!STATUSES.includes(data.status)) issues.push(issue('error', id, `frontmatter: status must be one of ${STATUSES.join('|')}`));
+  for (const msg of lensErrors(data.lenses)) issues.push(issue('error', id, `frontmatter: ${msg}`));
 
   const tier = TIERS.includes(data.tier) ? data.tier : 'standard';
   const status = STATUSES.includes(data.status) ? data.status : 'new';

package/package.json

@@ -1,42 +1,42 @@
-{
-  "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"
-}
+{
+  "name": "@warnyin/sdlc",
+  "version": "0.8.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/sdlc-conventions/SKILL.md

@@ -1,27 +1,30 @@
----
-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.
+---
+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)
+· `.state/sessions/<sid>.json` (this session's active-change pointer; `.state/active.json` is the project-wide fallback).
+
+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` · optional
+`lenses: [<ux-ui|api|data>@builtin | @project:<skill> | @user:<skill>]` (see `.playbook/lenses.md`).
+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> (sets this session's pointer + the project fallback) | note <name> [k=v]`.
+Validation: `npx @warnyin/sdlc validate [id] [--strict]` — red = the gate did not pass.

package/payload/hooks/_shared.mjs

@@ -8,6 +8,7 @@ import path from 'node:path';
 import process from 'node:process';
 import { fileURLToPath } from 'node:url';
 import { liveJournalPath, globalJournalPath, appendEvent } from './lib/journal.mjs';
+import { resolveActive } from './lib/active.mjs';
 
 export function resolveRoots(importMetaUrl) {
   const hooksDir = path.dirname(fileURLToPath(importMetaUrl));
@@ -114,26 +115,13 @@ export function clearPhase(sdlcRoot) {
   fs.rmSync(path.join(sdlcRoot, '.state', 'phase.json'), { force: true });
 }
 
-// Active change: explicit .state/active.json first, else the most recently
-// modified changes/*/change.md.
-export function activeChange(sdlcRoot) {
-  try {
-    const explicit = JSON.parse(fs.readFileSync(path.join(sdlcRoot, '.state', 'active.json'), 'utf8'));
-    if (explicit?.change && fs.existsSync(path.join(sdlcRoot, 'changes', explicit.change))) {
-      return explicit.change;
-    }
-  } catch { /* fall through */ }
-  const changesDir = path.join(sdlcRoot, 'changes');
-  if (!fs.existsSync(changesDir)) return null;
-  let best = null;
-  for (const d of fs.readdirSync(changesDir, { withFileTypes: true })) {
-    if (!d.isDirectory() || d.name === 'archive') continue;
-    const p = path.join(changesDir, d.name, 'change.md');
-    if (!fs.existsSync(p)) continue;
-    const mtime = fs.statSync(p).mtimeMs;
-    if (!best || mtime > best.mtime) best = { change: d.name, mtime };
-  }
-  return best?.change ?? null;
+// Active change: session pointer, then project pointer, then the most recently
+// modified changes/*/change.md — resolution lives in lib/active.mjs so the CLI's
+// `status` answers the same question the hooks do. Callers still get just the id
+// (the `recent` fallback still attributes hook events, it just isn't reported as
+// confirmed by `status`).
+export function activeChange(sdlcRoot, sessionId = null) {
+  return resolveActive(sdlcRoot, { sessionId })?.change ?? null;
 }
 
 // Journal: per-change ndjson when a change is active, else a global one — both under