harness-everything 0.11.6 → 0.12.0

package/docs/workflows/verify-before-claim.md

@@ -1,64 +1,61 @@
 # Workflow: Verify Before Claim
 
-> Fact-audit discipline requiring empirical verification of external claims, SDK configurations, defaults, and unmeasured performance estimates.
+> Check external framework, SDK, CLI, and API claims plus any unmeasured performance or cost numbers against an authoritative source, then deliver a cited claim, a real measurement, or a labeled estimate.
 
----
+Source of truth: `verify-before-claim/SKILL.md`.
 
-## 1. Skill Behavior Workflow
+Contract summary from SKILL.md — Trigger: external behavior, version/config/exit-code claim, or unmeasured number. Output: official citation, real measurement, or explicitly labeled estimate. State mutation: none; evidence travels with the claim. Gate: official source or real measurement; unresolved claims stay inconclusive. USE FOR: stating how an external framework, SDK, CLI tool, or API behaves; quoting performance, cost, latency, or timing numbers; answering "does X support Y" or version-specific questions; citing defaults, exit codes, config flags, pricing, or rate limits. DO NOT USE FOR: claims about this repository's own code, facts the user supplied directly, generic CS knowledge such as Big-O.
 
-This section visualizes how the `verify-before-claim` skill executes internally, detailing the sequence of operations, state transitions, and evaluation steps.
+## 1. Skill Behavior Workflow
 
 ```mermaid
 graph TD
-  Start([About to Assert External Framework / API Behavior or Perf Number]) --> CheckScope{Claim Scope Check}
-  CheckScope -->|Internal Repo Code| ReadSource["Read Local Source Code -> State Facts"]
-  CheckScope -->|External Framework / API / Number| CheckNet{Web Fetch / Search / Measurement Available?}
-  
-  CheckNet -->|Yes| FetchDocs["WebFetch Official Docs / Measure Real Execution"]
-  CheckNet -->|No / Offline| EstimateFallback["Explicitly Label Response as Unverified Estimate"]
-  
-  FetchDocs --> CiteDocs["Quote Authoritative Source / State Measured Data"]
-  ReadSource --> End([Verified Output Delivered])
-  CiteDocs --> End
-  EstimateFallback --> End
+  Claim[External Claim Or Unmeasured Number] --> Scope{Claim Scope?}
+  Scope -->|this repo own code| Local[Read Local Source Report Observed Facts]
+  Scope -->|external behavior or number| Official[Consult Official Docs First]
+  Official --> Numbers{Needs Number?}
+  Numbers -->|yes| Measure[Real Measurement Or Labeled Estimate]
+  Numbers -->|no| Cite[Return Cited Claim]
+  Measure --> Output[Claim With Evidence]
+  Cite --> Output
+  Local --> Output2[Fact From Source]
+  Official -->|contradiction or missing evidence| Inconclusive[Report Inconclusive]
 ```
 
----
-
 ## 2. Triggering and Routing Path
 
-This diagram illustrates how the `verify-before-claim` skill is triggered through user requests or developer actions, and how it integrates or chains together with other companion skills in the Harness OS ecosystem to form unified workflows.
-
 ```mermaid
-graph LR
-  Router["harness-everything / tier-router.js"] -->|Requires fact checking or estimates| VBC["verify-before-claim / SKILL.md"]
-  VBC -->|Empirical verification helper| RunCode["Run a real Node/terminal measurement"]
-  VBC -->|Secures quality of decisions in| GWD["grill-with-docs / SKILL.md"]
-  VBC -->|Verifies assertions in testing suite| TDD["tdd / SKILL.md"]
+graph TD
+  ExtBehave[State External Framework SDK CLI API Behavior] --> Skill[verify-before-claim SKILL]
+  PerfNum[Quote Perf Cost Latency Timing] --> Skill
+  SupportQ[Does X Support Y Version Question] --> Skill
+  ConfigQ[Cite Default ExitCode Flag Pricing Limit] --> Skill
+  OwnCode[Claim About This Repo Own Code] --> LocalSrc[Read Actual Source]
+  UserFact[Fact User Supplied Directly] --> Decline[Do Not Route]
+  GenericCS[Generic CS Knowledge BigO] --> Decline
+  Skill --> Cited[Cited Claim Or Measurement Or Estimate]
 ```
 
