@warnyin/sdlc 0.8.0 → 0.10.0

package/payload/hooks/_shared.mjs

@@ -1,138 +1,138 @@
-// Shared plumbing for installed hooks. This file lives at
-// <project>/sdlc/.hooks/_shared.mjs with lib/ as a sibling directory.
-// Every hook must be fail-open: on any unexpected condition, exit 0 silently
-// so the harness is never blocked by our tooling.
-
-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';
-import { resolveActive } from './lib/active.mjs';
-
-export function resolveRoots(importMetaUrl) {
-  const hooksDir = path.dirname(fileURLToPath(importMetaUrl));
-  const sdlcRoot = path.dirname(hooksDir);
-  const projectRoot = path.dirname(sdlcRoot);
-  return { hooksDir, sdlcRoot, projectRoot };
-}
-
-// Reads the hook payload from stdin. Must NEVER hang: when a playbook or a
-// user script invokes a hook utility with stdin open-but-idle (no piped JSON),
-// resolve null after a short grace period instead of blocking forever.
-export function readStdinJson({ timeoutMs = 1000 } = {}) {
-  return new Promise((resolve) => {
-    let data = '';
-    let done = false;
-    const finish = () => {
-      if (done) return;
-      done = true;
-      // Release stdin so an open-idle stream cannot keep the event loop alive.
-      process.stdin.pause();
-      if (typeof process.stdin.unref === 'function') process.stdin.unref();
-      try { resolve(data.trim() ? JSON.parse(data) : null); } catch { resolve(null); }
-    };
-    const timer = setTimeout(finish, timeoutMs);
-    if (typeof timer.unref === 'function') timer.unref();
-    process.stdin.on('data', (chunk) => { data += chunk; });
-    process.stdin.on('end', finish);
-    process.stdin.on('error', finish);
-  });
-}
-
-// Resolve symlinks on the deepest EXISTING ancestor, then re-attach the tail.
-// Needed because import.meta.url is symlink-resolved while tool file_paths may
-// arrive through a symlink (/tmp → /private/tmp on macOS).
-export function realResolve(p) {
-  let cur = path.resolve(p);
-  const tail = [];
-  while (!fs.existsSync(cur)) {
-    const parent = path.dirname(cur);
-    if (parent === cur) break;
-    tail.unshift(path.basename(cur));
-    cur = parent;
-  }
-  try { cur = fs.realpathSync.native(cur); } catch { /* keep as-is */ }
-  return tail.length ? path.join(cur, ...tail) : cur;
-}
-
-export function toPosixRel(projectRoot, absPath) {
-  const rel = path.relative(realResolve(projectRoot), realResolve(absPath));
-  if (rel.startsWith('..')) return null;
-  return rel.split(path.sep).join('/');
-}
-
-// Lexical (no-symlink-resolution) relative path: what the path CLAIMS to be.
-// Tried against both the raw and the realpathed project root so /tmp-style
-// root symlinks don't break matching. Guards must compare this against
-// toPosixRel — a divergence means a symlink sits inside the project.
-export function lexicalPosixRel(projectRoot, absPath) {
-  const abs = path.resolve(absPath);
-  const realRoot = realResolve(projectRoot);
-  for (const base of [path.resolve(projectRoot), realRoot]) {
-    const rel = path.relative(base, abs);
-    if (rel && !rel.startsWith('..') && !path.isAbsolute(rel)) {
-      return rel.split(path.sep).join('/');
-    }
-  }
-  // Root-level symlinks (/tmp → /private/tmp): find the SHALLOWEST ancestor of
-  // abs whose realpath IS the project root; the remaining tail is the lexical
-  // claim. In-project symlinks are deliberately not resolved here.
-  const segs = abs.split(path.sep);
-  for (let i = 1; i < segs.length; i++) {
-    const ancestor = segs.slice(0, i).join(path.sep) || path.sep;
-    let real;
-    try { real = fs.realpathSync.native(ancestor); } catch { continue; }
-    if (real === realRoot) {
-      const tail = segs.slice(i).join('/');
-      return tail || null;
-    }
-  }
-  return null;
-}
-
-// Gate state written by `journal.mjs open-<phase>` — {phase, change?, expires}.
-export function readPhase(sdlcRoot) {
-  try {
-    const raw = fs.readFileSync(path.join(sdlcRoot, '.state', 'phase.json'), 'utf8');
-    const phase = JSON.parse(raw);
-    if (phase.expires && Date.parse(phase.expires) < Date.now()) return null;
-    return phase;
-  } catch {
-    return null;
-  }
-}
-
-export function writePhase(sdlcRoot, phase, ttlMinutes = 30) {
-  const stateDir = path.join(sdlcRoot, '.state');
-  fs.mkdirSync(stateDir, { recursive: true });
-  const payload = { ...phase, expires: new Date(Date.now() + ttlMinutes * 60_000).toISOString() };
-  fs.writeFileSync(path.join(stateDir, 'phase.json'), JSON.stringify(payload));
-  return payload;
-}
-
-export function clearPhase(sdlcRoot) {
-  fs.rmSync(path.join(sdlcRoot, '.state', 'phase.json'), { force: true });
-}
-
-// 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
-// .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 target = (change && liveJournalPath(sdlcRoot, change)) || globalJournalPath(sdlcRoot);
-    appendEvent(target, { ts: new Date().toISOString(), ...event });
-  } catch { /* fail open */ }
-}
+// Shared plumbing for installed hooks. This file lives at
+// <project>/sdlc/.hooks/_shared.mjs with lib/ as a sibling directory.
+// Every hook must be fail-open: on any unexpected condition, exit 0 silently
+// so the harness is never blocked by our tooling.
+
+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';
+import { resolveActive } from './lib/active.mjs';
+
+export function resolveRoots(importMetaUrl) {
+  const hooksDir = path.dirname(fileURLToPath(importMetaUrl));
+  const sdlcRoot = path.dirname(hooksDir);
+  const projectRoot = path.dirname(sdlcRoot);
+  return { hooksDir, sdlcRoot, projectRoot };
+}
+
+// Reads the hook payload from stdin. Must NEVER hang: when a playbook or a
+// user script invokes a hook utility with stdin open-but-idle (no piped JSON),
+// resolve null after a short grace period instead of blocking forever.
+export function readStdinJson({ timeoutMs = 1000 } = {}) {
+  return new Promise((resolve) => {
+    let data = '';
+    let done = false;
+    const finish = () => {
+      if (done) return;
+      done = true;
+      // Release stdin so an open-idle stream cannot keep the event loop alive.
+      process.stdin.pause();
+      if (typeof process.stdin.unref === 'function') process.stdin.unref();
+      try { resolve(data.trim() ? JSON.parse(data) : null); } catch { resolve(null); }
+    };
+    const timer = setTimeout(finish, timeoutMs);
+    if (typeof timer.unref === 'function') timer.unref();
+    process.stdin.on('data', (chunk) => { data += chunk; });
+    process.stdin.on('end', finish);
+    process.stdin.on('error', finish);
+  });
+}
+
+// Resolve symlinks on the deepest EXISTING ancestor, then re-attach the tail.
+// Needed because import.meta.url is symlink-resolved while tool file_paths may
+// arrive through a symlink (/tmp → /private/tmp on macOS).
+export function realResolve(p) {
+  let cur = path.resolve(p);
+  const tail = [];
+  while (!fs.existsSync(cur)) {
+    const parent = path.dirname(cur);
+    if (parent === cur) break;
+    tail.unshift(path.basename(cur));
+    cur = parent;
+  }
+  try { cur = fs.realpathSync.native(cur); } catch { /* keep as-is */ }
+  return tail.length ? path.join(cur, ...tail) : cur;
+}
+
+export function toPosixRel(projectRoot, absPath) {
+  const rel = path.relative(realResolve(projectRoot), realResolve(absPath));
+  if (rel.startsWith('..')) return null;
+  return rel.split(path.sep).join('/');
+}
+
+// Lexical (no-symlink-resolution) relative path: what the path CLAIMS to be.
+// Tried against both the raw and the realpathed project root so /tmp-style
+// root symlinks don't break matching. Guards must compare this against
+// toPosixRel — a divergence means a symlink sits inside the project.
+export function lexicalPosixRel(projectRoot, absPath) {
+  const abs = path.resolve(absPath);
+  const realRoot = realResolve(projectRoot);
+  for (const base of [path.resolve(projectRoot), realRoot]) {
+    const rel = path.relative(base, abs);
+    if (rel && !rel.startsWith('..') && !path.isAbsolute(rel)) {
+      return rel.split(path.sep).join('/');
+    }
+  }
+  // Root-level symlinks (/tmp → /private/tmp): find the SHALLOWEST ancestor of
+  // abs whose realpath IS the project root; the remaining tail is the lexical
+  // claim. In-project symlinks are deliberately not resolved here.
+  const segs = abs.split(path.sep);
+  for (let i = 1; i < segs.length; i++) {
+    const ancestor = segs.slice(0, i).join(path.sep) || path.sep;
+    let real;
+    try { real = fs.realpathSync.native(ancestor); } catch { continue; }
+    if (real === realRoot) {
+      const tail = segs.slice(i).join('/');
+      return tail || null;
+    }
+  }
+  return null;
+}
+
+// Gate state written by `journal.mjs open-<phase>` — {phase, change?, expires}.
+export function readPhase(sdlcRoot) {
+  try {
+    const raw = fs.readFileSync(path.join(sdlcRoot, '.state', 'phase.json'), 'utf8');
+    const phase = JSON.parse(raw);
+    if (phase.expires && Date.parse(phase.expires) < Date.now()) return null;
+    return phase;
+  } catch {
+    return null;
+  }
+}
+
+export function writePhase(sdlcRoot, phase, ttlMinutes = 30) {
+  const stateDir = path.join(sdlcRoot, '.state');
+  fs.mkdirSync(stateDir, { recursive: true });
+  const payload = { ...phase, expires: new Date(Date.now() + ttlMinutes * 60_000).toISOString() };
+  fs.writeFileSync(path.join(stateDir, 'phase.json'), JSON.stringify(payload));
+  return payload;
+}
+
+export function clearPhase(sdlcRoot) {
+  fs.rmSync(path.join(sdlcRoot, '.state', 'phase.json'), { force: true });
+}
+
+// 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
+// .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 target = (change && liveJournalPath(sdlcRoot, change)) || globalJournalPath(sdlcRoot);
+    appendEvent(target, { ts: new Date().toISOString(), ...event });
+  } catch { /* fail open */ }
+}

