harness-everything 0.16.0 → 0.16.2

package/docs/routing.md

@@ -4,21 +4,21 @@ Harness classifies software work and selects the smallest sufficient execution t
 
 The current architecture follows two coupled rules:
 
-> **Mandatory applicable workflow; flexible reasoning/implementation inside it.**
+> **Guidance-first workflow; flexible reasoning/implementation and execution.**
 >
-> **Skill applicability is evaluated explicitly; workflow escape is exception-only and evidence-backed.**
+> **Skill applicability is evaluated explicitly; skipped guidance should have a concise evidence-based reason.**
 
 A strong model remains free to decide *how* to perform the work. It may not decide that an applicable selected lifecycle can be skipped because the task feels simple or already understood.
 
 ## Kernel invariants
 
-For software/project work, Harness establishes mandatory rails before mutation:
+For software/project work, Harness establishes routing context and lightweight rails before broad mutation:
 
 1. **Route before execution** — establish scope/tier and the smallest justified topology.
 2. **Verify before claim** — completion requires objective evidence appropriate to the change.
 3. **Re-plan after repeated failure** — after three same-signature failures, stop micro-retrying and use a fresh diagnosis / `zoom-out`.
 4. **Evaluate before omission** — read every suggested skill's complete `SKILL.md` entry before deciding applicability.
-5. **Resolve selected workflow** - successful completion requires `satisfied`; `blocked` is a reportable incomplete outcome. Escape covers only a declared stage and preserves other obligations.
+5. **Review selected workflow** — use it as planning guidance and surface unresolved evidence before claiming completion.
 
 The model owns tools, implementation technique, reasoning, and decomposition details inside those rails.
 
@@ -30,8 +30,8 @@ kernel-router.js
   ├─ preserves tier + rationale + dynamic-skill recommendations
   ├─ emits required invariants + structured workflow plan
   ├─ requires applicability evaluation for suggested skills