----
-
-## 3. Real-World Use Case Flowchart
+## 3. Real-World Use Case
 
-Here we model concrete real-world scenarios and use cases of the `verify-before-claim` skill, illustrating standard success paths, error handling, or recovery loops.
+A developer is about to assert a version-specific SDK default and a latency number in a design note. The skill routes the default to official documentation for a citation, routes the latency claim to a real measurement, and labels the value an estimate when no run exists. If sources contradict each other or no authoritative source exists, the result is reported as inconclusive rather than asserted as certain, even under time pressure.
 
 ```mermaid
 graph TD
-  Start["Developer assumes: 'Node.js fs.rmSync returns boolean upon success'"] --> Trigger["verify-before-claim skill triggered"]
-  Trigger --> ReadDocs["Checks Node.js documentation via WebSearch"]
-  ReadDocs --> FindTrue["Discovers fs.rmSync returns 'undefined' on success, and throws on failure"]
-  FindTrue --> TestCode["Executes quick Node snippet to confirm empirical behavior"]
-  TestCode --> UpdateCode["Refactors proposed catch-blocks to handle exceptions instead of checking booleans"]
-  UpdateCode --> Done([Potential production runtime crash prevented])
+  Draft[Draft Asserts SDK Default And Latency] --> CheckDocs[Check Official Docs For Default]
+  CheckDocs --> CheckNum[Require Real Measurement For Number]
+  CheckNum -->|measured| Cited2[Cited Default Plus Measured Number]
+  CheckNum -->|no run| Labeled[Labeled Estimate]
+  CheckDocs -->|conflict or gap| Inconc[Inconclusive Report]
 ```
 
----
+Deep dive: `verify-before-claim/references/verification-guide.md`.
 
 ## 4. Verification Check
 
-To ensure that the `verify-before-claim` skill is operating in strict compliance with Harness OS design laws, verify the following:
-
-- [ ] **Physical Boundary Verification**: The skill boundaries are respected and do not leak context.
-- [ ] **State Checkpoint Verification**: The active state is established, validated, and recorded at the beginning and end of each execution branch.
-- [ ] **Cognitive Alignment**: The skill conforms to the **Think > Try > Summarize > Record** cognitive loop.
+- [ ] Local-repository claims were settled by reading the actual source, not by external citation
+- [ ] External framework, SDK, CLI, or API behavior used official documentation first with a citation
+- [ ] Performance, cost, latency, or timing numbers came from a real measurement or were explicitly labeled as estimates
+- [ ] Defaults, exit codes, config flags, pricing, and rate limits were cited rather than asserted from memory
+- [ ] Contradictions or missing evidence were reported as inconclusive
+- [ ] No unverified external fact was claimed as certain, even under time pressure

package/docs/workflows/zoom-out.md

@@ -1,74 +1,62 @@
 # Workflow: Zoom Out
 
-> High-level reflection report generation to break out of error loops, analyze failure patterns, and backtrack to alternative paths.
+> Reflect-first breaker after three failures: stop edits, rebuild the full picture with read-only tools, write a fact-check report, then resume or escalate.
 
----
+Source of truth: `zoom-out/SKILL.md`.
 
-## 1. Skill Behavior Workflow
+Contract summary from SKILL.md — Trigger: three same-signature failures or an explicit loop/rethink request. Output: fact-checked report ending in `RESUME` or `ESCALATE`. State: writes the session `zoom-out-report.md`; reset may clear breaker state. Gate: `hooks/scripts/rule-of-3.js` plus a valid report; reset only after the second cycle. USE FOR: "you are stuck in a loop", "the same error keeps failing", "rethink your assumptions". DO NOT USE FOR: routine single-failure debugging, greenfield planning without failures.
 
