harness-everything 0.3.6 → 0.4.1

package/docs/workflows/fable-mode.md

@@ -1,29 +1,85 @@
-# Workflow: Fable Mode
+# Workflow: Fable Mode (v3)
 
-> Macro-task planning and execution engine. Like all Harness workflows, this is not a straight line to success. It requires continuous verification and course correction.
+> Stage large, multi-source or multi-session work through an explicit stage map, named agents, failable per-stage checks, and skeptical delivery review. Fable is not the default path for ordinary Tier 2 work.
 
 ---
 
-## 1. Skill Behavior Workflow
+## 1. When Fable Mode Applies
 
-This section visualizes how `fable-mode` handles macro tasks. Subagent failure or integration crashes are expected realities, not edge cases.
+Use `fable-mode` when the work is large enough that one undifferentiated execution loop would lose scope or evidence: multi-file architectural work, multi-source investigation, multi-session execution, or an explicit `fable on haiku|sonnet|opus` request.
 
 ```mermaid
-graph TD
-  Start([Tier 3 Macro Task Triggered]) --> Discovery["1. Discovery & Architectural Plan"]
-  Discovery --> InitTodo["2. Delegate Roadmap to todo-driven-workflow"]
-  
-  InitTodo --> Delegate{3. Delegate Sub-tasks}
-  Delegate -->|Sub-agent Tool Available| SpawnSub["Spawn Sub-agent via multi-agent-workspace"]
-  Delegate -->|No Sub-agent Tool| InlinePersona["Inline Persona Role-Switch Fallback"]
-  
-  SpawnSub --> ScopeCheck["Monitor via hooks/scripts/subagent-scope-guard.js"]
-  InlinePersona --> ScopeCheck
-  
-  ScopeCheck --> VerifyStep["4. Integration Verification via harness-everything/scripts/verify-gate.js"]
-  VerifyStep --> CheckGate{Integration Verification Passed?}
-  
-  CheckGate -->|No: Integration Error| FixBlocker["Add Blocker Item to todo-driven-workflow & Fix"] --> VerifyStep
-  CheckGate -->|Yes: Gate Passes| Transition["5. Transition Scaffolding to TDD Iteration"]
-  Transition --> End([Macro Scaffolding Successfully Deployed])
+flowchart TD
+  Request[User request] --> Scope{Large / multi-source / multi-session?}
+  Scope -->|No| Normal[Use the normal Harness execution path]
+  Scope -->|Yes| Discover[Discover runtime + authorized file scope]
+  Discover --> Map[Write numbered stage map]
+  Map --> Run[Execute one stage at a time]
 ```
