repo-harness 0.4.3 → 0.5.0

package/README.es.md

@@ -42,7 +42,7 @@ repo-local que él mismo genera para los proyectos downstream.
   opcionales según el tipo de proyecto y cuatro hook profiles (`standard`,
   `minimal`, `biome`, `biome-strict`). Ejecuta
   `npx -y repo-harness init`; no necesitas clonar el repositorio fuente.
-- **Comando de refresco del repo (`repo-harness update`).** La instalación y el
+- **Comando de adopción del repo (`repo-harness adopt`).** La instalación y el
   refresco de repos existentes tienen su propia superficie de comando, manteniendo
   la ruta de migración repo-local anterior mientras `init` queda dedicado al
   runtime global.
@@ -100,7 +100,7 @@ En conjunto hay tres capas:
 1. **Capa del paquete fuente**: este repositorio mantiene la CLI, los command
    skill facades, los templates, los hook assets, el workflow contract, los tests
    y el release gate.
-2. **Capa del contract del repositorio objetivo**: `repo-harness update` o la
+2. **Capa del contract del repositorio objetivo**: `repo-harness adopt` o la
    migración escribe `docs/spec.md`, `plans/`, `tasks/`, `.ai/context/`,
    `.ai/harness/`, helper scripts y `.ai/hooks/`.
 3. **Capa del host adapter**: el `~/.claude/settings.json` y el
@@ -208,7 +208,8 @@ npx -y repo-harness init
 
 La npm package release line y el generated workflow stamp usan ahora la misma
 línea `0.4.x`. `repo-harness init` es el bootstrap
-global y `repo-harness update` es el refresco repo-local. `repo-harness init`
+global, `repo-harness update` es el refresco user-level y `repo-harness adopt`
+es el refresco repo-local. `repo-harness init`
 configura el CLI, los hook adapters de nivel usuario, Waza, Mermaid, el brain
 root y CodeGraph MCP; el viejo camino Claude plugin `scripts/setup-plugins.sh`
 queda retirado.
@@ -245,17 +246,17 @@ elimina `scripts/sync-codex-installed-copies.sh`.
 En un repositorio existente, ejecuta desde el repo root:
 
 ```bash
-npx -y repo-harness update --dry-run
+npx -y repo-harness adopt --dry-run
 ```
 
 Aplica solo después de que el reporte del dry-run sea correcto:
 
 ```bash
-npx -y repo-harness update
+npx -y repo-harness adopt
 ```
 
 Para un proyecto o módulo nuevo, usa la branch command `repo-harness-scaffold`.
-Para un repositorio existente, usa `repo-harness update`; este instala o refresca
+Para un repositorio existente, usa `repo-harness adopt`; este instala o refresca
 el harness y no crea el stack tecnológico de la aplicación.
 
 ### Cómo se ve el éxito
@@ -345,8 +346,8 @@ Guards habituales:
 
 ## Release actual
 
-- npm package: `repo-harness@0.4.3`
-- Generated workflow stamp: `repo-harness@0.4.3+template@0.4.3`
+- npm package: `repo-harness@0.5.0`
+- Generated workflow stamp: `repo-harness@0.5.0+template@0.5.0`
 - GitHub repository: `Ancienttwo/repo-harness`
 - Release history: [`docs/CHANGELOG.md`](docs/CHANGELOG.md)
 
@@ -360,7 +361,7 @@ Guards habituales:
   - `assets/workflow-contract.v1.json`
 - Los generated repos usan por defecto el repo-local harness flow:
   - `docs/spec.md -> plans/ -> tasks/contracts/ -> tasks/reviews/ -> .ai/context/context-map.json -> .ai/harness/*`
-- `repo-harness update` refresca las runtime pieces:
+- `repo-harness update` refresca las runtime pieces de usuario:
   - los `repo-harness` skill aliases
   - los global Codex/Claude hook adapters
   - las Waza skills: `think`, `hunt`, `check`, `health`
@@ -393,7 +394,7 @@ compatibilidad de discovery por skills, mientras el CLI y los hooks ejecutan:
 - Repo workflow actions: `repo-harness-ship`, `repo-harness-init`, `repo-harness-migrate`, `repo-harness-upgrade`, `repo-harness-capability`, `repo-harness-architecture`, `repo-harness-handoff`, `repo-harness-deploy`, `repo-harness-repair`, `repo-harness-check`
 - Branch project creation: `repo-harness-scaffold`
 
-`repo-harness update` se usa para repositorios existentes; `repo-harness-scaffold`
+`repo-harness adopt` se usa para repositorios existentes; `repo-harness-scaffold`
 queda como branch command para crear proyectos o módulos nuevos. `hooks-init`, `docs-init` y
 `create-project-dirs` son pasos internos, no commands públicos.
 

package/README.fr.md