package/payload/hooks/_update-notice.mjs

@@ -0,0 +1,81 @@
+// SessionStart side of the update notice: reads the cached check, and when it is due records
+// the attempt and hands the network request to a detached `check-update.mjs`. Never waits on
+// the network and never throws — any failure means no notice.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import process from 'node:process';
+import { spawn } from 'node:child_process';
+import { parseConfig } from './lib/config.mjs';
+import { parseVersion } from './lib/version.mjs';
+import { isCheckDisabled, isCheckDue, noticeLine } from './lib/update-notice.mjs';
+
+export const cachePath = (sdlcRoot) => path.join(sdlcRoot, '.state', 'update-check.json');
+
+export function readJsonFile(p) {
+  try { return JSON.parse(fs.readFileSync(p, 'utf8')); } catch { return null; }
+}
+
+// `.state/` is gitignored, not unwritable: a repo can ship a link there. Write only into a
+// `.state/` that already exists and really is `<sdlcRoot>/.state` (same rule as the change
+// pointers in lib/active.mjs); never create it, so a deleted project is not resurrected.
+function isRealStateDir(sdlcRoot) {
+  try {
+    const stateDir = path.join(sdlcRoot, '.state');
+    return fs.lstatSync(stateDir).isDirectory()
+      && fs.realpathSync.native(stateDir) === path.join(fs.realpathSync.native(sdlcRoot), '.state');
+  } catch {
+    return false;
+  }
+}
+
+// Temp file + rename: a symlink at the destination is replaced rather than written through,
+// and a concurrent reader sees the old file or the new one, never half of either.
+export function writeCache(sdlcRoot, value) {
+  const p = cachePath(sdlcRoot);
+  if (!isRealStateDir(sdlcRoot)) return false;
+  const tmp = `${p}.${process.pid}.${Date.now()}.tmp`;
+  try {
+    fs.writeFileSync(tmp, JSON.stringify(value), { flag: 'wx' });
+    fs.renameSync(tmp, p);
+    return true;
+  } catch {
+    fs.rmSync(tmp, { force: true });
+    return false;
+  }
+}
+
+function readConfig(sdlcRoot) {
+  try { return parseConfig(fs.readFileSync(path.join(sdlcRoot, 'config.yaml'), 'utf8')); } catch { return {}; }
+}
+
+// The checker talks to a third-party host; it gets only what a request needs, not the
+// session's tokens. SYSTEMROOT keeps Windows sockets working; the CA var keeps corporate TLS.
+const CHECKER_ENV = ['PATH', 'SYSTEMROOT', 'NODE_EXTRA_CA_CERTS', 'WARNYIN_SDLC_REGISTRY_URL'];
+const checkerEnv = (env) => Object.fromEntries(CHECKER_ENV.filter((k) => env[k] !== undefined).map((k) => [k, env[k]]));
+
+function startCheck(hooksDir) {
+  const child = spawn(process.execPath, [path.join(hooksDir, 'check-update.mjs')], {
+    detached: true, stdio: 'ignore', windowsHide: true, env: checkerEnv(process.env),
+  });
+  child.on('error', () => {});
+  child.unref();
+}
+
+export function updateNotice({ sdlcRoot, hooksDir, now = Date.now() }) {
+  try {
+    if (isCheckDisabled(process.env, readConfig(sdlcRoot))) return null;
+    const installed = readJsonFile(path.join(hooksDir, 'version.json'))?.version;
+    if (!parseVersion(installed)) return null;
+    const cache = readJsonFile(cachePath(sdlcRoot));
+    const latest = parseVersion(cache?.latest) ? cache.latest : undefined;
+    // No recorded attempt, no request: a cache that cannot be written would otherwise mean a
+    // request on every session.
+    if (isCheckDue(cache, now) && writeCache(sdlcRoot, { checkedAt: new Date(now).toISOString(), latest })) {
+      startCheck(hooksDir);
+    }
+    return noticeLine(installed, latest);
+  } catch {
+    return null;
+  }
+}

