harness-everything 0.2.2 → 0.4.0

package/harness-everything/SKILL.md

@@ -1,141 +1,43 @@
 ---
 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
+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.4.0
 ---
 
-# Harness Everything (System Main Entry & Dynamic Router)
+# Harness Everything
 
-## 📋 Skill Contract
+Public/manual Harness kernel entry. Hook-capable hosts should run the kernel before peer/domain skill selection.
 
-| 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`. |
+## USE FOR:
+- Software triage/re-routing, including work that already names or strongly matches another skill.
+- Inspecting Tier, invariants, or suggestions.
 
-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.
+## DO NOT USE FOR:
+- General Q&A or non-software writing.
 
-## 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.
+## Invariants
 
-**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.
+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.
 
-**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).
+These rails are mandatory; Tier guidance is not a fixed pipeline.
 
-**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.
+## Workflow
 
-## 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.
+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.
 
-### 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)
-  - ...
-```
+## Tier Guidance
 
-### 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:** 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 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.
+**Rule:** do not enforce workflow order; let the agent orchestrate itself inside the invariants.
 
-### 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.)
+Deep dive: <this-skill-dir>/references/triage-and-tiers.md

package/harness-everything/examples/README.md

@@ -1,9 +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"`
+# 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

@@ -1,22 +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.
+# 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/references/router-workflow-plan.md

@@ -0,0 +1,128 @@
+# Router Workflow Plan Contract
+
+Issue #85 separates three decisions that were previously conflated:
+
+```text
+Tier / risk classification
+        + execution topology
+        + optional capabilities
+```
+
+The router is a planner. It emits a versioned, deterministic plan but does not execute tools, spawn agents, create workspaces, write memory, enforce approvals, or retry failed execution.
+
+## Phase 2 flow
+
+```mermaid
+flowchart TD
+    U[User prompt + host/task context] --> C[Tier / risk classification]
+    C --> S[Task-shape normalization]
+    S --> X{Explicit user strategy?}
+    X -- yes --> O[Honor choice unless contradictory prohibition]
+    X -- no --> H{Routing healthy?}
+    H -- no --> D[deferred strategy + degraded fallback]
+    H -- yes --> W{Durable reusable specialists?}
+    W -- yes --> MW[fable-multi-agent-workspace]
+    W -- no --> P{Independent + read-only/disjoint?}
+    P -- yes --> FP[fable-parallel]
+    P -- no --> T{Tier}
+    T -- Tier 1 --> DS[direct-single]
+    T -- Tier 2 --> IS[iterative-single]
+    T -- Tier 3 --> FS[fable-staged]
+    T -- unclassified --> DU[deferred strategy]
+    O --> F[Capability/budget fallback pass]
+    MW --> F
+    FP --> F
+    DS --> F
+    IS --> F
+    FS --> F
+    DU --> F
+    D --> F
+    F --> G[Orthogonal actionGate / memory / verification modifiers]
+    G --> K[kernel-router consumes structured plan]
+```
+
+`unclassified` is not a synonym for Tier 1 or `direct-single`. Missing classification evidence leaves strategy selection deferred, while independent risk signals such as `actionGate` are still evaluated.
+
+## Structured transport
+
+`tier-router.js` keeps human-readable output for compatibility and writes the machine-readable contract to a per-invocation side-channel path supplied by `kernel-router.js`. The kernel validates and consumes that contract; it does not scrape tier or strategy from text.
+
+If the structured contract is missing or invalid, the kernel emits a degraded/unclassified contract rather than silently choosing Tier 1/direct execution.
+
+## Deterministic strategy vocabulary
+
+| Strategy | Selection rule | Key invariants |
+|---|---|---|
+| `direct-single` | Tier 1 bounded/trivial task | scope lock, verify before claim |
+| `iterative-single` | Tier 2 ordinary diagnosis/TDD/tool loop | objective verification, explicit iteration budget |
+| `fable-staged` | Tier 3 dependent work or parallel independence not proven | stage contracts, cold verifier |
+| `fable-parallel` | Tier 3 with explicit independent workstreams and read-only/disjoint write scope | stage contracts, parallel scope contract, synthesis barrier |
+| `fable-multi-agent-workspace` | durable multi-session task needing reusable specialists | workspace state, handoffs, stage contracts, cold verifier |
+
+Tier 3 alone never implies a persistent workspace. Likewise, an `independent` label alone is insufficient for `fable-parallel`: the write set must also be `read-only` or `disjoint`.
+
+The Phase 2 `iterative-single` loop budget is **8 iterations**. This is a policy bound chosen for control, not a measured optimum. It is separate from the rule-of-3 repeated-failure breaker.
+
+## Explicit user choice and prohibitions
+
+The task-shape contract records:
+
+- an explicit requested strategy, when named;
+- an explicit Fable model request, still delegated to `fable-mode/scripts/model-selector.js`;
+- prohibitions such as no Fable, no subagents, no parallel execution, or no workspace.
+
+Explicit choices override derived topology. Contradictory choice + prohibition is visible as a blocked fallback rather than silently guessing which instruction to ignore.
+
+## Host capability and budget fallbacks
+
+Host capabilities can be supplied in hook context (`hostCapabilities`) or deterministic environment inputs. Unknown capability remains `unknown`; only known unavailability causes fallback.
+
+Examples:
+
+- missing parallel calls or `concurrency: 1` serializes `fable-parallel` to `fable-staged` with a `reduced/serialized` fallback;
+- unavailable subagents may reduce staged execution to visible inline execution;
+- missing durable state for a required multi-agent workspace is `blocked`, not silently downgraded;
+- a requested Fable model with known unavailable model capability is `blocked`; the router never substitutes another branded model;
+- a required `actionGate` with known unavailable hook capability is `blocked`.
+
+Fallbacks carry deterministic reason codes.
+
+## `actionGate` is orthogonal to strategy
+
+Irreversible or external side-effect intent (for example destructive database changes, force push, production deploy, publish, payment, or external send) adds:
+
+```json
+{
+  "actionGate": {
+    "required": true,
+    "reasonCodes": ["irreversible-action"],
+    "approver": "rule-or-human",
+    "disposition": "pending-approval"
+  }
+}
+```
+
+This does not choose a topology and does not itself enforce the gate. Phase 5 owns PreToolUse enforcement. The router only declares the invariant so any eventual executor must preserve it.
+
+## Invariants vs advisory skills
+
+`requiredInvariants` and `suggestedSkills` are separate plan fields. The kernel prints both separately and consumes them from the structured plan instead of reconstructing suggestions from tier.
+
+Examples:
+
+- `objective-verification` and `loop-budget` are mandatory for `iterative-single`;
+- `tdd` and `verification-loop` remain advisory skill suggestions;
+- `stage-contracts` and `cold-verification` are mandatory for Fable topologies;
+- `multi-agent-workspace` is suggested only when the selected topology actually requires durable workspace behavior.
+
+There is no universal `TODO → TDD → verification` pipeline.
+
+## Guide deduplication
+
+Knowledge-guide recommendations are deduplicated by the referenced guide path, not by full line text. If two routing groups describe `security-review/SKILL.md` differently, the path is still emitted once.
+
+## Determinism rule
+
+The structured contract contains no timestamp, random plan identifier, temporary path, or runtime-only noise. The same normalized task inputs plus the same host capability/config state serialize to byte-equivalent JSON.
+
+Derived estimates remain visibly derived fields. Unknown host/task facts remain `unknown`; the router must not invent capability or state evidence.

