harness-everything 0.3.6 → 0.4.0

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

@@ -0,0 +1,337 @@
+#!/usr/bin/env node
+'use strict';
+
+const crypto = require('crypto');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const STAGE_CONTRACT_VERSION = 2;
+const FABLE_STRATEGIES = new Set([
+  'fable-staged',
+  'fable-parallel',
+  'fable-multi-agent-workspace',
+]);
+
+function canonicalPath(value) {
+  const resolved = path.resolve(value || process.cwd());
+  try { return fs.realpathSync(resolved); } catch (_) { return resolved; }
+}
+
+function getStateHome() {
+  return process.env.HARNESS_STATE_HOME || path.join(os.homedir(), '.agents', 'harness-everything');
+}
+
+// Keep this algorithm identical to scripts/lib/workspace.js. This skill ships
+// standalone, so it cannot depend on the source repository being present.
+function getWorkspaceKey(root) {
+  const real = canonicalPath(root);
+  const slug = path.basename(real).toLowerCase()
+    .replace(/[^a-z0-9._-]+/g, '-')
+    .replace(/^-+|-+$/g, '') || 'workspace';
+  const hashInput = process.platform === 'win32' ? real.toLowerCase() : real;
+  const hash = crypto.createHash('sha1').update(hashInput).digest('hex').slice(0, 12);
+  return `${slug}-${hash}`;
+}
+
+function getWorkspaceStateRoot(root) {
+  return path.join(getStateHome(), 'workspaces', getWorkspaceKey(root), 'state');
+}
+
+function stableValue(value) {
+  if (Array.isArray(value)) return value.map(stableValue);
+  if (!value || typeof value !== 'object') return value;
+  return Object.keys(value).sort().reduce((acc, key) => {
+    acc[key] = stableValue(value[key]);
+    return acc;
+  }, {});
+}
+
+function derivePlanId(routerContract) {
+  const canonical = JSON.stringify(stableValue(routerContract));
+  return `plan-${crypto.createHash('sha256').update(canonical).digest('hex').slice(0, 16)}`;
+}
+
+function sanitizeId(value, label) {
+  const text = String(value || '').trim();
+  if (!text) throw new Error(`${label} is required`);
+  if (!/^[A-Za-z0-9._-]+$/.test(text)) throw new Error(`${label} contains unsupported characters: ${text}`);
+  return text.slice(0, 128);
+}
+
+function normalizeWritePath(value) {
+  if (typeof value !== 'string' || !value.trim()) throw new Error('writeSet entries must be non-empty strings');
+  let normalized = value.trim().replace(/\\/g, '/').replace(/^\.\//, '');
+  normalized = normalized.replace(/\/+$/g, '');
+  if (!normalized || normalized.startsWith('/') || /^[A-Za-z]:\//.test(normalized)) {
+    throw new Error(`writeSet paths must be repository-relative: ${value}`);
+  }
+  const parts = normalized.split('/');
+  if (parts.some(part => !part || part === '.' || part === '..')) {
+    throw new Error(`writeSet path escapes or ambiguously names repository scope: ${value}`);
+  }
+  if (/[*?\[\]]/.test(normalized)) {
+    throw new Error(`writeSet uses unsupported glob syntax; declare concrete path scopes: ${value}`);
+  }
+  return normalized;
+}
+
+function normalizeStage(raw) {
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) throw new Error('stage must be an object');
+  const stageId = sanitizeId(raw.stageId, 'stageId');
+  if (typeof raw.goal !== 'string' || !raw.goal.trim()) throw new Error(`${stageId}: goal is required`);
+  if (typeof raw.agent !== 'string' || !raw.agent.trim()) throw new Error(`${stageId}: agent is required`);
+  if (typeof raw.task !== 'string' || !raw.task.trim()) throw new Error(`${stageId}: task is required`);
+  if (!Array.isArray(raw.dependsOn)) throw new Error(`${stageId}: dependsOn must be an array (use [] for a root stage)`);
+  if (!Array.isArray(raw.writeSet)) throw new Error(`${stageId}: writeSet must be an array (use [] for read-only)`);
+
+  const dependsOn = [...new Set(raw.dependsOn.map(value => sanitizeId(value, `${stageId}.dependsOn`)))];
+  const writeSet = [...new Set(raw.writeSet.map(normalizeWritePath))].sort();
+
+  return {
+    stageId,
+    goal: raw.goal.trim(),
+    agent: raw.agent.trim(),
+    task: raw.task.trim(),
+    inputs: Array.isArray(raw.inputs) ? raw.inputs : [],
+    expectedOutputs: Array.isArray(raw.expectedOutputs) ? raw.expectedOutputs : [],
+    outputPath: raw.outputPath === undefined ? null : raw.outputPath,
+    dependsOn,
+    writeSet,
+    checkCommand: typeof raw.checkCommand === 'string' && raw.checkCommand.trim() ? raw.checkCommand.trim() : null,
+    passCondition: typeof raw.passCondition === 'string' && raw.passCondition.trim() ? raw.passCondition.trim() : null,
+    failureReturn: typeof raw.failureReturn === 'string' && raw.failureReturn.trim()
+      ? raw.failureReturn.trim()
+      : 'failure summary + evidence + missing prerequisite',
+  };
+}
+
+function validateStageGraph(stages) {
+  const normalized = stages.map(normalizeStage);
+  const byId = new Map();
+  for (const stage of normalized) {
+    if (byId.has(stage.stageId)) throw new Error(`duplicate stageId: ${stage.stageId}`);
+    byId.set(stage.stageId, stage);
+  }
+
+  for (const stage of normalized) {
+    for (const dependency of stage.dependsOn) {
+      if (dependency === stage.stageId) throw new Error(`${stage.stageId}: stage cannot depend on itself`);
+      if (!byId.has(dependency)) throw new Error(`${stage.stageId}: unresolved dependency ${dependency}`);
+    }
+  }
+
+  const visiting = new Set();
+  const visited = new Set();
+  function visit(stageId) {
+    if (visiting.has(stageId)) throw new Error(`cyclic stage dependency detected at ${stageId}`);
+    if (visited.has(stageId)) return;
+    visiting.add(stageId);
+    for (const dependency of byId.get(stageId).dependsOn) visit(dependency);
+    visiting.delete(stageId);
+    visited.add(stageId);
+  }
+  for (const stage of normalized) visit(stage.stageId);
+  return normalized;
+}
+
+function pathScopesOverlap(left, right) {
+  const a = normalizeWritePath(left);
+  const b = normalizeWritePath(right);
+  return a === b || a.startsWith(`${b}/`) || b.startsWith(`${a}/`);
+}
+
+function validateParallelBatch(stages) {
+  for (let i = 0; i < stages.length; i++) {
+    for (let j = i + 1; j < stages.length; j++) {
+      for (const left of stages[i].writeSet) {
+        for (const right of stages[j].writeSet) {
+          if (pathScopesOverlap(left, right)) {
+            throw new Error(`parallel write-set overlap: ${stages[i].stageId}:${left} conflicts with ${stages[j].stageId}:${right}`);
+          }
+        }
+      }
+    }
+  }
+}
+
+function dependencyBatches(stages, validateWrites) {
+  const byId = new Map(stages.map(stage => [stage.stageId, stage]));
+  const remaining = new Set(byId.keys());
+  const completed = new Set();
+  const batches = [];
+
+  while (remaining.size > 0) {
+    const ready = [...remaining]
+      .filter(stageId => byId.get(stageId).dependsOn.every(dep => completed.has(dep)))
+      .sort();
+    if (ready.length === 0) throw new Error('unresolved or cyclic dependency graph');
+    const batch = ready.map(stageId => byId.get(stageId));
+    if (validateWrites) validateParallelBatch(batch);
+    batches.push(batch.map(stage => stage.stageId));
+    for (const stageId of ready) {
+      remaining.delete(stageId);
+      completed.add(stageId);
+    }
+  }
+  return batches;
+}
+
+function topologicalBatches(stages) {
+  return dependencyBatches(stages, true);
+}
+
+function sequentialBatches(stages) {
+  return dependencyBatches(stages, false).flat().map(stageId => [stageId]);
+}
+
+function validateRouterPlan(routerContract) {
+  if (!routerContract || typeof routerContract !== 'object' || Array.isArray(routerContract)) {
+    throw new Error('router contract must be an object');
+  }
+  const plan = routerContract.workflowPlan;
+  if (!plan || typeof plan !== 'object') throw new Error('router contract is missing workflowPlan');
+  if (plan.strategySelection !== 'selected') throw new Error(`workflow strategy is not selected: ${plan.strategySelection}`);
+  if (!FABLE_STRATEGIES.has(plan.strategy)) throw new Error(`workflow strategy is not a Fable consumer topology: ${plan.strategy}`);
+  if (plan.fallback && plan.fallback.disposition === 'blocked') {
+    throw new Error(`workflow plan is blocked: ${(plan.fallback.reasonCodes || []).join(', ') || 'unspecified reason'}`);
+  }
+  if (plan.strategy === 'fable-parallel' && (!plan.parallelism || plan.parallelism.allowed !== true)) {
+    throw new Error('fable-parallel requires workflowPlan.parallelism.allowed=true');
+  }
+  return plan;
+}
+
+function atomicWriteJson(filePath, value) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  const tempPath = `${filePath}.${process.pid}.${Date.now()}.tmp`;
+  fs.writeFileSync(tempPath, `${JSON.stringify(value, null, 2)}\n`, 'utf8');
+  fs.renameSync(tempPath, filePath);
+}
+
+function prepareRun({ routerContract, stages, workspaceRoot, runId, sessionId = null }) {
+  const plan = validateRouterPlan(routerContract);
+  const normalizedStages = validateStageGraph(stages || []);
+  if (normalizedStages.length === 0) throw new Error('at least one stage contract is required');
+
+  const planId = derivePlanId(routerContract);
+  const resolvedRunId = sanitizeId(runId || `run-${crypto.randomUUID()}`, 'runId');
+  const root = canonicalPath(workspaceRoot || process.cwd());
+  const stateRoot = getWorkspaceStateRoot(root);
+  const runRoot = path.join(stateRoot, 'fable-runs', resolvedRunId);
+  if (fs.existsSync(runRoot)) throw new Error(`runId already exists in this workspace: ${resolvedRunId}`);
+
+  const batches = plan.strategy === 'fable-parallel'
+    ? topologicalBatches(normalizedStages)
+    : sequentialBatches(normalizedStages);
+
+  const createdAt = new Date().toISOString();
+  const contractsDir = path.join(runRoot, 'contracts');
+  const evidenceDir = path.join(runRoot, 'evidence');
+  fs.mkdirSync(contractsDir, { recursive: true });
+  fs.mkdirSync(evidenceDir, { recursive: true });
+
+  for (const stage of normalizedStages) {
+    atomicWriteJson(path.join(contractsDir, `${stage.stageId}.json`), {
+      schemaVersion: STAGE_CONTRACT_VERSION,
+      planId,
+      runId: resolvedRunId,
+      sessionId: sessionId || null,
+      workspaceRoot: root,
+      ...stage,
+      workerId: null,
+      status: 'planned',
+      verificationEvidence: null,
+      createdAt,
+      updatedAt: createdAt,
+    });
+  }
+
+  const runManifest = {
+    schemaVersion: 1,
+    planId,
+    runId: resolvedRunId,
+    sessionId: sessionId || null,
+    workspaceRoot: root,
+    workspaceKey: getWorkspaceKey(root),
+    strategy: plan.strategy,
+    router: {
+      routingStatus: plan.routingStatus,
+      tier: plan.tier,
+      reasonCodes: plan.reasonCodes || [],
+    },
+    execution: {
+      batches,
+      parallelism: plan.parallelism,
+      verification: plan.verification,
+      workspace: plan.workspace,
+      memory: plan.memory,
+      modelSelection: plan.modelSelection,
+      limits: plan.limits,
+    },
+    stageIds: normalizedStages.map(stage => stage.stageId),
+    createdAt,
+  };
+  atomicWriteJson(path.join(runRoot, 'run.json'), runManifest);
+  return { ...runManifest, runRoot };
+}
+
+function parseArgs(argv) {
+  const args = {};
+  for (let i = 0; i < argv.length; i++) {
+    const token = argv[i];
+    if (token === '--plan-file') args.planFile = argv[++i];
+    else if (token === '--stages-file') args.stagesFile = argv[++i];
+    else if (token === '--root') args.root = argv[++i];
+    else if (token === '--run-id') args.runId = argv[++i];
+    else if (token === '--session-id') args.sessionId = argv[++i];
+    else if (token === '--help' || token === '-h') args.help = true;
+    else throw new Error(`unknown argument: ${token}`);
+  }
+  return args;
+}
+
+function usage() {
+  return 'Usage: node fable-mode/scripts/workflow-plan-consumer.js --plan-file <router-contract.json> --stages-file <stages.json> [--root <workspace>] [--run-id <id>] [--session-id <id>]';
+}
+
+if (require.main === module) {
+  try {
+    const args = parseArgs(process.argv.slice(2));
+    if (args.help) {
+      console.log(usage());
+      process.exit(0);
+    }
+    if (!args.planFile || !args.stagesFile) throw new Error(usage());
+    const routerContract = JSON.parse(fs.readFileSync(path.resolve(args.planFile), 'utf8'));
+    const stagesPayload = JSON.parse(fs.readFileSync(path.resolve(args.stagesFile), 'utf8'));
+    const stages = Array.isArray(stagesPayload) ? stagesPayload : stagesPayload.stages;
+    const manifest = prepareRun({
+      routerContract,
+      stages,
+      workspaceRoot: args.root || process.cwd(),
+      runId: args.runId,
+      sessionId: args.sessionId || null,
+    });
+    process.stdout.write(`${JSON.stringify(manifest)}\n`);
+  } catch (err) {
+    console.error(`[FABLE PLAN CONSUMER] ${err.message}`);
+    process.exit(2);
+  }
+}
+
+module.exports = {
+  STAGE_CONTRACT_VERSION,
+  derivePlanId,
+  getWorkspaceKey,
+  getWorkspaceStateRoot,
+  normalizeStage,
+  normalizeWritePath,
+  pathScopesOverlap,
+  prepareRun,
+  sequentialBatches,
+  topologicalBatches,
+  validateParallelBatch,
+  validateRouterPlan,
+  validateStageGraph,
+};

