harness-everything 0.3.6 → 0.4.1

package/docs/platform-capabilities.md

@@ -0,0 +1,73 @@
+# Platform Capability Matrix
+
+This is the repository-wide source of truth for current platform integration, installation, and enforcement claims. The machine-readable matrix is [platform-compatibility.json](platform-compatibility.json); this page explains its evidence boundaries and the most important operator-facing paths.
+
+## Evidence policy
+
+The matrix separates standalone Agent Skills from plugin support, bundled skills, lifecycle hooks, project/global scope, install/uninstall symmetry, assets/references, update/sync, and live-host verification. A package or deterministic mechanism test cannot be promoted to `Live verified` without a preserved real-host session, import report, or portal artifact.
+
+Statuses are intentionally explicit:
+
+- `Supported`: official/native host support and a verified Harness path.
+- `Mechanism verified`: the repository package, adapter, or installer contract passes; a real host run is not confirmed.
+- `Live verified`: preserved evidence shows a real host session or portal operation.
+- `Partial`: only part of the capability is available or verified.
+- `Unsupported`: official host documentation explicitly rules out the capability.
+- `Unknown`: the capability or its current host behavior was not established.
+
+All current `liveHostVerification` rows are `Unknown`. This checkout contains deterministic package and installer evidence, but no fresh host-session artifacts, managed-workspace import report, or public OpenAI approval record.
+
+## Current capability summary
+
+| Platform surface | Standalone skills | Plugin support | Hooks/lifecycle | Project scope | Global scope | Current evidence boundary |
+| --- | --- | --- | --- | --- | --- | --- |
+| Codex | `Supported` | `Mechanism verified` | `Mechanism verified` for the local OpenAI package, including session, prompt, supported-tool, subagent, and stop hooks | `.agents/skills/`, `AGENTS.md` | `~/.agents/skills/` | Local package hooks are mechanically checked; live loading and marketplace refresh remain `Unknown`. |
+| ChatGPT / OpenAI Plugin | `Unknown` for a repository-local standalone path | `Mechanism verified` | `Partial`: local Work/Codex hooks are separate from ordinary Chat | Managed workspace marketplace | Not established | The public Skills-only bundle is mechanically reproducible; import, approval, and live behavior remain `Unknown`. |
+| Claude Code | `Supported` | `Supported` | `Mechanism verified` for Harness configuration | `.claude/skills/` | `~/.claude/skills/` | Native Claude surfaces are documented and package/installer checks pass; fresh-host execution is not preserved here. |
+| OpenCode | `Supported` | `Mechanism verified` | `Mechanism verified` against `tool.execute.*` and `session.idle` | `.opencode/skills/`, `.agents/skills/`, `.opencode/plugins/` | `~/.config/opencode/skills/`, `~/.agents/skills/`, `~/.config/opencode/plugins/` | The real adapter API is tested, but live plugin loading remains unverified. |
+| GitHub Copilot agent surfaces | `Supported` | `Unknown` for a Harness-specific plugin install | `Unknown` | `.github/skills/`, `.agents/skills/`, repository instructions | `~/.copilot/skills/`, `~/.agents/skills/` | GitHub Agent Skills paths and installer behavior are checked; no live Copilot session or plugin install is preserved. |
+| Cursor | `Supported` | `Mechanism verified` for the portable package shape | `Unknown` for Harness | `.cursor/skills/`, `.agents/skills/` | `~/.cursor/skills/`, `~/.agents/skills/` | Official paths and package shape are checked; Cursor plugin loading and hooks remain unverified. |
+| Continue.dev | `Unknown` for standalone `SKILL.md` discovery | `Unknown` | `Unknown` | `.continue/rules/` is documented; `.continue/skills/` is only an installer candidate | `~/.continue/skills/` is only an installer candidate | The reviewed official docs establish rules, not an Agent Skills host contract. |
+| Hermes Agent | `Supported` | `Unknown` | `Unknown` | `.hermes/skills/` or trusted `.agents/skills/` | `~/.hermes/skills/` | Skill installation and ownership are tested; project loading still follows Hermes trust, and no live session is preserved. |
+
+The full ten-dimension entries and official source URLs are in [platform-compatibility.json](platform-compatibility.json). “Supported” in the standalone-skills column refers to the host’s documented skill surface plus the repository’s verified path contract; it does not mean that a live Harness session was run on every platform.
+
+## Installer target contract
+
+The general installer’s target paths are tested independently from host discovery. This prevents a successful file copy from being reported as proof that an agent will load the file.
+
+| Installer target | Project scope | User/global scope | Host-support note |
+| --- | --- | --- | --- |
+| Claude Code | `.claude/skills/` | `~/.claude/skills/` | Official skill locations |
+| Cursor | `.cursor/skills/` | `~/.agents/skills/` | Official Agent Skills compatibility path |
+| GitHub Copilot agent surfaces | `.github/skills/` | `~/.agents/skills/` | Official project/global Agent Skills paths |
+| Codex | `.agents/skills/` | `~/.agents/skills/` | Official Agent Skills paths; `AGENTS.md` is separate instruction context |
+| Continue.dev | `.continue/skills/` | `~/.continue/skills/` | Installer adapter candidate; host discovery is `Unknown` from reviewed official docs |
+| Hermes Agent | `.agents/skills/` | `~/.hermes/skills/` | Project loading is subject to Hermes trust |
+
+These targets apply to both default link mode and explicit `--copy` mode. A canonical store is only a deduplication detail; it cannot make an unsupported host path supported. Install/uninstall tests also protect user-owned files and cover Linux, Windows, and macOS round-trip fixtures.
+
+## Codex / local OpenAI plugin boundary
+
+Codex has two paths that must not be collapsed:
+
+1. The general `--codex` installer writes advisory `AGENTS.md` plus repo-scoped skills under `.agents/skills/`.
+2. The local OpenAI plugin at `plugins/harness-everything/` packages the skills plus lifecycle hooks for session start, prompt routing, supported local tool calls, subagent lifecycle, and stop verification. Those hooks are mechanically checked, but no live plugin/session artifact is committed.
+
+The package is tested at the mechanism layer and remains subject to the host’s hook review/trust flow. A fresh host session is still required before claiming that a particular ChatGPT/Codex installation loaded and fired the hooks.
+
+The public OpenAI Skills-only plugin is narrower again. Its ZIP contains the packaged `skills/` tree and referenced files, but not the local `.codex-plugin` lifecycle hooks. Public submission readiness is therefore a package/form contract, not evidence of public-directory approval or live hook execution.
+
+## Install/uninstall ownership boundary
+
+The general installer merges shared files only through Harness-owned markers and removes only manifest-tracked artifacts. Malformed configuration and pre-existing user-owned files fail closed. Install/uninstall round-trip coverage protects user skills and runs on Linux, Windows, and macOS fixtures.
+
+## OpenCode boundary
+
+The OpenCode adapter uses the documented plugin API and has deterministic mechanism coverage. That proves the implementation contract only. **Live plugin loading remains unverified** until a real OpenCode session artifact demonstrates that the host loaded and fired the module.
+
+## Official sources
+
+The matrix records the official documentation reviewed for each platform. Important source families include [OpenAI plugin packaging](https://developers.openai.com/plugins/build/plugins), [OpenAI public submission](https://developers.openai.com/plugins/deploy/submission), [Codex skills](https://learn.chatgpt.com/docs/build-skills), [Codex hooks](https://learn.chatgpt.com/docs/hooks), [Claude skills](https://code.claude.com/docs/en/skills), [OpenCode skills](https://opencode.ai/docs/skills), [GitHub Copilot Agent Skills](https://docs.github.com/en/copilot/how-tos/copilot-on-github/customize-copilot/customize-cloud-agent/add-skills), [Cursor skills](https://cursor.com/docs/skills), [Continue rules](https://docs.continue.dev/customize/rules), and [Hermes skills](https://hermes-agent.nousresearch.com/docs/user-guide/features/skills).
+
+When a platform behavior changes, update this page, `docs/platform-compatibility.json`, and every affected current-state surface in the same change. `npm run test:docs:capabilities` and the compatibility mechanism suite enforce the repository-side contract; they do not replace manual live-host evidence.

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,48 +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.
+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 solves this through its **Self-Evolution and Persistent Memory system**.
+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).
 
 ---
 