package/harness-everything/references/skill-registry.md

@@ -0,0 +1,39 @@
+# Skill Registry (Full Activation Map)
+
+## 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 |
+| :--- | :--- | :--- |
+| `harness-everything` | Entry point | New software request with no skill indicated; emits the tier checkpoint. |
+| `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` | Tier 1 | Commit creation and conventional commit verification. |
+| `rewrite-commits` | Tier 1 | History rewriting and commit cleanup. |
+| `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 | v3 staged planning, named-agent delegation, model selection, failable gates, and cold review. |
+| `fable-discipline` | Tier 3 | Risk control paired with fable-mode. |
+| `fable-mode/fable-haiku` | Tier 3 (opt-in) | User explicitly asks for staged execution on Haiku for bulk mechanical work. |
+| `fable-mode/fable-sonnet` | Tier 3 (opt-in) | User explicitly asks for staged execution on Sonnet for bounded reasoning or synthesis. |
+| `fable-mode/fable-opus` | Tier 3 (opt-in) | User explicitly asks for staged execution on Opus for orchestration or high-stakes architecture. |
+| `multi-agent-workspace` | Tier 3 | Scaffolding a multi-agent workspace and selecting bounded specialists. |
+| `repo-docs` | Tier 3 | Creating project-level documentation. |
+| `grill-with-docs` | Tier 3 | Documenting decisions (ADR / CONTEXT) before large designs. |
+| `to-spec` | Tier 2/3 (advisory, never a gate) | Synthesizing the (already-settled) conversation into whichever doc shape fits — feature spec, CLI/API reference, schema doc, or dev doc — published to this repo's issue tracker. Explicit-invoke only — never auto-executed. |
+| `to-tickets` | Tier 2/3 (advisory, never a gate) | Breaking a `to-spec` feature spec (or an already-settled plan/conversation) into tracer-bullet tickets with declared blocking edges. Reuses `to-spec`'s own `check-project-docs.js` gate — never a second setup interview. Explicit-invoke only — never auto-executed. |
+| `zoom-out` | Circuit breaker | Rule of 3 trips (§3). |
+| `self-evolve` | Evolution | Post-breaker resolution or major breakthrough (§4). |
+| `find-skills` | Meta | No static/generated/already-installed skill covers the user's need (checked live via `npx skills list`, not manifest-cached) — searches skills.sh/`npx skills` and, only with explicit approval, applies it ephemerally via a self-expiring OS-temp cache (`scripts/use-skill.js`, the default — zero persistent footprint) or, only if the user wants to keep it, installs via `npx skills add` (the rare exception). Deliberately not manifest-tracked or router-auto-surfaced like `self-evolve`'s `generated[]` — third-party content isn't lifecycle-owned by Harness the way self-authored skills are. |
+| `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`. |
+
+(`ci/` is internal CI for the router itself — run `node ci/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/references/triage-and-tiers.md

