harness-everything 0.11.6 → 0.12.0

package/plugins/harness-everything/hooks/scripts/lib/workflow-runtime.js

@@ -162,6 +162,23 @@ function settleMutationProbe(context, key, afterFingerprint, tool) {
   });
 }
 
+function settleMutationProbeConservative(context, key, tool, evidence = 'unobservable-workspace') {
+  return withMutationProbeLock(context, () => {
+    const file = mutationProbeFile(context, key);
+    const probe = readJson(file);
+    if (!probe || probe.schemaVersion !== 1) return null;
+    refreshWorkflowForProbe(context);
+    fs.unlinkSync(file);
+    context.workflow.lastMutationAt = Date.now();
+    if (probe.reserveIteration && context.workflow.strategy === 'iterative-single') {
+      recordBudgetEvent(context, 'iteration', { evidence: String(tool || 'shell') + ':' + evidence });
+    } else {
+      saveWorkflow(context);
+    }
+    return { changed: true, probe, conservative: true };
+  });
+}
+
 function discardMutationProbe(context, key) {
   return withMutationProbeLock(context, () => {
     const file = mutationProbeFile(context, key);
@@ -396,4 +413,4 @@ function readHookInput(decide) {
   process.stdin.on('error', finish);
 }
 
-module.exports = { OPEN_STATES, SAFE_ID, WORKFLOW_CONTROLLER_COMMANDS, isMajorWorkflow, loadWorkflow, saveWorkflow, budgetLimits, ensureWorkflowBudget, mutationProbeReservations, assertIterationCapacity, registerMutationProbe, peekMutationProbe, settleMutationProbe, discardMutationProbe, clearMutationProbes, recordBudgetEvent, resetWorkflowBudget, syncBudgetToRun, matchingRun, unresolvedStages, readHookInput };
+module.exports = { OPEN_STATES, SAFE_ID, WORKFLOW_CONTROLLER_COMMANDS, isMajorWorkflow, loadWorkflow, saveWorkflow, budgetLimits, ensureWorkflowBudget, mutationProbeReservations, assertIterationCapacity, registerMutationProbe, peekMutationProbe, settleMutationProbe, settleMutationProbeConservative, discardMutationProbe, clearMutationProbes, recordBudgetEvent, resetWorkflowBudget, syncBudgetToRun, matchingRun, unresolvedStages, readHookInput };

package/plugins/harness-everything/hooks/scripts/rule-of-3-tracker.js

@@ -17,6 +17,7 @@ process.stdin.on('end', () => {
     const payload = JSON.parse(inputData);
     const hookEventName = payload.hook_event_name || payload.hookEventName || '';
     const isFailureEvent = hookEventName === 'PostToolUseFailure';
+    const isSuccessEvent = hookEventName === 'PostToolUse';
     const toolResponse = payload.tool_response || {};
     const stdout = toolResponse.stdout ?? payload.stdout ?? '';
     const stderr = toolResponse.stderr ?? payload.stderr ?? '';
@@ -25,10 +26,10 @@ process.stdin.on('end', () => {
     const exitCode = typeof rawExitCode === 'number' ? rawExitCode : undefined;
 
     const explicitFailure = exitCode !== undefined && exitCode !== 0;
-    const explicitSuccess = exitCode === 0;
     const stderrSignal = typeof stderr === 'string' && stderr.trim().length > 0;
     const looksLikeError = /\b(error|fail|failed|failure|exception|fatal|panic|traceback|denied|refused|cannot|unable)\b/i.test(stderr);
-    const isFailure = isFailureEvent || explicitFailure || (exitCode === undefined && stderrSignal && looksLikeError);
+    const isFailure = isFailureEvent || explicitFailure ||
+      (!isSuccessEvent && exitCode === undefined && stderrSignal && looksLikeError);
     const errorText = isFailureEvent
       ? (failureText || (stderrSignal ? stderr : stdout) || '')
       : ((stderrSignal ? stderr : stdout) || failureText || '');
@@ -47,19 +48,22 @@ process.stdin.on('end', () => {
       const filePath = payload.tool_input?.file_path || payload.tool_input?.filePath || '';
       const command = payload.tool_input?.command || '';
 
-      // Categorize failure type for context-aware thresholds
+      // Categorize failure type for context-aware thresholds.
+      // NOTE (#167): match anchored diagnostic phrases, not bare substrings.
+      // A bare `denied`/`timeout` substring matches file names such as
+      // `workflow-mutation-denied.js` and misclassifies the failure.
       let category = 'unknown';
-      if (/SyntaxError|Unexpected token|Syntax Error/i.test(errorText)) {
+      if (/\bSyntaxError\b|Unexpected token|Syntax Error/i.test(errorText)) {
         category = 'syntax';
-      } else if (/ENOENT|not found|No such file|找不到|不存在/i.test(errorText)) {
+      } else if (/\bENOENT\b|\bnot found\b|No such file|找不到|不存在/i.test(errorText)) {
         category = 'environment';
-      } else if (/timeout|timed out|超時|逾時/i.test(errorText)) {
+      } else if (/\bETIMEDOUT\b|TimeoutError|\btimeout\b|\btimed out\b|\btiming out\b|超時|逾時/i.test(errorText)) {
         category = 'timeout';
       } else if (/test.*fail|assertion|AssertionError|測試.*失敗|斷言.*錯誤/i.test(errorText)) {
         category = 'test';
-      } else if (/permission|denied|EACCES|權限/i.test(errorText)) {
+      } else if (/\bpermission denied\b|\bEACCES\b|\bEPERM\b|權限.*(拒絕|不足|被拒)|拒絕.*權限/i.test(errorText)) {
         category = 'permission';
-      } else if (/dependency|module not found|Cannot find module|模組.*找不到/i.test(errorText)) {
+      } else if (/\bdependency\b|\bmodule not found\b|Cannot find module|模組.*找不到/i.test(errorText)) {
         category = 'dependency';
       }
 
@@ -114,7 +118,11 @@ process.stdin.on('end', () => {
       state.lastFailureAt = Date.now();
 
       fs.writeFileSync(stateFile, JSON.stringify(state, null, 2), 'utf8');
-    } else if (!isFailureEvent && explicitSuccess) {
+    } else if (!isFailure) {
+      // NOTE (#166, follows #153): Claude Code PostToolUse success payloads
+      // carry no numeric exit code. The lifecycle event is authoritative:
+      // PostToolUse is success unless a numeric non-zero status contradicts it;
+      // hosts without lifecycle event names keep the conservative stderr fallback.
       // A successful action after an accepted zoom-out is an objective recovery
       // boundary. Emit only IDs/hashes/category; never copy command/output text.
       if ((state.zoomOutCycles || 0) > 0 && state.lastHash) {

package/plugins/harness-everything/hooks/scripts/state-persist.js

@@ -2,8 +2,8 @@
 const fs = require('fs');
 const path = require('path');
 const { getWorkspaceRoot, getSessionDir } = require('./lib/harness-state');
-const { loadWorkflow, saveWorkflow, peekMutationProbe, settleMutationProbe } = require('./lib/workflow-runtime');
-const { cwdOf, shellProbeKey, workspaceFingerprint } = require('./lib/workflow-isolation');
+const { loadWorkflow, saveWorkflow, isMajorWorkflow, peekMutationProbe, settleMutationProbe, settleMutationProbeConservative } = require('./lib/workflow-runtime');
+const { cwdOf, shellProbeKey, workspaceFingerprint, directMutationInWorkspace } = require('./lib/workflow-isolation');
 const { observeTool } = require('./lib/telemetry');
 
 // Commands that count as "verification ran" for the Stop gate
@@ -42,6 +42,10 @@ function observeWorkspaceMutation(payload, root) {
   try {
     after = workspaceFingerprint(cwd);
   } catch (error) {
+    if (!isMajorWorkflow(context.workflow)) {
+      const conservative = settleMutationProbeConservative(context, probeKey, toolName, 'unobservable-workspace');
+      return Boolean(conservative && conservative.changed);
+    }
     context.workflow.state = 'blocked';
     context.workflow.blockReason = 'mutation-observation-failed';
     saveWorkflow(context);
@@ -79,9 +83,10 @@ function processState(payload) {
       const exitCode = typeof rawExitCode === 'number' ? rawExitCode : undefined;
       const stderrSignal = typeof stderr === 'string' && stderr.trim().length > 0;
       const hookEvent = payload.hook_event_name || payload.hookEventName || '';
+      const isSuccessEvent = hookEvent === 'PostToolUse';
       const isFailed = hookEvent === 'PostToolUseFailure' ||
         (exitCode !== undefined && exitCode !== 0) ||
-        (exitCode === undefined && stderrSignal);
+        (!isSuccessEvent && exitCode === undefined && stderrSignal);
       const toolName = payload.tool_name || payload.tool || 'command';
       const observedMutation = observeWorkspaceMutation(payload, root);
 
@@ -97,8 +102,13 @@ function processState(payload) {
         state.tool = toolName;
         state.exitCode = exitCode;
         state.errorSummary = output.trim();
-      } else if (exitCode === 0 && state.status === 'failed') {
-        // Clear failed state or mark as idle/resolved
+      } else if (!isFailed && state.status === 'failed') {
+        // Clear failed state or mark as idle/resolved.
+        // NOTE (#166, follows #153): Claude Code Bash PostToolUse payloads
+        // carry no numeric exit code, so `exitCode === 0` never holds there.
+        // A PostToolUse event with no numeric non-zero exit status counts as
+        // success even when stderr contains diagnostics. Hosts that omit the
+        // lifecycle event name retain the conservative stderr fallback.
         state.lastResolved = { tool: state.tool, timestamp: state.timestamp };
         state.status = 'idle';
         state.timestamp = new Date().toISOString();
@@ -107,8 +117,10 @@ function processState(payload) {
       }
 
       // Milestones for the Stop gate: when did the last mutation happen, and
-      // has any verification-ish command succeeded since.
-      if (toolName === 'Edit' || toolName === 'Write' || toolName === 'apply_patch' || observedMutation) {
+      // has any verification-ish command succeeded since. Direct-tool edits
+      // outside the workspace advance neither milestone (#165).
+      const isDirectTool = toolName === 'Edit' || toolName === 'Write' || toolName === 'apply_patch';
+      if ((isDirectTool && directMutationInWorkspace(payload, cwdOf(payload, root), root)) || observedMutation) {
         state.lastEditAt = Date.now();
       }
       if ((toolName === 'Bash' || toolName === 'PowerShell') && !isFailed) {

package/plugins/harness-everything/hooks/scripts/workflow-disposition.js

@@ -3,7 +3,7 @@
 
 const fs = require('fs');
 const path = require('path');
-const { loadWorkflow, saveWorkflow, matchingRun, OPEN_STATES, ensureWorkflowBudget, recordBudgetEvent, resetWorkflowBudget, syncBudgetToRun, WORKFLOW_CONTROLLER_COMMANDS } = require('./lib/workflow-runtime');
+const { loadWorkflow, saveWorkflow, matchingRun, OPEN_STATES, budgetLimits, ensureWorkflowBudget, recordBudgetEvent, resetWorkflowBudget, syncBudgetToRun, WORKFLOW_CONTROLLER_COMMANDS } = require('./lib/workflow-runtime');
 const { getWorkspaceRoot, readCurrentSession } = require('./lib/harness-state');
 const { atomicWriteJson, readJson } = require('./lib/fable-contracts');
 
@@ -32,6 +32,20 @@ function consumer() {
   throw new Error('Fable consumer unavailable');
 }
 
+function activatePlan(workflow, plan) {
+  workflow.workflowPlan = plan;
+  workflow.strategy = plan.strategy;
+  workflow.strategySelection = plan.strategySelection;
+  workflow.tier = plan.tier;
+  workflow.requiredInvariants = plan.requiredInvariants || [];
+  workflow.suggestedSkills = plan.suggestedSkills || [];
+  workflow.verification = plan.verification;
+  workflow.mutationIsolation = plan.mutationIsolation || { required: false };
+  const budget = ensureWorkflowBudget(workflow);
+  budget.limits = budgetLimits(workflow);
+  budget.updatedAt = new Date().toISOString();
+}
+
 function main() {
   const args = parseArgs(process.argv.slice(2));
   if (!WORKFLOW_CONTROLLER_COMMANDS.has(args.command)) throw new Error(usage());
@@ -47,10 +61,12 @@ function main() {
     if (isReplan) recordBudgetEvent(context, 'replan', { evidence: 'workflow-disposition:start' });
     const plan = workflow.pendingPlan || workflow.workflowPlan;
     if (!String(plan.strategy || '').startsWith('fable-')) {
+      activatePlan(workflow, plan);
       workflow.revision++;
       workflow.state = 'running';
+      workflow.escapes = [];
+      delete workflow.pendingPlan;
       delete workflow.blockReason;
-      ensureWorkflowBudget(workflow);
       saveWorkflow(context);
       process.stdout.write(JSON.stringify({ state: workflow.state, workflowId: workflow.workflowId, revision: workflow.revision }) + '\n');
       return;
@@ -66,18 +82,13 @@ function main() {
       routerContract: { workflowPlan: plan }, stages, workspaceRoot: context.root,
       sessionId, workflowId: workflow.workflowId,
     });
-    workflow.workflowPlan = plan;
-    workflow.strategy = plan.strategy;
-    workflow.tier = plan.tier;
-    workflow.verification = plan.verification;
-    workflow.mutationIsolation = plan.mutationIsolation || workflow.mutationIsolation;
+    activatePlan(workflow, plan);
     workflow.runId = run.runId;
     workflow.revision++;
     workflow.state = 'running';
     workflow.escapes = [];
     delete workflow.pendingPlan;
     delete workflow.blockReason;
-    ensureWorkflowBudget(workflow);
   } else if (args.command === 'revision') {
     recordBudgetEvent(context, 'revision', { evidence: args.evidence || 'workflow-disposition:revision' });
   } else if (args.command === 'reset-budget') {

package/plugins/harness-everything/hooks/scripts/workflow-gate.js

@@ -4,7 +4,7 @@
 const path = require('path');
 const fs = require('fs');
 const { loadWorkflow, saveWorkflow, isMajorWorkflow, matchingRun, registerMutationProbe, recordBudgetEvent, readHookInput, WORKFLOW_CONTROLLER_COMMANDS } = require('./lib/workflow-runtime');
-const { key, classifyShell, workspaceFingerprint, shellProbeKey, cwdOf, commandOf, mutationPaths, linkedWorktree, assertTargets, assertShellScope } = require('./lib/workflow-isolation');
+const { key, classifyShell, workspaceFingerprint, shellProbeKey, cwdOf, commandOf, mutationPaths, directMutationInWorkspace, linkedWorktree, assertTargets, assertShellScope } = require('./lib/workflow-isolation');
 
 const DIRECT = new Set(['Edit', 'Write', 'apply_patch']);
 const SHELL = new Set(['Bash', 'PowerShell', 'exec_command']);
@@ -48,6 +48,10 @@ function decide(payload) {
     throw new Error('selected Fable workflow has no correlated run. Write workflow-stages.json at the displayed session path, then use workflow-disposition.js start.');
   }
   if (DIRECT.has(tool)) {
+    // Bookkeeping outside the workspace (scratchpad, memory files, temp
+    // notes) is not a workspace mutation: it consumes no Tier-2 iteration
+    // and advances no mutation milestone (#165).
+    if (!directMutationInWorkspace(payload, cwd, root)) return;
     if (workflow.strategy === 'iterative-single') {
       recordBudgetEvent(context, 'iteration', { evidence: `${tool}:direct-mutation` });
     }
@@ -58,9 +62,22 @@ function decide(payload) {
 
   // Shell safety and shell mutation accounting are intentionally separate.
   // `untrusted` means "not proven read-only", not "a mutation occurred".
-  // Capture an opaque pre-execution workspace fingerprint; the post-tool
-  // observer consumes an iteration only when workspace content actually changed.
-  const fingerprint = workspaceFingerprint(cwd);
+  // Capture an opaque pre-execution workspace fingerprint when possible. A
+  // non-major workflow may run outside Git, where mutation observation is an
+  // accounting aid rather than an isolation boundary; degrade conservatively
+  // instead of blocking the user's command (#162).
+  let fingerprint;
+  try {
+    fingerprint = workspaceFingerprint(cwd);
+  } catch (error) {
+    if (isMajorWorkflow(workflow)) throw error;
+    if (workflow.strategy === 'iterative-single') {
+      recordBudgetEvent(context, 'iteration', { evidence: 'shell:unobservable-workspace' });
+    }
+    workflow.lastMutationAt = Date.now();
+    saveWorkflow(context);
+    return;
+  }
   const probeKey = shellProbeKey(payload, cwd);
   registerMutationProbe(context, probeKey, fingerprint, workflow.strategy === 'iterative-single');
 }

package/plugins/harness-everything/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "harness-everything",
-  "version": "0.11.6",
+  "version": "0.12.0",
   "description": "Invariant-first engineering harness for routing, verification, and failure recovery while preserving agent autonomy.",
   "author": {
     "name": "Miya Daniel",

package/plugins/harness-everything/skills/grill-with-docs/ADR-FORMAT.md

@@ -22,6 +22,28 @@ Only include these when they add genuine value. Most ADRs won't need them.
 - **Considered Options** — only when the rejected alternatives are worth remembering
 - **Consequences** — only when non-obvious downstream effects need to be called out
 
+## Decision lifecycle and contract lineage
+
+Once an ADR is **accepted**, keep its decision and rationale historically stable. Do not rewrite an accepted ADR to make a later design look as though it was always the decision.
+
+Use compact metadata when the ADR participates in a behavior contract:
+
+```md
+ADR-ID: ADR-0001
+Status: proposed | accepted | deprecated | superseded by ADR-0002
+Affected requirements: REQ-001, REQ-004
+```
+
+When a later change materially changes the decision or its rationale:
+
+1. create a new sequential ADR;
+2. state the new decision and why the prior trade-off changed;
+3. mark the earlier ADR `superseded by ADR-NNNN`;
+4. update the living spec requirements affected by that decision;
+5. let the structured contract trace carry detailed ticket/test/implementation lineage.
+
+A ticket or implementation note never silently becomes the new architectural source of truth. If only implementation changes and the approved behavior/decision does not, keep the accepted ADR unchanged.
+
 ## Numbering
 
 Scan `docs/adr/` for the highest existing number and increment by one.

package/plugins/harness-everything/skills/grill-with-docs/SKILL.md

@@ -4,7 +4,7 @@ description: Challenge the plan against the existing domain model, sharpen termi
 license: Apache-2.0
 metadata:
   author: Miya Daniel
-  version: 0.4.0
+  version: 0.12.0
 ---
 
 # Grill With Docs (Domain Modeling & Architectural Alignment)

package/plugins/harness-everything/skills/harness-everything/SKILL.md

@@ -4,7 +4,7 @@ description: "Route software/project work through the Harness kernel: classify T
 license: Apache-2.0
 metadata:
   author: Miya Daniel
-  version: 0.11.2
+  version: 0.11.7
 ---
 
 # Harness Everything

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

@@ -33,12 +33,26 @@ function issueMemoryCapability(workflow) {
   return token;
 }
 
+// Host-generated background-task notifications arrive as UserPromptSubmit
+// hook payloads but are not user input (#168). Routing them like prompts
+// replaces the workflow contract mid-turn (e.g. deferred -> a new Tier-2).
+// A prompt that is entirely a notification envelope must never create or
+// replace a workflow; the current contract is kept unchanged.
+function isHostNotificationPrompt(prompt) {
+  const text = String(prompt || '').trim();
+  if (!text) return false;
+  return /^<task-notification[\s>][\s\S]*<\/task-notification>\s*$/i.test(text);
+}
+
 function persistWorkflow(plan, payload, prompt) {
   if (!payload || !(payload.session_id || payload.sessionId)) return null;
   const { runtime, hooksRoot } = loadRuntime();
   const context = runtime.loadWorkflow(payload);
   const { writeCurrentSession } = require(path.join(hooksRoot, 'lib/harness-state'));
   writeCurrentSession(context.root, context.sessionId);
+  if (isHostNotificationPrompt(prompt)) {
+    return { ...context, hooksRoot, retained: true, hostNotification: true };
+  }
   if (context.workflow && runtime.OPEN_STATES.has(context.workflow.state)) {
     if (!context.workflow.workflowPlan) throw new Error('legacy unresolved workflow needs explicit migration; refusing to replace its obligations');
     // Steering/status prompts cannot drop an unresolved execution contract.
@@ -92,17 +106,30 @@ function run(raw) {
     try { payload = JSON.parse(raw); } catch (_) { console.error('[Workflow Router] Invalid hook payload; lifecycle persistence unavailable.'); }
   }
   const prompt = promptArg || (typeof payload?.prompt === 'string' ? payload.prompt : '');
-  const result = core.route(promptArg, raw || null);
-  let plan = result.contract.workflowPlan;
+  const hostNotification = isHostNotificationPrompt(prompt);
+  // Host-generated notifications are lifecycle events, not user-authored task
+  // input. Never feed their text into the router: when there is an active
+  // contract we retain it below; when there is none, the event is a no-op.
+  const result = hostNotification ? null : core.route(promptArg, raw || null);
+  let plan = result?.contract?.workflowPlan || null;
   let persisted = null;
   let failure = null;
   try {
     persisted = persistWorkflow(plan, payload, prompt);
-    if (persisted?.retained) plan = persisted.workflow.workflowPlan;
+    if (persisted?.retained && persisted.workflow) plan = persisted.workflow.workflowPlan;
   } catch (error) { failure = error; }
-  if (result.sanitized) console.log(result.sanitized);
-  if (result.stderr) process.stderr.write(result.stderr);
-  if (persisted?.retained) console.log('\n=> Retaining unresolved workflow from earlier prompts; the checkpoint below is the active execution contract.');
+  if (hostNotification && !persisted?.workflow) {
+    console.log('\n=> Host notification — no active execution contract; ignored for routing.');
+    if (failure) {
+      console.error('[Workflow Router] ' + failure.message);
+      process.exitCode = 2;
+    }
+    return;
+  }
+  if (result?.sanitized) console.log(result.sanitized);
+  if (result?.stderr) process.stderr.write(result.stderr);
+  if (persisted?.hostNotification) console.log('\n=> Host notification — routing unchanged; keeping the active execution contract.');
+  else if (persisted?.retained) console.log('\n=> Retaining unresolved workflow from earlier prompts; the checkpoint below is the active execution contract.');
   core.printWorkflowPlan(plan);
   core.printRoutingCheckpoint(plan);
   core.printKernelContract(plan);
@@ -116,7 +143,7 @@ function run(raw) {
     console.log('   - Tier 3 / Fable source and artifact mutations require Git worktree isolation; unavailable isolation means BLOCKED.');
     console.log('   - Escape is limited to workflow-uncovered-scope or host-capability-unavailable, with stage, scope and evidence; other obligations remain mandatory.');
   }
-  if (persisted) {
+  if (persisted?.workflow) {
     const controller = path.join(persisted.hooksRoot, 'workflow-disposition.js');
     console.log('   - Workflow id: ' + persisted.workflow.workflowId);
     console.log('   - Memory write disposition: ' + (persisted.workflow.workflowPlan.memory?.write || 'none'));
@@ -130,12 +157,13 @@ function run(raw) {
   if (failure) {
     console.error('[Workflow Router] ' + failure.message);
     process.exitCode = 2;
-  } else if (result.status !== 0) process.exitCode = result.status || 1;
+  } else if (result && result.status !== 0) process.exitCode = result.status || 1;
 }
 
+if (typeof module !== 'undefined') module.exports = { isHostNotificationPrompt };
+
 if (process.argv.length > 2 || process.stdin.isTTY) run('');
-else {
-  let input = '';
+else {  let input = '';
   let finished = false;
   const finish = () => { if (finished) return; finished = true; clearTimeout(timeout); run(input); };
   const timeout = setTimeout(finish, 500);

package/plugins/harness-everything/skills/multi-agent-workspace/SKILL.md

@@ -4,7 +4,7 @@ description: "Scaffold a verified multi-agent workspace and select bounded speci
 license: Apache-2.0
 metadata:
   author: Miya Daniel
-  version: 0.10.0
+  version: 0.12.0
 ---
 
 # Multi-Agent Workspace

package/plugins/harness-everything/skills/multi-agent-workspace/scripts/index_memory.js

@@ -5,6 +5,18 @@ const fs = require('fs');
 const path = require('path');
 const { getWorkspaceRoot, getRuntimeRoot, resolveProjectDocs } = require('./project-docs-resolver');
 
+let emitLessonTelemetry = () => ({ ok: false, unavailable: true });
+for (const relative of [
+  '../../hooks/scripts/lib/telemetry.js',
+  '../../../hooks/scripts/lib/telemetry.js',
+]) {
+  const candidate = path.resolve(__dirname, relative);
+  if (fs.existsSync(candidate)) {
+    ({ emitLessonTelemetry } = require(candidate));
+    break;
+  }
+}
+
 function option(args, ...names) {
   for (const name of names) {
     const index = args.indexOf(name);
@@ -166,6 +178,22 @@ function retrieveMemoryRecords({ workspace, task = '', requirement = '', role =
     });
   }
 
+  for (const record of included) {
+    if (!record.origin?.lessonCandidateId) continue;
+    emitLessonTelemetry({
+      event: 'lesson_retrieved',
+      root,
+      sessionId: record.writer?.sessionId || null,
+      candidateId: record.origin.lessonCandidateId,
+      observedAt: new Date(nowMs).toISOString(),
+      status: 'success',
+      reasonCodes: [
+        'scoped-memory-retrieval',
+        ...(record.retrieval?.reasonCodes || []),
+      ],
+    });
+  }
+
   return {
     schemaVersion: 1,
     workspace: root,

package/plugins/harness-everything/skills/self-evolve/SKILL.md

@@ -4,7 +4,7 @@ description: "Extract root causes from resolved problems and persist them as def
 license: Apache-2.0
 metadata:
   author: Miya Daniel
-  version: 0.11.0
+  version: 0.12.0
 ---
 
 # Self-evolve

package/plugins/harness-everything/skills/self-evolve/scripts/lesson-candidate.js

@@ -6,6 +6,18 @@ const path = require('path');
 const { spawnSync } = require('child_process');
 const { contentHash, scoreRuleQuality, screenMemoryForPersistence } = require('./persist-memory');
 
+let emitLessonTelemetry = () => ({ ok: false, unavailable: true });
+for (const relative of [
+  '../../hooks/scripts/lib/telemetry.js',
+  '../../../hooks/scripts/lib/telemetry.js',
+]) {
+  const candidate = path.resolve(__dirname, relative);
+  if (fs.existsSync(candidate)) {
+    ({ emitLessonTelemetry } = require(candidate));
+    break;
+  }
+}
+
 let getWorkspaceRoot;
 let getWorkspaceStateDir;
 try {
@@ -69,6 +81,24 @@ function pushState(candidate, state, reasonCode, evidenceRef = null) {
   }].slice(-32);
 }
 
+function emitCandidateLifecycle(input, candidate, event, state, status = 'unknown') {
+  const history = [...(candidate.history || [])].reverse().find(item => item.state === state);
+  const reasonCodes = [
+    history && history.reasonCode,
+    candidate.trigger && candidate.trigger.type ? `trigger:${candidate.trigger.type}` : null,
+    ...(candidate.evaluation && Array.isArray(candidate.evaluation.reasonCodes) ? candidate.evaluation.reasonCodes : []),
+  ].filter(Boolean);
+  return emitLessonTelemetry({
+    event,
+    root: input.workspace,
+    sessionId: input.sessionId || (candidate.provenance && candidate.provenance.sessionId),
+    candidateId: candidate.candidateId,
+    observedAt: history && history.observedAt,
+    status,
+    reasonCodes,
+  });
+}
+
 function replayability(candidate) {
   if (candidate.trigger?.type === 'verifier-fail-pass' &&
       candidate.evidence?.previousStatus === 'fail' &&
@@ -134,6 +164,8 @@ function evaluateCandidate(input) {
     };
     pushState(candidate, 'rejected', 'candidate-screening-or-quality-failed');
     atomicWriteJson(file, candidate);
+    emitCandidateLifecycle(input, candidate, 'lesson_screened', 'screened', screening.allowed ? 'success' : 'failure');
+    emitCandidateLifecycle(input, candidate, 'lesson_rejected', 'rejected', 'failure');
     return { file, candidate };
   }
 
@@ -150,6 +182,15 @@ function evaluateCandidate(input) {
   pushState(candidate, 'evaluated', replay.reasonCode);
   pushState(candidate, disposition, disposition === 'accepted' ? 'eligible-for-governed-promotion' : 'paired-or-later-evidence-required');
   atomicWriteJson(file, candidate);
+  emitCandidateLifecycle(input, candidate, 'lesson_screened', 'screened', 'success');
+  emitCandidateLifecycle(input, candidate, 'lesson_evaluated', 'evaluated', 'success');
+  emitCandidateLifecycle(
+    input,
+    candidate,
+    disposition === 'accepted' ? 'lesson_accepted' : 'lesson_inconclusive',
+    disposition,
+    disposition === 'accepted' ? 'success' : 'unknown',
+  );
   return { file, candidate };
 }
 
@@ -212,6 +253,7 @@ function promoteCandidate(input) {
   if (persisted) pushState(candidate, 'persisted', 'accepted-and-authorized-memory-write');
   else pushState(candidate, 'accepted', 'memory-governance-held-as-review-candidate');
   atomicWriteJson(file, candidate);
+  if (persisted) emitCandidateLifecycle(input, candidate, 'lesson_persisted', 'persisted', 'success');
   return { ok: true, exitCode: 0, persisted, stdout: result.stdout, stderr: result.stderr, candidate };
 }
 
@@ -234,6 +276,16 @@ function observeCandidate(input) {
   };
   pushState(candidate, next, `lesson-${next}`, evidenceRef);
   atomicWriteJson(file, candidate);
+  // Retrieval telemetry is emitted by the actual scoped retrieval path so the
+  // funnel measures exposure, not an operator-authored lifecycle annotation.
+  if (next !== 'retrieved') {
+    const event = {
+      validated: 'lesson_validated',
+      regressed: 'lesson_regressed',
+      superseded: 'lesson_superseded',
+    }[next];
+    if (event) emitCandidateLifecycle(input, candidate, event, next, next === 'regressed' ? 'failure' : 'success');
+  }
   return { file, candidate };
 }
 

package/plugins/harness-everything/skills/to-spec/SKILL.md

@@ -4,7 +4,7 @@ description: "Turn the conversation into a written spec — feature PRD, CLI/API
 license: Apache-2.0
 metadata:
   author: Miya Daniel
-  version: 0.4.0
+  version: 0.12.0
 ---
 
 # To Spec

package/plugins/harness-everything/skills/to-spec/references/process.md

@@ -60,6 +60,32 @@ What "confirm" means depends on the shape picked:
 
 Skip this step only if the conversation already pinned down the relevant surface explicitly (e.g. a prior `grill-with-docs` pass already fixed the schema).
 
+## Stable contract identity
+
+When the published artifact is an authoritative behavior contract, every normative requirement must have a stable identity instead of relying on prose position.
+
+Use this compact shape in the selected template:
+
+```md
+## Contract Requirements
+
+### REQ-001 — <short behavior name>
+**Status:** CURRENT
+**Revision:** 1
+**Decision lineage:** ADR-0001 (or `None`)
+<normative behavior and observable acceptance boundary>
+```
+
+Rules:
+
+- Never recycle a `REQ-*` ID for different behavior.
+- Behavior changes increment the requirement revision and update the living spec **before** implementation is accepted.
+- Superseded behavior remains traceable; do not erase the old requirement history merely because a ticket changed.
+- If a ticket is classified `changeImpact: architecture`, publish the new/superseding ADR first and link it from the affected requirement.
+- If the document is informative rather than authoritative, say so explicitly and link the authoritative requirement instead of inventing a parallel source of truth.
+
+The detailed ADR -> spec -> ticket -> test -> implementation lineage belongs in the structured contract trace; keep the human spec concise.
+
 ## Publishing details
 
 Write the doc using the adapted template at the resolved storage path:

package/plugins/harness-everything/skills/to-spec/templates/cli-reference.md

@@ -28,4 +28,18 @@ Every distinct exit code or error response: what triggers it, what the caller sh
 
 Other commands/endpoints this one is commonly paired with, supersedes, or is superseded by.
 
+## Contract Requirements
+
+For every normative behavior this document owns, assign a stable requirement identity:
+
+```md
+### REQ-001 — <short behavior name>
+**Status:** CURRENT
+**Revision:** 1
+**Decision lineage:** ADR-0001 (or None)
+<observable command/API behavior or error contract>
+```
+
+Do not recycle requirement IDs. A changed caller-visible contract increments the revision before implementation completion.
+
 </spec-template>

package/plugins/harness-everything/skills/to-spec/templates/dev-doc.md

@@ -24,4 +24,18 @@ What this decision costs, even though it was the right call.
 
 How this ships (flag, gradual, all-at-once) and how to undo it if it's wrong.
 
+## Contract Requirements
+
+If this document owns normative behavior, assign stable requirement identities:
+
+```md
+### REQ-001 — <short behavior name>
+**Status:** CURRENT
+**Revision:** 1
+**Decision lineage:** ADR-0001 (or None)
+<observable behavior / acceptance boundary>
+```
+
+If this document is informative only, say so and link the authoritative requirement instead. Do not create a second source of truth.
+
 </spec-template>