repo-harness 0.4.2 → 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.2`
-- Generated workflow stamp: `repo-harness@0.4.2+template@0.4.2`
+- 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.2`
-- Generated workflow stamp : `repo-harness@0.4.2+template@0.4.2`
+- 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.2`
-- Generated workflow stamp：`repo-harness@0.4.2+template@0.4.2`
+- 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
@@ -34,20 +34,30 @@ This repository now dogfoods its own tasks-first contract. It is both:
   read a 1KB capability contract or query the index instead of spending thousands of
   tokens rediscovering structure.
 
-## What's New in 0.4.2
-
-- **PRD-to-Sprint planning hierarchy.** `repo-harness-prd` now owns
-  upper-layer product requirements under `plans/prds/`, while
-  `repo-harness-sprint` derives ordered execution backlogs under
-  `plans/sprints/*.sprint.md`.
-- **Generated helper runtime isolation.** Downstream installs place real helper
-  implementations under `.ai/harness/scripts/` and keep root `scripts/*` as
-  compatibility wrappers; this self-host repo remains the source runtime.
-- **Subagent return-channel guard.** Managed hook routes include a guard that
-  keeps delegated runs reporting back through the parent session instead of
-  bypassing the file-backed contract.
-- **Release path alignment.** PRD/Sprint eval fixtures, workflow checks, and
-  command guidance now point at the same installed helper runtime.
+In an adopted repo, the surface area is intentionally small:
+
+| Surface | Purpose |
+| --- | --- |
+| `docs/spec.md` and `docs/reference-configs/` | Shared standards and stable product intent that every agent session can read. |
+| `plans/`, `plans/prds/`, and `plans/sprints/` | Decision-complete work packages before implementation starts. |
+| `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.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
 
@@ -72,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
@@ -200,9 +210,11 @@ concrete sprint instead of reinterpreting the original chat.
 ## First 5 Minutes
 
 This is the fastest path for an AI tooling owner evaluating whether the workflow is
-safe to adopt in a real repo.
+safe to adopt in a real repo. It separates the machine-level runtime bootstrap
+from the repo-local contract install, so a dry run can show exactly what will
+change before anything is applied.
 
-### Initial bootstrap
+### 1. Bootstrap the host runtime once
 
 ```bash
 npx -y repo-harness init
@@ -214,27 +226,53 @@ 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.
 
-### Install or refresh a repo-local harness
+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 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 adopt`, while new projects or modules use
+`repo-harness-scaffold`.
+
+### 3. Apply, then prove the workflow
 
 ```bash
-npx -y repo-harness update --dry-run
-npx -y repo-harness update
+npx -y repo-harness adopt
+bash scripts/check-task-workflow.sh --strict
+bun test
 ```
 
-`update` is the existing-repo install and refresh path. Run it from a target
-repository to install or refresh workflow files, hook assets, host adapters,
-skill aliases, and repo-local verification surfaces from the current npm package.
-
-The npm package and generated workflow stamp now share the `0.4.x` release line.
-The `0.4.2` package keeps first-run
-global bootstrap (`repo-harness init`) separate from repo-local refresh
-(`repo-harness update`) while adding the PRD-to-Sprint planning hierarchy,
-isolated generated-project helper runtime, subagent return-channel guard, and
-release-path alignment on top of the `0.4.0` loop-engine surfaces.
-These sit on top of the renamed `repo-harness` CLI, user-level hook
-adapter bootstrap, AI-native scaffold overlays, the typed prompt-guard decision
-engine, plan-stem task artifact naming, `REPO_HARNESS_*` runtime aliases, Waza
-runtime skill sync, and the maintainer release gate.
+After apply, the repo should have a reviewable file-backed contract rather than
+tool-specific chat setup. Agents should be able to find the stable intent in
+`docs/spec.md`, execution state in `plans/` and `tasks/`, and resume state in
+`.ai/harness/handoff/`.
 
 Only maintainers editing the package need a source checkout:
 
@@ -269,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
@@ -293,13 +331,6 @@ The command should end with `=== Migration Report ===` and summarize:
 - `Helper runtime:` to show `.ai/harness/scripts/*` implementations and `scripts/*` compatibility wrappers after apply
 - `--- External Tooling ---` to show default gstack/Waza/gbrain routing plus advisory install/update hints
 
-### Next two commands
-
-```bash
-bash scripts/check-task-workflow.sh --strict
-bun test
-```
-
 If the dry-run output looks wrong, stop there and inspect
 [`docs/reference-configs/hook-operations.md`](docs/reference-configs/hook-operations.md)
 before applying anything.
@@ -312,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:
@@ -381,8 +427,8 @@ Most common guards:
 
 ## Current Release
 
-- npm package: `repo-harness@0.4.2`
-- Generated workflow stamp: `repo-harness@0.4.2+template@0.4.2`
+- 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)
 
@@ -471,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.
 
@@ -527,6 +573,22 @@ bun scripts/inspect-project-state.ts --repo . --format text
 bash scripts/migrate-project-template.sh --repo . --dry-run
 ```
 
+### Runtime reference docs
+
+Generic repo-harness runtime/reference docs live in the installed package under
+`assets/reference-configs/` and are resolved through the CLI:
+
+```bash
+repo-harness docs list
+repo-harness docs path harness-overview
+repo-harness docs show harness-overview
+```
+
+Generated and migrated repos still keep `docs/reference-configs/*.md`, but
+those files are deterministic pointer stubs. Repo-local workflow state,
+policy, checks, runs, handoff packets, context maps, and helper snapshots stay
+under `.ai/`.
+
 ### Explicit template assembly
 
 ```bash
@@ -556,8 +618,9 @@ bun run benchmark:skills --eval repair-agents-task-sync
 - Plan mapping: `assets/plan-map.json`
 - Question-pack: `assets/initializer-question-pack.v4.json`
 - Shared hooks: `assets/hooks/`
+- Runtime reference docs: `assets/reference-configs/` via `repo-harness docs`
 - Workflow contract: `assets/workflow-contract.v1.json`
-- Hook operations reference: `docs/reference-configs/hook-operations.md`
+- Source repo reference docs: `docs/reference-configs/*.md`
 - Template assembler: `scripts/assemble-template.ts`
 - Question inference helper: `scripts/initializer-question-pack.ts`
 - State inspector: `scripts/inspect-project-state.ts`