@@ -0,0 +1,193 @@
+# Task Triage & Tier Details
+
+Harness uses tiers to estimate scope and surface useful capabilities. A tier is **not** a fixed pipeline. The runtime enforces a very small set of cross-cutting invariants and leaves tactics, skill choice, ordering, and delegation to the agent.
+
+> Architecture rule: **Do not enforce workflow order. Enforce workflow invariants.**
+
+## 0. When Harness Routing Applies
+
+```mermaid
+flowchart TD
+    U([User Prompt]) --> S{Software / project work?}
+    S -- No --> B[Bypass Harness<br/>Answer naturally]
+    S -- Yes --> K[Harness Kernel<br/>classify scope + inject invariants]
+    K --> T{Tier recommendation}
+    T -- Tier 1 --> A1[Prefer direct execution]
+    T -- Tier 2 --> A2[Agent chooses useful domain skills]
+    T -- Tier 3 --> A3[Agent chooses planning / delegation if useful]
+    A1 --> E[Execute with agent-selected tactics]
+    A2 --> E
+    A3 --> E
+    E --> V{Objective evidence supports completion?}
+    V -- No --> R[Diagnose / iterate]
+    R --> F{Same-signature failure x3?}
+    F -- No --> E
+    F -- Yes --> Z[Zoom out / re-plan]
+    Z --> E
+    V -- Yes --> D([Claim completion])
+```
+
+### Bypass Rules
+
+- **Pure chat, translation, general web search, non-software writing:** bypass Harness routing.
+- **Software engineering / codebase / project work:** establish the Harness Kernel contract before mutating work, even when the prompt already names a domain skill such as `tdd`, `security-review`, or `repo-docs`.
+
+A host may auto-select a peer/domain skill. That selection must not be treated as proof that Harness routing already happened.
+
+## 1. The Minimal Harness Kernel
+
+The kernel exists to keep strong models free while protecting the few behaviors that should not disappear under autonomous skill selection.
+
+### Mandatory invariants
+
+1. **Route before execution** — establish task scope/tier before mutating software work.
+2. **Verify before claim** — completion claims require objective evidence appropriate to the change.
+3. **Re-plan on repetition** — after three same-signature failures, stop micro-retrying and use a fresh diagnosis / `zoom-out`.
+
+These are the rails. Everything else is agent judgment unless the user or an authoritative project document explicitly requires it.
+
+### What is intentionally *not* mandatory
+
+- Loading `todo-driven-workflow` for every Tier 2/3 task.
+- Running TDD for changes where executable behavioral tests do not add value.
+- Entering Fable/multi-agent mode merely because the task is Tier 3.
+- Following a universal `TODO → TDD → verification-loop` or `Fable → subagent → verification-loop` sequence.
+- Loading `install-cognitive-os` as a peer skill before every other skill.
+
+`install-cognitive-os` remains the human-readable/manual entry point for the cognitive policy. Supported runtime integrations should establish the kernel invariants without depending on that skill being selected first.
+
+## 2. Routing Mechanism
+
+Use the public kernel entry point:
+
+```bash
+node "<this-skill-dir>/scripts/kernel-router.js" "<brief prompt summary>"
+```
+
+or:
+
+```bash
+npx github:dyphn1/Harness-everything next "<brief prompt summary>"
+```
+
+`kernel-router.js` delegates classification and guide discovery to `tier-router.js`, removes legacy fixed-pipeline instructions, and emits:
+
+- the recommended tier and rationale,
+- the **required Harness invariants**,
+- **suggested skills** marked advisory,
+- the policy that the agent may choose the smallest useful skill/tool set.
+
+If a host's `UserPromptSubmit` integration already ran the kernel this turn, reuse that output rather than running it twice.
+
+The tier classifier is heuristic. Treat its result as the default route, not an oracle. A clear task reading or explicit user instruction may override it; record the reason when doing so.
+
+## 3. Tier Guidance
+
+### Tier 1 — Trivial
+
+Typical shape:
+- typo/small documentation correction,
+- simple local code edit,
+- narrow explanation,
+- straightforward Git operation.
+
+Default behavior:
+- prefer direct execution,
+- avoid large plans and unnecessary delegation,
+- load a focused skill only when it materially improves the result,
+- still verify any completion claim with evidence appropriate to the change.
+
+### Tier 2 — Standard
+
+Typical shape:
+- a specific feature or bug fix,
+- multi-file coordination,
+- behavioral changes needing tests,
+- focused benchmark/review work.
+
+Common **suggestions**, not a pipeline:
+
+| Need observed in the task | Useful skill |
+|---|---|
+| Several verifiable steps need explicit tracking | `todo-driven-workflow` |
+| Behavior can be specified by executable tests | `tdd` |
+| Delivery needs systematic build/lint/test/diff evidence | `verification-loop` |
+| Auth/input/secrets/network boundaries are touched | `security-review` |
+| Isolated workspace would reduce risk | `using-git-worktrees` |
+| Quantitative scoring/benchmarking is requested | `eval-harness` |
+
+The model decides which of these are useful and in what order. It may use none, one, or several while preserving the kernel invariants.
+
+### Tier 3 — Macro
+
+Typical shape:
+- repository-wide or architectural changes,
+- large ambiguous requirements,
+- broad documentation/system design,
+- work where deliberate delegation may reduce risk or improve coverage.
+
+Common **suggestions**, not a pipeline:
+
+| Need observed in the task | Useful skill |
+|---|---|
+| Deliberate macro planning / model-mode selection | `fable-mode`, `fable-discipline` |
+| Bounded parallel delegation genuinely helps | `multi-agent-workspace` |
+| Project-level docs need creation/update | `repo-docs` |
+| Important decisions need challenge before implementation | `grill-with-docs` |
+| Settled intent needs a spec | `to-spec` |
+| Settled work needs tracer-bullet issues | `to-tickets` |
+
+Tier 3 does **not** automatically require multi-agent execution. A strong model may complete macro work directly when that is the safer/smaller choice.
+
+## 4. Cognitive OS Relationship
+
+The cognitive loop remains useful:
+
+```mermaid
+flowchart LR
+    D[Discover] --> T[Think]
+    T --> Y[Try]
+    Y --> S[Summarize]
+    S --> R[Record]
+    S -- evidence insufficient --> T
+    Y -- same failure x3 --> Z[Zoom Out]
+    Z --> T
+```
+
+But this diagram describes a reasoning policy, not a peer-skill dependency graph. Domain skills may implement their own local phases and gates. They do not need to invoke `install-cognitive-os` first as long as the Harness invariants remain satisfied.
+
+## 5. Host Integration and Enforcement Strength
+
+| Host mode | Expected behavior |
+|---|---|
+| Lifecycle hook available | Run the Harness Kernel on prompt submission so routing context exists before domain-skill execution. Hard gates may enforce supported invariants at tool/stop boundaries. |
+| Advisory instructions only | Tell the agent to run/reuse `harness next` before software mutation and `harness verify` before completion. The behavior is advisory, not a hard gate. |
+| Manual use | Invoke `harness-everything` or `install-cognitive-os` explicitly to inspect/re-establish the contract. |
+
+Never describe an advisory integration as hard enforcement. Platform-specific adapters may differ while preserving functional intent.
+
+## 6. Routing Checkpoint
+
+When a visible checkpoint is useful, keep it small:
+
+```markdown
+## 🚦 Harness Routing Checkpoint
+- Tier: Tier X — <reason>
+- Required invariants: route-before-execution; verify-before-claim; re-plan-after-3-same-failures
+- Suggested skills: <only the skills that appear useful>
+```
+
+The checkpoint reports state; it does not prescribe a universal workflow.
+
+## 7. Self-Healing and Dynamic Skills
+
+Existing self-heal, generated-skill discovery, knowledge-guide matching, and fact-audit behavior remain part of the classifier/runtime. They may recommend resources but should not silently convert recommendations into mandatory pipeline stages.
+
+If bootstrap reports missing integration touchpoints, use the existing self-heal command:
+
+```bash
+node "<this-skill-dir>/scripts/self-heal.js"
+node "<this-skill-dir>/scripts/self-heal.js" --check
+```
+
+Respect an explicit user choice to remove/disable an integration.