harness-everything 0.3.6 → 0.4.1

package/plugins/harness-everything/skills/environment-detection/scripts/preflight.js

@@ -0,0 +1,103 @@
+#!/usr/bin/env node
+const { execSync } = require('child_process');
+const os = require('os');
+const fs = require('fs');
+const path = require('path');
+
+function checkCmd(cmd) {
+  try {
+    if (os.platform() === 'win32') {
+      execSync(`where "${cmd}"`, { stdio: 'ignore' });
+    } else {
+      execSync(`which "${cmd}"`, { stdio: 'ignore' });
+    }
+    return true;
+  } catch (e) {
+    try {
+      execSync(`${cmd} --version`, { stdio: 'ignore' });
+      return true;
+    } catch (e2) {
+      return false;
+    }
+  }
+}
+
+console.log("# [Environment Preflight Report]");
+console.log(`- **Operating System**: ${os.platform()} (${os.release()} ${os.arch()})`);
+
+// Shell Detection
+const isGitBash = !!(
+  process.env.MSYSTEM ||
+  process.env.BASH_VERSION ||
+  (process.env.SHELL && process.env.SHELL.toLowerCase().includes("bash"))
+);
+const isPowerShell = !!(
+  process.env.PSModulePath ||
+  (process.env.SHELL && (process.env.SHELL.toLowerCase().includes("powershell") || process.env.SHELL.toLowerCase().includes("pwsh")))
+);
+
+let shell = process.env.SHELL || (isGitBash ? "bash" : (isPowerShell ? "powershell" : process.env.COMSPEC)) || "Unknown";
+let shellName = "Unknown Shell";
+
+if (isGitBash || shell.toLowerCase().includes("bash")) {
+  shellName = "Git Bash / Bash";
+} else if (isPowerShell) {
+  shellName = "PowerShell";
+} else if (shell.toLowerCase().includes("cmd.exe")) {
+  shellName = "Windows Command Prompt (CMD)";
+} else {
+  shellName = shell;
+}
+
+console.log(`- **Active Shell**: ${shellName} (Path: \`${shell}\`)`);
+console.log(`- **Terminal Program**: ${process.env.TERM_PROGRAM || "Standard Terminal"}`);
+
+// CLI Tools Check
+const tools = ['git', 'docker', 'docker-compose', 'node', 'pnpm', 'npm', 'python', 'pip'];
+const availableTools = [];
+for (const tool of tools) {
+  if (checkCmd(tool)) {
+    availableTools.push(tool);
+  }
+}
+console.log(`- **Available CLI Tools**: ${availableTools.join(', ') || 'None'}`);
+
+// Sandbox Capabilities Detection
+const hasDocker = availableTools.includes('docker');
+const hasSandboxExec = checkCmd('sandbox-exec');
+const sandboxCapabilities = [];
+if (hasSandboxExec) sandboxCapabilities.push('macOS Seatbelt (sandbox-exec)');
+if (hasDocker) sandboxCapabilities.push('Docker Containers');
+if (os.platform() === 'win32') {
+  sandboxCapabilities.push('Windows AppContainer (Native)');
+}
+console.log(`- **Sandbox Capabilities**: ${sandboxCapabilities.join(', ') || 'No isolation sandbox detected'}`);
+
+// Repo Status
+try {
+  const branch = execSync('git branch --show-current', { encoding: 'utf8' }).trim();
+  console.log(`- **Git Workspace**: Detected (Branch: \`${branch}\`)`);
+} catch (e) {
+  console.log(`- **Git Workspace**: No git repository detected in ${process.cwd()}`);
+}
+
+// Recommended Syntax Guardrails
+console.log("\n## [Syntax & Command Guardrails for this Environment]");
+if (os.platform() === 'win32') {
+  if (shellName.includes("Bash")) {
+    console.log("- **Path Handling**: ALWAYS use `/` slashes for directory paths in commands (e.g., `scripts/run.js`). Avoid raw backslashes `\\` as they act as escape chars.");
+    console.log("- **Environment Variables**: Use `$VAR` syntax. Do NOT use `%VAR%` or `$env:VAR`.");
+    console.log("- **Command Chaining**: Use `&&` for sequence, `|` for piping.");
+    console.log("- **Avoid Native Windows Commands**: Do NOT use `dir`, `copy`, or `del`. Use bash standard equivalents `ls`, `cp`, `rm`.");
+  } else if (shellName.includes("PowerShell")) {
+    console.log("- **Path Handling**: Slashes `/` or `\\` are generally acceptable.");
+    console.log("- **Environment Variables**: Use `$env:VAR` syntax.");
+    console.log("- **Command Chaining**: Use `;` or `&&` (if PowerShell 7+). Avoid bash-specific commands like `grep`, `awk`, `sed` unless explicitly piping.");
+  } else {
+    console.log("- **Path Handling**: Use `\\` for directories.");
+    console.log("- **Environment Variables**: Use `%VAR%`.");
+    console.log("- **Chaining**: Use `&`.");
+  }
+} else {
+  console.log("- **Unix Native**: Standard Bash/Zsh syntax applies. Use relative paths, pipeline chaining, and standard utilities.");
+}