-  ├─ activates the selected workflow execution contract
-  └─ exposes explicit blocked/degraded/escape state instead of silent downgrade
+  ├─ records the selected workflow guidance
+  └─ exposes warnings/degraded/escape evidence instead of silently hiding limitations
 ```
 
 Use:
@@ -97,7 +97,7 @@ No universal `TODO → TDD → verification-loop` order is implied. But when a s
 
 Typical triggers: repository-wide refactors, architecture/migration work, broad synthesis, or bounded delegation. The router may select `fable-staged`, `fable-parallel`, or `fable-multi-agent-workspace`.
 
-A selected Fable topology is mandatory for that run. `fable-parallel` dispatches only validated independent batches; `fable-staged` preserves ordered stage contracts; workspace mode preserves durable handoffs/roles while Fable owns staged execution.
+A selected Fable topology is structured guidance for that run; dependency/write-set validation remains useful evidence, while missing workflow state does not hard-block execution.
 
 Tier 3 does **not** automatically mean multi-agent. The smallest sufficient topology still wins.
 
@@ -107,25 +107,25 @@ Tier 3 does **not** automatically mean multi-agent. The smallest sufficient topo
 
 Policy lives in `hooks/scripts/action-gate-rules.json`. Matched actions are handled according to host capability and configured policy; approved/executed payload identity is audited. `HARNESS_ACTION_GATE_POLICY=always-ask` forces Claude's ask path where supported. Unsupported host behavior must remain visible rather than being described as equivalent hard enforcement.
 
-## Workflow lifecycle gates
+## Workflow lifecycle reminders
 
 The [workflow runtime contract](workflow-runtime.md) defines the executable boundary:
 
-- `workflow-gate.js` checks shell/direct mutation, correlated Fable entry, and major-workflow Git isolation.
-- `workflow-stop-gate.js` checks manifest stage membership and observed verification evidence before `satisfied`.
+- `workflow-gate.js` observes shell/direct mutation, Fable correlation, and major-workflow Git isolation and emits reminders.
+- `workflow-stop-gate.js` reports unresolved stage/verification evidence without rejecting Stop.
 - `workflow-disposition.js` starts/replans the run, records a scoped stage escape, or reports `blocked`.
 
-A follow-up prompt cannot erase unresolved obligations. Start from the router's displayed session stage-specification path; source mutation waits for entry and isolation. Replan is bounded. Escape requires `workflow-uncovered-scope` or `host-capability-unavailable`, a stage id, uncovered scope, and evidence. It never waives isolation or independent verification.
+Follow-up prompts retain useful evidence, but unresolved cognitive workflow state does not lock mutation or completion.
 
 Direct/iterative verification milestones are checked, while semantic check quality and iteration budgeting remain executor obligations. Shell inspection does not contain arbitrary script side effects. Package/mechanism tests do not prove host loading or behavioral compliance; #82 owns retained live evidence.
 
 ## Cognitive OS relationship
 
-`install-cognitive-os` remains the explanatory/manual entry point for Discover → Think → Try → Summarize → Record. It is a reasoning policy, not a peer skill that must be selected before domain work. The selected workflow contract governs lifecycle obligations; the model retains freedom inside it.
+`install-cognitive-os` remains the explanatory/manual entry point for Discover → Think → Try → Summarize → Record. It is a reasoning policy, not a peer skill that must be selected before domain work. The selected workflow guidance informs lifecycle choices; the model retains execution freedom.
 
-## Enforcement strength
+## Guidance and enforcement strength
 
-A contract can be semantically mandatory even when a host cannot mechanically enforce every transition. Keep those claims separate:
+Workflow guidance is intentionally non-blocking across hosts. Keep that separate from Rule-of-3 and explicit permission enforcement.
 
 - **contract:** what the agent is required to do;
 - **mechanism:** which transitions a packaged hook/plugin can block or observe;

package/docs/workflow-runtime.md

@@ -1,122 +1,92 @@
-# Selected workflow runtime
+# Workflow Runtime
 
-The selected applicable topology is mandatory. This contract governs lifecycle
-obligations; agents still choose tools, reasoning, and implementation inside it.
-Skill suggestions require individual applicability evaluation, not one universal
-skill sequence. Git mutation isolation and durable multi-agent workspace state
-are separate concerns.
+Harness uses workflow state to **observe, explain, and remind**. It is not a numeric-budget scheduler.
 
-## State and entry
+## Product rule
 
-`UserPromptSubmit` records `workflow-run.json` in the bound workspace's global
-Harness session state. It includes a unique `workflowId`, complete plan, prompt
-hash (no prompt text), revision count, and scoped exceptions. Unresolved work
-survives follow-up/status prompts; a weaker route cannot erase it. A stronger
-route blocks mutation until an explicit replan. A new task after `satisfied`
-gets a new identity. Invalid recorded state fails closed with a diagnostic.
+The runtime follows **minimal rails, maximum freedom**:
 
-```text
-pending -> running -> satisfied
-              |          (only after required evidence)
-              -> blocked -> start/replan (within budget)
-```
+- routing selects a useful topology and suggested skills;
+- workflow state records useful evidence and unresolved obligations;
+- verification hooks remind when evidence is missing;
+- worktree/isolation checks warn when a safer execution shape is available;
+- iteration, revision, replan, and worker counts are planning hints only.
 
-`blocked` is a reportable incomplete outcome, never successful completion.
-`deferred` means no topology has been selected. Legacy `active`/`escaped` records
-remain subject to isolation and cannot supply a correlated run implicitly.
+None of those cognitive workflow conditions should trap a session or require a reset command.
 
-For Fable, write a stage array in the exact `workflow-stages.json` path displayed
-by the router. This one file is allowed as runtime bootstrap data before entry;
-the exception does not authorize changing workflow state or source artifacts.
-Use the [stage schema](../fable-mode/CONTRACT-FORMAT.md); each stage needs an
-objective `checkCommand` and `passCondition`. If the plan requires independent
-verification, declare a read-only `fable-verifier` stage depending on every
-other stage. Then run the displayed controller with the host session id:
+The two intentionally separate hard boundaries are:
 
-```text
-node "<hooks>/workflow-disposition.js" start --session-id "<session>"
-```
+1. **Rule of 3** — the third matching failure pauses mutation until a zoom-out reflection is written;
+2. **user/host permission and dangerous-action approval** — authorization boundaries such as the action gate.
 
-The controller prepares the existing Fable consumer's run at the **bound** state
-root, even when tool execution has moved to a linked worktree. The run records
-both `workflowId` and `sessionId`; matching only strategy or creation time is
-insufficient. `start` creates contracts, not agents. Fable retains ownership of
-worker dispatch, dependency/write-set scheduling, and synthesis.
-
-## Isolation boundary
-
-Before Tier 3 or Fable source/artifact mutation, the gate verifies a registered
-linked Git worktree with the same common Git directory as the bound repository.
-It checks the tool's execution directory and actual Edit/Write/apply_patch paths,
-including move destinations, relative traversal, and symlink/junction resolution.
-Unknown direct targets, Git metadata, and nested repositories are rejected.
-Read-only discovery and a literal `git worktree add` transition remain available
-before entry. Prefer an already-ignored path or sibling path for setup; never
-edit the primary tree's ignore file just to establish mandatory isolation.
-
-Shell recognition is conservative: redirects, substitutions, chained commands,
-and side-effect options are not accepted as read-only. Mutation-capable shell
-execution requires an isolated working-directory field, with explicit outside
-paths and directory changes rejected. **This is not a filesystem sandbox**:
-arbitrary scripts, aliases/configuration, indirect variable paths, and races can
-have effects a hook cannot infer. OS/host sandboxing is needed to contain them.
-Agent-writable state is also not tamper-proof. These mechanisms prevent tested
-bypasses; they do not establish durable containment against a malicious agent.
-
-## Mutation probes
-
-Shell-effect accounting is keyed per tool call, not per command text. The gate
-registers a pending probe per shell tool-use identity (`workflow-isolation.js`),
-`state-persist.js` settles probes in a single ordered handler, and
-`workflow-mutation-denied.js` discards the probe when that shell execution is
-denied — a denial is never recorded as an observed mutation. Staging-insensitive
-fingerprinting keeps the comparison on visible content, so metadata-only Git
-operations do not register as workspace effects. These lifecycle semantics are
-covered by deterministic workflow mechanism tests (`ci/mechanism-2ah-*`); live
-host loading and behavioral improvement still require separately retained host
-traces and paired evaluations.
-
-## Escape, replan, and completion
-
-Escape names one stage in the correlated run and records the uncovered scope,
-evidence, and `workflow-uncovered-scope` or `host-capability-unavailable` reason:
+## Runtime flow
 
 ```text
