harness-everything 0.2.2 → 0.4.0

package/docs/security-audit.md

@@ -0,0 +1,38 @@
+# Security Audit: Verifier Boundaries
+
+Date: 2026-09-10
+
+## Scope
+
+The audit covers `scripts/lib/path-boundary.js` and
+`scripts/lib/execution-contract.js`, which are shared by later verifier,
+workspace, installer, and plugin fixes. The standalone consumers also have
+focused regressions for archive output, legacy migration, global installation,
+fixture construction, and reflection patch authorization.
+
+## STRIDE and abuse cases
+
+| Threat | Abuse case | Boundary |
+|---|---|---|
+| Tampering | A junction or symlink below an output root redirects a new file outside it. | Resolve the deepest existing ancestor and reject link components below the root. |
+| Tampering | `..` or an absolute patch path escapes the repository allowlist. | Normalize repository-relative paths and reject traversal/absolute paths. |
+| Information disclosure | A verifier treats a path fragment as proof that a different command ran. | Compare the complete normalized command or exact argv. |
+| Elevation of privilege | A mixed patch includes one allowed file and one unrelated file. | Require every parsed patch path to be authorized; reject the entire patch otherwise. |
+| Repudiation | A caller cannot distinguish an outside path from a link alias. | Stable error codes identify the rejected boundary condition. |
+
+## Residual risks
+
+- Callers must still use the returned physical target and perform the check
+  immediately before the filesystem operation; a check done earlier can be
+  invalidated by a time-of-check/time-of-use race.
+- The helper does not grant permission to choose a boundary root. Consumers
+  must establish that the root itself is trusted before calling it.
+- Live model behavioral evidence remains an environment/acceptance concern and
+  is not manufactured by these deterministic helpers.
+
+## Verification
+
+`ci/mechanism-2v-verifier-boundaries.test.js` covers normal paths, traversal,
+junction/symlink escapes, missing leaves, Windows casing, exact commands, and
+all-or-nothing patch authorization. `npm run test:mutations` then verifies that
+eight corresponding production protections are load-bearing.

package/docs/troubleshooting.md