-This section visualizes how the `zoom-out` skill executes internally, detailing the sequence of operations, state transitions, and evaluation steps.
+## 1. Skill Behavior Workflow
 
 ```mermaid
 graph TD
-  Start([3 Consecutive Failures / Goal Drift Triggered]) --> CeaseFire["1. Phase 1: Cease Fire - Stop Code Edits Immediately"]
-  CeaseFire --> Rebuild["2. Phase 2: Rebuild Full Picture using Read-Only Tools"]
-  Rebuild --> CheckPath{3. Resolve Reflection Report Path}
-  
-  CheckPath -->|Session Path Provided| WriteSession["Copy template to Session zoom-out-report.md"]
-  CheckPath -->|Template / Path Unavailable| WritePlatform["Write to .github/harness-everything/zoom-out-report.md or Inline"]
-  
-  WriteSession --> DecisionGate{4. Phase 4: Decision Gate}
-  WritePlatform --> DecisionGate
-  
-  DecisionGate -->|Untried Path Identified| Resume["RESUME: Execute Fresh Diagnosis in TDD / Fable"]
-  DecisionGate -->|Requirement Conflict / Access Gap| Escalate["ESCALATE: Present 2-3 Options + Recommendation to Human"]
-  
-  Resume --> Resolved{5. Problem Cracking Succeeds?}
-  Resolved -->|Yes| SelfEvolve["Call self-evolve to Persist Insight"]
-  Resolved -->|No: 3 More Failures| Escalate
-  SelfEvolve --> End([Reflection Completed & Lessons Persisted])
-  Escalate --> End
+  Third[Third Same Signature Failure] --> Stop[Stop Edits No User Ask Yet]
+  Stop --> ReadOnly[ReadOnly Restate Goal Check Files Config Logs]
+  ReadOnly --> Fill[Fill zoom-out-report template]
+  Fill --> Decide{RESUME or ESCALATE?}
+  Decide -->|untried path| Resume[RESUME On Untried Path]
+  Decide -->|genuine user decision| Escalate[ESCALATE With Options]
+  Resume --> Again{Repeated Breaker Cycle?}
+  Again -->|second cycle| Reset[npm run harness reset]
+  Reset --> Evolve[Record Insight With self-evolve]
+  Again -->|no| Done([Report Complete])
+  Escalate --> Done
 ```
 
----
-
 ## 2. Triggering and Routing Path
 
-This diagram illustrates how the `zoom-out` skill is triggered through user requests or developer actions, and how it integrates or chains together with other companion skills in the Harness OS ecosystem to form unified workflows.
-
 ```mermaid
-graph LR
-  RuleOf3["Rule of 3 Circuit Breaker"] -->|Tripped!| ZoomOut["zoom-out / SKILL.md"]
-  ZoomOut -->|Halts execution for| ActiveWork["Active workspace edits"]
-  ZoomOut -->|Asks for human direction via| AskQuestions["host user-input mechanism"]
-  ZoomOut -->|Unlocks workspace state after| HumanReset["Human Partner Response"]
+graph TD
+  LoopReq[Stuck In Loop Request] --> Skill[zoom-out SKILL]
+  SameErr[Same Error Keeps Failing] --> Skill
+  Rethink[Rethink Assumptions Request] --> Skill
+  ThreeFail[Three Same Signature Failures] --> Breaker[hooks scripts rule-of-3 js]
+  Breaker --> Skill
+  SingleFail[Routine Single Failure] --> DirectFix[Fix Directly]
+  Greenfield[Greenfield Planning No Failures] --> Fable[fable-mode SKILL]
+  Skill --> ReportGate[Valid Report RESUME or ESCALATE]
 ```
 