+
+`fable-mode` does **not** imply a mandatory `todo-driven-workflow → TDD` pipeline. Each stage chooses only the tactics and domain skills needed for its own artifact and pass condition.
+
+## 2. Stage Contract
+
+Every stage owns one concrete artifact and one explicit pass condition. A stage is not complete because an agent says it is complete; its named check must pass.
+
+```mermaid
+stateDiagram-v2
+  [*] --> Planned
+  Planned --> Running: artifact + pass condition defined
+  Running --> Verifying: stage work produced
+  Verifying --> Passed: named check passes
+  Verifying --> Blocked: check fails / unresolved dependency
+  Blocked --> Running: blocker resolved
+  Passed --> Reviewed: cold review when risk warrants it
+  Reviewed --> Recorded: audit record written
+  Recorded --> [*]
+```
+
+The stage record preserves the requested/effective model, fallback reason, stage brief, artifact, pass condition, verification command, and verifier result.
+
+## 3. Model Selection and Delegation
+
+Explicit model requests are resolved through `model-selector.js`. Fable never silently downgrades a requested model.
+
+```mermaid
+flowchart LR
+  Requested[Requested model] --> Selector[model-selector.js]
+  Selector -->|Available| Named[Named fable agent]
+  Selector -->|Fallback allowed| Fallback[Recorded fallback]
+  Selector -->|No valid fallback| Blocked[Escalate blocked stage]
+  Named --> Stage[Bounded stage brief]
+  Fallback --> Stage
+  Stage --> Verify[Named stage check]
+  Verify -->|High-stakes artifact| Cold[fable-verifier cold review]
+  Verify -->|Ordinary artifact| Record[Record evidence]
+  Cold --> Record
+```
+
+The intended role split is explicit rather than magical: Opus is suitable for orchestration, Sonnet for reasoning-heavy stage work, and Haiku for bounded mechanical work. Workers do not spawn workers.
+
+## 4. Scope and Context Discipline
+
+`fable-discipline` acts as the shadow guard while Fable is active. A worker receives the current stage contract and authorized scope, not the entire unresolved history.
+
+```mermaid
+flowchart TD
+  Stage[Current stage contract] --> Worker[Named worker]
+  Worker --> Scope{Stayed inside authorized scope?}
+  Scope -->|No| Block[Stop + report scope violation]
+  Scope -->|Yes| Check[Run stage verification]
+  Check -->|Fail| Diagnose[Record blocker / diagnose]
+  Diagnose --> Replan{Need full replan?}
+  Replan -->|No| Worker
+  Replan -->|Yes, max two| Map[Update stage map]
+  Map --> Worker
+  Check -->|Pass| Handoff[Compact evidence + handoff]
+```
+
+At most two full replans are allowed before unresolved blockers are escalated rather than hidden behind endless restructuring.
+
+## 5. Completion Boundary
+
+Fable completion means the planned stages have produced their artifacts, their checks have passed, and high-risk outputs have received skeptical review where required. It does not mean every possible companion skill was invoked.
+
+The canonical executable and policy details live in `fable-mode/SKILL.md`, `fable-mode/model-matrix.json`, `fable-mode/scripts/model-selector.js`, and `fable-mode/references/model-matrix.md`.

package/docs/workflows/find-skills.md

@@ -34,3 +34,43 @@ flowchart TD
 If search, network, or application fails, report the failure and continue with
 the direct built-in solution. Never treat an unaudited third-party skill as a
 first-party Harness skill or add it to the static manifest.
+
+## Lazy-loading and trust boundary
+
+The local catalog is the first source of truth. A candidate is inspected
+before approval, and the detailed body is loaded only after the user agrees
+to apply it.
+
+```mermaid
+sequenceDiagram
+  participant Agent
+  participant Catalog as Local catalog
+  participant Search as skills.sh / npx
+  participant User
+  Agent->>Catalog: Check existing coverage
+  alt Covered locally
+    Catalog-->>Agent: Return the local skill
+  else Missing locally
+    Agent->>Search: Find candidates
+    Search-->>Agent: Return source and metadata
+    Agent->>User: Present candidate for approval
+    User-->>Agent: Approve or decline
+    Agent->>Agent: Load body only after approval
+  end
+```
+
+## Failure handling
+
+Search and application are optional edges. A failed edge returns control to a
+direct solution without changing the static catalog.
+
+```mermaid
+flowchart TD
+  Search[Search candidate] --> Inspect[Inspect source and trust signal]
+  Inspect -->|Unsafe or unclear| Decline[Decline and use built-in path]
+  Inspect -->|Acceptable| Approval{Human approval?}
+  Approval -->|No| Decline
+  Approval -->|Yes| Apply[Apply for the session]
+  Apply -->|Failure| Decline
+  Apply -->|Success| Verify[Verify the applied skill]
+```

package/docs/workflows/grill-with-docs.md

@@ -19,10 +19,10 @@ graph TD
   UpdateGlossary --> ResolveADRPath{Resolve ADR Storage Path}
   
   ResolveADRPath -->|docs/adr/ or CONTEXT-MAP.md Exists| WriteDocs["Write ADR to docs/adr/ or CONTEXT-MAP.md Location"]