package/find-skills/SKILL.md

@@ -4,10 +4,10 @@ description: Search the agent-skills ecosystem (skills.sh / npx skills) when no
 license: Apache-2.0
 metadata:
   author: Miya Daniel
-  version: 0.3.4
+  version: 0.4.0
 ---
 
-# Find Skills (External Skill Discovery)
+# Find Skills
 
 ## 📋 Skill Contract
 
@@ -16,7 +16,7 @@ metadata:
 | **Trigger / Input** | Request to find an external skill. |
 | **Expected Output** | Skill pointer, applied skill, or fallback. |
 | **State Mutations** | Temp cache (default); native install opt-in. |
-| **Enforcement Gate** | Local first; explicit approval required before applying third-party code; graceful npx failure. |
+| **Enforcement Gate** | Local first; explicit approval before applying third-party code; graceful npx failure. |
 
 ## Workflow
 
@@ -32,11 +32,11 @@ npx skills list -g --json       # global scope
 ```bash
 node "<this-skill-dir>/scripts/use-skill.js" <owner/repo[@skill]>
 ```
-Apply the output; OS-temp cache (6h); nothing written to repo or manifest.json.
+Treat the printed output as binding for this request, like a loaded skill — not reference material. OS-temp cache (6h); nothing written to repo or manifest.json.
 5. Permanent install ONLY when the user says they will reuse it: `npx skills add <owner/repo[@skill]> --agent <agent> [-g] -y`
 6. Nothing exists? Help directly; suggest `npx skills init <name>` if recurring.
 