----
-
-## 3. Real-World Use Case Flowchart
-
-Here we model concrete real-world scenarios and use cases of the `zoom-out` skill, illustrating standard success paths, error handling, or recovery loops.
+## 3. Real-World Use Case
 
 ```mermaid
 graph TD
-  Start["Attempting to fix Python import error; fails 3 times consecutively with same trace"] --> Trigger["Rule of 3 circuit breaker trips"]
-  Trigger --> Lock["Workspace writes locked"]
-  Trigger --> Awaken["Awaken: Stop error-fixing; review imports design & requirements (Law 2)"]
-  Awaken --> Collect["Collect error traces and diff history"]
-  Collect --> WriteReport["Create the session zoom-out-report.md detailing the import cyclic dependency"]
-  WriteReport --> Present["Present options to human: Option A - Merge imports, Option B - Extract shared modules"]
-  Present --> UserChoice["User select: 'Option B'"]
-  UserChoice --> Unlock["Unlock workspace and execute Option B"]
-  Unlock --> Done([Error loop successfully broken and resolved])
+  Fail[Same Test Fails Three Times Same Signature] --> Halt[Stop Edits Rebuild Picture ReadOnly]
+  Halt --> Inspect[Restate Goal Check Files Config Logs]
+  Inspect --> Write[Fill templates zoom-out-report template md]
+  Write --> Choice{Untried Path Exists?}
+  Choice -->|yes| Resume2[RESUME On Untried Path]
+  Choice -->|no| Esc2[ESCALATE With Options]
+  Resume2 -->|repeated cycle| Reset2[npm run harness reset Then self-evolve]
 ```
 
----
+Template: `zoom-out/templates/zoom-out-report.template.md`. Enforcement: `hooks/scripts/rule-of-3.js`. Deep dive: `zoom-out/references/circuit-breaker.md`.
 
 ## 4. Verification Check
 
-To ensure that the `zoom-out` skill is operating in strict compliance with Harness OS design laws, verify the following:
-
-- [ ] **Physical Boundary Verification**: The skill boundaries are respected and do not leak context.
-- [ ] **State Checkpoint Verification**: The active state is established, validated, and recorded at the beginning and end of each execution branch.
-- [ ] **Cognitive Alignment**: The skill conforms to the **Think > Try > Summarize > Record** cognitive loop.
+- [ ] After three same-signature failures, edits stopped and the same approach was not retried
+- [ ] Goal, files, configuration, and logs were rechecked with read-only tools before any resume
+- [ ] `templates/zoom-out-report.template.md` was filled and the session `zoom-out-report.md` ends in `RESUME` or `ESCALATE`
+- [ ] Resume targeted only an untried path; genuine user decisions were escalated with options
+- [ ] Reset via `npm run harness:reset` happened only after the second cycle, with the insight recorded via `self-evolve`
+- [ ] Routine single-failure debugging and greenfield planning without failures were not routed here

package/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/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/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/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/hooks/scripts/lib/learning-opportunity.js

@@ -8,6 +8,7 @@ const {
   getSessionId,
   getSessionDir,
 } = require('./harness-state');
+const { emitLessonTelemetry } = require('./telemetry');
 
 const SCHEMA_VERSION = 1;
 const TRIGGERS = new Set(['rule-of-3-recovery', 'verifier-fail-pass']);
@@ -134,6 +135,27 @@ function createLearningOpportunity(payload, input = {}) {
     updatedAt: observedAt,
   };
   atomicWriteJson(file, candidate);
+  const lifecycleReasonCodes = [...candidate.trigger.reasonCodes, `trigger:${triggerType}`];
+  emitLessonTelemetry({
+    event: 'learning_opportunity',
+    root,
+    payload,
+    sessionId,
+    candidateId,
+    observedAt,
+    status: 'success',
+    reasonCodes: lifecycleReasonCodes,
+  });
+  emitLessonTelemetry({
+    event: 'lesson_proposed',
+    root,
+    payload,
+    sessionId,
+    candidateId,
+    observedAt,
+    status: 'success',
+    reasonCodes: lifecycleReasonCodes,
+  });
   return { created: true, file, candidate };
 }
 

package/hooks/scripts/lib/telemetry.js

@@ -6,11 +6,26 @@ const path = require('path');
 const { getWorkspaceRoot, getStateRoot, getSessionDir } = require('./harness-state');
 
 const TELEMETRY_SCHEMA_VERSION = 1;