-  ResolveADRPath -->|No Folder Found| WritePlatform["Write to .github/harness-everything/adr/ or Delegate to to-spec"]
+  ResolveADRPath -->|No Folder Found| WriteFallback["Write to committable docs/adr"]
   
   WriteDocs --> ToSpec["Hand off to to-spec for Outline Preview & Spec/ADR Publishing"]
-  WritePlatform --> ToSpec
+  WriteFallback --> ToSpec
   ToSpec --> End([Route to to-tickets / fable-mode / tdd])
 ```
 

package/docs/workflows/multi-agent-workspace.md

@@ -9,17 +9,28 @@ Discover target + source
         |
 Validate divisions, frontmatter, names, slugs, revision, platform
         |
-Scaffold .harness/multi-agent/
-  state / logs / decisions / domain / architecture / roles
+Resolve global runtime + repository document paths
         |
-Write router + catalog + selected roles + launcher + handoff
+Write global manifest/handoff + selected roles
         |
-Run generated index_memory.js -> memory-index.md
+Run installed immutable index_memory.js -> global memory-index.md
+```
+
+```mermaid
+flowchart TD
+    Source[Optional agency source] --> Validate[Validate metadata and selection]
+    Validate --> Resolve[Shared project-docs resolver]
+    Resolve --> Runtime[Global workspace-keyed runtime]
+    Resolve --> Docs[Committable decision/domain/architecture paths]
+    Runtime --> Router[Installed immutable skill]
+    Runtime --> Indexer[Installed immutable indexer]
+    Router --> Handoff[Manifest and handoff]
+    Indexer --> Memory[Global memory index]
 ```
 
 ## Selection contract
 
-Use `--agency-source <path>` or `AGENCY_AGENTS_SOURCE`. Select by repeated
+Use `--workspace <path>` plus `--agency-source <path>` or `AGENCY_AGENTS_SOURCE`. Select by repeated
 `--division` or `--agent`; `--all-agents` is explicit and metadata-only. The
 generated launcher lists each selected role's division, source-relative file,
 description, and boundary. Specialist bodies are loaded only on demand after a
@@ -31,12 +42,13 @@ No source creates a visible `agency.status: unavailable` fallback. Invalid
 frontmatter, missing or empty divisions, duplicate names/slugs, unknown
 agents, and unsupported platforms fail before output is written. A changed
 source revision requires `--allow-source-drift` to refresh a Harness-owned
-catalog. Existing generated artifacts require `--force` only when they are
-not identical.
+catalog. Runtime artifacts are regenerated under the global workspace key;
+authored document conflicts fail before migration.
 
 ## Handoff
 
 The launcher and `handoff.json` require `status`, `changes`, `verification`,
-`risks`, and `nextAction`. The immutable generated router directs agents to
-the six zones and forbids router edits. Fable remains responsible for macro
-planning; TDD remains responsible for ordinary feature implementation.
+`risks`, and `nextAction`. The global manifest carries resolved paths, selected
+roles, and execution metadata; the installed skill and indexer remain
+immutable. Fable remains responsible for macro planning; TDD remains
+responsible for ordinary feature implementation.

package/docs/workflows/self-evolve.md

@@ -40,3 +40,36 @@ After resolving a recurring Windows path error, the agent summarizes the cause,
 - [ ] No raw transcript, secret, or one-off detail was persisted.
 - [ ] Rule/dynamic-skill classification and deduplication passed.
 - [ ] Self-regression passed before the memory or manifest changed.
+
+## Persistence boundary
+
+The host supplies selected evidence. `self-evolve` receives only that brief,
+then chooses a small rule or a reusable skill. It never scans transcript
+stores on its own.
+
+```mermaid
+flowchart LR
+  Host[Host evidence and root cause] --> Classify{Reusable procedure?}
+  Classify -->|No| Rule[Persist a concise rule]
+  Classify -->|Yes| Draft[Load skill-creator and draft a skill]
+  Rule --> Gate[Deduplicate and quality-check]
+  Draft --> Gate
+  Gate -->|Pass| Record[Write the selected memory or manifest]
+  Gate -->|Fail| Stop[Leave state unchanged]
+```
+
+## Persistence outcomes
+
+The decision is made from the lesson, not from transcript discovery. A long
+existing memory is split into a topic file and reached through a pointer.
+
+```mermaid
+flowchart TD
+  Lesson[Resolved lesson] --> Existing{Matching workspace memory?}
+  Existing -->|Short enough| Append[Append the defensive rule]
+  Existing -->|Too long| Split[Create topic memory and pointer]
+  Existing -->|No| Fallback[Choose the workspace fallback]
+  Fallback --> Append
+  Append --> Verify[Run the relevant gate]
+  Split --> Verify
+```

