harness-everything 0.30.10 → 0.31.0

package/benchmarks/results/pr-303-review-2026-10-13/verification/verify-gate-final.json

@@ -0,0 +1,46 @@
+{
+  "status": "UNCHECKED_DISCOVERED",
+  "reason": "1 verification candidate(s) detected but not executed",
+  "repoRoot": "<workspace>",
+  "roots": [
+    {
+      "path": "<workspace>",
+      "status": "UNCHECKED_DISCOVERED",
+      "reason": "1 verification candidate(s) detected but not executed",
+      "checks": [
+        {
+          "id": "package-test",
+          "run": "npm run test",
+          "cwd": "<workspace>",
+          "source": "package-auto",
+          "exitCode": 0,
+          "durationMs": 245096
+        }
+      ],
+      "candidates": [
+        {
+          "source": "git-hook",
+          "run": "git commit (pre-commit hook configured)",
+          "cwd": "<workspace>"
+        }
+      ]
+    }
+  ],
+  "checks": [
+    {
+      "id": "package-test",
+      "run": "npm run test",
+      "cwd": "<workspace>",
+      "source": "package-auto",
+      "exitCode": 0,
+      "durationMs": 245096
+    }
+  ],
+  "candidates": [
+    {
+      "source": "git-hook",
+      "run": "git commit (pre-commit hook configured)",
+      "cwd": "<workspace>"
+    }
+  ]
+}

package/bin/cli.js

@@ -103,7 +103,7 @@ Commands:
                      error instead of silently doing nothing.
   self-regression    Run syntax and routing checks before committing changes (alias: test)
   next "<prompt>"    Print the Harness Kernel routing recommendation for a prompt:
-                     tier/rationale + mandatory invariants + advisory skill suggestions.
+                     tier/rationale + mandatory invariants + normalized knowledge signals.
                      Hookless platforms can call this explicitly at the start of software
                      work; hosts with UserPromptSubmit hooks receive it automatically.
   verify-install     Compare installed Harness manifests and skill trees with

package/ci/invariant-routing.test.js

@@ -11,13 +11,15 @@ check(tier2.status===0,'kernel router exits successfully');
 check(/RECOMMENDED TIER:\s*Tier 2/i.test(tier2.stdout),'classifier result is preserved');
 check(tier2.stdout.includes('"strategy":"iterative-single"'),'Tier 2 selects iterative-single workflow');
 check(tier2.stdout.includes('loop-awareness:'),'iterative work exposes loop-awareness instead of a hard budget');
-check(tier2.stdout.includes('WORKFLOW SKILLS (APPLICABILITY MUST BE RESOLVED)'),'skill applicability is explicitly mandatory');
+check(tier2.stdout.includes('ACTIVE-STEP KNOWLEDGE BINDINGS (MUST)'),'active-step binding resolution is explicitly mandatory');
 check(tier2.stdout.includes('ORCHESTRATION POLICY: Selected-topology required obligations and applicable skill core contracts are semantic MUSTs'),'orchestration policy preserves semantic MUST obligations');
 check(tier2.stdout.includes('WORKFLOW SEMANTIC CONTRACT (NON-BLOCKING OBSERVATION)'),'kernel separates semantic contract from non-blocking observation');
 check(tier2.stdout.includes('Tier 3 / Fable broad mutation MUST resolve isolation'),'worktree isolation disposition is a semantic MUST');
 check(!tier2.stdout.includes('SELECTED WORKFLOW IS GUIDANCE'),'old planning-guidance label is absent');
 check(!tier2.stdout.includes('unavailable isolation means BLOCKED'),'old worktree hard-block wording is absent');
