@warnyin/sdlc 0.6.0 → 0.7.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/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.7.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,29 @@
----
-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`.
+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

package/payload/hooks/guard-writes.mjs

@@ -14,11 +14,12 @@ import path from 'node:path';
 import {
   resolveRoots, readStdinJson, readPhase, activeChange, appendJournal, toPosixRel, lexicalPosixRel,
 } from './_shared.mjs';
+import { pickSessionId } from './lib/active.mjs';
 
 const { sdlcRoot, projectRoot } = resolveRoots(import.meta.url);
 
-function deny(reason, rel) {
-  appendJournal(sdlcRoot, activeChange(sdlcRoot), { event: 'guard', action: 'deny', path: rel, reason });
+function deny(reason, rel, sessionId) {
+  appendJournal(sdlcRoot, activeChange(sdlcRoot, sessionId), { event: 'guard', action: 'deny', path: rel, reason });
   console.log(JSON.stringify({
     hookSpecificOutput: {
       hookEventName: 'PreToolUse',
@@ -31,9 +32,9 @@ function deny(reason, rel) {
 // Evaluate the lock rules against ONE view of the path. Returns true when a
 // deny was emitted. Rules must hold for BOTH the lexical (claimed) and the
 // realpath-resolved view — a symlink must never weaken a lock.
-function guard(rel, phase) {
+function guard(rel, phase, sessionId) {
   if (rel.startsWith('sdlc/.state/') || rel.endsWith('journal.ndjson')) {
-    deny(`"${rel}" is machine-owned (hooks/CLI write it) — never edit it by hand.`, rel);
+    deny(`"${rel}" is machine-owned (hooks/CLI write it) — never edit it by hand.`, rel, sessionId);
     return true;
   }
   if (rel.startsWith('sdlc/specs/') || rel.startsWith('sdlc/changes/archive/')) {
@@ -42,6 +43,7 @@ function guard(rel, phase) {
       `"${rel}" is write-locked outside ship. Living specs change only by merging a change's Delta: `
       + 'run `warnyin-sdlc archive <id>` (or `node sdlc/.hooks/journal.mjs open-ship <id>` first if you must edit).',
       rel,
+      sessionId,
     );
     return true;
   }
@@ -51,6 +53,7 @@ function guard(rel, phase) {
       'The constitution is always-loaded context — edits go through /sdlc:steer '
       + '(`node sdlc/.hooks/journal.mjs open-steer` opens the gate).',
       rel,
+      sessionId,
     );
     return true;
   }
@@ -62,6 +65,7 @@ async function main() {
   const filePath = input?.tool_input?.file_path ?? input?.tool_input?.notebook_path;
   if (!filePath || !fs.existsSync(sdlcRoot)) return;
 
+  const sessionId = pickSessionId(input?.session_id, process.env.CLAUDE_CODE_SESSION_ID);
   const abs = path.resolve(projectRoot, filePath);
   const relLexical = lexicalPosixRel(projectRoot, abs);
   const relReal = toPosixRel(projectRoot, abs);
@@ -70,13 +74,13 @@ async function main() {
   // the project) went through a symlink — deny conservatively; a symlink must
   // never disable the write-lock.
   if (relLexical?.startsWith('sdlc/') && relReal !== relLexical) {
-    deny(`"${relLexical}" resolves through a symlink to "${relReal ?? 'outside the project'}" — refusing to touch it.`, relLexical);
+    deny(`"${relLexical}" resolves through a symlink to "${relReal ?? 'outside the project'}" — refusing to touch it.`, relLexical, sessionId);
     return;
   }
 
   const phase = readPhase(sdlcRoot);
   for (const rel of new Set([relLexical, relReal].filter(Boolean))) {
-    if (rel.startsWith('sdlc/') && guard(rel, phase)) return;
+    if (rel.startsWith('sdlc/') && guard(rel, phase, sessionId)) return;
   }
 }
 

package/payload/hooks/inject-context.mjs

@@ -10,12 +10,14 @@ import process from 'node:process';
 import { resolveRoots, readStdinJson, activeChange, appendJournal } from './_shared.mjs';
 import { parseFrontmatter } from './lib/frontmatter.mjs';
 import { CAPS } from './lib/caps.mjs';
+import { pickSessionId } from './lib/active.mjs';
 
 const { sdlcRoot } = resolveRoots(import.meta.url);
 
 async function main() {
-  await readStdinJson(); // drain; content not needed
+  const input = await readStdinJson();
   if (!fs.existsSync(sdlcRoot)) return;
+  const sessionId = pickSessionId(input?.session_id, process.env.CLAUDE_CODE_SESSION_ID);
 
   const injected = [];
   const out = [];
@@ -37,7 +39,7 @@ async function main() {
     }
   }
 
-  const active = activeChange(sdlcRoot);
+  const active = activeChange(sdlcRoot, sessionId);
   if (active) out.push(`Active change: sdlc/changes/${active}/change.md — run /sdlc:next for status.`);
 
   if (!out.length) return;

package/payload/hooks/journal.mjs

@@ -5,15 +5,15 @@
 //   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 sessions/events to a change
+//   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 fs from 'node:fs';
-import path from 'node:path';
 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);
 
