harness-everything 0.7.0 → 0.8.1

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

@@ -7,7 +7,7 @@ description: >-
 license: Apache-2.0
 metadata:
   author: Miya Daniel
-  version: 0.4.0
+  version: 0.8.1
 ---
 
 # 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.4.0
+  version: 0.8.1
 ---
 
 # 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.4.0
+  version: 0.8.1
 ---
 
 # 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.4.0
+  version: 0.8.1
 ---
 
 # Fable Mode — Sonnet

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

@@ -209,7 +209,7 @@ function atomicWriteJson(filePath, value) {
   fs.renameSync(tempPath, filePath);
 }
 
-function prepareRun({ routerContract, stages, workspaceRoot, runId, sessionId = null }) {
+function prepareRun({ routerContract, stages, workspaceRoot, runId, sessionId = null, workflowId = null }) {
   const plan = validateRouterPlan(routerContract);
   const normalizedStages = validateStageGraph(stages || []);
   if (normalizedStages.length === 0) throw new Error('at least one stage contract is required');
@@ -237,6 +237,7 @@ function prepareRun({ routerContract, stages, workspaceRoot, runId, sessionId =
       planId,
       runId: resolvedRunId,
       sessionId: sessionId || null,
+      workflowId,
       workspaceRoot: root,
       ...stage,
       workerId: null,
@@ -252,6 +253,7 @@ function prepareRun({ routerContract, stages, workspaceRoot, runId, sessionId =
     planId,
     runId: resolvedRunId,
     sessionId: sessionId || null,
+    workflowId,
     workspaceRoot: root,
     workspaceKey: getWorkspaceKey(root),
     strategy: plan.strategy,

package/harness-everything/SKILL.md

@@ -4,41 +4,35 @@ description: "Route software/project work through the Harness kernel: classify T
 license: Apache-2.0
 metadata:
   author: Miya Daniel
-  version: 0.7.0
+  version: 0.8.1
 ---
 
 # Harness Everything
 
-Public/manual Harness kernel entry. Hook-capable hosts should run the kernel before peer/domain skill selection.
+Kernel routing entry.
 
 ## USE FOR:
-- Software triage/re-routing, including work that already names or strongly matches another skill.
-- Inspecting Tier, invariants, or suggestions.
+- Software/project triage, routing, re-routing, and workflow selection.
+- Work that names or matches another skill.
 
 ## DO NOT USE FOR:
 - General Q&A or non-software writing.
 
 ## Invariants
-
-1. **Route before execution** — establish scope/tier before mutation.
-2. **Verify before claim** — completion needs objective evidence.
-3. **Re-plan on repetition** — after 3 same-signature failures, stop micro-retrying and use `zoom-out`/fresh diagnosis.
-
-These rails are mandatory; Tier guidance is not a fixed pipeline.
+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`.
+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.
 
 ## Workflow
-
-1. Reuse current-turn kernel output, or run `node "<this-skill-dir>/scripts/kernel-router.js" "<prompt summary>"`.
-2. Ensure the emitted **Harness Routing Checkpoint** is user-visible: reuse a host-visible rendering or include it in the first progress/update message.
-3. Preserve the invariants.
-4. Treat suggested skills as advisory: choose, combine, reorder, or omit them as useful. If suggestions are non-empty and you use none, state one brief skip reason with the visible checkpoint/progress update.
-
-## Tier Guidance
-
-- **Tier 1:** Prefer direct execution.
-- **Tier 2:** TODO tracking, TDD, and verification are common suggestions.
-- **Tier 3:** Fable/multi-agent skills are optional when macro planning or delegation helps.
-
-**Rule:** enforce checkpoint visibility and workflow invariants, not workflow order; let the agent orchestrate itself inside those rails.
+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.
+
+**Rule:** mandatory applicable workflow; flexible reasoning/implementation inside it; evidence-backed escape only for uncovered scope.
 
 Deep dive: <this-skill-dir>/references/triage-and-tiers.md

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

@@ -1,8 +1,8 @@
 # Task Triage & Tier Details
 
-Harness uses tiers to estimate scope and surface useful capabilities. A tier is **not** a fixed pipeline. The runtime enforces a very small set of cross-cutting invariants and leaves tactics, skill choice, ordering, and delegation to the agent.
+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: **Do not enforce workflow order. Enforce workflow invariants.**
+> Architecture rule: **Mandatory applicable workflow; flexible reasoning/implementation inside it; evidence-backed escape only for workflow-uncovered scope.**
 
 ## 0. When Harness Routing Applies
 
@@ -10,51 +10,51 @@ Harness uses tiers to estimate scope and surface useful capabilities. A tier is
 flowchart TD
     U([User Prompt]) --> S{Software / project work?}
     S -- No --> B[Bypass Harness<br/>Answer naturally]
-    S -- Yes --> K[Harness Kernel<br/>classify scope + inject invariants]
-    K --> T{Tier recommendation}
-    T -- Tier 1 --> A1[Prefer direct execution]
-    T -- Tier 2 --> A2[Agent chooses useful domain skills]
-    T -- Tier 3 --> A3[Agent chooses planning / delegation if useful]
-    A1 --> E[Execute with agent-selected tactics]
-    A2 --> E
-    A3 --> E
-    E --> V{Objective evidence supports completion?}
-    V -- No --> R[Diagnose / iterate]
-    R --> F{Same-signature failure x3?}
-    F -- No --> E
-    F -- Yes --> Z[Zoom out / re-plan]
-    Z --> E
-    V -- Yes --> D([Claim completion])
+    S -- Yes --> K[Harness Kernel<br/>classify + select topology]
+    K --> W{Workflow selected?}
+    W -- No / deferred --> D[Preserve invariants<br/>choose smallest justified workflow]
+    W -- Yes --> A[ACTIVE workflow contract]
+    A --> G{Suggested skills?}
+    G -- Yes --> R[Read each suggested SKILL.md<br/>resolve applicability]
+    G -- No --> E[Execute selected workflow]
+    R --> E
+    E --> V{Required checks / stages resolved?}
+    V -- Yes --> O([Claim completion])
+    V -- No --> P[Diagnose / re-plan]
+    P --> X{Workflow covers next step?}
+    X -- Yes --> E
+    X -- No --> C[Record evidence-backed escape<br/>for uncovered scope only]
 ```
 
 ### Bypass Rules
 
 - **Pure chat, translation, general web search, non-software writing:** bypass Harness routing.
-- **Software engineering / codebase / project work:** establish the Harness Kernel contract before mutating work, even when the prompt already names a domain skill such as `tdd`, `security-review`, or `repo-docs`.
+- **Software engineering / codebase / project work:** establish the Harness Kernel contract before mutation, even when the prompt already names a domain skill.
 
-A host may auto-select a peer/domain skill. That selection must not be treated as proof that Harness routing already happened.
+Host skill selection is not proof that Harness routing already happened.
 
-## 1. The Minimal Harness Kernel
+## 1. Minimal Kernel Contract
 
-The kernel exists to keep strong models free while protecting the few behaviors that should not disappear under autonomous skill selection.
+The kernel protects lifecycle obligations without micromanaging model reasoning.
 
 ### Mandatory invariants
 
-1. **Route before execution** — establish task scope/tier before mutating software work.
-2. **Verify before claim** — completion claims require objective evidence appropriate to the change.
+1. **Route before execution** — establish task scope/tier and the smallest justified topology.
+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.
 
-These are the rails. Everything else is agent judgment unless the user or an authoritative project document explicitly requires it.
+The model remains free to choose tools, implementation technique, decomposition details, and reasoning inside the workflow.
 
 ### What is intentionally *not* mandatory
 
-- Loading `todo-driven-workflow` for every Tier 2/3 task.
-- Running TDD for changes where executable behavioral tests do not add value.
-- Entering Fable/multi-agent mode merely because the task is Tier 3.
-- Following a universal `TODO → TDD → verification-loop` or `Fable → subagent → verification-loop` sequence.
-- Loading `install-cognitive-os` as a peer skill before every other skill.
+- One universal `TODO → TDD → verification-loop` sequence for every Tier 2/3 task.
+- Multi-agent execution merely because a task is Tier 3.
+- Every router-suggested skill when its evaluated flow is objectively not applicable.
+- Every optional deep-dive/reference linked from a skill.
 
-`install-cognitive-os` remains the human-readable/manual entry point for the cognitive policy. Supported runtime integrations should establish the kernel invariants without depending on that skill being selected first.
+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.
 
 ## 2. Routing Mechanism
 
@@ -62,88 +62,67 @@ Use the public kernel entry point:
 
 ```bash
 node "<this-skill-dir>/scripts/kernel-router.js" "<brief prompt summary>"
+# or
+npx github:dyphn1/Harness-everything next "<brief prompt summary>"
 ```
 
-or:
+`kernel-router.js` delegates classification/guide discovery to `tier-router.js` and emits:
 
-```bash
-npx github:dyphn1/Harness-everything next "<brief prompt summary>"
-```
+- recommended tier + rationale,
+- structured workflow plan,
+- compact **Harness Routing Checkpoint**,
+- required invariants,
+- suggested skills whose applicability must be evaluated,
+- **Workflow Execution Contract** 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.
+
+### Suggestion applicability contract
+
+For every router-suggested skill:
+
+1. Read the complete `SKILL.md` entry.
+2. Evaluate `USE FOR`, `DO NOT USE FOR`, workflow/basic flow, and hard rules.
+3. Read extra material only when the entry explicitly requires it to decide applicability.
+4. Resolve the suggestion as `use`, `not-applicable`, or `unresolved/unavailable`.
 
-`kernel-router.js` delegates classification and guide discovery to `tier-router.js`, removes legacy fixed-pipeline instructions, and emits:
+A name, description, router summary, tier label, or generic "routine/common task" judgement is not enough to mark a suggestion not applicable. Using one suggestion does not resolve the others automatically.
 
-- the recommended tier and rationale,
-- a compact **Harness Routing Checkpoint**,
-- the **required Harness invariants**,
-- **suggested skills** marked advisory,
-- the policy that the agent may choose the smallest useful skill/tool set.
+### Workflow escape contract
 
-If a host's `UserPromptSubmit` integration already ran the kernel this turn, reuse that output rather than running it twice. The checkpoint must still become user-visible for software/project work: use the host's visible hook rendering when it has one, otherwise include the checkpoint in the first progress/update message.
+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:
 
-The tier classifier is heuristic. Treat its result as the default route, not an oracle. A clear task reading or explicit user instruction may override it; record the reason when doing so.
+- `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.
 
 ## 3. Tier Guidance
 
 ### Tier 1 — Trivial
 
-Typical shape:
-- typo/small documentation correction,
-- simple local code edit,
-- narrow explanation,
-- straightforward Git operation.
+Typical shape: typo/small docs correction, narrow local edit, bounded explanation, straightforward Git operation.
 
-Default behavior:
-- prefer direct execution,
-- avoid large plans and unnecessary delegation,
-- load a focused skill only when it materially improves the result,
-- still verify any completion claim with evidence appropriate to the change.
+Default topology is normally `direct-single`. Keep the lifecycle minimal, but still satisfy applicable scope/safety/verification obligations.
 
 ### Tier 2 — Standard
 
-Typical shape:
-- a specific feature or bug fix,
-- multi-file coordination,
-- behavioral changes needing tests,
-- focused benchmark/review work.
-
-Common **suggestions**, not a pipeline:
+Typical shape: specific feature/bug fix, multi-file coordination, behavioral change, focused benchmark/review.
 
-| Need observed in the task | Useful skill |
-|---|---|
-| Several verifiable steps need explicit tracking | `todo-driven-workflow` |
-| Behavior can be specified by executable tests | `tdd` |
-| Delivery needs systematic build/lint/test/diff evidence | `verification-loop` |
-| Auth/input/secrets/network boundaries are touched | `security-review` |
-| Isolated workspace would reduce risk | `using-git-worktrees` |
-| Quantitative scoring/benchmarking is requested | `eval-harness` |
+The router normally selects `iterative-single`: bounded reason/act work plus objective verification. It may surface `tdd`, `verification-loop`, `security-review`, `using-git-worktrees`, or other focused skills. Those suggestions are applicability decisions, not a universal sequence.
 
-The model decides which of these are useful and in what order. It may use none, one, or several while preserving the kernel invariants. If the router emitted one or more suggestions and the agent uses none of them, the visible checkpoint/progress update must include one brief skip reason; using at least one suggestion does not require explaining why the others were omitted.
+When an evaluated skill is applicable, follow its workflow rather than reading it and then discarding it because the implementation seems obvious.
 
 ### Tier 3 — Macro
 
-Typical shape:
-- repository-wide or architectural changes,
-- large ambiguous requirements,
-- broad documentation/system design,
-- work where deliberate delegation may reduce risk or improve coverage.
+Typical shape: repository-wide/architectural work, large ambiguous requirements, cross-source synthesis, or bounded delegation.
 
-Common **suggestions**, not a pipeline:
+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.
 
-| Need observed in the task | Useful skill |
-|---|---|
-| Deliberate macro planning / model-mode selection | `fable-mode`, `fable-discipline` |
-| Bounded parallel delegation genuinely helps | `multi-agent-workspace` |
-| Project-level docs need creation/update | `repo-docs` |
-| Important decisions need challenge before implementation | `grill-with-docs` |
-| Settled intent needs a spec | `to-spec` |
-| Settled work needs tracer-bullet issues | `to-tickets` |
-
-Tier 3 does **not** automatically require multi-agent execution. A strong model may complete macro work directly when that is the safer/smaller choice. The same all-skipped rationale rule applies when the router emitted suggestions.
+Tier 3 does **not** automatically mean multi-agent; the router still chooses the smallest sufficient topology.
 
 ## 4. Cognitive OS Relationship
 
-The cognitive loop remains useful:
-
 ```mermaid
 flowchart LR
     D[Discover] --> T[Think]
@@ -155,38 +134,42 @@ flowchart LR
     Z --> T
 ```
 
-But this diagram describes a reasoning policy, not a peer-skill dependency graph. Domain skills may implement their own local phases and gates. They do not need to invoke `install-cognitive-os` first as long as the Harness invariants remain satisfied.
+This describes a reasoning policy. The workflow contract governs lifecycle obligations; domain skills may define their own local phases inside it.
 
 ## 5. Host Integration and Enforcement Strength
 
 | Host mode | Expected behavior |
 |---|---|
-| Lifecycle hook available | Run the Harness Kernel on prompt submission so routing context exists before domain-skill execution. Surface the emitted checkpoint through a host-visible hook surface when supported; otherwise the agent carries it into the first visible progress/update. Hard gates may enforce supported invariants at tool/stop boundaries. |
-| Advisory instructions only | Tell the agent to run/reuse `harness next` before software mutation, surface the checkpoint, and run `harness verify` before completion. The behavior is advisory, not a hard host gate. |
-| Manual use | Invoke `harness-everything` or `install-cognitive-os` explicitly to inspect/re-establish and surface the contract. |
+| 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. |
+| 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.
 
-Never describe an advisory integration as hard enforcement. Platform-specific adapters may differ while preserving functional intent. Kernel emission alone is not proof that a host UI displayed the checkpoint; #82 live evidence owns that claim.
+Never turn mechanism/package evidence into a cross-host live-enforcement claim. #82 owns host-specific retained evidence.
 
 ## 6. Routing Checkpoint
 
-For software/project work, the kernel always emits a compact checkpoint and the execution surface must make it user-visible before or with the first progress update:
+For software/project work, surface this state before or with the first progress update:
 
 ```markdown
 ## 🚦 Harness Routing Checkpoint
 - Tier: Tier X — <reason>
 - Strategy: <selected/deferred strategy>
-- Required invariants: route-before-execution; verify-before-claim; re-plan-after-3-same-failures
-- Suggested skills: <deduplicated suggestions, or none>
-- Suggestion disposition: <using one or more | skipped all — brief reason>
+- Workflow state: <pending | running | satisfied | deferred | blocked>
+- Required invariants: <router invariants>
+- Suggested skills: <deduplicated suggestions or none>
+- Suggestion applicability: <use | not-applicable + reason | unresolved/unavailable>
+- Escape: <none | reason + uncovered scope + evidence>
 ```
 
-The checkpoint reports state; it does not prescribe a universal workflow. Suggested skills remain advisory. The only extra accountability rule is that a non-empty suggestion set cannot disappear silently: if every suggestion is skipped, state one brief reason. Do not add a skip explanation when at least one suggestion is used.
+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.**
 
 ## 7. Self-Healing and Dynamic Skills
 
-Existing self-heal, generated-skill discovery, knowledge-guide matching, and fact-audit behavior remain part of the classifier/runtime. They may recommend resources but should not silently convert recommendations into mandatory pipeline stages.
+Self-heal, generated-skill discovery, knowledge-guide matching, and fact-audit behavior remain part of the runtime. Dynamic recommendations still require applicability evaluation.
 
-If bootstrap reports missing integration touchpoints, use the existing self-heal command:
+If bootstrap reports missing integration touchpoints:
 
 ```bash
 node "<this-skill-dir>/scripts/self-heal.js"