@@ -42,7 +42,7 @@ workflow repo-local qu'il génère lui-même pour les projets en aval.
   optionnels selon le type de projet, et quatre hook profiles (`standard`,
   `minimal`, `biome`, `biome-strict`). Exécutez
   `npx -y repo-harness init` ; aucun clone du dépôt source n'est nécessaire.
-- **Commande de rafraîchissement du dépôt (`repo-harness update`).** L'installation
+- **Commande d'adoption du dépôt (`repo-harness adopt`).** L'installation
   et le rafraîchissement des dépôts existants ont leur propre surface de commande,
   tout en conservant l'ancien chemin de migration repo-local et en gardant `init`
   dédié au runtime global.
@@ -102,7 +102,7 @@ L'ensemble se découpe en trois couches :
 1. **Couche package source** : ce dépôt maintient le CLI, les command skill
    facades, les templates, les hook assets, le workflow contract, les tests et le
    release gate.
-2. **Couche contrat du dépôt cible** : `repo-harness update` ou une migration écrit
+2. **Couche contrat du dépôt cible** : `repo-harness adopt` ou une migration écrit
    `docs/spec.md`, `plans/`, `tasks/`, `.ai/context/`, `.ai/harness/`, les helper
    scripts et `.ai/hooks/`.
 3. **Couche host adapter** : les `~/.claude/settings.json` et `~/.codex/hooks.json`
@@ -213,8 +213,8 @@ npx -y repo-harness init
 
 La release line du package npm et le generated workflow stamp utilisent
 désormais la même ligne `0.4.x`. `repo-harness init`
-sert au bootstrap global et `repo-harness update` sert au rafraîchissement
-repo-local. `repo-harness init` configure le CLI, les hook adapters de niveau
+sert au bootstrap global, `repo-harness update` au rafraîchissement
+user-level, et `repo-harness adopt` au rafraîchissement repo-local. `repo-harness init` configure le CLI, les hook adapters de niveau
 utilisateur, Waza, Mermaid, le brain root et CodeGraph MCP ; l'ancien chemin
 Claude plugin `scripts/setup-plugins.sh` est retiré.
 
@@ -250,17 +250,17 @@ sont supprimés par `scripts/sync-codex-installed-copies.sh`.
 Pour un dépôt existant, exécutez depuis le repo root :
 
 ```bash
-npx -y repo-harness update --dry-run
+npx -y repo-harness adopt --dry-run
 ```
 
 Appliquez seulement une fois que le rapport du dry-run est correct :
 
 ```bash
-npx -y repo-harness update
+npx -y repo-harness adopt
 ```
 
 Pour un nouveau projet ou un nouveau module, utilisez la branch command
-`repo-harness-scaffold`. Pour un dépôt existant, utilisez `repo-harness update` ;
+`repo-harness-scaffold`. Pour un dépôt existant, utilisez `repo-harness adopt` ;
 il installe ou rafraîchit le harness sans créer de stack applicatif.
 
 ### À quoi ressemble le succès
@@ -350,8 +350,8 @@ Guards courants :
 
 ## Release actuelle
 
-- npm package : `repo-harness@0.4.3`
-- Generated workflow stamp : `repo-harness@0.4.3+template@0.4.3`
+- npm package : `repo-harness@0.5.0`
+- Generated workflow stamp : `repo-harness@0.5.0+template@0.5.0`
 - GitHub repository : `Ancienttwo/repo-harness`
 - Release history : [`docs/CHANGELOG.md`](docs/CHANGELOG.md)
 
@@ -365,7 +365,7 @@ Guards courants :
   - `assets/workflow-contract.v1.json`
 - Les generated repos utilisent par défaut le repo-local harness flow :
   - `docs/spec.md -> plans/ -> tasks/contracts/ -> tasks/reviews/ -> .ai/context/context-map.json -> .ai/harness/*`
-- `repo-harness update` rafraîchit les runtime pieces :
+- `repo-harness update` rafraîchit les runtime pieces utilisateur :
   - les `repo-harness` skill aliases
   - les global Codex/Claude hook adapters
   - les Waza skills : `think`, `hunt`, `check`, `health`
@@ -399,7 +399,7 @@ aux hooks :
 - Repo workflow actions : `repo-harness-ship`, `repo-harness-init`, `repo-harness-migrate`, `repo-harness-upgrade`, `repo-harness-capability`, `repo-harness-architecture`, `repo-harness-handoff`, `repo-harness-deploy`, `repo-harness-repair`, `repo-harness-check`
 - Branch project creation : `repo-harness-scaffold`
 
-`repo-harness update` sert aux dépôts existants ; `repo-harness-scaffold` sert de
+`repo-harness adopt` sert aux dépôts existants ; `repo-harness-scaffold` sert de
 branch command pour créer un nouveau projet ou module. `hooks-init`, `docs-init` et
 `create-project-dirs` sont des étapes internes, pas des commands publiques.
 

package/README.ja.md

@@ -34,7 +34,7 @@ skill runtime を提供します。
   commit/pending）、プロジェクト種別ごとのオプション LSP plugins、そして 4 段階の hook profile
   （`standard`、`minimal`、`biome`、`biome-strict`）を扱います。
   実行は `npx -y repo-harness init`。source checkout は不要です。
