@renzrollon/interlock 1.5.0 → 1.6.0

package/hooks/mod.mjs

@@ -102,8 +102,12 @@
 // run's trajectory, its manifest or its wave state, and no listing or
 // existence check (the hook lists, in Node). It reads at each prompt a person
 // submits, the one event that reaches a module after the preflight wrote, and
-// after the classic session-start event where an engine raises one. A report
-// is known by its own written time, so a re-read changes nothing and the band
+// when one of the two commands is run. It never reads at the classic
+// session-start event: the settings hook that writes the file runs inside that
+// event's chain, and the module's hook there resets the meter and returns the
+// chain's call as it is, so after a boundary the module holds no report until
+// the next prompt (clear-the-plugin-directory-holds design D1). A report is
+// known by its own written time, so a re-read changes nothing and the band
 // stays hidden once hidden; the lines, the hide rule and the card's cap are
 // `lib/preflight-file.mjs`'s.
 //
@@ -908,11 +912,6 @@ function endRunAtBoundary($, input) {
   }
 }
 
-/** Once the chain beneath has run: the preflight's report, read for every source. */
-async function readPreflightAfterStart($, input) {
-  if (session.interactive) await readPreflight($, str(input.cwd) || session.cwd)
-}
-
 /** One Explore investigator the chain let through (design D5). Never throws. */
 async function countInvestigator($) {
   try {
@@ -2117,22 +2116,24 @@ export function register(on) {
   // The session boundary (design D4). /clear, /resume and /branch start the
   // session over: the engine empties `$.state`, the launch guard's record with
   // it, and `session.start` does not fire. The meter ends the run it holds on
-  // the same event. A compaction is the same session and the same run, and a
-  // source this cannot read changes nothing. The pane is left open: it redraws
-  // to the no-run text, which is true, and the person dismisses it. Once the
-  // settings hooks beneath have run, the preflight's report is read for every
-  // source (show-preflight-and-interrupted-runs-at-session-start design D5).
-  // The kit raises this event; Claude Code 2.1.291 raises no classic event to
-  // a module, so there the prompt hook above reads the report instead.
+  // the same event, before the chain beneath is called. A compaction is the
+  // same session and the same run, and a source this cannot read changes
+  // nothing. The pane is left open: it redraws to the no-run text, which is
+  // true, and the person dismisses it.
+  //
+  // Pass the event on unchanged. The hook returns the forward call itself,
+  // with nothing bound to it, awaited on it or chained after it, so the
+  // event's result, the session's first message included, is the chain's own
+  // and never this module's (clear-the-plugin-directory-holds design D1).
+  // test/spine/mod-pins.test.mjs holds the hook to that shape.
   //
-  // Pass the event on unchanged. The value this hook returns is the forward
-  // itself: no first message, no permission decision. The meter's reset runs
-  // before that chain and the preflight read after it; neither becomes the return.
+  // The preflight's report is never read here. The settings hook that writes
+  // it runs inside this chain, so a read before the call would draw the
+  // previous session's file, and a read after it needs the chain's promise.
+  // The report is read at a person's prompt, above, and by the two commands.
   on('classic.SessionStart', async (meterSessionApi, meterSessionInput, meterSessionForward) => {
     endRunAtBoundary(meterSessionApi, meterSessionInput)
-    const sessionForwarded = meterSessionForward(meterSessionInput)
-    await sessionForwarded.then(() => readPreflightAfterStart(meterSessionApi, meterSessionInput))
-    return sessionForwarded
+    return meterSessionForward(meterSessionInput)
   })
 
   on('ui.render', { component: 'Spinner' }, ($, e, next) => {

package/hooks/notify-option.mjs

@@ -0,0 +1,69 @@
+// SessionStart hook: hand one saved plugin option to the session's commands.
+//
+// Run as `node hooks/notify-option.mjs <topic|url> <value>`, where the value is
+// what the manifest wrote as an option reference and the host substituted.
+//
+// WHY IT EXISTS. The host gives a plugin option to hook processes only. The
+// command that pushes when a ship run stops (`interlock run close --notify`,
+// `interlock notify`) is run through the Bash tool or by `interlock-run`, and
+// is not a hook. The session's environment file is the host's channel between
+// a hook and those commands, so this hook appends one `export` of the matching
+// variable there, and `lib/notify.mjs` reads that variable and nothing else.
+//
+// WHY ONE HOOK TO AN OPTION. The host does not run a hook whose arguments name
+// an option with no saved value, and prints nothing about it (probed on Claude
+// Code 2.1.296 and 2.1.161; clear-the-plugin-directory-holds design D4). So
+// the reference cannot sit in the preflight's entry, which must run for
+// everyone, and the topic and the server cannot share an entry, or a person
+// who saved a topic and left the server alone would have neither exported.
+// Each entry exists, for the host, only when the person saved that option.
+//
+// WHAT IT NEVER DOES. It prints nothing to standard output, because a
+// session-start hook's output becomes context and the topic is a capability.
+// It exits 0 on every path. It leaves a variable the operator already provided
+// as it is. It writes nothing for a value that is empty, that carries a line
+// break or a NUL, or that still reads as a reference nobody substituted. It
+// never judges the value's shape: `readNotifyConfig` does that where the value
+// is used, and names the variable without the value.
+
+import { appendFileSync } from 'node:fs'
+
+/** The variable each kind of option is exported as. */
+const VARIABLES = new Map([
+  ['topic', 'INTERLOCK_NTFY_TOPIC'],
+  ['url', 'INTERLOCK_NTFY_URL']
+])
+
+/** How a reference the host passed through as written begins. */
+const UNSUBSTITUTED = '${user_config.'
+
+/** A single-quoted shell word. */
+function shellQuote(value) {
+  return `'${String(value).replace(/'/g, `'\\''`)}'`
+}
+
+/** A value worth exporting: text, not blank, on one line, and not a reference left as written. */
+function publishable(value) {
+  return typeof value === 'string' && value.trim() !== '' && !/[\0\r\n]/.test(value) && !value.includes(UNSUBSTITUTED)
+}
+
+/** A variable the operator's own environment already carries. */
+function provided(name) {
+  const value = process.env[name]
+  return typeof value === 'string' && value.trim() !== ''
+}
+
+let variable
+try {
+  const [kind, value] = process.argv.slice(2)
+  variable = VARIABLES.get(kind)
+  const file = process.env.CLAUDE_ENV_FILE
+  if (variable && publishable(value) && typeof file === 'string' && file && !provided(variable)) {
+    // One short line in a single write: the other option's hook appends beside this one.
+    appendFileSync(file, `export ${variable}=${shellQuote(value.trim())}\n`)
+  }
+} catch (err) {
+  const reason = String((err && err.message) || err).replace(/\s+/g, ' ')
+  process.stderr.write(`interlock notify option: ${variable || 'the option'} was not exported (ignored): ${reason}\n`)
+}
+process.exit(0)

package/hooks/preflight.mjs

@@ -40,9 +40,14 @@
 // on stderr. Every other repository gets no file, no directory, and exactly
 // the output it got before. The file is outcome-class: losing it costs the
 // band, never the session.
+//
+// It reads and writes nothing for the push. A plugin option reaches the
+// session's commands through a hook of its own, `hooks/notify-option.mjs`,
+// which the host runs only for an option the person saved; the manifest's
+// entry for this hook names no option, so it runs for everyone.
 
 import { execFileSync } from 'node:child_process'
-import { appendFileSync, existsSync, mkdirSync, realpathSync, rmSync, statSync, writeFileSync } from 'node:fs'
+import { existsSync, mkdirSync, realpathSync, rmSync, statSync, writeFileSync } from 'node:fs'
 import { dirname, join, resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
 
@@ -283,48 +288,7 @@ function report(message) {
   process.stdout.write(JSON.stringify(out) + '\n')
 }
 
-/** A single-quoted shell word. A value with a newline or a NUL is refused. */
-function shellQuote(value) {
-  return `'${String(value).replace(/'/g, `'\\''`)}'`
-}
-
-function publishable(value) {
-  return typeof value === 'string' && value.trim() && !/[\0\r\n]/.test(value)
-}
-
-/**
- * Copy a plugin option into the session so `interlock notify` can see it.
- *
- * The host injects `userConfig` into hook processes only. A ship run's notify
- * call is not a hook, so without this copy a topic typed into the plugin
- * options would never reach the CLI. An operator who already provided the
- * shell variable keeps that value. Nothing is printed, and a failure here
- * does not change the preflight.
- */
-function publishNotifyOptions() {
-  const file = process.env.CLAUDE_ENV_FILE
-  if (typeof file !== 'string' || !file) return
-  const lines = []
-  const topic = process.env.CLAUDE_PLUGIN_OPTION_NTFY_TOPIC
-  const url = process.env.CLAUDE_PLUGIN_OPTION_NTFY_URL
-  if (publishable(topic) && !publishable(process.env.INTERLOCK_NTFY_TOPIC)) {
-    lines.push(`export INTERLOCK_NTFY_TOPIC=${shellQuote(topic.trim())}`)
-  }
-  if (publishable(url) && !publishable(process.env.INTERLOCK_NTFY_URL)) {
-    lines.push(`export INTERLOCK_NTFY_URL=${shellQuote(url.trim())}`)
-  }
-  if (!lines.length) return
-  appendFileSync(file, lines.join('\n') + '\n')
-}
-
 try {
-  try {
-    publishNotifyOptions()
-  } catch (err) {
-    process.stderr.write(
-      `interlock preflight could not publish notify options (ignored): ${(err && err.message) || err}\n`
-    )
-  }
   const cwd = process.cwd()
   const source = await sessionSource()
   const { message, stateHome, surface, doctor } = run()

package/lib/conformance.mjs

@@ -79,6 +79,79 @@ export function buildChecklist(root = '.', requested, opts = {}) {
   }
 }
 
+/**
+ * The living list: the requirements already in force for the capabilities the
+ * change touches, as questions for the handoff. Pure. It is the domain
+ * reviewer's own selection and bounded text (`lib/prompts/domain-context.mjs`)
+ * turned into locations, so the reviewer and the handoff can never disagree about
+ * which living requirements a change is judged against.
+ *
+ * Headings and locations only, never a requirement body: whoever answers reads
+ * the spec at the cited line, as it reads a scenario's artifact. Identifiers run
+ * L1..Ln in capability then spec order, and `requirementsRequired` is the only
+ * denominator a reader may use. design D5 of
+ * complete-and-record-the-merge-verdict.
+ *
+ * `skipped` and `partial` come from the selection alone: the assembler also
+ * reports a skip when a graph linked nothing, and that is an empty list, not a
+ * missing graph.
+ *
+ * @param {{ selection?: object, assembled?: object }} input
+ * @returns {{
+ *   skipped: string|null, partial: string|null,
+ *   requirements: { id: string, capability: string, artifact: string, line: number, title: string }[],
+ *   requirementsRequired: number,
+ *   omitted: { capability: string, heading: string }[],
+ *   source: string
+ * }}
+ */
+export function buildLivingChecklist({ selection, assembled } = {}) {
+  const skipped = typeof selection?.skipped === 'string' && selection.skipped ? selection.skipped : null
+  const partial = typeof selection?.partial === 'string' && selection.partial ? selection.partial : null
+  const kept = Array.isArray(assembled?.kept) ? assembled.kept : []
+  const requirements = kept.map((entry, i) => ({
+    id: `L${i + 1}`,
+    capability: entry.capability,
+    artifact: `openspec/specs/${entry.capability}/spec.md`,
+    line: entry.line,
+    title: entry.heading
+  }))
+  return {
+    skipped,
+    partial,
+    requirements,
+    requirementsRequired: requirements.length,
+    omitted: (Array.isArray(assembled?.omitted) ? assembled.omitted : []).map(o => ({
+      capability: o.capability,
+      heading: o.heading
+    })),
+    source: typeof assembled?.source === 'string' ? assembled.source : 'the working tree'
+  }
+}
+
+/** The living block of a checklist, as lines; empty when none was asked for. */
+function livingLines(living) {
+  if (!living || typeof living !== 'object') return []
+  const lines = ['']
+  const n = Array.isArray(living.requirements) ? living.requirements.length : 0
+  if (living.skipped) {
+    lines.push(`  Living requirements — not built: ${living.skipped}`)
+    return lines
+  }
+  lines.push(`  Living requirements in force — ${n} to confirm (read from ${living.source})`)
+  if (living.partial) lines.push(`  Partial: ${living.partial}`)
+  for (const r of living.requirements ?? []) {
+    lines.push(`  ${r.id}  ${r.title}`)
+    lines.push(`      ${r.artifact}:${r.line}`)
+  }
+  if (Array.isArray(living.omitted) && living.omitted.length) {
+    lines.push('')
+    lines.push(`  ${living.omitted.length} requirement${living.omitted.length === 1 ? '' : 's'} left out to fit the size bound:`)
+    for (const o of living.omitted) lines.push(`    ${o.capability}: ${o.heading}`)
+  }
+  return lines
+}
+
 /** Human-readable checklist. One numbered question per scenario, nothing decided. */
 export function formatChecklist(result) {
   const lines = []
@@ -103,6 +176,7 @@ export function formatChecklist(result) {
       lines.push('  A change may legitimately carry none. But a change that promised behaviour and')
       lines.push('  wrote no scenario has nothing to conform to, which is worth noticing.')
     }
+    lines.push(...livingLines(result.living))
     lines.push('')
     lines.push('Nothing here blocks.')
     return lines.join('\n')
@@ -116,6 +190,7 @@ export function formatChecklist(result) {
     lines.push(`  ${s.id}  ${s.title}`)
     lines.push(`      ${s.artifact}:${s.line}`)
   }
+  lines.push(...livingLines(result.living))
 
   if (result.changedFiles.length) {
     lines.push('')