package/payload/hooks/check-update.mjs

@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+// Detached from SessionStart by _update-notice.mjs — not a registered hook. Asks the registry
+// for the latest published version and caches it only when it is a plain X.Y.Z. Prints
+// nothing, follows no redirect, reads at most MAX_BODY_BYTES, and gives up after
+// FETCH_TIMEOUT_MS. Every failure leaves the cache as the hook left it.
+
+import process from 'node:process';
+import { resolveRoots } from './_shared.mjs';
+import { cachePath, readJsonFile, writeCache } from './_update-notice.mjs';
+import { parseVersion } from './lib/version.mjs';
+import {
+  DEFAULT_REGISTRY, FETCH_TIMEOUT_MS, MAX_BODY_BYTES, latestUrl,
+} from './lib/update-notice.mjs';
+
+const { sdlcRoot } = resolveRoots(import.meta.url);
+
+async function readCapped(body, limit) {
+  const chunks = [];
+  let size = 0;
+  for await (const chunk of body) {
+    size += typeof chunk === 'string' ? Buffer.byteLength(chunk) : chunk.byteLength;
+    if (size > limit) return null;
+    chunks.push(typeof chunk === 'string' ? Buffer.from(chunk) : chunk);
+  }
+  return Buffer.concat(chunks).toString('utf8');
+}
+
+async function main() {
+  const url = new URL(latestUrl(process.env.WARNYIN_SDLC_REGISTRY_URL || DEFAULT_REGISTRY));
+  if (url.protocol !== 'https:' && url.protocol !== 'http:') return; // fetch also reads data:
+  const res = await fetch(url, {
+    redirect: 'error',
+    headers: { accept: 'application/json' },
+    signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+  });
+  if (!res.ok || !res.body) return;
+  const text = await readCapped(res.body, MAX_BODY_BYTES);
+  if (text === null) return;
+  const version = JSON.parse(text)?.version;
+  if (!parseVersion(version)) return;
+  const cache = readJsonFile(cachePath(sdlcRoot));
+  writeCache(sdlcRoot, { checkedAt: cache?.checkedAt ?? new Date().toISOString(), latest: version });
+}
+
+main().catch(() => {}).finally(() => process.exit(0)); // fail open, silently

