harness-everything 0.2.2 → 0.4.0

package/docs/platform-compatibility.json

@@ -0,0 +1,270 @@
+{
+  "format": "harness-platform-compatibility-v1",
+  "last_reviewed": "2026-09-14",
+  "status_vocabulary": {
+    "Supported": "An official or native mechanism exists and the Harness behavior is verified.",
+    "Mechanism verified": "Harness package, adapter, or installer checks pass, but a real host run is not confirmed.",
+    "Live verified": "A real host session or portal operation produced preserved evidence.",
+    "Partial": "Only part of the capability is available or verified.",
+    "Unsupported": "The host explicitly does not provide the required mechanism.",
+    "Unknown": "The capability was not verified or the official documentation does not establish it."
+  },
+  "dimensions": [
+    "standaloneSkills",
+    "pluginSupport",
+    "bundledSkills",
+    "hooksLifecycle",
+    "projectScope",
+    "globalScope",
+    "installUninstallSymmetry",
+    "assetsReferences",
+    "updateSync",
+    "liveHostVerification"
+  ],
+  "installer_targets": {
+    "codex": {
+      "project": ".agents/skills",
+      "global": "~/.agents/skills",
+      "host_discovery_status": "Supported"
+    },
+    "chatgpt-openai-plugin": {
+      "project": "managed workspace marketplace",
+      "global": "not established",
+      "host_discovery_status": "Unknown"
+    },
+    "claude-code": {
+      "project": ".claude/skills",
+      "global": "~/.claude/skills",
+      "host_discovery_status": "Supported"
+    },
+    "opencode": {
+      "project": ".opencode/skills or .agents/skills",
+      "global": "~/.config/opencode/skills or ~/.agents/skills",
+      "host_discovery_status": "Supported"
+    },
+    "github-copilot": {
+      "project": ".github/skills",
+      "global": "~/.agents/skills",
+      "host_discovery_status": "Supported"
+    },
+    "cursor": {
+      "project": ".cursor/skills",
+      "global": "~/.agents/skills",
+      "host_discovery_status": "Supported"
+    },
+    "continue": {
+      "project": ".continue/skills",
+      "global": "~/.continue/skills",
+      "host_discovery_status": "Unknown"
+    },
+    "hermes": {
+      "project": ".agents/skills",
+      "global": "~/.hermes/skills",
+      "host_discovery_status": "Supported"
+    }
+  },
+  "action_gate": {
+    "policy_version": 1,
+    "mechanism_status": "Mechanism verified",
+    "rule_table": "hooks/scripts/action-gate-rules.json",
+    "audit_scope": "workspace-keyed global state / per-session action-gate records",
+    "hosts": {
+      "claude-code": {
+        "ask_decision": "Mechanism verified",
+        "permission_mode_matrix": "Mechanism verified",
+        "fallback": "defer-to-host",
+        "notes": "By default a matched command returns no permission decision, so the session's permission mode, rules and auto-mode classifier decide. The hooks reference documents that a hook ask forces a prompt even in auto mode (#107). Deterministic tests verify the deferred result for every permission_mode value and the ask JSON of the opt-in HARNESS_ACTION_GATE_POLICY=always-ask. Live evidence (2026-09-15, plugin 0.3.8-beta, auto mode) showed the earlier forced ask prompting the user; the deferred behavior has no preserved live evidence yet."
+      },
+      "codex": {
+        "ask_decision": "Unsupported",
+        "permission_mode_matrix": "Unknown",
+        "fallback": "exit-2-block",
+        "notes": "Current Codex PreToolUse parses permissionDecision=ask but does not support it; Codex reports the hook failure and continues the tool call. Harness therefore uses exit 2 for matched destructive actions rather than relying on ask semantics."
+      },
+      "chatgpt-openai-plugin": {
+        "ask_decision": "Unknown",
+        "permission_mode_matrix": "Unknown",
+        "fallback": "exit-2-block",
+        "notes": "Public skills-only distribution does not include local lifecycle hooks; local plugin hook semantics remain a separate host capability."
+      },
+      "other": {
+        "ask_decision": "Unknown",
+        "permission_mode_matrix": "Unknown",
+        "fallback": "exit-2-block",
+        "notes": "A matched action fails closed until that host has a Harness-verified ask-style decision contract."
+      }
+    }
+  },
+  "platforms": [
+    {
+      "id": "codex",
+      "name": "Codex",
+      "official_sources": [
+        "https://learn.chatgpt.com/docs/build-skills",
+        "https://learn.chatgpt.com/docs/build-plugins",
+        "https://learn.chatgpt.com/docs/hooks",
+        "https://learn.chatgpt.com/docs/agent-configuration/agents-md"
+      ],
+      "capabilities": {
+        "standaloneSkills": {"status": "Supported", "paths": {"project": [".agents/skills"], "global": ["~/.agents/skills"]}},
+        "pluginSupport": {"status": "Mechanism verified", "paths": {"manifest": ["plugin.json", ".codex-plugin/plugin.json"]}},
+        "bundledSkills": {"status": "Mechanism verified", "notes": "The local package contains a root skills/ tree."},
+        "hooksLifecycle": {"status": "Mechanism verified", "notes": "Codex-supported SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, SubagentStart, SubagentStop, and Stop are covered by package checks; the plugin intentionally does not declare unsupported PostToolUseFailure. Non-managed hooks still require trust."},
+        "projectScope": {"status": "Mechanism verified", "paths": {"skills": [".agents/skills"], "instructions": ["AGENTS.md"]}},
+        "globalScope": {"status": "Mechanism verified", "paths": {"skills": ["~/.agents/skills"]}},
+        "installUninstallSymmetry": {"status": "Mechanism verified", "notes": "Harness installer round-trip checks cover owned files and user-owned collisions."},
+        "assetsReferences": {"status": "Mechanism verified", "notes": "Packaged skill references are checked and remain inside the package."},
+        "updateSync": {"status": "Unknown", "notes": "A real marketplace refresh has not been run in a Codex host."},
+        "liveHostVerification": {"status": "Unknown", "notes": "No preserved Codex plugin/session artifact is committed."}
+      }
+    },
+    {
+      "id": "chatgpt-openai-plugin",
+      "name": "ChatGPT / OpenAI Plugin",
+      "official_sources": [
+        "https://help.openai.com/en/articles/20001256-plugins-in-codex",
+        "https://help.openai.com/en/articles/20001504-importing-and-syncing-plugin-marketplaces-from-github",
+        "https://developers.openai.com/plugins/build/plugins",
+        "https://developers.openai.com/plugins/deploy/submission"
+      ],
+      "capabilities": {
+        "standaloneSkills": {"status": "Unknown", "notes": "The reviewed OpenAI docs establish plugin skills and personal skills, not a repository-local standalone path for ChatGPT."},
+        "pluginSupport": {"status": "Mechanism verified", "paths": {"marketplace": [".agents/plugins/marketplace.json", ".claude-plugin/marketplace.json"], "manifest": ["plugin.json", ".codex-plugin/plugin.json"]}},
+        "bundledSkills": {"status": "Mechanism verified", "notes": "The public submission builder produces a skills-only ZIP."},
+        "hooksLifecycle": {"status": "Partial", "notes": "Local Codex/ChatGPT Work hooks are separate from ordinary Chat, and the public skills-only bundle excludes local hooks."},
+        "projectScope": {"status": "Partial", "notes": "GitHub marketplace import is a managed-workspace flow; local project installation is not live verified."},
+        "globalScope": {"status": "Unknown", "notes": "No public evidence establishes a user-global scope for this package."},
+        "installUninstallSymmetry": {"status": "Unknown", "notes": "No live install/uninstall report has been preserved."},
+        "assetsReferences": {"status": "Mechanism verified", "notes": "The skills-only builder includes referenced skill files and excludes host hooks."},
+        "updateSync": {"status": "Mechanism verified", "notes": "The repository has supported marketplace manifests; GitHub Sync now remains a manual live check."},
+        "liveHostVerification": {"status": "Unknown", "notes": "No import report, fresh-workspace smoke log, or public approval artifact is committed."}
+      }
+    },
+    {
+      "id": "claude-code",
+      "name": "Claude Code",
+      "official_sources": [
+        "https://code.claude.com/docs/en/skills",
+        "https://code.claude.com/docs/en/plugins",
+        "https://code.claude.com/docs/en/plugin-evals",
+        "https://code.claude.com/docs/en/hooks",
+        "https://code.claude.com/docs/en/permissions"
+      ],
+      "capabilities": {
+        "standaloneSkills": {"status": "Supported", "paths": {"project": [".claude/skills"], "global": ["~/.claude/skills"]}},
+        "pluginSupport": {"status": "Supported", "paths": {"manifest": [".claude-plugin/plugin.json"], "skills": ["skills/"]}},
+        "bundledSkills": {"status": "Mechanism verified", "notes": "The local Claude package layout and canonical skill copies are validated."},
+        "hooksLifecycle": {"status": "Mechanism verified", "notes": "Claude hook configuration and command contracts are covered by deterministic tests."},
+        "projectScope": {"status": "Mechanism verified", "paths": {"skills": [".claude/skills"], "hooks": [".claude/settings.json"]}},
+        "globalScope": {"status": "Mechanism verified", "paths": {"skills": ["~/.claude/skills"], "hooks": ["~/.claude/settings.json"]}},
+        "installUninstallSymmetry": {"status": "Mechanism verified", "notes": "Owned settings, skills, agents, and user files are covered by round-trip tests."},
+        "assetsReferences": {"status": "Mechanism verified", "notes": "Skill-local references, scripts, and templates are checked."},
+        "updateSync": {"status": "Unknown", "notes": "A live marketplace update has not been run in Claude Code."},
+        "liveHostVerification": {"status": "Unknown", "notes": "No fresh Claude Code plugin session artifact is committed for this revision."}
+      }
+    },
+    {
+      "id": "opencode",
+      "name": "OpenCode",
+      "official_sources": [
+        "https://opencode.ai/docs/skills",
+        "https://opencode.ai/docs/plugins/"
+      ],
+      "capabilities": {
+        "standaloneSkills": {"status": "Supported", "paths": {"project": [".opencode/skills", ".agents/skills", ".claude/skills"], "global": ["~/.config/opencode/skills", "~/.agents/skills", "~/.claude/skills"]}},
+        "pluginSupport": {"status": "Mechanism verified", "paths": {"project": [".opencode/plugins"], "global": ["~/.config/opencode/plugins"]}},
+        "bundledSkills": {"status": "Partial", "notes": "Harness provides a standalone enforcement module; it is not an OpenCode bundled-skill package."},
+        "hooksLifecycle": {"status": "Mechanism verified", "notes": "tool.execute.before, tool.execute.after, and session.idle are covered against the documented plugin API."},
+        "projectScope": {"status": "Mechanism verified", "paths": {"skills": [".opencode/skills", ".agents/skills"], "plugins": [".opencode/plugins"]}},
+        "globalScope": {"status": "Mechanism verified", "paths": {"skills": ["~/.config/opencode/skills", "~/.agents/skills"], "plugins": ["~/.config/opencode/plugins"]}},
+        "installUninstallSymmetry": {"status": "Unknown", "notes": "The adapter is manually copied; Harness does not own an OpenCode install/uninstall flow."},
+        "assetsReferences": {"status": "Mechanism verified", "notes": "The adapter is self-contained and skill references are separately checked."},
+        "updateSync": {"status": "Unknown", "notes": "No live OpenCode refresh or npm plugin update is preserved."},
+        "liveHostVerification": {"status": "Unknown", "notes": "The real OpenCode host has not loaded the module in a preserved session artifact."}
+      }
+    },
+    {
+      "id": "github-copilot",
+      "name": "GitHub Copilot agent surfaces",
+      "official_sources": [
+        "https://docs.github.com/en/copilot/how-tos/copilot-on-github/customize-copilot/customize-cloud-agent/add-skills",
+        "https://docs.github.com/en/copilot/concepts/agents/about-agent-skills",
+        "https://docs.github.com/en/copilot/concepts/agents"
+      ],
+      "capabilities": {
+        "standaloneSkills": {"status": "Supported", "paths": {"project": [".github/skills", ".agents/skills"], "global": ["~/.copilot/skills", "~/.agents/skills"]}},
+        "pluginSupport": {"status": "Unknown", "notes": "Copilot documents installable plugins, but this repository has no Copilot-specific plugin manifest or live install evidence."},
+        "bundledSkills": {"status": "Unknown", "notes": "The portable package is not verified in a Copilot plugin host."},
+        "hooksLifecycle": {"status": "Unknown", "notes": "Copilot plugin hooks are not part of the Harness package tested here."},
+        "projectScope": {"status": "Mechanism verified", "paths": {"skills": [".github/skills", ".agents/skills"], "instructions": [".github/copilot-instructions.md"]}},
+        "globalScope": {"status": "Mechanism verified", "paths": {"skills": ["~/.copilot/skills", "~/.agents/skills"]}},
+        "installUninstallSymmetry": {"status": "Mechanism verified", "notes": "Harness-owned project/global skill and instruction files have round-trip coverage."},
+        "assetsReferences": {"status": "Mechanism verified", "notes": "The Agent Skills layout permits referenced scripts/resources; repository references are checked."},
+        "updateSync": {"status": "Unknown", "notes": "No Copilot skill reload or plugin marketplace refresh has been run here."},
+        "liveHostVerification": {"status": "Unknown", "notes": "No Copilot agent session artifact is committed."}
+      }
+    },
+    {
+      "id": "cursor",
+      "name": "Cursor",
+      "official_sources": [
+        "https://cursor.com/docs/skills",
+        "https://cursor.com/docs/plugins",
+        "https://prod.cursor.com/help/customization/rules"
+      ],
+      "capabilities": {
+        "standaloneSkills": {"status": "Supported", "paths": {"project": [".agents/skills", ".cursor/skills"], "global": ["~/.agents/skills", "~/.cursor/skills"]}},
+        "pluginSupport": {"status": "Mechanism verified", "notes": "The package now includes a portable root plugin.json; Cursor-specific loading is not live verified."},
+        "bundledSkills": {"status": "Mechanism verified", "paths": {"skills": ["skills/<name>/SKILL.md"]}},
+        "hooksLifecycle": {"status": "Unknown", "notes": "Cursor plugin hooks use Cursor-specific components; Harness does not claim their execution."},
+        "projectScope": {"status": "Mechanism verified", "paths": {"skills": [".agents/skills", ".cursor/skills"], "rules": [".cursor/rules"]}},
+        "globalScope": {"status": "Mechanism verified", "paths": {"skills": ["~/.agents/skills", "~/.cursor/skills"]}},
+        "installUninstallSymmetry": {"status": "Unknown", "notes": "The Harness installer manages skill files, not Cursor's plugin marketplace installation."},
+        "assetsReferences": {"status": "Mechanism verified", "notes": "Portable skill files and referenced resources are present and checked."},
+        "updateSync": {"status": "Unknown", "notes": "No Cursor local-plugin reload or marketplace refresh has been run here."},
+        "liveHostVerification": {"status": "Unknown", "notes": "No Cursor session artifact is committed."}
+      }
+    },
+    {
+      "id": "continue",
+      "name": "Continue.dev",
+      "official_sources": [
+        "https://docs.continue.dev/customize/rules",
+        "https://docs.continue.dev/customize/deep-dives/rules"
+      ],
+      "capabilities": {
+        "standaloneSkills": {"status": "Unknown", "notes": "The reviewed Continue documentation establishes .continue/rules, not an Agent Skills discovery path."},
+        "pluginSupport": {"status": "Unknown", "notes": "No compatible Continue plugin package or official plugin discovery path was verified."},
+        "bundledSkills": {"status": "Unknown", "notes": "The installer target .continue/skills is retained as an adapter candidate, not a host-supported claim."},
+        "hooksLifecycle": {"status": "Unknown", "notes": "No official lifecycle hook contract was identified in the reviewed Continue sources."},
+        "projectScope": {"status": "Mechanism verified", "paths": {"rules": [".continue/rules"]}},
+        "globalScope": {"status": "Unknown", "notes": "A global skill/plugin scope is not established by the reviewed sources."},
+        "installUninstallSymmetry": {"status": "Mechanism verified", "notes": "Harness rule-file ownership and collision behavior are tested; skill loading remains unknown."},
+        "assetsReferences": {"status": "Unknown", "notes": "No official Continue skill package contract was verified."},
+        "updateSync": {"status": "Unknown", "notes": "No Continue refresh mechanism was verified."},
+        "liveHostVerification": {"status": "Unknown", "notes": "No Continue session artifact is committed."}
+      }
+    },
+    {
+      "id": "hermes",
+      "name": "Hermes Agent",
+      "official_sources": [
+        "https://hermes-agent.nousresearch.com/docs/user-guide/features/skills",
+        "https://hermes-agent.nousresearch.com/docs/developer-guide/creating-skills",
+        "https://hermes-agent.nousresearch.com/docs/guides/work-with-skills"
+      ],
+      "capabilities": {
+        "standaloneSkills": {"status": "Supported", "paths": {"project": [".hermes/skills", ".agents/skills"], "global": ["~/.hermes/skills"]}},
+        "pluginSupport": {"status": "Unknown", "notes": "Hermes documents plugins as an extension surface, but no compatible Harness plugin package is verified."},
+        "bundledSkills": {"status": "Mechanism verified", "notes": "The installer writes the documented skill tree; project skills remain subject to Hermes trust."},
+        "hooksLifecycle": {"status": "Unknown", "notes": "No Hermes lifecycle hook contract is claimed by Harness."},
+        "projectScope": {"status": "Mechanism verified", "paths": {"skills": [".hermes/skills", ".agents/skills"], "trust": ["hermes skills trust"]}},
+        "globalScope": {"status": "Mechanism verified", "paths": {"skills": ["~/.hermes/skills"]}},
+        "installUninstallSymmetry": {"status": "Mechanism verified", "notes": "Harness-owned Hermes skill and detection-marker round trips are tested."},
+        "assetsReferences": {"status": "Mechanism verified", "notes": "Skill-local references and scripts are retained in the installed tree and checked."},
+        "updateSync": {"status": "Unknown", "notes": "Hermes bundled-skill update behavior is documented, but Harness source refresh is not live verified."},
+        "liveHostVerification": {"status": "Unknown", "notes": "No Hermes session artifact is committed."}
+      }
+    }
+  ]
+}