package/docs/workflows/tdd.md

@@ -40,3 +40,39 @@ graph TD
   
   VerifyRefactor -->|Exit 0| End([Feature verified & completed])
 ```
+
+## Profile boundary
+
+The profile describes the boundary crossed by the behavior under test. The
+RED/GREEN/REFACTOR loop remains the same; only the evidence and fixtures
+change.
+
+```mermaid
+flowchart TD
+  Behavior[Behavior under test] --> Boundary{External process or service boundary?}
+  Boundary -->|No| Unit[Unit profile]
+  Boundary -->|Yes| Integration[Integration profile]
+  Unit --> Loop[RED -> GREEN -> REFACTOR]
+  Integration --> Loop
+  Loop --> Evidence[Run tests and score evidence]
+  Evidence -->|Gate fails| Loop
+  Evidence -->|All gates pass| Done([Verified behavior])
+```
+
+## Recovery state
+
+The circuit breaker limits repeated edits. A third failed GREEN attempt moves
+the work into `zoom-out`, where the assumptions are rebuilt before retrying.
+
+```mermaid
+stateDiagram-v2
+  [*] --> Red
+  Red --> GreenAttempt
+  GreenAttempt --> Green: tests pass
+  GreenAttempt --> Retry: tests fail
+  Retry --> GreenAttempt: attempts one or two
+  Retry --> ZoomOut: attempt three
+  ZoomOut --> Red: assumptions rebuilt
+  Green --> Refactor
+  Refactor --> [*]
+```

package/docs/workflows/todo-driven-workflow.md

@@ -32,3 +32,36 @@ graph TD
 
 The repository has no TODO CLI state machine. This keeps progress portable,
 host-native, and transparent across sessions.
+
+## Blocker loop
+
+One milestone owns the active work. A failed check updates that milestone and
+returns to execution; it does not silently advance the rest of the list.
+
+```mermaid
+flowchart LR
+  Active[One milestone in progress] --> Execute[Execute bounded scope]
+  Execute --> Verify[Run named verification]
+  Verify -->|Pass| Record[Record evidence and complete]
+  Verify -->|Fail| Blocker[Record blocker and update plan]
+  Blocker --> Active
+  Record --> More{More milestones?}
+  More -->|Yes| Active
+  More -->|No| Done([Finish])
+```
+
+## Ownership state
+
+The checklist makes ownership visible from planning through completion.
+
+```mermaid
+stateDiagram-v2
+  [*] --> Planned
+  Planned --> InProgress
+  InProgress --> Verifying
+  Verifying --> Complete: check passes
+  Verifying --> Blocked: check fails
+  Blocked --> InProgress: plan updated
+  Complete --> InProgress: milestones remain
+  Complete --> [*]: no milestones remain
+```

package/environment-detection/SKILL.md

@@ -4,7 +4,7 @@ description: Use at session start (Discover phase) to detect and align with the
 license: Apache-2.0
 metadata:
   author: Miya Daniel
-  version: 0.3.4
+  version: 0.4.0
 ---
 
 # Environment Detection & Shell Alignment
@@ -25,11 +25,11 @@ Boundary: operate solely within `process.cwd()`; ignore other workspaces, histor
 ## Workflow
 
 1. Preflight from this skill's own directory; parse OS, shell, available CLIs: `node "<this-skill-dir>/scripts/preflight.js"`
-2. Self-heal harness touchpoints (idempotent): `node "<skills-repo-root>/harness-everything/scripts/self-heal.js"` — audits `.claude/settings.json`, `.cursorrules`, `.github/copilot-instructions.md`, `AGENTS.md`.
+2. Self-heal harness touchpoints (idempotent): `node "<skills-repo-root>/harness-everything/scripts/self-heal.js"` — audits `<workspace>/.claude/settings.json`, `<workspace>/.cursorrules`, `<workspace>/.github/copilot-instructions.md`, `<workspace>/AGENTS.md`.
 3. Adopt syntax: Git Bash → forward `/`, `$VAR`, Unix cmds (`ls`, `rm -rf`), never `dir`/`del`/PowerShell · PowerShell → `$env:VAR`, cmdlets · CMD → `\`, `%VAR%`, `dir`/`del`/`copy`, never Unix.
 4. On failure don't blindly retry — suspect wrong-shell syntax. Three failures → trigger `zoom-out`.
 
-Deep dive: references/shell-syntax-rules.md
+Deep dive: <this-skill-dir>/references/shell-syntax-rules.md
 
 ## USE FOR:
 - session-start OS/shell/toolchain detection

package/eval-harness/SKILL.md

@@ -4,7 +4,7 @@ description: Evaluate AI agent performance across correctness, token efficiency,
 license: Apache-2.0
 metadata:
   author: Miya Daniel
-  version: 0.3.6
+  version: 0.4.0
 ---
 
 # Eval Harness
@@ -17,15 +17,15 @@ Evaluate an agent log with a four-dimension scorecard.
 | :--- | :--- |
 | **Trigger / Input** | A benchmark request and an execution log or conversation history. |
 | **Expected Output** | A 0–10 scorecard for correctness, efficiency, anti-loop focus, and environment awareness. |
-| **State Mutations** | Writes the scorecard under `evals/` or `.github/harness-everything/evals/`. |
-| **Enforcement Gate** | Run `scripts/evaluate.js`; use the documented fallback only if it fails or is missing. |
+| **State Mutations** | Writes the scorecard under `<workspace>/evals/` or `<workspace>/.github/harness-everything/evals/`. |
+| **Enforcement Gate** | Run `<this-skill-dir>/scripts/evaluate.js`; use the documented fallback only if it fails or is missing. |
 
 ## Workflow
 
 1. Parse actions, errors, tokens, and timing from the log.
-2. Score all four dimensions using `references/scoring-rubric.md`.
-3. Run `node scripts/evaluate.js <A> <B> <C> <D> "insights"`.
-4. If the script fails, write `evals/scorecard.md` (or the `.github` fallback).
+2. Score all four dimensions using `<this-skill-dir>/references/scoring-rubric.md`.
+3. Run `node <this-skill-dir>/scripts/evaluate.js <A> <B> <C> <D> "insights"`.
+4. If the script fails, write `<workspace>/evals/scorecard.md` (or the `<workspace>/.github` fallback).
 
 ## USE FOR:
 
@@ -39,4 +39,4 @@ Evaluate an agent log with a four-dimension scorecard.
 - General review without scoring dimensions.
 - Tasks without an execution log.
 
-Deep dive: `references/scoring-rubric.md`
+Deep dive: `<this-skill-dir>/references/scoring-rubric.md`

package/eval-harness/scripts/evaluate.js

@@ -1,6 +1,12 @@
 #!/usr/bin/env node
 const fs = require('fs');
 const path = require('path');
+let getWorkspaceRoot;
+try {
+  ({ getWorkspaceRoot } = require('../../scripts/lib/workspace'));
+} catch (err) {
+  getWorkspaceRoot = () => null;
+}
 
 const args = process.argv.slice(2);
 
@@ -50,17 +56,13 @@ for (const [dim, score] of Object.entries(scores)) {
 markdown += `| **Total Score** | **${total}/40** |\n\n`;
 markdown += `### Insights\n${insights}\n\n---\n`;
 
