harness-everything 0.30.10 → 0.31.0

package/ci/router-workflow-plan.test.js

@@ -15,6 +15,7 @@ const {
   FABLE_MAX_WORKERS,
   validateRouterContract,
 } = require(path.join(ROOT, 'harness-everything', 'scripts', 'router-contract.js'));
+const { splitProfileLookupClauses } = require(tierRouter);
 let failed = 0;
 
 function check(condition, message) {
@@ -83,9 +84,11 @@ if (validContract(iterative, 'iterative-single')) {
   check(plan.limits.maxWorkers === FABLE_MAX_WORKERS, 'workflow exposes a MAY worker planning value');
   check(plan.requiredInvariants.includes('objective-verification'), 'iterative-single carries objective verification invariant');
   check(plan.requiredInvariants.includes('loop-awareness'), 'iterative-single carries semantic loop-awareness obligation while numeric counts remain MAY');
-  check(plan.suggestedSkills.includes('tdd'), 'TDD remains applicability-conditional rather than a universal invariant');
+  check(plan.knowledgeSignals.includes('tdd-test'), 'test-related keywords become normalized step input signals');
+  check(plan.suggestedSkills.length === 0, 'selected topology no longer pushes a global skill list');
+  check(!plan.knowledgeSignals.some(signal => signal.includes('/') || signal.endsWith('.md')), 'knowledge signals do not directly select documents');
   check(plan.memory.write === 'none', 'ordinary iterative work cannot write durable memory');
-  check(!plan.requiredInvariants.includes('tdd'), 'suggested skill names remain separate from plan invariants until applicability is resolved');
+  check(!plan.requiredInvariants.includes('tdd'), 'binding ids remain step-local rather than workflow invariants');
 }
 
 const memoryPersist = runTier('Persist this lesson as memory after resolving the checkout regression.');
@@ -94,7 +97,7 @@ if (validContract(memoryPersist, 'self-evolve persistence')) {
   check(plan.strategy === 'direct-single', 'bounded explicit persistence request receives a selected workflow');
   check(plan.memory.write === 'persist-via-self-evolve', 'explicit persistence request authorizes only self-evolve durable write');
   check(plan.requiredInvariants.includes('memory-write-authorization'), 'durable memory route carries runtime authorization invariant');
-  check(plan.suggestedSkills.includes('self-evolve'), 'durable memory route suggests self-evolve explicitly');
+  check(plan.suggestedSkills.length === 0, 'memory authorization does not add a global self-evolve suggestion');
   check(memoryPersist.contract.taskShape.observedSignals.memoryPersistenceRequested === true, 'persistence intent is recorded in task shape');
 }
 
@@ -141,7 +144,8 @@ if (validContract(staged, 'fable-staged')) {
   check(plan.parallelism.allowed === false, 'dependent stages remain sequential');
   check(plan.verification.mode === 'cold-verifier', 'fable-staged requires cold verification');
   check(plan.requiredInvariants.includes('isolated-worktree-before-mutation'), 'fable-staged carries mandatory isolation disposition');
-  check(plan.suggestedSkills.includes('using-git-worktrees'), 'fable-staged surfaces worktree resolution skill');
+  check(plan.requiredInvariants.includes('isolated-worktree-before-mutation'), 'fable-staged keeps its worktree isolation invariant');
+  check(plan.suggestedSkills.length === 0, 'fable topology does not globally push worktree/fable skills');
 }
 
 const parallelPrompt = 'Audit the entire repository with independent read-only security, architecture, and documentation workstreams.';
@@ -218,6 +222,13 @@ if (validContract(explicitSonnect, 'explicit Fable sonnect alias')) {
 
 // #290: mentioning a profile in a bounded lookup must not launch orchestration.
 for (const prompt of [
+  'Could you please explain fable on sonnet? Return only JSON.',
+  'Please, explain fable on sonnet; return only JSON.',
+  'What is fable on opus? Return only JSON.',
+  'Explain what fable on sonnet means.Return only JSON.',
+  'Could you please explain fable on sonnet as a compact JSON record.',
+  '說明 fable on sonnet，不必啟動任何流程，請只輸出 JSON。',
+  '解釋 fable on opus，無須進入任何階段，請回傳 JSON。',
   "Explain what 'fable on sonnect' means; return only a small JSON selection record.",
   "Resolve fable on haiku into a profile JSON record; no orchestration or delegation.",
   "解釋 fable on opus 的意思，只回傳 JSON。",
@@ -242,13 +253,13 @@ for (const prompt of [
   const lookup = runTier(prompt);
   const repeat = runTier(prompt);
   if (validContract(lookup, 'bounded Fable lookup')) {
-    check(lookup.contract.classification.tier === 'tier1', 'lookup remains a bounded Tier 1 operation');
-    check(lookup.contract.workflowPlan.strategy === 'direct-single', 'lookup selects direct-single before loading references');
+    check(lookup.contract.classification.tier === 'tier1', `${prompt}: lookup remains a bounded Tier 1 operation`);
+    check(lookup.contract.workflowPlan.strategy === 'direct-single', `${prompt}: lookup selects direct-single before loading references`);
     check(lookup.contract.workflowPlan.parallelism.allowed === false, 'lookup does not delegate');
-    check(lookup.result.stdout.includes('references/profile-lookup.md'), 'lookup selects only compact reference');
-    check(!lookup.result.stdout.includes('RECOMMENDED KNOWLEDGE GUIDES'), 'lookup omits unrelated keyword guides');
-    check(!lookup.result.stdout.includes('with fable-mode/scripts/model-selector.js'), 'lookup does not send agent to selector implementation');
-    check(JSON.stringify(lookup.contract) === JSON.stringify(repeat.contract), 'lookup contract is deterministic');
+    check(lookup.result.stdout.includes('references/profile-lookup.md'), `${prompt}: lookup selects only compact reference`);
+    check(!lookup.result.stdout.includes('RECOMMENDED KNOWLEDGE GUIDES'), `${prompt}: lookup omits unrelated keyword guides`);
+    check(!lookup.result.stdout.includes('with fable-mode/scripts/model-selector.js'), `${prompt}: lookup does not send agent to selector implementation`);
+    check(JSON.stringify(lookup.contract) === JSON.stringify(repeat.contract), `${prompt}: lookup contract is deterministic`);
   }
 }
 for (const prompt of [
@@ -351,8 +362,16 @@ if (validContract(hookUnavailable, 'actionGate capability block')) {
 }
 
 const guideDedup = runTier('security audit login authentication');
-const securityGuideCount = (guideDedup.result.stdout.match(/security-review\/SKILL\.md/g) || []).length;
-check(securityGuideCount === 1, 'duplicate guide matches emit security-review/SKILL.md exactly once by path');
+check(guideDedup.contract.workflowPlan.knowledgeSignals.filter(signal => signal === 'security').length === 1,
+  'overlapping keywords deduplicate normalized security input signals');
+check(!guideDedup.result.stdout.includes('security-review/SKILL.md'), 'keyword matching does not print a document path');
+check(!guideDedup.result.stdout.includes('RECOMMENDED KNOWLEDGE GUIDES'), 'keyword matching no longer pushes guide lists');
+
+const dottedLookupClauses = splitProfileLookupClauses('Explain what fable on sonnet means in README.md version v1.2.Return only JSON.');
+check(dottedLookupClauses[0].includes('README.md') && dottedLookupClauses[0].includes('v1.2'),
+  'profile lookup clause splitting keeps filenames and dotted versions intact');
+check(dottedLookupClauses.length === 2 && dottedLookupClauses[1] === 'Return only JSON',
+  'profile lookup clause splitting recognizes a no-space output clause boundary');
 
 const repeatA = runTier('Fix this checkout bug and add a regression test.');
 const repeatB = runTier('Fix this checkout bug and add a regression test.');
@@ -395,7 +414,7 @@ const kernelNotificationPersistFailure = spawnSync(process.execPath, [kernelRout
   env: { ...process.env, HARNESS_STATE_HOME: notificationStateFile, HARNESS_WORKSPACE_ROOT: ROOT },
 });
 check(kernelNotificationPersistFailure.status === 0, 'host notification persistence failure stays fail-open');
-check(kernelNotificationPersistFailure.stdout.includes('Host notification — no active execution contract; ignored for routing.'), 'host notification remains a routing no-op when state persistence fails');
+check(kernelNotificationPersistFailure.stdout.includes('Host notification: no active execution contract; ignored for routing.'), 'host notification remains a routing no-op when state persistence fails');
 check(kernelNotificationPersistFailure.stderr.includes('routing state was not persisted'), 'host notification persistence failure remains visible as a reminder');
 fs.rmSync(notificationStateHome, { recursive: true, force: true });
 
@@ -407,7 +426,83 @@ check(kernelIterative.stdout.includes('"strategy":"iterative-single"'), 'kernel
 check(kernelIterative.stdout.includes('loop-awareness:'), 'kernel prints dynamic semantic plan obligations');
 check(kernelIterative.stdout.includes('visible-status-updates:'), 'kernel prints the user-visible status invariant');
 check(kernelIterative.stdout.includes('USER-VISIBLE HARNESS STATUS CONTRACT (MUST)'), 'kernel prints the canonical mandatory user-visible status contract');
-check(kernelIterative.stdout.includes('   - tdd'), 'kernel prints suggested skills separately from required invariants');
+check(kernelIterative.stdout.includes('KNOWLEDGE SIGNALS (STEP INPUT ONLY)'), 'kernel identifies knowledge signals as planning inputs');
+check(!kernelIterative.stdout.includes('tdd/SKILL.md'), 'initial router output waits for an active step before disclosing a skill path');
+check(!kernelIterative.stdout.includes('evaluate-suggestions-before-skip'), 'legacy read-every-suggestion invariant is removed');
+
+const retainedStateHome = fs.mkdtempSync(path.join(os.tmpdir(), 'harness-router-retained-step-'));
+const retainedSession = 'issue297-retained-step';
+const retainedEnv = {
+  ...process.env,
+  HARNESS_STATE_HOME: retainedStateHome,
+  HARNESS_WORKSPACE_ROOT: ROOT,
+};
+const retainedInput = prompt => JSON.stringify({ session_id: retainedSession, cwd: ROOT, hook_event_name: 'UserPromptSubmit', prompt });
+const initialRetainedRoute = spawnSync(process.execPath, [kernelRouter], {
+  cwd: ROOT,
+  encoding: 'utf8',
+  input: retainedInput('Fix this checkout bug and add a regression test.'),
+  env: retainedEnv,
+});
+check(initialRetainedRoute.status === 0, 'retained workflow fixture routes successfully');
+check(initialRetainedRoute.stdout.includes('PLANNING STEP: decompose → compose'), 'new selected workflow exposes its planning step');
+
+const sessionPathResult = spawnSync(process.execPath, ['-e', "const s=require('./hooks/scripts/lib/harness-state');process.stdout.write(s.getSessionDir(process.env.HARNESS_WORKSPACE_ROOT, process.env.TEST_SESSION_ID, {session_id:process.env.TEST_SESSION_ID,cwd:process.env.HARNESS_WORKSPACE_ROOT}))"], {
+  cwd: ROOT,
+  encoding: 'utf8',
+  env: { ...retainedEnv, TEST_SESSION_ID: retainedSession },
+});
+const retainedSessionDir = sessionPathResult.stdout;
+const retainedController = path.join(ROOT, 'hooks', 'scripts', 'workflow-disposition.js');
+const typedRequirements = JSON.stringify([
+  { id: 'req-review', stepType: 'review', summary: 'Review the checkout behavior', acceptance: 'the affected behavior is understood' },
+  { id: 'req-change', stepType: 'behavior-change', summary: 'Change the checkout behavior', acceptance: 'the requested behavior is corrected' },
+  { id: 'req-verify', stepType: 'verification', summary: 'Verify the checkout behavior', acceptance: 'objective verification evidence is recorded' },
+]);
+const planCommand = spawnSync(process.execPath, [retainedController, 'plan', '--session-id', retainedSession,
+  '--requirements-json', typedRequirements, '--strategy', 'iterative-single', '--evidence', 'three ordered requirement steps were confirmed'], {
+  cwd: ROOT, encoding: 'utf8', env: retainedEnv,
+});
+check(planCommand.status === 0, 'retained workflow records typed requirements before execution');
+const startCommand = spawnSync(process.execPath, [retainedController, 'start', '--session-id', retainedSession], {
+  cwd: ROOT, encoding: 'utf8', env: retainedEnv,
+});
+const startedRetained = JSON.parse(startCommand.stdout || '{}');
+check(startCommand.status === 0 && startedRetained.activeStep?.id === 'req-review', 'retained workflow starts at its first typed step');
+check(startedRetained.activeStepCommands?.resolveBinding.includes('--step-id "req-review"') &&
+  startedRetained.activeStepCommands?.passStep.includes('--step-id "req-review"'),
+  'start returns concrete active binding and step disposition commands');
+const reviewCommand = spawnSync(process.execPath, [retainedController, 'step', '--session-id', retainedSession,
+  '--step-id', 'req-review', '--disposition', 'pass', '--evidence', 'the affected behavior and request were reviewed'], {
+  cwd: ROOT, encoding: 'utf8', env: retainedEnv,
+});
+check(reviewCommand.status === 0, 'retained workflow advances to its active behavior-change step');
+
+const retainedWorkflowPath = path.join(retainedSessionDir, 'workflow-run.json');
+const retainedObligationsPath = path.join(retainedSessionDir, 'workflow-obligations.json');
+const retainedBeforeNotification = {
+  workflow: fs.readFileSync(retainedWorkflowPath, 'utf8'),
+  obligations: fs.readFileSync(retainedObligationsPath, 'utf8'),
+};
+const hostNotification = spawnSync(process.execPath, [kernelRouter], {
+  cwd: ROOT,
+  encoding: 'utf8',
+  input: retainedInput('<task-notification><task-id>active-step-reminder</task-id><status>completed</status></task-notification>'),
+  env: retainedEnv,
+});
+check(hostNotification.status === 0, 'host notification retains the active workflow');
+check(hostNotification.stdout.includes('req-change') && hostNotification.stdout.includes('tdd/SKILL.md'),
+  'retained notification preserves only the active step and its binding');
+check(hostNotification.stdout.includes('binding --session-id "issue297-retained-step" --step-id "req-change"') &&
+  hostNotification.stdout.includes('step --session-id "issue297-retained-step" --step-id "req-change"'),
+  'retained notification surfaces the binding and step disposition syntax');
+check(!hostNotification.stdout.includes('verification-loop/SKILL.md'), 'retained notification hides future-step bindings');
+check(!hostNotification.stdout.includes('ROUTER WORKFLOW PLAN (JSON)') && !hostNotification.stdout.includes('REQUIRED HARNESS INVARIANTS (SEMANTIC MUST)'),
+  'host notification avoids repeating the full workflow contract');
+check(retainedBeforeNotification.workflow === fs.readFileSync(retainedWorkflowPath, 'utf8') &&
+  retainedBeforeNotification.obligations === fs.readFileSync(retainedObligationsPath, 'utf8'),
+  'host notification does not replace or advance workflow state');
+fs.rmSync(retainedStateHome, { recursive: true, force: true });
 
 for (const schemaPath of [
   'harness-everything/schemas/router-task-shape.schema.json',

package/ci/skill-routing-check.js

@@ -1,9 +1,11 @@
 #!/usr/bin/env node
 /**
- * Deterministic route coverage gate for directly-routable skills plus an
- * explicit classification gate for nested skills. A new nested SKILL.md must
- * declare whether it is parent-routed or internal; otherwise CI fails instead
- * of silently ignoring it.
+ * Deterministic coverage gate for positive skill evals plus an explicit
+ * classification gate for nested skills. Each positive prompt must surface the
+ * skill as a candidate step-binding id (relevance), while the router must not
+ * push canonical skill paths before an active step binds them. A new nested
+ * SKILL.md must declare whether it is parent-routed or internal; otherwise CI
+ * fails instead of silently ignoring it.
  */
 
 const fs = require('fs');
@@ -22,6 +24,18 @@ const NESTED_ROUTING = new Map([
   ['fable-mode/fable-opus', 'parent'],
 ]);
 
+// Skills whose positive evals prove a route shape rather than a binding: the
+// router itself and the todo-driven multi-step strategy.
+const ROUTE_SHAPE_SKILLS = new Map([
+  ['harness-everything', output => /=> RECOMMENDED TIER: \S/.test(output)],
+  ['todo-driven-workflow', output => /=> WORKFLOW STRATEGY: (?!deferred)\S+/.test(output)],
+]);
+
+function candidateBindingIds(output) {
+  const line = output.match(/Candidate step binding ids: ([^\r\n]+)/);
+  return line ? line[1].split(',').map(id => id.trim()).filter(Boolean) : [];
+}
+
 function walkPositiveTasks(dir) {
   if (!fs.existsSync(dir)) return [];
   const files = [];
@@ -47,12 +61,6 @@ function discoverNestedSkills(skillDir) {
   return found;
 }
 
-function expectedMarker(skill) {
-  if (skill === 'harness-everything') return 'RECOMMENDED TIER';
-  if (skill === 'todo-driven-workflow') return 'WORKFLOW STRATEGY';
-  return `${skill}/SKILL.md`;
-}
-
 const skillDirs = fs.readdirSync(ROOT, { withFileTypes: true })
   .filter(entry => entry.isDirectory() && fs.existsSync(path.join(ROOT, entry.name, 'SKILL.md')))
   .map(entry => entry.name)
@@ -62,6 +70,8 @@ let failures = 0;
 let cases = 0;
 
 const nestedOnDisk = skillDirs.flatMap(skill => discoverNestedSkills(path.join(ROOT, skill))).sort();
+const canonicalSkillPaths = [...skillDirs, ...nestedOnDisk]
+  .map(skill => `${skill.replace(/\\/g, '/')}/SKILL.md`);
 for (const nested of nestedOnDisk) {
   const classification = NESTED_ROUTING.get(nested);
   if (!classification) {
@@ -121,15 +131,34 @@ for (const skill of skillDirs) {
 
     const result = spawnSync(process.execPath, [ROUTER, prompt], { cwd: ROOT, encoding: 'utf8' });
     const output = `${result.stdout || ''}\n${result.stderr || ''}`;
-    const marker = expectedMarker(skill);
-    if (result.status !== 0 || !output.includes(marker)) {
-      console.error(`FAIL ${path.relative(ROOT, taskFile)}: expected "${marker}"`);
+    const missingPlanFields = [
+      '=> RECOMMENDED TIER:',
+      '=> WORKFLOW STRATEGY:',
+    ].filter(marker => !output.includes(marker));
+    const requestedNested = nestedOnDisk
+      .filter(nested => NESTED_ROUTING.get(nested) === 'parent')
+      .filter(nested => (task.tags || []).includes(path.posix.basename(nested)));
+    const requiredParentPaths = requestedNested
+      .map(nested => `${nested.split('/')[0]}/SKILL.md`);
+    const missingParentPaths = requiredParentPaths.filter(skillPath => !output.includes(skillPath));
+    const leakedPaths = canonicalSkillPaths
+      .filter(skillPath => output.includes(skillPath) && !requiredParentPaths.includes(skillPath));
+    const routeShape = ROUTE_SHAPE_SKILLS.get(skill);
+    const relevant = routeShape ? routeShape(output) : candidateBindingIds(output).includes(skill);
+    if (result.status !== 0 || missingPlanFields.length || missingParentPaths.length || leakedPaths.length || !relevant) {
+      const reasons = [];
+      if (result.status !== 0) reasons.push(`router exited ${result.status}`);
+      if (missingPlanFields.length) reasons.push(`missing ${missingPlanFields.join(', ')}`);
+      if (!relevant) reasons.push(routeShape ? 'expected route shape not emitted' : `skill is not a candidate step binding (got: ${candidateBindingIds(output).join(', ') || 'none'})`);
+      if (missingParentPaths.length) reasons.push(`missing explicit parent route: ${missingParentPaths.join(', ')}`);
+      if (leakedPaths.length) reasons.push(`pre-step skill paths leaked: ${leakedPaths.join(', ')}`);
+      console.error(`FAIL ${path.relative(ROOT, taskFile)}: ${reasons.join('; ')}`);
       failures++;
     } else {
-      console.log(`PASS ${skill}/${path.basename(taskFile)}`);
+      console.log(`PASS ${skill}/${path.basename(taskFile)}: skill-specific relevance proven without pre-step path leaks`);
     }
   }
 }
 
-console.log(`\nRoute coverage: ${cases} positive case(s) checked across ${skillDirs.length} direct skills; ${nestedOnDisk.length} nested skill(s) classified.`);
+console.log(`\nPositive skill-eval coverage: ${cases} case(s) checked across ${skillDirs.length} direct skills; ${nestedOnDisk.length} nested skill(s) classified.`);
 process.exit(failures ? 1 : 0);

package/ci/workflow-plan-consumers.test.js

@@ -22,6 +22,7 @@ const {
   prepareRun,
   validateStageGraph,
 } = require(path.join(ROOT, 'fable-mode', 'scripts', 'workflow-plan-consumer.js'));
+const { activeStageBindings } = require(path.join(ROOT, 'fable-mode', 'scripts', 'workflow-plan-consumer.js'));
 const { consumeWorkspacePlan } = require(path.join(ROOT, 'multi-agent-workspace', 'scripts', 'consume-workflow-plan.js'));
 const { pathWithinScope } = require(path.join(ROOT, 'hooks', 'scripts', 'lib', 'fable-contracts.js'));
 
@@ -70,17 +71,20 @@ const parallelStages = [
   {
     stageId: 'security', goal: 'read security state', agent: 'fable-worker-sonnet', task: 'audit security',
     inputs: [], expectedOutputs: ['security notes'], outputPath: null, dependsOn: [], writeSet: [],
+    requiredBindings: ['unknown-security-check'],
     checkCommand: 'node --test security.test.js', passCondition: 'exit 0',
   },
   {
     stageId: 'architecture', goal: 'read architecture state', agent: 'fable-worker-sonnet', task: 'audit architecture',
     inputs: [], expectedOutputs: ['architecture notes'], outputPath: null, dependsOn: [], writeSet: [],
+    optionalBindings: [{ id: 'architecture-reference', path: 'docs/architecture.md' }],
     checkCommand: 'node --test architecture.test.js', passCondition: 'exit 0',
   },
   {
     stageId: 'synthesis', goal: 'synthesize results', agent: 'fable-worker-sonnet', task: 'write synthesis',
     inputs: [], expectedOutputs: ['summary'], outputPath: 'reports/summary.md', dependsOn: ['security', 'architecture'],
-    writeSet: ['reports/summary.md'], checkCommand: 'node --test synthesis.test.js', passCondition: 'exit 0',
+    writeSet: ['reports/summary.md'], requiredBindings: [{ id: 'verification-loop', path: 'verification-loop/SKILL.md' }],
+    checkCommand: 'node --test synthesis.test.js', passCondition: 'exit 0',
   },
 ];
 
@@ -95,6 +99,30 @@ check(JSON.stringify(runA.execution.batches) === JSON.stringify([['architecture'
 check(runA.execution.limits.maxWorkers === 4, 'run manifest retains maxWorkers as an advisory planning hint');
 check(fs.existsSync(path.join(runA.runRoot, 'contracts', 'security.json')), 'run-scoped stage contract is written');
 check(fs.existsSync(path.join(runA.runRoot, 'contracts', 'synthesis.json')), 'downstream stage has its own contract');
+const initialActiveStages = activeStageBindings(runA.runRoot);
+check(initialActiveStages.map(stage => stage.stageId).join(',') === 'security,architecture', 'only dependency-ready Fable stages expose bindings');
+check(initialActiveStages[0].requiredBindings[0].path === null &&
+  initialActiveStages[0].requiredBindings[0].status === 'pending', 'unknown required binding remains visible and unresolved');
+check(initialActiveStages[1].optionalBindings[0].path === 'docs/architecture.md' &&
+  initialActiveStages[1].optionalBindings[0].status === 'pending', 'active optional reference path appears only on its ready stage');
+check(!JSON.stringify(initialActiveStages).includes('verification-loop/SKILL.md'), 'future-stage binding paths stay hidden until dependencies pass');
+for (const stageId of ['security', 'architecture']) {
+  const file = path.join(runA.runRoot, 'contracts', `${stageId}.json`);
+  const contract = JSON.parse(fs.readFileSync(file, 'utf8'));
+  contract.status = 'pass';
+  fs.writeFileSync(file, JSON.stringify(contract));
+}
+const unresolvedDependencies = activeStageBindings(runA.runRoot);
+check(!unresolvedDependencies.some(stage => stage.stageId === 'synthesis'), 'a stage marked pass with unresolved bindings does not activate dependents');
+for (const stageId of ['security', 'architecture']) {
+  const file = path.join(runA.runRoot, 'contracts', `${stageId}.json`);
+  const contract = JSON.parse(fs.readFileSync(file, 'utf8'));
+  for (const binding of [...contract.requiredBindings, ...contract.optionalBindings]) binding.status = 'loaded';
+  fs.writeFileSync(file, JSON.stringify(contract));
+}
+const nextActiveStages = activeStageBindings(runA.runRoot);
+check(nextActiveStages.map(stage => stage.stageId).join(',') === 'synthesis', 'downstream bindings appear only after every dependency passes');
+check(nextActiveStages[0].requiredBindings[0].path === 'verification-loop/SKILL.md', 'current stage receives only its own declared binding path');
 
 const runB = prepareRun({
   routerContract: parallelContract,
@@ -143,6 +171,18 @@ expectThrow(() => validateStageGraph([
   { stageId: 'b', goal: 'b', agent: 'a', task: 'b', dependsOn: ['a'], writeSet: [], inputs: [], expectedOutputs: [] },
 ]), /cyclic/, 'dependency cycle is rejected');
 
+expectThrow(() => validateStageGraph([
+  { stageId: 'unsafe-binding', goal: 'x', agent: 'a', task: 'x', dependsOn: [], writeSet: [], requiredBindings: [{ id: 'escaped', path: '../outside.md' }] },
+]), /repository-relative|escapes/, 'binding paths reject traversal outside the repository');
+
+expectThrow(() => validateStageGraph([
+  { stageId: 'drive-binding', goal: 'x', agent: 'a', task: 'x', dependsOn: [], writeSet: [], requiredBindings: [{ id: 'drive', path: 'C:outside.md' }] },
+]), /repository-relative|escapes/, 'binding paths reject Windows drive-relative names');
+
+expectThrow(() => validateStageGraph([
+  { stageId: 'duplicate-binding', goal: 'x', agent: 'a', task: 'x', dependsOn: [], writeSet: [], requiredBindings: ['same'], optionalBindings: ['same'] },
+]), /both required and optional/, 'a stage binding cannot be both required and optional');
+
 expectThrow(() => prepareRun({
   routerContract: parallelContract,
   workspaceRoot: workspace,

package/docs/architecture.md

@@ -10,7 +10,7 @@ The minimal kernel establishes:
 
 - scope/tier before mutation,
 - a selected workflow topology as a semantic execution contract when task evidence supports one,
-- applicability evaluation for every suggested skill before omission,
+- ordered requirement decomposition and step-scoped knowledge bindings,
 - objective evidence before completion,
 - bounded re-plan/recovery after repeated failure,
 - explicit warnings/degraded/escape evidence instead of silent workflow deletion;
@@ -18,7 +18,7 @@ The minimal kernel establishes:
 
 > **Contract-first lifecycle; flexible reasoning/implementation and execution.**
 >
-> Suggested skills MUST be evaluated from their real flows. Applicable skill core contracts and selected-topology obligations are semantic MUSTs; missing evidence produces reminders rather than persistent Harness locks.
+> Active required bindings and selected-topology obligations are semantic MUSTs; keyword signals are planning inputs, and unrelated future bindings stay undisclosed.
 
 This avoids both extremes: no universal Tier-2/Tier-3 pipeline and no maze of self-deadlocking cognitive gates.
 
@@ -31,10 +31,9 @@ flowchart TD
     P --> A{Strategy selected?}
     A -- No / deferred --> D[Preserve invariants<br/>choose smallest justified workflow]
     A -- Yes --> C[ACTIVE workflow contract]
-    C --> S{Suggested skills?}
-    S -- Yes --> E[Read SKILL.md<br/>resolve applicability]
-    S -- No --> X[Execute topology]
-    E --> X
+    C --> D[Decompose ordered requirements]
+    D --> B[Bind skills/references per step]
+    B --> X[Execute active step/stage]
     X --> V{Required stage/check resolved?}
     V -- Yes --> Done[Evidence-backed completion]
     V -- No --> R[Diagnose / bounded re-plan]
@@ -49,7 +48,8 @@ flowchart TD
 - tier + rationale,
 - selected/deferred execution strategy,
 - required invariants,
-- suggested skills that require applicability evaluation,
+- normalized knowledge signals for planning, not document selection,
+- bindings only for the active step or dependency-ready Fable stage,
 - the internal routing checkpoint,
 - the semantic workflow contract.
 
@@ -74,9 +74,9 @@ Use nested evidence bullets when multiple items would otherwise become one dense
 
 This is a semantic contract, not another cognitive lock. Hook-capable hosts may observe or remind about compliance; instruction-only hosts still receive the MUST contract without pretending they can mechanically enforce it.
 
-### Skill applicability vs. topology execution
+### Step-scoped knowledge vs. topology execution
 
-Router suggestions remain useful domain/workflow knowledge, not a universal sequence. Before omission, the agent reads the complete `SKILL.md` entry and evaluates `USE FOR`, `DO NOT USE FOR`, workflow/basic flow, and hard rules. Name/description/router-summary or “routine task” is insufficient evidence.
+Keyword/domain matches are planning signals, not skill/reference paths. Requirement composition declares bindings on ordered steps; only active bindings are disclosed. A required skill binding MUST be read and its applicable core contract followed before the step passes. Unknown/unavailable paths remain visible and unresolved, while unrelated and future-step knowledge is not preloaded.
 
 The selected topology is a semantic lifecycle contract, not a persistent execution lock. Required obligations MUST resolve; implementation tactics MAY adapt.
 
@@ -89,7 +89,7 @@ For selected Fable topologies on Claude:
 - `workflow-gate.js` observes supported mutation/worktree/Fable state and emits reminders;
 - Fable owns stage contracts, `dependsOn`/`writeSet`, validated execution batches, objective per-stage checks, synthesis, cold verification, and bounded re-plans;
 - `workflow-stop-gate.js` reports unresolved stage/verification evidence without rejecting Stop;
-- `workflow-disposition.js` records explicit lifecycle/audit decisions; numeric budgets are no longer authoritative control state.
+- `workflow-disposition.js` records explicit lifecycle/audit decisions and active step/stage binding dispositions; numeric budgets are no longer authoritative control state.
 
 Other topologies use their own applicable mechanisms: MAY-level loop-awareness planning hints, regular verification stop-gates, action gates, and task-specific skills. Mechanism coverage is not assumed identical across hosts.
 

package/docs/enforcement-locks.md

@@ -7,7 +7,7 @@ Harness deliberately separates **semantic obligation strength** from **mechanica
 | Mechanism / obligation | Semantic strength | Runtime behavior | Hard block? |
 |---|---|---|---|
 | Workflow routing / selected topology | **MUST** resolve required obligations | Observe/remind about unresolved lifecycle evidence | No |
-| Suggested skill applicability | **MUST** evaluate; applicable core contract **MUST** run | Kernel/instructions expose dispositions | No |
+| Active required skill/reference binding | **MUST** load/resolve before its step passes; applicable skill core contract **MUST** be followed | Step/stage contract records declared binding dispositions; active paths only | No |
 | Iteration/revision/replan/worker numbers | **MAY** guide planning | Planning hints only | No |
 | Verification before claim | **MUST** | Stop/hooks remind when evidence is missing | No |
 | Boundary guard / huge-noisy context | **SHOULD** narrow reads/searches | Warn | No |

package/docs/mechanism-first-skill-mesh.md

@@ -4,7 +4,7 @@ Harness coordinates independently useful skills through a small workflow runtime
 
 The preferred shape is:
 
-> **guidance-first workflow + local skill autonomy + narrow runtime mechanisms**
+> **step-scoped knowledge bindings + local skill autonomy + narrow runtime mechanisms**
 
 Platform-specific enforcement claims remain bounded by [platform-capabilities.md](platform-capabilities.md).
 
@@ -19,7 +19,7 @@ A skill should answer:
 3. **What workflow/mechanism do I expose?** A local flow, verifier, script, gate, or stable result when useful.
 4. **What evidence means I am done?** A check, artifact, or explicit blocked state.
 
-The router may surface several skills. Those suggestions must be evaluated from their actual `SKILL.md` flows before omission. They are **not** automatically all executed. Separately, the router selects one smallest sufficient outer topology. **The selected topology guides the run.**
+The router emits normalized keyword/domain signals for requirement composition; these signals are not document selectors. Ordered requirement steps declare the skills/references they need, and only the active step or dependency-ready Fable stage exposes those paths. Separately, the router selects one smallest sufficient outer topology. **The selected topology governs the run.**
 
 ## Why Not One Global Skill Sequence?
 
@@ -33,16 +33,15 @@ A universal TODO/TDD/Fable sequence would:
 So Harness separates **topology** from **capabilities/domain skills**:
 
 ```text
-tier / task shape
       +
 selected execution topology
       +
-applicable skills/capabilities
+active-step knowledge bindings
       +
 required invariants/gates
 ```
 
-The topology is the lifecycle contract. Skills are resolved for applicability within/around that contract.
+The topology is the lifecycle contract. Skills and references are bound to the requirement steps that consume them.
 
 ## Mechanisms Over Prose
 
@@ -56,8 +55,9 @@ tier: 2
 strategy: iterative-single
 workflow_state: active
 required: scope-lock, objective-verification, loop-awareness
-suggest: tdd, verification-loop
-suggestion_policy: evaluate-applicability
+knowledge_signals: test-related
+active_step: behavior-change
+required_bindings: tdd/SKILL.md
 escape_policy: workflow-uncovered-scope-only
 ```
 
@@ -81,18 +81,19 @@ Every skill should retain:
 - explicit neighbor links rather than hidden dependencies;
 - blocked/exit discipline.
 
-Read-before-omission exists so the agent can inspect this local contract without loading the entire ecosystem. If the skill flow applies, follow it; reading a skill is not permission to discard an applicable discipline because the model believes it already knows the answer.
+An active required binding exists so the agent can inspect the local contract without loading the entire ecosystem. If the skill applies to that step, follow its core contract; later or unrelated bindings remain undisclosed.
 
 ## Coordination Patterns
 
 ### Router Decision
 
-`harness-everything/scripts/kernel-router.js` emits tier, strategy, invariants, skill suggestions, and an execution contract.
+`harness-everything/scripts/kernel-router.js` emits tier, strategy, invariants, normalized knowledge signals, and an execution contract.
 
-- Suggested skills: read and resolve applicability (`use`, `not-applicable`, `unresolved/unavailable`).
+- Knowledge signals: planning inputs only; they never choose paths.
+- Active bindings: declare required/optional skill/reference ids and paths on ordered steps; future-step bindings remain hidden.
 - Selected topology: execute to resolution (`active` → verified/satisfied, blocked, or explicit evidence-backed escape).
 
-Names/descriptions/router summaries or “routine task” judgements cannot resolve applicability by themselves.
+Required bindings must resolve before the current step/stage passes. Unknown/unavailable bindings stay visible; hooks and Stop remain fail-open.
 
 ### Fable Stage Contracts
 

package/docs/openai-plugin.md

@@ -28,7 +28,7 @@ flowchart TD
     X[Stop hook] --> V
 ```
 
-The local OpenAI adapter enforces cross-cutting invariants through the lifecycle events that it packages. Suggested skills require applicability evaluation; the selected topology is mandatory with scoped, evidence-backed escape. The [workflow runtime](workflow-runtime.md) documents pending/running/satisfied/blocked state, Fable entry, worktree isolation, completion evidence, and degradation limits. Tool enforcement is limited to the host tool names declared in `hooks/hooks.json`.
+The local OpenAI adapter observes cross-cutting invariants through the lifecycle events that it packages. Required bindings are declared per active step/stage; the selected topology is mandatory with scoped, evidence-backed escape. The [workflow runtime](workflow-runtime.md) documents active binding visibility, pending/running/satisfied/blocked state, Fable entry, worktree isolation, completion evidence, and degradation limits. Tool enforcement is limited to the host tool names declared in `hooks/hooks.json`.
 
 ## Package layout
 

package/docs/philosophy.md

@@ -10,7 +10,7 @@ The mechanism/enforcement boundary remains platform-specific; see [Platform Capa
 
 1. **Reasoning autonomy remains high.** The model chooses implementation technique, tools, decomposition details, and tactics inside the selected workflow.
 2. **Selected lifecycle obligations are contracts, not advice.** Once a topology is selected, its required invariants, stages, checks, synthesis barriers, and verification obligations are semantic MUSTs. The model remains free to decide how to satisfy them.
-3. **Skill applicability is explicit.** Every router-suggested skill MUST be read/evaluated before omission. If its real flow is applicable, its core contract MUST be followed; if it is not applicable, the agent MUST keep a flow-grounded reason.
+3. **Knowledge is step-scoped.** Normalized keyword signals help requirement composition but do not select documents. Ordered steps declare required/optional skill or reference bindings; active required bindings MUST be read and their applicable core contracts followed before the step passes.
 4. **Escape is conditional, not default.** If the selected workflow genuinely cannot represent part of the task, record the uncovered scope and evidence, then allow model-defined handling only for that uncovered portion.
 5. **Mechanisms do not define obligation strength.** Hooks/plugins may observe, remind, or mechanically block where the host supports them, but a missing blocking mechanism does not downgrade a semantic MUST to optional advice.
 
@@ -26,7 +26,7 @@ Harness uses three semantic strengths. Recommendation-style language is the last
 
 | Strength | Meaning | Typical use |
 |---|---|---|
-| **MUST** | Skipping the obligation violates the Harness semantic contract. Host enforcement may still be reminder-only. | routing, applicability resolution, applicable skill core contracts, selected-topology obligations, verification-before-claim, status, scope/safety/authorization evidence |
+| **MUST** | Skipping the obligation violates the Harness semantic contract. Host enforcement may still be reminder-only. | routing, active required binding resolution, applicable skill core contracts, selected-topology obligations, verification-before-claim, status, scope/safety/authorization evidence |
 | **SHOULD** | The default is expected, but a concrete evidence-based exception is legitimate. | ordinary isolation, targeted editing, splitting mixed commit concerns, context-size/noisy-search discipline |
 | **MAY** | Optional optimization/capability. Omitting it needs no exception unless another contract selected it. | numeric planning hints, optional ensemble selection, extra deep references, opportunistic parallelism |
 
@@ -37,8 +37,9 @@ The repository-wide classification for #217 is:
 | Obligation | Strength |
 |---|---|
 | Route before software/project execution | **MUST** |
-| Read/evaluate every suggested skill before omission | **MUST** |
-| Follow an applicable suggested skill's core contract; otherwise keep a flow-grounded not-applicable reason | **MUST** |
+| Resolve active required skill/reference bindings before their step | **MUST** |
+| Follow an active skill binding's applicable core contract | **MUST** |
+| Load unrelated keyword-matched documents or future-step bindings | Not required |
 | Resolve selected-topology invariants/stages/checks/synthesis/verification | **MUST** |
 | Choose tools, implementation technique, decomposition details, and local tactics | **MAY** within the MUST contract |
 | Verify before claiming completion | **MUST** |
@@ -67,7 +68,7 @@ The router chooses the **smallest sufficient topology**:
 - `fable-parallel` only for validated independent workstreams;
 - `fable-multi-agent-workspace` when persistent roles/handoffs/memory are materially needed.
 
-Domain skills remain conditional on applicability. The contract says “execute the selected lifecycle”, not “execute every skill in the repository.”
+Domain skills and references are conditional on the needs of each requirement step. The contract says “execute the selected lifecycle”, not “execute every skill in the repository.” Unknown required bindings remain visible and unresolved; they do not turn workflow hooks into a persistent lock.
 
 ## The 4 Pillars of AI Model Guidance
 
@@ -81,7 +82,7 @@ Circuit breakers, action gates, workflow gates, scope guards, and completion gat
 
 ### 3. Context Preservation — Progressive Disclosure
 
-**SHOULD** load the smallest useful context. A suggested skill's complete entry **MUST** be read before deciding applicability; optional deep references **MAY** remain unloaded unless needed. Machine-visible workflow state SHOULD carry lifecycle facts instead of repeating large prompt blocks.
+**SHOULD** load the smallest useful context. An active required skill's complete entry **MUST** be read and followed; optional bindings resolve as loaded or not-needed. Future-step bindings remain undisclosed until active. Machine-visible workflow state SHOULD carry lifecycle facts instead of repeating large prompt blocks.
 
 ### 4. Self-Evolution — Learn from Workflow Evidence