harness-everything 0.2.0

package/grill-with-docs/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: grill-with-docs
+description: Grilling session that challenges your plan against the existing domain model, sharpens terminology, and updates documentation (CONTEXT.md, ADRs) inline as decisions crystallise. Use when user wants to stress-test a plan against their project's language and documented decisions.
+author: Miya Daniel | Harness Core Team
+version: 0.2.0
+---
+
+## 📋 Skill Contract
+
+| Component | Specification |
+| :--- | :--- |
+| **Trigger / Input** | User wants to stress-test a plan against the project's existing domain language and documented decisions (`CONTEXT.md`, ADRs). |
+| **Expected Output** | A one-question-at-a-time interview walking the design tree to resolution; `CONTEXT.md` updated inline as terms resolve; new ADRs created only when a decision is hard-to-reverse, surprising, and a genuine trade-off. |
+| **State Mutations** | Creates/edits `CONTEXT.md` and `docs/adr/*.md` (or the per-context equivalents under a `CONTEXT-MAP.md` layout). |
+| **Enforcement Gate** | `CONTEXT.md` **MUST** stay a pure glossary — no implementation details. An ADR **MUST NOT** be offered unless all three criteria (hard to reverse, surprising without context, real trade-off) hold. |
+
+<what-to-do>
+
+Interview me relentlessly about every aspect of this plan until we reach a shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one. For each question, provide your recommended answer.
+
+Ask the questions one at a time, waiting for feedback on each question before continuing.
+
+If a question can be answered by exploring the codebase, explore the codebase instead.
+
+</what-to-do>
+
+<supporting-info>
+
+## Domain awareness
+
+During codebase exploration, also look for existing documentation:
+
+### File structure
+
+Most repos have a single context:
+
+```
+/
+├── CONTEXT.md
+├── docs/
+│   └── adr/
+│       ├── 0001-event-sourced-orders.md
+│       └── 0002-postgres-for-write-model.md
+└── src/
+```
+
+If a `CONTEXT-MAP.md` exists at the root, the repo has multiple contexts. The map points to where each one lives:
+
+```
+/
+├── CONTEXT-MAP.md
+├── docs/
+│   └── adr/                          ← system-wide decisions
+├── src/
+│   ├── ordering/
+│   │   ├── CONTEXT.md
+│   │   └── docs/adr/                 ← context-specific decisions
+│   └── billing/
+│       ├── CONTEXT.md
+│       └── docs/adr/
+```
+
+Create files lazily — only when you have something to write. If no `CONTEXT.md` exists, create one when the first term is resolved. If no `docs/adr/` exists, create it when the first ADR is needed.
+
+## During the session
+
+### Challenge against the glossary
+
+When the user uses a term that conflicts with the existing language in `CONTEXT.md`, call it out immediately. "Your glossary defines 'cancellation' as X, but you seem to mean Y — which is it?"
+
+### Sharpen fuzzy language
+
+When the user uses vague or overloaded terms, propose a precise canonical term. "You're saying 'account' — do you mean the Customer or the User? Those are different things."
+
+### Discuss concrete scenarios
+
+When domain relationships are being discussed, stress-test them with specific scenarios. Invent scenarios that probe edge cases and force the user to be precise about the boundaries between concepts.
+
+### Cross-reference with code
+
+When the user states how something works, check whether the code agrees. If you find a contradiction, surface it: "Your code cancels entire Orders, but you just said partial cancellation is possible — which is right?"
+
+### Update CONTEXT.md inline
+
+When a term is resolved, update `CONTEXT.md` right there. Don't batch these up — capture them as they happen. Use the format in [CONTEXT-FORMAT.md](./CONTEXT-FORMAT.md).
+
+`CONTEXT.md` should be totally devoid of implementation details. Do not treat `CONTEXT.md` as a spec, a scratch pad, or a repository for implementation decisions. It is a glossary and nothing else.
+
+### Offer ADRs sparingly
+
+Only offer to create an ADR when all three are true:
+
+1. **Hard to reverse** — the cost of changing your mind later is meaningful
+2. **Surprising without context** — a future reader will wonder "why did they do it this way?"
+3. **The result of a real trade-off** — there were genuine alternatives and you picked one for specific reasons
+
+If any of the three is missing, skip the ADR. Use the format in [ADR-FORMAT.md](./ADR-FORMAT.md).
+
+</supporting-info>