-node "<hooks>/workflow-disposition.js" escape --session-id "<session>" --stage-id "<stage>" --reason-code workflow-uncovered-scope --scope "<uncovered scope>" --evidence "<evidence>"
-node "<hooks>/workflow-disposition.js" block --session-id "<session>" --evidence "<blocker>"
+route
+  -> selected workflow guidance
+  -> execute freely
+  -> observe edits / verification / stage evidence
+  -> emit reminders when evidence is weak
+  -> complete or continue
+
+same failure signature x3
+  -> zoom-out reflection required
+  -> reflection accepted
+  -> normal execution resumes
 ```
 
-An escape never resolves the whole run, waives isolation, or removes independent
-verification. Covered stages remain mandatory. Unavailable required verification
-means blocked. The controller permits the initial run plus the plan's
-`maxRevisionRounds` replans; exhaustion stays blocked. Previous run evidence is
-retained, but cannot satisfy a replacement run.
-
-`contract-test.js` records exact check commands, observed worker/session identity,
-numeric exit code, and run/plan/stage evidence. A failed check can recover on a
-later observed pass. A dependent check cannot pass before its prerequisites.
-Stop enumerates the manifest's expected stages, so deleting a contract does not
-make the run complete. A `pass` label without matching exit-zero evidence fails.
-The independent verifier must have a distinct observed identity and evidence
-after the latest mutation/check. This proves attribution, not reasoning quality.
-
-Unresolved Stop exits 2. If the host marks a Stop retry, the contract becomes
-`blocked` with diagnostics instead of looping indefinitely or recording success.
-Direct/iterative routes use observed edit/verification milestones; iteration
-counting and semantic check quality remain executor obligations, not proven by
-these gates. Broad verification-command recognition is a heuristic.
-
-## Host evidence
-
-Claude's manifest carries the shell/direct-mutation and Stop hooks. The local
-OpenAI package carries the same runtime for its declared `Bash|apply_patch`
-surface. Package tests exercise both layouts. Missing worker/exit metadata keeps
-Fable completion unresolved; it must be reported as degraded/blocked, not passed.
-Manual CLI routing without a session cannot persist lifecycle state.
-
-OpenCode and instruction-only/public Skills-only surfaces do not gain these
-runtime gates from this change. An absent/disabled hook or deleted state cannot
-be detected as an active contract by that same hook. No host compatibility status
-is upgraded: see [platform capabilities](platform-capabilities.md). Live hook
-loading, enforced host transitions, and behavioral improvement need separately
-retained host traces and paired evaluations.
+There is no `budget-exhausted -> blocked -> reset-budget` lifecycle.
+
+## Numeric guidance
+
+Router plans may still expose values such as:
+
+- `maxIterations`
+- `maxRevisionRounds`
+- `maxReplans`
+- `maxWorkers`
+
+These are **advisory defaults**, useful for prompts, diagnostics, or planning. Runtime hooks do not maintain authoritative counters, reserve mutation capacity, or reject the Nth event.
+
+A long loop should produce a message such as:
+
+> Iterative work is getting long; verify assumptions or consider re-planning.
+
+It should not create a lock.
+
+## Mutation observation
+
+The previous mutation-probe subsystem and `.mutation-probes.lock` were removed by #190. Shell classification is now best-effort evidence for reminders. A false positive/negative must not deadlock work.
+
+Direct edits can still update `lastMutationAt`. Shell outcomes can update handoff evidence heuristically. Missing or ambiguous evidence degrades reminder quality, not execution availability.
+
+## Completion
+
+`workflow-stop-gate.js` and `stop-gate.js` are reminder surfaces. When verification or Fable stage evidence is incomplete they report the missing evidence and return success to the host.
+
+A workflow may retain `blocked` as a descriptive status recorded by the controller or legacy state, but workflow hooks do not use that value as a persistent execution lock.
+
+## Fable and worktrees
+
+Fable stage graphs, dependencies, write sets, and objective checks remain useful planning/evidence structures. `maxWorkers` no longer chunks ready stages as a hard concurrency cap.
+
+For major work, a linked worktree remains strongly recommended. Missing isolation is surfaced prominently, but Harness-owned cognitive workflow hooks do not turn it into a self-deadlocking runtime state.
+
+## Legacy state
+
+Existing sessions may contain `budget.state = "budget-exhausted"`, old counters, or mutation-probe files from earlier versions. Current runtime code treats the budget API as advisory compatibility only and creates no new mutation-probe state.
+
+Starting a fresh session remains the cleanest way to discard old evidence, but it is no longer required to recover from numeric budget exhaustion.
+
+## Testing contract
+
+Regression tests should prove:
+
+- reminders fire when relevant;
+- commands/Stop remain available;
+- no mutation-probe lock or reservation state is created;
+- `exec_command` verification can update `lastVerifyAt`;
+- Rule of 3 trips exactly at three matching failures;
+- a valid reflection resets the cycle;
+- a later three-failure cycle requests another reflection rather than a permanent hard lock;
+- permission/dangerous-action boundaries remain separate and intact.

package/evals/harness-everything/tasks/positive-tier1.yaml

@@ -1,6 +1,6 @@
 id: positive-trivial-tier1-001
 name: Trivial edit routes to Tier 1
-description: "Route software/project work through the Harness kernel: classify Tier 1/2/3, establish mandatory invariants, then let the agent choose tactics and domain skills. Use for software triage, routing, and re-routing; not general Q&A or non-software writing."
+description: "Route software/project work through the Harness kernel: classify Tier 1/2/3, surface planning guidance and applicable skills, then let the agent choose tactics. Use for software triage, routing, and re-routing; not general Q&A or non-software writing."
 tags:
   - positive-trigger
   - tier-1

package/evals/harness-everything/tasks/positive-tier2.yaml

@@ -1,6 +1,6 @@
 id: positive-standard-tier2-001
 name: Standard bug fix routes to Tier 2
-description: "Route software/project work through the Harness kernel: classify Tier 1/2/3, establish mandatory invariants, then let the agent choose tactics and domain skills. Use for software triage, routing, and re-routing; not general Q&A or non-software writing."
+description: "Route software/project work through the Harness kernel: classify Tier 1/2/3, surface planning guidance and applicable skills, then let the agent choose tactics. Use for software triage, routing, and re-routing; not general Q&A or non-software writing."
 tags:
   - positive-trigger
   - tier-2

package/evals/harness-everything/tasks/positive-tier3.yaml

@@ -1,6 +1,6 @@
 id: positive-macro-tier3-001
 name: Architectural task routes to Tier 3
-description: "Route software/project work through the Harness kernel: classify Tier 1/2/3, establish mandatory invariants, then let the agent choose tactics and domain skills. Use for software triage, routing, and re-routing; not general Q&A or non-software writing."
+description: "Route software/project work through the Harness kernel: classify Tier 1/2/3, surface planning guidance and applicable skills, then let the agent choose tactics. Use for software triage, routing, and re-routing; not general Q&A or non-software writing."
 tags:
   - positive-trigger
   - tier-3

package/evals/using-git-worktrees/tasks/positive-trigger.yaml

@@ -1,6 +1,6 @@
 id: positive-using-git-worktrees-001
 name: On-scope prompt triggers using-git-worktrees
-description: "Use when starting feature work needing isolation or before implementation plans - ensures an isolated workspace via native tools or git worktree fallback"
+description: "Use when starting feature work needing isolation or before implementation plans - recommends an isolated workspace via native tools or git worktree fallback"
 tags:
   - positive-trigger
 inputs:

package/fable-mode/SKILL.md

@@ -4,7 +4,7 @@ description: "Stage large, multi-source or multi-session tasks through a written
 license: Apache-2.0
 metadata:
   author: Miya Daniel
-  version: 0.13.0
+  version: 0.16.2
 ---
 
 # Fable Mode (v3)

package/fable-mode/agents/fable-orchestrator.md

@@ -53,12 +53,13 @@ overlap reject dispatch instead of becoming a verbal warning.
 
 The stage map remains a living orchestration document only inside those
 constraints. When new information invalidates it, re-plan and create revised
-stage contracts before dispatching new work. Replan budget comes from `workflowPlan.limits.maxReplans` and is accounted by
-the runtime controller. Re-enter through `workflow-disposition.js start`; a
-third full replan under the default budget is machine-blocked as
-`replan-budget-exhausted` instead of being only an orchestration reminder. Scope rule:
-deliver the task as specified; new scope discovered mid-run is surfaced as a
-recommendation at delivery, not silently built.
+stage contracts before dispatching new work. `workflowPlan.limits.maxReplans`
+is advisory orchestration guidance, not a machine-enforced counter. Re-enter
+through `workflow-disposition.js start`; after repeated replans, consider a
+zoom-out/reflection and keep the reason explicit, but do not block execution
+solely because an advisory count was reached. Scope rule: deliver the task as
+specified; new scope discovered mid-run is surfaced as a recommendation at
+delivery, not silently built.
 
 **2. Delegate by name and validated batch.** Every artifact-producing stage goes
 to a named agent via the Task tool:

package/fable-mode/execution-guardrails/SKILL.md

@@ -7,7 +7,7 @@ description: >-
 license: Apache-2.0
 metadata:
   author: Miya Daniel
-  version: 0.13.0
+  version: 0.16.2
 ---
 
 # Execution Guardrails

package/fable-mode/fable-haiku/SKILL.md

@@ -4,7 +4,7 @@ description: "Run staged fable work on Haiku for bulk mechanical tasks with expl
 license: Apache-2.0
 metadata:
   author: Miya Daniel
-  version: 0.13.0
+  version: 0.16.2
 ---
 
 # Fable Mode — Haiku

package/fable-mode/fable-opus/SKILL.md

@@ -4,7 +4,7 @@ description: "Run staged fable orchestration on Opus for cross-stage synthesis,
 license: Apache-2.0
 metadata:
   author: Miya Daniel
-  version: 0.13.0
+  version: 0.16.2
 ---
 
 # Fable Mode — Opus

package/fable-mode/fable-sonnet/SKILL.md

@@ -4,7 +4,7 @@ description: "Run staged fable work on Sonnet for non-trivial implementation, re
 license: Apache-2.0
 metadata:
   author: Miya Daniel
-  version: 0.13.0
+  version: 0.16.2
 ---
 
 # Fable Mode — Sonnet

package/fable-mode/scripts/workflow-plan-consumer.js

@@ -180,8 +180,9 @@ function dependencyBatches(stages, validateWrites, maxBatchSize = Infinity) {
   return batches;
 }
 
-function topologicalBatches(stages, maxWorkers) {
-  return dependencyBatches(stages, true, maxWorkers);
+function topologicalBatches(stages, _maxWorkers) {
+  // maxWorkers is an advisory planning hint, not a runtime concurrency lock (#190).
+  return dependencyBatches(stages, true);
 }
 
 function sequentialBatches(stages) {
@@ -197,7 +198,7 @@ function validateRouterPlan(routerContract) {
   if (plan.strategySelection !== 'selected') throw new Error(`workflow strategy is not selected: ${plan.strategySelection}`);
   if (!FABLE_STRATEGIES.has(plan.strategy)) throw new Error(`workflow strategy is not a Fable consumer topology: ${plan.strategy}`);
   if (plan.fallback && plan.fallback.disposition === 'blocked') {
-    throw new Error(`workflow plan is blocked: ${(plan.fallback.reasonCodes || []).join(', ') || 'unspecified reason'}`);
+    console.error(`[Fable Reminder] plan reports blocked/degraded capability: ${(plan.fallback.reasonCodes || []).join(', ') || 'unspecified reason'}`);
   }
   if (plan.strategy === 'fable-parallel' && (!plan.parallelism || plan.parallelism.allowed !== true)) {
     throw new Error('fable-parallel requires workflowPlan.parallelism.allowed=true');

package/harness-everything/SKILL.md

@@ -1,10 +1,10 @@
 ---
 name: harness-everything
-description: "Route software/project work through the Harness kernel: classify Tier 1/2/3, establish mandatory invariants, then let the agent choose tactics and domain skills. Use for software triage, routing, and re-routing; not general Q&A or non-software writing."
+description: "Route software/project work through the Harness kernel: classify Tier 1/2/3, surface planning guidance and applicable skills, then let the agent choose tactics. Use for software triage, routing, and re-routing; not general Q&A or non-software writing."
 license: Apache-2.0
 metadata:
   author: Miya Daniel
-  version: 0.13.0
+  version: 0.16.2
 ---
 
 # Harness Everything
@@ -19,20 +19,20 @@ Kernel routing entry.
 - General Q&A or non-software writing.
 
 ## Invariants
-1. **Route before execution** — establish scope/tier and the smallest applicable workflow.
-2. **Verify before claim** — require objective evidence.
-3. **Re-plan on repetition** — after 3 same-signature failures, use `zoom-out`.
+1. **Route before execution** — establish scope/tier and useful workflow guidance.
+2. **Verify before claim** — seek objective evidence before saying work is done.
+3. **Zoom out on repetition** — after 3 same-signature failures, use `zoom-out`.
 4. **Evaluate before omission** — read each suggested skill's `SKILL.md` before deciding applicability.
-5. **Resolve selected workflow** — model confidence is not an escape condition.
+5. **Keep agency** — workflow state and numeric limits guide; they do not hard-stop execution.
 
 ## Workflow
 1. Reuse kernel output, or run `node "<this-skill-dir>/scripts/kernel-router.js" "<prompt summary>"`.
 2. Surface the **Harness Routing Checkpoint**.
-3. Read each suggested `SKILL.md`; evaluate `USE FOR`, `DO NOT USE FOR`, workflow/basic flow, and hard rules. "Simple", "routine", names, or summaries alone cannot justify omission.
-4. Execute the selected workflow topology to resolution. Suggested skills are conditional on applicability; the selected topology is not advisory.
-5. If the workflow genuinely cannot represent part of the task, use the explicit escape with uncovered scope + evidence. Covered obligations remain mandatory.
-6. Complete only after applicable workflow obligations and objective verification resolve.
+3. Read each suggested `SKILL.md`; evaluate `USE FOR`, `DO NOT USE FOR`, workflow/basic flow, and hard rules.
+4. Use the selected topology as planning guidance. Choose, combine, reorder, or skip steps when evidence supports doing so.
+5. Prefer worktree isolation for broad/Tier-3 mutation and objective verification before completion.
+6. If guidance is not useful, explain the reason briefly and continue; no Harness reset is required.
 
-**Rule:** mandatory applicable workflow; flexible reasoning/implementation inside it; evidence-backed escape only for uncovered scope.
+**Rule:** guidance may become louder when evidence is weak, but only Rule-of-3 reflection and explicit user/host permission boundaries may block.
 
 Deep dive: <this-skill-dir>/references/triage-and-tiers.md

package/harness-everything/references/router-workflow-plan.md

@@ -54,14 +54,14 @@ If the structured contract is missing or invalid, the kernel emits a degraded/un
 | Strategy | Selection rule | Key invariants |
 |---|---|---|
 | `direct-single` | Tier 1 bounded/trivial task | scope lock, verify before claim |
-| `iterative-single` | Tier 2 ordinary diagnosis/TDD/tool loop | objective verification, explicit iteration budget |
+| `iterative-single` | Tier 2 ordinary diagnosis/TDD/tool loop | objective verification, advisory iteration guidance |
 | `fable-staged` | Tier 3 dependent work or parallel independence not proven | stage contracts, cold verifier |
 | `fable-parallel` | Tier 3 with explicit independent workstreams and read-only/disjoint write scope | stage contracts, parallel scope contract, synthesis barrier |
 | `fable-multi-agent-workspace` | durable multi-session task needing reusable specialists | workspace state, handoffs, stage contracts, cold verifier |
 
 Tier 3 alone never implies a persistent workspace. Likewise, an `independent` label alone is insufficient for `fable-parallel`: the write set must also be `read-only` or `disjoint`.
 
-The Phase 2 `iterative-single` loop budget is **8 iterations**. This is a policy bound chosen for control, not a measured optimum. It is separate from the rule-of-3 repeated-failure breaker.
+The Phase 2 `iterative-single` plan exposes **8 iterations** as advisory planning guidance, not a machine-enforced stop. Continue when evidence justifies it; the separate rule-of-3 repeated-failure reflection gate remains the hard boundary.
 
 ## Explicit user choice and prohibitions
 

package/harness-everything/references/triage-and-tiers.md

@@ -2,7 +2,7 @@
 
 Harness uses tiers to estimate scope and select the smallest sufficient execution topology. A tier is **not** a fixed TODO/TDD/Fable pipeline. Once the router selects an applicable topology, however, that topology becomes the run's execution contract.
 
-> Architecture rule: **Mandatory applicable workflow; flexible reasoning/implementation inside it; evidence-backed escape only for workflow-uncovered scope.**
+> Architecture rule: **Guidance-first workflow; flexible reasoning/implementation; only Rule-of-3 reflection and explicit permission boundaries may block.**
 
 ## 0. When Harness Routing Applies
 
@@ -43,7 +43,7 @@ The kernel protects lifecycle obligations without micromanaging model reasoning.
 2. **Verify before claim** — completion requires objective evidence appropriate to the change.
 3. **Re-plan on repetition** — after three same-signature failures, stop micro-retrying and use a fresh diagnosis / `zoom-out`.
 4. **Evaluate before omission** — when the router suggests a skill, read its complete `SKILL.md` entry/basic flow before deciding applicability.
-5. **Resolve selected workflow** — once a topology is selected, execute it to a resolved state; "simple", "routine", "already clear", or model confidence are not escape conditions.
+5. **Review selected workflow** — use the topology as planning guidance and keep any skipped step evidence-based.
 
 The model remains free to choose tools, implementation technique, decomposition details, and reasoning inside the workflow.
 
@@ -54,7 +54,7 @@ The model remains free to choose tools, implementation technique, decomposition
 - Every router-suggested skill when its evaluated flow is objectively not applicable.
 - Every optional deep-dive/reference linked from a skill.
 
-A suggested skill may resolve as `use`, `not-applicable`, or `unresolved/unavailable`. `not-applicable` needs a flow-grounded reason; a metadata-only or confidence-only judgement is insufficient. The selected **topology** is different: it is mandatory after selection unless an explicit workflow escape records genuinely uncovered scope plus evidence.
+A suggested skill may resolve as `use`, `not-applicable`, or `unresolved/unavailable`. `not-applicable` needs a flow-grounded reason; a metadata-only or confidence-only judgement is insufficient. The selected **topology** is planning guidance. Escape/replan metadata may still record why a suggested path was not followed, but it is not a lock.
 
 ## 2. Routing Mechanism
 
@@ -73,7 +73,7 @@ npx github:dyphn1/Harness-everything next "<brief prompt summary>"
 - compact **Harness Routing Checkpoint**,
 - required invariants,
 - suggested skills whose applicability must be evaluated,
-- **Workflow Execution Contract** for the selected topology.
+- **Workflow Guidance** for the selected topology.
 
 If `UserPromptSubmit` already ran the kernel this turn, reuse that output. Do not infer a silent Tier 1/direct path from missing or degraded routing.
 
@@ -90,12 +90,12 @@ A name, description, router summary, tier label, or generic "routine/common task
 
 ### Workflow escape contract
 
-Escape is an exception path, not an alternative default. Use it only when the selected topology genuinely cannot represent part of the task. The permitted reason codes are:
+Escape is audit metadata for a bounded guidance deviation. Use it only when the selected topology genuinely cannot represent part of the task. The permitted reason codes are:
 
 - `workflow-uncovered-scope` — the selected topology cannot represent a bounded part of the task;
 - `host-capability-unavailable` — the host lacks a capability required to execute the selected topology.
 
-Every escape must name a declared stage in the correlated run and record the reason code, uncovered scope, and evidence explaining the coverage/capability gap. The entire workflow never becomes escaped; isolation and independent verification cannot be waived. Covered workflow obligations remain mandatory. Host capability loss must be visible as degradation/blocked/escape evidence, never silently converted into optional execution.
+Every escape must name a declared stage in the correlated run and record the reason code, uncovered scope, and evidence explaining the coverage/capability gap. Host capability loss and missing isolation should remain visible as warnings/evidence, without creating a persistent execution lock.
 
 ## 3. Tier Guidance
 
@@ -117,7 +117,7 @@ When an evaluated skill is applicable, follow its workflow rather than reading i
 
 Typical shape: repository-wide/architectural work, large ambiguous requirements, cross-source synthesis, or bounded delegation.
 
-The router may select `fable-staged`, `fable-parallel`, or `fable-multi-agent-workspace`. A selected Fable topology is not advisory: enter its stage-contract lifecycle, honor dependency/write-set constraints, run objective checks, synthesize, cold-verify where required, and use bounded re-planning on failure.
+The router may select `fable-staged`, `fable-parallel`, or `fable-multi-agent-workspace`. A selected Fable topology is structured planning guidance: use its stages/dependencies/evidence when helpful, but do not convert missing lifecycle evidence into a persistent workflow lock.
 
 Tier 3 does **not** automatically mean multi-agent; the router still chooses the smallest sufficient topology.
 
@@ -140,11 +140,11 @@ This describes a reasoning policy. The workflow contract governs lifecycle oblig
 
 | Host mode | Expected behavior |
 |---|---|
-| Lifecycle hooks available | Kernel creates the selected workflow contract. Supported PreToolUse/Stop gates may mechanically prevent known bypasses. |
-| Advisory instructions only | Agent is instructed to establish and resolve the same contract, but the host cannot be described as mechanically enforcing it. |
+| Lifecycle hooks available | Kernel records selected workflow guidance. PreToolUse/Stop hooks emit reminders; Rule-of-3 and permission gates are the intentional blocking exceptions. |
+| Advisory instructions only | Agent receives the same routing/workflow guidance without lifecycle observations. |
 | Manual use | Invoke `harness-everything` / `harness next`, then execute the selected topology explicitly. |
 
-On Claude and the local OpenAI package, supported mutation hooks require Fable entry and Tier 3/Fable Git worktree isolation. Follow-up prompts preserve unresolved state. The router displays a session `workflow-stages.json` path and `workflow-disposition.js start` command; declare stages there before entry. Stop checks expected stage contracts plus correlated exit-zero/worker evidence. A retry records `blocked`, never false success. Direct/patch paths and explicit shell targets are checked, but arbitrary scripts are not sandboxed. Other selected topologies still rely on their applicable mechanisms (for example objective verification/stop gates) and shared contract text.
+On Claude and the local OpenAI package, supported hooks observe workflow/worktree/verification state and emit reminders. Rule-of-3 reflection and explicit action/permission gates remain separate blocking boundaries.
 
 Never turn mechanism/package evidence into a cross-host live-enforcement claim. #82 owns host-specific retained evidence.
 
@@ -163,7 +163,7 @@ For software/project work, surface this state before or with the first progress
 - Escape: <none | reason + uncovered scope + evidence>
 ```
 
-The checkpoint is state, not a universal response template. The key distinction is: **skill suggestions are evaluated for applicability; a selected workflow topology is executed to resolution.**
+The checkpoint is state, not a universal response template. The key distinction is: **skill suggestions are evaluated for applicability; a selected topology guides execution but does not trap it.**
 
 ## 7. Self-Healing and Dynamic Skills