package/docs/reflection.md

@@ -1,34 +1,63 @@
-# Harness Reflection, Memory & Self-Evolution
-
-AI models are notorious for forgetting lessons learned in previous coding sessions. When a bug is solved, if the developer opens a new terminal or launches a new AI session, the agent may encounter the same environment quirks or framework gotchas and make the exact same mistakes again.
-
-Harness solves this through its **Self-Evolution and Persistent Memory system**.
-
----
-
-## The Transaction Log (WAL) & Session Handoff
-
-Harness maintains a lightweight transaction log (analogous to a Write-Ahead Log in databases) via `hooks/scripts/state-persist.js`.
-
-*   **Continuous Capture:** Every successful tool use or milestone is recorded in the session transaction log.
-*   **Handoff File:** A session handoff checkpoint is saved in the workspace.
-*   **Session Start Recovery:** Upon starting a new session, the `bootstrap.js` hook reads the handoff file. It automatically "wakens" the agent, restoring the previous task state, completed milestones, and pending actions. This completely eliminates "session restart amnesia."
-
----
-
-## Long-term Memory & Workspace Rules
-
-When a complex issue—such as an environment-specific bug, a unique framework quirk, or a custom build command requirement—is successfully resolved:
-
-1.  **Deep Reflection:** Harness triggers the `self-evolve` skill, directing the model to reflect on the root cause and extract the exact pattern.
-2.  **Rule Generation:** The model abstracts the learning into a concise rule (avoiding generic prompt prose).
-3.  **RULES.md Integration:** The rule is appended or merged into local workspace rules (usually under a `RULES.md` or a customized folder).
-4.  **Self-Regression Validation:** Before any new rule is persisted, Harness executes the `self-regression.js` test suite. This ensures that the generated rules do not conflict with existing core rules and that all script syntax is 100% correct, preventing behavior decay.
-
----
-
-## The Benefits of Self-Evolution
-
-*   **Immunization:** The workspace is permanently "immunized" against recurring bugs.
-*   **Team Alignment:** Because rules are checked into Git, every developer (and every AI agent they launch) immediately benefits from the shared, updated knowledge base.
-*   **Token Efficiency:** Rather than the user repeatedly reminding the AI about custom project structures or conventions, the agent reads them natively from the immunized RULES file.
+# Harness Reflection, Memory & Self-Evolution
+
+AI models can forget lessons learned in previous coding sessions. When a bug is solved, a later session may encounter the same environment quirk or framework gotcha and repeat the same mistake.
+
+Harness addresses this with two deliberately separate concepts:
+
+1. **Runtime session state** — checkpoints/WAL-style state on integration surfaces that actually package the corresponding lifecycle/tool hooks.
+2. **Durable workspace learning** — `self-evolve` can persist a verified lesson as a concise rule or reusable generated skill when that persistence is justified.
+
+Do not infer runtime-state parity from shared skill text. The current platform boundary is documented in [platform-capabilities.md](platform-capabilities.md).
+
+---
+
+## Runtime Transaction State & Session Handoff
+
+The Claude Code hook path uses `hooks/scripts/state-persist.js` and `bootstrap.js` to maintain bounded runtime state and recover useful context across supported sessions.
+
+On a surface that packages those mechanisms:
+
+* **Outcome capture:** supported tool outcomes/milestones can update the session transaction state.
+* **Handoff checkpoint:** a session checkpoint can record pending/failed state for later recovery.
+* **Session-start recovery:** a compatible session-start hook can surface that checkpoint back to the agent.
+
+This is a runtime integration feature, not a property of every Harness skill installation. The **Codex / local OpenAI plugin** packages the session/prompt hooks plus the supported-tool `state-persist.js` / circuit-breaker / `PostToolUse` runtime and stop/subagent adapters. That is mechanism-tested package coverage, not proof that a live host loaded every hook. The public OpenAI **Skills-only** artifact has no local `.codex-plugin` lifecycle hooks at all.
+
+---
+
+## Long-term Memory & Workspace Rules
+
+When a complex issue — such as an environment-specific bug, unique framework quirk, or custom build requirement — is successfully resolved, the agent may use `self-evolve` to decide whether the verified lesson deserves durable persistence:
+
+1. **Deep Reflection:** establish the actual root cause and supporting evidence rather than persisting a guess.
+2. **Rule Generation:** abstract the lesson into a concise rule when a simple local reminder is enough.
+3. **Memory vs. Dynamic Skill Judgment:** decide whether the insight is a simple localized tip or a reusable multi-step procedure. Packaging every lesson as a skill would create unnecessary context and maintenance cost.
+   * **Simple Rule (default path):** persist to authorized local workspace rules via `persist-memory.js`.
+   * **Dynamic Skill (exception path):** create a standalone `SKILL.md` that satisfies `skill-creator`'s Dynamic Skill Generation Contract and register it through the supported manifest workflow so routing can surface it later.
+4. **Validation Before Persistence:** persistence is allowed only after the relevant validation/self-regression checks establish that the artifact is structurally valid and does not break the repository contract.
+
+`self-evolve` is not assumed to auto-trigger on every completed task. It is a reusable persistence workflow the agent selects when a lesson is both verified and worth keeping.
+
+---
+
+## External Skills: A Deliberately Different Loop for Third-Party Content
+
+`self-evolve`-generated skills are workspace-authored content whose lifecycle Harness can validate and manage. `find-skills` solves a different problem: discovering third-party skills that may change independently of this repository.
+
+Treating those two sources as the same trust tier would create silent drift. A fetched external skill can change upstream, be updated/removed outside Harness, or have metadata that no longer matches a cached copy.
+
+For that reason, `find-skills` prefers live/ephemeral discovery rather than silently converting borrowed content into durable Harness memory. `find-skills/scripts/use-skill.js` wraps the external fetch/apply path behind a content-addressed temporary cache, avoiding repository or manifest pollution for one-off use. Permanent installation remains an explicit user choice rather than the default persistence path.
+
+This separation keeps two questions distinct:
+
+- **What did this workspace learn and intentionally persist?** → `self-evolve` / generated rules or skills.
+- **What external expertise can this task borrow right now?** → `find-skills` / third-party discovery.
+
+---
+
+## The Benefits of Self-Evolution
+
+* **Immunization:** verified recurring lessons can become durable workspace guidance.
+* **Team Alignment:** project-owned rules/skills can be reviewed and shared through the repository's normal change process.
+* **Token Efficiency:** durable, concise knowledge can reduce repeated rediscovery without pretending every session has universal background memory.
+* **Clear evidence boundary:** session runtime state, durable project knowledge, and third-party borrowed skills remain separate mechanisms with separate trust and lifecycle rules.