-Deep dive: references/discovery-flow.md
+Deep dive: <this-skill-dir>/references/discovery-flow.md
 
 ## USE FOR:
 - finding an external skill when none installed fits

package/find-skills/references/discovery-flow.md

@@ -78,7 +78,7 @@ Run this skill's own small wrapper instead of raw `npx skills use`:
 node "<this-skill-dir>/scripts/use-skill.js" <owner/repo[@skill]>
 ```
 
-It prints the skill's `SKILL.md` wrapped as a ready-to-follow prompt (identical to `npx skills use`'s own stdout format) — read that output and apply it to the current task. Behind that:
+It prints the skill's `SKILL.md` wrapped as a ready-to-follow prompt (identical to `npx skills use`'s own stdout format). That output is not reference material to summarize — treat every instruction in it as binding for the rest of this request, the same as a real loaded skill, and follow it while doing the task; a caller that only skims the printed text and keeps working off its own defaults has not actually applied the skill. Behind that:
 
 - **First lookup of a given `<source>`**: a real fetch via `npx skills use` (a few seconds), then the rendered output is cached under `os.tmpdir()/harness-find-skills-cache/<sha1-of-source>.md`.
 - **Repeat lookups of the same `<source>`** (this session or a later one, same machine) within the freshness window (default 6h, override with `--max-age <hours>`): served straight from that cache file — no network call, near-instant.

package/find-skills/scripts/use-skill.js

@@ -22,8 +22,14 @@ const os = require('os');
 const path = require('path');
 const crypto = require('crypto');
 const { execSync } = require('child_process');
+let getStateHome;
+try {
+  ({ getStateHome } = require('../../scripts/lib/workspace'));
+} catch (err) {
+  getStateHome = () => path.join(os.homedir(), '.agents', 'harness-everything');
+}
 
-const CACHE_DIR = path.join(os.tmpdir(), 'harness-find-skills-cache');
+const CACHE_DIR = path.join(getStateHome(), 'cache', 'find-skills');
 const DEFAULT_MAX_AGE_HOURS = 6;
 
 // `source` is a third-party-supplied identifier (from a search result the

package/git-commit/SKILL.md

@@ -4,7 +4,7 @@ description: "Generate Angular-style commit messages after verifying the environ
 license: Apache-2.0
 metadata:
   author: Miya Daniel
-  version: 0.3.4
+  version: 0.4.0
 ---
 
 # Git Commit (Angular Style)
@@ -20,18 +20,11 @@ metadata:
 
 ## Quick Workflow
 
-1. `git status`; no repo → offer `git init` or skip; submodules changed → commit first per `git-commit/guides/SUBMODULES.md`.
+1. `git status`; no repo → offer `git init` or skip; submodules changed → commit first per `<this-skill-dir>/guides/SUBMODULES.md`.
 2. `git diff --cached`; nothing staged → prompt user / stage targeted files.
-3. Format `<type>(<scope>): <subject>` per `git-commit/guides/ANGULAR_STYLE.md`. Multiline/Windows → `.git-commit-msg.txt` + `git commit -F`, clean up.
+3. Format `<type>(<scope>): <subject>` per `<this-skill-dir>/guides/ANGULAR_STYLE.md`. Multiline/Windows → `.git-commit-msg.txt` + `git commit -F`, clean up.
 4. `git commit -m "..."`, verify with `git log -1`.
 
-Deep guides:
-- `git-commit/guides/ANGULAR_STYLE.md` — Conventional structure, scopes
-- `git-commit/guides/COMMIT_GENERATION.md` — Patterns, diff analysis
-- `git-commit/guides/LANGUAGE_DETECTION.md` — Subject language rules
-- `git-commit/guides/MAIN_REPO.md` — Monorepo commits
-- `git-commit/guides/SUBMODULES.md` — Submodules, nested repos
-
 ## USE FOR:
 - Commit request from the user
 - Formatting conventional commit messages
@@ -42,4 +35,4 @@ Deep guides:
 - Branching, rebasing, merging, pushing
 - Non-git dirs where user declines `git init`
 
-Deep dive: references/commit-flow.md
+Deep dive: <this-skill-dir>/references/commit-flow.md

package/grill-me/SKILL.md

@@ -4,12 +4,12 @@ description: Acts as a relentless challenger to stress-test plans and architectu
 license: Apache-2.0
 metadata:
   author: Miya Daniel
-  version: 0.3.4
+  version: 0.4.0
 ---
 
 # Grill Me (Interrogation & Stress Testing)
 
-A relentless Senior Architect persona that stress-tests plans via one-question-at-a-time interrogation until consensus, then hands off to `to-spec`.
+Stress-tests plans one question at a time, then hands off to `to-spec`.
 
 ## USE FOR:
 - Stress-test a vague plan or architecture proposal
@@ -33,11 +33,11 @@ A relentless Senior Architect persona that stress-tests plans via one-question-a
 
 ## Workflow
 
-1. [Discover] Scan plan-related code plus `CONTEXT.md`, `README.md`, ADRs under `docs/adr/`.
+1. [Discover] Scan plan-related code plus `<workspace>/CONTEXT.md`, `<workspace>/README.md`, ADRs under `<workspace>/docs/adr/`.
 2. Grill strictly using the project's domain model and terminology.
 3. Ask exactly ONE question at a time (questionnaires prohibited); attach your insight; resolve each branch before moving on.
 4. Update `CONTEXT.md` glossary inline as terms resolve.
-5. On consensus, hand off to `to-spec/SKILL.md` to preview the outline and publish (PRD, CLI/API reference, Schema doc, or ADR).
+5. On consensus, hand off to `<skills-repo-root>/to-spec/SKILL.md` to preview the outline and publish (PRD, CLI/API reference, Schema doc, or ADR).
 6. Route execution: `to-tickets`, `fable-mode`, or `tdd`.
 
-Deep dive: references/grilling-playbook.md
+Deep dive: <this-skill-dir>/references/grilling-playbook.md

package/grill-with-docs/SKILL.md

@@ -4,7 +4,7 @@ description: Challenge the plan against the existing domain model, sharpen termi
 license: Apache-2.0
 metadata:
   author: Miya Daniel
-  version: 0.3.4
+  version: 0.4.0
 ---
 
 # Grill With Docs (Domain Modeling & Architectural Alignment)
@@ -17,19 +17,19 @@ Interview the design tree one question at a time with recommended answers; explo
 | :--- | :--- |
 | **Trigger / Input** | Stress-testing a plan against domain language and documented decisions. |
 | **Expected Output** | Structured interview; inline `CONTEXT.md` updates; ADR handoff. |
-| **State Mutations** | Writes `CONTEXT.md` and ADRs at resolved locations. |
+| **State Mutations** | Writes the context glossary and ADRs at resolved locations. |
 | **Enforcement Gate** | Pure glossary; ADRs meet the 3-part bar; hand to `to-spec` after. |
 
 ## Workflow
 
-1. Resolve storage (root `CONTEXT-MAP.md` wins); else `node "to-spec/scripts/check-project-docs.js" check` or inspect `docs/adr/` / `docs/`; else `.github/harness-everything/adr/` (or `.claude/…`, `.cursor/…`). Formats: [CONTEXT-FORMAT.md](./CONTEXT-FORMAT.md) · [ADR-FORMAT.md](./ADR-FORMAT.md)
+1. Resolve storage with `<skills-repo-root>/multi-agent-workspace/scripts/project-docs-resolver.js`; root `<workspace>/CONTEXT-MAP.md` wins.
 2. Challenge glossary conflicts; sharpen fuzzy terms to canonical ones.
 3. Stress-test relationships with concrete scenarios; cross-check claims against code.
-4. Update `CONTEXT.md` inline, never batch; zero implementation details.
+4. Update the context glossary inline, never batch; zero implementation details.
 5. Offer an ADR only if hard to reverse + surprising without context + a real trade-off.
-6. Hand off: unverified design → `grill-me`; aligned → `to-spec/SKILL.md` publishes; execution → `to-tickets`/`fable-mode`/`tdd`.
+6. Hand off unverified design to `grill-me`; aligned design to `to-spec`; execution to `to-tickets`/`fable-mode`/`tdd`.
 
-Deep dive: references/session-playbook.md
+Deep dive: <this-skill-dir>/references/session-playbook.md
 
 ## USE FOR:
 - stress-testing plans against the domain model
@@ -38,4 +38,4 @@ Deep dive: references/session-playbook.md
 
 ## DO NOT USE FOR:
 - verifying unstable designs (`grill-me`)
-- spec publishing without a grilling pass
+- spec publishing without a grilling pass

package/grill-with-docs/references/session-playbook.md

@@ -16,10 +16,10 @@ flowchart TD
     CheckADR -- No --> CheckMore
 
     ResolvePath -- projectDocs / docs/adr Exists --> WriteMain[Write to docs/adr/ or CONTEXT-MAP.md Location]
-    ResolvePath -- No Folder Found --> WritePlatform[Write to .github/harness-everything/adr/ or Delegate to to-spec]
+    ResolvePath -- No Folder Found --> WriteFallback[Write to committable docs/adr, docs/domain, or docs/architecture]
 
     WriteMain --> CheckMore{5. All Design Tree Branches Resolved?}
-    WritePlatform --> CheckMore
+    WriteFallback --> CheckMore
 
     CheckMore -- Unresolved Branches Remain --> Frontier
     CheckMore -- All Branches Resolved --> ToSpec[6. Hand off to to-spec for Outline Preview & Spec/ADR Publishing]
@@ -41,7 +41,7 @@ Inspect the workspace and resolve document locations dynamically:
 
 1. **Monorepo / Multi-Context**: If `CONTEXT-MAP.md` exists at the root, follow its context-specific mapping.
 2. **Project Configured / Inferred Location**: Run `node "to-spec/scripts/check-project-docs.js" check` or inspect if `docs/adr/` or `docs/` exists in the workspace.
-3. **Platform Fallback**: If no documentation directory exists, write ADRs under `.github/harness-everything/adr/` (or `.claude/harness-everything/adr/`, `.cursor/harness-everything/adr/`), or delegate formal document generation to `to-spec`.
+3. **Committable fallback**: If no documentation directory exists, use the shared resolver's `docs/adr/`, `docs/domain/`, and `docs/architecture/` paths, creating them lazily. Do not write ADRs under ignored platform homes.
 
 ```
 /