-- **Repo refresh コマンド（`repo-harness update`）。** 既存 repo の install / refresh は
+- **Repo adoption コマンド（`repo-harness adopt`）。** 既存 repo の install / refresh は
   独立した command surface になり、従来の repo-local migration path を保ちながら
   `init` は global runtime setup に集中します。
 - **CodeGraph index の自己修復。** prompt hook が構造的な code-navigation intent を検出し、
@@ -79,7 +79,7 @@ product boundary は意図的に地味です。対象リポジトリを検査し
 
 1. **ソースパッケージ層**：本リポジトリが CLI、CLI-backed command facades、templates、hook assets、
    workflow contract、tests、release gate を所有します。
-2. **対象リポジトリ contract 層**：`repo-harness update` または migration が、`docs/spec.md`、
+2. **対象リポジトリ contract 層**：`repo-harness adopt` または migration が、`docs/spec.md`、
    `plans/`、`tasks/`、`.ai/context/`、`.ai/harness/`、helper scripts、`.ai/hooks/` といった
    repo-local ファイルを書き込みます。
 3. **Host adapter 層**：user-level の `~/.claude/settings.json` と `~/.codex/hooks.json` が
@@ -180,7 +180,7 @@ npx -y repo-harness init
 
 npm package と generated workflow stamp は現在同じ `0.4.x` release line を使います。
 `repo-harness init` は global bootstrap、`repo-harness update` は
-repo-local refresh です。`repo-harness init` は CLI、user-level hook adapters、Waza、Mermaid、
+user-level refresh、`repo-harness adopt` は repo-local refresh です。`repo-harness init` は CLI、user-level hook adapters、Waza、Mermaid、
 brain root、CodeGraph MCP を設定し、退役した `scripts/setup-plugins.sh` の Claude plugin path は使いません。
 
 ソースの checkout から作業する場合：
@@ -214,17 +214,17 @@ symlink に裏打ちされた runtime entrypoint です。退役した `repo-har
 既存リポジトリでは repo root から実行します。
 
 ```bash
-npx -y repo-harness update --dry-run
+npx -y repo-harness adopt --dry-run
 ```
 
 dry-run のレポートが正しいことを確認してから適用します。
 
 ```bash