package/plugins/harness-everything/skills/eval-harness/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: eval-harness
+description: Evaluate AI agent performance across correctness, token efficiency, anti-loop focus, and environment awareness; save a 4-dimension scorecard. Use when asked to run a benchmark or score an execution log or conversation history.
+license: Apache-2.0
+metadata:
+  author: Miya Daniel
+  version: 0.4.0
+---
+
+# Eval Harness
+
+Evaluate an agent log with a four-dimension scorecard.
+
+## Skill Contract
+
+| Component | Specification |
+| :--- | :--- |
+| **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 `<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 `<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:
+
+- Running a benchmark or scoring an agent execution.
+- Comparing Vanilla and Harness execution.
+- Generating a four-dimension scorecard.
+
+## DO NOT USE FOR:
+
+- Writing or fixing the evaluated code.
+- General review without scoring dimensions.
+- Tasks without an execution log.
+
+Deep dive: `<this-skill-dir>/references/scoring-rubric.md`

package/plugins/harness-everything/skills/eval-harness/references/scoring-rubric.md

@@ -0,0 +1,68 @@
+# Eval Harness — Full Process & Scoring Rubric
+
+## Process & Evaluation Output Flow
+
+Follow the decision matrix below to evaluate performance and record scorecards:
+
+```mermaid
+flowchart TD
+    Start[Trigger: Benchmark / Evaluate Log] --> Parse[1. Parse Log: Actions, Loops, Tokens]
+    Parse --> Score[2. Calculate 4-Dimension Rubric Scores]
+
+    Score --> CheckScript{3. Is evaluate.js Executable?}
+
+    CheckScript -- Yes --> RunScript[Run node "<this-skill-dir>/scripts/evaluate.js" <scores> <insights>]
+    RunScript -- Exit 0 (Success) --> Done[Scorecard Saved to evals/]
+    RunScript -- Fails --> FileFallback
+
+    CheckScript -- No --> FileFallback{4. Markdown File Fallback}
+
+    FileFallback -- evals/ Directory Exists --> WriteEvals[Write to evals/scorecard.md]
+    FileFallback -- No evals/ Directory --> WritePlatform[Write to .github/harness-everything/evals/scorecard.md]
+
+    WriteEvals --> Done
+    WritePlatform --> Done
+```
+
+## 1. Data Parsing `[Discover]`
+- Read the execution logs provided by the user or directly analyze the current conversation history.
+- Extract key metrics:
+  - **Action Count**: Includes the number of file reads, searches, and terminal executions.
+  - **Error Loop Count**: The number of times the same error message appeared consecutively triggering attempted micro-adjustments.
+  - **Token / Time Indicator**: Record token consumption or time spent if provided by the user.
+
+## 2. Scoring Rubric `[Think]`
+
+Score based on the following four dimensions (out of 10 points each):
+
+### A. Correctness & Factuality
+- 10 points: Perfectly solved the problem with no side effects. Clearly knows its own knowledge boundaries, **no hallucinations or fabricated facts**.
+- 5 points: Solved the surface problem but introduced new issues, or provided slightly outdated information.
+- 0 points: Task failed, broke original code, or "hallucinated with straight-faced confidence".
+
+### B. Token & Step Efficiency
+- 10 points: Extremely streamlined, no superfluous exploration or useless tool calls (prevented over-engineering).
+- 5 points: Reasonable steps, but with minor unnecessary file reads.
+- 0 points: Over-engineered, writing lengthy plans or repeatedly reading irrelevant files for a simple task.
+
+### C. Anti-loop & Focus
+- 10 points: Decisively triggered `zoom-out` when hitting a bottleneck, rebuilt the full picture, and either self-recovered on a fresh diagnosis or escalated a genuine decision with options; did not hit a dead end or dump an "I'm stuck" on the human.
+- 5 points: Stopped after 3~5 attempts.
+- 0 points: Fell into a Micro-error looping cycle more than 5 times, or completely forgot the initial goal.
+
+### D. Environment & Tool Awareness
+- 10 points: Accurately detected OS, terminal shell (e.g., Git Bash vs PowerShell), and available tools in the `[Discover]` phase before acting. No syntax errors caused by wrong shell assumptions.
+- 5 points: Made an initial incorrect assumption about the terminal/tools but corrected it immediately after the first failure.
+- 0 points: Blindly threw commands (e.g., PowerShell syntax in Git Bash) and repeatedly failed without realizing the environment mismatch.
+
+## 3. Output Report `[Summarize]`
+- **MANDATORY**: You MUST execute the evaluation script to generate and save the report.
+- Find the `evaluate.js` script in the `scripts/` directory of this skill and run it via terminal:
+
+```bash
+node "<this-skill-dir>/scripts/evaluate.js" <scoreA> <scoreB> <scoreC> <scoreD> "<Your insights here>"
+```
+
+*(Example: `node scripts/evaluate.js 10 5 10 10 "The agent successfully used zoom-out..."`)* — run with `--help` for the scoring-dimension reference.
+
+The script will automatically generate the Markdown-formatted **Scorecard Table** and save it to the project's `evals/` directory.