package/payload/hooks/guard-writes.mjs

@@ -1,87 +1,87 @@
-#!/usr/bin/env node
-// PreToolUse hook — the deterministic guardrail ("things the agent should
-// never forget but often does"). Denies direct edits to:
-//   sdlc/specs/**              outside an open ship gate
-//   sdlc/changes/archive/**    outside an open ship gate
-//   sdlc/context/constitution.md (existing) outside an open steer gate
-//   sdlc/.state/** and any journal.ndjson   always (machine-owned)
-// The sanctioned paths are the CLI (`warnyin-sdlc archive`) and the gates
-// opened by `journal.mjs open-ship|open-steer`.
-
-import fs from 'node:fs';
-import process from 'node:process';
-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, sessionId) {
-  appendJournal(sdlcRoot, activeChange(sdlcRoot, sessionId), { event: 'guard', action: 'deny', path: rel, reason });
-  console.log(JSON.stringify({
-    hookSpecificOutput: {
-      hookEventName: 'PreToolUse',
-      permissionDecision: 'deny',
-      permissionDecisionReason: reason,
-    },
-  }));
-}
-
-// 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, 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, sessionId);
-    return true;
-  }
-  if (rel.startsWith('sdlc/specs/') || rel.startsWith('sdlc/changes/archive/')) {
-    if (phase?.phase === 'ship') return false;
-    deny(
-      `"${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;
-  }
-  if (rel === 'sdlc/context/constitution.md' && fs.existsSync(path.join(projectRoot, rel))) {
-    if (phase?.phase === 'steer' || phase?.phase === 'ship') return false;
-    deny(
-      '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;
-  }
-  return false;
-}
-
-async function main() {
-  const input = await readStdinJson();
-  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);
-
-  // A path that CLAIMS to live under sdlc/ but resolves elsewhere (or out of
-  // 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, sessionId);
-    return;
-  }
-
-  const phase = readPhase(sdlcRoot);
-  for (const rel of new Set([relLexical, relReal].filter(Boolean))) {
-    if (rel.startsWith('sdlc/') && guard(rel, phase, sessionId)) return;
-  }
-}
-
-main().catch(() => process.exit(0)); // fail open
+#!/usr/bin/env node
+// PreToolUse hook — the deterministic guardrail ("things the agent should
+// never forget but often does"). Denies direct edits to:
+//   sdlc/specs/**              outside an open ship gate
+//   sdlc/changes/archive/**    outside an open ship gate
+//   sdlc/context/constitution.md (existing) outside an open steer gate
+//   sdlc/.state/** and any journal.ndjson   always (machine-owned)
+// The sanctioned paths are the CLI (`warnyin-sdlc archive`) and the gates
+// opened by `journal.mjs open-ship|open-steer`.
+
+import fs from 'node:fs';
+import process from 'node:process';
+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, sessionId) {
+  appendJournal(sdlcRoot, activeChange(sdlcRoot, sessionId), { event: 'guard', action: 'deny', path: rel, reason });
+  console.log(JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: 'PreToolUse',
+      permissionDecision: 'deny',
+      permissionDecisionReason: reason,
+    },
+  }));
+}
+
+// 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, 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, sessionId);
+    return true;
+  }
+  if (rel.startsWith('sdlc/specs/') || rel.startsWith('sdlc/changes/archive/')) {
+    if (phase?.phase === 'ship') return false;
+    deny(
+      `"${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;
+  }
+  if (rel === 'sdlc/context/constitution.md' && fs.existsSync(path.join(projectRoot, rel))) {
+    if (phase?.phase === 'steer' || phase?.phase === 'ship') return false;
+    deny(
+      '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;
+  }
+  return false;
+}
+
+async function main() {
+  const input = await readStdinJson();
+  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);
+
+  // A path that CLAIMS to live under sdlc/ but resolves elsewhere (or out of
+  // 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, sessionId);
+    return;
+  }
+
+  const phase = readPhase(sdlcRoot);
+  for (const rel of new Set([relLexical, relReal].filter(Boolean))) {
+    if (rel.startsWith('sdlc/') && guard(rel, phase, sessionId)) return;
+  }
+}
+
+main().catch(() => process.exit(0)); // fail open