harness-everything 0.30.9 → 0.31.0

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

@@ -5,11 +5,11 @@ const {
   buildRouterContract,
   writeRouterContract,
 } = require('./router-contract');
-const { requireWorkspace } = require('./runtime-paths');
+const { getHarnessRoot, requireWorkspace } = require('./runtime-paths');
 
 const DEFAULT_ROUTING_CONFIG = {
   tiers: { tier3: [], tier2: [] },
-  guideGroups: [],
+  inputSignalGroups: [],
   factAudit: { externalClaim: [], estimate: [] },
 };
 
@@ -21,7 +21,7 @@ function loadRoutingConfig() {
     return {
       config: {
         tiers: parsed.tiers || DEFAULT_ROUTING_CONFIG.tiers,
-        guideGroups: Array.isArray(parsed.guideGroups) ? parsed.guideGroups : DEFAULT_ROUTING_CONFIG.guideGroups,
+        inputSignalGroups: Array.isArray(parsed.inputSignalGroups) ? parsed.inputSignalGroups : DEFAULT_ROUTING_CONFIG.inputSignalGroups,
         factAudit: parsed.factAudit || DEFAULT_ROUTING_CONFIG.factAudit,
       },
       routingStatus: 'ok',
@@ -60,15 +60,25 @@ function detectFableModel(prompt) {
 // retains execution routing; format field lists are recognized separately.
 function containsOnlyLookupTerms(text, operation) {
   const terms = {
-    explanation: /\b(?:please|help|me|explain|resolve|define|what|is|does|mean|means|meaning|the|a|an|of|to|into|in|for|behavior|behaviour|profile|profiles|selection|json|record|alias|role|runtime|model|effort|floor|fableprofile)\b/gi,
-    output: /\b(?:return|respond|output|show|provide|only|a|an|small|compact|json|record|selection|profile|result|with|fields|containing|include|including)\b/gi,
+    explanation: /\b(?:please|help|me|could|would|you|explain|resolve|define|what|is|does|mean|means|meaning|the|a|an|of|to|into|in|for|as|compact|small|only|behavior|behaviour|profile|profiles|selection|json|record|object|alias|role|runtime|model|effort|floor|fableprofile)\b/gi,
+    output: /\b(?:as|return|respond|output|show|provide|only|a|an|small|compact|short|json|record|object|selection|profile|result|with|fields|containing|include|including)\b/gi,
   };
   const chineseTerms = {
-    explanation: /(?:請|幫我|解釋|說明|解析|的意思|意思|含義|意義|是什麼|設定檔|行為|角色)/g,
+    explanation: /(?:請問|麻煩|請|幫我|解釋|說明|解析|的意思|意思|含義|意義|是什麼|設定檔|行為|角色|精簡|簡短|緊湊|JSON|紀錄|記錄)/g,
     output: /(?:只|僅|回傳|返回|輸出|顯示|提供|包含|含|的|欄位|記錄|紀錄|結果|設定檔)/g,
   };
   return text.replace(PROFILE_LOOKUP_FIELDS, '').replace(terms[operation], '')
-    .replace(chineseTerms[operation], '').replace(/[\s"'`“”‘’?:：？]/g, '') === '';
+    .replace(chineseTerms[operation], '').replace(/[.!?]+$/g, '').replace(/[\s"'`“”‘’?:：？]/g, '') === '';
+}
+
+function splitProfileLookupClauses(prompt) {
+  let text = String(prompt || '').trim()
+    .replace(/^(?:could\s+you(?:\s+please)?|would\s+you(?:\s+please)?|please)\s*,?\s+/i, '')
+    .replace(/^(?:麻煩請|麻煩|請問|請)\s*/u, '');
+  const outputLead = String.raw`(?:please\s+)?(?:return|respond|output|show|provide|no|without|do\s+not|don't)\b|(?:請(?:問)?\s*)?(?:只|僅|回傳|返回|輸出|顯示|提供|不要|不需要|無需|無須|不必|毋須|不用|不會|不)`;
+  text = text.replace(new RegExp(String.raw`\.(?=\s*${outputLead})|[—–](?=\s*(?:${outputLead}|as\s+(?:a\s+)?(?:compact\s+|small\s+|short\s+)?json\s+(?:record|object)\b))`, 'giu'), ';');
+  return text.split(/(?:\.{3,}|[;!?？！,，；。、…]|\b(?:and\s+then|and|then|also|plus|afterwards|additionally)\b|(?:並且?|以及|接著|然後|另外))/iu)
+    .map(part => part.trim().replace(/[.!?…]+$/g, '')).filter(Boolean);
 }
 
 // A negation scopes only its own noun/verb list. Vocabulary-only matching would
@@ -80,11 +90,12 @@ const NEGATED_ITEM = '(?:orchestration|delegation|stages?|staging|execution|mode
 const NEGATED_ACTION = '(?:switch(?:ing)?\\s+(?:the\\s+)?models?|delegate|orchestrate|stage|execute)';
 const ENGLISH_NEGATION = new RegExp(`^(?:(?:no|without)\\s+${negatedList(NEGATED_ITEM)}|(?:do not|don't)\\s+${negatedList(NEGATED_ACTION)})$`, 'i');
 const ENGLISH_NEGATION_CONTINUATION = new RegExp(`^(?:or\\s+)?${negatedList(NEGATED_ITEM)}$`, 'i');
-const CHINESE_NEGATION_TERMS = /(?:不要|不需要|無需|不|或|編排|委派|階段|執行|切換模型)/g;
+const CHINESE_NEGATION_PREFIX = /^(?:不要|不需要|無需|無須|不必|毋須|不用|不會|不)/;
+const CHINESE_NEGATION_TERMS = /(?:不要|不需要|無需|無須|不必|毋須|不用|不會|不|或|也|任何|一切|啟動|開始|開啟|進入|執行|進行|運行|啟用|切換|模型|階段|流程|任務|操作|編排|委派)/g;
 
 function isBoundedNegation(clause, continuation) {
-  const text = clause.replace(/’/g, "'").replace(/[“”"`?:：？]/g, '').replace(/\s+/g, ' ').trim();
-  if (/^(?:不要|不需要|無需|不)/.test(text)) {
+  const text = clause.replace(/’/g, "'").replace(/[.!?…]+$/g, '').replace(/[“”"`?:：？]/g, '').replace(/\s+/g, ' ').trim();
+  if (CHINESE_NEGATION_PREFIX.test(text)) {
     return !continuation && text.replace(CHINESE_NEGATION_TERMS, '').replace(/\s/g, '') === '';
   }
   return (continuation ? ENGLISH_NEGATION_CONTINUATION : ENGLISH_NEGATION).test(text);
@@ -94,8 +105,7 @@ function isFableProfileLookup(prompt, hasMacroSignal) {
   if (!detectFableModel(prompt) || hasMacroSignal) return false;
   if (/\b(?:direct[- ]single|iterative[- ]single|fable[- ](?:staged|parallel|multi[- ]agent[- ]workspace))\b/i.test(prompt)) return false;
 
-  const clauses = prompt
-    .split(/(?:[;,.，；。、]|\b(?:and|then|also|plus|afterwards|additionally)\b|(?:並且?|以及|接著|然後|另外))/i)
+  const clauses = splitProfileLookupClauses(prompt)
     .map(part => part.trim())
     .filter(Boolean);
   if (clauses.length === 0) return false;
@@ -105,14 +115,15 @@ function isFableProfileLookup(prompt, hasMacroSignal) {
   const normalizedLookup = lookupClause.replace(/[“”]/g, '"').replace(/[‘’]/g, "'")
     .replace(quotedInvocation, 'fableprofile')
     .replace(new RegExp(FABLE_PROFILE_INVOCATION.source, 'gi'), 'fableprofile');
-  const isLookupLead = /^(?:(?:please|help me)\s+|(?:請|幫我)\s*)?(?:explain|resolve|define|what (?:is|does)|解釋|說明|解析)/i.test(lookupClause)
+  const isLookupLead = /^(?:(?:please|help me|could you(?: please)?|would you(?: please)?)\s+|(?:請問|麻煩請|麻煩|請|幫我)\s*)?(?:explain|resolve|define|what (?:is|does)|解釋|說明|解析)/i.test(lookupClause)
     && Boolean(detectFableModel(lookupClause));
-  if (!isLookupLead || !containsOnlyLookupTerms(normalizedLookup, 'explanation')) return false;
+  const normalizedFormatRequest = normalizedLookup.replace(/\bas\s+(?:a\s+)?(?:compact|small|short)?\s*json\s+(?:record|object)\b/gi, '');
+  if (!isLookupLead || !containsOnlyLookupTerms(normalizedFormatRequest, 'explanation')) return false;
 
   let continuationOperation = null;
   for (const clause of continuations) {
-    const output = /^(?:please\s+)?(?:return|respond|output|show|provide)\b|^(?:請\s*)?(?:只|僅)?(?:回傳|返回|輸出|顯示|提供)/i.test(clause);
-    const negative = /^(?:please\s+)?(?:no|without|do not|don't)\b|^(?:請\s*)?(?:不要|不需要|無需|不)/i.test(clause);
+    const output = /^(?:please\s+)?(?:return|respond|output|show|provide)\b|^as\s+(?:a\s+)?(?:compact\s+|small\s+|short\s+)?json\s+(?:record|object)\b|^(?:請\s*)?(?:只|僅)?(?:回傳|返回|輸出|顯示|提供)/i.test(clause);
+    const negative = /^(?:please\s+)?(?:no|without|do not|don't)\b|^(?:請\s*)?(?:不要|不需要|無需|無須|不必|毋須|不用|不會|不)/i.test(clause);
     if (output || negative) {
       continuationOperation = output ? 'output' : 'negative';
       const normalizedContinuation = clause.replace(/^(?:please\s+|請\s*)/i, '');
@@ -184,16 +195,6 @@ function addReason(reasonCodes, code) {
   if (code && !reasonCodes.includes(code)) reasonCodes.push(code);
 }
 
-function deduplicateGuidesByPath(guides) {
-  const byPath = new Map();
-  for (const guide of guides) {
-    const match = String(guide).match(/^\s*-\s+([^\s]+)/);
-    const key = match ? match[1].replace(/\\/g, '/') : String(guide).trim();
-    if (!byPath.has(key)) byPath.set(key, guide);
-  }
-  return Array.from(byPath.values());
-}
-
 function countDomainSignals(promptLower) {
   const domains = [
     /\bsecurity\b|安全|資安/i,
@@ -238,73 +239,17 @@ function plannerInputsFromContext(context, promptLower) {
   return { hostCapabilities, constraints };
 }
 
-function emitDynamicSkills(promptLower, context, recommendedGuides) {
+// Self-evolved skills are discovered from manifest metadata only: matching ids
+// become step inputs, and the SKILL.md path resolves when a declaring step is
+// active. Discovery is advisory and never breaks routing.
+function matchGeneratedSkillIds(promptLower, context) {
   try {
-    const userHome = process.env.HOME || process.env.USERPROFILE || '';
+    const generated = require(path.join(getHarnessRoot(), 'scripts', 'lib', 'generated-skills.js'));
     const { getWorkspaceRoot } = requireWorkspace();
-    const workspaceRoot = getWorkspaceRoot(context);
-
-    const manifestPaths = [
-      path.join(workspaceRoot, '.claude', 'harness-everything', 'manifest.json'),
-      path.join(workspaceRoot, '.cursor', 'harness-everything', 'manifest.json'),
-      path.join(workspaceRoot, '.github', 'harness-everything', 'manifest.json'),
-      path.join(workspaceRoot, '.codex', 'harness-everything', 'manifest.json'),
-      path.join(workspaceRoot, '.continue', 'harness-everything', 'manifest.json'),
-      path.join(userHome, '.agents', 'harness-everything', 'manifest.json'),
-      path.join(userHome, '.claude', 'harness-everything', 'manifest.json'),
-    ];
-
-    const generatedSkills = new Map();
-    for (const manifestPath of manifestPaths) {
-      if (!fs.existsSync(manifestPath)) continue;
-      try {
-        const manifestData = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
-        if (Array.isArray(manifestData.generated)) {
-          for (const skill of manifestData.generated) generatedSkills.set(skill.id, skill);
-        }
-      } catch (err) {
-        // Ignore malformed generated-skill manifests; they are advisory only.
-      }
-    }
-
-    const allDynamicSkills = Array.from(generatedSkills.values());
-    const matchedDynamicSkills = [];
-
-    for (const skill of allDynamicSkills) {
-      let score = 0;
-      for (const rawTrigger of skill.triggers || []) {
-        const trigger = rawTrigger.toLowerCase().trim();
-        if (!trigger || trigger.length < 2) continue;
-        if (['the', 'and', 'for', 'with', 'your', 'this', 'that', 'some', 'from', 'prevent', 'resolved'].includes(trigger)) continue;
-
-        if (/[\u4e00-\u9fa5]/.test(trigger)) {
-          if (promptLower.includes(trigger)) score += trigger.length * 2;
-        } else {
-          const escapedTrigger = trigger.replace(/[-/\\^$*+?.()|[\]{}]/g, '\\$&');
-          const regex = new RegExp(`\\b${escapedTrigger}\\b`, 'i');
-          if (regex.test(promptLower)) score += trigger.length >= 4 ? 3 : 1.5;
-        }
-      }
-      if (score >= 3) matchedDynamicSkills.push({ skill, score });
-    }
-
-    if (matchedDynamicSkills.length > 0) {
-      matchedDynamicSkills.sort((a, b) => b.score - a.score);
-      console.log(`\n=> 🎯 HIGH-RELEVANCE SELF-EVOLVED SKILL(S) DETECTED:`);
-      matchedDynamicSkills.forEach(({ skill }) => {
-        let displayPath = skill.dirPath;
-        if (displayPath.startsWith(workspaceRoot)) displayPath = path.relative(workspaceRoot, displayPath);
-        console.log(`- ${displayPath}/SKILL.md (${skill.description} [DYNAMIC SKILL])`);
-      });
-    } else if (recommendedGuides.length === 0 && allDynamicSkills.length > 0) {
-      console.log(`\n=> ℹ️ UNMATCHED PROMPT HINT:`);
-      console.log(`No standard or dynamic skills matched your prompt directly.`);
-      console.log(`However, you have ${allDynamicSkills.length} self-evolved dynamic skill(s) registered in your manifest.json.`);
-      console.log(`To ensure you don't miss past lessons, you should inspect the "generated" section of your manifest.json or check .claude/harness-everything/skills/generated/ to see if any apply to your current task.`);
-      console.log(`If genuinely nothing covers this - including nothing already fetched via find-skills - load find-skills/SKILL.md: it checks "npx skills list" for anything already installed, then searches skills.sh/npx skills if not, and always requires explicit approval before installing anything.`);
-    }
-  } catch (err) {
-    // Dynamic-skill discovery is advisory and must never break core routing.
+    const skills = generated.readGeneratedSkills(getWorkspaceRoot(context));
+    return { registered: skills.size, matched: generated.matchGeneratedSkills(promptLower, skills) };
+  } catch (_) {
+    return { registered: 0, matched: [] };
   }
 }
 
@@ -427,34 +372,26 @@ function run(userPrompt, context, options = {}) {
     }
   }
 
-  const allRecommendedGuides = [];
-  for (const group of profileLookup ? [] : routingConfig.guideGroups) {
+  const knowledgeSignals = [];
+  const candidateBindings = [];
+  for (const group of profileLookup ? [] : routingConfig.inputSignalGroups) {
     let matched = false;
     if (typeof group.regex === 'string') {
       matched = new RegExp(group.regex, 'i').test(promptLower);
     } else if (Array.isArray(group.keywords)) {
-      matched = group.keywords.some(keyword => promptLower.includes(keyword));
+      matched = group.keywords.some(keyword => matchKeyword(promptLower, keyword));
+    }
+    if (matched && typeof group.id === 'string') {
+      knowledgeSignals.push(group.id);
+      if (Array.isArray(group.bindings)) candidateBindings.push(...group.bindings.filter(id => typeof id === 'string'));
     }
-    if (matched && Array.isArray(group.guides)) allRecommendedGuides.push(...group.guides);
   }
-  const recommendedGuides = deduplicateGuidesByPath(allRecommendedGuides);
-
-  if (recommendedGuides.length > 0) {
-    console.log(`\n=> RECOMMENDED KNOWLEDGE GUIDES (Auto-loaded based on keywords):`);
-    recommendedGuides.forEach(guide => {
-      const match = guide.match(/^- ([^\s]+)/);
-      if (match) {
-        const guidePath = path.join(__dirname, '..', '..', match[1]);
-        if (!fs.existsSync(guidePath)) {
-          console.log(`${guide} [NOT INSTALLED - Ignore this recommendation]`);
-          return;
-        }
-      }
-      console.log(guide);
-    });
+  if (memoryPersistenceRequested && !knowledgeSignals.includes('memory-persistence')) {
+    knowledgeSignals.push('memory-persistence');
+    candidateBindings.push('self-evolve');
   }
-
-  if (!profileLookup) emitDynamicSkills(promptLower, context, recommendedGuides);
+  const generatedSkills = profileLookup ? { registered: 0, matched: [] } : matchGeneratedSkillIds(promptLower, context);
+  if (generatedSkills.matched.length > 0) knowledgeSignals.push('self-evolved-skill');
 
   const externalClaimTriggers = routingConfig.factAudit.externalClaim || [];
   const estimateTriggers = routingConfig.factAudit.estimate || [];
@@ -495,6 +432,7 @@ function run(userPrompt, context, options = {}) {
     rationale,
     reasonCodes,
     requestedFableModel,
+    knowledgeSignals,
     explicitRequest: {
       fableModel: requestedFableModel,
       strategy: requestedStrategy,
@@ -528,6 +466,19 @@ function run(userPrompt, context, options = {}) {
     },
   });
 
+  if (knowledgeSignals.length > 0) {
+    console.log(`\n=> KNOWLEDGE SIGNALS (STEP INPUT ONLY): ${knowledgeSignals.join(', ')}`);
+    console.log('   These normalized prompt signals help compose requirement steps; they do not select or load documents.');
+    const bindingIds = [...new Set(candidateBindings)];
+    if (bindingIds.length > 0) console.log(`   Candidate step binding ids: ${bindingIds.join(', ')}`);
+  }
+  if (generatedSkills.matched.length > 0) {
+    console.log(`\n=> SELF-EVOLVED SKILL SIGNALS (STEP INPUT ONLY): ${generatedSkills.matched.join(', ')}`);
+    console.log('   Declare a matching id as a step binding; its SKILL.md resolves from the manifest only when that step is active.');
+  } else if (generatedSkills.registered > 0 && knowledgeSignals.length === 0) {
+    console.log(`\n=> SELF-EVOLVED SKILLS REGISTERED: ${generatedSkills.registered} (none matched this prompt; inspect manifest "generated" metadata if a past lesson may apply).`);
+  }
+
   console.log(`\n=> WORKFLOW STRATEGY: ${contract.workflowPlan.strategy || 'deferred'}`);
   if (contract.workflowPlan.memory.write !== 'none') {
     console.log(`=> MEMORY WRITE: ${contract.workflowPlan.memory.write}`);
@@ -586,4 +537,4 @@ if (process.argv[2]) {
   });
 }
 }
-module.exports = { run };
+module.exports = { run, splitProfileLookupClauses, isFableProfileLookup, containsOnlyLookupTerms, detectFableModel };

package/hooks/scripts/contract-test.js

@@ -39,16 +39,26 @@ function resultState(payload) {
   return { failed, exitCode, evidence };
 }
 
+function unresolvedBindings(contract) {
+  const bindings = [...(contract.requiredBindings || []), ...(contract.optionalBindings || [])];
+  return bindings.filter(binding => binding.required !== false
+    ? binding.status !== 'loaded'
+    : !['loaded', 'not-needed'].includes(binding.status));
+}
+
 function updateRunContract(entry, payload, command, sessionId) {
   const { failed, exitCode, evidence } = resultState(payload);
+  const unresolved = unresolvedBindings(entry.contract);
+  const status = failed ? 'fail' : unresolved.length ? 'binding-unresolved' : 'pass';
   const observedAt = new Date().toISOString();
   const contract = {
     ...entry.contract,
     workerId: entry.contract.workerId || getWorkerId(payload),
-    status: failed ? 'fail' : 'pass',
+    status,
     lastObservedCommand: command,
     lastObservedExitCode: exitCode ?? null,
     evidence,
+    unresolvedBindings: unresolved.map(binding => binding.id),
     verifiedAt: observedAt,
     updatedAt: observedAt,
   };
@@ -63,7 +73,9 @@ function updateRunContract(entry, payload, command, sessionId) {
     sessionId: sessionId || contract.sessionId || null,
     workerId: contract.workerId || null,
     checkCommand: command,
-    status: failed ? 'fail' : 'pass',
+    status,
+    checkStatus: failed ? 'fail' : 'pass',
+    unresolvedBindings: unresolved.map(binding => binding.id),
     exitCode: exitCode ?? null,
     evidence,
     observedAt,
@@ -72,6 +84,15 @@ function updateRunContract(entry, payload, command, sessionId) {
   return contract;
 }
 
+function activeFableStages(runRoot) {
+  for (const relative of ['../../fable-mode/scripts/workflow-plan-consumer.js', '../../skills/fable-mode/scripts/workflow-plan-consumer.js']) {
+    const file = path.resolve(__dirname, relative);
+    if (!fs.existsSync(file)) continue;
+    try { return require(file).activeStageBindings(runRoot); } catch (_) { return []; }
+  }
+  return [];
+}
+
 function resolveLegacyContract(stateRoot, command, payload) {
   const contractsDir = path.join(stateRoot, 'contracts');
   let files = [];
@@ -110,7 +131,7 @@ process.stdin.on('end', () => {
     const workflowContext = loadWorkflow(payload);
     const activeRun = workflowContext.workflow?.workflowId ? matchingRun(workflowContext) : null;
     const runMatches = listRunContracts(stateRoot).filter(({ contract }) =>
-      (contract.workflowId ? ['pending', 'planned', 'running', 'fail', 'pass'] : ['pending', 'planned', 'running']).includes(contract.status) && commandMatches(contract, command) &&
+      (contract.workflowId ? ['pending', 'planned', 'running', 'fail', 'pass', 'binding-unresolved'] : ['pending', 'planned', 'running', 'fail', 'binding-unresolved']).includes(contract.status) && commandMatches(contract, command) &&
       (!workflowContext.workflow?.workflowId || (activeRun && contract.runId === activeRun.run.runId && contract.sessionId === sessionId))
     );
 
@@ -163,6 +184,11 @@ process.stdin.on('end', () => {
         }
       }
       console.log(`[Contract Test] ${contract.planId}/${contract.runId}/${contract.stageId}: ${contract.status.toUpperCase()} ${contract.checkCommand}`);
+      if (contract.status === 'binding-unresolved') {
+        console.error(`Resolve declared stage bindings before this stage can pass: ${contract.unresolvedBindings.join(', ')}`);
+      }
+      const activeStages = activeFableStages(entry.runRoot);
+      if (activeStages.length) console.log('[Contract Test] Active stage bindings: ' + JSON.stringify(activeStages));
       if (contract.status === 'fail') {
         console.error(`Evidence: ${contract.evidence || '(no output captured)'}`);
         console.error(`Review this failed stage before relying on its output. Artifact: ${contract.outputPath || '(no path recorded)'}`);

package/hooks/scripts/lib/binding-resolver.js

@@ -0,0 +1,76 @@
+'use strict';
+
+// Resolves a declared step/stage binding to a real, readable file. A binding
+// path is availability evidence only after it resolves under the workspace or
+// an installed Harness skill root; path syntax alone proves nothing.
+const fs = require('fs');
+const path = require('path');
+
+function loadGeneratedSkills() {
+  const file = path.resolve(__dirname, '..', '..', '..', 'scripts', 'lib', 'generated-skills.js');
+  return fs.existsSync(file) ? require(file) : null;
+}
+
+// Source checkout and Claude plugin keep skills at the package root; the
+// Codex plugin keeps them under skills/. Host-provided plugin roots win.
+function packageRoots() {
+  const packageRoot = path.resolve(__dirname, '..', '..', '..');
+  const roots = [];
+  for (const root of [process.env.CLAUDE_PLUGIN_ROOT, process.env.PLUGIN_ROOT, packageRoot]) {
+    if (!root) continue;
+    roots.push(path.resolve(root), path.resolve(root, 'skills'));
+  }
+  return [...new Set(roots)];
+}
+
+function readableFile(file) {
+  try {
+    if (!fs.statSync(file).isFile()) return false;
+    fs.accessSync(file, fs.constants.R_OK);
+    return true;
+  } catch (_) {
+    return false;
+  }
+}
+
+// Registered Harness bindings and the path each one loads.
+const PACKAGED_BINDING_PATHS = {
+  tdd: 'tdd/SKILL.md',
+  'verification-loop': 'verification-loop/SKILL.md',
+  'git-commit': 'git-commit/SKILL.md',
+  'security-review': 'security-review/SKILL.md',
+  'review-guidance': 'harness-everything/references/triage-and-tiers.md',
+};
+const SKILL_ID = /^[a-z0-9][a-z0-9-]{0,63}$/;
+
+// Only a recognized Harness binding may search installation roots: a
+// registered id at its registered path, or a skill id naming its own
+// `<id>/SKILL.md`. Any other path is a workspace reference and must never
+// resolve to an unrelated file that happens to exist in the Harness package.
+function isPackagedBinding(binding) {
+  if (!binding.path) return false;
+  if (PACKAGED_BINDING_PATHS[binding.id]) return PACKAGED_BINDING_PATHS[binding.id] === binding.path;
+  return SKILL_ID.test(binding.id || '') && binding.path === `${binding.id}/SKILL.md`;
+}
+
+// Returns { availability, file }: `available` with an absolute readable file,
+// `missing` when a declared path resolves nowhere, or `unknown` when neither a
+// path nor a registered generated skill names a location.
+function resolveBinding(binding, workspaceRoot) {
+  const roots = isPackagedBinding(binding) ? [...packageRoots(), workspaceRoot] : [workspaceRoot];
+  if (binding.path) {
+    for (const root of roots.filter(Boolean)) {
+      const file = path.resolve(root, binding.path);
+      if (readableFile(file)) return { availability: 'available', file };
+    }
+    return { availability: 'missing', file: null };
+  }
+  const generated = loadGeneratedSkills()?.findGeneratedSkill(binding.id, workspaceRoot);
+  if (generated) {
+    const file = path.join(generated.dirPath, 'SKILL.md');
+    return readableFile(file) ? { availability: 'available', file } : { availability: 'missing', file: null };
+  }
+  return { availability: 'unknown', file: null };
+}
+
+module.exports = { resolveBinding, packageRoots, isPackagedBinding, PACKAGED_BINDING_PATHS };

package/hooks/scripts/lib/fable-contracts.js

@@ -102,7 +102,7 @@ function stagesForChangedPath(filePath, contractEntries) {
 
 function getActiveRunContracts(stateRoot, sessionId) {
   return listRunContracts(stateRoot).filter(({ contract }) => {
-    if (!['pending', 'planned', 'running'].includes(contract.status)) return false;
+    if (!['pending', 'planned', 'running', 'fail', 'binding-unresolved'].includes(contract.status)) return false;
     return !sessionId || !contract.sessionId || contract.sessionId === sessionId;
   });
 }

package/hooks/scripts/lib/observations.js

@@ -370,15 +370,16 @@ function routerState(payload) {
   }
 }
 
-function withLock(root, fn) {
+function withLock(root, fn, options = {}) {
   fs.mkdirSync(root, { recursive: true, mode: 0o700 });
   const lock = path.join(root, '.index.lock');
-  const deadline = Date.now() + 2000;
+  const timeoutMs = Number.isFinite(options.timeoutMs) && options.timeoutMs >= 0 ? options.timeoutMs : 2000;
+  const deadline = Date.now() + timeoutMs;
   let fd = null;
   while (fd === null) {
     try { fd = fs.openSync(lock, 'wx'); } catch (_) {
       try { if (Date.now() - fs.statSync(lock).mtimeMs > 5000) fs.unlinkSync(lock); } catch (__) { /* raced */ }
-      if (Date.now() > deadline) return false;
+      if (Date.now() >= deadline) return false;
       const until = Date.now() + 10;
       while (Date.now() < until) { /* short spin; hooks are short-lived */ }
     }
@@ -432,18 +433,88 @@ function sweep(root, now = Date.now()) {
   });
 }
 
-function appendRecord(root, record, text) {
-  return withLock(root, () => {
+function appendRecordDetailed(root, record, text, options = {}) {
+  let outcome = null;
+  const locked = withLock(root, () => {
+    const file = path.join(root, 'observations-index.json');
+    const index = readJson(file, null) || { schemaVersion: 1, kind: 'system-one-observations', records: [] };
+    if (options.dedupeById && index.records.some(existing => existing.id === record.id)) {
+      outcome = 'duplicate';
+      return;
+    }
+    if (options.dedupeByTurn) {
+      const match = observationTurnMatch(index.records, record);
+      if (match) {
+        outcome = match === 'ambiguous-legacy-turn' ? 'ambiguous' : 'duplicate';
+        return;
+      }
+    }
     // The blob is written under the lock, so a concurrent sweep cannot remove it before its record lands.
     const textDir = path.join(root, 'text');
     fs.mkdirSync(textDir, { recursive: true, mode: 0o700 });
-    if (text) fs.writeFileSync(path.join(textDir, `${record.contentSha256}.json`), JSON.stringify(text), { mode: 0o600 });
-    const file = path.join(root, 'observations-index.json');
-    const index = readJson(file, null) || { schemaVersion: 1, kind: 'system-one-observations', records: [] };
+    if (text) fs.writeFileSync(path.join(textDir, record.contentSha256 + '.json'), JSON.stringify(text), { mode: 0o600 });
     index.records.push(record);
     sweepLocked(root, index, Date.now());
     writeJsonAtomic(file, index);
-  });
+    outcome = 'appended';
+  }, { timeoutMs: options.lockTimeoutMs });
+  if (!locked) return { status: 'lock-timeout' };
+  return { status: outcome || 'appended' };
+}
+
+function appendRecord(root, record, text, options = {}) {
+  return appendRecordDetailed(root, record, text, options).status === 'appended';
+}
+
+function observationTurnMatch(records, record) {
+  const writer = record && record.writer || {};
+  const sessionId = String(writer.sessionId || '');
+  const turnId = String(writer.turnId || '');
+  if (!sessionId || !record.host) return null;
+  const sameSession = (Array.isArray(records) ? records : []).filter(existing =>
+    existing && existing.host === record.host &&
+    String(existing.writer && existing.writer.sessionId || '') === sessionId
+  );
+  if (!sameSession.length) return null;
+
+  if (turnId && sameSession.some(existing => String(existing.writer && existing.writer.turnId || '') === turnId)) {
+    return 'same-turn-id';
+  }
+
+  // Older live records have no turn ID. Only treat matching ordinal plus text
+  // as a definite duplicate; a partial match is ambiguous and the importer
+  // skips it instead of risking a second training row for the same turn.
+  const legacy = sameSession.filter(existing => existing.captureMethod !== 'session-backfill' &&
+    (!turnId || !String(existing.writer && existing.writer.turnId || '')));
+  if (!legacy.length) return null;
+  const sameTurn = existing => Number.isInteger(existing.turn) && existing.turn === record.turn;
+  const sameText = existing => Boolean(existing.contentSha256 && existing.contentSha256 === record.contentSha256);
+  if (legacy.some(existing => sameTurn(existing) && sameText(existing))) return 'legacy-same-turn';
+  if (legacy.some(existing => sameTurn(existing) || sameText(existing))) return 'ambiguous-legacy-turn';
+  return null;
+}
+
+function findObservationTurnMatch(root, record) {
+  const index = readJson(path.join(root, 'observations-index.json'), null);
+  return observationTurnMatch(index && index.records, record);
+}
+
+function markSessionBackfillBehaviorUnobserved(root, options = {}) {
+  const file = path.join(root, 'observations-index.json');
+  if (!fs.existsSync(file)) return 0;
+  let changed = 0;
+  const locked = withLock(root, () => {
+    const index = readJson(file, null);
+    if (!index || !Array.isArray(index.records)) return;
+    for (const record of index.records) {
+      if (record.captureMethod === 'session-backfill' && record.behavior !== null) {
+        record.behavior = null;
+        changed++;
+      }
+    }
+    if (changed) writeJsonAtomic(file, index);
+  }, { timeoutMs: options.lockTimeoutMs });
+  return locked ? changed : null;
 }
 
 // Tool events are immutable files, one per event, so parallel hooks never
@@ -484,6 +555,7 @@ function startTurn(payload, root) {
   session.turn++;
   session.pending = {
     turn: session.turn,
+    turnId: String(payload.turn_id || payload.turnId || ''),
     startedAt: new Date().toISOString(),
     prompt: redact(typeof payload.prompt === 'string' ? payload.prompt : ''),
     previous: session.lastFinal || '',
@@ -505,6 +577,7 @@ function toolTurn(payload, root, failed, codex) {
 
 function finishPending(session, payload, root, final) {
   const pending = session.pending;
+  const turnId = String(payload.turn_id || payload.turnId || pending.turnId || '');
   const { label, reason } = final.text === null && final.reason ? { label: null, reason: final.reason } : parseLabelLine(final.text);
   const collected = collectEvents(root, payload.session_id, pending.turn);
   const behavior = { ...collected };
@@ -531,7 +604,10 @@ function finishPending(session, payload, root, final) {
     contentSha256,
     host: detectHost(payload, { codex: final.codex || collected._codex }),
     turn: pending.turn,
-    writer: { sessionId: String(payload.session_id || 'unknown') },
+    writer: {
+      sessionId: String(payload.session_id || 'unknown'),
+      ...(turnId ? { turnId } : {}),
+    },
     scope: { taskTerms: normalizeTerms(pending.prompt), requirementTerms: [], roles: [] },
     promptBytes: Buffer.byteLength(pending.prompt, 'utf8'),
     router: routerState(payload),
@@ -575,7 +651,7 @@ function handle(payload, env = process.env) {
 }
 
 module.exports = {
-  INTENTS, TIERS, STRATEGIES, enabled, storeRoot, redact, parseLabelLine, classifyCommand, labelTier, contradictions,
-  normalizeTerms, transcriptMessage, recordTool, emptyBehavior, mergeBehavior, toolFailed, handle, readJson,
+  INTENTS, TIERS, STRATEGIES, RETENTION_MS, PREVIOUS_BYTES, enabled, storeRoot, redact, parseLabelLine, stripLabels, tailBytes, sha, classifyCommand, labelTier, contradictions,
+  normalizeTerms, transcriptMessage, recordTool, emptyBehavior, mergeBehavior, toolFailed, handle, readJson, appendRecord, appendRecordDetailed, observationTurnMatch, findObservationTurnMatch, markSessionBackfillBehaviorUnobserved,
   expired, recordText, sweep,
 };