package/plugins/harness-everything/skills/eval-harness/scripts/evaluate.js

@@ -0,0 +1,79 @@
+#!/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);
+
+if (args[0] === '--help' || args[0] === '-h') {
+  console.log(`Score a Harness-guarded session and write an evaluation report.
+
+Usage: node evaluate.js <scoreA> <scoreB> <scoreC> <scoreD> "<insights>"
+
+Four positional scores (0, 5, or 10 each), in this order:
+  scoreA  Correctness & Factuality
+  scoreB  Token & Step Efficiency
+  scoreC  Anti-loop & Focus
+  scoreD  Environment & Tool Awareness
+
+Followed by one free-text insights string (wrap in quotes).`);
+  process.exit(0);
+}
+
+if (args.length < 5) {
+  console.error("Usage: node evaluate.js <scoreA> <scoreB> <scoreC> <scoreD> \"<insights>\"");
+  console.error("Scores should be 0, 5, or 10.");
+  process.exit(1);
+}
+
+const [scoreA, scoreB, scoreC, scoreD, ...insightParts] = args;
+const insights = insightParts.join(" ");
+
+const scores = {
+  "Correctness & Factuality": parseInt(scoreA, 10),
+  "Token & Step Efficiency": parseInt(scoreB, 10),
+  "Anti-loop & Focus": parseInt(scoreC, 10),
+  "Environment & Tool Awareness": parseInt(scoreD, 10)
+};
+
+let total = 0;
+let markdown = `## Harness Evaluation Report - ${new Date().toISOString()}\n\n| Dimension | Score |\n|---|---|\n`;
+
+for (const [dim, score] of Object.entries(scores)) {
+  if (isNaN(score)) {
+    console.error(`Error: Score for ${dim} is not a valid number.`);
+    process.exit(1);
+  }
+  markdown += `| ${dim} | ${score}/10 |\n`;
+  total += score;
+}
+
+markdown += `| **Total Score** | **${total}/40** |\n\n`;
+markdown += `### Insights\n${insights}\n\n---\n`;
+
+// Store the evaluations in an evals folder in the project root
+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 });
+}
+
+const reportPath = path.join(evalDir, 'evaluation-reports.md');
+try {
+  fs.appendFileSync(reportPath, markdown, 'utf8');
+  console.log(`[Success] Evaluation report generated and saved to ${reportPath}`);
+  console.log('\n--- Report Preview ---\n');
+  console.log(markdown);
+} catch (err) {
+  console.error(`[Error] Failed to write evaluation report: ${err.message}`);
+  process.exit(1);
+}