-check(tier2.stdout.includes('evaluate-suggestions-before-skip'),'skill suggestions still require evaluation before omission');
+check(tier2.stdout.includes('future-step bindings remain undisclosed'),'future step knowledge stays undisclosed');
+check(tier2.stdout.includes('unknown/unavailable binding stays visible and unresolved'),'required binding gaps remain visible without adding a lock');
+check(!tier2.stdout.includes('evaluate-suggestions-before-skip'),'global read-every-suggestion invariant is removed');
 check(tier2.stdout.includes('visible-status-updates'),'workflow plan carries mandatory user-visible status invariant');
 check(tier2.stdout.includes('USER-VISIBLE HARNESS STATUS CONTRACT (MUST)'),'kernel emits the mandatory unified status contract');
 for(const field of ['### 🚦 Harness Status','- **Current:**','- **Read / Evidence:**','- **Next:**','- **Risk / Blocked:**']){
@@ -31,7 +33,8 @@ check(tier2.stdout.includes('semantic communication MUST, not a hard execution l
 const tier3=spawnSync(process.execPath,[kernel,'audit the entire repository architecture and coordinate multiple modules'],{cwd:ROOT,encoding:'utf8'});
 check(tier3.status===0,'Tier 3 routing exits successfully');
 check(/RECOMMENDED TIER:\s*Tier 3/i.test(tier3.stdout),'macro task remains Tier 3');
-check(tier3.stdout.includes('using-git-worktrees'),'Tier 3 still routes the worktree skill');
+check(tier3.stdout.includes('isolated-worktree-before-mutation'),'Tier 3 keeps the worktree isolation invariant');
+check(!tier3.stdout.includes('using-git-worktrees/SKILL.md'),'Tier 3 does not push a global worktree skill path');
 check(tier3.stdout.includes('Tier 3 / Fable broad mutation MUST resolve isolation'),'Tier 3 requires an isolation disposition without a hard lock');
 
 const hs=read('harness-everything/SKILL.md');
@@ -60,7 +63,7 @@ const philosophy=read('docs/philosophy.md');
 check(/Contract Strength: MUST \/ SHOULD \/ MAY/i.test(philosophy),'philosophy defines canonical MUST/SHOULD/MAY strength');
 for(const phrase of [
   'Route before software/project execution',
-  'Read/evaluate every suggested skill before omission',
+  'Resolve active required skill/reference bindings before their step',
   'Resolve selected-topology invariants/stages/checks/synthesis/verification',
   'Discover relevant environment/host facts',
   'Resolve Tier-3/Fable isolation before broad mutation',

package/ci/mechanism-2ag-router-worktree-contract.test.js

@@ -16,7 +16,7 @@ const tier3 = router.buildRouterContract({
 
 assert.strictEqual(tier3.strategy, 'fable-staged');
 assert.ok(tier3.requiredInvariants.includes('isolated-worktree-before-mutation'), 'Tier 3 plan must carry mutation isolation invariant');
-assert.ok(tier3.suggestedSkills.includes('using-git-worktrees'), 'Tier 3 plan must surface the worktree workflow');
+assert.strictEqual(tier3.suggestedSkills.length, 0, 'Tier 3 must not push a global worktree skill list');
 assert.strictEqual(tier3.workspace.required, false, 'Git worktree isolation must remain distinct from durable multi-agent workspace state');
 assert.strictEqual(tier3.mutationIsolation.onUnavailable, 'degraded', 'unavailable isolation records an explicit degraded fallback instead of a cognitive hard block');
 
@@ -29,7 +29,7 @@ const tier2 = router.buildRouterContract({
 
 assert.strictEqual(tier2.strategy, 'iterative-single');
 assert.ok(!tier2.requiredInvariants.includes('isolated-worktree-before-mutation'), 'Tier 2 must not be globally forced into major-workflow isolation');
-assert.ok(!tier2.suggestedSkills.includes('using-git-worktrees'), 'Tier 2 keeps worktree use task-dependent');
+assert.strictEqual(tier2.suggestedSkills.length, 0, 'Tier 2 also has no topology-wide skill suggestions');
 
 const explicitFable = router.buildWorkflowPlan({
   routingStatus: 'ok',

package/ci/mechanism-2ai-workspace-fingerprint-batch.test.js

@@ -189,7 +189,8 @@ try {
   });
   check(routed.status === 0, '#169 large-workspace Tier-2 fixture routes normally');
   const requirements = JSON.stringify([
-    { id: 'req-fingerprint', summary: 'Exercise large-workspace shell admission', acceptance: 'the shell call remains available above the fingerprint observation cap' },
+    { id: 'req-fingerprint', stepType: 'behavior-change', summary: 'Exercise large-workspace shell admission', acceptance: 'the shell call remains available above the fingerprint observation cap' },
+    { id: 'req-verify', stepType: 'verification', summary: 'Verify shell admission', acceptance: 'objective test evidence is recorded' },
   ]);
   const planned = node('hooks/scripts/workflow-disposition.js', undefined, [
     'plan', '--session-id', sessionId,

package/ci/mechanism-2an-workflow-obligations.test.js

@@ -32,6 +32,9 @@ function run(script, args = [], input = null) {
   });
 }
 function readJson(file) { return JSON.parse(fs.readFileSync(file, 'utf8')); }
+function responseOf(result) {
+  try { return JSON.parse(result.stdout || ''); } catch (_) { return null; }
+}
 
 console.log('=== Issue #85 requirements-first workflow contract ===');
 
@@ -72,9 +75,16 @@ check((workflow.unresolved || []).includes('decompose:pending'), 'decomposition
 check((workflow.unresolved || []).includes('compose:pending'), 'workflow-composition gap is visible');
 
 const requirements = JSON.stringify([
-  { id: 'req-fix', summary: 'Correct the checkout failure', acceptance: 'the failing scenario succeeds', suggestedSkills: ['tdd'] },
-  { id: 'req-regression', summary: 'Protect the behavior with a regression test', acceptance: 'the test fails before the fix and passes after it', suggestedSkills: ['tdd', 'verification-loop'] },
+  { id: 'req-fix', stepType: 'behavior-change', summary: 'Correct the checkout failure', acceptance: 'the failing scenario succeeds' },
+  { id: 'req-verify', stepType: 'verification', summary: 'Verify the checkout change', acceptance: 'objective check evidence is recorded' },
+]);
+const untypedRequirements = JSON.stringify([
+  { id: 'req-untyped', summary: 'Correct the checkout failure', acceptance: 'the failing scenario succeeds' },
 ]);
+check(run(controller, [
+  'plan', '--session-id', sessionId, '--requirements-json', untypedRequirements,
+  '--strategy', 'iterative-single', '--evidence', 'legacy untyped planning fixture',
+]).status !== 0, 'new single-agent plans cannot bypass active step typing');
 const planned = run(controller, [
   'plan', '--session-id', sessionId,
   '--requirements-json', requirements,
@@ -83,7 +93,7 @@ const planned = run(controller, [
 ]);
 check(planned.status === 0, 'requirements and workflow selection are recorded before execution');
 obligations = readJson(obligationFile);
-check(obligations.requirements.map(item => item.id).join(',') === 'req-fix,req-regression', 'requirement fragments are machine-readable');
+check(obligations.requirements.map(item => item.id).join(',') === 'req-fix,req-verify', 'requirement fragments are machine-readable');
 check(obligations.workflowSelection.disposition === 'confirmed', 'workflow choice is explicitly confirmed after decomposition');
 check(obligations.obligations.find(item => item.id === 'decompose').status === 'pass', 'decompose obligation resolves from requirement fragments');
 check(obligations.obligations.find(item => item.id === 'compose').status === 'pass', 'compose obligation resolves from workflow-selection evidence');
@@ -111,6 +121,14 @@ check((workflow.unresolved || []).includes('verify:blocked'), 'blocked verificat
 
 check(run(controller, ['obligation', '--session-id', sessionId, '--obligation-id', 'verify', '--disposition', 'pass', '--evidence', 'npm test and focused regression passed']).status === 0,
   'verification can later resolve to pass with evidence');
+check(run(controller, ['binding', '--session-id', sessionId, '--step-id', 'req-fix', '--binding-id', 'tdd', '--disposition', 'loaded', '--evidence', 'read and followed the TDD core contract before behavior changes']).status === 0,
+  'behavior-change binding resolves before its active step passes');
+check(run(controller, ['step', '--session-id', sessionId, '--step-id', 'req-fix', '--disposition', 'pass', '--evidence', 'behavior fix and regression case are complete']).status === 0,
+  'behavior-change step advances after TDD binding resolution');
+check(run(controller, ['binding', '--session-id', sessionId, '--step-id', 'req-verify', '--binding-id', 'verification-loop', '--disposition', 'loaded', '--evidence', 'read the verification contract for this step']).status === 0,
+  'verification skill resolves only when the verification step becomes active');
+check(run(controller, ['step', '--session-id', sessionId, '--step-id', 'req-verify', '--disposition', 'pass', '--evidence', 'objective checks completed and recorded']).status === 0,
+  'verification step passes with objective evidence');
 check(run(statePersist, [], {
   session_id: sessionId, cwd: ROOT, hook_event_name: 'PostToolUse',
   tool_name: 'Bash', tool_input: { command: 'npm test' },
@@ -122,10 +140,339 @@ check(resolvedStop.status === 0, 'resolved workflow Stop remains fail-open');
 check(workflow.state === 'satisfied', 'planning + execution + verification allow satisfied');
 check((workflow.unresolved || []).length === 0, 'satisfied workflow has no unresolved obligations');
 
+const stepSession = 'issue297-active-step-bindings';
+const stepPayload = { session_id: stepSession, cwd: ROOT, prompt: 'Fix this checkout bug and add a regression test.' };
+check(run(kernel, [], stepPayload).status === 0, 'Tier 2 route persists for active-step binding coverage');
+const stepDir = getSessionDir(ROOT, stepSession, stepPayload);
+const stepWorkflowFile = path.join(stepDir, 'workflow-run.json');
+const stepObligationFile = path.join(stepDir, 'workflow-obligations.json');
+
+console.log('\n=== Binding declaration validation ===');
+let invalidBindingCase = 0;
+for (const field of ['requiredBindings', 'optionalBindings']) {
+  for (const [valueName, value] of [
+    ['null', null],
+    ['object', { id: 'silently-dropped' }],
+    ['string', 'silently-dropped'],
+    ['boolean', false],
+    ['number', 0],
+  ]) {
+    for (const typed of [true, false]) {
+      invalidBindingCase++;
+      const sessionId = `issue303-invalid-binding-${invalidBindingCase}`;
+      const payload = { session_id: sessionId, cwd: ROOT, prompt: 'Fix this checkout bug and add a regression test.' };
+      const routed = run(kernel, [], payload);
+      check(routed.status === 0, `invalid ${field} ${valueName} fixture route persists (${typed ? 'typed' : 'untyped'})`);
+      const dir = getSessionDir(ROOT, sessionId, payload);
+      const workflowFile = path.join(dir, 'workflow-run.json');
+      const obligationFile = path.join(dir, 'workflow-obligations.json');
+      const workflowBefore = readJson(workflowFile);
+      const obligationsBefore = readJson(obligationFile);
+      const malformed = { id: 'req-review', summary: 'Review a change', acceptance: 'the change is reviewed', [field]: value };
+      const requirements = typed
+        ? [
+          { ...malformed, stepType: 'review' },
+          { id: 'req-verify', stepType: 'verification', summary: 'Verify the change', acceptance: 'objective evidence is recorded' },
+        ]
+        : [malformed];
+      const result = run(controller, [
+        'plan', '--session-id', sessionId, '--requirements-json', JSON.stringify(requirements),
+        '--strategy', 'iterative-single', '--evidence', 'validate binding declaration types',
+      ]);
+      check(result.status === 2, `plan exits 2 for ${field} ${valueName} (${typed ? 'typed' : 'untyped'} requirement)`);
+      check(result.stdout === '', `rejected ${field} ${valueName} plan writes no stdout (${typed ? 'typed' : 'untyped'})`);
+      check(new RegExp(field).test(result.stderr || ''), `rejection identifies ${field} for ${valueName} (${typed ? 'typed' : 'untyped'} requirement)`);
+      check(JSON.stringify(readJson(workflowFile)) === JSON.stringify(workflowBefore),
+        `rejected ${field} ${valueName} plan leaves workflow state unchanged (${typed ? 'typed' : 'untyped'})`);
+      check(JSON.stringify(readJson(obligationFile)) === JSON.stringify(obligationsBefore),
+        `rejected ${field} ${valueName} plan leaves obligation state unchanged (${typed ? 'typed' : 'untyped'})`);
+    }
+  }
+}
+
+const emptyBindingsSession = 'issue303-empty-binding-arrays';
+const emptyBindingsPayload = { session_id: emptyBindingsSession, cwd: ROOT, prompt: 'Fix this checkout bug and add a regression test.' };
+check(run(kernel, [], emptyBindingsPayload).status === 0, 'empty-array binding fixture route persists');
+const emptyBindingsDir = getSessionDir(ROOT, emptyBindingsSession, emptyBindingsPayload);
+const emptyBindingsRequirements = JSON.stringify([
+  { id: 'req-review-omitted', stepType: 'review', summary: 'Review a change', acceptance: 'the change is reviewed' },
+  { id: 'req-review-empty', stepType: 'review', summary: 'Review another change', acceptance: 'the second change is reviewed', requiredBindings: [], optionalBindings: [] },
+  { id: 'req-verify', stepType: 'verification', summary: 'Verify both reviews', acceptance: 'objective evidence is recorded' },
+]);
+const emptyBindingsPlan = run(controller, [
+  'plan', '--session-id', emptyBindingsSession, '--requirements-json', emptyBindingsRequirements,
+  '--strategy', 'iterative-single', '--evidence', 'omitted and empty binding arrays are supported',
+]);
+check(emptyBindingsPlan.status === 0, 'plan accepts omitted and explicit empty binding arrays');
+const emptyBindingsState = readJson(path.join(emptyBindingsDir, 'workflow-obligations.json'));
+check(emptyBindingsState.requirements[0].requiredBindings.length === 0 && emptyBindingsState.requirements[0].optionalBindings.length === 0,
+  'omitted binding arrays remain empty after normalization');
+check(emptyBindingsState.requirements[1].requiredBindings.length === 0 && emptyBindingsState.requirements[1].optionalBindings.length === 0,
+  'explicit empty binding arrays remain empty after normalization');
+
+const stepRequirements = JSON.stringify([
+  { id: 'req-review', stepType: 'review', summary: 'Inspect the existing checkout change', acceptance: 'the relevant diff has been reviewed', optionalBindings: ['security-review', 'review-guidance'] },
+  { id: 'req-change', stepType: 'behavior-change', summary: 'Correct the checkout behavior', acceptance: 'the reported behavior is corrected' },
+  { id: 'req-verify', stepType: 'verification', summary: 'Verify the checkout change', acceptance: 'objective verification evidence is recorded' },
+  { id: 'req-commit', stepType: 'commit', summary: 'Commit the requested change', acceptance: 'the authorized commit is recorded' },
+]);
+check(run(controller, [
+  'plan', '--session-id', stepSession,
+  '--requirements-json', stepRequirements,
+  '--strategy', 'iterative-single',
+  '--evidence', 'the request contains review, behavior-change, verification, and commit steps',
+]).status === 0, 'normalized ordered steps are recorded in the existing requirements contract');
+let stepState = readJson(stepObligationFile);
+check(stepState.requirements.map(item => item.stepType || 'legacy').join(',') === 'review,behavior-change,verification,commit',
+  'typed steps preserve request order');
+check((stepState.requirements[1].requiredBindings || []).map(item => item.id).join(',') === 'tdd',
+  'behavior-change step materializes required TDD binding');
+check((stepState.requirements[2].requiredBindings || []).map(item => item.id).join(',') === 'verification-loop',
+  'verification step owns its verification-loop binding');
+check((stepState.requirements[3].requiredBindings || []).map(item => item.id).join(',') === 'git-commit',
+  'commit step materializes required git-commit binding');
+const stepsWithoutVerification = JSON.stringify([
+  { id: 'req-review-only', stepType: 'review', summary: 'Review the diff', acceptance: 'the diff is reviewed' },
+]);
+check(run(controller, [
+  'plan', '--session-id', stepSession, '--requirements-json', stepsWithoutVerification,
+  '--strategy', 'iterative-single', '--evidence', 'invalid fixture omits mandatory verification',
+]).status !== 0, 'typed-step plan cannot omit the mandatory verification step');
+
+const stepStart = run(controller, ['start', '--session-id', stepSession]);
+check(stepStart.status === 0, 'start accepts a confirmed typed-step workflow');
+let stepResponse = responseOf(stepStart) || {};
+check(stepResponse.activeStep?.id === 'req-review' && stepResponse.activeStep?.stepType === 'review',
+  'start returns the first ordered step as active');
+check(stepResponse.activeStepCommands?.resolveBinding.includes('--step-id "req-review"') &&
+  stepResponse.activeStepCommands?.passStep.includes('--step-id "req-review"'),
+  'start returns concrete commands for resolving the active binding and passing the step');
+check(stepResponse.activeStep?.requiredBindings?.length === 0 &&
+  stepResponse.activeStep?.optionalBindings?.map(item => item.id).join(',') === 'security-review,review-guidance',
+  'review starts without TDD and surfaces only its optional binding');
+check(stepResponse.activeStep?.optionalBindings?.[0]?.path === 'security-review/SKILL.md',
+  'active optional binding includes its load path');
+check(!JSON.stringify(stepResponse).includes('tdd') && !JSON.stringify(stepResponse).includes('git-commit'),
+  'start does not disclose future-step bindings');
+check(run(controller, [
+  'binding', '--session-id', stepSession, '--step-id', 'req-commit', '--binding-id', 'git-commit',
+  '--disposition', 'loaded', '--evidence', 'premature future-step load attempt',
+]).status !== 0, 'future-step binding cannot be resolved before its step becomes active');
+stepState = readJson(stepObligationFile);
+check(stepState.activeStepId === 'req-review', 'active step is persisted in workflow-obligations state');
+check(stepState.obligations.find(item => item.id === 'execute').suggestedSkills.length === 0 &&
+  stepState.obligations.find(item => item.id === 'verify').suggestedSkills.length === 0,
+  'typed-step workflows do not reintroduce global suggested-skill pushes');
+check(run(controller, [
+  'step', '--session-id', stepSession, '--step-id', 'req-review', '--disposition', 'pass',
+  '--evidence', 'review finished without resolving optional bindings',
+]).status !== 0, 'active step cannot pass before surfaced optional bindings are resolved');
+
+check(run(controller, [
+  'binding', '--session-id', stepSession, '--step-id', 'req-review', '--binding-id', 'security-review',
+  '--disposition', 'loaded', '--evidence', 'loaded the security review checklist for this step',
+]).status === 0, 'active optional binding can be loaded with evidence');
+check(run(controller, [
+  'binding', '--session-id', stepSession, '--step-id', 'req-review', '--binding-id', 'review-guidance',
+  '--disposition', 'not-needed',
+]).status !== 0, 'optional binding cannot be marked not-needed without evidence');
+check(run(controller, [
+  'binding', '--session-id', stepSession, '--step-id', 'req-review', '--binding-id', 'review-guidance',
+  '--disposition', 'not-needed', '--evidence', 'the bounded diff review does not need the broader triage guide',
+]).status === 0, 'active optional binding can be marked not-needed with evidence');
+const reviewAdvance = run(controller, [
+  'step', '--session-id', stepSession, '--step-id', 'req-review', '--disposition', 'pass',
+  '--evidence', 'the relevant diff and acceptance criteria were reviewed',
+]);
+const reviewResponse = responseOf(reviewAdvance) || {};
+check(reviewAdvance.status === 0, 'review step can pass after its surfaced optional binding is resolved');
+stepResponse = reviewResponse;
+check(stepResponse.activeStep?.id === 'req-change' &&
+  stepResponse.activeStep?.requiredBindings?.map(item => item.id).join(',') === 'tdd',
+  'review advance returns only the behavior-change step and its required TDD binding');
+check(stepResponse.activeStep?.requiredBindings?.[0]?.path === 'tdd/SKILL.md' &&
+  !JSON.stringify(stepResponse).includes('verification-loop') && !JSON.stringify(stepResponse).includes('git-commit'),
+  'behavior-change output includes its TDD path but keeps later bindings hidden');
+check(run(controller, [
+  'step', '--session-id', stepSession, '--step-id', 'req-change', '--disposition', 'pass',
+  '--evidence', 'behavior changed',
+]).status !== 0, 'behavior-change cannot pass before required TDD binding is resolved');
+check(run(controller, [
+  'binding', '--session-id', stepSession, '--step-id', 'req-change', '--binding-id', 'tdd',
+  '--disposition', 'loaded', '--evidence', 'read and followed the TDD core contract before changing behavior',
+]).status === 0, 'required TDD binding resolves with load evidence');
+const changeAdvance = run(controller, [
+  'step', '--session-id', stepSession, '--step-id', 'req-change', '--disposition', 'pass',
+  '--evidence', 'the checkout behavior and regression case are implemented',
+]);
+const changeResponse = responseOf(changeAdvance) || {};
+check(changeAdvance.status === 0 && changeResponse.activeStep?.id === 'req-verify',
+  'resolved behavior-change advances to the mandatory verification step');
+stepResponse = changeResponse;
+check(stepResponse.activeStep?.requiredBindings?.map(item => item.id).join(',') === 'verification-loop' &&
+  !JSON.stringify(stepResponse).includes('git-commit'),
+  'verification binding is disclosed only when verification becomes active');
+check(run(controller, [
+  'binding', '--session-id', stepSession, '--step-id', 'req-verify', '--binding-id', 'verification-loop',
+  '--disposition', 'loaded', '--evidence', 'read the verification-loop contract for this verification step',
+]).status === 0, 'verification binding resolves at its own step');
+const verifyAdvance = run(controller, [
+  'step', '--session-id', stepSession, '--step-id', 'req-verify', '--disposition', 'pass',
+  '--evidence', 'objective checks completed and their result is recorded',
+]);
+const verifyResponse = responseOf(verifyAdvance) || {};
+check(verifyAdvance.status === 0 && verifyResponse.activeStep?.id === 'req-commit',
+  'verification step advances to commit only after its binding resolves');
+stepResponse = verifyResponse;
+check(stepResponse.activeStep?.requiredBindings?.map(item => item.id).join(',') === 'git-commit' &&
+  !JSON.stringify(stepResponse).includes('tdd') && !JSON.stringify(stepResponse).includes('verification-loop'),
+  'commit binding is disclosed only when the commit step becomes active');
+check(run(controller, [
+  'binding', '--session-id', stepSession, '--step-id', 'req-commit', '--binding-id', 'git-commit',
+  '--disposition', 'loaded', '--evidence', 'read the commit authorization and staged-diff contract',
+]).status === 0, 'required git-commit binding resolves at the commit step');
+const commitAdvance = run(controller, [
+  'step', '--session-id', stepSession, '--step-id', 'req-commit', '--disposition', 'pass',
+  '--evidence', 'the explicitly requested commit was created and checked',
+]);
+const commitResponse = responseOf(commitAdvance) || {};
+check(commitAdvance.status === 0 && commitResponse.activeStep === null,
+  'advancing the last step leaves no active-step bindings');
+stepState = readJson(stepObligationFile);
+check(stepState.obligations.find(item => item.id === 'execute').status === 'pass' &&
+  stepState.obligations.find(item => item.id === 'verify').status === 'pass',
+  'completed typed steps resolve their aggregate execute and verify obligations with linked evidence');
+const typedResolvedStop = run(stopGate, [], { session_id: stepSession, cwd: ROOT, hook_event_name: 'Stop' });
+const typedWorkflow = readJson(stepWorkflowFile);
+check(typedResolvedStop.status === 0 && typedWorkflow.state === 'satisfied',
+  'all typed steps can satisfy the workflow without separate aggregate dispositions');
+check((typedWorkflow.unresolved || []).length === 0, 'satisfied typed-step workflow has no unresolved obligations');
+
+const verifyOnlySession = 'issue297-verification-only';
+const verifyOnlyPayload = { session_id: verifyOnlySession, cwd: ROOT, prompt: 'Fix this checkout bug and add a regression test.' };
+check(run(kernel, [], verifyOnlyPayload).status === 0, 'verification-only workflow route persists');
+const verifyOnlyObligationFile = path.join(getSessionDir(ROOT, verifyOnlySession, verifyOnlyPayload), 'workflow-obligations.json');
+const verifyOnlyRequirements = JSON.stringify([
+  { id: 'req-verify-only', stepType: 'verification', summary: 'Verify existing behavior', acceptance: 'objective checks pass' },
+]);
+check(run(controller, [
+  'plan', '--session-id', verifyOnlySession, '--requirements-json', verifyOnlyRequirements,
+  '--strategy', 'iterative-single', '--evidence', 'the request verifies existing behavior without implementation work',
+]).status === 0, 'verification-only typed plan is accepted');
+const verifyOnlyStart = run(controller, ['start', '--session-id', verifyOnlySession]);
+check(verifyOnlyStart.status === 0 && responseOf(verifyOnlyStart)?.activeStep?.id === 'req-verify-only',
+  'verification-only typed plan starts at its verification step');
+let verifyOnlyState = readJson(verifyOnlyObligationFile);
+check(verifyOnlyState.obligations.find(item => item.id === 'execute')?.status === 'pass' &&
+  verifyOnlyState.obligations.find(item => item.id === 'execute')?.evidence.includes('verification-only workflow'),
+  'empty typed execution group resolves as explicit verification-only evidence');
+check(run(controller, [
+  'binding', '--session-id', verifyOnlySession, '--step-id', 'req-verify-only', '--binding-id', 'verification-loop',
+  '--disposition', 'loaded', '--evidence', 'loaded and followed the verification binding for the active step',
+]).status === 0, 'verification-only step resolves its required binding');
+check(run(controller, [
+  'step', '--session-id', verifyOnlySession, '--step-id', 'req-verify-only', '--disposition', 'pass',
+  '--evidence', 'the existing behavior passed its objective verification checks',
+]).status === 0, 'verification-only step passes with objective evidence');
+const verifyOnlyStop = run(stopGate, [], { session_id: verifyOnlySession, cwd: ROOT, hook_event_name: 'Stop' });
+const verifyOnlyWorkflow = readJson(path.join(getSessionDir(ROOT, verifyOnlySession, verifyOnlyPayload), 'workflow-run.json'));
+verifyOnlyState = readJson(verifyOnlyObligationFile);
+check(verifyOnlyStop.status === 0 && verifyOnlyWorkflow.state === 'satisfied',
+  'verification-only workflow can satisfy without an execution step');
+check(verifyOnlyState.obligations.find(item => item.id === 'verify')?.status === 'pass',
+  'verification-only completion also resolves the aggregate verify obligation');
+
+const unknownSession = 'issue297-unknown-binding';
+const unknownPayload = { session_id: unknownSession, cwd: ROOT, prompt: 'Fix this checkout bug and add a regression test.' };
+check(run(kernel, [], unknownPayload).status === 0, 'route persists for unknown-required-binding coverage');
+const unknownDir = getSessionDir(ROOT, unknownSession, unknownPayload);
+const unknownRequirements = JSON.stringify([
+  { id: 'req-unknown-review', stepType: 'review', summary: 'Review the unfamiliar domain change', acceptance: 'the unfamiliar behavior is assessed', requiredBindings: ['unregistered-review-skill'] },
+  { id: 'req-unknown-verify', stepType: 'verification', summary: 'Verify the reviewed change', acceptance: 'verification evidence exists' },
+]);
+check(run(controller, [
+  'plan', '--session-id', unknownSession, '--requirements-json', unknownRequirements,
+  '--strategy', 'iterative-single', '--evidence', 'a review-only capability was requested explicitly',
+]).status === 0, 'unknown required binding is accepted into the auditable contract');
+const unknownStart = run(controller, ['start', '--session-id', unknownSession]);
+check(unknownStart.status === 0, 'start surfaces rather than silently discarding an unknown required binding');
+stepResponse = responseOf(unknownStart) || {};
+check(stepResponse.activeStep?.requiredBindings?.[0]?.id === 'unregistered-review-skill' &&
+  stepResponse.activeStep?.requiredBindings?.[0]?.path === null &&
+  stepResponse.activeStep?.requiredBindings?.[0]?.status === 'pending',
+  'unknown required binding remains visible as pending/unavailable');
+check(run(controller, [
+  'binding', '--session-id', unknownSession, '--step-id', 'req-unknown-review', '--binding-id', 'unregistered-review-skill',
+  '--disposition', 'loaded', '--evidence', 'attempted to load unknown skill',
+]).status !== 0, 'unknown required binding cannot be falsely marked loaded');
+check(run(controller, [
+  'step', '--session-id', unknownSession, '--step-id', 'req-unknown-review', '--disposition', 'pass',
+  '--evidence', 'review finished',
+]).status !== 0, 'step with unknown required binding cannot pass');
+const unknownMutationReminder = run(workflowGate, [], {
+  session_id: unknownSession, cwd: ROOT, hook_event_name: 'PreToolUse',
+  tool_name: 'Write', tool_input: { file_path: path.join(ROOT, 'tmp-unknown-binding.txt'), content: 'x' },
+});
+check(unknownMutationReminder.status === 0, 'unknown required binding does not hard-block ordinary tools');
+const unknownStop = run(stopGate, [], { session_id: unknownSession, cwd: ROOT, hook_event_name: 'Stop' });
+const unknownWorkflow = readJson(path.join(unknownDir, 'workflow-run.json'));
+check(unknownStop.status === 0 && unknownWorkflow.state === 'running',
+  'missing binding keeps Stop fail-open while workflow remains unresolved');
+check((unknownWorkflow.unresolved || []).some(item => item.includes('unregistered-review-skill')),
+  'Stop reports the unresolved unknown binding');
+
+const referenceSession = 'issue297-custom-reference-binding';
+const referencePayload = { session_id: referenceSession, cwd: ROOT, prompt: 'Fix this checkout bug and add a regression test.' };
+check(run(kernel, [], referencePayload).status === 0, 'custom-reference workflow route persists');
+const referenceRequirements = JSON.stringify([
+  { id: 'req-reference-review', stepType: 'review', summary: 'Review the domain-specific behavior', acceptance: 'the domain rule is checked', requiredBindings: [{ id: 'domain-reference', path: 'docs\\philosophy.md' }] },
+  { id: 'req-reference-verify', stepType: 'verification', summary: 'Verify the domain change', acceptance: 'objective check evidence exists' },
+]);
+check(run(controller, [
+  'plan', '--session-id', referenceSession, '--requirements-json', referenceRequirements,
+  '--strategy', 'iterative-single', '--evidence', 'the review step requires one explicit domain reference',
+]).status === 0, 'step contracts accept an explicit skill/reference path');
+const referenceStart = run(controller, ['start', '--session-id', referenceSession]);
+stepResponse = responseOf(referenceStart) || {};
+check(referenceStart.status === 0 && stepResponse.activeStep?.requiredBindings?.[0]?.path === 'docs/philosophy.md',
+  'custom reference path is normalized and disclosed only at its active step');
+check(run(controller, [
+  'binding', '--session-id', referenceSession, '--step-id', 'req-reference-review', '--binding-id', 'domain-reference',
+  '--disposition', 'loaded', '--evidence', 'read docs/philosophy.md before completing the review',
+]).status === 0, 'explicit reference binding can resolve with evidence');
+check(run(controller, [
+  'step', '--session-id', referenceSession, '--step-id', 'req-reference-review', '--disposition', 'pass',
+  '--evidence', 'the relevant domain rule was applied in the review',
+]).status === 0, 'active step can pass after its explicit reference binding is resolved');
+const unsafeReferenceRequirements = JSON.stringify([
+  { id: 'req-unsafe-reference', stepType: 'review', summary: 'Review a rule', acceptance: 'the rule is checked', requiredBindings: [{ id: 'unsafe-reference', path: '../private.md' }] },
+  { id: 'req-unsafe-verify', stepType: 'verification', summary: 'Verify the review', acceptance: 'objective check evidence exists' },
+]);
+const unsafeReferenceSession = 'issue297-unsafe-reference-binding';
+check(run(kernel, [], { session_id: unsafeReferenceSession, cwd: ROOT, prompt: 'Fix this checkout bug and add a regression test.' }).status === 0,
+  'unsafe-reference workflow route persists');
+check(run(controller, [
+  'plan', '--session-id', unsafeReferenceSession, '--requirements-json', unsafeReferenceRequirements,
+  '--strategy', 'iterative-single', '--evidence', 'unsafe traversal path should be rejected',
+]).status !== 0, 'step bindings reject paths that traverse outside repository scope');
+const driveReferenceSession = 'issue297-drive-reference-binding';
+check(run(kernel, [], { session_id: driveReferenceSession, cwd: ROOT, prompt: 'Fix this checkout bug and add a regression test.' }).status === 0,
+  'drive-reference workflow route persists');
+const driveReferenceRequirements = JSON.stringify([
+  { id: 'req-drive-reference', stepType: 'review', summary: 'Review a rule', acceptance: 'the rule is checked', requiredBindings: [{ id: 'drive-reference', path: 'C:outside.md' }] },
+  { id: 'req-drive-verify', stepType: 'verification', summary: 'Verify the review', acceptance: 'objective check evidence exists' },
+]);
+check(run(controller, [
+  'plan', '--session-id', driveReferenceSession, '--requirements-json', driveReferenceRequirements,
+  '--strategy', 'iterative-single', '--evidence', 'drive-relative path should be rejected',
+]).status !== 0, 'step bindings reject Windows drive-relative paths');
+
 const mismatchSession = 'issue85-replan';
 const mismatchPayload = { session_id: mismatchSession, cwd: ROOT, prompt: 'Fix this checkout bug and add a regression test.' };
 check(run(kernel, [], mismatchPayload).status === 0, 'second Tier 2 route persists for replan discriminator');
 const mismatchDir = getSessionDir(ROOT, mismatchSession, mismatchPayload);
+const initialSignals = readJson(path.join(mismatchDir, 'workflow-run.json')).workflowPlan.knowledgeSignals || [];
+check(initialSignals.includes('tdd-test'), 'initial route records normalized knowledge signals');
 const mismatchPlan = run(controller, [
   'plan', '--session-id', mismatchSession,
   '--requirements-json', requirements,
@@ -140,6 +487,8 @@ check(mismatchObligations.workflowSelection.requestedStrategy === 'fable-staged'
   mismatchObligations.workflowSelection.confirmedStrategy === 'fable-staged',
   'requested and router-confirmed post-decomposition strategy are preserved');
 check(mismatchWorkflow.pendingPlan?.strategy === 'fable-staged', 'recomposed plan becomes the pending execution contract');
+check(JSON.stringify(mismatchWorkflow.pendingPlan?.knowledgeSignals) === JSON.stringify(initialSignals),
+  'strategy recomposition preserves the original knowledge signals');
 const mismatchStop = run(stopGate, [], { session_id: mismatchSession, cwd: ROOT, hook_event_name: 'Stop' });
 const mismatchAfterStop = readJson(path.join(mismatchDir, 'workflow-run.json'));
 check(mismatchStop.status === 0 && mismatchAfterStop.state === 'pending' &&