@@ -0,0 +1,320 @@
+# Harness OS Troubleshooting Guide
+
+This guide helps you resolve common issues with Harness OS installation and usage. Platform enforcement claims follow [platform-capabilities.md](platform-capabilities.md).
+
+## Installation Issues
+
+### Permission Denied Errors
+
+**Symptom:** `EACCES: permission denied` during installation
+
+**Solution:**
+```bash
+# Option 1: Install without sudo (recommended)
+npx github:dyphn1/Harness-everything install
+
+# Option 2: If you need global installation
+npx github:dyphn1/Harness-everything install --global
+
+# Option 3: Fix npm permissions (if using npm)
+mkdir ~/.npm-global
+npm config set prefix '~/.npm-global'
+export PATH=~/.npm-global/bin:$PATH
+```
+
+### Node.js Version Issues
+
+**Symptom:** `SyntaxError` or unsupported engine errors
+
+**Solution:**
+```bash
+# Check your Node.js version
+node --version
+
+# Harness requires Node.js 18 or higher
+# Update using nvm (recommended):
+nvm install 18
+nvm use 18
+
+# Or download from https://nodejs.org/
+```
+
+### Network Issues
+
+**Symptom:** `npm ERR! network` or timeout errors
+
+**Solution:**
+```bash
+# Check your internet connection
+npm ping
+
+# Try with different registry
+npm config set registry https://registry.npmjs.org/
+
+# Clear npm cache
+npm cache clean --force
+
+# Use yarn instead
+yarn install
+```
+
+## Hook Issues
+
+### Hooks Not Firing (Claude Code)
+
+**Symptom:** Harness rules not being enforced
+
+**Solution:**
+1. Verify hooks are installed:
+   ```bash
+   cat .claude/settings.json | grep -A 10 "hooks"
+   ```
+2. Check hook file permissions:
+   ```bash
+   ls -la hooks/scripts/*.js
+   ```
+3. Restart Claude Code session.
+
+### Hook Execution Errors
+
+**Symptom:** `Error: Cannot find module` or similar
+
+**Solution:**
+```bash
+# Verify Node.js is in PATH
+which node
+
+# Check if hooks directory exists
+ls -la hooks/scripts/
+
+# Reinstall Harness
+npx github:dyphn1/Harness-everything uninstall
+npx github:dyphn1/Harness-everything install
+```
+
+### Circuit Breaker Tripping Too Often
+
+**Symptom:** `RULE OF 3 CIRCUIT BREAKER TRIGGERED!` frequently
+
+**Solution:**
+1. This is normal behavior on an integration surface that actually packages the circuit-breaker hooks: Harness is protecting you from infinite loops.
+2. Follow the zoom-out instructions in the error message.
+3. If it's a false positive on the Claude Code hook path, check the error signature:
+   ```bash
+   cat .claude/harness-everything/state/sessions/default/rule-of-3-state.json
+   ```
+4. Reset if needed:
+   ```bash
+   npm run harness:reset
+   ```
+
+Do not expect this Claude Code state file merely because Harness skills or an instruction-only platform integration are installed.
+
+## Platform-Specific Issues
+
+### Cursor Not Showing Rules
+
+**Symptom:** `.cursorrules` file not created
+
+**Solution:**
+1. Verify file exists:
+   ```bash
+   cat .cursorrules | head -20
+   ```
+2. If missing, reinstall with Cursor flag:
+   ```bash
+   npx github:dyphn1/Harness-everything install --cursor
+   ```
+3. Restart Cursor.
+
+### Copilot Not Following Rules
+
+**Symptom:** GitHub Copilot ignoring Harness guidance
+
+**Solution:**
+1. Check file exists:
+   ```bash
+   cat .github/copilot-instructions.md | head -20
+   ```
+2. Ensure Copilot is using the instructions file.
+3. Restart VS Code/GitHub Copilot.
+
+### Codex advisory installer / AGENTS.md issues
+
+**Symptom:** Codex does not appear to receive the general installer guidance.
+
+**Solution:**
+1. Check `AGENTS.md` exists and contains Harness guidance:
+   ```bash
+   cat AGENTS.md | head -20
+   ```
+2. Reinstall the advisory Codex target if needed:
+   ```bash
+   npx github:dyphn1/Harness-everything install --codex
+   ```
+3. Remember that this is the instruction-oriented installer path. It is different from the **local OpenAI plugin** package described below.
+
+### Codex / local OpenAI plugin not appearing
+
+**Symptom:** The Harness plugin is missing from the local Plugins Directory, skills are stale, or packaged lifecycle behavior does not reflect the current repository package.
+
+**Checks:**
+```bash
+npm run plugin:sync
+npm run test:plugin:openai
+```
+
+Then verify the repository contains:
+
+```text
+.agents/plugins/marketplace.json
+plugins/harness-everything/.codex-plugin/plugin.json
+plugins/harness-everything/hooks/hooks.json
+plugins/harness-everything/hooks/session-start.js
+plugins/harness-everything/skills/
+```
+
+If those checks pass but the host still shows an older copy:
+
+1. Refresh/sync the imported marketplace or repository plugin in the host.
+2. Restart/refresh the local ChatGPT/Codex host if it cached the plugin package.
+3. Start a **new chat/session** before judging `SessionStart` or `UserPromptSubmit` behavior.
+4. Re-review/trust changed command hooks if the host asks again after hook definitions changed.
+
+The local plugin mechanically injects the session policy and invariant-first routing contract, and its package includes mechanism-tested supported-tool, subagent, and stop adapters. If those events do not appear in a live session, verify the host loaded the current package and that changed command hooks were reviewed/trusted; package tests alone cannot prove host loading.
+
+See [openai-plugin.md](openai-plugin.md) for installation and validation details.
+
+### Public OpenAI Skills-only plugin behaves differently from local Codex plugin
+
+**Symptom:** A public/reviewer Skills-only install does not run local `.codex-plugin` lifecycle hooks.
+
+**Expected behavior:** This is by design. The public Skills-only upload contains reusable skills and referenced assets, but not the local `.codex-plugin` lifecycle hooks. Validate public behavior with:
+
+```bash
+npm run plugin:submission:build
+npm run test:plugin:submission
+```
+
+Do not troubleshoot a missing `SessionStart` or `UserPromptSubmit` hook in the public Skills-only artifact as if it were a packaging defect.
+
+### OpenCode plugin implementation works in tests but host loading is uncertain
+
+**Symptom:** Source/mechanism tests pass, but there is no evidence that a real OpenCode session loaded and fired the plugin.
+
+**Interpretation:** The current repository claim is intentionally **mechanism-tested, live loading unverified**. Check [`../opencode-plugin/README.md`](../opencode-plugin/README.md) and run the OpenCode mechanism coverage. Do not promote a source-level pass into a live-host pass without a real session artifact.
+
+## Performance Issues
+
+### Slow Hook Execution
+
+**Symptom:** Terminal commands feel slower on a hook-enabled integration.
+
+**Solution:**
+1. Check Claude Code hook execution time where applicable:
+   ```bash
+   time node hooks/scripts/rule-of-3.js < /dev/null
+   ```
+2. If >200ms, check for:
+   - Large state files
+   - Network calls in hooks
+   - Complex file operations
+3. Reset state if appropriate:
+   ```bash
+   rm -rf .claude/harness-everything/state/sessions/
+   ```
+
+### High Memory Usage
+
+**Symptom:** Node.js processes consuming too much memory
+
+**Solution:**
+1. Check for memory leaks:
+   ```bash
+   ps aux | grep node
+   ```
+2. Restart session if needed.
+3. Report issue if persistent.
+
+## Debugging
+
+### Enable Verbose Logging
+
+```bash
+export HARNESS_DEBUG=1
+node hooks/scripts/rule-of-3.js < payload.json
+```
+
+### Check State Files
+
+```bash
+# Claude Code hook-path state example
+cat .claude/harness-everything/state/sessions/default/rule-of-3-state.json
+cat .claude/harness-everything/state/sessions/default/handoff-state.json
+
+# Reset Claude hook-path state
+rm -rf .claude/harness-everything/state/sessions/
+npm run harness:reset
+```
+
+### Manual Hook Testing
+
+For deterministic cross-platform mechanism checks, prefer:
+
+```bash
+npm run test:mechanism
+npm run test:docs:capabilities
+```
+
+When isolating a specific Claude hook, use the Windows-safe `spawnSync` recipes in [../VERIFICATION.md](../VERIFICATION.md) rather than assuming a shell `echo | node` pipeline behaves the same on every OS.
+
+## Getting Help
+
+### Collect Diagnostic Information
+
+```bash
+# Generate diagnostic report
+echo "=== System Info ===" > harness-diagnostic.txt
+node --version >> harness-diagnostic.txt
+npm --version >> harness-diagnostic.txt
+echo "" >> harness-diagnostic.txt
+
+echo "=== Harness Version ===" >> harness-diagnostic.txt
+cat package.json | grep version >> harness-diagnostic.txt
+echo "" >> harness-diagnostic.txt
+
+echo "=== Installed Platforms ===" >> harness-diagnostic.txt
+ls -la .claude/ .cursorrules .github/copilot-instructions.md AGENTS.md .continue/rules/ .hermes.md .agents/plugins/ plugins/harness-everything/ 2>/dev/null >> harness-diagnostic.txt
+echo "" >> harness-diagnostic.txt
+
+echo "=== Hook Status ===" >> harness-diagnostic.txt
+cat .claude/settings.json | grep -A 20 "hooks" >> harness-diagnostic.txt 2>/dev/null
+```
+
+### Contact Support
+
+1. **GitHub Issues:** https://github.com/dyphn1/Harness-everything/issues
+2. **Include:** Diagnostic report, error messages, steps to reproduce
+3. **Platform:** Specify which AI tool and which Harness installation surface you're using (for example `--codex` advisory installer vs local OpenAI plugin vs public Skills-only plugin).
+
+## Common Error Messages
+
+### "Cannot find module './lib/harness-state'"
+- **Cause:** Missing dependencies
+- **Solution:** Run `npm install` or reinstall Harness
+
+### "Routing-keywords.json missing/invalid"
+- **Cause:** Configuration file corrupted
+- **Solution:** Will fail open to Tier 1 - reinstall to restore
+
+### "Session state not found"
+- **Cause:** First run, state cleared, or the selected platform surface does not create that runtime state
+- **Solution:** Confirm the platform/integration surface first; on a supported stateful hook path, state is created on first use
+
+### "Zoom-out report not found"
+- **Cause:** Circuit breaker tripped but no report written
+- **Solution:** Follow the zoom-out instructions in the error message
+
+---
+
+*This troubleshooting guide covers the most common issues. For other problems, please open a GitHub issue with diagnostic information.*