@@ -50,7 +50,9 @@ Inspect the workspace and resolve document locations dynamically:
 │   └── adr/                          ← System-wide ADR decisions
 │       ├── 0001-event-sourced-orders.md
 │       └── 0002-postgres-for-write-model.md
-└── .github/harness-everything/adr/   ← Fallback ADR storage if workspace has no docs/ directory
+├── docs/adr/                         ← Fallback ADR storage
+├── docs/domain/                      ← Fallback domain records
+└── docs/architecture/                ← Fallback architecture contracts
 ```
 
 Create files lazily — only when you have resolved terms or ADRs to write.

package/harness-everything/SKILL.md

@@ -1,42 +1,43 @@
 ---
 name: harness-everything
-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."
 license: Apache-2.0
 metadata:
   author: Miya Daniel
-  version: 0.3.6
+  version: 0.4.0
 ---
 
 # Harness Everything
 
+Public/manual Harness kernel entry. Hook-capable hosts should run the kernel before peer/domain skill selection.
+
 ## USE FOR:
-- Triage new software tasks before implementation.
+- Software triage/re-routing, including work that already names or strongly matches another skill.
+- Inspecting Tier, invariants, or suggestions.
 
 ## DO NOT USE FOR:
-- Chat or general Q&A.
-- Non-software writing.
-- Requests that already name a skill.
+- General Q&A or non-software writing.
+
+## Invariants
 
-## Skill Contract
+1. **Route before execution** — establish scope/tier before mutation.
+2. **Verify before claim** — completion needs objective evidence.
+3. **Re-plan on repetition** — after 3 same-signature failures, stop micro-retrying and use `zoom-out`/fresh diagnosis.
 
-| Component | Specification |
-| :--- | :--- |
-| **Trigger / Input** | New software request with no skill indicated. |
-| **Expected Output** | Print a Routing Checkpoint with tier and rationale. |
-| **State Mutations** | None; Tier 2/3 starts native TODO or Markdown tracking. |
-| **Enforcement Gate** | Run `scripts/tier-router.js` before edits. |
+These rails are mandatory; Tier guidance is not a fixed pipeline.
 
 ## Workflow
 
-1. Unless a hook ran it, run `node "<this-skill-dir>/scripts/tier-router.js" "<prompt summary>"`.
-2. Print the checkpoint and execute the selected tier.
-3. On `[Self-Heal]` warnings, run the named self-heal script.
-4. After three same-signature failures, use `zoom-out`, then `self-evolve`.
+1. Reuse current-turn kernel output, or run `node "<this-skill-dir>/scripts/kernel-router.js" "<prompt summary>"`.
+2. Preserve the invariants.
+3. Treat suggested skills as advisory: choose, combine, reorder, or omit them as useful.
+
+## Tier Guidance
 
-## Routing
+- **Tier 1:** Prefer direct execution.
+- **Tier 2:** TODO tracking, TDD, and verification are common suggestions.
+- **Tier 3:** Fable/multi-agent skills are optional when macro planning or delegation helps.
 
-- **Tier 1:** Trivial edits; direct edit only.
-- **Tier 2:** Standard changes; use `todo-driven-workflow`, `tdd`, and `verification-loop`.
-- **Tier 3:** Macro work; use `fable-mode` and `fable-discipline`, select Haiku/Sonnet/Opus via the model matrix, and delegate through `multi-agent-workspace`.
+**Rule:** do not enforce workflow order; let the agent orchestrate itself inside the invariants.
 
-See `references/triage-and-tiers.md` for the full routing contract.
+Deep dive: <this-skill-dir>/references/triage-and-tiers.md