-npx -y repo-harness update
+npx -y repo-harness adopt
 ```
 
 新しいプロジェクトやモジュールには支線 command `repo-harness-scaffold` を使います。既存リポジトリには
-`repo-harness update` を使います。これは harness をインストールまたはリフレッシュするもので、アプリケーション
+`repo-harness adopt` を使います。これは harness をインストールまたはリフレッシュするもので、アプリケーション
 スタックは作成しません。
 
 ### 成功した状態
@@ -312,8 +312,8 @@ hook がブロックしたときは、まず terminal の構造化された出
 
 ## 現在の Release
 
-- npm package：`repo-harness@0.4.3`
-- Generated workflow stamp：`repo-harness@0.4.3+template@0.4.3`
+- npm package：`repo-harness@0.5.0`
+- Generated workflow stamp：`repo-harness@0.5.0+template@0.5.0`
 - GitHub repository：`Ancienttwo/repo-harness`
 - Release history：[`docs/CHANGELOG.md`](docs/CHANGELOG.md)
 
@@ -327,7 +327,7 @@ hook がブロックしたときは、まず terminal の構造化された出
   - `assets/workflow-contract.v1.json`
 - Generated repos はデフォルトで repo-local harness flow を使います：
   - `docs/spec.md -> plans/ -> tasks/contracts/ -> tasks/reviews/ -> .ai/context/context-map.json -> .ai/harness/*`
-- `repo-harness update` は runtime pieces をリフレッシュします：
+- `repo-harness update` は user-level runtime pieces をリフレッシュします：
   - `repo-harness` skill aliases
   - global Codex/Claude hook adapters
   - Waza skills：`think`、`hunt`、`check`、`health`
@@ -358,7 +358,7 @@ knowledge sync、handoff retrieval の workflow 設計に影響を与えてい
 - Repo workflow actions：`repo-harness-ship`、`repo-harness-init`、`repo-harness-migrate`、`repo-harness-upgrade`、`repo-harness-capability`、`repo-harness-architecture`、`repo-harness-handoff`、`repo-harness-deploy`、`repo-harness-repair`、`repo-harness-check`
 - Branch project creation：`repo-harness-scaffold`
 
-`repo-harness update` は既存リポジトリ向け、`repo-harness-scaffold` は支線 command として新しいプロジェクトやモジュールを作成します。
+`repo-harness adopt` は既存リポジトリ向け、`repo-harness-scaffold` は支線 command として新しいプロジェクトやモジュールを作成します。
 `hooks-init`、`docs-init`、`create-project-dirs` は内部ステップであり、公開 commands ではありません。
 
 ## Maintainer Reference

package/README.md

@@ -1,7 +1,7 @@
 # repo-harness
 
 <p align="center">
-  <img src="docs/images/repo-harness-hook-carrot.png" alt="repo-harness hooks leading Codex and Claude forward with repo-local workflow state" width="900">
+  <img src="docs/images/image.png" alt="One next button joining Claude and Codex under repo-harness workflow rules" width="760">
 </p>
 
 Repo-local agentic development harness CLI and skill runtime for Claude/Codex
@@ -43,20 +43,21 @@ In an adopted repo, the surface area is intentionally small:
 | `tasks/contracts/`, `tasks/reviews/`, and `.ai/harness/checks/` | Scope, verification, and review evidence for proving the work is done. |
 | `.ai/harness/handoff/` and `tasks/current.md` | Session journal and resumable status, derived from workflow artifacts instead of chat memory. |
 
-## What's New in 0.4.3
-
-- **Runtime docs lookup.** `repo-harness docs list|path|show` resolves bundled
-  runtime/reference docs from the installed package instead of requiring copied
-  repo prose.
-- **Init-hook bootstrap audit.** `repo-harness init-hook --json` reports concrete
-  Agent actions for missing working rules, adapter drift, stale CLI installs,
-  and tooling readiness.
-- **First-principles edit guard.** Managed hook routes now include
-  anti-overengineering guidance for implementation edits while keeping the guard
-  advisory.
-- **Slimmer generated reference docs.** Generated and migrated repos write
-  deterministic `docs/reference-configs/*.md` pointer stubs while `.ai/harness/*`
-  and `.ai/context/*` remain local runtime artifacts.
+## What's New in 0.5.0
+
+- **Clean command boundary.** `repo-harness update` now refreshes only the
+  user-level CLI/runtime surface, while `repo-harness adopt` owns repo-local
+  workflow install, refresh, and migration.
+- **Package-dispatched helper runtime.** Generated `scripts/*` wrappers can
+  delegate through `repo-harness run <helper>`, so adopted repos do not need to
+  vendor every helper implementation when the installed package already owns it.
+- **Eight managed hook routes.** The README now documents the exact hook route
+  matrix that Claude and Codex adapters install: session context, edit guards,
+  delegated-agent routing, post-edit and post-bash observers, always-on trace,
+  prompt routing, and stop closeout.
+- **Release-ready install examples.** The first-run and refresh commands now
+  show the split between machine bootstrap, user-level updates, read-only setup
+  audit, and repo-local adoption.
 
 ## What repo-harness Does
 
@@ -81,7 +82,7 @@ The design has three layers:
 
 1. **Source package**: this repository owns the CLI, CLI-backed command facades,
    templates, hook assets, workflow contract, tests, and release gate.
-2. **Target repo contract**: `repo-harness update` or migration writes repo-local
+2. **Target repo contract**: `repo-harness adopt` or migration writes repo-local
    files such as `docs/spec.md`, `plans/`, `tasks/`, `.ai/context/`,
    `.ai/harness/`, helper scripts, and `.ai/hooks/`.
 3. **Host adapters**: user-level `~/.claude/settings.json` and
@@ -225,28 +226,45 @@ user-level hook adapters, configures Waza runtime skills, persists a brain root
 under `~/.repo-harness/config.json`, and configures CodeGraph MCP. It does not
 apply repo-local workflow files to the current directory.
 
-For an Agent-owned, read-only bootstrap audit, run `npx -y repo-harness
-init-hook --json` or add `--check-updates` for version advisories. `init-hook`
-is not a runtime hook: it does not write user-level files, install updates, or
+For an Agent-owned, read-only bootstrap audit, run `npx -y repo-harness setup
+check --json` or add `--check-updates` for version advisories. `setup check` is
+not a runtime hook: it does not write user-level files, install updates, or
 register adapters. It emits `agent_actions` with the reason, risk, target files,
 optional command, and verification surface for the Agent to execute deliberately.
+`repo-harness init-hook` remains a compatibility alias.
+
+### Install and refresh examples
+
+```bash
+# First machine bootstrap: global CLI, skills, host adapters, Waza, brain, CodeGraph.
+npx -y repo-harness init
+
+# Refresh user-level CLI/runtime pieces after a package update.
+repo-harness update
+
+# Ask for read-only repair guidance without writing files.
+repo-harness update --check
+
+# Refresh repo-local workflow files in an adopted repository.
+repo-harness adopt --repo /path/to/repo
+```
 
 ### 2. Preview the repo-local contract
 
 ```bash
-npx -y repo-harness update --dry-run
+npx -y repo-harness adopt --dry-run
 ```
 
 Run the dry run from the target repository root. It reports the specs, task
 state, helper runtime, hook adapter target, and verification files that would be
 created or refreshed. It should not create an application stack; existing repos
-use `repo-harness update`, while new projects or modules use
+use `repo-harness adopt`, while new projects or modules use
 `repo-harness-scaffold`.
 
 ### 3. Apply, then prove the workflow
 
 ```bash
-npx -y repo-harness update
+npx -y repo-harness adopt
 bash scripts/check-task-workflow.sh --strict
 bun test
 ```
@@ -289,17 +307,17 @@ Claude/Codex paths are symlink-backed runtime entrypoints. Only
 For an existing repo, run from the repo root:
 
 ```bash
-npx -y repo-harness update --dry-run
+npx -y repo-harness adopt --dry-run
 ```
 
 Apply only after the dry-run report looks correct:
 
 ```bash
-npx -y repo-harness update
+npx -y repo-harness adopt
 ```
 
 For a new project or module, use the branch command `repo-harness-scaffold`. For
-an existing repo, use `repo-harness update`; it installs or refreshes the harness
+an existing repo, use `repo-harness adopt`; it installs or refreshes the harness
 without creating an application stack.
 
 ### Success looks like this
@@ -325,7 +343,22 @@ before applying anything.
 - Repo-local `.claude/settings.json` and `.codex/hooks.json` hook adapters are legacy project-level config and should be retired during migration.
 - Codex must mark `~/.codex/hooks.json` as trusted in Codex Settings before those hooks run.
 - Debug in this order: user-level adapter config -> `repo-harness-hook` (or fallback `repo-harness hook`) -> route registry -> `.ai/hooks/*`.
-- If `repo-harness-hook` reports `.ai/hooks` drift, refresh the repo-local copy with `repo-harness update --repo <root>`.
+- If `repo-harness-hook` reports `.ai/hooks` drift, refresh the repo-local copy with `repo-harness adopt --repo <root>`.
+
+The installed adapter owns eight managed hook routes. The route tuple
+`event + routeId + matcher` is the stable contract; script names are the current
+implementation under `assets/hooks/` or a repo-pinned `.ai/hooks/` copy.
+
+| Route | Matcher | Scripts | Function |
+| --- | --- | --- | --- |
+| `SessionStart.default` | all sessions | `session-start-context.sh`, `security-sentinel.sh` | Injects prior handoff, sprint status, and read-only config-security findings before work starts. |
+| `PreToolUse.edit` | `Edit|Write` | `worktree-guard.sh`, `pre-edit-guard.sh` | Enforces worktree policy and plan/contract readiness before implementation edits. |
+| `PreToolUse.subagent` | `Task|Agent|SendUserMessage` | `subagent-return-channel-guard.sh` | Keeps delegated work returning through the parent session instead of leaking completion claims. |
+| `PostToolUse.edit` | `Edit|Write` | `post-edit-guard.sh` | Records edit traces, refreshes handoff/task status, and queues architecture drift when controlled files change. |
+| `PostToolUse.bash` | `Bash` | `post-bash.sh` | Observes command results and captures verification evidence without replacing the command runner. |
+| `PostToolUse.always` | all tools | `post-tool-observer.sh` | Provides low-noise always-on trace and runtime observation; stale pinned copies soft-skip with a refresh hint. |
+| `UserPromptSubmit.default` | all prompts | `prompt-guard.sh` | Classifies prompt intent, routes planning/check/hunt hints, and renders host-safe workflow guidance. |
+| `Stop.default` | session stop | `stop-orchestrator.sh` | Finalizes handoff and guards against ending with unresolved draft-plan or completion evidence gaps. |
 
 `SessionStart` resolves hooks central-first, then runs two ordered scripts before
 work begins:
@@ -394,8 +427,8 @@ Most common guards:
 
 ## Current Release
 
-- npm package: `repo-harness@0.4.3`
-- Generated workflow stamp: `repo-harness@0.4.3+template@0.4.3`
+- npm package: `repo-harness@0.5.0`
+- Generated workflow stamp: `repo-harness@0.5.0+template@0.5.0`
 - GitHub repository: `Ancienttwo/repo-harness`
 - Release history: [`docs/CHANGELOG.md`](docs/CHANGELOG.md)
 
@@ -484,7 +517,7 @@ skill discovery compatible while the CLI and hooks own execution:
 - Repo workflow actions: `repo-harness-ship`, `repo-harness-init`, `repo-harness-migrate`, `repo-harness-upgrade`, `repo-harness-capability`, `repo-harness-architecture`, `repo-harness-handoff`, `repo-harness-deploy`, `repo-harness-repair`, `repo-harness-check`
 - Branch project creation command: `repo-harness-scaffold`
 
-`repo-harness update` is for an existing repo; `repo-harness-scaffold` creates a
+`repo-harness adopt` is for an existing repo; `repo-harness-scaffold` creates a
 new project or module scaffold as a side command. `hooks-init`, `docs-init`, and
 `create-project-dirs` are internal steps, not public commands.
 

package/README.zh-CN.md

@@ -32,18 +32,18 @@ repo-local workflow 的自托管样例。
 | `tasks/contracts/`、`tasks/reviews/`、`.ai/harness/checks/` | 证明完成所需的 scope、verification 和 review evidence。 |
 | `.ai/harness/handoff/` 和 `tasks/current.md` | session journal 与可恢复状态，从 workflow artifacts 派生，而不是依赖聊天记忆。 |
 
-## 0.4.3 新特性
-
-- **Runtime docs lookup。** `repo-harness docs list|path|show` 从已安装 package
-  解析 bundled runtime/reference docs，不再要求把完整 repo prose 复制到下游。
-- **Init-hook bootstrap audit。** `repo-harness init-hook --json` 会把缺失的
-  working rules、adapter drift、stale CLI install 和 tooling readiness 汇成
-  具体 Agent actions。
-- **First-principles edit guard。** Managed hook routes 增加实现编辑时的
-  anti-overengineering guidance，同时保持 advisory，不把风格判断变成硬拦截。
-- **更轻的 generated reference docs。** 生成和迁移的仓库写入确定性的
-  `docs/reference-configs/*.md` pointer stubs，`.ai/harness/*` 和 `.ai/context/*`
-  继续作为 repo-local runtime artifacts。
+## 0.5.0 新特性
+
+- **清晰的命令边界。** `repo-harness update` 只负责 user-level CLI/runtime
+  刷新；`repo-harness adopt` 负责 repo-local workflow 安装、刷新和迁移。
+- **Package-dispatched helper runtime。** 生成的 `scripts/*` wrapper 可以通过
+  `repo-harness run <helper>` 委派到已安装 package，不必在每个下游仓库复制完整
+  helper implementation。
+- **8 条 managed hook routes。** README 现在明确记录 Claude/Codex adapter
+  安装的 route matrix：session context、edit guards、delegated-agent routing、
+  post-edit/post-bash observers、always-on trace、prompt routing 和 stop closeout。
+- **发布前安装刷新例子。** First 5 Minutes 明确区分 machine bootstrap、
+  user-level update、read-only setup audit 和 repo-local adoption。
 
 ## 产品做什么
 
@@ -66,7 +66,7 @@ repo-local hooks，然后验证这些 workflow surfaces 仍然一致。
 
 1. **源码包层**：本仓库维护 CLI、CLI-backed command facades、templates、hook assets、
    workflow contract、tests 和 release gate。
-2. **目标仓库合约层**：`repo-harness update` 或 migration 会写入 `docs/spec.md`、
+2. **目标仓库合约层**：`repo-harness adopt` 或 migration 会写入 `docs/spec.md`、
    `plans/`、`tasks/`、`.ai/context/`、`.ai/harness/`、helper scripts 和
    `.ai/hooks/`。
 3. **Host adapter 层**：user-level `~/.claude/settings.json` 和 `~/.codex/hooks.json`
@@ -189,25 +189,42 @@ skill aliases，安装 user-level hook adapters，配置 Waza runtime skills，
 root 持久化到 `~/.repo-harness/config.json`，并配置 CodeGraph MCP。它不会把当前目录
 默认迁移成 repo-local workflow。
 
-如果要让 Agent 做只读 bootstrap audit，运行 `npx -y repo-harness init-hook
---json`；需要版本提示时加 `--check-updates`。`init-hook` 不是 runtime hook：
+如果要让 Agent 做只读 bootstrap audit，运行 `npx -y repo-harness setup check
+--json`；需要版本提示时加 `--check-updates`。`setup check` 不是 runtime hook：
 它不会写 user-level files、安装更新或注册 adapters，只输出带 reason、risk、
 targets、可选 command 和 verification 的 `agent_actions`，由 Agent 再显式执行。
+`repo-harness init-hook` 保留为兼容 alias。
+
+### 安装和刷新例子
+
+```bash
+# 首次机器级 bootstrap：global CLI、skills、host adapters、Waza、brain、CodeGraph。
+npx -y repo-harness init
+
+# 包更新后刷新 user-level CLI/runtime。
+repo-harness update
+
+# 只读检查需要 agent 修复什么，不写文件。
+repo-harness update --check
+
+# 刷新已接入仓库里的 repo-local workflow 文件。
+repo-harness adopt --repo /path/to/repo
+```
 
 ### 2. 预览 repo-local contract
 
 ```bash
-npx -y repo-harness update --dry-run
+npx -y repo-harness adopt --dry-run
 ```
 
 在目标仓库根目录运行 dry-run。它会报告将要创建或刷新的 spec、task state、
 helper runtime、hook adapter target 和 verification files。它不会创建应用技术栈；
-已有仓库走 `repo-harness update`，新项目或新模块走 `repo-harness-scaffold`。
+已有仓库走 `repo-harness adopt`，新项目或新模块走 `repo-harness-scaffold`。
 
 ### 3. 应用后验证 workflow
 
 ```bash
-npx -y repo-harness update
+npx -y repo-harness adopt
 bash scripts/check-task-workflow.sh --strict
 bun test
 ```
@@ -247,17 +264,17 @@ symlink-backed runtime entrypoints。退休的 `repo-harness-skill` 与
 已有仓库从 repo root 执行：
 
 ```bash
-npx -y repo-harness update --dry-run
+npx -y repo-harness adopt --dry-run
 ```
 
 dry-run 报告正确后再应用：
 
 ```bash
-npx -y repo-harness update
+npx -y repo-harness adopt
 ```
 
 新项目或新模块使用支线 command `repo-harness-scaffold`。已有仓库使用
-`repo-harness update`；它会安装或刷新 harness，不会创建应用技术栈。
+`repo-harness adopt`；它会安装或刷新 harness，不会创建应用技术栈。
 
 ### 成功长什么样
 
@@ -343,8 +360,8 @@ hook block 工作时，先看 terminal 里的结构化输出。核心字段是
 
 ## 当前 Release
 
-- npm package：`repo-harness@0.4.3`
-- Generated workflow stamp：`repo-harness@0.4.3+template@0.4.3`
+- npm package：`repo-harness@0.5.0`
+- Generated workflow stamp：`repo-harness@0.5.0+template@0.5.0`
 - GitHub repository：`Ancienttwo/repo-harness`
 - Release history：[`docs/CHANGELOG.md`](docs/CHANGELOG.md)
 
@@ -401,7 +418,7 @@ Co-authored-by: codex <codex@openai.com>
 - Repo workflow actions：`repo-harness-ship`、`repo-harness-init`、`repo-harness-migrate`、`repo-harness-upgrade`、`repo-harness-capability`、`repo-harness-architecture`、`repo-harness-handoff`、`repo-harness-deploy`、`repo-harness-repair`、`repo-harness-check`
 - 支线项目创建 command：`repo-harness-scaffold`
 
-`repo-harness update` 用于已有仓库；`repo-harness-scaffold` 作为支线 command 创建新项目或模块。
+`repo-harness adopt` 用于已有仓库；`repo-harness-scaffold` 作为支线 command 创建新项目或模块。
 `hooks-init`、`docs-init` 和 `create-project-dirs` 是内部步骤，不是公共 commands。
 
 `repo-harness-scaffold` 保持 A-K plan catalog 作为项目类型 authority；AI-native

package/assets/reference-configs/AGENTS.md

@@ -0,0 +1,13 @@
+# Functional Block Agent Context
+
+Keep this file focused on the local contract for this primary functional block.
+
+## Local Context Contract
+
+- Describe only the ownership, boundaries, stable entrypoints, and local verification commands for this functional block.
+- Keep sibling `CLAUDE.md` and `AGENTS.md` files aligned. Claude Code consumes `CLAUDE.md`; Codex consumes `AGENTS.md`.
+- Record the local LSP/tooling profile here when it differs from the repo default.
+- Route deep implementation detail into nearby docs instead of inflating root agent context files.
+- Treat `.ai/context/context-map.json` as the index of discoverable context files.
+- Do not keep pushing context files deeper by default; add lower-level files only for a separately owned functional block with its own commands and invariants.
+- Prefer repo-local workflow artifacts over tool-specific chat memory.

package/assets/reference-configs/CLAUDE.md

@@ -0,0 +1,13 @@
+# Functional Block Agent Context
+
+Keep this file focused on the local contract for this primary functional block.
+
+## Local Context Contract
+
+- Describe only the ownership, boundaries, stable entrypoints, and local verification commands for this functional block.
+- Keep sibling `CLAUDE.md` and `AGENTS.md` files aligned. Claude Code consumes `CLAUDE.md`; Codex consumes `AGENTS.md`.
+- Record the local LSP/tooling profile here when it differs from the repo default.
+- Route deep implementation detail into nearby docs instead of inflating root agent context files.
+- Treat `.ai/context/context-map.json` as the index of discoverable context files.
+- Do not keep pushing context files deeper by default; add lower-level files only for a separately owned functional block with its own commands and invariants.
+- Prefer repo-local workflow artifacts over tool-specific chat memory.

package/assets/reference-configs/external-tooling.md

@@ -20,11 +20,18 @@ Codex/Claude hook adapters, Waza (`think`, `hunt`, `check`, `health`), brain
 root persistence, Mermaid, and CodeGraph CLI/MCP configuration. It must not
 silently install unrelated toolchains or Claude marketplace plugins.
 
+`repo-harness update` refreshes only the CLI and repo-harness-owned user-level
+runtime by default. Third-party tooling and CodeGraph registration stay
+readiness findings from `repo-harness setup check` unless the update command is
+run with an explicit opt-in such as `--with-external-skills` or
+`--configure-codegraph`.
+
 The cross-review skills are **harness-owned and self-contained** — their source
 lives in `assets/skills/<skill>/` and they wrap the peer CLI (`codex exec` /
 `claude -p`) in a read-only sandbox with no gstack dependency, so installing them
-is a workflow-owned repo-local update concern, not an unrelated toolchain. They
-install host-aware during `repo-harness update`: `codex-review` only into `~/.claude/skills` (a Claude session asking
+is a workflow-owned runtime concern, not an unrelated toolchain. They install
+host-aware during `repo-harness init` and explicit external-skill refreshes:
+`codex-review` only into `~/.claude/skills` (a Claude session asking
 Codex for an independent review) and `claude-review` only into `~/.codex/skills`
 (a Codex session asking Claude). When gstack is present, its `/codex` and
 `gstack-claude` skills are a more featureful superset; the harness skills are the

package/assets/reference-configs/harness-overview.md

@@ -4,7 +4,7 @@ This repo uses a shared long-running harness. The durable workflow lives in repo
 
 ## Adoption Model
 
-Use this file as the first onboarding map after `repo-harness update` installs
+Use this file as the first onboarding map after `repo-harness adopt` installs
 or refreshes a repo. The harness gives agents three durable surfaces:
 
 - **Shared standards**: `docs/spec.md`, `docs/reference-configs/`, root

package/assets/reference-configs/hook-operations.md

@@ -14,7 +14,7 @@ Start with the shortest truth path:
 Central-first means one `install` (or one CLI upgrade) updates hook behavior for every trusted opt-in repo at once; vendored `.ai/hooks` copies are inert defaults unless the repo pins `"hook_source": "repo"`. Missing advisory scripts warn and skip, but required guard routes still fail closed. `repo-harness doctor` and `scripts/repo-harness.sh status` report which source is active for the current repo.
 Generated host adapter commands carry a 30 second timeout; long-running work belongs in explicit CLI commands, not hook foreground execution.
 
-`repo-harness update`, migration, and new-project scaffold paths do not copy the full hook runtime into ordinary downstream repos. Without a `"hook_source": "repo"` pin they prune stale top-level `.ai/hooks/*.sh` entry scripts and refresh only `.ai/hooks/lib/` helper libraries plus a README tombstone, because active execution should come from the user-level adapter and packaged hooks. Repos that intentionally develop or override hooks must set `"hook_source": "repo"` before syncing a full vendored hook runtime.
+`repo-harness adopt`, migration, and new-project scaffold paths do not copy the full hook runtime into ordinary downstream repos. Without a `"hook_source": "repo"` pin they prune stale top-level `.ai/hooks/*.sh` entry scripts and refresh only `.ai/hooks/lib/` helper libraries plus a README tombstone, because active execution should come from the user-level adapter and packaged hooks. Repos that intentionally develop or override hooks must set `"hook_source": "repo"` before syncing a full vendored hook runtime.
 
 `UserPromptSubmit.default` dispatches to the active `prompt-guard.sh` resolved by the central-first hook source decision. For ordinary repos that means the packaged/user-level runtime; `.ai/hooks/prompt-guard.sh` is active only when the repo pins `"hook_source": "repo"`. The shell layer parses host prompt JSON, reads workflow files, performs capture side effects, and renders host-safe output; it pipes `{"prompt": ...}` into `repo-harness-hook prompt-guard-decide`, which owns every prompt-text intent classifier (Unicode-aware, in `src/cli/hook/prompt-intents.ts`) plus the intent x state decision table and returns one verdict JSON line (action, intent facts, derived strings). If the engine is unreachable or predates the protocol, the prompt layer degrades to a one-shot advisory instead of guessing; there is no shell fallback decision table.
 

package/assets/skill-commands/repo-harness-init/SKILL.md

@@ -11,18 +11,18 @@ Use this command for an existing repository that needs the repo-local agentic wo
 ## Protocol
 
 1. Confirm the target repo path.
-2. If running from the target repo root, use `repo-harness update`; do not require `--repo .`.
+2. If running from the target repo root, use `repo-harness adopt`; do not require `--repo .`.
 3. Run `bun scripts/inspect-project-state.ts --repo <repo> --format text`.
 4. If the repo is legacy, route to `repo-harness-migrate`.
-5. Otherwise run the safe path through `repo-harness update` or `bash scripts/migrate-project-template.sh --repo <repo> --apply`.
-6. Bootstrap the expected host runtime dependencies in the same pass: Waza (`think`, `hunt`, `check`, `health`) and the bundled cross-review skills when source copies are available.
+5. Otherwise run the safe path through `repo-harness adopt` or `bash scripts/migrate-project-template.sh --repo <repo> --apply`.
+6. If user-level runtime dependencies are missing, run `repo-harness update` separately; repo adoption must not write HOME.
 7. Verify with `bash .ai/harness/scripts/check-task-workflow.sh --strict` inside the target repo when the helper exists.
 
 ## Failure Modes
 
 - If the repo has legacy workflow docs, route to `repo-harness-migrate`.
 - If the user asks for a new product skeleton, route to `repo-harness-scaffold`.
-- If global runtime setup fails, report the exact target and rerun the focused install command.
+- If global runtime setup is missing, report the exact target and rerun the focused `repo-harness update` command.
 
 ## Boundaries