package/docs/verifier-boundaries.md

@@ -0,0 +1,45 @@
+# Verifier Boundary Contracts
+
+This repository handles paths and execution evidence produced by local agent
+sessions. Consumers must use these contracts before writing, deleting, or
+grading anything derived from a session. The repository-side evidence archiver
+and legacy workspace migration use the same checks; the standalone OpenCode
+plugin mirrors the patch authorization rule because it is distributed as one
+file.
+
+## Physical path containment
+
+```js
+const { assertContainedPath } = require('../scripts/lib/path-boundary');
+
+const { target } = assertContainedPath(outputRoot, requestedPath);
+```
+
+`assertContainedPath()` resolves the deepest existing ancestor before appending
+missing segments. It rejects lexical traversal, junction/symlink components
+below the selected root, and physical paths outside the root. Call it for the
+final target, not only for the user-provided parent directory. Consumers must
+handle `PATH_OUTSIDE_BOUNDARY`, `LINK_COMPONENT_IN_BOUNDARY`, and
+`INVALID_BOUNDARY_PATH` as hard failures.
+
+## Exact execution evidence
+
+Use `commandMatches()` for command expectations. Complete strings compare after
+whitespace normalization; argv arrays compare each argument and length exactly.
+The only shorthand accepted is a script basename when an approved interpreter
+(`node`, `bun`, `deno`, Python, or Ruby) is the command launcher. Substring
+checks are not valid evidence.
+
+Use `extractPatchPaths()` and `patchPathsAuthorized()` for patch-shaped tool
+output. A patch is authorized only when every touched path is allowlisted;
+mixed authorized and unauthorized patches must be rejected atomically.
+
+Prefer structured argv and patch metadata when the producer provides them.
+These string fallbacks intentionally fail closed rather than guessing intent.
+
+## Mutation gate
+
+`npm run test:mutations` runs focused tests against temporary in-memory source
+mutations for each consumer boundary. A green result means the test would fail
+if its corresponding protection were removed; it does not replace the normal
+mechanism, consistency, or live behavioral-evidence gates.