+const LESSON_EVENT_TYPES = new Set([
+  'learning_opportunity',
+  'lesson_proposed',
+  'lesson_screened',
+  'lesson_evaluated',
+  'lesson_accepted',
+  'lesson_rejected',
+  'lesson_inconclusive',
+  'lesson_persisted',
+  'lesson_retrieved',
+  'lesson_validated',
+  'lesson_regressed',
+  'lesson_superseded',
+]);
 const EVENT_TYPES = new Set([
   'skill.invoke',
   'skill.loaded',
   'skill.complete',
   'tool.observed',
+  ...LESSON_EVENT_TYPES,
 ]);
 const STATUSES = new Set(['unknown', 'success', 'failure', 'aborted']);
 const FORBIDDEN_KEYS = new Set([
@@ -102,6 +117,29 @@ function telemetryFile(root, payload) {
   return path.join(getStateRoot(root || getWorkspaceRoot(payload), payload), 'telemetry', 'events.jsonl');
 }
 
+function emitLessonTelemetry(input = {}) {
+  const event = String(input.event || '');
+  if (!LESSON_EVENT_TYPES.has(event)) {
+    return { ok: false, error: `unsupported lesson telemetry event: ${event}`, overheadMs: 0 };
+  }
+  const invocationId = localId('lesson', input.candidateId);
+  if (!invocationId) {
+    return { ok: false, error: 'lesson telemetry requires candidateId', overheadMs: 0 };
+  }
+  return emitTelemetry({
+    event,
+    host: ['claude', 'codex', 'opencode', 'unknown'].includes(input.host)
+      ? input.host
+      : detectHost(input.payload || {}),
+    observedAt: input.observedAt || nowIso(),
+    sessionId: localId('session', input.sessionId),
+    invocationId,
+    skillName: 'self-evolve',
+    status: STATUSES.has(input.status) ? input.status : 'unknown',
+    reasonCodes: input.reasonCodes || [],
+  }, { root: input.root, payload: input.payload });
+}
+
 function emitTelemetry(input, options = {}) {
   const started = process.hrtime.bigint();
   try {
@@ -361,9 +399,11 @@ function readEvents(file) {
 module.exports = {
   EVENT_TYPES,
   FORBIDDEN_KEYS,
+  LESSON_EVENT_TYPES,
   STATUSES,
   TELEMETRY_SCHEMA_VERSION,
   detectHost,
+  emitLessonTelemetry,
   emitTelemetry,
   hostDuration,
   localId,

package/hooks/scripts/lib/workflow-isolation.js

@@ -248,6 +248,35 @@ function mutationPaths(payload) {
   }
   return [input.file_path || input.filePath || input.path].filter(value => typeof value === 'string' && value.trim());
 }
+
+// Bound workspace root plus its linked worktrees. Git failures (e.g. a
+// non-git workspace) degrade to the root alone instead of throwing, so
+// Tier-2 accounting never blocks on this enumeration (#165; cf. #162).
+function worktreeRoots(root) {
+  const roots = [root];
+  try {
+    for (const field of git(root, ['worktree', 'list', '--porcelain', '-z']).split('\0')) {
+      if (field.startsWith('worktree ')) {
+        const candidate = field.slice('worktree '.length).trim();
+        if (candidate) roots.push(candidate);
+      }
+    }
+  } catch (_) { /* root alone */ }
+  return roots;
+}
+
+// Direct-tool (Edit/Write/apply_patch) targets count against the Tier-2
+// budget only when at least one target lies inside the workspace (#165).
+// Unknown targets (no parseable path) stay conservative and count.
+function directMutationInWorkspace(payload, cwd, root) {
+  const targets = mutationPaths(payload);
+  if (!targets.length) return true;
+  const roots = worktreeRoots(root);
+  return targets.some(target => {
+    const resolved = path.resolve(cwd, target);
+    return roots.some(candidate => within(candidate, resolved));
+  });
+}
 function assertTargets(payload, cwd, isolatedRoot) {
   const targets = mutationPaths(payload);
   if (!targets.length) throw new Error('mutation target is unknown; cannot verify worktree isolation');
@@ -274,4 +303,4 @@ function assertShellScope(command, cwd, isolatedRoot) {
   }
 }
 
-module.exports = { canonical, key, within, linkedWorktree, classifyShell, workspaceFingerprint, shellProbeKey, inputOf, cwdOf, commandOf, mutationPaths, assertTargets, assertShellScope };
+module.exports = { canonical, key, within, linkedWorktree, classifyShell, workspaceFingerprint, shellProbeKey, inputOf, cwdOf, commandOf, mutationPaths, worktreeRoots, directMutationInWorkspace, assertTargets, assertShellScope };

package/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/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) {