-## The Transaction Log (WAL) & Session Handoff
+## 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.
 
-Harness maintains a lightweight transaction log (analogous to a Write-Ahead Log in databases) via `hooks/scripts/state-persist.js`.
+On a surface that packages those mechanisms:
 
-*   **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."
+* **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, a unique framework quirk, or a custom build command requirement—is successfully resolved:
+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.
 
-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.  **Memory vs. Dynamic Skill Judgment:** The model decides whether the insight is a simple, localized tip or a reusable, complex procedure — packaging every lesson as a skill would bloat context for no benefit, so this is a deliberate gate, not the default.
-    *   **Simple Rule (default path):** Appended to local workspace rules (`RULES.md`, or a customized folder) via `persist-memory.js`.
-    *   **Dynamic Skill (exception path):** Written as a standalone `SKILL.md` under `.claude/harness-everything/skills/generated/<name>/` per `skill-creator`'s Dynamic Skill Generation Contract (with `status: draft` lifecycle metadata and required `triggers:` keywords), then registered via `register-dynamic-skill.js` into `manifest.json`. From there, `tier-router.js` scans and auto-surfaces it in future sessions whenever its triggers match the prompt — closing the loop from "learned once" to "discovered automatically," not just recorded.
-4.  **Self-Regression Validation:** Before any new rule or dynamic skill is persisted, Harness executes the `self-regression.js` test suite. This ensures that the generated rules/skills do not conflict with existing core rules and that all script syntax is 100% correct, preventing behavior decay.
+`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
+## 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.
 
-`self-evolve`'s `generated[]` skills are self-authored — this workspace's own agent wrote them, `skill-creator` quality-gates them, and their lifecycle (`draft` → `active` → `deprecated`) is entirely Harness's to track. `find-skills` closes an adjacent gap — a capability that's neither in the static registry nor something this workspace has already learned, but that a third-party skill on `skills.sh` covers — and it was tempting to mirror `generated[]`'s exact mechanism for it (cache the skill's path + triggers in `manifest.json`, let `tier-router.js` auto-surface it the same way).
+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.
 
-That mirroring was tried and deliberately reverted: `generated[]` is safe to cache because Harness owns the whole lifecycle behind it. A skill fetched via `npx skills add` has none of that guarantee — its author can update the `SKILL.md` at any time, or the user can run `npx skills update`/`remove` independently of Harness, and a cached copy of its `description`/`triggers` from install time would silently drift out of sync with no mechanism to notice. Caching it anyway would launder unaudited, unowned third-party content into the same trust tier as `generated[]`'s self-authored, quality-gated content — a category error, not just a missing feature.
+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.
 
-So `find-skills` queries live instead of caching bookkeeping, and — a step further — defaults to never installing anything in the first place. `npx skills` already ships an ephemeral mode built for exactly this (`npx skills use <source>`): it fetches a skill and prints its content as a ready-to-follow prompt without installing it anywhere. `find-skills/scripts/use-skill.js` wraps that call behind a content-addressed cache under the OS temp directory (`os.tmpdir()/harness-find-skills-cache/<sha1-of-source>.md`, default 6h freshness) — a real fetch on first lookup, then zero network cost on repeat lookups of the same source, and nothing written to the repo, to a platform's native skill directory, or to `manifest.json`. When the OS eventually reclaims that temp directory, that's the entire "cleanup" story - no explicit expiry logic to maintain, because there was never any permanent state to expire.
+This separation keeps two questions distinct:
 
-Permanent install (`npx skills add`) still exists, but only as an explicit exception the user opts into when they know they'll reuse a skill across many future sessions - never the default `find-skills` reaches for. Checking `npx skills list` (§0.3 in `find-skills/SKILL.md`) only ever finds something from that rare path; the default ephemeral path never shows up there, by design, because it never installs. This is the actual answer to "won't skills pile up and bloat context over time?" - most borrowed knowledge is solved-once, applied-once, and leaves nothing behind. Only the deliberate minority a human chooses to keep ever accumulates, and that minority is small enough to stay legible without any Harness-side tracking.
+- **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:** 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.
+* **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,27 @@
+# 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
+
+This file is an evidence ledger, not a source of truth for the current package version. Historical rows stay unchanged until all four observations for a newer release are deliberately collected. Current release/runtime configuration must be read from Git history, package metadata, the release workflow, and [repository-contract.md](repository-contract.md), rather than from prose such as the retired `0.3.7-beta` review note.
+
+A GitHub tag or source version alone is not enough to add a completed row here; keep using `not observed` when registry, workflow, or publication evidence has not been checked.
+
+## 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/repository-contract.md

@@ -0,0 +1,27 @@
+<!-- GENERATED by scripts/repository-contract.js. Run `npm run docs:sync` after workflow/runtime changes. -->
+# Repository runtime and workflow contract
+
+This page is generated from checked-in runtime and workflow sources. Do not edit it by hand. Historical audit/evidence documents are intentionally outside this current-state contract.
+
+## Runtime
+
+- Minimum supported Node.js: **22** (from `package.json#engines.node`: `>=22`)
+- Primary development/CI Node.js: **24** (from `.nvmrc`)
+- Docker verification Node.js: **24** (from `Dockerfile`)
+
+## GitHub Actions runtime majors
+
+- `actions/checkout`: v7
+- `actions/setup-node`: v7
+
+## Active workflows
+
+| Workflow | Node.js versions | Explicit triggers | npm quality gates |
+| --- | --- | --- | --- |
+| `behavioral-evals.yml` | 24 | schedule, workflow_dispatch | n/a |
+| `ci.yml` | 22, 24 | workflow_call | `test`, `test:mutations`, `test:consistency`, `test:references`, `test:release`, `test:collision`, `test:plugin:openai`, `test:plugin:submission`, `test:platform:compatibility` |
+| `release.yml` | 24 | workflow_dispatch | n/a |
+
+## Drift prevention
+
+`npm run test:repo-contract` fails when runtime sources disagree, an active workflow reintroduces an unsupported Node version/action major, the Node 22 compatibility floor is no longer exercised, or this generated document is stale.