package/docs/workflows/environment-detection.md

@@ -10,16 +10,16 @@ This section visualizes how the `environment-detection` skill executes internall
 
 ```mermaid
 graph TD
-  Start([Before Command Execution]) --> DetectOS["Detect Operating System: Windows, macOS, Linux"]
-  DetectOS --> DetectShell["Detect Shell: Bash, PowerShell, CMD, Zsh"]
-  DetectShell --> ScanCapabilities["Scan available runtimes: Node, Python, .NET, Docker"]
-  ScanCapabilities --> CheckSyntax["Inspect command for active shell compatibilities"]
-  CheckSyntax --> SyntaxGuard{Syntax safe for shell?}
-  SyntaxGuard -->|No| RewriteCmd["Transform/Rewrite command syntax to match active shell"]
-  SyntaxGuard -->|Yes| Execute["Run command in persistent terminal"]
-  RewriteCmd --> Execute
-  Execute --> CaptureOutput["Interleave output and exit code correctly"]
-  CaptureOutput --> End([Secure terminal result returned])
+  Start([Session Start / Discover Phase]) --> CheckNode{Node.js Executable?}
+  CheckNode -->|Yes| RunPreflight["Run scripts/preflight.js"]
+  CheckNode -->|No / Fails| Heuristic["Inspect <environment_info> & Probe Shell via echo/env"]
+  
+  RunPreflight --> ParseOutput["Parse OS, Shell, Path Separators & CLI Runtimes"]
+  Heuristic --> ParseOutput
+  
+  ParseOutput --> SelfHeal["Run self-heal.js if Node available"]
+  SelfHeal --> AlignSyntax["Adopt Path Slash (/ vs \\) & Env Var Syntax ($VAR vs %VAR%)"]
+  AlignSyntax --> End([Environment Context Established])
 ```
 
 ---

package/docs/workflows/eval-harness.md

@@ -10,12 +10,19 @@ This section visualizes how the `eval-harness` skill executes internally, detail
 
 ```mermaid
 graph TD
-  Start([Agent Execution Finished]) --> CollectExecutionMetrics["Gather total elapsed time, token count, and API calls"]
-  CollectExecutionMetrics --> EvaluateAccuracy["Compare completed task output against baseline correctness requirements"]
-  EvaluateAccuracy --> AnalyzeLoops["Check for repetitive tool invocations or redundant edits"]
-  AnalyzeLoops --> CalculateScores["Calculate performance and efficiency scores"]
-  CalculateScores --> GenerateEvalReport["Compile formal evaluation report and dashboard metrics"]
-  GenerateEvalReport --> End([Performance metrics indexed and logged])
+  Start([Trigger: Benchmark / Evaluate Log]) --> ParseLog["1. Parse Log: Actions, Error Loops, Token Indicator"]
+  ParseLog --> CalcRubric["2. Calculate Scores across 4 Dimensions (0-10)"]
+  CalcRubric --> CheckScript{3. Is evaluate.js Executable?}
+  
+  CheckScript -->|Yes| RunScript["Run node eval-harness/scripts/evaluate.js"]
+  CheckScript -->|No / Fails| FileFallback{"4. Markdown File Fallback"}
+  
+  FileFallback -->|evals/ Exists| WriteEvals["Save Scorecard to evals/scorecard.md"]
+  FileFallback -->|No evals/ Folder| WritePlatform["Save Scorecard to .github/harness-everything/evals/scorecard.md"]
+  
+  RunScript --> End([Evaluation Scorecard Logged])
+  WriteEvals --> End
+  WritePlatform --> End
 ```
 
 ---

