@renzrollon/interlock 1.0.0

package/hooks/_shared.mjs

@@ -0,0 +1,162 @@
+// Shared plumbing for the PreToolUse guards and the SessionStart preflight.
+//
+// A hook is a bare Node script the Claude Code host runs in its own process: it
+// reads one JSON event on stdin and speaks its decision back through stdout and
+// the exit code, per the host's hook protocol. It shares no memory with the
+// plugin — the only state it has is what it reads off the filesystem. So every
+// helper here is a pure filesystem/stdin read, and every one of them fails in
+// the ALLOW direction: a guard that blocked a tool call because its own parse
+// threw would be a worse failure than the one it exists to prevent.
+
+import { readFileSync } from 'node:fs'
+import { isAbsolute, resolve } from 'node:path'
+
+/** Read the PreToolUse/SessionStart event the host writes to stdin. */
+export async function readEvent() {
+  const chunks = []
+  for await (const chunk of process.stdin) chunks.push(chunk)
+  const raw = Buffer.concat(chunks).toString('utf8').trim()
+  if (!raw) return {}
+  try {
+    return JSON.parse(raw)
+  } catch {
+    // A malformed event is not something a guard should block on — allow.
+    return {}
+  }
+}
+
+/**
+ * Allow the tool call. The host's default on a clean exit with no decision is to
+ * proceed, so allow is simply "say nothing, exit 0". Used for both the ordinary
+ * allow and the fail-open path after an internal error (with a stderr note).
+ */
+export function allow(note) {
+  if (note) process.stderr.write(`${note}\n`)
+  process.exit(0)
+}
+
+/**
+ * Deny the tool call in the shape the host's PreToolUse protocol expects, so the
+ * blocked agent receives `reason` as actionable feedback rather than an opaque
+ * failure. `detail` travels alongside the human-readable reason as machine-
+ * readable fields (guard name, path/command, current stage).
+ */
+export function deny(reason, detail = {}) {
+  const out = {
+    hookSpecificOutput: {
+      hookEventName: 'PreToolUse',
+      permissionDecision: 'deny',
+      permissionDecisionReason: reason
+    },
+    // Kept for a reader that wants the parts without re-parsing the sentence.
+    interlockGuard: detail
+  }
+  process.stdout.write(JSON.stringify(out) + '\n')
+  process.exit(0)
+}
+
+/** The tool name from the event, tolerant of the two casings seen in the wild. */
+export function toolName(event) {
+  return event.tool_name || event.toolName || ''
+}
+
+/** The tool input object, under either key the host has used. */
+export function toolInput(event) {
+  return event.tool_input || event.toolInput || {}
+}
+
+/** Project root the hook runs against — the host sets cwd to it. */
+export function projectRoot(event) {
+  return event.cwd || process.cwd()
+}
+
+/**
+ * The absolute file path an Edit/Write targets, or null when the payload names
+ * no concrete path. An unresolvable target is not a target to protect, so the
+ * guards allow it — this returning null is how they reach that decision.
+ */
+export function editTargetPath(event) {
+  const input = toolInput(event)
+  const raw = input.file_path || input.filePath || input.path
+  if (typeof raw !== 'string' || !raw.trim()) return null
+  return isAbsolute(raw) ? raw : resolve(projectRoot(event), raw)
+}
+
+/** Parse `.claude/testing/profile.json`, or null on absence/malformed. */
+export function loadTestProfile(root) {
+  try {
+    const value = JSON.parse(readFileSync(resolve(root, '.claude', 'testing', 'profile.json'), 'utf8'))
+    return value && typeof value === 'object' ? value : null
+  } catch {
+    return null
+  }
+}
+
+// Directory names that hold tests, used only to recognise a test root token
+// inside a profile command — never as a standalone hardcoded glob against the
+// tree. The profile is the source of truth for where THIS project's tests live.
+const TEST_DIR_TOKENS = new Set(['test', 'tests', '__tests__', 'e2e', 'cypress', 'playwright', 'spec', 'specs'])
+const TEST_FILE_SUFFIX = /\.(test|spec)\.[a-z0-9]+$/i
+
+/**
+ * Derive the set of test-root directories this project actually uses from its
+ * test profile, by reading the path tokens out of the profile's own commands
+ * (`find test -name ...`, `npx playwright test e2e/`, ...). A `<placeholder>`
+ * token is skipped — it is the argument the command leaves open, not a path.
+ *
+ * @returns {{ roots: string[], hasProfile: boolean }}
+ */
+export function testRootsFromProfile(profile) {
+  if (!profile || typeof profile !== 'object') return { roots: [], hasProfile: false }
+  const roots = new Set()
+  const consider = raw => {
+    if (typeof raw !== 'string') return
+    for (const token of raw.trim().split(/\s+/)) {
+      if (!token || token.startsWith('<') || token.startsWith('-')) continue
+      const norm = token.replace(/\\/g, '/').replace(/^\.\//, '').replace(/\/+$/, '')
+      const segments = norm.split('/')
+      // The first segment that is a known test-dir token anchors a root at the
+      // path up to and including it — `packages/app/e2e` → `packages/app/e2e`.
+      for (let i = 0; i < segments.length; i++) {
+        if (TEST_DIR_TOKENS.has(segments[i].toLowerCase())) {
+          roots.add(segments.slice(0, i + 1).join('/'))
+          break
+        }
+      }
+    }
+  }
+  for (const kind of ['unit', 'e2e']) {
+    const section = profile[kind]
+    if (!section || typeof section !== 'object') continue
+    consider(section.command)
+    consider(section.single_file)
+    consider(section.filter_syntax)
+  }
+  return { roots: [...roots], hasProfile: true }
+}
+
+/**
+ * Is `absPath` a test file for this project? True when it lives under one of the
+ * profile-derived roots, or when its filename carries the `.test.`/`.spec.`
+ * convention (a filename shape, not a directory glob). `root` is the project
+ * root the relative comparison is made against.
+ */
+export function isTestPath(absPath, testRoots, root) {
+  if (typeof absPath !== 'string') return false
+  const rel = relPosix(root, absPath)
+  if (TEST_FILE_SUFFIX.test(rel)) return true
+  for (const testRoot of testRoots) {
+    const r = testRoot.replace(/\/+$/, '')
+    if (rel === r || rel.startsWith(r + '/')) return true
+  }
+  return false
+}
+
+/** Project-relative POSIX path, for stable comparison against profile roots. */
+export function relPosix(root, absPath) {
+  const base = resolve(root).replace(/\\/g, '/').replace(/\/+$/, '')
+  const p = resolve(absPath).replace(/\\/g, '/')
+  if (p === base) return ''
+  if (p.startsWith(base + '/')) return p.slice(base.length + 1)
+  return p // outside the project root: return as-is, suffix check still applies
+}

package/hooks/guard-commit.mjs

@@ -0,0 +1,77 @@
+#!/usr/bin/env node
+// PreToolUse guard: no `git commit` outside the commit stage.
+//
+// `skills/commit/SKILL.md` and `skills/mr/SKILL.md` already set
+// `disable-model-invocation: true` — the prose version of "do not commit until
+// the commit stage." This guard is the deterministic half of the same intent: a
+// Bash command that performs a `git commit` is denied unless the run's stage is
+// `commit`. It bounds IN-RUN agents; it deliberately does NOT bound the human's
+// own shell, so when there is no active run marker it fails open — blocking a
+// developer's own commit on a stray marker would be the worse failure.
+//
+// The match canonicalises enough to catch `git commit`, `git -C <path> commit`,
+// `git -c key=val commit`, and a leading-env invocation (`FOO=bar git commit`),
+// across `&&`/`;`/`|` chains AND newlines — a multi-line script is the ordinary
+// shape of a Bash tool call, not an evasion, so a chain split by a line break
+// must segment the same way one split by `&&` does. A segment led by a shell
+// keyword (`then`, `do`, `else`) is scanned past it, so `if …; then git commit;
+// fi` is seen. It is a guardrail against the wrong-stage mistake, not a sandbox
+// against a determined adversary.
+
+import { readStage } from '../lib/ship-stage.mjs'
+import { readEvent, allow, deny, toolName, toolInput, projectRoot } from './_shared.mjs'
+
+const GUARD = 'guard-commit'
+
+// git global options that take an argument, so the scan can step past the value
+// and still find the `commit` subcommand after them.
+const OPTS_WITH_ARG = new Set(['-C', '-c', '--git-dir', '--work-tree', '--namespace', '--exec-path'])
+
+// Shell keywords that can lead a segment and are followed by the command
+// itself: `if true; then git commit`, `for f in *; do git commit`.
+const LEADING_KEYWORDS = new Set(['then', 'do', 'else'])
+
+/** Does `command` perform a git commit in any of its chained segments? */
+export function isGitCommit(command) {
+  if (typeof command !== 'string') return false
+  for (const segment of command.split(/&&|\|\||;|\||\r?\n|\r/)) {
+    const tokens = segment.trim().split(/\s+/).filter(Boolean)
+    let i = 0
+    // Leading environment assignments: FOO=bar git commit.
+    while (i < tokens.length && /^[A-Za-z_][A-Za-z0-9_]*=/.test(tokens[i])) i++
+    // …then a leading shell keyword, so `then git commit` is scanned like
+    // `git commit`.
+    while (i < tokens.length && LEADING_KEYWORDS.has(tokens[i])) i++
+    if (tokens[i] !== 'git') continue
+    i++
+    // git's own global options, some of which consume the next token.
+    while (i < tokens.length && tokens[i].startsWith('-')) {
+      const opt = tokens[i]
+      i++
+      if (OPTS_WITH_ARG.has(opt) && !opt.includes('=')) i++ // step past its argument
+    }
+    if (tokens[i] === 'commit') return true
+  }
+  return false
+}
+
+try {
+  const event = await readEvent()
+  if (toolName(event) !== 'Bash') allow()
+
+  const command = toolInput(event).command
+  if (!isGitCommit(command)) allow()
+
+  const { stage } = readStage({ root: projectRoot(event) })
+  if (stage === 'commit') allow() // the commit stage is exactly when a commit is legal
+  if (stage === 'unknown') allow() // no active run to bound — the human's own shell is not our business
+
+  deny(
+    `${GUARD}: \`git commit\` is blocked during the ${stage} stage of a ship run — commits are made ` +
+      `only in the commit stage, by the commit step, as one feature-level commit. This is the ` +
+      `deterministic form of the disable-model-invocation flag on skills/commit.`,
+    { guard: GUARD, command: String(command), stage }
+  )
+} catch (err) {
+  allow(`${GUARD}: internal error, allowing by default: ${(err && err.message) || String(err)}`)
+}

package/hooks/guard-tasks.mjs

@@ -0,0 +1,107 @@
+#!/usr/bin/env node
+// PreToolUse guard: the completion tick belongs to the CLI, not to an agent's
+// Edit tool.
+//
+// `interlock tasks tick` writes a change's `tasks.md` checkbox from an
+// adjudicated outcome — the tick is keyed off what the run RECORDED, not off
+// what an implementing agent claims (see the shipped change
+// `2026-08-25-tick-tasks-from-recorded-outcomes`). That change removed the
+// incentive to hand-tick; this guard removes the capability. An Edit/Write that
+// flips a checkbox line in the active change's `tasks.md` while a run is live is
+// denied; a prose-only edit that leaves every checkbox byte-identical is
+// allowed, and so is any edit when no run is active.
+//
+// The CLI's own tick does not route through the Edit/Write tools, so it never
+// trips this guard — the guard scopes to the agent-facing tools by construction.
+
+import { readStage, STAGES } from '../lib/ship-stage.mjs'
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import {
+  readEvent,
+  allow,
+  deny,
+  toolName,
+  toolInput,
+  projectRoot,
+  editTargetPath,
+  relPosix
+} from './_shared.mjs'
+
+const GUARD = 'guard-tasks'
+// Every stage a run publishes is an active-run stage; the tick is never the
+// agent's job in any of them. (The commit-stage agent does not edit tasks.md,
+// but denying a checkbox flip there too costs nothing and is the honest rule.)
+const ACTIVE_STAGES = new Set(STAGES)
+const CHECKBOX = /^\s*[-*]\s+\[([ xX])\]/
+
+/**
+ * The checkbox STATES of a blob, in order — `' '` or `'x'` per checkbox line.
+ * Only the marker inside the brackets is captured, so a reworded task title or
+ * a prose edit anywhere leaves this sequence byte-identical; only a tick flip,
+ * or a checkbox added or removed, changes it. That is exactly the edit the CLI
+ * owns and a hand-edit must not make.
+ */
+function checkboxStates(text) {
+  if (typeof text !== 'string') return []
+  const states = []
+  for (const line of text.split(/\r?\n/)) {
+    const m = CHECKBOX.exec(line)
+    if (m) states.push(m[1].toLowerCase())
+  }
+  return states
+}
+
+/** Do two blobs carry a different sequence of checkbox states (added, removed, or flipped)? */
+function checkboxesDiffer(before, after) {
+  const a = checkboxStates(before)
+  const b = checkboxStates(after)
+  if (a.length !== b.length) return true
+  for (let i = 0; i < a.length; i++) if (a[i] !== b[i]) return true
+  return false
+}
+
+try {
+  const event = await readEvent()
+  const tool = toolName(event)
+  if (tool !== 'Edit' && tool !== 'Write') allow()
+
+  const root = projectRoot(event)
+  const { stage, change } = readStage({ root })
+  if (!ACTIVE_STAGES.has(stage) || !change) allow() // no active run → allow
+
+  const target = editTargetPath(event)
+  if (!target) allow()
+
+  const tasksPath = resolve(root, 'openspec', 'changes', String(change), 'tasks.md')
+  if (resolve(target) !== tasksPath) allow() // not the active change's tasks.md
+
+  const input = toolInput(event)
+  let before
+  let after
+  if (tool === 'Edit') {
+    before = input.old_string || input.oldString || ''
+    after = input.new_string || input.newString || ''
+  } else {
+    // Write replaces the whole file — compare against what is on disk now.
+    try {
+      before = readFileSync(tasksPath, 'utf8')
+    } catch {
+      before = ''
+    }
+    after = input.content || input.contents || ''
+  }
+
+  if (!checkboxesDiffer(before, after)) allow() // prose-only edit, checkboxes byte-identical
+
+  const rel = relPosix(root, target) || target
+  deny(
+    `${GUARD}: changing a checkbox line in ${rel} is blocked during a ship run (stage ${stage}). ` +
+      `The completion tick is written by \`interlock tasks tick\` from the run's recorded outcomes, ` +
+      `never by hand — a hand-tick is how unimplemented work ships marked done. Edit the task's prose ` +
+      `freely; leave the \`- [ ]\` / \`- [x]\` markers to the CLI.`,
+    { guard: GUARD, path: rel, stage, change }
+  )
+} catch (err) {
+  allow(`${GUARD}: internal error, allowing by default: ${(err && err.message) || String(err)}`)
+}

package/hooks/guard-tests.mjs

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+// PreToolUse guard: an agent making a red check green must not be able to
+// weaken the check itself.
+//
+// During `remediation` and `fix-tests` the run's whole job is to turn a failing
+// assertion into a passing one. The cheapest way to do that dishonestly is to
+// edit the test. This guard denies an Edit/Write to a test file for exactly
+// those two stages, and allows everything else — including test edits during
+// `implement`, where adding coverage for the feature you are building is the
+// point, not a hazard.
+//
+// Fail open on everything it cannot establish: an unknown stage, an unresolvable
+// path, a missing test profile, or its own crash all ALLOW. Blocking test edits
+// whenever the marker is missing would break ordinary TDD the moment the plugin
+// is installed — a cost strictly larger than the guard's benefit, which exists
+// only inside a ship run's remediation window.
+
+import { readStage } from '../lib/ship-stage.mjs'
+import {
+  readEvent,
+  allow,
+  deny,
+  toolName,
+  projectRoot,
+  editTargetPath,
+  loadTestProfile,
+  testRootsFromProfile,
+  isTestPath,
+  relPosix
+} from './_shared.mjs'
+
+const GUARD = 'guard-tests'
+const BLOCKED_STAGES = new Set(['remediation', 'fix-tests'])
+
+try {
+  const event = await readEvent()
+  const tool = toolName(event)
+  if (tool !== 'Edit' && tool !== 'Write') allow()
+
+  const root = projectRoot(event)
+  const { stage } = readStage({ root })
+  if (!BLOCKED_STAGES.has(stage)) allow() // unknown or a non-repair stage → allow
+
+  const target = editTargetPath(event)
+  if (!target) allow() // no concrete path to protect
+
+  const { roots, hasProfile } = testRootsFromProfile(loadTestProfile(root))
+  if (!hasProfile) allow() // no profile → nothing names where tests live → allow
+
+  if (!isTestPath(target, roots, root)) allow() // not a test file → allow (source repair is expected)
+
+  const rel = relPosix(root, target) || target
+  deny(
+    `${GUARD}: editing the test file ${rel} is blocked during the ${stage} stage — ` +
+      `a run making a failing check pass must fix the code under test, not weaken the check. ` +
+      `If the test itself is wrong, stop the run and correct it outside remediation.`,
+    { guard: GUARD, path: rel, stage }
+  )
+} catch (err) {
+  // The guard's own crash must never block a tool call. Allow, and leave a
+  // diagnostic on stderr rather than a wedged session.
+  allow(`${GUARD}: internal error, allowing by default: ${(err && err.message) || String(err)}`)
+}

package/hooks/preflight.mjs

@@ -0,0 +1,107 @@
+#!/usr/bin/env node
+// SessionStart hook: run the preflight the run already owns, at the one moment
+// it is cheap to act on — session start, before any wave.
+//
+// `interlock doctor` (lib/doctor.mjs) already computes the allowlist / Node /
+// OpenSpec / writability preflight that decides whether a zero-touch run can
+// even begin. The failure it catches — an un-allowlisted command that stalls
+// wave four on an approval prompt no human is watching — is the expensive one.
+// A human or a skill used to have to remember to run it; this hook fires it
+// every session and surfaces any failure with the fix string the doctor emits.
+//
+// It NEVER blocks. `interlock doctor` is non-mutating, and a preflight that
+// aborted the session because its own binary was missing would be worse than no
+// preflight. Every path here exits 0.
+
+import { execFileSync } from 'node:child_process'
+import { existsSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const PLUGIN_ROOT = dirname(dirname(fileURLToPath(import.meta.url)))
+
+/** Prefer the bundled binary (always present next to this hook), fall back to PATH. */
+function interlockBin() {
+  const bundled = join(PLUGIN_ROOT, 'bin', 'interlock')
+  if (existsSync(bundled)) return bundled
+  return 'interlock' // let PATH resolution decide; a miss throws ENOENT below
+}
+
+function run() {
+  let raw
+  try {
+    raw = execFileSync(interlockBin(), ['doctor', '--json'], {
+      cwd: process.cwd(),
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+      timeout: 20000
+    })
+  } catch (err) {
+    // Two shapes of failure. A non-zero exit still carries JSON on stdout (the
+    // doctor exits 1 when a check fails) — parse it. A spawn failure (ENOENT:
+    // no binary) has no stdout, and that is the "binary not resolvable" case.
+    if (err && typeof err.stdout === 'string' && err.stdout.trim()) {
+      raw = err.stdout
+    } else {
+      report(
+        `interlock preflight could not run: ${(err && err.message) || String(err)}\n` +
+          `The \`interlock\` binary is not resolvable from this session. Inside Claude Code the ` +
+          `plugin's bin/ is normally injected; if you see this, reinstall the plugin. The session ` +
+          `continues — this preflight is advisory.`
+      )
+      return
+    }
+  }
+
+  let doctor
+  try {
+    doctor = JSON.parse(raw)
+  } catch {
+    report('interlock preflight ran but its output could not be parsed; skipping. The session continues.')
+    return
+  }
+
+  const checks = Array.isArray(doctor.checks) ? doctor.checks : []
+  const failures = checks.filter(c => c && c.status === 'fail')
+  if (!failures.length) {
+    const warns = (doctor.counts && doctor.counts.warn) || 0
+    // A clean preflight is quiet, not a wall of output — one confirming line.
+    report(`interlock preflight OK${warns ? ` (${warns} warning${warns === 1 ? '' : 's'})` : ''}.`)
+    return
+  }
+
+  const lines = ['interlock preflight found issues that can stall an unattended ship run:']
+  for (const c of failures) {
+    lines.push(`  [FAIL] ${c.id}: ${c.detail}`)
+    if (c.fix) {
+      const [first, ...rest] = String(c.fix).split('\n')
+      lines.push(`     fix: ${first}`)
+      for (const line of rest) lines.push(`          ${line.trim()}`)
+    }
+  }
+  lines.push('The session still starts — apply the fixes above before /interlock:ship.')
+  report(lines.join('\n'))
+}
+
+/**
+ * Surface advisory context to the session. SessionStart stdout is folded into
+ * the session context by the host; the structured form makes the intent
+ * explicit and is ignored harmlessly by a host that does not read it.
+ */
+function report(message) {
+  const out = {
+    hookSpecificOutput: {
+      hookEventName: 'SessionStart',
+      additionalContext: message
+    }
+  }
+  process.stdout.write(JSON.stringify(out) + '\n')
+}
+
+try {
+  run()
+} catch (err) {
+  // Belt and suspenders: nothing this hook does may abort the session.
+  process.stderr.write(`interlock preflight hook error (ignored): ${(err && err.message) || String(err)}\n`)
+}
+process.exit(0)