package/plugins/harness-everything/skills/fable-discipline/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: fable-discipline
+description: Enforce fable-mode's context discipline as a shadow guard. Use when running staged multi-agent loops to prevent context bloat, cap per-stage output size, keep each stage within its physical token boundaries, and stop agents from reading files outside the current stage's scope.
+license: Apache-2.0
+metadata:
+  author: Miya Daniel
+  version: 0.4.0
+---
+
+# Fable Discipline (Macro Task Discipline & Safety Net)
+
+## 📋 Skill Contract
+
+| Component | Specification |
+| :--- | :--- |
+| **Trigger / Input** | Background shadow for the whole duration `fable-mode` is active — not a standalone one-shot trigger. |
+| **Expected Output** | State compaction after milestones; one Git commit per independent logic block; a state manifest at every sub-agent handoff. |
+| **State Mutations** | None of its own — constrains how `fable-mode` and `multi-agent-workspace` mutate state. |
+| **Enforcement Gate** | **HALTS execution immediately** if build errors diverge (more fixes → more breakage); forces `zoom-out` instead of continued patching. |
+
+Shadow guard for `fable-mode`: MUST run in the background for its whole duration.
+
+## USE FOR:
+- Long architectural tasks under `fable-mode`
+- Compacting state after milestones
+- Sub-agent handoffs via `multi-agent-workspace`
+- Halting on diverging build errors
+
+## DO NOT USE FOR:
+- Small tasks where `fable-mode` is not active
+- Standalone one-shot invocation (background shadow skill)
+- Routine single-file edits
+
+## Core Rules
+
+1. **Anti-context bloat**: After each milestone, compact state and decisions; drop unneeded history. No broad regex without precise conditions; no reading irrelevant files over 1000 lines.
+2. **Physical boundaries**: Know your CWD before touching core architecture; one Git commit per independent logic block.
+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: <this-skill-dir>/references/discipline-rules.md

package/plugins/harness-everything/skills/fable-discipline/references/discipline-rules.md

@@ -0,0 +1,22 @@
+# Fable Discipline — Full Detail
+
+This skill acts as the shadow guard for `fable-mode`. As long as `fable-mode` is active, this skill MUST run in the background to prevent large tasks from spiraling out of control.
+
+## 1. Anti-Context Bloat Defense
+When executing large architectural tasks, conversation logs expand rapidly, leading to model attention loss (hallucinations or forgetting the original intent).
+- **Strategic Compact**: After completing each core milestone, forcefully summarize the current state and decisions, discarding unnecessary past conversation details.
+- **Avoid Broad Reads**: Prohibited from using broad Regex searches without precise conditions or reading irrelevant files over 1000 lines.
+
+## 2. Strict Physical Boundaries
+- **Environment Isolation**: Before modifying any core architecture, ensure you are clearly aware of the Current Working Directory (CWD).
+- **Atomic Commits**: You are NOT allowed to modify dozens of files at once before testing. For every independently functioning logic block completed, advise the human to create a Git Commit as a safe save point.
+
+## 3. Agent Handoff Protocol
+When `fable-mode` spawns and switches between different sub-agents via `multi-agent-workspace`, strict handoff discipline must be observed:
+- **State Manifest**: The previous agent MUST leave a clear state record (e.g., what APIs were completed, expected inputs/outputs).
+- **Contract Testing**: The very first step for the succeeding agent is to verify if the state manifest left by the previous agent is correct.
+
+## 4. Ultimate Circuit Breaker: Indefinite Halt
+- Large tasks easily generate the sunk cost fallacy of "I think it's almost fixed, let me try one more time."
+- If the system's Build Errors exhibit a divergent trend (the more you fix, the more it breaks), **HALT EXECUTION IMMEDIATELY**.
+- Call `zoom-out`, organize the error dependency graph for the human, and seek architectural-level refactoring advice.

package/plugins/harness-everything/skills/fable-mode/CONTRACT-FORMAT.md