package/docs/workflows/fable-discipline.md

@@ -1,6 +1,6 @@
 # Workflow: Fable Discipline
 
-> Shadow guard for fable-mode preventing context bloat, enforcing physical boundaries, and tracking token burn metrics.
+> Shadow guard for fable-mode preventing context bloat, enforcing physical boundaries, and preserving compact stage handoffs.
 
 ---
 
@@ -10,14 +10,14 @@ This section visualizes how the `fable-discipline` skill executes internally, de
 
 ```mermaid
 graph TD
-  Start([Fable Task Initiated]) --> AuditContext["Audit total file lengths in current context"]
-  AuditContext --> CheckTokenLimit{Tokens exceeding budget?}
+  Start([Fable Task Initiated]) --> AuditContext["Audit active context against the stage contract"]
+  AuditContext --> CheckTokenLimit{Context exceeds the active budget?}
   CheckTokenLimit -->|Yes| TrimContext["Evict raw logs, completed tasks, and non-essential file contents"]
   CheckTokenLimit -->|No| KeepState["Continue monitoring context state"]
   TrimContext --> EnforceLimit["Enforce physical boundary guidelines"]
   KeepState --> EnforceLimit
-  EnforceLimit --> LogMetrics["Track token utilization and distillation loops"]
-  LogMetrics --> End([Context maintained under safe, high-attention limits])
+  EnforceLimit --> RecordHandoff["Record a compact stage handoff"]
+  RecordHandoff --> End([Context maintained under safe, high-attention limits])
 ```
 
 ---
@@ -41,11 +41,11 @@ Here we model concrete real-world scenarios and use cases of the `fable-discipli
 
 ```mermaid
 graph TD
-  Start["Fable-mode is editing a large monorepo (context approaching 120k tokens)"] --> Monitor["Fable-discipline analyzes context size"]
-  Monitor --> TriggerPruning["Identifies 80k tokens of raw test execution logs & completed sub-task details"]
+  Start["Fable-mode is editing a large monorepo with growing context"] --> Monitor["Fable-discipline analyzes active context"]
+  Monitor --> TriggerPruning["Identifies raw logs & completed sub-task details"]
   TriggerPruning --> Clean["Evicts completed step details and logs from immediate active context"]
-  Clean --> Compress["Summarizes historical state into a 50-line relational state.json"]
-  Compress --> Done([Active context drops back to 40k tokens, preserving model's reasoning precision])
+  Clean --> Compress["Summarizes historical state into the stage handoff"]
+  Compress --> Done([Active context remains bounded while preserving required facts])
 ```
 
 ---

package/docs/workflows/fable-mode.md

@@ -1,32 +1,85 @@
-# Workflow: Fable Mode
-
-> 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.
-
----
-
-## 1. Skill Behavior Workflow
-
-This section visualizes how `fable-mode` handles macro tasks. Subagent failure or integration crashes are expected realities, not edge cases.
-
-```mermaid
-graph TD
-  Start([Tier 3 Macro Task Triggered]) --> InitFable["Initialize Fable Execution Context"]
-  InitFable --> AnalyzeScope["Map system dependencies & files"]
-  AnalyzeScope --> GenerateContract["Generate Contract & Todo List"]
-  
-  GenerateContract --> RunStep["Try: Execute Step / Sub-agent"]
-  RunStep --> VerifyStep["Try: Run verify-gate.js for Integration"]
-  
-  VerifyStep --> Check{Gate: Exit Code?}
-  Check -->|Exit 1: Sub-agent Failed| Diagnose["Reflect: Why did sub-agent fail?"]
-  Diagnose --> InsertBlocker["Insert Blocker Todo: Fix Integration"]
-  InsertBlocker --> RunStep
-  
-  Check -->|Exit 0: Success| CheckAllSteps{All steps done?}
-  CheckAllSteps -->|No| RunStep
-  CheckAllSteps -->|Yes| FinalAudit["Perform system-wide verification loop"]
-  
-  FinalAudit --> FinalCheck{Gate: Exit Code?}
-  FinalCheck -->|Exit 1| Diagnose
-  FinalCheck -->|Exit 0| End([Macro rewrite successfully deployed])
-```
+# Workflow: Fable Mode (v3)
+
+> 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. When Fable Mode Applies
+
+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
+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`.