package/docs/release-evidence.md

@@ -0,0 +1,25 @@
+# Release evidence
+
+This is the repository-facing record of release observations. It separates a release that was actually published from a version that is only prepared in source control. Add a dated row after collecting all four observations in [RELEASING.md](../RELEASING.md).
+
+## Observed release
+
+The following evidence was collected on 2026-09-07 before the issue #20 integration work:
+
+| Version | Registry observation | GitHub release | Workflow run | Gate and publish result |
+| --- | --- | --- | --- | --- |
+| 0.3.6 | `npm view harness-everything version dist-tags --json`: version and latest are `0.3.6` | `v0.3.6`, published 2026-09-01T03:50:44Z | [33466676632](https://github.com/dyphn1/Harness-everything/actions/runs/33466676632), commit `5aa74119d08ff241a7d6fe8f163a6a0d40c3c932` | `gate=success`, `publish=success` |
+
+The source capture for this row is the local review artifact `.git/issue-review-20260907/release-evidence.md`. That review artifact is not expected to be present in every checkout; it is historical evidence, not a release artifact shipped in the npm package.
+
+## Current review boundary
+
+No evidence in the source capture proves that `0.3.7-beta` was tagged, published to npm, or released on GitHub. The release preparation commit and changelog heading must therefore remain separate from a release claim until a maintainer records the post-tag observations above.
+
+## Evidence entry template
+
+Copy this row for each future release and replace every placeholder with command output or a directly inspectable URL:
+
+| `<version>` | `npm view ...`: `<registry version and dist-tags>` | [`v<version>`](https://github.com/dyphn1/Harness-everything/releases) published `<UTC timestamp>` | [`<run-id>`](https://github.com/dyphn1/Harness-everything/actions) commit `<full SHA>` | `gate=<conclusion>`, `publish=<conclusion>` |
+
+If a command fails or a field cannot be checked, record `not observed` instead of converting the missing observation into a success claim.

package/docs/routing.md

@@ -1,45 +1,171 @@
-# Harness Routing & Task Triage
-
-To prevent both over-engineering and under-planning, Harness classifies every user request into one of three execution tiers. This ensures that trivial tasks are executed instantly without unnecessary bloat, while complex architectural refactoring is strictly designed and verified.
-
----
-
-## The Three-Tier Routing System
-
-Upon receiving a request, the `tier-router.js` script analyzes the scope, affected files, and instruction patterns to route the task:
-
-```
-                  [ User Request ]
-                         |
-                         v
-                [ Triage Analysis ]
-               /         |         \
-              /          |          \
-     (Trivial)       (Standard)      (Macro)
-     /                   |                  \
-    v                    v                   v
-[ Tier 1 ]           [ Tier 2 ]          [ Tier 3 ]
-Direct Edit       Test-Driven (TDD)     Multi-Agent Flow
-(No plans)        (Red-Green-Refactor)   (Fable-Mode)
-```
-
-### Tier 1: Trivial Tasks (Direct Execution)
-*   **Trigger criteria:** Single-file edits, typos, simple styling fixes, readme corrections, or clean-up tasks.
-*   **Behavior:** Harness bypasses plans, code-reviews, and sub-agents. The model is directed to make the edit directly and complete the task, consuming minimal tokens.
-*   **Verification:** Basic syntax checks or a quick compile verify success.
-
-### Tier 2: Standard Tasks (Test-Driven Development)
-*   **Trigger criteria:** Normal feature requests, bug fixes, algorithm additions, API endpoint creations, or any task affecting multiple files with logical risk.
-*   **Behavior:** Harness enforces the `todo-driven-workflow` base execution loop (initialize a 3-7 item verifiable checklist before editing, one item in-progress at a time) and the `tdd` skill. The model is strictly guided through the Red-Green-Refactor loop:
-    1.  **Red:** Write an automated test first that reproduces the issue or covers the feature, then run it to verify failure.
-    2.  **Green:** Implement the minimal amount of code to make the test pass.
-    3.  **Refactor:** Polish the code, clean up duplicates, and ensure coverage targets (minimum 80%) are met.
-*   **Verification:** Strict execution of the test suite.
-
-### Tier 3: Macro Tasks (Multi-Agent/Fable-Mode)
-*   **Trigger criteria:** High-level design changes, migration of modules, large-scale refactoring, or major capability additions affecting multiple domains.
-*   **Behavior:** Harness automatically spawns the multi-agent orchestration engine (`fable-mode` and `create-agent-launcher`), with the macro plan materialized as the `todo-driven-workflow` checklist.
-    1.  **Planning:** An agent constructs a rigorous, phase-based implementation plan.
-    2.  **Delegation:** Specialized sub-agents (e.g., `security-reviewer`, `database-reviewer`, `code-reviewer`) are created to handle specific work streams or audits.
-    3.  **Handoffs:** Session handoffs are saved periodically to ensure that if a session limits out or restarts, the progress is seamlessly restored.
-*   **Verification:** Multi-layer unit, integration, and E2E verification loops.
+# Harness Routing & Task Triage
+
+Harness classifies software work into three tiers to prevent both over-engineering and under-planning. **The tier is a scope recommendation, not a workflow pipeline.**
+
+The current architecture follows one rule:
+
+> **Do not enforce workflow order. Enforce workflow invariants.**
+
+A strong model should be free to decide how to complete the task. Harness protects only the small set of behaviors that must not disappear when the host chooses a peer/domain skill directly.
+
+## Kernel invariants
+
+For software/project work, Harness establishes three mandatory rails before mutation:
+
+1. **Route before execution** — establish task scope/tier.
+2. **Verify before claim** — completion requires objective evidence appropriate to the change.
+3. **Re-plan after repeated failure** — after three same-signature failures, stop micro-retrying and use a fresh diagnosis / `zoom-out`.
+
+Skill selection, ordering, planning style, and delegation remain agent decisions unless the user or an authoritative project contract explicitly requires them.
+
+## Public routing path
+
+```text
+kernel-router.js
+  ├─ delegates classification / guide discovery → tier-router.js
+  ├─ preserves tier + rationale + dynamic-skill recommendations
+  ├─ suppresses legacy fixed-pipeline wording
+  ├─ emits required invariants
+  └─ emits advisory skill suggestions
+```
+
+Use:
+
+```bash
+node harness-everything/scripts/kernel-router.js "<prompt>"
+# or
+npx github:dyphn1/Harness-everything next "<prompt>"
+```
+
+On a host where `UserPromptSubmit` is wired, reuse the hook output instead of running it twice.
+
+## Non-software bypass
+
+General Q&A, translation, ordinary web search, and non-software writing bypass Harness routing. The model should answer directly and naturally.
+
+A software prompt that already says "use TDD", "security review", `repo-docs`, or another skill **does not bypass the kernel**. Host skill routing and Harness routing are different layers: the kernel establishes cross-cutting invariants; the host/model selects useful expertise.
+
+## Three-tier recommendation model
+
+```mermaid
+flowchart TD
+    U([User Request]) --> S{Software / project work?}
+    S -- No --> B[Bypass Harness]
+    S -- Yes --> K[Harness Kernel<br/>scope + invariants]
+    K --> T{Tier recommendation}
+    T -- Tier 1 --> A[Agent self-orchestrates]
+    T -- Tier 2 --> A
+    T -- Tier 3 --> A
+    A --> E[Execute selected tactics / skills]
+    E --> V{Evidence supports completion?}
+    V -- Yes --> D([Done])
+    V -- No --> R[Diagnose and iterate]
+    R --> F{Same failure x3?}
+    F -- No --> E
+    F -- Yes --> Z[Zoom out / re-plan]
+    Z --> E
+```
+
+### Tier 1 — Trivial
+
+Typical triggers: typos, narrow single-file edits, straightforward cleanup, code explanation, simple Git operations.
+
+Guidance:
+- prefer direct execution,
+- avoid large plans/delegation,
+- load a focused skill only when it adds value,
+- still gather enough evidence to support the completion claim.
+
+### Tier 2 — Standard
+
+Typical triggers: normal feature work, bug fixes, multi-file changes, security review, focused benchmark/evaluation.
+
+Possible suggestions:
+- `todo-driven-workflow` when explicit progress tracking helps,
+- `tdd` when executable behavioral tests are a useful design/verification tool,
+- `verification-loop` when systematic build/lint/test/diff selection helps,
+- `security-review` for trust/input/auth/secrets/network boundaries,
+- `using-git-worktrees` where isolation reduces workspace risk,
+- `eval-harness` for quantitative scoring.
+
+None of those imply a universal `TODO → TDD → verification-loop` sequence.
+
+### Tier 3 — Macro
+
+Typical triggers: repository-wide refactors, architecture/migration work, large ambiguous requirements, broad documentation/system design, or work that may benefit from delegation.
+
+Possible suggestions:
+- `fable-mode` / `fable-discipline` for deliberate macro planning,
+- `multi-agent-workspace` for bounded delegation,
+- `repo-docs` for project-level documentation,
+- `grill-with-docs`, `to-spec`, and `to-tickets` when design decisions/specs/issues genuinely help.
+
+Tier 3 does **not** automatically mean multi-agent. If one capable agent can complete the work safely and efficiently, direct execution is valid.
+
+## Classifier tuning
+
+`tier-router.js` reads keyword/guide tables from `harness-everything/scripts/routing-keywords.json`. Edit that data to tune Tier 2/3 signals or knowledge-guide matches without changing classifier code.
+
+The classifier remains heuristic:
+- its recommendation is the default, not an order,
+- a clear task reading may override it,
+- explicit user intent wins,
+- when overriding a materially different tier, record the reason briefly.
+
+## Pre-action `actionGate`
+
+The router may predict that a request needs `workflowPlan.actionGate`, but the Phase 5 enforcement hook deliberately **re-classifies the exact tool payload**. A missing or incorrect router prediction therefore cannot authorize a destructive command.
+
+The executable policy lives in `hooks/scripts/action-gate-rules.json`. A missing or invalid table activates built-in safety defaults and reports the degradation. A valid empty table remains empty so the CI negative control can detect accidental policy erasure.
+
+| Exact tool action | Harness result | Audit disposition before execution |
+|---|---|---|
+| Safe unmatched command such as `git status` | allow/no decision | no gate record |
+| Matched command on Claude Code (default policy) | no decision: the session's permission mode, rules and auto-mode classifier decide | `deferred-to-host` |
+| Matched command on Claude Code with `HARNESS_ACTION_GATE_POLICY=always-ask` | `permissionDecision: "ask"` | `pending-approval` |
+| Matched command on a host without Harness-verified ask semantics | block with exit 2 | `rejected` |
+| Payload reaches `PostToolUse` | continue | `executed` with exact payload SHA-256 |
+| Payload reaches `PostToolUseFailure` | continue | `executed` + failed execution outcome |
+| Deferred or pending payload never executes before `Stop` | no execution | `rejected` |
+| Hook internal error | Claude: no decision plus a `systemMessage` warning (`always-ask`: `ask`); other/unverified host: exit 2 | host decides on Claude; fail closed elsewhere |
+
+`rm -rf` and `Remove-Item -Recurse -Force` are exempt only when every parsed target is inside the OS temp directory, the current session scratch directory, or an explicitly supplied Harness scratch directory. An uncertain target is gated conservatively.
+
+```mermaid
+flowchart TD
+    P[PreToolUse exact payload] --> C{Matches action-gate rule?}
+    C -- No --> A[Allow without gate record]
+    C -- Yes --> X{Scratch-only destructive delete?}
+    X -- Yes --> A
+    X -- No --> H{Host has a native permission flow?}
+    H -- Claude Code --> Y{always-ask policy?}
+    Y -- No --> D[No decision: the permission mode decides<br/>record deferred-to-host + payload hash]
+    Y -- Yes --> Q[Emit permissionDecision: ask<br/>record pending-approval + payload hash]
+    H -- No / unknown --> B[Exit 2 block<br/>record rejected]
+    D --> U{Did the exact tool payload execute?}
+    Q --> U
+    U -- PostToolUse --> E[record executed]
+    U -- PostToolUseFailure --> F[record executed + failure]
+    U -- no execution by Stop --> R[record rejected]
+```
+
+On Claude Code the gate returns no decision by default. The [hooks reference](https://code.claude.com/docs/en/hooks) says a hook's `ask` "also forces a permission prompt in auto mode: the classifier can still deny the tool call, but it can't approve the call silently". A forced `ask` would therefore override the permission mode the user picked (#107).
+
+With no decision, the normal permission flow applies:
+
+- Manual and `acceptEdits` prompt unless a rule or the mode already allows the command.
+- Auto mode lets the classifier decide.
+- `dontAsk` denies anything that is not pre-approved.
+- Deny rules apply in every mode.
+
+Set `HARNESS_ACTION_GATE_POLICY=always-ask` to have Harness force its own prompt instead. Either way the gate classifies and audits every matched payload.
+
+The deterministic suite verifies two things: the deferred result for every known `permission_mode` value, and the `ask` JSON under `always-ask`. That is **mechanism evidence only** until preserved live evidence exists.
+
+## Cognitive OS relationship
+
+`install-cognitive-os` remains the canonical explanatory/manual entry point for Discover → Think → Try → Summarize → Record. It is **not** required to win peer-skill selection before domain work begins. The runtime kernel establishes the smaller invariant contract independently; domain skills provide their own tactics inside that contract.
+
+## Enforcement strength
+
+A lifecycle hook can mechanically inject/guard supported invariants. Instruction-only integrations can only advise the model. Do not label advisory behavior as hard enforcement, and do not infer cross-host parity from shared skill text alone.