harness-everything 0.31.2 → 0.32.0

package/ci/mechanism-2ba-step-type-docs.test.js

@@ -0,0 +1,166 @@
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const ROOT = path.resolve(__dirname, '..');
+const registryFile = path.join(ROOT, 'hooks', 'scripts', 'lib', 'step-types.json');
+const routerFile = path.join(ROOT, 'harness-everything', 'scripts', 'kernel-router.js');
+const AUTHORITATIVE_DOC = 'harness-everything/references/router-workflow-plan.md';
+const ALLOWED_LIST_DOCS = [
+  'docs/routing.md',
+  'harness-everything/references/router-workflow-plan.md',
+  'harness-everything/references/triage-and-tiers.md',
+  'docs/workflows/harness-everything.md',
+];
+const START = '<!-- step-types:start -->';
+const END = '<!-- step-types:end -->';
+const FIX_PROMPT = 'Fix this checkout bug and add a regression test.';
+const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'harness-step-type-docs-'));
+let failed = 0;
+
+process.on('exit', () => fs.rmSync(tempRoot, { recursive: true, force: true }));
+
+console.log('\n[2ba] step-type registry documentation and router drift...');
+
+function check(name, ok, detail) {
+  if (ok) console.log(`✅ ${name}`);
+  else {
+    failed++;
+    console.log(`❌ ${name}`);
+    if (detail) console.log(`   ${detail}`);
+  }
+}
+
+function checkCase(name, run) {
+  try {
+    run();
+    check(name, true);
+  } catch (error) {
+    check(name, false, error && error.message ? error.message : String(error));
+  }
+}
+
+// Independent oracle: renders the registry directly from the JSON file, not through the runtime loader.
+function renderRegistry(entries) {
+  const byId = (left, right) => (left.id < right.id ? -1 : left.id > right.id ? 1 : 0);
+  const list = bindings => bindings.map(binding => `\`${binding}\``).join(', ') || 'none';
+  return entries.slice().sort(byId).map(entry =>
+    `- \`${entry.id}\` — required bindings: ${list(entry.requiredBindings)} — forbidden bindings: ${list(entry.forbiddenBindings)}`,
+  );
+}
+
+function markerBlocks(text, label) {
+  const lines = text.split('\n');
+  const blocks = [];
+  let openAt = null;
+  lines.forEach((line, index) => {
+    const marker = line.trim();
+    if (marker === START) {
+      if (openAt !== null) throw new Error(`${label}: nested step-types:start at line ${index + 1}`);
+      openAt = index;
+    } else if (marker === END) {
+      if (openAt === null) throw new Error(`${label}: step-types:end without start at line ${index + 1}`);
+      blocks.push(lines.slice(openAt + 1, index).map(item => item.trim()).filter(Boolean));
+      openAt = null;
+    }
+  });
+  if (openAt !== null) throw new Error(`${label}: step-types:start is never closed`);
+  return blocks;
+}
+
+function routeFixPrompt(runtimeRoot, workspace) {
+  const home = path.join(tempRoot, `home-${Math.random().toString(36).slice(2)}`);
+  fs.mkdirSync(home, { recursive: true });
+  const payload = { session_id: `2ba-${Math.random().toString(36).slice(2)}`, cwd: workspace, prompt: FIX_PROMPT };
+  return spawnSync(process.execPath, [path.join(runtimeRoot, 'harness-everything', 'scripts', 'kernel-router.js')], {
+    cwd: workspace,
+    encoding: 'utf8',
+    input: JSON.stringify(payload),
+    env: {
+      ...process.env,
+      HARNESS_STATE_HOME: path.join(tempRoot, 'state'),
+      HARNESS_WORKSPACE_ROOT: workspace,
+      HOME: home,
+      USERPROFILE: home,
+    },
+  });
+}
+
+const registry = JSON.parse(fs.readFileSync(registryFile, 'utf8'));
+const registryIds = registry.map(entry => entry.id).sort();
+const expectedLines = renderRegistry(registry);
+
+checkCase('2ba. every step-types marker block in the allowed-list docs equals the registry rendering', () => {
+  let total = 0;
+  for (const doc of ALLOWED_LIST_DOCS) {
+    const blocks = markerBlocks(fs.readFileSync(path.join(ROOT, doc), 'utf8'), doc);
+    for (const block of blocks) {
+      total++;
+      if (JSON.stringify(block) !== JSON.stringify(expectedLines)) {
+        throw new Error(`${doc} marker block drifted from the registry:\n${block.join('\n')}\nexpected:\n${expectedLines.join('\n')}`);
+      }
+    }
+  }
+  if (total === 0) throw new Error('no step-types marker block found in any allowed-list doc');
+  const authoritative = markerBlocks(fs.readFileSync(path.join(ROOT, AUTHORITATIVE_DOC), 'utf8'), AUTHORITATIVE_DOC);
+  if (authoritative.length !== 1) throw new Error(`${AUTHORITATIVE_DOC} must carry exactly one step-types marker block; found ${authoritative.length}`);
+});
+
+checkCase('2ba. router lists exactly the registry step-type ids', () => {
+  const routed = routeFixPrompt(ROOT, ROOT);
+  if (routed.status !== 0) throw new Error(`router exited ${routed.status}: ${routed.stderr}`);
+  const match = routed.stdout.match(/Record ordered step types \(([^)]*)\) and their bindings/);
+  if (!match) throw new Error('router did not print the ordered step-type list');
+  const listed = match[1].split(',').map(item => item.trim());
+  if (JSON.stringify(listed) !== JSON.stringify(registryIds)) {
+    throw new Error(`router listed [${listed.join(', ')}]; registry ids are [${registryIds.join(', ')}]`);
+  }
+});
+
+checkCase('2ba. router example plan does not steer step authoring toward behavior-change', () => {
+  const routed = routeFixPrompt(ROOT, ROOT);
+  const recordPlan = routed.stdout.split('\n').find(line => line.includes('Record plan:')) || '';
+  if (!recordPlan) throw new Error('router did not print a Record plan example');
+  if (recordPlan.includes('behavior-change')) throw new Error(`example still hard-codes behavior-change: ${recordPlan}`);
+});
+
+checkCase('2ba. router prints the explicit-choice guidance line exactly once in fresh tier2 output', () => {
+  const guidance = '- Replace <step-type-id> with a registered type you choose explicitly; mixed docs+code work uses separate doc-change and behavior-change steps; keep the verification step.';
+  const routed = routeFixPrompt(ROOT, ROOT);
+  if (routed.status !== 0) throw new Error(`router exited ${routed.status}: ${routed.stderr}`);
+  const matches = routed.stdout.split('\n').filter(line => line.trim() === guidance);
+  if (matches.length !== 1) throw new Error(`expected the guidance line exactly once; found ${matches.length}`);
+});
+
+checkCase('2ba. router record-plan guidance keeps the space after "node" in fresh tier2 output', () => {
+  const routed = routeFixPrompt(ROOT, ROOT);
+  if (routed.status !== 0) throw new Error(`router exited ${routed.status}: ${routed.stderr}`);
+  if (!routed.stdout.includes('   - Record plan: node "')) {
+    throw new Error(`router record-plan line lacks "Record plan: node"; got: ${routed.stdout.split('\n').find(line => line.includes('Record plan')) || '(none)'}`);
+  }
+});
+
+checkCase('2ba. router never crashes or prints a stale step-type list when the registry is missing', () => {
+  const copy = path.join(tempRoot, 'runtime-without-registry');
+  fs.cpSync(ROOT, copy, {
+    recursive: true,
+    filter: source => !/[\\/](node_modules|\.git|benchmarks|plugins)([\\/]|$)/.test(source),
+  });
+  fs.rmSync(path.join(copy, 'hooks', 'scripts', 'lib', 'step-types.json'));
+  const routed = routeFixPrompt(copy, copy);
+  if (routed.status !== 0) throw new Error(`router exited ${routed.status} without the registry: ${routed.stderr}`);
+  if (/Record ordered step types \(/.test(routed.stdout)) throw new Error('router printed a step-type list without a registry');
+  if (!routed.stderr.includes('cannot load step-type registry')) {
+    throw new Error(`router did not surface the missing registry visibly; stderr: ${routed.stderr}`);
+  }
+});
+
+checkCase('2ba. router-workflow-plan documents old-runtime rejection of persisted doc-change plans', () => {
+  const text = fs.readFileSync(path.join(ROOT, AUTHORITATIVE_DOC), 'utf8');
+  for (const required of ['doc-change', 'declared-only', 'planning:steps-invalid']) {
+    if (!text.includes(required)) throw new Error(`${AUTHORITATIVE_DOC} must mention ${required}`);
+  }
+});
+
+process.exitCode = failed ? 1 : 0;

package/ci/mechanism-test.js

@@ -7,7 +7,7 @@
  * keeps the test code highly decoupled, and simplifies debugging and adding new test suites.
  */
 
-const { spawnSync } = require('child_process');
+const { spawnTestNode } = require('./lib/isolated-test-process');
 const fs = require('fs');
 const path = require('path');
 
@@ -35,7 +35,7 @@ files.forEach(file => {
   const filePath = path.join(evalDir, file);
   console.log(`\n▶️  Running test suite: ${file}`);
   
-  const testRun = spawnSync('node', [filePath], {
+  const testRun = spawnTestNode([filePath], {
     stdio: 'inherit',
     cwd: projectRoot,
     env: { ...process.env, CLAUDE: '1' }

package/docs/platform-capabilities.md

@@ -116,6 +116,10 @@ harness codex-hooks uninstall
 
 The installer copies the current packaged runtime into `$CODEX_HOME/harness-everything/compat-hooks/` and merges absolute-path entries into `$CODEX_HOME/hooks.json`. harness codex-hooks status reports `inactive` when the compatibility hooks are absent, or `configured-unverified` when their files are healthy; it cannot read Codex trust state. A successful Codex run of plugin-sync.js installs or refreshes this copy automatically. The installer does **not** modify `config.toml`, trust hashes, approval policy, or hook enablement. Codex must still show/review/trust the resulting non-managed hooks through its normal `/hooks` flow.
 
+Updates retain at most two fingerprinted runtimes: the current runtime and the immediately previous distinct runtime. A third distinct install collects the oldest; sessions older than one update must restart. Reinstalling the same fingerprint preserves an intact previous runtime and drops a missing or modified one. `status` reports current and previous runtime file integrity separately and is unhealthy while a recorded previous runtime is missing or modified; this is filesystem health, not Codex hook trust or dispatch. Install, update, and uninstall hold an exclusive `compat-hooks.lock` directory for the whole manifest-read → runtime → hooks/manifest commit → collection transaction, so concurrent installers serialize instead of collecting each other's runtime. Each lock directory is created atomically together with its owner token. Acquisition and stale reclaim run under a short-lived `compat-hooks.lock.guard`, stale ownership is revalidated inside it, and a lock is removed only when it still carries the exact token judged stale; release likewise removes only the releasing holder's token. A lock or guard left by a dead local process is reclaimed, and a live lock times out (60 s) before any write. Uninstall removes all retained Harness-owned runtimes. Command paths remain fingerprinted: updates may require normal Codex hook review again; Harness does not bypass that security decision.
+
+Installs of a plugin source tracked by a linked Git worktree refuse before writing. For an ordinary checkout, only modified or untracked files inside the plugin source subtree cause refusal. The runtime is built from the subtree's Git-tracked files, so `.gitignore`-excluded files (for example `.DS_Store` or `__pycache__`) are neither copied nor fingerprinted and do not block installation. The operator can explicitly pass `--allow-unreleased-source`. Packaged copies whose plugin manifest is not tracked by an enclosing repository remain supported, including copies inside an unrelated dirty repository. The mechanism and self-regression runners give child processes temporary HOME/USERPROFILE and CODEX_HOME directories. Tests must pass temporary Codex homes or mock the hook installer; mocking host commands alone does not isolate filesystem writes.
+
 Ownership is deliberately strict: update/uninstall removes only exact entries recorded in the Harness compatibility manifest. If an installed Harness entry was edited after installation, the operation fails closed rather than overwriting or deleting that user-modified entry. Unrelated pre-existing and later-added user hooks are preserved.
 
 The compatibility path registers hook commands in Codex user configuration and covers the missing plugin-mount route where user hooks dispatch. It does not repair a Codex carrier that fails to dispatch `PreToolUse` at all; those host-level execution-path limitations remain a live compatibility boundary.

package/docs/platform-compatibility.json

@@ -114,7 +114,7 @@
         "globalScope": {"status": "Mechanism verified", "paths": {"skills": ["~/.agents/skills"]}},
         "installUninstallSymmetry": {"status": "Mechanism verified", "notes": "General Harness installer ownership is mechanism-tested. The optional codex-hooks compatibility fallback separately has exact-entry update/uninstall ownership tests and preserves unrelated user hooks. Live evidence confirms trusted dispatch for the two observation handlers on one Windows Codex CLI host; native plugin mounting and other scopes remain unverified."},
         "assetsReferences": {"status": "Mechanism verified", "notes": "Packaged skill references are checked and remain inside the package."},
-        "updateSync": {"status": "Mechanism verified", "notes": "scripts/plugin-sync.js detects installed state and uses marketplace upgrade for an installed Codex plugin; after successful install/update verification it refreshes the local codex-hooks compatibility runtime and hooks.json entries. Unsupported CLI options are dropped and retried, and a Codex build without codex plugin list/add is reported as an actionable capability-boundary skip. Live marketplace source reporting and plugin-sync refresh remain unverified; the separate compatibility fallback dispatch is live-verified as recorded in the evidence artifact."},
+        "updateSync": {"status": "Mechanism verified", "notes": "scripts/plugin-sync.js detects installed state and uses marketplace upgrade for an installed Codex plugin; after successful install/update verification it refreshes the local codex-hooks compatibility runtime and hooks.json entries, retaining current plus previous distinct runtime. Tracked linked-worktree sources or dirty plugin subtrees require explicit unreleased-source opt-in; untracked packaged sources remain supported even inside unrelated dirty repositories. Unsupported CLI options are dropped and retried, and a Codex build without codex plugin list/add is reported as an actionable capability-boundary skip. Live marketplace source reporting and plugin-sync refresh remain unverified; the separate compatibility fallback dispatch is live-verified as recorded in the evidence artifact."},
         "liveHostVerification": {"status": "Partial", "evidence": "benchmarks/results/live-host/codex-2026-10-13/README.md", "notes": "The preserved artifact verifies two consecutive observation captures through the user-hook compatibility fallback on Codex CLI 0.162.1 for Windows, including current-turn labels. Native plugin mounting, marketplace source reporting, other lifecycle events, and other host/version combinations remain unverified."}
       }
     },

package/fable-mode/SKILL.md

@@ -4,7 +4,7 @@ description: "Stage large tasks through plans, named fable agents, failable chec
 license: Apache-2.0
 metadata:
   author: Miya Daniel
-  version: 0.31.0
+  version: 0.31.3
 ---
 
 # Fable Mode

package/fable-mode/execution-guardrails/SKILL.md

@@ -4,7 +4,7 @@ description: "Reference guardrails for verified warnings and safe replacements;
 license: Apache-2.0
 metadata:
   author: Miya Daniel
-  version: 0.31.0
+  version: 0.31.3
 ---
 
 # Execution Guardrails

package/fable-mode/fable-haiku/SKILL.md

@@ -4,7 +4,7 @@ description: "Reference mechanical behavior profile (legacy alias haiku) for bul
 license: Apache-2.0
 metadata:
   author: Miya Daniel
-  version: 0.31.0
+  version: 0.31.3
 ---
 
 # Fable Mode — Haiku

package/fable-mode/fable-opus/SKILL.md

@@ -4,7 +4,7 @@ description: "Reference orchestrator behavior profile (legacy alias opus) for st
 license: Apache-2.0
 metadata:
   author: Miya Daniel
-  version: 0.31.0
+  version: 0.31.3
 ---
 
 # Fable Mode — Opus

package/fable-mode/fable-sonnet/SKILL.md

@@ -4,7 +4,7 @@ description: "Reference reasoning behavior profile (legacy alias sonnet/sonnect)
 license: Apache-2.0
 metadata:
   author: Miya Daniel
-  version: 0.31.0
+  version: 0.31.3
 ---
 
 # Fable Mode — Sonnet

package/fable-mode/references/execution-phases.md

@@ -2,37 +2,105 @@
 
 ```mermaid
 flowchart TD
-  Start[Qualifying Tier 3 task] --> Discover[Discover sources, runtime, and authorized scope]
-  Discover --> Plan[Write stage map and pass conditions]
-  Plan --> Select[Resolve requested model and write audit record]
-  Select --> Delegate[Delegate to named agent or visible inline fallback]
-  Delegate --> Contract[Write stage contract]
-  Contract --> Verify[Run the named failable check]
-  Verify --> Review[Cold-review high-stakes deliverables]
-  Review --> Done[Record result or escalate blocker]
+  Start[Qualifying Tier 3 task] --> Discover[Discover runtime and authorized scope]
+  Discover --> Profile[Resolve behavior profile and runtime choice]
+  Profile --> Plan[Write dependency-aware stage map and checks]
+  Plan --> Register[Write workflow-stages.json in session state]
+  Register --> Execute[Start workflow-disposition and execute ready stages]
+  Execute --> Check[Run exact check and record correlated evidence]
+  Check --> Review[Cold-review when the selected plan requires it]
+  Review --> Done[Record result or blocker]
 ```
 
 ## Discovery and planning
 
-Read the relevant files and sources before producing an artifact. Lock the
-authorized write scope in the handoff. Number the stages, assign one artifact
-and one pass condition to each. Replan counts are advisory and never a hard
-stop; three same-signature failures still require Rule-of-3 `zoom-out`.
+Read relevant files and sources before producing an artifact. Record the
+authorized write scope. Give each stage an objective, dependencies, write set,
+expected output, exact check command, and pass condition. Required and optional
+bindings belong on the stage that needs them. Replan counts are advisory; after
+three same-signature failures, use Rule-of-3 `zoom-out`.
 
-## Delegation
+## Profiles and delegation
 
-Use `fable-orchestrator` for Opus macro work, `fable-worker-sonnet` for
-reasoning and synthesis, and `fable-worker-haiku` for mechanical work. Brief
-each worker with its exact output path, context, audit record, and check.
-Workers do not spawn workers. If the named agent is unavailable, choose the
-explicit inline fallback or stop and escalate; do not silently change models.
+Resolve a requested behavior profile with Fable's profile selector and record
+it separately from the runtime choice. `fable-orchestrator`,
+`fable-worker-sonnet`, and `fable-worker-haiku` name coordination,
+reasoning/synthesis, and mechanical-work roles. These are behavior-profile
+aliases; they do not switch the runtime model. Preserve an explicit user or
+host runtime choice. Workers do not spawn workers. If a named worker is
+unavailable, use a declared inline fallback or report the gap.
 
-## Verification and handoff
+## Active workflow
+
+For an active mandatory workflow, use the router-displayed session path for
+`workflow-stages.json` and the router-displayed `workflow-disposition.js`
+controller. Do not register active stages in a repository-local contracts
+directory. Every required stage needs `dependsOn`, `writeSet`, `checkCommand`,
+and `passCondition`; an independent plan also needs a read-only `fable-verifier`
+stage that depends on all implementation stages.
+
+Start the selected run with the controller path and session id from the router:
+
+```bash
+node "<workflow-disposition.js path from the router>" start --session-id "<session-id>"
+```
+
+The controller creates correlated run-scoped contracts. Load only bindings on
+dependency-ready stages. Record each disposition with evidence:
+
+```bash
+node "<workflow-disposition.js path from the router>" stage-binding \
+  --session-id "<session-id>" --stage-id "<stage-id>" \
+  --binding-id "<binding-id>" --disposition loaded \
+  --evidence "Read the resolved required reference for this stage."
+```
+
+Run the exact `checkCommand`; the post-tool `contract-test.js` records the
+session, run, stage, worker identity, numeric exit code, and check evidence. If
+bindings are unresolved, resolve them and rerun the exact check before passing
+the stage. Keep results under the run's `contracts/<stageId>.json` and
+`evidence/<stageId>.json` records. Stage checks, required bindings, and selected
+independent verification remain semantic MUSTs. The controller and lifecycle
+hooks are reminder-only: unresolved evidence stays visible without locking
+ordinary tools or Stop. See [`../CONTRACT-FORMAT.md`](../CONTRACT-FORMAT.md) for
+the schema and correlation rules.
+
+## Blocked recovery
 
-Before each spot-check, create `.claude/harness-everything/state/contracts/<stage>.json`
-using `CONTRACT-FORMAT.md`, then run the exact command in that contract. A
-stage is not complete until the command passes and the audit record contains
-the verifier result. Use `fable-verifier` with only the spec and artifact for
-high-stakes or unsupervised delivery. Review scope-guard output before merging.
+If `start` is called while the workflow is running, it exits 2 with
+`workflow already running; record a blocker before replanning`. From that
+running state, record evidence with `block`:
+
+```bash
+node "<workflow-disposition.js path from the router>" block \
+  --session-id "<session-id>" \
+  --evidence "The current stage map needs a bounded recovery update."
+```
+
+Update the same session's `workflow-stages.json`, retaining the approved
+requirements, workflow selection, dependencies, and required bindings. Then
+start the revised stage map:
+
+```bash
+node "<workflow-disposition.js path from the router>" start --session-id "<session-id>"
+```
+
+This starts a new run and clears the recorded block reason. If the session is
+already `blocked`, update its stage map and run `start` directly. Do not call
+`plan` from `blocked`: planning is accepted only while the workflow is pending
+or active. When an explicitly authorized scope change requires new requirement
+composition, route a new session instead of replacing approved requirements.
+
+## Legacy/manual fallback
+
+The path `.claude/harness-everything/state/contracts/<stage>.json` belongs only
+to an explicitly selected legacy/manual workflow without an active mandatory
+run. It does not register stages or correlated evidence for the current
+workflow controller. Do not use it for an active Fable workflow.
+
+## Verification and handoff
 
-When macro scaffolding ends, transition to `tdd` for focused implementation.
+Run each named check and review scope-guard evidence before delivery. When the
+selected plan requires independent verification, the verifier is read-only and
+uses a distinct worker identity after all other stages pass. Record a blocker
+or an evidence-backed result; do not discard unresolved requirements.

package/harness-everything/SKILL.md

@@ -4,7 +4,7 @@ description: "Route software/project work through Harness: classify tier/topolog
 license: Apache-2.0
 metadata:
   author: Miya Daniel
-  version: 0.31.0
+  version: 0.32.0
 ---
 
 # Harness Everything

package/harness-everything/references/router-workflow-plan.md

@@ -118,6 +118,24 @@ Examples:
 
 There is no universal `TODO → TDD → verification` pipeline.
 
+## Step types
+
+The allowed step types are the entries of `hooks/scripts/lib/step-types.json`. The list below is rendered from that registry and checked against it by `ci/mechanism-2ba-step-type-docs.test.js`; examples elsewhere may name a subset.
+
+<!-- step-types:start -->
+- `behavior-change` — required bindings: `tdd` — forbidden bindings: none
+- `commit` — required bindings: `git-commit` — forbidden bindings: none
+- `doc-change` — required bindings: none — forbidden bindings: none
+- `review` — required bindings: none — forbidden bindings: `tdd`
+- `verification` — required bindings: `verification-loop` — forbidden bindings: none
+<!-- step-types:end -->
+
+`doc-change` is declared-only: a plan author chooses it explicitly, and router classification, keyword routing and System One never infer or insert it. It has no default bindings, and an explicitly declared `tdd` binding stays legal. Mixed documentation and code work is written as ordered `doc-change` and `behavior-change` steps, and one shared verification step may verify both.
+
+Old runtimes reject a persisted non-Fable `doc-change` plan visibly at the controller and Stop boundaries (`planning:steps-invalid`). The old retained router does not show that rejection: it shows no active step. Persisted bytes are not renamed or reset. Inert Fable planning metadata is not rejected by old runtimes, because step bindings are disabled there.
+
+Registry revisions: binding defaults and required/forbidden binding policy are materialized when a plan is recorded and are not reapplied on ordinary load. Existing typed plans must still reference currently registered step types; removing a type can invalidate a plan rather than migrate or waive its stored bindings. A policy fingerprint or migration path is future work and is not implemented today.
+
 ## Binding and disclosure rule
 
 Each ordered requirement or Fable stage may declare `requiredBindings` and `optionalBindings` by stable id and concrete repository-relative path. Only the active requirement or dependency-ready stage exposes its paths. Required bindings must resolve before that step/stage passes; unknown required bindings remain visible and unresolved. Future-step paths and keyword-matched documents are never preloaded.

package/harness-everything/scripts/kernel-router.js

@@ -33,6 +33,14 @@ function issueMemoryCapability(workflow) {
   return token;
 }
 
+function needsStepTypeRegistry(plan) {
+  return Boolean(
+    plan && plan.strategySelection === 'selected' &&
+    ['tier2', 'tier3'].includes(plan.tier) && plan.strategy &&
+    !String(plan.strategy).startsWith('fable-')
+  );
+}
+
 // Host-generated background-task notifications arrive as UserPromptSubmit
 // hook payloads but are not user input (#168). Routing them like prompts
 // replaces the workflow contract mid-turn (e.g. deferred -> a new Tier-2).
@@ -44,11 +52,28 @@ function isHostNotificationPrompt(prompt) {
   return /^<task-notification[\s>][\s\S]*<\/task-notification>\s*$/i.test(text);
 }
 
+function stepTypeIdsFor(hooksRoot) {
+  try {
+    return require(path.join(hooksRoot, 'lib/workflow-obligations')).stepTypeIds();
+  } catch {
+    return null;
+  }
+}
+
 function persistWorkflow(contract, payload, prompt) {
   const plan = contract && contract.workflowPlan;
   if (!payload || !(payload.session_id || payload.sessionId)) return null;
   const { runtime, hooksRoot } = loadRuntime();
   const context = runtime.loadWorkflow(payload);
+  const hasRetainedWorkflow = Boolean(context.workflow && runtime.OPEN_STATES.has(context.workflow.state));
+  const activePlan = hasRetainedWorkflow ? context.workflow.workflowPlan : plan;
+  if (needsStepTypeRegistry(activePlan)) {
+    try { require(path.join(hooksRoot, 'lib/workflow-obligations')).loadStepTypeRegistry(); }
+    catch (error) {
+      if (hasRetainedWorkflow) return { ...context, hooksRoot, retained: true, registryError: error };
+      throw error;
+    }
+  }
   const { writeCurrentSession } = require(path.join(hooksRoot, 'lib/harness-state'));
   writeCurrentSession(context.root, context.sessionId);
   if (isHostNotificationPrompt(prompt)) {
@@ -121,8 +146,8 @@ function activeExecutionFor(persisted, plan) {
     const obligations = require(path.join(persisted.hooksRoot, 'lib/workflow-obligations'));
     const loaded = obligations.loadObligationSet(persisted, plan);
     return { activeStep: loaded.set ? obligations.activeStepSnapshot(loaded.set) : null };
-  } catch (_) {
-    return null;
+  } catch (error) {
+    return { error: error && error.message ? error.message : String(error) };
   }
 }
 
@@ -163,10 +188,15 @@ function run(raw) {
   if (persisted?.retained && persisted.workflow) {
     if (persisted.hostNotification) console.log('\n=> Host notification: routing unchanged; keeping the active execution contract.');
     else console.log('\n=> Retaining unresolved workflow; showing its compact active contract.');
-    const activeExecution = activeExecutionFor(persisted, plan) || {};
+    const activeExecution = persisted.registryError
+      ? { error: persisted.registryError.message || String(persisted.registryError) }
+      : activeExecutionFor(persisted, plan) || {};
     const activeStep = activeExecution.activeStep || null;
     const activeStages = activeExecution.activeStages || [];
     core.printRetainedWorkflow(plan, persisted.workflow, activeStep, activeStages);
+    if (activeExecution.error) {
+      console.log('   - [Workflow Reminder] Active-step context unavailable: ' + activeExecution.error);
+    }
     if (activeStep) {
       const controller = path.join(persisted.hooksRoot, 'workflow-disposition.js');
       console.log('   - Resolve only bindings for this active step, then pass this step with evidence.');
@@ -205,8 +235,10 @@ function run(raw) {
     if (plan.strategySelection === 'selected' && ['tier2', 'tier3'].includes(plan.tier)) {
       console.log('   - Planning contract: ' + path.join(persisted.sessionDir, 'workflow-obligations.json'));
       console.log('   - Requirements first: decompose intent into requirement fragments, then confirm the smallest sufficient workflow.');
-      console.log('   - Record ordered step types (review, behavior-change, verification, commit) and their bindings before execution.');
-      console.log('   - Record plan: node "' + controller + '" plan --session-id "' + persisted.sessionId + '" --requirements-json "[{\\"id\\":\\"req-1\\",\\"stepType\\":\\"behavior-change\\",\\"summary\\":\\"...\\",\\"acceptance\\":\\"...\\"},{\\"id\\":\\"req-verify\\",\\"stepType\\":\\"verification\\",\\"summary\\":\\"...\\",\\"acceptance\\":\\"...\\"}]" --strategy "' + plan.strategy + '" --evidence "<why this workflow fits>"');
+      const stepTypeIds = stepTypeIdsFor(persisted.hooksRoot);
+      console.log('   - Record ordered step types' + (stepTypeIds ? ' (' + stepTypeIds.join(', ') + ')' : '') + ' and their bindings before execution.');
+      console.log('   - Replace <step-type-id> with a registered type you choose explicitly; mixed docs+code work uses separate doc-change and behavior-change steps; keep the verification step.');
+      console.log('   - Record plan: node "' + controller + '" plan --session-id "' + persisted.sessionId + '" --requirements-json "[{\\"id\\":\\"req-1\\",\\"stepType\\":\\"<step-type-id>\\",\\"summary\\":\\"...\\",\\"acceptance\\":\\"...\\"},{\\"id\\":\\"req-verify\\",\\"stepType\\":\\"verification\\",\\"summary\\":\\"...\\",\\"acceptance\\":\\"...\\"}]" --strategy "' + plan.strategy + '" --evidence "<why this workflow fits>"');
     }
     console.log('   - Enter selected workflow after planning: node "' + controller + '" start --session-id "' + persisted.sessionId + '"');
     console.log('   - Escape one declared stage: node "' + controller + '" escape --session-id "' + persisted.sessionId + '" --stage-id "<id>" --reason-code workflow-uncovered-scope --scope "<uncovered scope>" --evidence "<evidence>"');

package/hooks/scripts/codex-user-prompt.js

@@ -24,8 +24,11 @@ function finish() {
   clearTimeout(timer);
   if (!ROUTER) process.exit(0);
   const result = spawnSync(process.execPath, [ROUTER], { input, encoding: 'utf8', env: process.env, timeout: 25000 });
-  if (result.stderr) process.stderr.write(result.stderr);
-  const context = String(result.stdout || '').trim();
+  const stderr = String(result.stderr || '');
+  if (stderr) process.stderr.write(stderr);
+  const registryDiagnostics = stderr.split(/\r?\n/)
+    .filter(line => line.includes('cannot load step-type registry') && /(repair|restore|plugin:sync)/i.test(line));
+  const context = [String(result.stdout || '').trim(), ...registryDiagnostics].filter(Boolean).join('\n').trim();
   if (context) {
     process.stdout.write(JSON.stringify({ hookSpecificOutput: { hookEventName: 'UserPromptSubmit', additionalContext: context } }));
   }

package/hooks/scripts/lib/step-types.json

@@ -0,0 +1,37 @@
+[
+  {
+    "id": "behavior-change",
+    "requiredBindings": ["tdd"],
+    "optionalBindings": [],
+    "forbiddenBindings": [],
+    "evidenceHint": "Evidence should show the requested behavior changed."
+  },
+  {
+    "id": "commit",
+    "requiredBindings": ["git-commit"],
+    "optionalBindings": [],
+    "forbiddenBindings": [],
+    "evidenceHint": "Evidence should identify the authorized commit."
+  },
+  {
+    "id": "doc-change",
+    "requiredBindings": [],
+    "optionalBindings": [],
+    "forbiddenBindings": [],
+    "evidenceHint": "Evidence should show the requested document update."
+  },
+  {
+    "id": "review",
+    "requiredBindings": [],
+    "optionalBindings": [],
+    "forbiddenBindings": ["tdd"],
+    "evidenceHint": "Evidence should identify the reviewed scope and findings."
+  },
+  {
+    "id": "verification",
+    "requiredBindings": ["verification-loop"],
+    "optionalBindings": [],
+    "forbiddenBindings": [],
+    "evidenceHint": "Evidence should record objective checks appropriate to the change."
+  }
+]