@@ -0,0 +1,165 @@
+# Fable Stage Contract Format
+
+Issue #85 Phase 3 makes the stage map a machine-readable execution contract.
+The router still chooses only the execution topology. Fable owns the stage map,
+model selector, worker briefs, stage audit, replan budget, and cold verifier.
+Phase 4 adds an optional bounded ensemble modifier without creating a new base
+topology.
+
+Run state is stored under the existing workspace-keyed global Harness state
+root, never inside the repository:
+
+```text
+<workspace-state>/state/fable-runs/<runId>/
+  run.json
+  contracts/<stageId>.json
+  evidence/<stageId>.json
+  ensemble.json             # only when ensemble review executes
+```
+
+`planId` is a deterministic content hash of the router contract. `runId` is
+unique per orchestration. Two runs of the same plan therefore share a `planId`
+but never share mutable stage-contract files.
+
+## Stage schema v2
+
+Every planned stage declares dependency and write scope before dispatch:
+
+```json
+{
+  "stageId": "stage-3",
+  "goal": "implement one bounded objective",
+  "agent": "fable-worker-sonnet",
+  "task": "self-contained task statement",
+  "inputs": ["relevant files", "upstream outputs"],
+  "expectedOutputs": ["artifact or evidence"],
+  "outputPath": "path/to/artifact-or-null",
+  "dependsOn": ["stage-1"],
+  "writeSet": ["src/auth", "tests/auth.test.js"],
+  "checkCommand": "node --test tests/auth.test.js",
+  "passCondition": "exit 0",
+  "failureReturn": "failure summary + evidence + missing prerequisite"
+}
+```
+
+Rules:
+
+- `stageId`, `goal`, `agent`, and `task` are required.
+- `dependsOn` is always explicit. Use `[]` for a root stage.
+- `writeSet` is always explicit. Use `[]` for a read-only stage.
+- `writeSet` contains concrete repository-relative path scopes, not globs,
+  absolute paths, or `..` traversal.
+- a directory scope covers descendants; overlapping scopes cannot run in the
+  same parallel batch.
+- every `dependsOn` target must exist; self edges and cycles are invalid.
+- `checkCommand` is exact-match evidence when present. `passCondition` explains
+  what that command proves; it does not replace the command result.
+- workers do not widen their own `writeSet`. If scope must grow, return to the
+  orchestrator and produce a revised plan before dispatch.
+
+## Workflow-plan consumer
+
+Before dispatch, write the router contract and stage array to files and run:
+
+```bash
+node fable-mode/scripts/workflow-plan-consumer.js \
+  --plan-file <router-contract.json> \
+  --stages-file <stages.json> \
+  --root <workspace> \
+  --run-id <optional-stable-run-label> \
+  --session-id <optional-host-session-id>
+```
+
+The consumer validates the graph, derives `planId`, creates the isolated run
+root, and emits execution batches. It consumes only router-owned decisions:
+strategy, parallelism, verifier requirement, workspace/memory hints, limits,
+and requested-model metadata. It does **not** choose a model or execute a
+stage.
+
+For `fable-parallel`, every ready batch must have resolved dependencies and
+pairwise non-overlapping write sets. An invalid graph or overlap rejects the
+plan before workers are spawned. For `fable-staged` and
+`fable-multi-agent-workspace`, the same dependency graph is serialized unless
+a later validated plan explicitly allows parallelism.
+
+## Bounded ensemble evidence
+
+`workflowPlan.ensemble` is a modifier on a selected Fable topology, not a sixth
+execution strategy. The kernel may add it only for high-uncertainty/high-stakes
+work with comparable outputs (choice/ranking/verdict/recommendation) or when
+preserving disagreement is itself the deliverable. Creative generation,
+mechanical bulk work, explicit `no ensemble`, unavailable subagents, and blocked
+base plans do not receive the modifier.
+
+Current contract:
+
+```json
+{
+  "maxCandidates": 3,
+  "diversity": ["model", "prompt", "evidence"],
+  "synthesis": "preserve-disagreement",
+  "verifier": "independent",
+  "reasonCodes": ["ensemble-high-uncertainty-comparable-output"]
+}
+```
+
+Each candidate passed to `fable-mode/scripts/ensemble-review.js` records a
+bounded position, a model/prompt/evidence diversity fingerprint, objective
+verification status/evidence, and optional correctness/cost observations.
+Candidates with the same model+prompt+evidence fingerprint are not independent
+and are rejected. The verifier uses a distinct identity, declares
+`independent=true`, and supplies its own evidence.
+
+The synthesizer keeps every position and its evidence. A strict majority is
+only a proposal: any objective verification failure on the proposed position
+blocks selection, and verifier rejection/inconclusive/mismatch also blocks it.
+An accepted position therefore never deletes minority positions or evidence
+gaps.
+
+Run it after the candidate artifacts/checks exist:
+
+```bash
+node fable-mode/scripts/ensemble-review.js \
+  --plan-file <router-contract.json> \
+  --candidates-file <candidates.json> \
+  --verifier-file <verifier.json> \
+  --root <workspace> \
+  --run-id <runId> \
+  [--paired-evidence-file <paired-benchmark.json>]
+```
+
+The correlated result is written to `ensemble.json` under the same run root.
+Correctness is recorded separately from tool calls, tokens, elapsed time,
+retries, and failure mode so #71/#83 can consume the evidence without
+conflating quality with cost. Missing telemetry is allowed and never changes
+the strategy/result. No ensemble or multi-agent improvement claim is permitted
+unless paired evidence establishes the same engine/model/fixture/rubric/config,
+a sample count, effect estimate, and uncertainty.
+
+## Verification evidence
+
+`contract-test.js` watches Bash/PowerShell calls and resolves an exact
+`checkCommand` only when it can correlate the command to one run/stage. The
+result updates the stage contract and writes:
+
+```text
+evidence/<stageId>.json
+```
+
+with `planId`, `runId`, `stageId`, command, exit code, status, and captured
+evidence. If the same command is pending in multiple uncorrelated runs, the
+hook updates none of them and reports the ambiguity.
+
+Before delivery, every check-bearing contract in the run must be `pass` (not
+`pending`, `planned`, `running`, or `fail`). A failed check returns to the
+orchestrator for bounded re-planning.
+
+## Scope audit
+
+`subagent-scope-guard.js` snapshots active stage write sets at the beginning of
+a worker burst and compares the post-burst Git diff paths with that immutable
+snapshot. Expected paths are attributed to the matching stage; worker-level
+attribution is added when the host exposes a worker/subagent id and the stage
+contract records it. Ambiguous or out-of-scope changes exit 2. With no declared
+stage contracts, the older conservative behavior remains: every newly changed
+path requires review.