package/harness-everything/SKILL.md

@@ -0,0 +1,141 @@
+---
+name: harness-everything
+description: The single entry point and dynamic router for the Harness ecosystem. Triage tasks into Tier 1, 2, or 3.
+author: Miya Daniel | Harness Core Team
+version: 0.2.0
+---
+
+# Harness Everything (System Main Entry & Dynamic Router)
+
+## 📋 Skill Contract
+
+| Component | Specification |
+| :--- | :--- |
+| **Trigger / Input** | Every new user request where no specific skill is already indicated — the mandatory first load, run via `scripts/tier-router.js "<prompt>"`. |
+| **Expected Output** | A Tier determination (1/2/3) and a mandatory "🚦 Harness OS Routing Checkpoint" block at the very start of the response, listing the tier, rationale, and routed skills/guides. |
+| **State Mutations** | None directly — orchestrates which other skills/guides get loaded and, for Tier 2/3, triggers `todo-driven-workflow` checklist initialization. |
+| **Enforcement Gate** | **MUST** run `scripts/tier-router.js` (or reuse the `UserPromptSubmit` hook's output for the same turn) before deciding the tier — the routing checkpoint output is mandatory, not optional. Rule of 3: 3 consecutive failed fix attempts on the same signature **MUST** stop further edits and force `zoom-out`. |
+
+This is the single entry point for the entire Harness Skills ecosystem. When you receive a new request from the user and no specific Skill is indicated, you **MUST** prioritize loading this Skill to perform Task Triage.
+
+## 1. Core Rule: Global Underlying OS & Base Execution Loop
+Before taking any action, you must awaken and load the principles of `install-cognitive-os`.
+No matter how simple the task is, your behavior must comply with the **Discover > Think > Try > Summarize > Record** cognitive loop.
+Never rush to act before understanding the environment; establish contextual awareness first.
+
+**Base Execution Loop (`todo-driven-workflow`)**: The cognitive loop above defines *how you think*; `todo-driven-workflow` defines *how you execute*. For every **Tier 2 and Tier 3** task, you MUST load `todo-driven-workflow` and initialize its checklist BEFORE editing any file — it is the foundational step-by-step execution layer of this harness (break down into 3-7 verifiable sub-tasks, one `in-progress` at a time, verify with real evidence before marking `completed`). Tier 1 tasks are exempt to avoid checklist bloat.
+
+**Always-On Disciplines** (apply on every tier, alongside the loops above):
+- `fable-mode/execution-guardrails` — verify-before-flag, warning batching, find-and-replace safety. These are behavioral contracts, not Tier-3-only rules.
+- `verify-before-claim` — never assert external framework/API behavior or unmeasured performance numbers from training memory; verify against an authoritative source first.
+- `install-cognitive-os`'s Global Output Normalization — lead with direct answers, suppress preambles/recaps/pleasantries, and enforce natural locale terminology (§6).
+
+**Self-Healing Toolchain (工欲善其事,必先利其器)**: The harness may have been installed from a different editor than the one currently running (e.g., installed via Claude Code, now opened in Copilot). During the `[Discover]` phase, audit the workspace's integration touchpoints and repair any that are missing — the script is idempotent and delegates to the installer, so re-running is always safe:
+```bash
+node "<this-skill-dir>/scripts/self-heal.js"          # audit + auto-repair missing touchpoints
+node "<this-skill-dir>/scripts/self-heal.js" --check  # audit only, never writes
+```
+Also run this immediately whenever the `bootstrap.js` SessionStart output shows a `[Self-Heal] Missing integration touchpoints` warning. Exception: if the user says they intentionally removed one of these files, respect that and do not re-create it.
+
+## 2. Task Triage
+To avoid "over-engineering" and maximize efficiency, you must categorize the user's task during the `[Think]` phase and take the corresponding action path.
+- **MANDATORY**: Run the Tier Router script before deciding the tier. The script lives at `scripts/tier-router.js` **inside this skill's own directory** — resolve the path from wherever this SKILL.md was loaded (do not guess a hard-coded location):
+  ```bash
+  node "<this-skill-dir>/scripts/tier-router.js" "<Brief summary of the user's prompt>"
+  ```
+- You MUST follow the `REQUIRED TIER` output by the script.
+- If a `UserPromptSubmit` hook already ran the router this turn (its `[Tier Routing Pre-check]` output is visible in context), reuse that output instead of running it again.
+
+### Mandated Routing Checkpoint Output
+At the very beginning of your response to the user, you **MUST** output a clear, stylized routing report. This report is mandatory for all entries via `harness-everything`. It must list the determined Tier and the exact routing targets:
+```markdown
+## 🚦 Harness OS Routing Checkpoint
+- **Active Tier**: Tier X (Tier Name)
+- **Rationale**: Short 1-sentence reason from the tier router.
+- **Routed Skills, Guides & Actions**:
+  - `path/to/skill/or/guide.md` (Brief description of why this applies)
+  - ...
+```
+
+### Proactive Copilot & VS Code Instruction (Avoid Silent Degrades)
+If you are running in VS Code or GitHub Copilot, you do not have automated hooks to run scripts on your behalf.
+- You **MUST** proactively run the tier-router script (`node harness-everything/scripts/tier-router.js "<prompt>"`) or simulate its routing logic manually at the start.
+- **NEVER degrade newly added features or structural extensions to Tier 1.** Copilot is highly prone to treating new feature requests as trivial Tier 1 direct edits. If the request adds *any* new logic, a new API endpoint, or a new file/module, it **MUST** be triaged as **Tier 2 (Standard Task)** or **Tier 3 (Macro Task)**. This activates:
+  1. The `todo-driven-workflow` checklist (mandatory step-by-step progress tracking).
+  2. Multi-agent spawning / sub-agents via `create-agent-launcher` or macro plan orchestration via `fable-mode`.
+  3. The memory summarization & evolution sequence via `self-evolve` upon completion, ensuring new knowledge is registered in workspace memory.
+
+### Tier 1: Trivial Tasks & Daily Chores
+- **Characteristics**: Fixing typos, simple modifications to a single function, asking/explaining code, syntax adjustments. Or simple `git-commit` and `rewrite-commits`.
+- **Action Strategy (Direct Execution)**:
+  - **PROHIBITED** from writing large plans.
+  - **PROHIBITED** from calling `create-agent-launcher` or `fable-mode`.
+  - Execute the modification directly based on requirements, or load `git-commit` / `rewrite-commits`. Perform a simple `[Record]` after modifying.
+
+### Tier 2: Standard Tasks & Architectural Review
+- **Characteristics**: Adding a single API endpoint, fixing a specific bug, modifications requiring coordination across 2-3 files. Or requiring stress testing and benchmark evaluation for specific designs.
+- **Action Strategy (TDD, Deep Context & Domain Expertise)**:
+  - **Initialize the Base Execution Loop**: Load `todo-driven-workflow` and lay out the checklist first (the TDD Red/Green/Refactor phases map naturally onto todo items).
+  - **Information Depth Requirement**: Before entering TDD, you MUST perform a deep context trace (find references, call sites, and related interfaces). Superficial fixes that break dependencies are strictly forbidden.
+  - **Load Domain Experts (領域專家召喚)**: Based on the tech stack detected in Tier 1, explicitly search for and load the corresponding **Domain Skills** (e.g., `security-review` from this repo, or `frontend-patterns` / `api-design` from the user's legacy skill library) to inject robust expert knowledge into your context.
+  - Development tasks: Automatically load and follow the `tdd` (Test-Driven Development) skill. Write tests first (Red) -> Implement (Green) -> Refactor.
+  - Before starting feature work on a busy repository, consider loading `using-git-worktrees` to isolate your workspace and prevent workspace pollution.
+  - If the user requests grilling or refactoring a plan, load `grill-me` (pure Q&A) or `improve-codebase-architecture` (deep architectural analysis).
+  - If the user requests "scoring" or "benchmark comparison", load `eval-harness` for quantitative scoring and summarization.
+  - **Pre-Delivery Gate**: Before declaring the task done or creating a PR, load `verification-loop` (build / types / lint / tests / security scan / diff review). For changes touching auth, input handling, secrets, or network boundaries, additionally load `security-review`.
+
+### Tier 3: Macro Tasks & Documentation
+- **Characteristics**: New project initialization, low-level architecture refactoring, vague and massive requirements (e.g., "Help me write a user login system"). Or lack of global documentation.
+- **Action Strategy (Multi-Agent Orchestration & Domain Infusion)**:
+  - If initializing a multi-agent system workspace, load `build-multi-agent-system` to scaffold the 6 functional zones, memory relational indexes, and immutable routing laws.
+  - If project-level documentation needs to be created, load `repo-docs`.
+  - If establishing a large system design, strongly recommend loading `grill-with-docs` first to document decisions (ADR, CONTEXT) before proceeding.
+  - **Sub-Agent Specialization**: When calling `create-agent-launcher`, you MUST inject robust Domain Skills into the sub-agent's persona (e.g., passing `database-reviewer` and `backend-patterns` to a Backend Sub-Agent). Do not create generic, empty-shell agents.
+  - Development execution: Automatically load `fable-mode` and `fable-discipline`. The macro plan produced in fable-mode's Discovery phase MUST be materialized as the `todo-driven-workflow` checklist — sub-agent handoffs and milestone checks are tracked there, not in prose.
+  - **Pre-Delivery Gate**: Same as Tier 2 — run `verification-loop` (and `security-review` where applicable) before the final handoff.
+
+## 3. Foolproofing & Circuit Breaker Mechanism
+LLMs have a Reasoning Ceiling. To avoid invalid infinite retries, you must strictly obey the following limits:
+- **Rule of 3**: If attempting to fix the same Bug or test failure fails 3 times consecutively, **STOP modifying code immediately**.
+- **Trigger Circuit Breaker**: Forcefully call the `zoom-out` skill — rebuild the full picture, fact-check the assumption behind each failed attempt with read-only tools, and write the reflection report. Most trips should end in **self-recovery on a fresh diagnosis**, not a cry for help.
+- **Seek Human Help — only for genuine decisions**: Escalate when zoom-out concludes the blocker is a human call (requirement conflict, architecture trade-off, destructive action, missing access), or when the breaker hard-locks on a second trip of the same signature. Present verified facts and 2-3 options with a recommendation — never a bare "I'm stuck".
+
+## 4. Evolution Loop
+- When the circuit breaker is triggered and the problem is ultimately solved — whether by post-reflection self-recovery or with human intervention.
+- Or, when you have expended great effort to overcome difficulties and complete a complex task.
+- You **MUST** automatically call the `self-evolve` skill to write "human key insights" or "successfully avoided traps" into system memory, ensuring the same blind spots are bypassed next time.
+
+## 6. Always-On ADHD-Friendly Output Shaping
+This is the same always-on discipline `install-cognitive-os` defines under its own §"Global Output Normalization" — this router doesn't restate it (that duplication was flagged in a skill quality audit §1.1 and has been removed). Since §1 already sends every task through `install-cognitive-os` before any action, its output-shaping rules are already in effect by the time this router does anything — apply them as written there, on every response, regardless of tier.
+
+## 5. Skill Registry (Full Activation Map)
+Every skill in this repository is reachable from this router. If a task matches a trigger below and the skill is not yet loaded, load it.
+
+| Skill | Layer | Activated when |
+| :--- | :--- | :--- |
+| `install-cognitive-os` | Foundation | Always, before any action (§1). |
+| `todo-driven-workflow` | Foundation | Every Tier 2/3 task — the base execution loop (§1). |
+| `environment-detection` | Foundation | Session start / `[Discover]` phase, before running shell commands. |
+| `fable-mode/execution-guardrails` | Always-on discipline | Every tier: flagging problems, batching warnings, find-and-replace edits (§1). |
+| `verify-before-claim` | Always-on discipline | Before asserting external-system behavior or unmeasured numbers (§1). |
+| `git-commit` / `rewrite-commits` | Tier 1 | Commit creation / history rewriting. |
+| `tdd` | Tier 2 | Feature/bugfix development (Red-Green-Refactor). |
+| `using-git-worktrees` | Tier 2 | Isolating feature work on a busy repository. |
+| `grill-me` | Tier 2 | User asks to be grilled on a plan (pure Q&A). |
+| `improve-codebase-architecture` | Tier 2 | Deep architectural analysis / refactor planning. |
+| `eval-harness` | Tier 2 | Scoring, stress testing, benchmark comparison. |
+| `verification-loop` | Tier 2/3 gate | Before declaring done or creating a PR. |
+| `security-review` | Tier 2/3 gate | Changes touching auth, input handling, secrets, network boundaries. |
+| `fable-mode` | Tier 3 | Macro task planning & execution engine. |
+| `fable-discipline` | Tier 3 | Risk control paired with fable-mode. |
+| `fable-mode/fable-haiku` | Tier 3 (opt-in) | User explicitly asks for staged execution run cheaply on Haiku. |
+| `create-agent-launcher` | Tier 3 | Spawning specialized sub-agents. |
+| `build-multi-agent-system` | Tier 3 | Scaffolding a multi-agent workspace. |
+| `repo-docs` | Tier 3 | Creating project-level documentation. |
+| `grill-with-docs` | Tier 3 | Documenting decisions (ADR / CONTEXT) before large designs. |
+| `zoom-out` | Circuit breaker | Rule of 3 trips (§3). |
+| `self-evolve` | Evolution | Post-breaker resolution or major breakthrough (§4). |
+| `skill-style` | Meta | Authoring or modifying any SKILL.md in this repository — the terse Skill Contract format spec. |
+| `skill-creator` | Meta | Creating a new skill from scratch, auditing/refactoring an existing SKILL.md, or `self-evolve`'s dynamic skill generation step (§4) — the fuller authoring, quality-checklist, and testing workflow built on `skill-style`. |
+
+(`eval-framework/` is internal CI for the router itself — run `node eval-framework/runner.js` after modifying `tier-router.js`; it is not a routable skill. Likewise `scripts/self-heal.js` in this skill is infrastructure, invoked during `[Discover]` per §1.)

package/harness-everything/examples/README.md

@@ -0,0 +1,9 @@
+# Harness Examples
+This directory contains concrete examples of how to use Harness tools and workflows.
+
+## tier-router.js Quick Start
+If you are unsure how to use the tier router, you can call it directly:
+`node harness-everything/scripts/tier-router.js "YOUR PROMPT HERE"`
+
+Example:
+`node harness-everything/scripts/tier-router.js "Add a login page"`

package/harness-everything/examples/todo-workflow.md

@@ -0,0 +1,22 @@
+# Todo-Driven Workflow Example
+Here is a concrete example of how to implement the Todo-Driven Workflow using VS Code's `manage_todo_list` tool.
+
+## The Goal: Add a User Authentication Endpoint
+
+1. **Initialize the List**: Before writing code, call `manage_todo_list` with these items:
+   - ID: 1, Title: "Write auth tests", Status: "not-started"
+   - ID: 2, Title: "Implement /login API", Status: "not-started"
+   - ID: 3, Title: "Verify DB connection", Status: "not-started"
+
+2. **Start Task 1**: Call `manage_todo_list` to set ID 1 to "in-progress".
+
+3. **Execute**: Create `tests/auth.test.js` and write the tests.
+
+4. **Verify**: Run the tests using `run_in_terminal` (`npm test`). They should fail (Red).
+
+5. **Complete Task 1**: Call `manage_todo_list` to set ID 1 to "completed".
+
+6. **Start Task 2**: Call `manage_todo_list` to set ID 2 to "in-progress".
+...and so on.
+
+**CRITICAL**: Do NOT just type out a checklist in markdown. You MUST call the `manage_todo_list` tool.

package/harness-everything/scripts/bootstrap.js

@@ -0,0 +1,140 @@
+#!/usr/bin/env node
+const fs = require('fs');
+const path = require('path');
+const {
+  getWorkspaceRoot,
+  getSessionDir,
+  writeCurrentSession,
+  pruneStaleSessions,
+} = require('../../hooks/scripts/lib/harness-state');
+
+console.log("Bootstrapping Harness Skills OS...");
+
+// SessionStart hooks receive a payload with session_id via stdin, same as
+// every other hook. Read it synchronously up front - bootstrap has no
+// tool-call latency to protect, so there's no fast-path tradeoff here - but
+// skip entirely on an interactive TTY (manual run) where reading fd 0 would
+// just hang waiting for input that's never coming.
+let payload = null;
+if (!process.stdin.isTTY) {
+  try {
+    const raw = fs.readFileSync(0, 'utf8');
+    payload = JSON.parse(raw);
+  } catch (err) {
+    // No payload piped in, or invalid JSON - fall back to 'default'.
+  }
+}
+const sessionId = payload && payload.session_id;
+
+const root = getWorkspaceRoot();
+
+// Nothing purges old session directories the way an OS temp dir would -
+// drop ones untouched for a while so .claude/harness-state/sessions/ doesn't
+// grow forever.
+pruneStaleSessions(root);
+
+// The manual escape hatch (reset-circuit-breaker.js) and any CLI tool that
+// can't see a session_id (todo-cli.js) resolve "current session" through
+// this pointer.
+writeCurrentSession(root, sessionId);
+
+const harnessDir = getSessionDir(root, sessionId);
+
+// The Rule of 3 circuit breaker (hooks/scripts/rule-of-3.js) locks all
+// Bash/Edit/Write calls once tripped; the only in-session exits are a valid
+// zoom-out reflection report or a human reset. A new SessionStart means the
+// human has taken over (new session, /clear, /compact) and reviewed the
+// situation, so it's safe to clear here. The stale reflection report goes
+// with it - it belongs to the previous loop, not this session.
+const circuitBreakerFile = path.join(harnessDir, 'rule-of-3-state.json');
+if (fs.existsSync(circuitBreakerFile)) {
+  try {
+    fs.unlinkSync(circuitBreakerFile);
+    console.log("Rule of 3 circuit breaker state cleared for new session.");
+  } catch (err) {
+    // Ignore; worst case the breaker stays tripped until manually reset.
+  }
+}
+const zoomOutReportFile = path.join(harnessDir, 'zoom-out-report.md');
+if (fs.existsSync(zoomOutReportFile)) {
+  try {
+    fs.unlinkSync(zoomOutReportFile);
+  } catch (err) {
+    // Ignore; rule-of-3.js already rejects reports older than the last failure.
+  }
+}
+
+// Same reasoning: a stale subagent-scope baseline from a previous session
+// would make the first Task burst of this session diff against the wrong
+// starting point.
+const subagentScopeFile = path.join(harnessDir, 'subagent-scope-state.json');
+if (fs.existsSync(subagentScopeFile)) {
+  try {
+    fs.unlinkSync(subagentScopeFile);
+  } catch (err) {
+    // Ignore.
+  }
+}
+
+// Self-heal audit: report missing platform integration touchpoints so the
+// model (per harness-everything SKILL.md) repairs them via self-heal.js.
+// Audit-and-report only - bootstrap never writes these files itself, so a
+// user who intentionally removed one isn't fought every session start.
+try {
+  const MARKER = 'Harness OS Guidance (Advisory)';
+  const HOOK_ID = 'harness:pre:bootstrap';
+  const workspaceRoot = getWorkspaceRoot();
+  const contains = (p, needle) => {
+    try { return fs.readFileSync(p, 'utf8').includes(needle); } catch (e) { return false; }
+  };
+  const missing = [
+    ['.claude/settings.json (Claude Code hooks)', contains(path.join(workspaceRoot, '.claude', 'settings.json'), HOOK_ID)],
+    ['.cursorrules (Cursor)', contains(path.join(workspaceRoot, '.cursorrules'), MARKER)],
+    ['.github/copilot-instructions.md (Copilot)', contains(path.join(workspaceRoot, '.github', 'copilot-instructions.md'), MARKER)],
+    ['AGENTS.md (Codex)', contains(path.join(workspaceRoot, 'AGENTS.md'), MARKER)]
+  ].filter(([, ok]) => !ok).map(([label]) => label);
+  if (missing.length > 0 && path.resolve(workspaceRoot) !== path.resolve(__dirname, '..', '..')) {
+    console.log(`\n[Self-Heal] Missing integration touchpoints: ${missing.join(', ')}`);
+    console.log(`[Self-Heal] Repair (idempotent): node "${path.join(__dirname, 'self-heal.js')}"`);
+  }
+} catch (err) {
+  // Audit is best-effort; never block session start.
+}
+
+// Check for handoff/state checkpoint from previous session
+const handoffFile = path.join(harnessDir, 'handoff-state.json');
+if (fs.existsSync(handoffFile)) {
+  try {
+    const handoff = JSON.parse(fs.readFileSync(handoffFile, 'utf8'));
+    if (handoff.status === 'failed') {
+      const exitStr = handoff.exitCode ? ` (exit code ${handoff.exitCode})` : '';
+      const border = "─".repeat(60);
+      console.log(`\n┌${border}┐`);
+      console.log(`│             Harness OS - Handoff Checkpoint              │`);
+      console.log(`├${border}┤`);
+      console.log(`│ - Last active action failed${exitStr.padEnd(30)} │`);
+      console.log(`│ - Action: ${String(handoff.tool || 'unknown').padEnd(46)} │`);
+      console.log(`│ - Last error output snippet:                             │`);
+      
+      const snippet = handoff.errorSummary || 'No snippet available';
+      const lines = snippet.split('\n').map(l => l.trim()).filter(Boolean).slice(-3);
+      if (lines.length > 0) {
+        lines.forEach(line => {
+          const paddedLine = line.slice(0, 54).padEnd(54);
+          console.log(`│     > ${paddedLine} │`);
+        });
+      } else {
+        console.log(`│     > None                                               │`);
+      }
+      console.log(`├${border}┤`);
+      console.log(`│ Hint: Use this context to continue resolving the issue   │`);
+      console.log(`│       efficiently or start on a new path.                │`);
+      console.log(`└${border}┘\n`);
+    }
+  } catch (err) {
+    // Ignore malformed files
+  }
+}
+
+console.log("Harness OS initialized. Ready for user prompt.");
+

package/harness-everything/scripts/self-heal.js

@@ -0,0 +1,189 @@
+#!/usr/bin/env node
+/**
+ * Self-healing installation audit for Harness OS.
+ *
+ * Audits the six platform integration touchpoints in the current workspace
+ * and, when any are missing, re-runs the idempotent installer to repair them.
+ * This makes the harness portable across editors: install once via Claude
+ * Code, then open the same repo in Copilot/Cursor/Codex/Continue/Hermes and
+ * the missing advisory instructions are backfilled automatically the first time
+ * harness-everything (or the environment-detection Discover phase) runs.
+ *
+ * Usage:
+ *   node self-heal.js            Audit and repair anything missing.
+ *   node self-heal.js --check    Audit only; report, never write.
+ *   node self-heal.js --force-self  Allow repairing harness-everything repo
+ *                                   itself (skipped by default to avoid
+ *                                   polluting this repo with generated files).
+ *
+ * Repair strategy: delegate to scripts/installer.js rather than duplicating
+ * its logic - the installer merges hooks by id and appends advisory text only
+ * when its marker is absent, so re-running it is always safe.
+ */
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+
+const MARKER = 'Harness OS Guidance (Advisory)';
+const HOOK_ID = 'harness:pre:bootstrap';
+
+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();
+}
+
+function fileContains(filePath, needle) {
+  try {
+    return fs.readFileSync(filePath, 'utf8').includes(needle);
+  } catch (err) {
+    return false;
+  }
+}
+
+// Presence of the hook id alone is not enough: the skills repo may have been
+// MOVED since install (it already happened once - harness-everything to
+// miya.daniel/skills), leaving settings.json full of absolute paths to dead
+// scripts while still "containing" the id. Verify every harness hook command
+// points at a script that actually exists on disk.
+function auditClaudeHooks(workspaceRoot) {
+  const settingsPath = path.join(workspaceRoot, '.claude', 'settings.json');
+  let settings;
+  try {
+    settings = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
+  } catch (err) {
+    return { ok: false, detail: 'not installed' };
+  }
+  const commands = [];
+  for (const list of Object.values(settings.hooks || {})) {
+    for (const item of list) {
+      if (typeof item.id === 'string' && item.id.startsWith('harness:')) {
+        (item.hooks || []).forEach(h => {
+          if (h.type === 'command' && h.command) commands.push(h.command);
+        });
+      }
+    }
+  }
+  if (commands.length === 0) return { ok: false, detail: 'not installed' };
+  for (const cmd of commands) {
+    // Our hook commands are exactly `node <script>` with no extra args, in
+    // one of three historical quoting styles; stripping the prefix and all
+    // quotes yields the script path in every one of them.
+    const scriptPath = cmd.replace(/^node\s+/, '').replace(/"/g, '').trim();
+    if (!fs.existsSync(scriptPath)) {
+      return { ok: false, detail: `stale script path: ${scriptPath}` };
+    }
+  }
+  return { ok: true };
+}
+
+function auditWorkspace(workspaceRoot) {
+  const isClaudeCode = process.env.CLAUDE_CODE === 'true' || process.env.SHELL?.includes('claude-code') || false;
+  const isVSCodeCopilot = process.env.VSCODE_PID !== undefined || process.env.TERM_PROGRAM === 'vscode' || process.env.GITHUB_COPILOT_CHAT === 'true' || true; // Fallback default
+
+  const checks = [];
+
+  // 根據當前執行環境動態決定審查項目
+  if (isClaudeCode) {
+    const claudeHooks = auditClaudeHooks(workspaceRoot);
+    checks.push({
+      label: 'Claude Code hooks (.claude/settings.json)' + (claudeHooks.detail ? ` - ${claudeHooks.detail}` : ''),
+      ok: claudeHooks.ok,
+      platform: 'claude'
+    });
+  } else {
+    // 處於 VS Code / Copilot 或其他編輯器
+    checks.push({
+      label: 'Cursor rules (.cursorrules)',
+      ok: fileContains(path.join(workspaceRoot, '.cursorrules'), MARKER),
+      platform: 'cursor'
+    });
+    checks.push({
+      label: 'Copilot instructions (.github/copilot-instructions.md)',
+      ok: fileContains(path.join(workspaceRoot, '.github', 'copilot-instructions.md'), MARKER),
+      platform: 'copilot'
+    });
+    checks.push({
+      label: 'Codex instructions (AGENTS.md)',
+      ok: fileContains(path.join(workspaceRoot, 'AGENTS.md'), MARKER),
+      platform: 'codex'
+    });
+    checks.push({
+      label: 'Continue.dev rules (.continue/rules/harness.md)',
+      ok: fileContains(path.join(workspaceRoot, '.continue', 'rules', 'harness.md'), MARKER),
+      platform: 'continue'
+    });
+    checks.push({
+      label: 'Hermes Agent instructions (.hermes.md)',
+      ok: fileContains(path.join(workspaceRoot, '.hermes.md'), MARKER),
+      platform: 'hermes'
+    });
+  }
+
+  return checks;
+}
+
+function printAudit(checks) {
+  console.log('[Harness Self-Heal Audit]');
+  checks.forEach(c => {
+    console.log(`  ${c.ok ? 'OK     ' : 'MISSING'}  ${c.label}`);
+  });
+}
+
+function main() {
+  const checkOnly = process.argv.includes('--check');
+  const forceSelf = process.argv.includes('--force-self');
+
+  const workspaceRoot = getWorkspaceRoot();
+  const harnessSourceDir = path.resolve(__dirname, '..', '..');
+  const installerPath = path.join(harnessSourceDir, 'scripts', 'installer.js');
+
+  console.log(`Workspace: ${workspaceRoot}`);
+  const checks = auditWorkspace(workspaceRoot);
+  printAudit(checks);
+
+  const missing = checks.filter(c => !c.ok);
+  if (missing.length === 0) {
+    console.log('\nAll active integration touchpoints present. Nothing to repair.');
+    return;
+  }
+
+  if (checkOnly) {
+    console.log(`\n${missing.length} active touchpoint(s) missing. Run without --check to repair:`);
+    console.log(`  node "${path.join(__dirname, 'self-heal.js')}"`);
+    return;
+  }
+
+  const isSelf = path.resolve(workspaceRoot) === path.resolve(harnessSourceDir);
+  if (isSelf && !forceSelf) {
+    console.log('\nWorkspace IS the harness-everything repo itself - skipping repair to avoid');
+    console.log('polluting it with generated config files. Pass --force-self to override.');
+    return;
+  }
+
+  if (!fs.existsSync(installerPath)) {
+    console.error(`\nCannot repair: installer not found at ${installerPath}`);
+    process.exit(1);
+  }
+
+  console.log(`\nRepairing ${missing.length} missing active touchpoint(s) via installer...\n`);
+  
+  // 構造參數只針對當前環境缺少的平台調用安裝器
+  const activeFlags = missing.map(c => `--${c.platform}`).join(' ');
+  execSync(`node "${installerPath}" ${activeFlags} --yes`, { cwd: workspaceRoot, stdio: 'inherit' });
+
+  const after = auditWorkspace(workspaceRoot);
+  console.log('');
+  printAudit(after);
+  const stillMissing = after.filter(c => !c.ok);
+  if (stillMissing.length > 0) {
+    console.error(`\nSelf-heal incomplete: ${stillMissing.length} touchpoint(s) still missing.`);
+    process.exit(1);
+  }
+  console.log('\nSelf-heal complete. Active platforms are now covered.');
+}
+
+main();