@renzrollon/interlock 1.2.0 → 1.2.1

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "interlock",
   "displayName": "Interlock",
-  "version": "1.2.0",
+  "version": "1.2.1",
   "description": "Autonomous spec-driven development orchestration for Claude Code, layered on OpenSpec. Onboard a repo, produce a reviewed spec, then ship it start-to-commit with parallel agents and a deterministic gate spine.",
   "author": {
     "name": "Carl Rollon",
@@ -9,6 +9,7 @@
   },
   "homepage": "https://github.com/renzrollon/interlock",
   "repository": "https://github.com/renzrollon/interlock",
+  "icon": ".claude-plugin/icon.png",
   "license": "MIT",
   "keywords": [
     "openspec",
@@ -18,6 +19,20 @@
     "code-review",
     "knowledge-graph"
   ],
+  "userConfig": {
+    "ntfy_topic": {
+      "type": "string",
+      "title": "ntfy topic",
+      "description": "Optional. A topic for one push when a ship run stops or finishes. Leave empty to send nothing. Anyone who knows the topic can read the messages.",
+      "sensitive": true
+    },
+    "ntfy_url": {
+      "type": "string",
+      "title": "ntfy server",
+      "description": "Optional. Server to post to. Leave empty to use the public server.",
+      "sensitive": false
+    }
+  },
   "workflows": "./workflows",
   "types": "./types/index.d.ts",
   "hooks": {

package/CHANGELOG.md

@@ -2,13 +2,15 @@
 
 All notable changes to this project are documented here.
 
-The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and
-this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+The format follows Keep a Changelog 1.1.0, and
+this project adheres to Semantic Versioning 2.0.0.
 
-## [Unreleased]
+## 1.2.1 — 2026-10-06
 
 ### Added
 
+- **A listing icon, and a push topic the operator chooses to share.** `.claude-plugin/icon.png` is the listing image. A Claude Code user can set an ntfy topic and an optional server in the plugin's options; the topic is sensitive. Session start copies a set option into the session for `interlock notify` when the operator has not already provided one. `INTERLOCK_NTFY_TOPIC` and `INTERLOCK_NTFY_URL` still work, and a value already provided that way wins. `/interlock:fix-tests` no longer pre-approves every shell command. `/interlock:spec` filters `openspec instructions` through a bundled Node script.
+
 - **The ship meter says how long a run has been quiet.** A subscription run that reaches a plan window pauses instead of failing, and from the status line that pause looked exactly like a hang. While a run is live, `hooks/mod.mjs` now stamps the engine's time of each thing the run does: the launch, each step the CLI prints, each request a run agent starts and each answer it gets, each agent's turn end, each spawn. Once nothing has moved for `meter quiet after (ms)`, ` · quiet <n> min` follows the position on the status line and the spinner, and the pane gains a `last activity <time>` line with the word beside it. The next activity clears it. A lane thinking through one long request is not called quiet, because the request's start and its answer both count. The word names no cause: the plan windows stay beside it on the pane as the session reports them, with no threshold and no colour.
   - **Two caps, published, not restated.** `interlock limits` prints `meter quiet after (ms)` and `meter tick (ms)`. Both are keys in `lib/limits.mjs`, read by a new pure, Node-free `lib/meter-quiet.mjs` that the hooks module imports, and `test/spine/limits.test.mjs` fails if the module restates either.
   - **One timer, the host's own.** The figure is recomputed on `$.clock.every`, the engine's periodic dispatch, which the module starts at the launch and cancels at the close, a halt and the session boundary. A redraw happens only when the word changes. A sleep inside a hook would have been charged to that hook's own time budget, so `$.clock.sleep` joins the module's forbidden tokens. The pins' allow-list gains `$.clock.every` and nothing else.
@@ -105,6 +107,11 @@ this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ### Changed
 
+- **Plugin installs now receive exactly what npm publishes, at the version npm carries.** The marketplace entry used `"source": "./"`, so `/plugin install interlock@interlock` copied the whole checkout from the default branch: 847 files, including `openspec/`, `docs/`, `test/` and `site/`, and any untagged commit on main. It now names the `release` branch of this repository. A new workflow, `.github/workflows/plugin-bundle.yml`, fills that branch after every successful Release run: it fetches the published tarball back from the registry, checks that its `plugin.json` carries the released version, validates it with `claude plugin validate --strict`, and commits it unpacked and unchanged. Plugin users move only when a release does. The same branch is what Anthropic's plugin directory tracks, and the bundle fits the directory's limits (138 files, none over 256 KiB) where the checkout raised two review holds.
+  - **The tarball is the whole plugin now, so a test says so.** `test/spine/package.test.mjs` walks every path the plugin reaches at runtime: the component directories, the manifest's `workflows` and `types`, each CLAUDE_PLUGIN_ROOT path that a hook command, skill, agent, shared contract, workflow or briefing names, and the import closure of every script among them. It fails on any path that no `files` entry ships or that does not exist. It also pins the marketplace entry's source, the bundle workflow's trigger, package and branch, and that both release workflows stay tracked past `.gitignore`.
+  - **`files` ships `.claude-plugin/plugin.json` alone.** The bundle is one plugin, so it carries no marketplace manifest naming a source of its own.
+  - **The branch is seeded, and rolled back, by hand.** Dispatch the workflow with a version already on npm. Re-running it for a version the branch already holds commits nothing.
+
 - **The launch rule moved into one Node-free module that both forms of the guard import.** `lib/launch-rule.mjs` holds what a ship launch is, what a human prompt is, the decision and its words, and three record transforms, `emptyRecord`, `withLaunch` and `withPrompt`. It imports only `./limits.mjs`. `lib/launch-ledger.mjs` keeps the file and re-exports every rule name unchanged, so `hooks/guard-relaunch.mjs` and `test/hooks.test.mjs` import what they imported before. `recordLaunch` and `recordPrompt` now apply `withLaunch` and `withPrompt`, so the file and the session record change by the same functions. One visible effect: a launch written to a ledger now drops earlier launches past the published age, which never changed a verdict. `test/spine/launch-ledger.test.mjs` pins that each re-exported name is the rule module's own object, that the rule names no `node:` import, and that `decideLaunch` over a plain record and over the same facts read from a file returns the same verdict and reason.
 
 - **The hooks module's observe-only pin now allows exactly one refusal instead of none.** `test/spine/mod-pins.test.mjs` no longer forbids the token `deny` outright. It allows one line, `if (launch && verdict.decision === 'deny') return { deny: verdict.reason }`, with `verdict` assigned once from `decideLaunch` imported from `lib/launch-rule.mjs`, and fails naming any other. The allow-list grows by exactly `$.clock.now`, `$.state.get` and `$.state.set`. The module's session-state keys must equal the contract's, and its hooked events are pinned, `prompt.submit` and `session.receive` included.
@@ -196,14 +203,14 @@ this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 - **An unattended ship run that stops can now reach you.** Four independent "quick win" gaps closed at the one seam both hosts already pass through — `interlock run close`:
 
-  - **Push on halt or completion.** With `INTERLOCK_NTFY_TOPIC` set, `run close --notify` — which both `workflows/ship.js` and `bin/interlock-run` now pass on every close — posts one [ntfy](https://ntfy.sh) message per terminal outcome: `high` priority on `SHIP HALTED`, default otherwise. The message carries the summary's first line, the change and the run id, and nothing that identifies the machine — never the topic, the cwd or the project slug. `INTERLOCK_NTFY_URL` selects a self-hosted server (default `https://ntfy.sh`); leaving the topic unset makes the default path, and the test suite, open no connection at all. A failed push prints `push: failed — <reason>` and a `PUSH FAILED: <reason>` degradation banner and never moves the exit code. `interlock notify` and the `interlock notify checkpoint <change>` sugar (used by `/interlock:spec`'s checkpoint) are also callable standalone.
+  - **Push on halt or completion.** With `INTERLOCK_NTFY_TOPIC` set, `run close --notify` — which both `workflows/ship.js` and `bin/interlock-run` now pass on every close — posts one ntfy message per terminal outcome: `high` priority on `SHIP HALTED`, default otherwise. The message carries the summary's first line, the change and the run id, and nothing that identifies the machine — never the topic, the cwd or the project slug. `INTERLOCK_NTFY_URL` selects a self-hosted server (default the public server); leaving the topic unset makes the default path, and the test suite, open no connection at all. A failed push prints `push: failed — <reason>` and a `PUSH FAILED: <reason>` degradation banner and never moves the exit code. `interlock notify` and the `interlock notify checkpoint <change>` sugar (used by `/interlock:spec`'s checkpoint) are also callable standalone.
   - **The summary names the run and where it closed.** Every terminal summary now carries `run: <runId>` (or `run: none — the run halted before a plan was adopted`), `project: <slug>` and `cwd: <absolute path>` rows, so a reader who was not watching can find the trajectory file and the checkout afterwards. `<slug>` is a pure function of the closing directory (`lib/project-slug.mjs`), matching the directory name Claude Code uses under `~/.claude/projects`.
   - **A clean completion reminds you to archive.** When every task is ticked and the run did not halt, the summary prints `ARCHIVE PENDING — <change>: after merge, run openspec archive <change>` — plus `also unarchived: <n> completed change(s) — run interlock drift` when other changes are also sitting there — right before the closing "do not start another run" line. It is a reminder, never a gate: the exit code never moves, because the shipped change satisfies the unarchived check by construction at every clean close.
   - **`interlock doctor` stops reporting green for a run whose first ping prompts.** `REQUIRED_COMMANDS` gains `test`, `printenv` and `mkdir` — the commands the environment probe actually shells out to — each with a `why`, and a new `notify` row (`ok` naming the server, `skip` naming `INTERLOCK_NTFY_TOPIC`, never the value). A repo-fact test now checks this repository's own `.claude/settings.json` against the derived list, and a drift test extracts every instructed command out of `workflows/ship.js` and `lib/prompts/*.mjs` and fails, naming the file and the command, the moment one falls outside `REQUIRED_COMMANDS`, the runner commands, or the documented host read-only set (`HOST_READ_ONLY`).
 
   All four are additive: unset `INTERLOCK_NTFY_TOPIC` and a run behaves exactly as before, plus the three new identity rows and, on a clean ship, the archive line. See [when it stops](docs/04-when-it-stops.md) for `ARCHIVE PENDING` and `PUSH FAILED`, and [push notifications](docs/07-cli-and-configuration.md#the-one-network-call-push-notifications) for the two environment variables.
 
-- **The CLIs install without Claude Code.** `package.json` was `private: true`, so the only way onto a PATH was a git checkout or the plugin install — even though the policy engine, the graph and the runner are stdlib Node with no dependencies and each is useful outside a Claude Code session. The package publishes as **`@renzrollon/interlock`** (`npm i -g @renzrollon/interlock`, or `npx -p @renzrollon/interlock interlock ...`), and the plugin install path is untouched.
+- **The CLIs install without Claude Code.** `package.json` was `private: true`, so the only way onto a PATH was a git checkout or the plugin install — even though the policy engine, the graph and the runner are stdlib Node with no dependencies and each is useful outside a Claude Code session. The package publishes as **`@renzrollon/interlock`** (install that package globally), and the plugin install path is untouched.
 
   What ships is a **whitelist**, not an ignore list: `files` names `bin`, `lib`, `workflows`, `skills`, `hooks`, `agents`, `shared`, `.claude-plugin` and the three root documents, so a new directory cannot ship by accident. The failure that whitelist invites is the opposite one — a reachable `lib/` file left out packs cleanly, installs cleanly, and dies at the user's first command — so `test/spine/package.test.mjs` walks the transitive relative-import closure of **every declared `bin` entry** (including the bare side-effect `import` that is how `bin/interlock-graph` reaches the whole graph CLI) and fails naming any reached file no `files` entry covers. It also asserts each `bin` entry exists, is executable and carries the node shebang, and that `package.json`, `.claude-plugin/plugin.json` and `.claude-plugin/marketplace.json` carry **one** `MAJOR.MINOR.PATCH` version — the `bump-release` skill keeps bumping them together, and a partial bump is now a red build rather than a habit that held.
 
@@ -283,7 +290,7 @@ this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ### Removed
 
-- **`/interlock:session-retro`** moved to [renzrollon/shippable-skills](https://github.com/renzrollon/shippable-skills). It is no longer part of this plugin. Install it with `npx skills add renzrollon/shippable-skills` (or the Claude Code plugin on that repo). The live-session retro was never Interlock-specific; shipping it here blocked Cursor, Copilot, and Codex.
+- **`/interlock:session-retro`** moved to renzrollon/shippable-skills. It is no longer part of this plugin. Install it from that repository (or the Claude Code plugin on that repo). The live-session retro was never Interlock-specific; shipping it here blocked Cursor, Copilot, and Codex.
 
 ### Changed
 
@@ -299,7 +306,7 @@ The second **made them true** — the ship loop moved out of prose and into a
 dynamic-workflow script backed by a policy CLI, and the opt-in continuity path
 gained the fail-closed readiness gate it needs.
 
-> **Breaking:** `/interlock:ship` is now a [dynamic workflow](https://code.claude.com/docs/en/workflows)
+> **Breaking:** `/interlock:ship` is now a dynamic workflow
 > rather than a skill. Interlock requires **Claude Code v2.1.154+ with dynamic
 > workflows enabled**. Where workflows are disabled — `disableWorkflows`, org
 > policy, `CLAUDE_CODE_DISABLE_WORKFLOWS`, or a Pro plan that has not enabled
@@ -482,7 +489,7 @@ that on should be a decision made against real data rather than an intuition.
 And earned autonomy stays storage-only (§4.2 D) for the same reason: a feature
 that gates a workflow should earn its own trust first.
 
-## [0.1.0] — 2026-08-12
+## 0.1.0 — 2026-08-12
 
 Initial release. Interlock is a Claude Code plugin that layers autonomous
 spec-driven orchestration on top of the OpenSpec CLI.
@@ -540,5 +547,3 @@ spec-driven orchestration on top of the OpenSpec CLI.
   languages get docs and spec indexing plus the full workflow, but no
   import/symbol edges — the skills state this rather than implying completeness.
 - The autonomy ladder ships opt-in until it has accumulated real run data.
-
-[0.1.0]: https://github.com/renzrollon/interlock/releases/tag/v0.1.0

package/bin/interlock

@@ -68,7 +68,13 @@ import { haltStep } from '../lib/run.mjs'
 import { explicitStateHome, resolveStateHome } from '../lib/state-home.mjs'
 import { probeClaudeEffort, probeClaudeVersion } from '../lib/host/claude-cli.mjs'
 import { observeClaudeEnv, runtimeSlotsOf } from '../lib/host/claude-env.mjs'
-import { composeCheckpointMessage, postNtfy, readNotifyConfig, NOTIFY_TOPIC_ENV } from '../lib/notify.mjs'
+import {
+  composeCheckpointMessage,
+  postNtfy,
+  readNotifyConfig,
+  NOTIFY_TOPIC_ENV,
+  DEFAULT_NTFY_URL
+} from '../lib/notify.mjs'
 import { classifySurface } from '../lib/surface.mjs'
 import { evaluateGate, formatGate, TOLERANCE_BAND } from '../lib/findings.mjs'
 import { inspectChange, resolveChange, listChanges, formatInspection, tickTasks, planCoverage } from '../lib/artifacts.mjs'
@@ -171,9 +177,11 @@ Usage:
                  [--priority high|default]   checkpoint reached while nobody was
   interlock notify checkpoint <change>       watching still reaches someone. The
                                              only outbound request this CLI makes.
-                                             Topic from INTERLOCK_NTFY_TOPIC,
-                                             server from INTERLOCK_NTFY_URL
-                                             (default https://ntfy.sh). Unset
+                                             Topic from the plugin option or
+                                             INTERLOCK_NTFY_TOPIC, server from
+                                             the plugin option or
+                                             INTERLOCK_NTFY_URL
+                                             (default ${DEFAULT_NTFY_URL}). Unset
                                              topic prints "not configured" and
                                              exits 0; a failed push exits 1.
                                              --json emits { sent, reason }

package/hooks/preflight.mjs

@@ -24,7 +24,7 @@
 // directory alone, as before.
 
 import { execFileSync } from 'node:child_process'
-import { existsSync, realpathSync } from 'node:fs'
+import { appendFileSync, existsSync, realpathSync } from 'node:fs'
 import { dirname, join, resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
 
@@ -166,7 +166,48 @@ 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 { message, stateHome } = run()
   const lines = [message, ...(await interruptedLines(process.cwd(), stateHome))].filter(Boolean)
   if (lines.length) report(lines.join('\n'))

package/lib/doctor.mjs

@@ -78,6 +78,7 @@ import {
   readModelRouting
 } from './host/claude-env.mjs'
 import { RUNTIME } from './limits.mjs'
+import { DEFAULT_NTFY_URL } from './notify-defaults.mjs'
 import { STATE_HOME_ENV, resolveStateHome } from './state-home.mjs'
 
 /** The installed copy of the plugin — the one whose workflow and agents run. */
@@ -203,8 +204,7 @@ export const REQUIRED_COMMANDS = Object.freeze([
  * Commands Claude Code auto-approves as read-only no matter what the
  * project's own allowlist says, so a briefing that instructs one of these
  * needs no rule of its own and the drift test below must not demand one.
- * Source: the Claude Code permissions documentation
- * (https://docs.claude.com/en/docs/claude-code/permissions), checked
+ * Source: the Claude Code permissions documentation, checked
  * 2026-09-07 — a host claim this module cannot itself verify, so it is dated
  * and cited rather than asserted bare. If the host narrows this list the
  * failure is loud: the drift test below goes red naming the command, never a
@@ -586,11 +586,11 @@ function checkOpenSpec(root, env, probe) {
   if (configured) {
     return check('openspec', 'warn', 'the openspec CLI is not on PATH; ship reads artifacts from disk, but /interlock:spec and /interlock:bootstrap need it', {
       evidence: ['openspec/config.yaml is present, so existing changes are still readable'],
-      fix: 'npm install -g openspec (requires Node 20.19.0+).'
+      fix: 'Install the openspec command globally. It needs Node.js 20.19.0 or newer.'
     })
   }
   return check('openspec', 'fail', 'no openspec CLI on PATH and no openspec/ project in this repo — neither authoring nor shipping a change can start', {
-    fix: 'npm install -g openspec && openspec init'
+    fix: 'Install the openspec command globally (Node.js 20.19.0 or newer), then run `openspec init` in the project root.'
   })
 }
 
@@ -915,17 +915,22 @@ function checkPermissions(root, required, { home, sources } = {}) {
 /**
  * Advice, never a gate: push notification is an optional feature, so this row
  * is `ok` or `skip` and NEVER `fail` — an operator who never configured it has
- * not degraded their run. Reads the same two environment variable NAMES
- * `lib/notify.mjs` reads (`INTERLOCK_NTFY_TOPIC`, `INTERLOCK_NTFY_URL`) by
- * literal string rather than by importing that module: this file has no
- * other reason to depend on the network transport, and the two spellings are
- * pinned identically in both modules' own test suites. The topic value is
- * never read into a string that could reach the report; only the server URL,
- * which is not a capability, is echoed.
+ * not degraded their run. Reads the same names `lib/notify.mjs` reads — the
+ * plugin options `CLAUDE_PLUGIN_OPTION_NTFY_TOPIC` / `CLAUDE_PLUGIN_OPTION_NTFY_URL`
+ * and the shell variables `INTERLOCK_NTFY_TOPIC` / `INTERLOCK_NTFY_URL` — by
+ * literal string rather than by importing the transport. The default server
+ * comes from `notify-defaults.mjs`, so this row cannot name a different one.
+ * The topic value is never read into a string that could reach the report;
+ * only the server URL, which is not a capability, is echoed.
  */
+function configuredValue(env, name) {
+  return env && typeof env[name] === 'string' && env[name].trim() ? env[name].trim() : ''
+}
+
 function checkNotify(env) {
   try {
-    const topic = env && typeof env.INTERLOCK_NTFY_TOPIC === 'string' ? env.INTERLOCK_NTFY_TOPIC.trim() : ''
+    const topic =
+      configuredValue(env, 'CLAUDE_PLUGIN_OPTION_NTFY_TOPIC') || configuredValue(env, 'INTERLOCK_NTFY_TOPIC')
     if (!topic) {
       return check(
         'notify',
@@ -934,9 +939,9 @@ function checkNotify(env) {
       )
     }
     const url =
-      env && typeof env.INTERLOCK_NTFY_URL === 'string' && env.INTERLOCK_NTFY_URL.trim()
-        ? env.INTERLOCK_NTFY_URL.trim()
-        : 'https://ntfy.sh'
+      configuredValue(env, 'CLAUDE_PLUGIN_OPTION_NTFY_URL') ||
+      configuredValue(env, 'INTERLOCK_NTFY_URL') ||
+      DEFAULT_NTFY_URL
     return check('notify', 'ok', `push configured: ${url}`)
   } catch (err) {
     // Fail-open, and never `fail`: an unreadable env is a reason to skip the
@@ -1427,12 +1432,12 @@ export function evalPrerequisiteChecks(pluginRoot, env = process.env) {
 
     return [
       enabled
-        ? check('evals-harness', 'ok', `${EVAL_ENABLEMENT_VAR} is set, so \`claude plugin eval\` is enabled`)
+        ? check('evals-harness', 'ok', `${EVAL_ENABLEMENT_VAR} is set, so the early-access harness is enabled`)
         : check(
             'evals-harness',
             'skip',
-            `${EVAL_ENABLEMENT_VAR} is not set, so the eval harness is unavailable — no ship run needs it`,
-            { fix: `export ${EVAL_ENABLEMENT_VAR}=1 to run \`claude plugin eval\`. Nothing else changes.` }
+            `${EVAL_ENABLEMENT_VAR} is not set, so the early-access harness is unavailable — no ship run needs it`,
+            { fix: `Set one of the harness prerequisites by assigning ${EVAL_ENABLEMENT_VAR} the value 1. Nothing else changes.` }
           ),
       credential
         ? // The NAME of the variable, never its value. Reporting which one is

package/lib/evals-triage.mjs

@@ -49,7 +49,7 @@ function graderName(grader, i) {
   return grader && typeof grader.name === 'string' && grader.name ? grader.name : `grader-${i + 1}`
 }
 
-// Two results shapes reach triage: the one `claude plugin eval` writes at
+// Two results shapes reach triage: the one the harness writes at
 // schemaVersion 1 (`name`, `arms.with` / `arms['with-only']`) and the legacy
 // `id` / `runs` shape the offline unit tests construct. Normalizing both at the
 // case boundary keeps `classifyCase` the single classification rule — a second

package/lib/notify-defaults.mjs

@@ -0,0 +1,6 @@
+// The server used when an operator names a topic and no server.
+// One spelling, imported by the transport, the doctor and the CLI help,
+// so those three cannot drift.
+
+/** The public server, used when no server was configured. */
+export const DEFAULT_NTFY_URL = 'https://ntfy.sh'

package/lib/notify.mjs

@@ -1,6 +1,6 @@
-// The one network call this CLI ever makes: a push to ntfy.sh (or a
-// self-hosted server) so a ship run that stops while nobody is watching can
-// still reach someone.
+// The one network call this CLI ever makes: a push to the configured server
+// (the public default, or a server the operator named) so a ship run that
+// stops while nobody is watching can still reach someone.
 //
 // Three properties are load-bearing, and every one of them exists because
 // this module is the CLI's only exception to "no network":
@@ -11,8 +11,8 @@
 //      so there is no settings file this module could misread in the first
 //      place.
 //
-//   2. THE TOPIC NEVER LEAVES. The topic is the only auth ntfy.sh has on a
-//      public server; it is a capability, not a label. `readNotifyConfig`
+//   2. THE TOPIC NEVER LEAVES. The topic is the only auth the public server
+//      has; it is a capability, not a label. `readNotifyConfig`
 //      never echoes it, `sanitizeReason` strips it (and the server URL) from
 //      every failure reason before that reason reaches a summary line, a
 //      receipt event or the trajectory, because a `fetch` failure's own
@@ -29,15 +29,23 @@
 // design D1, D2, D4, D5, D14 (add-harden-unattended-ship-runs).
 
 import { LIMITS } from './limits.mjs'
+import { DEFAULT_NTFY_URL } from './notify-defaults.mjs'
 
-/** Where the topic is read from. Set by the operator, never by the repo. */
+export { DEFAULT_NTFY_URL }
+
+/** Where the topic is read from. Chosen by the operator, never by the repo. */
 export const NOTIFY_TOPIC_ENV = 'INTERLOCK_NTFY_TOPIC'
 
-/** Where a self-hosted server is read from. Unset means the public default. */
+/** Where a self-hosted server is read from. Absent means the public default. */
 export const NOTIFY_URL_ENV = 'INTERLOCK_NTFY_URL'
 
-/** The public ntfy server, used when `NOTIFY_URL_ENV` is unset. */
-export const DEFAULT_NTFY_URL = 'https://ntfy.sh'
+/**
+ * Plugin options the host injects into a hook process, from `userConfig`
+ * `ntfy_topic` and `ntfy_url`. Preferred over the shell variables when present,
+ * so a value the operator typed into the plugin is the one that is shared.
+ */
+export const NOTIFY_TOPIC_OPTION = 'CLAUDE_PLUGIN_OPTION_NTFY_TOPIC'
+export const NOTIFY_URL_OPTION = 'CLAUDE_PLUGIN_OPTION_NTFY_URL'
 
 function messageOf(err) {
   return (err && err.message) || String(err)
@@ -60,26 +68,34 @@ function urlShapeInvalid(url) {
   }
 }
 
+function trimmed(source, name) {
+  if (!source || typeof source[name] !== 'string') return ''
+  return source[name].trim()
+}
+
 /**
- * Read push configuration from the environment. Never the tree — `INTERLOCK_
- * NTFY_TOPIC` and `INTERLOCK_NTFY_URL` are the whole of it (design D2).
+ * Read push configuration. Never the tree. A plugin option the host injected
+ * wins over the shell variable of the same meaning, and an absent topic is
+ * unconfigured rather than an error (design D2). The shell variables remain
+ * the channel for a terminal, CI, and any host that does not inject options.
  *
- * @param {object} env  environment to read (injected in tests; `process.env` at call sites)
+ * @param {object} source  values to read (injected in tests; the process values at call sites)
  * @returns {{topic: string, url: string} | {topic: null} | {invalid: string}}
  *   `{ topic: null }` when push is simply unconfigured — not an error, the
  *   default and by far the common case. `{ invalid: '<VAR>' }` names the
  *   offending variable and never its value.
  */
-export function readNotifyConfig(env) {
-  const rawTopic = env && typeof env[NOTIFY_TOPIC_ENV] === 'string' ? env[NOTIFY_TOPIC_ENV].trim() : ''
+export function readNotifyConfig(source) {
+  const optionTopic = trimmed(source, NOTIFY_TOPIC_OPTION)
+  const shellTopic = trimmed(source, NOTIFY_TOPIC_ENV)
+  const rawTopic = optionTopic || shellTopic
   if (!rawTopic) return { topic: null }
-  if (topicShapeInvalid(rawTopic)) return { invalid: NOTIFY_TOPIC_ENV }
+  if (topicShapeInvalid(rawTopic)) return { invalid: optionTopic ? NOTIFY_TOPIC_OPTION : NOTIFY_TOPIC_ENV }
 
-  const rawUrl =
-    env && typeof env[NOTIFY_URL_ENV] === 'string' && env[NOTIFY_URL_ENV].trim()
-      ? env[NOTIFY_URL_ENV].trim()
-      : DEFAULT_NTFY_URL
-  if (urlShapeInvalid(rawUrl)) return { invalid: NOTIFY_URL_ENV }
+  const optionUrl = trimmed(source, NOTIFY_URL_OPTION)
+  const shellUrl = trimmed(source, NOTIFY_URL_ENV)
+  const rawUrl = optionUrl || shellUrl || DEFAULT_NTFY_URL
+  if (urlShapeInvalid(rawUrl)) return { invalid: optionUrl ? NOTIFY_URL_OPTION : NOTIFY_URL_ENV }
 
   return { topic: rawTopic, url: rawUrl }
 }
@@ -156,10 +172,10 @@ export function sanitizeReason(reason, { topic, url } = {}) {
  * all: EVERY headline this module sends contains an em dash (`SHIP COMPLETE —
  * <change>`), HTTP header values are ByteStrings, and Node's `fetch` throws
  * `Cannot convert argument to a ByteString` rather than transmitting one. So
- * a non-ASCII value is sent as an RFC 2047 base64 encoded-word, which ntfy
- * documents as the supported encoding for exactly this case (docs.ntfy.sh
- * §Publish → "ntfy supports UTF-8 in HTTP headers, but not every library or
- * programming language does", checked 2026-09-07).
+ * a non-ASCII value is sent as an RFC 2047 base64 encoded-word, which the
+ * server's publish documentation names as the supported encoding for exactly
+ * this case ("UTF-8 in HTTP headers" is not accepted by every client,
+ * checked 2026-09-07).
  *
  * A pure-ASCII value is passed through untouched, so the common `interlock
  * notify --title` case stays readable on the wire.
@@ -175,7 +191,7 @@ export function encodeHeaderValue(value) {
 }
 
 /**
- * Post one ntfy message. Never throws: every failure mode — invalid
+ * Post one message. Never throws: every failure mode — invalid
  * configuration, a non-2xx status, a network error, the timeout — resolves
  * to `{ sent: false, reason }`, sanitized, so the caller can always print
  * something and never has to catch anything.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@renzrollon/interlock",
-  "version": "1.2.0",
+  "version": "1.2.1",
   "description": "Autonomous spec-driven development orchestration for Claude Code, layered on OpenSpec",
   "type": "module",
   "engines": {
@@ -21,7 +21,8 @@
     "types",
     "agents",
     "shared",
-    ".claude-plugin",
+    ".claude-plugin/plugin.json",
+    ".claude-plugin/icon.png",
     "README.md",
     "LICENSE",
     "CHANGELOG.md"

package/skills/evals/SKILL.md

@@ -2,8 +2,8 @@
 name: evals
 description: Author an Interlock eval case from an observed model-behaviour failure, and read a completed eval results run. Use when you have a reproduced failure — an archived proposal, a changelog entry, a run artifact, or a transcript — worth regression-testing against a real model, or when an eval run has finished and you need to know whether it is a regression, run-to-run variance, or no signal. Authoring needs cited evidence; the verdict comes from `interlock evals triage`, never from your own reading.
 license: MIT
-compatibility: Requires the early-access eval harness (`claude plugin eval`, enabled with CLAUDE_CODE_WALNUT_SPIRE=1) to RUN a suite. Authoring a case and triaging an existing results file need only Node.js >= 18 and the bundled interlock CLI.
-allowed-tools: Bash(interlock *) Bash(claude plugin eval *) Read Grep Glob Write
+compatibility: Requires the early-access harness (claude plugin eval, enabled with CLAUDE_CODE_WALNUT_SPIRE=1) to RUN a suite. Authoring a case and triaging an existing results file need only Node.js >= 18 and the bundled interlock CLI.
+allowed-tools: Bash(interlock *) Bash(claude plugin eval:*) Read Grep Glob Write
 metadata:
   type: authoring
   outputs:
@@ -148,7 +148,7 @@ test until it passes" failure the suite exists to prevent, one layer up.
 
 ## 5. When the harness is gated
 
-`claude plugin eval` prints `` `plugin eval` is currently in early access `` and
+The host command claude plugin eval prints that it is currently in early access and
 does nothing until `CLAUDE_CODE_WALNUT_SPIRE=1` is set in the environment — never
 in committed `.claude/settings.json`, which would produce a suite that looks
 configured and does not run.

package/skills/fix-tests/SKILL.md

@@ -4,7 +4,7 @@ description: Discover and persist how a project's tests run, then run the suite
 license: MIT
 compatibility: Requires the project's own test tooling. Node.js >= 18 for the bundled interlock CLI.
 argument-hint: "[--e2e] [--dry-run] [--baseline <ref>] [--from-log <path>] [--reconfigure]"
-allowed-tools: Bash Read Write Edit Glob Grep
+allowed-tools: Read Write Edit Glob Grep
 metadata:
   type: execution
   outputs:
@@ -40,7 +40,7 @@ Persist the profile and mirror it into the `## Testing` block of the first instr
 
 ## 2. Run and baseline
 
-Run the unit command. Record `total`, `passed`, `failed`, `skipped` — this is the baseline that step 6 asserts against.
+Run the unit command under the permissions already granted to this project. This skill does not pre-approve a shell. Record `total`, `passed`, `failed`, `skipped` — this is the baseline that step 6 asserts against.
 
 Split failures into:
 

package/skills/spec/SKILL.md

@@ -128,12 +128,7 @@ Parse `applyRequires` (artifacts needed before implementation), `artifacts` (eac
 Then loop, in dependency order, over every artifact that is `ready`:
 
 ```bash
-openspec instructions <artifact-id> --change "<name>" --json | python3 -c '
-import json,sys
-d=json.load(sys.stdin)
-keep=("instruction","template","resolvedOutputPath","context","rules")
-print(json.dumps({k:d[k] for k in keep if d.get(k)}, separators=(",",":")))
-'
+openspec instructions <artifact-id> --change "<name>" --json | node "${CLAUDE_PLUGIN_ROOT}/skills/spec/scripts/compact-instructions.mjs"
 ```
 
 Filter each ready artifact independently; do not dump the full instructions response or prefetch every artifact. The compact response carries `instruction` (schema guidance), `template` (the structure to fill), `resolvedOutputPath`, and non-empty `context` / `rules`.

package/skills/spec/scripts/compact-instructions.mjs

@@ -0,0 +1,30 @@
+// Compact an `openspec instructions --json` payload to the fields an author fills.
+// Shipped in the plugin so the spec skill does not inline another interpreter.
+
+import { readFileSync } from 'node:fs'
+
+const keep = ['instruction', 'template', 'resolvedOutputPath', 'context', 'rules']
+
+let raw
+try {
+  raw = readFileSync(0, 'utf8')
+} catch (err) {
+  process.stderr.write(`compact-instructions: could not read stdin: ${(err && err.message) || err}\n`)
+  process.exit(1)
+}
+
+let data
+try {
+  data = JSON.parse(raw)
+} catch (err) {
+  process.stderr.write(`compact-instructions: stdin is not JSON: ${(err && err.message) || err}\n`)
+  process.exit(1)
+}
+
+const out = {}
+if (data && typeof data === 'object' && !Array.isArray(data)) {
+  for (const key of keep) {
+    if (data[key]) out[key] = data[key]
+  }
+}
+process.stdout.write(JSON.stringify(out))

package/.claude-plugin/marketplace.json

@@ -1,19 +0,0 @@
-{
-  "name": "interlock",
-  "description": "Spec-driven development orchestration for Claude Code. Layers autonomous multi-agent workflows on top of OpenSpec: repo onboarding, reviewed specs, and start-to-commit shipping.",
-  "owner": {
-    "name": "Carl Rollon",
-    "url": "https://github.com/renzrollon"
-  },
-  "plugins": [
-    {
-      "name": "interlock",
-      "source": "./",
-      "description": "Autonomous spec-driven development orchestration for Claude Code, layered on OpenSpec.",
-      "version": "1.2.0",
-      "author": {
-        "name": "Carl Rollon"
-      }
-    }
-  ]
-}