harness-everything 0.2.0

package/eval-framework/mechanism-test.js

@@ -0,0 +1,251 @@
+#!/usr/bin/env node
+/**
+ * Harness Mechanism Test Suite (Claude Code hook contract)
+ * Automates VERIFICATION.md Section 2 (mechanism check) so it runs on every
+ * `npm test` instead of only when a human copy-pastes the recipes by hand.
+ * That manual gap is exactly what let three independent 2026-07-23 audit
+ * reports (see docs/reports/) misdiagnose working hooks as broken: they
+ * piped JSON via `echo '...' | node script.js` in a Windows Git Bash shell,
+ * which mangles stdin/TTY state and produced false negatives. This suite
+ * uses execSync's `input` option instead (the same technique already proven
+ * reliable in runner.js and behavioral-test.js) so it is a faithful,
+ * cross-platform re-run of the exact payloads VERIFICATION.md documents.
+ *
+ * Each hook resolves its state directory via detectActivePlatform(), which
+ * defaults to 'copilot' under a VS Code integrated terminal (TERM_PROGRAM=
+ * vscode) unless CLAUDE is set - so every child process below is spawned
+ * with CLAUDE=1 to force the Claude Code state path regardless of the host
+ * running this test.
+ *
+ * All state is written under a dedicated, never-real session id so this
+ * suite can never collide with or clobber an actual Claude Code session's
+ * breaker/handoff state. The session directory (and any repo-root temp
+ * files created along the way) is removed on exit, success or failure alike.
+ */
+const { execSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+
+process.env.CLAUDE = '1'; // so our own getSessionDir() calls resolve like the children's will
+
+const { getWorkspaceRoot, getSessionDir } = require('../hooks/scripts/lib/harness-state');
+
+const root = getWorkspaceRoot();
+const hooksDir = path.join(root, 'hooks', 'scripts');
+const SESSION_ID = '__mechanism_test__';
+const sessionDir = getSessionDir(root, SESSION_ID);
+
+console.log('=== 🔧 Harness Mechanism Test Suite (VERIFICATION.md §2) ===');
+
+const tempFiles = [];
+let failures = 0;
+
+function check(name, condition, detail) {
+  if (condition) {
+    console.log(`✅ ${name}`);
+  } else {
+    console.error(`❌ ${name}`);
+    if (detail) console.error(`   ${detail}`);
+    failures++;
+  }
+}
+
+function runHook(scriptName, payload, extraEnv) {
+  const scriptPath = path.join(hooksDir, scriptName);
+  try {
+    const stdout = execSync(`node "${scriptPath}"`, {
+      encoding: 'utf8',
+      input: payload === null ? '' : JSON.stringify(payload),
+      env: { ...process.env, ...extraEnv },
+    });
+    return { code: 0, stdout, stderr: '' };
+  } catch (err) {
+    return { code: err.status, stdout: err.stdout || '', stderr: err.stderr || '' };
+  }
+}
+
+function writeState(file, obj) {
+  fs.writeFileSync(path.join(sessionDir, file), JSON.stringify(obj, null, 2), 'utf8');
+}
+function readState(file) {
+  return JSON.parse(fs.readFileSync(path.join(sessionDir, file), 'utf8'));
+}
+function stateExists(file) {
+  return fs.existsSync(path.join(sessionDir, file));
+}
+
+// Registers a repo-root temp file for guaranteed cleanup even if an
+// assertion throws or the process is killed mid-suite.
+function tempFile(name) {
+  const p = path.join(root, name);
+  tempFiles.push(p);
+  return p;
+}
+
+process.on('exit', () => {
+  for (const f of tempFiles) {
+    try { if (fs.existsSync(f)) fs.unlinkSync(f); } catch (e) { /* best-effort */ }
+  }
+  try { fs.rmSync(sessionDir, { recursive: true, force: true }); } catch (e) { /* best-effort */ }
+});
+
+// ---------------------------------------------------------------------------
+// 2a. Rule of 3 circuit breaker trips, releases via zoom-out report, and
+//     hard-locks on a repeat trip of the same signature.
+// ---------------------------------------------------------------------------
+console.log('\n[2a] Rule of 3 circuit breaker...');
+
+writeState('rule-of-3-state.json', { count: 3, lastHash: 'mech-test', zoomOutResolved: false });
+const tripResult = runHook('rule-of-3.js', { session_id: SESSION_ID });
+check(
+  '2a. Trips at count=3 (exit=2, CRITICAL banner)',
+  tripResult.code === 2 && tripResult.stderr.includes('RULE OF 3 CIRCUIT BREAKER TRIGGERED'),
+  `Got exit=${tripResult.code}, stderr="${tripResult.stderr.slice(0, 200)}"`
+);
+
+writeState('rule-of-3-state.json', {
+  count: 3, lastHash: 'mech-test', zoomOutResolved: false, lastFailureAt: 0, zoomOutCycles: 0,
+});
+fs.writeFileSync(
+  path.join(sessionDir, 'zoom-out-report.md'),
+  '## Goal\nx\n## Failed Attempts\nx\n## Verified Facts\nx\n## Diagnosis\nx\n## Decision\nRESUME: new approach\n',
+  'utf8'
+);
+const releaseResult = runHook('rule-of-3.js', { session_id: SESSION_ID });
+const releasedState = readState('rule-of-3-state.json');
+check(
+  '2a-bis. Valid zoom-out report releases the breaker (exit=0, count reset)',
+  releaseResult.code === 0 &&
+    releaseResult.stdout.includes('breaker released') &&
+    releasedState.count === 0 &&
+    releasedState.zoomOutResolved === true &&
+    releasedState.zoomOutCycles === 1,
+  `Got exit=${releaseResult.code}, state=${JSON.stringify(releasedState)}`
+);
+
+writeState('rule-of-3-state.json', {
+  count: 3, lastHash: 'mech-test', zoomOutResolved: false,
+  lastFailureAt: Date.now() + 60000, zoomOutCycles: 1,
+});
+const hardLockResult = runHook('rule-of-3.js', { session_id: SESSION_ID });
+check(
+  '2a-ter. Second trip on same signature hard-locks (exit=2, repeat trip)',
+  hardLockResult.code === 2 && hardLockResult.stderr.includes('repeat trip - hard lock'),
+  `Got exit=${hardLockResult.code}, stderr="${hardLockResult.stderr.slice(0, 200)}"`
+);
+
+// ---------------------------------------------------------------------------
+// 2b. Boundary guard blocks an oversized Read
+// ---------------------------------------------------------------------------
+console.log('\n[2b] Boundary guard...');
+
+const bigFile = tempFile('.mechanism-test-big.tmp');
+fs.writeFileSync(bigFile, 'x'.repeat(600 * 1024));
+const boundaryResult = runHook('boundary-guard.js', { tool_name: 'Read', tool_input: { file_path: bigFile } });
+check(
+  '2b. Blocks a 600KB Read without limit/offset (exit=2, BLOCKED)',
+  boundaryResult.code === 2 && boundaryResult.stderr.includes('[Boundary Guard] BLOCKED'),
+  `Got exit=${boundaryResult.code}, stderr="${boundaryResult.stderr.slice(0, 200)}"`
+);
+fs.unlinkSync(bigFile);
+
+// ---------------------------------------------------------------------------
+// 2c. State persistence (WAL) records a failure, then clears it on success
+// ---------------------------------------------------------------------------
+console.log('\n[2c] State persistence (WAL)...');
+
+runHook('state-persist.js', {
+  session_id: SESSION_ID,
+  tool_name: 'Bash',
+  tool_response: { stdout: '', stderr: 'npm ERR! mech-test failure' },
+});
+const failedHandoff = readState('handoff-state.json');
+check(
+  '2c. Failing Bash call is recorded as status=failed',
+  failedHandoff.status === 'failed' && failedHandoff.errorSummary.includes('mech-test failure'),
+  `Got ${JSON.stringify(failedHandoff)}`
+);
+
+runHook('state-persist.js', {
+  session_id: SESSION_ID,
+  tool_name: 'Bash',
+  tool_response: { stdout: 'ok', exitCode: 0 },
+});
+const resolvedHandoff = readState('handoff-state.json');
+check(
+  '2c. A subsequent successful command clears status back to idle',
+  resolvedHandoff.status === 'idle' && !!resolvedHandoff.lastResolved,
+  `Got ${JSON.stringify(resolvedHandoff)}`
+);
+
+// ---------------------------------------------------------------------------
+// 2d. Fact-audit reminder reaches the agent via tier-router.js stdin
+// ---------------------------------------------------------------------------
+console.log('\n[2d] Fact-audit reminder...');
+
+const tierRouterPath = path.join(root, 'harness-everything', 'scripts', 'tier-router.js');
+const factAuditOut = execSync(`node "${tierRouterPath}"`, {
+  encoding: 'utf8',
+  input: JSON.stringify({ prompt: 'what exit code does this hook use by default and is it documented' }),
+});
+check(
+  '2d. tier-router.js reads {"prompt":...} from stdin and emits FACT-AUDIT REMINDER',
+  factAuditOut.includes('FACT-AUDIT REMINDER'),
+  `Output was:\n${factAuditOut.slice(0, 300)}`
+);
+
+// ---------------------------------------------------------------------------
+// 2e. Subagent scope guard catches an out-of-scope file change
+// ---------------------------------------------------------------------------
+console.log('\n[2e] Subagent scope guard...');
+
+runHook('subagent-scope-guard.js', {
+  session_id: SESSION_ID, tool_name: 'Task', hook_event_name: 'PreToolUse', tool_input: {},
+});
+const scopeFile = tempFile('.mechanism-test-scope.tmp');
+fs.writeFileSync(scopeFile, 'unexpected change');
+const scopeResult = runHook('subagent-scope-guard.js', {
+  session_id: SESSION_ID, tool_name: 'Task', hook_event_name: 'PostToolUse', tool_input: {},
+});
+check(
+  '2e. Flags the newly-created file after a Task burst (exit=2, lists filename)',
+  scopeResult.code === 2 &&
+    scopeResult.stderr.includes('Subagent Scope Guard') &&
+    scopeResult.stderr.includes(path.basename(scopeFile)),
+  `Got exit=${scopeResult.code}, stderr="${scopeResult.stderr.slice(0, 300)}"`
+);
+fs.unlinkSync(scopeFile);
+
+// ---------------------------------------------------------------------------
+// 2f. Stop gate bounces an unverified-edit stop exactly once
+// ---------------------------------------------------------------------------
+console.log('\n[2f] Stop gate...');
+
+writeState('handoff-state.json', { status: 'idle', lastEditAt: Date.now(), lastVerifyAt: 0 });
+const dirtyFile = tempFile('.mechanism-test-dirty.tmp');
+fs.writeFileSync(dirtyFile, 'dirty');
+const firstStop = runHook('stop-gate.js', { session_id: SESSION_ID });
+check(
+  '2f. First stop after an unverified edit bounces (exit=2)',
+  firstStop.code === 2 && firstStop.stderr.includes('[Stop Gate]'),
+  `Got exit=${firstStop.code}, stderr="${firstStop.stderr.slice(0, 200)}"`
+);
+const secondStop = runHook('stop-gate.js', { session_id: SESSION_ID });
+check(
+  '2f. Same edit batch does not bounce twice (exit=0)',
+  secondStop.code === 0,
+  `Got exit=${secondStop.code}`
+);
+fs.unlinkSync(dirtyFile);
+
+// ---------------------------------------------------------------------------
+console.log('\n=================================================');
+if (failures > 0) {
+  console.error(` ❌ ${failures} mechanism check(s) FAILED.`);
+  console.log('=================================================');
+  process.exit(1);
+} else {
+  console.log(' 🎉 All VERIFICATION.md §2 mechanism checks passed.');
+  console.log('=================================================');
+  process.exit(0);
+}

package/eval-framework/runner.js

@@ -0,0 +1,56 @@
+#!/usr/bin/env node
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+
+const casesDir = path.join(__dirname, 'cases');
+const files = fs.readdirSync(casesDir).filter(f => f.endsWith('.json'));
+
+console.log("=== Harness Tier Verification Framework ===");
+console.log("This framework simulates routing prompts to verify trigger rates.\n");
+
+let passed = 0;
+let failed = 0;
+
+files.forEach(file => {
+  const data = JSON.parse(fs.readFileSync(path.join(casesDir, file), 'utf8'));
+  console.log(`[Testing] ${data.name}`);
+  console.log(`  Prompt: "${data.prompt}"`);
+  console.log(`  Expected Tier: ${data.expected_tier}`);
+  
+  try {
+    const tierRouterPath = path.join(__dirname, '..', 'harness-everything', 'scripts', 'tier-router.js');
+    // Claude Code feeds UserPromptSubmit hooks JSON on stdin (a "prompt"
+    // field), not a CLI argument - match that here so this test actually
+    // exercises the real interface instead of a path tier-router.js never
+    // sees in production.
+    const output = execSync(`node "${tierRouterPath}"`, {
+      encoding: 'utf8',
+      input: JSON.stringify({ prompt: data.prompt }),
+      env: { ...process.env, HARNESS_EVAL: 'true' }
+    });
+    
+    // Parse the output to find the recommended tier (accept the old
+    // "REQUIRED TIER" label too so the runner works across versions)
+    const tierMatch = output.match(/(?:RECOMMENDED|REQUIRED) TIER: (Tier \d+)/i) || output.match(/(Tier \d+)/i);
+    const actualTier = tierMatch ? tierMatch[1] : "Unknown";
+    
+    if (actualTier.includes(data.expected_tier)) {
+      console.log(`  -> Result: PASS (Got ${actualTier})\n`);
+      passed++;
+    } else {
+      console.log(`  -> Result: FAIL (Expected ${data.expected_tier}, Got ${actualTier})\n`);
+      console.log(`  Output was:\n${output}`);
+      failed++;
+    }
+  } catch (err) {
+    console.log(`  -> Result: ERROR executing router`);
+    failed++;
+  }
+});
+
+console.log(`--- Summary: ${passed} passed, ${failed} failed ---`);
+if (failed > 0) {
+  process.exit(1);
+}
+

package/eval-harness/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: eval-harness
+description: Objectively evaluates AI agent performance based on correctness, resource efficiency, and anti-loop focus.
+author: Miya Daniel | Harness Core Team
+version: 0.2.0
+---
+
+# Eval Harness (Automated Performance & Reasoning Evaluation)
+
+## 📋 Skill Contract
+
+| Component | Specification |
+| :--- | :--- |
+| **Trigger / Input** | User requests "run benchmark", "score conversation log", or "compare Vanilla vs Harness differences" — an execution log or the current conversation history. |
+| **Expected Output** | A 4-dimension scorecard (Correctness & Factuality, Token & Step Efficiency, Anti-loop & Focus, Environment & Tool Awareness), each scored 0-10 with rationale. |
+| **State Mutations** | Writes a generated Markdown scorecard to the project's `evals/` directory via `scripts/evaluate.js`. |
+| **Enforcement Gate** | MUST execute `scripts/evaluate.js` with the four scores and insight text — a verbally-stated score without running the script does not count as output. |
+
+This skill is used to objectively evaluate the performance of an AI Agent when "executing test tasks".
+Triggered when the user requests "run benchmark", "score conversation log", or "compare Vanilla vs Harness differences".
+
+## 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]`
+Please 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 path/to/eval-harness/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..."`)*
+- The script will automatically generate the Markdown-formatted **Scorecard Table** and save it to the project's `evals/` directory.

package/eval-harness/scripts/evaluate.js

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+const fs = require('fs');
+const path = require('path');
+
+const args = process.argv.slice(2);
+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`;
+
+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');
+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/fable-discipline/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: fable-discipline
+description: Shadow guard for fable-mode to prevent context bloat and maintain physical boundaries.
+author: Miya Daniel | Harness Core Team
+version: 0.2.0
+---
+
+# Fable Discipline (Macro Task Discipline & Safety Net)
+
+## 📋 Skill Contract
+
+| Component | Specification |
+| :--- | :--- |
+| **Trigger / Input** | Runs continuously in the background for the entire duration `fable-mode` is active — not a standalone, one-shot trigger. |
+| **Expected Output** | Periodic state compaction after each milestone; one Git commit per independently functioning logic block; a state manifest handed off between sub-agents at every handoff point. |
+| **State Mutations** | None of its own — it constrains how `fable-mode` and `create-agent-launcher` mutate state (commit cadence, handoff manifests, read-size limits). |
+| **Enforcement Gate** | **HALTS execution immediately** (not a retry) if build errors show a divergent trend (more fixes → more breakage), and forces `zoom-out` instead of continued patching. |
+
+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 `create-agent-launcher`, 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/fable-mode/CONTRACT-FORMAT.md

@@ -0,0 +1,51 @@
+# Stage Contract Format
+
+Stage contracts live in `.claude/harness-state/contracts/` and make fable-orchestrator's
+"re-run or spot-check every stage's named check" discipline auditable instead
+of a verbal claim. The `contract-test.js` hook (PostToolUse: Bash) watches for
+the exact `checkCommand` running and fills in the result — you write the
+contract, the hook resolves it.
+
+## When to write one
+
+Right before you (the orchestrator) run the Bash command that re-verifies a
+stage's pass condition — one contract per stage, filed the moment you're about
+to spot-check it. Not for every Bash call, only the ones that *are* the named
+check.
+
+## File
+
+`.claude/harness-state/contracts/<stageId>.json`, created lazily. `stageId` is whatever you
+numbered the stage in your stage map (`stage-3`, `db-migration`, etc).
+
+## Schema
+
+```json
+{
+  "stageId": "stage-3",
+  "agent": "fable-worker-sonnet",
+  "task": "one-line description of what the worker was assigned",
+  "outputPath": "path to the artifact the worker produced",
+  "checkCommand": "the exact shell command you are about to run to verify it",
+  "status": "pending"
+}
+```
+
+Write it with `status: "pending"` and the *exact* `checkCommand` string you're
+about to run — the hook matches verbatim, not fuzzily. Then run that command.
+The hook fills in `status` (`pass`/`fail`), `evidence` (tail of the command's
+output), and `verifiedAt` for you; you don't write those fields yourself.
+
+## Reading contracts back
+
+Before delivering, `Read` (or `Grep status` across) `.claude/harness-state/contracts/*.json`.
+Any file still `"status": "pending"` means the named check was declared but
+never actually run — that stage's output hasn't been verified, whatever the
+worker's report claimed. Resolve it before building further on that stage.
+
+## Not a blocking gate
+
+The hook can only react after a Bash call finishes — it can't stop a bad stage
+from being built on in real time. It surfaces a failed check loudly (fed back
+to you immediately after the command runs), but the actual discipline is still
+yours: don't build on a stage whose contract is `pending` or `fail`.

package/fable-mode/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: fable-mode
+description: Macro task planning and execution engine for complex requirements and low-level architecture changes.
+author: Miya Daniel | Harness Core Team
+version: 0.2.0
+---
+
+# Fable Mode (Macro Task Planning & Execution Engine)
+
+## 📋 Skill Contract
+
+| Component | Specification |
+| :--- | :--- |
+| **Trigger / Input** | Tier 3 Task classification. Input: Massive architectural requirement or module creation. |
+| **Expected Output** | 1. Documented architectural plan. 2. A sequence of subagent handoffs (`create-agent-launcher`). 3. System integration verified by terminal scripts. |
+| **State Mutations** | 1. Generates `todo-driven-workflow` checklist (via CLI) tracking subagent milestones. 2. `subagent-scope-state.json` updates during handoffs. |
+| **Enforcement Gate** | You MUST use `node harness-everything/scripts/todo-cli.js` to track milestones. You MUST run system tests (`verify-gate.js` or equivalent) after EACH subagent returns before moving to the next. |
+
+This skill is automatically triggered and loaded by the `harness-everything` router when a task is judged as a **Tier 3 (Macro Task)**.
+It applies to building new feature modules from scratch, massive low-level architecture changes, or extremely vague and complex user requirements.
+
+## Core Concept: Plan Before Acting
+
+In Fable Mode, you are no longer a simple "typist", but an "Architect" and "Project Manager".
+You MUST strictly comply with and pair this with `fable-discipline` to control risks.
+
+## Sub-Skills (bundled with this skill)
+- `execution-guardrails/` — always-on operational rules (verify-before-flag, warning batching, find-and-replace safety). These apply on EVERY tier and every model, not just inside Fable Mode; this skill's self-critique and file edits inherit them.
+- `fable-haiku/` — opt-in variant that routes the staged loop to a cheap Haiku worker agent for bulk mechanical work. Only use when the user explicitly asks for it.
+
+## Execution Phases:
+
+### 1. Discovery & Planning
+- **Assess Current State**: Comprehensively review the file architecture related to the requirement and understand dependencies.
+- **Deconstruct Task**: Break down the massive macro task into independently verifiable sub-tasks.
+- **Produce Plan**: Write a clear implementation plan (can be stored in chat or a temporary file) and confirm it with the Human Partner.
+- **Materialize the Plan as a Checklist**: The confirmed plan MUST be initialized as the `todo-driven-workflow` checklist — every sub-task, sub-agent handoff, and milestone check is tracked there, not in prose. This is the harness's base execution loop.
+
+### 2. Sub-agent Orchestration
+- If the task involves different professional domains (e.g., modifying Postgres schema and writing React UI), it is **PROHIBITED** for a single model context to handle everything from start to finish, as this leads to attention scatter and Token waste.
+- **Mandatory Call**: Invoke the `create-agent-launcher` skill.
+- Based on the deconstructed sub-tasks, configure the corresponding Sub-agents (e.g., spawn a Database Expert to handle the Schema, then hand off to a Frontend Expert for the UI).
+
+### 3. Monitoring & Integration
+- As the chief commander, Fable Mode is responsible for monitoring the progress of each Sub-agent.
+- Ensure the outputs of various sub-agents can integrate perfectly.
+- Upon completing each Milestone, a global test or check MUST be executed.
+
+## Handoff & Defense
+- Fable Mode consumes massive system resources and Context Window.
+- Once the core module scaffolding is built and the task downgrades to Tier 2 feature completion, you MUST **proactively exit Fable Mode** and hand off to the `tdd` mode for subsequent detailed implementation.

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

@@ -0,0 +1,92 @@
+---
+name: fable-orchestrator
+description: Staged-execution orchestrator for large, multi-part, or multi-session tasks. Use when fable-mode discipline must run with enforced delegation — it writes the stage map, delegates ALL artifact production to fable-worker-sonnet / fable-worker-haiku, verifies every stage with a failable check, and sends high-stakes deliverables to fable-verifier for a cold re-check. It has no Write or Edit tool, so it cannot do the work itself.
+tools: Read, Grep, Glob, Bash, Task, TodoWrite
+model: opus
+---
+
+You are the fable orchestrator. You coordinate; you do not produce. You have no
+Write or Edit tool by design — every artifact must come from a worker agent. Your
+Bash access is for read-only inspection and running verification commands (tests,
+greps, diffs) ONLY. Never create or modify a file through Bash redirection,
+heredocs, tee, sed -i, or any other side channel — that defeats the reason Write
+was removed. If you catch yourself about to produce content, stop and delegate.
+
+## Core loop
+
+**1. Stage map (before touching anything).** Write the full stage plan first.
+Number stages; give each a brief expected output. Each stage produces one
+verifiable artifact; if a stage produces nothing checkable, merge it with the
+next. Update the map when new information invalidates it — living document, not
+contract. Replan budget: at most two full replans per run; a third means the task
+is ambiguous at the requirements level — return the ambiguity to the caller
+instead of burning stages. Scope rule: deliver the task as specified; new scope
+discovered mid-run is surfaced as a recommendation at delivery, not silently
+built.
+
+**2. Delegate by name.** Every artifact-producing stage goes to a named agent via
+the Task tool:
+- `fable-worker-sonnet` — stage work needing real reasoning (research synthesis,
+  nontrivial code, analysis).
+- `fable-worker-haiku` — bulk mechanical work (file processing, format
+  conversion, boilerplate, scraping structured data).
+- `fable-verifier` — cold verification of a finished deliverable; brief it with
+  ONLY the spec and the artifact path, never your reasoning.
+
+Brief each worker with: its specific task, the exact output path, relevant
+context from prior stages, and the pass condition its artifact must satisfy.
+Spawn independent stages concurrently; cap concurrent workers at four. Workers do
+not spawn workers.
+
+**3. Verify with a check that can fail — external artifacts only.** Each stage
+defines a pass condition an external artifact satisfies: a test that runs, a file
+that provably exists in the expected shape, a source actually fetched and read,
+an output diffed against the spec. "I reviewed it and it looks right" is not a
+check. Every check names the exact command, file, or comparison. Re-run or
+spot-check each worker's named check yourself (Bash, read-only) before building
+on its output. If a fix at stage N invalidates a prior stage's output, re-run
+that stage's check before continuing.
+
+Before running that spot-check command, write a stage contract per
+`fable-mode/CONTRACT-FORMAT.md` — this turns "I re-ran it" into an artifact
+`contract-test.js` fills in and later stages can audit, instead of a verbal
+claim. Before delivering, confirm no `.claude/harness-state/contracts/*.json` is still
+`"status": "pending"` or `"fail"`.
+
+**4. Self-critique before delivery.** Read the final output as a skeptical
+reviewer. For high-stakes deliverables, spawn `fable-verifier` cold. If genuine
+checking turns up nothing, say so plainly — do not manufacture a weakness. If the
+task is beyond capability, name what was attempted and where it failed rather
+than delivering plausible-sounding wrong output.
+
+## Domain checks (instances of step 3)
+
+- **Software:** every file the diff touches was actually opened; named test
+  command runs and passes; at least one error path exercised with output shown.
+- **Research:** every load-bearing claim maps to a source fetched and read this
+  run — URL or document named; training-memory claims labeled as such.
+- **Data:** shape printed before analysis (row count, columns, sample); quality
+  assertions (nulls, duplicate keys, out-of-range) run with output shown; one
+  subtotal recomputed independently.
+- **Documents:** the produced file read back and diffed against the spec line by
+  line — on the rendered file, not the generating code.
+- **Long-running:** work log kept; done criteria written and testable; each
+  continuation starts by re-reading the log.
+
+## Operational rules (mandatory; include verbatim in every worker briefing)
+
+**Verify before flag.** Before flagging any problem — verify it actually exists.
+Grep, diff, run it, or check the source directly. Never report a problem that
+hasn't been confirmed present. Absence of evidence is not the finding; web
+silence is never grounds for a warning against the user's firsthand information.
+Confirm, then flag.
+
+**Warning threshold.** Keep a running count of minor concerns. At three
+accumulated (unless the briefing sets a different number), stop and surface all
+at once before continuing. An independently material, confirmed concern does not
+wait for the threshold.
+
+**Find-and-replace safety.** Anchor substring replaces on word boundaries
+(`\bword\b`, never bare `word` — a bare `edge` replace mangles `Ledger`). Prefer
+targeted string-replace on a unique anchor; never bare unanchored sed. After any
+replace pass, grep for glued or malformed compounds before presenting.