-function getWorkspaceRoot() {
-  let dir = path.resolve(process.cwd());
-  while (dir !== path.parse(dir).root) {
-    if (fs.existsSync(path.join(dir, '.git'))) return dir;
-    dir = path.dirname(dir);
-  }
-  return process.cwd();
-}
-
 // Store the evaluations in an evals folder in the project root
-const evalDir = path.join(getWorkspaceRoot(), 'evals');
+const workspaceRoot = getWorkspaceRoot();
+if (!workspaceRoot) {
+  console.error('[eval-harness] Cannot write an evaluation report without a resolved git workspace.');
+  process.exit(1);
+}
+const evalDir = path.join(workspaceRoot, 'evals');
 if (!fs.existsSync(evalDir)) {
   fs.mkdirSync(evalDir, { recursive: true });
 }

package/evals/evaluation-reports.md

@@ -0,0 +1,14 @@
+## Harness Evaluation Report - 2026-08-31T14:29:33.829Z
+
+| Dimension | Score |
+|---|---|
+| Correctness & Factuality | 10/10 |
+| Token & Step Efficiency | 5/10 |
+| Anti-loop & Focus | 10/10 |
+| Environment & Tool Awareness | 10/10 |
+| **Total Score** | **35/40** |
+
+### Insights
+Repository-grounded audit. Environment preflight passed. Core npm test and 9 mechanism suites passed after npm ci, but routing misclassified this macro evaluation request as Tier 1; waza was unavailable; behavioral validation has 3 invalid case files; existing 37 Harness-only live records are 26/37 pass and 9/15 pressure pass; the fresh Claude runner case was invalid because shell:true truncated the prompt to Add.; no causal benchmark case proved vanilla fail to Harness pass.
+
+---

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: "Triage new software requests into Tier 1/2/3 before work begins. USE FOR: \"triage a new software task\", \"route this coding request\". DO NOT USE FOR: \"chat or general Q&A\", \"non-software writing\", \"a skill is already indicated\"."
+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."
 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: "Triage new software requests into Tier 1/2/3 before work begins. USE FOR: \"triage a new software task\", \"route this coding request\". DO NOT USE FOR: \"chat or general Q&A\", \"non-software writing\", \"a skill is already indicated\"."