package/plugins/harness-everything/skills/fable-mode/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: fable-mode
+description: "Stage large, multi-source or multi-session tasks through a written plan, named fable agents, failable per-stage checks, and skeptical delivery review; use fable-opus, fable-sonnet, or fable-haiku for explicit model selection."
+license: Apache-2.0
+metadata:
+  author: Miya Daniel
+  version: 0.4.0
+---
+
+# Fable Mode (v3)
+
+## Skill Contract
+
+| Component | Specification |
+| :--- | :--- |
+| **Trigger / Input** | Tier 3 work spanning multiple files, sources, or sessions. |
+| **Expected Output** | Stage map, named-agent briefs, failable checks, and skeptical review. |
+| **State Mutations** | Native host TODO tracker or a Markdown checklist; one JSON audit record per stage. |
+| **Enforcement Gate** | `<this-skill-dir>/scripts/model-selector.js`, stage contracts, and `<skills-repo-root>/harness-everything/scripts/verify-gate.js`. |
+
+## USE FOR:
+- Large multi-file, multi-source, or multi-session work
+- Explicit `fable on haiku`, `fable on sonnet`, or `fable on opus` requests
+- Work needing named delegation and cold verification
+
+## DO NOT USE FOR:
+- One obvious single-pass edit
+- Ordinary Tier 2 implementation or bugfix work
+
+## Workflow
+
+1. Discover the runtime and lock the authorized file scope before edits.
+2. Write a numbered stage map with one artifact and pass condition per stage; allow at most two full replans.
+3. Resolve the requested model with `model-selector.js`; never silently downgrade.
+4. Delegate by named agent where available: Opus orchestrates, Sonnet reasons, Haiku handles mechanical work, and workers never spawn workers.
+5. Write a stage contract, run its named check, then cold-review high-stakes artifacts with `fable-verifier`.
+6. Record requested/effective model, fallback reason, stage brief, pass condition, verification command, and verifier result for every stage. Escalate unresolved blockers.
+
+Deep dive: <this-skill-dir>/references/model-matrix.md