harness-everything 0.11.7 → 0.12.1

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

@@ -76,10 +76,18 @@ function workspaceFingerprint(cwd) {
 function shellProbeKey(payload, cwd) {
   const toolUseId = String(payload?.tool_use_id || payload?.toolUseId || '').trim();
   const tool = String(payload?.tool_name || payload?.tool || '');
+  if (toolUseId) {
+    // Host tool-use identity is stable across Pre/Post payload cwd drift.
+    return crypto.createHash('sha256')
+      .update('harness-shell-probe-v3\0')
+      .update(toolUseId).update('\0')
+      .update(tool)
+      .digest('hex');
+  }
+  // Compatibility fallback for hosts that do not expose tool_use_id.
   const command = commandOf(payload);
   return crypto.createHash('sha256')
-    .update('harness-shell-probe-v2\0')
-    .update(toolUseId || 'no-tool-use-id').update('\0')
+    .update('harness-shell-probe-v2-fallback\0')
     .update(tool).update('\0')
     .update(key(cwd)).update('\0')
     .update(command)

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

@@ -4,6 +4,7 @@ const fs = require('fs');
 const path = require('path');
 const { getWorkspaceRoot, getSessionDir, getSessionId, getStateRoot } = require('./harness-state');
 const { atomicWriteJson, readJson } = require('./fable-contracts');
+const { workspaceFingerprint } = require('./workflow-isolation');
 
 const OPEN_STATES = new Set(['pending', 'active', 'running', 'failed', 'blocked', 'escaped']);
 const SAFE_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
@@ -45,6 +46,25 @@ function saveWorkflow(context) { atomicWriteJson(context.file, context.workflow)
 
 const MUTATION_PROBE_KEY = /^[a-f0-9]{64}$/;
 const MUTATION_PROBE_WAIT = new Int32Array(new SharedArrayBuffer(4));
+const MUTATION_PROBE_DEFAULT_TIMEOUT_MS = 120000;
+const MUTATION_PROBE_RECLAIM_GRACE_MS = 5000;
+const MUTATION_PROBE_MAX_TIMEOUT_MS = 30 * 60 * 1000;
+
+function mutationProbeLeaseMs(timeoutMs) {
+  const parsed = Number(timeoutMs);
+  const executionMs = Number.isFinite(parsed) && parsed > 0
+    ? Math.min(parsed, MUTATION_PROBE_MAX_TIMEOUT_MS)
+    : MUTATION_PROBE_DEFAULT_TIMEOUT_MS;
+  return executionMs + MUTATION_PROBE_RECLAIM_GRACE_MS;
+}
+
+function mutationProbeExpired(probe, now = Date.now()) {
+  const reclaimAfterAt = Number(probe?.reclaimAfterAt);
+  if (Number.isFinite(reclaimAfterAt)) return now >= reclaimAfterAt;
+  const observedAt = Number(probe?.observedAt);
+  return Number.isFinite(observedAt) &&
+    now - observedAt >= mutationProbeLeaseMs(null);
+}
 
 function mutationProbeDir(context) {
   return path.join(context.sessionDir, 'mutation-probes');
@@ -81,15 +101,25 @@ function withMutationProbeLock(context, callback) {
   finally { fs.rmSync(lockDir, { recursive: true, force: true }); }
 }
 
+function probeCountsIteration(probe) {
+  return Boolean(probe && (probe.countIteration === true ||
+    (probe.countIteration === undefined && probe.reserveIteration === true)));
+}
+
 function mutationProbeReservations(context) {
   const dir = mutationProbeDir(context);
   let files = [];
   try { files = fs.readdirSync(dir).filter(file => /^[a-f0-9]{64}\.json$/.test(file)); }
   catch (_) { return 0; }
+  const now = Date.now();
   let count = 0;
   for (const file of files) {
     const probe = readJson(path.join(dir, file));
-    if (probe?.schemaVersion === 1 && probe.reserveIteration === true) count++;
+    if (probe?.schemaVersion !== 1 || probe.reserveIteration !== true) continue;
+    // A reservation remains active for the host/tool execution timeout plus
+    // a grace period. This prevents a genuinely in-flight command from being
+    // reclaimed merely because it ran longer than an arbitrary short delay.
+    if (!mutationProbeExpired(probe, now)) count++;
   }
   return count;
 }
@@ -115,22 +145,78 @@ function assertIterationCapacity(context, evidence) {
   return { applicable: true, value: budget.counters.iterations, reserved, limit };
 }
 
-function registerMutationProbe(context, key, fingerprint, reserveIteration) {
+function reclaimStaleMutationProbes(context, keepKey) {
+  const dir = mutationProbeDir(context);
+  let files = [];
+  try { files = fs.readdirSync(dir).filter(file => /^[a-f0-9]{64}\.json$/.test(file)); }
+  catch (_) { return; }
+  const now = Date.now();
+  for (const name of files) {
+    const staleKey = name.slice(0, -'.json'.length);
+    if (staleKey === keepKey) continue;
+    const file = path.join(dir, name);
+    const probe = readJson(file);
+    if (!probe || probe.schemaVersion !== 1) continue;
+    if (!mutationProbeExpired(probe, now)) continue;
+    const countsIteration = probeCountsIteration(probe);
+    if (!probe.observationCwd) {
+      // Legacy probes predate stored observation roots and cannot be safely
+      // re-observed. Once outside the in-flight grace window they must not
+      // reserve capacity forever.
+      fs.unlinkSync(file);
+      continue;
+    }
+    let currentFingerprint;
+    try {
+      currentFingerprint = workspaceFingerprint(probe.observationCwd);
+    } catch (_) {
+      fs.unlinkSync(file);
+      context.workflow.lastMutationAt = now;
+      if (countsIteration && context.workflow.strategy === 'iterative-single') {
+        recordBudgetEvent(context, 'iteration', { evidence: 'shell:reclaimed-unobservable-workspace' });
+      } else {
+        saveWorkflow(context);
+      }
+      continue;
+    }
+    if (currentFingerprint !== probe.fingerprint) {
+      fs.unlinkSync(file);
+      context.workflow.lastMutationAt = now;
+      if (countsIteration && context.workflow.strategy === 'iterative-single') {
+        recordBudgetEvent(context, 'iteration', { evidence: 'shell:reclaimed-stale-workspace-mutation' });
+      } else {
+        saveWorkflow(context);
+      }
+      continue;
+    }
+    // No visible workspace effect after the grace window: this probe was
+    // orphaned by a denial/block/missing Post event. Discard it so it cannot
+    // reserve capacity or later attribute an unrelated mutation (#161).
+    fs.unlinkSync(file);
+  }
+}
+
+function registerMutationProbe(context, key, fingerprint, reserveIteration, observationCwd, timeoutMs) {
   if (!MUTATION_PROBE_KEY.test(String(key || '')) || !MUTATION_PROBE_KEY.test(String(fingerprint || ''))) {
     throw new Error('invalid mutation probe identity');
   }
   return withMutationProbeLock(context, () => {
     refreshWorkflowForProbe(context);
+    reclaimStaleMutationProbes(context, key);
     if (reserveIteration) assertIterationCapacity(context, 'shell:untrusted');
     const dir = mutationProbeDir(context);
     fs.mkdirSync(dir, { recursive: true });
     const file = mutationProbeFile(context, key);
     if (fs.existsSync(file)) throw new Error('mutation probe is already pending for this tool call');
+    const observedAt = Date.now();
     const probe = {
       schemaVersion: 1,
       fingerprint,
       reserveIteration: Boolean(reserveIteration),
-      observedAt: Date.now(),
+      countIteration: Boolean(reserveIteration),
+      observationCwd: observationCwd ? path.resolve(observationCwd) : null,
+      observedAt,
+      reclaimAfterAt: observedAt + mutationProbeLeaseMs(timeoutMs),
     };
     atomicWriteJson(file, probe);
     return probe;
@@ -152,7 +238,7 @@ function settleMutationProbe(context, key, afterFingerprint, tool) {
     const changed = afterFingerprint !== probe.fingerprint;
     if (changed) {
       context.workflow.lastMutationAt = Date.now();
-      if (probe.reserveIteration && context.workflow.strategy === 'iterative-single') {
+      if (probeCountsIteration(probe) && context.workflow.strategy === 'iterative-single') {
         recordBudgetEvent(context, 'iteration', { evidence: String(tool || 'shell') + ':observed-workspace-mutation' });
       } else {
         saveWorkflow(context);
@@ -162,6 +248,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 (probeCountsIteration(probe) && 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 +499,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/state-persist.js

@@ -2,7 +2,7 @@
 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 { loadWorkflow, saveWorkflow, isMajorWorkflow, peekMutationProbe, settleMutationProbe, settleMutationProbeConservative } = require('./lib/workflow-runtime');
 const { cwdOf, shellProbeKey, workspaceFingerprint, directMutationInWorkspace } = require('./lib/workflow-isolation');
 const { observeTool } = require('./lib/telemetry');
 
@@ -37,11 +37,17 @@ function observeWorkspaceMutation(payload, root) {
   if (!context.workflow || context.workflow.state === 'deferred') return false;
   const cwd = cwdOf(payload, root);
   const probeKey = shellProbeKey(payload, cwd);
-  if (!peekMutationProbe(context, probeKey)) return false;
+  const probe = peekMutationProbe(context, probeKey);
+  if (!probe) return false;
+  const observationCwd = probe.observationCwd || cwd;
   let after;
   try {
-    after = workspaceFingerprint(cwd);
+    after = workspaceFingerprint(observationCwd);
   } 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);

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

@@ -9,6 +9,15 @@ const { key, classifyShell, workspaceFingerprint, shellProbeKey, cwdOf, commandO
 const DIRECT = new Set(['Edit', 'Write', 'apply_patch']);
 const SHELL = new Set(['Bash', 'PowerShell', 'exec_command']);
 
+function shellTimeoutMs(payload) {
+  const input = payload?.tool_input || payload?.input || {};
+  for (const value of [input.timeout_ms, input.timeoutMs, input.timeout, payload.timeout_ms, payload.timeoutMs]) {
+    const parsed = Number(value);
+    if (Number.isFinite(parsed) && parsed > 0) return parsed;
+  }
+  return null;
+}
+
 function isController(command, cwd) {
   // One trusted local executable, literal arguments, no shell evaluation.
   if (/[;&|`\r\n<>$(){}]/.test(command)) return false;
@@ -62,11 +71,31 @@ 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');
+  registerMutationProbe(
+    context,
+    probeKey,
+    fingerprint,
+    workflow.strategy === 'iterative-single',
+    cwd,
+    shellTimeoutMs(payload)
+  );
 }
 
 readHookInput(decide);

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.7",
+  "version": "0.12.1",
   "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/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>

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

@@ -56,4 +56,18 @@ A description of the things that are out of scope for this spec.
 
 Any further notes about the feature.
 
+## 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 behavior / acceptance boundary>
+```
+
+Do not recycle requirement IDs. When approved behavior changes, increment the revision and reconcile the living spec before implementation completion.
+
 </spec-template>