+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."
 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: "Triage new software requests into Tier 1/2/3 before work begins. USE FOR: \"triage a new software task\", \"route this coding request\". DO NOT USE FOR: \"chat or general Q&A\", \"non-software writing\", \"a skill is already indicated\"."
+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."
 tags:
   - positive-trigger
   - tier-3

package/evals/install-cognitive-os/tasks/positive-trigger.yaml

@@ -1,6 +1,6 @@
 id: positive-install-cognitive-os-001
 name: On-scope prompt triggers install-cognitive-os
-description: "Defines the fundamental physical laws of behavior — Discover, Think, Try, Summarize, Record — for all Agents. Use this loop before acting on any task to ground progress in verified tool output."
+description: "Explain or explicitly apply the Harness cognitive policy: Discover, Think, Try, Summarize, Record. It provides cross-cutting behavior without requiring this skill to be selected before domain skills."
 tags:
   - positive-trigger
 inputs:

package/fable-discipline/SKILL.md

@@ -4,7 +4,7 @@ description: Enforce fable-mode's context discipline as a shadow guard. Use when
 license: Apache-2.0
 metadata:
   author: Miya Daniel
-  version: 0.3.6
+  version: 0.4.0
 ---
 
 # Fable Discipline (Macro Task Discipline & Safety Net)
@@ -38,4 +38,4 @@ Shadow guard for `fable-mode`: MUST run in the background for its whole duration
 3. **Agent handoff**: Outgoing agents MUST leave a state manifest (completed APIs, expected inputs/outputs); incoming agents MUST verify it first.
 4. **Circuit breaker**: If build errors diverge, HALT, call `zoom-out`, and map the error dependency graph for the human.
 
-Deep dive: references/discipline-rules.md
+Deep dive: <this-skill-dir>/references/discipline-rules.md