@@ -36,19 +36,27 @@ async function main() {
   } else if (cmd === 'set-active') {
     const change = rest[0];
     if (!change) { console.error('usage: journal.mjs set-active <change-id>'); process.exit(2); }
-    fs.mkdirSync(path.join(sdlcRoot, '.state'), { recursive: true });
-    fs.writeFileSync(path.join(sdlcRoot, '.state', 'active.json'), JSON.stringify({ change }));
-    console.log(`active change: ${change}`);
+    // 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.
-    if (!process.stdin.isTTY) await readStdinJson();
+    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), { event: name, ...extra });
+    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);

package/payload/hooks/session-summary.mjs

@@ -10,6 +10,7 @@ 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);
 
@@ -30,7 +31,8 @@ async function main() {
   } catch { /* no config, no cost */ }
   const usd = costUsd(usage, prices);
 
-  const change = activeChange(sdlcRoot);
+  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,

package/payload/hooks/validate-artifact.mjs

@@ -14,6 +14,7 @@ import { resolveRoots, readStdinJson, activeChange, appendJournal, toPosixRel }
 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);
 
@@ -42,7 +43,9 @@ function steeringPointer(rel, sessionId) {
   const steeringDir = path.join(sdlcRoot, 'context', 'steering');
   if (!fs.existsSync(steeringDir)) return;
 
-  const safeSession = String(sessionId ?? '').replace(/[^A-Za-z0-9_-]/g, '') || 'nosession';
+  // 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 */ }
@@ -52,7 +55,7 @@ function steeringPointer(rel, sessionId) {
     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), { event: 'pointer', steering: f, file: rel });
+    appendJournal(sdlcRoot, activeChange(sdlcRoot, sessionId), { event: 'pointer', steering: f, file: rel });
     if (!seen.includes(f)) hits.push(f);
   }
   if (!hits.length) return;
@@ -73,8 +76,9 @@ async function main() {
   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, input?.session_id);
+  else steeringPointer(rel, sessionId);
 }
 
 main().catch(() => process.exit(0)); // fail open

package/payload/playbook/next.md

@@ -1,14 +1,24 @@
-# /sdlc:next — where am I, what now (read-only)
-
-1. Run `npx @warnyin/sdlc status`.
-2. For each active change map status → next command:
-   - `new` + markers unresolved → resolve questions (playbook new.md §5)
-   - `new` (clean) → /sdlc:design (deep/signal) or /sdlc:contract
-   - `contracted` → /sdlc:build
-   - `building` → /sdlc:build (finish open tasks)
-   - `verified` → /sdlc:review (if signals) or /sdlc:ship
-3. If nothing is active: suggest /sdlc:new, or /sdlc:observe if archived changes
-   have unread digests.
-4. Answer in ≤5 lines. Create or modify nothing.
-5. When the remaining path is more than one stage, add one line: the same command
-   with `--auto` confirms once and runs to ship.
+# /sdlc:next — where am I, what now (read-only)
+
+1. Run `npx @warnyin/sdlc status`.
+2. Answer for the current change first: the line marked `← this session`, or —
+   if none carries that marker — the line marked `← last set for project` (say
+   plainly it was last set for the project, not this session, and confirm
+   before acting on it as this session's work). Map that change's status to
+   the next command:
+   - `new` + markers unresolved → resolve questions (playbook new.md §5)
+   - `new` (clean) → /sdlc:design (deep/signal) or /sdlc:contract
+   - `contracted` → /sdlc:build
+   - `building` → /sdlc:build (finish open tasks)
+   - `verified` → /sdlc:review (if signals) or /sdlc:ship
+   Changes marked `(not this session)` are context only — mention them in at
+   most one line, never as this session's next command, never picked up. If the
+   human says this session is on a different change, their answer wins — use it,
+   and give them `node sdlc/.hooks/journal.mjs set-active <id>` so the next status agrees. If no
+   line carries any marker, list the open changes and ask which one this
+   session is on; do not choose for the human.
+3. If nothing is active: suggest /sdlc:new, or /sdlc:observe if archived changes
+   have unread digests.
+4. Answer in ≤5 lines. Create or modify nothing.
+5. When the remaining path is more than one stage, add one line: the same command
+   with `--auto` confirms once and runs to ship.