repo-harness 0.22.1 → 0.23.0

package/AGENTS.md

@@ -4,23 +4,34 @@
 - For non-trivial work, follow the global Progressive Due Diligence rule (P1 map, P2 trace, P3 decision) before design decisions or code edits.
 - Keep root CLAUDE.md and AGENTS.md as standalone regular files; repeat shared rules in both and keep host-specific guidance separate.
 - Read the current request and repo-local agent context, work on a branch, make bounded commits, verify once, then report the PR outcome.
+- Read `tasks/lessons.md` at session start and apply its active lessons. Current repo state and evidence override a lesson.
+- Finish the main task first. Fix a small problem found on the way directly. For a large problem, open a GitHub issue before you work on it.
 - Write output text (docs, PR descriptions, commit messages, reports) in ASD-STE100 Simplified Technical English: short sentences, one idea per sentence, active voice, approved-dictionary words; write Chinese output the same way, with short sentences and one idea per sentence.
 - Ordinary tasks use the PR description: goal, scope, changes, verification, risk and rollback. No mandatory plan/contract/review/notes chain; notes are only for non-obvious decisions.
 - Keep four hard boundaries: main publication, deletion, credentials/permissions, and release/production operations.
 - Only when the current task explicitly authorizes main publication may a model squash-merge after automated checks pass and GitHub has no outstanding change requests or unresolved review threads; an explicit no-merge instruction always wins. Push/tag still require task authorization; credentials/permissions, other deletion and release/production retain their separate approval boundaries. Record authorized publication, the provider-confirmed merge SHA and parent SHA, `git revert <squash-commit>`, and the daily report. Do not create rollback tags.
-- Default task worktrees use `/tmp/<repo>-wt-<slug>` on POSIX. Native Windows uses `os.tmpdir()` as the root. Stored downstream templates stay unchanged. Commit or push work before a reboot or age-based tmp cleanup, such as `systemd-tmpfiles`. These cleaners can remove checkouts. Missing entries are pruned. The sweep saves missing registration identities before global prune. Later batches finish deferred branch cleanup. Unmerged branches remain.
-- Closeout removes a merged, clean checkout and its branch. It releases only that checkout's own canonical marker after merge proof under the topology lock. The sweep keeps dirty, locked, marked or leased worktrees. It keeps branch reflogs without a commit-creation message and missing or unreadable reflogs. Fast-forward, target-only automatic merges, reset and rebase-finish messages do not count. Dispatch must establish an unmerged commit or keep the worktree dirty, marked or leased. A merged, clean, unowned branch with its own commits can be swept.
-- `start` recovers only a real target directory registered by this clone on the expected branch, under the topology lock, with no lock or other owner. Recovery requires a current-user-owned checkout directory without group or other write access, a regular owned Git pointer, its matching admin backpointer, and the original directory identity saved by start. Git metadata can be group-writable but must not be other-writable. Start still creates a checkout when uid is unavailable; recovery then refuses. Exact removal retires the identity after Git readback. Missing identity or a replacement directory blocks recovery. Files, symlinks, unregistered paths and other branches are refused. Cleanup refuses a registered worktree whose branch is missing. MCP cleanup also refuses active markers and retained native verification evidence. Sweep reports name processed paths. Deferred entries are reported as counts. `kept` excludes deferred entries. A command timeout sends SIGTERM to the direct child only. A grandchild can briefly extend the deadline. No detached cleanup process starts. Herdr notifications accept registered default task worktrees and paths inside them. Other temporary paths and `rh-herdr-` labels stay filtered.
+- Default worktrees are at `/tmp/<repo>-wt-<slug>` (Windows: `os.tmpdir()`). Commit or push before a reboot or a tmp cleanup.
+- Closeout and sweep remove only merged, clean and unowned worktrees. To keep one, give it an unmerged commit, keep it dirty, or mark or lease it. Details: [agentic-development-flow](docs/reference-configs/agentic-development-flow.md).
 - Automatically delete only merged, clean worktrees/branches; ask the user for every other deletion. Credentials/permissions (including confirmation bypass) and release/production operations require user approval.
 - Use gatekeeper/cross-model review for large changes, security/permissions, or unresolved model uncertainty; ordinary steps record diagnostics without approval loops.
 - When you delegate, investigate first, then split work by write ownership. Give each parallel writer its own worktree from a clean source. Implementation sub-agents edit only their scope. They do not run build, typecheck or tests. They commit early in their own worktree and return early. In a shared checkout they do not commit; the parent commits. Evidence roles run the named check that is their task and do not commit. The parent agent owns task management, conflict resolution, build, typecheck, tests and integration. After integration, the parent removes each sub-agent worktree and branch whose commits are in the task branch and whose checkout is clean. It also removes the intermediate build output and temporary files that the work created. Other deletion still needs the user.
-- Model division and cross-model dispatch/review follow [Herdr Dispatch](docs/reference-configs/external-tooling.md#herdr-dispatch).
+- Model division and cross-model dispatch/review follow [Herdr Dispatch](docs/reference-configs/herdr-notify.md#herdr-dispatch).
 - GitHub operations (PRs, reviews, merges, labels, releases, comments) go only through the gh/git CLI or the GitHub API. Never use simulated browser clicks on github.com: the account can be banned.
 - When one PR changes both test assertions and implementation code, run one read-only review focused on tests bent to fit a bug (on-demand, not a restored gate; dispatch per the herdr guide).
 - `.archcontext/model/` owns architecture boundaries; read `docs/architecture/` on demand and update only real responsibility changes. Architecture diagnostics do not block work or author nested agent instructions.
+- When a branch changes a capability's responsibility, entrypoints, relations or flows, run `repo-harness architecture-projection check --json` before review and follow `repo-harness-architecture` (`assets/skill-commands/repo-harness-architecture/references/worker.md`).
 - Preserve `agents/fleet/`, release checklists and downstream `assets/templates` / `assets/partials*`. `.ai/harness/workflow-contract.json` is the opt-in marker. `assets/workflow-contract.v1.json` is the contract.
 - `_ops/` is ignored private operations state: never commit or agent-edit it. `_ref/` is an ignored reference cache; cite influential revisions. Follow deploy SQL policy, otherwise use ascending 4-digit files under `deploy/sql/`.
 
+## GitHub Issue Claims
+- Before an agent starts work on a GitHub issue, read its current state, assignees and all comments through `gh` or the GitHub API. Use pagination for comments. Check existing work claims, linked PRs and handoff notes.
+- An active claim is an assignee other than the current task owner, an open PR that links the issue, or an active claim comment that no later status comment released. If another agent or person has an active claim, do not start duplicate work. Coordinate with that owner within the authorized task scope. Take over only after an explicit handoff or user instruction. Silence, an old timestamp or a disconnected session does not release a claim.
+- When taking an unclaimed issue or an approved handoff, post a claim comment before edits, tests or worker dispatch. Use `gh issue comment <issue-url> --body-file <file>`. This rule authorizes claim and status comments for an issue within the user's task scope. It grants no other GitHub write authority.
+- Start the comment with `repo-harness issue claim`. Include `Status: active`, the agent kind and unique session or task ID, the branch, the work scope and any prior claim comment URL for a handoff. Use this identity in later status comments. A shared GitHub login is not an agent identity. Do not include secrets or private host paths.
+- Read the issue comments again after posting. Confirm the published comment URL and body. If a competing claim appeared, stop duplicate work and resolve ownership before continuing. For simultaneous claims without an explicit assignment or handoff, the earliest GitHub comment wins; break timestamp ties by comment ID. These comments coordinate agents; they are not an atomic lock and do not replace canonical task claims or leases.
+- On resume, check the current claim before continuing. Reuse the same active claim instead of posting it again. If a read or post fails, or delivery is uncertain, stop and report the failure. Read back before retrying an uncertain post.
+- Post a status comment that links the claim when the work is blocked, ready for review, complete or released. Keep a blocked or review-pending claim active. Include the PR or result when available. Release ownership explicitly on cancellation or handoff. Do not close the issue unless the task authorizes closure.
+
 ## Code Optimization Principles
 - Identify observable conditions, controllable inputs, the invariant and the actual pressure point before changing structure.
 - Keep one source of truth for each datum; other representations are deterministic projections with drift checks.
@@ -31,10 +42,12 @@
 - Self-review before committing: remove dead code, empty branches and debug leftovers, and split functions by responsibility instead of one large block.
 
 ## Testing
-- Run `bun run check:type` plus tests covering the changed behavior once after the implementation is stable.
+- Run `bun run check:type` for code changes and tests covering the changed behavior once after the implementation is stable. Development-time debugging can run focused checks before that final verification.
+- For a bug fix, prefer a focused failing regression before the fix. Run only the reproducer during RED. Record a reproduction gap when the environment cannot produce it; ordinary tasks do not require RED artifacts.
+- A diff's size, a new test file, a new agent or a rebase does not by itself require a full run.
 - Use `bun run test:files <affected tests> --timeout 60000 --max-concurrency 1`; extend existing coverage before creating a new test file.
 - Select tests by observable risk and owning runtime boundary, including error/recovery paths when affected.
-- Mechanical prose changes need link/scope validation, not new product tests; do not test incidental formatting.
+- Mechanical prose changes need link/scope validation, not new product tests; do not test incidental formatting or that deleted files stay deleted.
 - Reviewers consume the recorded command, result, revision and environment; they do not rerun passing checks to claim ownership.
 - Changed inputs or a new uncovered failure justify affected delta checks; an old pass is only historical evidence for its old subject.
 - Run the full suite daily; a failure opens an automatic repair task and appears in the daily report.
@@ -54,7 +67,7 @@
 
 ## Codex
 - Own backend implementation and testing; Claude owns frontend implementation and interaction, and the parent coordinates scope and integration.
-- User-level `~/.codex/hooks.json` hooks invoke `repo-harness-hook`; its typed route registry selects one in-process handler. Repo-local hook adapters are retired. Operator helpers use the package path from `repo-harness hook-lib path`. This source repo keeps `.ai/hooks/lib/workflow-state.sh` for self-hosting.
+- User-level `~/.codex/hooks.json` hooks invoke `repo-harness-hook`; its typed route registry selects one in-process handler. Operator helpers run from the package through `repo-harness run <helper>`.
 - Use `~/.codex/skills` as the runtime skill source; `~/.agents/skills` is staging/cache only. Keep `think`, `hunt`, `check` and `health` updates verified before runtime use.
 - The Codex automation profile requires runtime-provided `health`, `check` and `mermaid`; do not vendor their bodies.
 - Treat auto-compact as a fallback; prepare ignored `.ai/harness/handoff/current.md` and `resume.md` when long-task rollover is needed.

package/CLAUDE.md

@@ -4,23 +4,34 @@
 - For non-trivial work, follow the global Progressive Due Diligence rule (P1 map, P2 trace, P3 decision) before design decisions or code edits.
 - Keep root CLAUDE.md and AGENTS.md as standalone regular files; repeat shared rules in both and keep host-specific guidance separate.
 - Read the current request and repo-local agent context, work on a branch, make bounded commits, verify once, then report the PR outcome.
+- Read `tasks/lessons.md` at session start and apply its active lessons. Current repo state and evidence override a lesson.
+- Finish the main task first. Fix a small problem found on the way directly. For a large problem, open a GitHub issue before you work on it.
 - Write output text (docs, PR descriptions, commit messages, reports) in ASD-STE100 Simplified Technical English: short sentences, one idea per sentence, active voice, approved-dictionary words; write Chinese output the same way, with short sentences and one idea per sentence.
 - Ordinary tasks use the PR description: goal, scope, changes, verification, risk and rollback. No mandatory plan/contract/review/notes chain; notes are only for non-obvious decisions.
 - Keep four hard boundaries: main publication, deletion, credentials/permissions, and release/production operations.
 - Only when the current task explicitly authorizes main publication may a model squash-merge after automated checks pass and GitHub has no outstanding change requests or unresolved review threads; an explicit no-merge instruction always wins. Push/tag still require task authorization; credentials/permissions, other deletion and release/production retain their separate approval boundaries. Record authorized publication, the provider-confirmed merge SHA and parent SHA, `git revert <squash-commit>`, and the daily report. Do not create rollback tags.
-- Default task worktrees use `/tmp/<repo>-wt-<slug>` on POSIX. Native Windows uses `os.tmpdir()` as the root. Stored downstream templates stay unchanged. Commit or push work before a reboot or age-based tmp cleanup, such as `systemd-tmpfiles`. These cleaners can remove checkouts. Missing entries are pruned. The sweep saves missing registration identities before global prune. Later batches finish deferred branch cleanup. Unmerged branches remain.
-- Closeout removes a merged, clean checkout and its branch. It releases only that checkout's own canonical marker after merge proof under the topology lock. The sweep keeps dirty, locked, marked or leased worktrees. It keeps branch reflogs without a commit-creation message and missing or unreadable reflogs. Fast-forward, target-only automatic merges, reset and rebase-finish messages do not count. Dispatch must establish an unmerged commit or keep the worktree dirty, marked or leased. A merged, clean, unowned branch with its own commits can be swept.
-- `start` recovers only a real target directory registered by this clone on the expected branch, under the topology lock, with no lock or other owner. Recovery requires a current-user-owned checkout directory without group or other write access, a regular owned Git pointer, its matching admin backpointer, and the original directory identity saved by start. Git metadata can be group-writable but must not be other-writable. Start still creates a checkout when uid is unavailable; recovery then refuses. Exact removal retires the identity after Git readback. Missing identity or a replacement directory blocks recovery. Files, symlinks, unregistered paths and other branches are refused. Cleanup refuses a registered worktree whose branch is missing. MCP cleanup also refuses active markers and retained native verification evidence. Sweep reports name processed paths. Deferred entries are reported as counts. `kept` excludes deferred entries. A command timeout sends SIGTERM to the direct child only. A grandchild can briefly extend the deadline. No detached cleanup process starts. Herdr notifications accept registered default task worktrees and paths inside them. Other temporary paths and `rh-herdr-` labels stay filtered.
+- Default worktrees are at `/tmp/<repo>-wt-<slug>` (Windows: `os.tmpdir()`). Commit or push before a reboot or a tmp cleanup.
+- Closeout and sweep remove only merged, clean and unowned worktrees. To keep one, give it an unmerged commit, keep it dirty, or mark or lease it. Details: [agentic-development-flow](docs/reference-configs/agentic-development-flow.md).
 - Automatically delete only merged, clean worktrees/branches; ask the user for every other deletion. Credentials/permissions (including confirmation bypass) and release/production operations require user approval.
 - Use gatekeeper/cross-model review for large changes, security/permissions, or unresolved model uncertainty; ordinary steps record diagnostics without approval loops.
 - When you delegate, investigate first, then split work by write ownership. Give each parallel writer its own worktree from a clean source. Implementation sub-agents edit only their scope. They do not run build, typecheck or tests. They commit early in their own worktree and return early. In a shared checkout they do not commit; the parent commits. Evidence roles run the named check that is their task and do not commit. The parent agent owns task management, conflict resolution, build, typecheck, tests and integration. After integration, the parent removes each sub-agent worktree and branch whose commits are in the task branch and whose checkout is clean. It also removes the intermediate build output and temporary files that the work created. Other deletion still needs the user.
-- Model division and cross-model dispatch/review follow [Herdr Dispatch](docs/reference-configs/external-tooling.md#herdr-dispatch).
+- Model division and cross-model dispatch/review follow [Herdr Dispatch](docs/reference-configs/herdr-notify.md#herdr-dispatch).
 - GitHub operations (PRs, reviews, merges, labels, releases, comments) go only through the gh/git CLI or the GitHub API. Never use simulated browser clicks on github.com: the account can be banned.
 - When one PR changes both test assertions and implementation code, run one read-only review focused on tests bent to fit a bug (on-demand, not a restored gate; dispatch per the herdr guide).
 - `.archcontext/model/` owns architecture boundaries; read `docs/architecture/` on demand and update only real responsibility changes. Architecture diagnostics do not block work or author nested agent instructions.
+- When a branch changes a capability's responsibility, entrypoints, relations or flows, run `repo-harness architecture-projection check --json` before review and follow `repo-harness-architecture` (`assets/skill-commands/repo-harness-architecture/references/worker.md`).
 - Preserve `agents/fleet/`, release checklists and downstream `assets/templates` / `assets/partials*`. `.ai/harness/workflow-contract.json` is the opt-in marker. `assets/workflow-contract.v1.json` is the contract.
 - `_ops/` is ignored private operations state: never commit or agent-edit it. `_ref/` is an ignored reference cache; cite influential revisions. Follow deploy SQL policy, otherwise use ascending 4-digit files under `deploy/sql/`.
 
+## GitHub Issue Claims
+- Before an agent starts work on a GitHub issue, read its current state, assignees and all comments through `gh` or the GitHub API. Use pagination for comments. Check existing work claims, linked PRs and handoff notes.
+- An active claim is an assignee other than the current task owner, an open PR that links the issue, or an active claim comment that no later status comment released. If another agent or person has an active claim, do not start duplicate work. Coordinate with that owner within the authorized task scope. Take over only after an explicit handoff or user instruction. Silence, an old timestamp or a disconnected session does not release a claim.
+- When taking an unclaimed issue or an approved handoff, post a claim comment before edits, tests or worker dispatch. Use `gh issue comment <issue-url> --body-file <file>`. This rule authorizes claim and status comments for an issue within the user's task scope. It grants no other GitHub write authority.
+- Start the comment with `repo-harness issue claim`. Include `Status: active`, the agent kind and unique session or task ID, the branch, the work scope and any prior claim comment URL for a handoff. Use this identity in later status comments. A shared GitHub login is not an agent identity. Do not include secrets or private host paths.
+- Read the issue comments again after posting. Confirm the published comment URL and body. If a competing claim appeared, stop duplicate work and resolve ownership before continuing. For simultaneous claims without an explicit assignment or handoff, the earliest GitHub comment wins; break timestamp ties by comment ID. These comments coordinate agents; they are not an atomic lock and do not replace canonical task claims or leases.
+- On resume, check the current claim before continuing. Reuse the same active claim instead of posting it again. If a read or post fails, or delivery is uncertain, stop and report the failure. Read back before retrying an uncertain post.
+- Post a status comment that links the claim when the work is blocked, ready for review, complete or released. Keep a blocked or review-pending claim active. Include the PR or result when available. Release ownership explicitly on cancellation or handoff. Do not close the issue unless the task authorizes closure.
+
 ## Code Optimization Principles
 - Identify observable conditions, controllable inputs, the invariant and the actual pressure point before changing structure.
 - Keep one source of truth for each datum; other representations are deterministic projections with drift checks.
@@ -31,10 +42,12 @@
 - Self-review before committing: remove dead code, empty branches and debug leftovers, and split functions by responsibility instead of one large block.
 
 ## Testing
-- Run `bun run check:type` plus tests covering the changed behavior once after the implementation is stable.
+- Run `bun run check:type` for code changes and tests covering the changed behavior once after the implementation is stable. Development-time debugging can run focused checks before that final verification.
+- For a bug fix, prefer a focused failing regression before the fix. Run only the reproducer during RED. Record a reproduction gap when the environment cannot produce it; ordinary tasks do not require RED artifacts.
+- A diff's size, a new test file, a new agent or a rebase does not by itself require a full run.
 - Use `bun run test:files <affected tests> --timeout 60000 --max-concurrency 1`; extend existing coverage before creating a new test file.
 - Select tests by observable risk and owning runtime boundary, including error/recovery paths when affected.
-- Mechanical prose changes need link/scope validation, not new product tests; do not test incidental formatting.
+- Mechanical prose changes need link/scope validation, not new product tests; do not test incidental formatting or that deleted files stay deleted.
 - Reviewers consume the recorded command, result, revision and environment; they do not rerun passing checks to claim ownership.
 - Changed inputs or a new uncovered failure justify affected delta checks; an old pass is only historical evidence for its old subject.
 - Run the full suite daily; a failure opens an automatic repair task and appears in the daily report.
@@ -55,6 +68,6 @@
 ## Claude Code
 - Own frontend implementation and interaction; Codex owns backend implementation and testing, and the parent coordinates scope and integration.
 - Use Claude Code's available tools within granted permissions; changes to tool grants, hooks or confirmation bypass require approval of the exact change.
-- User-level `~/.claude/settings.json` hooks invoke `repo-harness-hook`; its typed route registry selects one in-process handler. Repo-local hook adapters are retired. Operator helpers use the package path from `repo-harness hook-lib path`. This source repo keeps `.ai/hooks/lib/workflow-state.sh` for self-hosting.
+- User-level `~/.claude/settings.json` hooks invoke `repo-harness-hook`; its typed route registry selects one in-process handler. Operator helpers run from the package through `repo-harness run <helper>`.
 - Write comments, commits and PR text from the final diff; comments explain non-obvious reasons, and PRs describe final behavior and material rationale.
 - Keep this file short; load [development flow](docs/reference-configs/agentic-development-flow.md) and [external tooling](docs/reference-configs/external-tooling.md) only when needed.

package/README.es.md

@@ -156,9 +156,8 @@ repo-harness mcp uninstall --services-stopped # after stopping all MCP HTTP serv
 - **Sesiones respaldadas por archivos, no por historial de chat.** Las
   sesiones separadas de Claude y Codex se mantienen coordinadas a través del
   repositorio. `SessionStart` inyecta el resume packet de la sesión anterior,
-  `Stop` escribe el handoff, y cada edición registra un pequeño evento de
-  bitácora. Una sesión puede terminar a mitad de tarea, y la siguiente retoma
-  exactamente el próximo paso, los blockers y los archivos modificados, sin
+  y `Stop` escribe el handoff y el resume. Una sesión puede terminar a mitad
+  de tarea, y la siguiente retoma exactamente el próximo paso, los blockers y los archivos modificados, sin
   tener que volver a inferirlos.
 - **Ahorro de tokens por diseño.** En lugar de bucles de grep-and-read que
   reescanean el repositorio en cada sesión, el harness se apoya en un índice
@@ -222,7 +221,7 @@ escrito un humano.
 | | |
 | --- | --- |
 | **Sesiones respaldadas por archivos** | Plans, contracts, checks y handoffs viven en el repositorio, de modo que una sesión nueva retoma desde artefactos en vez de un hilo de chat |
-| **Typed hook runtime** | Ocho managed routes compartidas, más tres delegation routes exclusivas de Codex, cada una atada a exactamente un typed handler in-process, con guards fail-closed en el límite de edición |
+| **Typed hook runtime** | 6 routes públicas (Claude 5, Codex 5), cada una atada a exactamente un typed handler in-process, con guards fail-closed en el límite de edición |
 | **Plan → Contract → Review** | Un solo ciclo de vida desde el plan aprobado hasta el contract proyectado, el worktree aislado, la evidencia estructurada y un closeout revisable |
 | **Programas planificados por el Bot** | Programas de collaboration con task offers de engineer y leases renovables; el Bot planifica, repo-harness aporta herramientas y evidencia |
 | **Carga de contexto progresiva** | Un root context estable de ~12KB más capability contracts de ~1KB que solo se cargan para los archivos que realmente se están tocando |
@@ -299,11 +298,11 @@ flowchart TD
   CurrentTree --> Implement
   ContractRun --> Changes
 
-  Implement["Edit and run commands"] --> PreHooks["Pre-edit guards<br/>PlanStatusGuard, ContractScopeGuard, WorktreeGuard"]
-  PreHooks -->|blocked| ScopeFix["Fix plan, contract, worktree, or scope"]
+  Implement["Edit and run commands"] --> PreHooks["Pre-edit guards<br/>RepoScopeGuard, ExternalReferenceGuard, OpsPrivateGuard"]
+  PreHooks -->|blocked| ScopeFix["Fix the target path"]
   ScopeFix --> Implement
   PreHooks -->|allowed| Changes["Code, docs, tests, or config changes"]
-  Changes --> PostHooks["Post-edit and post-bash hooks<br/>trace, handoff, check evidence"]
+  Changes --> PostHooks["Bash observer and Stop hook<br/>repair circuit, owed architecture, handoff"]
   PostHooks --> ArchUpdate["Explicit architecture update<br/>archctx ChangeSet when responsibilities change<br/>architecture-projection apply"]
   ArchUpdate --> Verify["Run verification<br/>tests plus repo workflow checks"]
 
@@ -368,13 +367,13 @@ Campaign execution moved to the existing Bot skills on 2026-10-04. Use [repo-har
 ### Refactor recommendations
 
 ```bash
-repo-harness refactor recommendations                       # measured suggestions with evidence
-repo-harness refactor decide <id> accept|defer|reject --reason "<text>"
+repo-harness refactor recommendations [--import-node-limit <n>]   # measured suggestions with evidence
+repo-harness refactor decide <id> accept|defer|reject --reason "<text>" [--import-node-limit <n>]
 ```
 
 ArchContext mide problemas estructurales como ciclos y violaciones de
-dirección. repo-harness muestra cada sugerencia con sus métricas y las
-estadísticas de sus módulos, y registra la decisión del usuario. Nunca ejecuta
+dirección. repo-harness muestra cada sugerencia con sus métricas, su evidencia
+acotada y las estadísticas de sus módulos, y registra la decisión del usuario. Nunca ejecuta
 un refactor; una sugerencia aceptada sigue el flujo normal de plan y pull request.
 
 ### Plano de colaboración
@@ -421,26 +420,11 @@ Un task-agent fleet `deep-reasoner` persiste en un linked checkout dedicado y la
 
 ## Hooks
 
-El adapter instalado posee ocho managed hook routes compartidas. El route
-tuple `event + routeId + matcher` es el contract estable; cada tuple ata
-exactamente un typed handler in-process.
-
-| Route | Matcher | Handler | Función |
-| --- | --- | --- | --- |
-| `SessionStart.default` | all sessions | `src/cli/hook/session-context.ts` (in-process builder) | Inyecta el handoff anterior, el estado del sprint, guía de minimal-change y hallazgos de config-security de solo lectura antes de que empiece el trabajo. |
-| `PreToolUse.edit` | `Edit\|Write` | `src/cli/hook/mutation-guard.ts` (in-process handler) | Aplica la worktree policy y la readiness de plan/contract antes de las ediciones de implementación. |
-| `PreToolUse.subagent` | `Task\|Agent\|SendUserMessage` | `src/cli/hook/subagent-handler.ts` | Mantiene el trabajo delegado retornando a través de la sesión padre, en lugar de dejar escapar afirmaciones de finalización. |
-| `PostToolUse.edit` | `Edit\|Write` | `src/cli/hook/mutation-observed.ts` (in-process handler) | Escribe como máximo un pequeño evento de bitácora con dirty bits por cada edición calificada; la verificación del contract, el sync de architecture/context/capability y la evidencia de minimal-change se difieren a Stop en vez de ejecutarse por cada edición. |
-| `PostToolUse.bash` | `Bash` | `src/cli/hook/command-observed.ts` | Observa los resultados de comandos y captura evidencia de verificación sin reemplazar el command runner. |
-| `PostToolUse.always` | all tools | `src/cli/hook/trace-observer.ts` | Provee trace y runtime observation de bajo ruido y siempre activo. |
-| `UserPromptSubmit.default` | all prompts | `src/cli/hook/prompt-handler.ts` | Clasifica la intención del prompt, enruta hints de planning/check y renderiza guía de workflow host-safe. |
-| `Stop.default` | session stop | `src/cli/hook/stop-handler.ts` (in-process handler) | Finaliza el handoff y protege contra terminar con draft-plans sin resolver o vacíos de evidencia de completion. |
-
-Codex también instala tres Codex-only bounded-delegation routes —
-`UserPromptSubmit.delegation`, `SubagentStart.context`, y
-`SubagentStop.quality`, todas atadas a `src/cli/hook/subagent-handler.ts`;
-Claude solo conserva la route compartida de return-channel,
-`PreToolUse.subagent`.
+El adapter instalado ata 6 hook routes públicas: Claude instala 5 y Codex instala
+5. El route tuple `event + routeId + matcher` es el contract estable;
+cada tuple ata exactamente un typed handler in-process. La tabla de routes, con una
+columna Host, está en
+[`docs/reference-configs/hook-operations.md`](docs/reference-configs/hook-operations.md#hook-authority-map).
 
 `repo-harness-hook` y su typed handler registry son el host-event runtime;
 `~/.claude/settings.json` y `~/.codex/hooks.json` son los adapters a nivel de
@@ -449,13 +433,14 @@ esos hooks corran. `.claude/settings.json` y `.codex/hooks.json` repo-locales
 son config legacy a retirar. Depura en este orden: adapter config ->
 `repo-harness-hook` -> route registry -> typed handler.
 
-Cuando un hook bloquea el trabajo, lee primero el structured terminal
-output: `guard`, `reason`, `fix`, `failure_class`, y `run_id`. Los registros
-durables viven en `.ai/harness/failures/latest.jsonl`, con la actividad de
-tools circundante en `.claude/.trace.jsonl`. Los guards comunes son
-`PlanStatusGuard` (no hay plan activo o ejecutable), `ContractGuard` (falta
-el contract scaffold, o se afirma completion antes de que el contract
-pasara), y `WorktreeGuard` (escrituras desde el worktree equivocado).
+Cuando un hook bloquea el trabajo, lee primero la salida del terminal: una
+línea `[<Guard>] <reason>` y una línea `Fix:`. El registro durable en
+`.ai/harness/failures/latest.jsonl` lleva `guard`, `reason`, `fix`,
+`failure_class`, y `run_id`. `.ai/harness/runs/hook-events.jsonl` registra
+cada evento de hook. Los edit guards son `RepoScopeGuard` (una ruta fuera del
+repositorio), `ExternalReferenceGuard` (`_ref/`), `OpsPrivateGuard`
+(`_ops/`), y `ApplyPatchScopeGuard` y `EditScopeGuard` (sin una ruta de
+destino legible).
 Playbook completo:
 [`docs/reference-configs/hook-operations.md`](docs/reference-configs/hook-operations.md).
 
@@ -598,9 +583,11 @@ Ese checkout es la única fuente de verdad editable; las rutas locales de
 skill de Claude/Codex son runtime entrypoints respaldados por symlinks,
 reconstruidos por `scripts/sync-codex-installed-copies.sh`.
 
-`bun run check:ci` es el único gate equivalente a CI; `bun run check:release`
-solo añade el preflight de unpublished-version de npm antes de delegar a ese
-mismo gate.
+`bun run check:ci` es el único gate equivalente a CI. `bun run check:release`
+añade el preflight de unpublished-version de npm y después ejecuta el lane
+`release`: los tests protegidos por el gate de coste y el smoke de instalación
+del tarball. No es una segunda suite completa ni el gate de CI; un release
+depende de un CI en verde para el SHA del release.
 Las pruebas afectadas cubren el routing del runtime. El antiguo gate de routing eval está retirado.
 
 ```bash
@@ -611,8 +598,8 @@ repo-harness docs show harness-overview
 bun scripts/assemble-template.ts --plan C --name "MyProject"
 ```
 
-Los cambios de hook actualizan `assets/hooks/` canónico una vez, y luego
-corren `bun run sync:hooks` con `bun run check:hooks` en la verificación. Los
+Los cambios de hook handler van a `src/cli/hook/`. Los operator helpers están en
+`scripts/` y se ejecutan con `repo-harness run <helper>`. Los
 reference docs son canónicos bajo `assets/reference-configs/` y se proyectan
 en `docs/reference-configs/`; `bun run check:reference-configs` verifica esa
 proyección.
@@ -649,8 +636,8 @@ repositorio adopte la misma política.
 
 ## Versión actual
 
-- Paquete npm: `repo-harness@0.22.1`
-- Sello de workflow generado: `repo-harness@0.22.1+template@0.22.1`
+- Paquete npm: `repo-harness@0.23.0`
+- Sello de workflow generado: `repo-harness@0.23.0+template@0.23.0`
 - Repositorio de GitHub: `Ancienttwo/repo-harness`
 - Notas de versión e historial: [`docs/CHANGELOG.md`](docs/CHANGELOG.md)
 

package/README.fr.md

@@ -154,10 +154,9 @@ repo-harness mcp uninstall --services-stopped # after stopping all MCP HTTP serv
 
 - **Des sessions file-backed, pas de mémoire de chat.** Les sessions Claude et
   Codex séparées restent coordonnées via le dépôt. `SessionStart` injecte le
-  resume packet de la session précédente, `Stop` écrit le handoff, et chaque
-  édition enregistre un petit événement de journal. Une session peut
-  s'arrêter en plein milieu d'une tâche, et la suivante reprend directement à
-  l'étape suivante exacte, avec les blockers et les fichiers modifiés, sans
+  resume packet de la session précédente, et `Stop` écrit le handoff et le
+  resume. Une session peut s'arrêter en plein milieu d'une tâche, et la
+  suivante reprend directement à l'étape suivante exacte, avec les blockers et les fichiers modifiés, sans
   avoir à les redéduire.
 - **Économe en tokens par conception.** Au lieu de boucles grep-and-read qui
   rescannent le dépôt à chaque session, le harness s'appuie sur un index
@@ -220,7 +219,7 @@ humain aurait écrits.
 | | |
 | --- | --- |
 | **Sessions file-backed** | Les plans, contracts, checks et handoffs vivent dans le dépôt, si bien qu'une nouvelle session reprend à partir des artifacts plutôt que d'un chat thread |
-| **Runtime de hooks typés** | Huit routes managées partagées, plus trois routes de delegation réservées à Codex, chacune liée à exactement un typed handler in-process, avec des guards fail-closed à la frontière d'édition |
+| **Runtime de hooks typés** | 6 routes publiques (Claude 5, Codex 5), chacune liée à exactement un typed handler in-process, avec des guards fail-closed à la frontière d'édition |
 | **Plan → Contract → Review** | Un seul lifecycle, du plan approuvé au contract projeté, en passant par le worktree isolé et l'evidence structurée, jusqu'à un closeout prêt pour la review |
 | **Programmes ordonnancés par le Bot** | Programmes de collaboration avec des task offers d'engineer et des leases renouvelables ; le Bot ordonnance, repo-harness fournit les outils et les preuves |
 | **Chargement de contexte progressif** | Un root context stable d'environ 12 Ko, plus des capability contracts d'environ 1 Ko chargés uniquement pour les fichiers réellement touchés |
@@ -297,11 +296,11 @@ flowchart TD
   CurrentTree --> Implement
   ContractRun --> Changes
 
-  Implement["Edit and run commands"] --> PreHooks["Pre-edit guards<br/>PlanStatusGuard, ContractScopeGuard, WorktreeGuard"]
-  PreHooks -->|blocked| ScopeFix["Fix plan, contract, worktree, or scope"]
+  Implement["Edit and run commands"] --> PreHooks["Pre-edit guards<br/>RepoScopeGuard, ExternalReferenceGuard, OpsPrivateGuard"]
+  PreHooks -->|blocked| ScopeFix["Fix the target path"]
   ScopeFix --> Implement
   PreHooks -->|allowed| Changes["Code, docs, tests, or config changes"]
-  Changes --> PostHooks["Post-edit and post-bash hooks<br/>trace, handoff, check evidence"]
+  Changes --> PostHooks["Bash observer and Stop hook<br/>repair circuit, owed architecture, handoff"]
   PostHooks --> ArchUpdate["Explicit architecture update<br/>archctx ChangeSet when responsibilities change<br/>architecture-projection apply"]
   ArchUpdate --> Verify["Run verification<br/>tests plus repo workflow checks"]
 
@@ -366,13 +365,13 @@ Campaign execution moved to the existing Bot skills on 2026-10-04. Use [repo-har
 ### Refactor recommendations
 
 ```bash
-repo-harness refactor recommendations                       # measured suggestions with evidence
-repo-harness refactor decide <id> accept|defer|reject --reason "<text>"
+repo-harness refactor recommendations [--import-node-limit <n>]   # measured suggestions with evidence
+repo-harness refactor decide <id> accept|defer|reject --reason "<text>" [--import-node-limit <n>]
 ```
 
 ArchContext mesure des problèmes structurels comme les cycles et les
 violations de direction. repo-harness montre chaque suggestion avec ses
-métriques et les statistiques de ses modules, et enregistre la décision de
+métriques, ses preuves bornées et les statistiques de ses modules, et enregistre la décision de
 l'utilisateur. Il n'exécute jamais de refactor ; une suggestion acceptée suit le
 flux normal de plan et de pull request.
 
@@ -420,25 +419,11 @@ Un task-agent fleet `deep-reasoner` persiste dans un linked checkout dédié et
 
 ## Hooks
 
-L'adapter installé possède huit routes de hook managées et partagées. Le
-tuple de route `event + routeId + matcher` est le contrat stable ; chaque
-tuple lie exactement un typed handler in-process.
-
-| Route | Matcher | Handler | Fonction |
-| --- | --- | --- | --- |
-| `SessionStart.default` | all sessions | `src/cli/hook/session-context.ts` (in-process builder) | Injecte le handoff précédent, le statut sprint, la guidance minimal-change, et les findings config-security read-only avant le début du travail. |
-| `PreToolUse.edit` | `Edit\|Write` | `src/cli/hook/mutation-guard.ts` (in-process handler) | Impose la worktree policy et la readiness plan/contract avant les edits d'implémentation. |
-| `PreToolUse.subagent` | `Task\|Agent\|SendUserMessage` | `src/cli/hook/subagent-handler.ts` | Garde le travail délégué qui revient via la session parent, au lieu de laisser fuiter des complétions prétendues. |
-| `PostToolUse.edit` | `Edit\|Write` | `src/cli/hook/mutation-observed.ts` (in-process handler) | Écrit au plus un petit événement de journal avec des dirty bits par edit qualifiant ; la contract verification, la sync architecture/context/capability, et l'evidence minimal-change sont différées jusqu'au Stop plutôt qu'exécutées à chaque edit. |
-| `PostToolUse.bash` | `Bash` | `src/cli/hook/command-observed.ts` | Observe les résultats de commande et capture l'evidence de vérification sans remplacer le command runner. |
-| `PostToolUse.always` | all tools | `src/cli/hook/trace-observer.ts` | Fournit une trace toujours active et à faible bruit, ainsi que l'observation runtime. |
-| `UserPromptSubmit.default` | all prompts | `src/cli/hook/prompt-handler.ts` | Classifie l'intent du prompt, route les hints de planning/check, et rend une guidance de workflow host-safe. |
-| `Stop.default` | session stop | `src/cli/hook/stop-handler.ts` (in-process handler) | Finalise le handoff et empêche de terminer avec un draft-plan non résolu ou des gaps d'evidence de complétion. |
-
-Codex installe aussi trois routes de bounded-delegation réservées à Codex —
-`UserPromptSubmit.delegation`, `SubagentStart.context` et
-`SubagentStop.quality`, toutes liées à `src/cli/hook/subagent-handler.ts` ;
-Claude ne garde que la route partagée `PreToolUse.subagent` return-channel.
+L'adapter installé lie 6 routes de hook publiques : Claude en installe 5 et Codex en
+installe 5. Le tuple de route `event + routeId + matcher` est
+le contrat stable ; chaque tuple lie exactement un typed handler in-process. La table
+des routes, avec une colonne Host, est dans
+[`docs/reference-configs/hook-operations.md`](docs/reference-configs/hook-operations.md#hook-authority-map).
 
 `repo-harness-hook` et son typed handler registry constituent le host-event
 runtime ; `~/.claude/settings.json` et `~/.codex/hooks.json` sont les adapters
@@ -448,13 +433,14 @@ Settings avant que ces hooks ne s'exécutent. Les `.claude/settings.json` et
 l'ordre : adapter config -> `repo-harness-hook` -> route registry -> typed
 handler.
 
-Quand un hook bloque le travail, lisez d'abord la sortie terminal structurée :
-`guard`, `reason`, `fix`, `failure_class` et `run_id`. Les enregistrements
-durables vivent dans `.ai/harness/failures/latest.jsonl`, avec l'activité
-outil environnante dans `.claude/.trace.jsonl`. Les guards courants sont
-`PlanStatusGuard` (pas de plan actif ou exécutable), `ContractGuard` (contract
-scaffold manquant, ou complétion déclarée avant que le contract ne passe), et
-`WorktreeGuard` (écritures depuis le mauvais worktree). Guide complet :
+Quand un hook bloque le travail, lisez d'abord la sortie terminal : une ligne
+`[<Guard>] <reason>` et une ligne `Fix:`. L'enregistrement durable dans
+`.ai/harness/failures/latest.jsonl` contient `guard`, `reason`, `fix`,
+`failure_class` et `run_id`. `.ai/harness/runs/hook-events.jsonl` enregistre
+chaque événement de hook. Les edit guards sont `RepoScopeGuard` (un chemin
+hors du dépôt), `ExternalReferenceGuard` (`_ref/`), `OpsPrivateGuard`
+(`_ops/`), et `ApplyPatchScopeGuard` et `EditScopeGuard` (aucun chemin cible
+lisible). Guide complet :
 [`docs/reference-configs/hook-operations.md`](docs/reference-configs/hook-operations.md).
 
 ## Console de contrôle humaine locale
@@ -595,8 +581,11 @@ Ce checkout est l'unique source of truth éditable ; les chemins de skill
 Claude/Codex locaux sont des runtime entrypoints adossés à des symlinks,
 reconstruits par `scripts/sync-codex-installed-copies.sh`.
 
-`bun run check:ci` est le gate unique équivalent CI ; `bun run check:release`
-ajoute seulement le preflight npm unpublished-version avant de lui déléguer.
+`bun run check:ci` est le gate unique équivalent CI. `bun run check:release`
+ajoute le preflight npm unpublished-version, puis exécute le lane `release` :
+les tests protégés par le gate de coût et le smoke d'installation du tarball.
+Ce n'est ni une deuxième suite complète ni le gate CI ; une release dépend d'un
+CI vert pour le SHA de la release.
 Les tests concernés vérifient le routing du runtime. Le gate de routing eval est retiré.
 
 ```bash
@@ -607,9 +596,8 @@ repo-harness docs show harness-overview
 bun scripts/assemble-template.ts --plan C --name "MyProject"
 ```
 
-Les changements de hook mettent à jour `assets/hooks/` canonique une fois,
-puis lancent `bun run sync:hooks`, avec `bun run check:hooks` en
-vérification. Les reference docs sont canoniques sous
+Les changements de hook handler vont dans `src/cli/hook/`. Les operator helpers sont dans
+`scripts/` et s'exécutent avec `repo-harness run <helper>`. Les reference docs sont canoniques sous
 `assets/reference-configs/` et projetées dans `docs/reference-configs/` ;
 `bun run check:reference-configs` vérifie cette projection.
 
@@ -645,8 +633,8 @@ adopte la même policy.
 
 ## Release actuelle
 
-- Package npm : `repo-harness@0.22.1`
-- Generated workflow stamp : `repo-harness@0.22.1+template@0.22.1`
+- Package npm : `repo-harness@0.23.0`
+- Generated workflow stamp : `repo-harness@0.23.0+template@0.23.0`
 - Dépôt GitHub : `Ancienttwo/repo-harness`
 - Notes et historique de release : [`docs/CHANGELOG.md`](docs/CHANGELOG.md)
 

package/README.ja.md

@@ -157,7 +157,7 @@ repo-harness mcp uninstall --services-stopped # after stopping all MCP HTTP serv
 - **セッションの状態はファイルに残り、チャット履歴には残らない。** 別々の
   Claude セッションと Codex セッションは、リポジトリを介して同期を保ちます。
   `SessionStart` が前回セッションの resume packet を注入し、`Stop` が handoff
-  を書き出し、各編集は小さな journal event を記録します。セッションはタスクの
+  と resume を書き出します。セッションはタスクの
   途中で終了でき、次のセッションは正確な次の一手・blocker・変更ファイルを、
   推測し直すことなくそのまま引き継ぎます。
 - **設計上 token を節約する。** セッションのたびにリポジトリを grep-and-read
@@ -217,7 +217,7 @@ Layer 2 は Layer 1 を置き換えるものではありません。program の
 | | |
 | --- | --- |
 | **File-backed sessions** | Plan、contract、check、handoff がリポジトリに残るので、新しいセッションはチャットスレッドではなく artifacts から再開します |
-| **Typed hook runtime** | 8 本の共有 managed route と 3 本の Codex 専用 delegation route があり、それぞれが exactly one の typed in-process handler に bind され、edit boundary で fail-closed な guard がかかります |
+| **Typed hook runtime** | 6 本の公開 route（Claude 5 本、Codex 5 本）があり、それぞれが exactly one の typed in-process handler に bind され、edit boundary で fail-closed な guard がかかります |
 | **Plan → Contract → Review** | approved plan から投射された contract、隔離された worktree、構造化された evidence、review 可能な closeout までの 1 本の lifecycle |
 | **Bot-scheduled programs** | engineer task offer と更新可能な lease を持つ collaboration program。Bot がスケジュールし、repo-harness が tools と evidence を提供します |
 | **Progressive context loading** | 安定した約 12KB の root context に、実際に触れるファイルにだけ読み込まれる約 1KB の capability contract が加わります |
@@ -296,11 +296,11 @@ flowchart TD
   CurrentTree --> Implement
   ContractRun --> Changes
 
-  Implement["Edit and run commands"] --> PreHooks["Pre-edit guards<br/>PlanStatusGuard, ContractScopeGuard, WorktreeGuard"]
-  PreHooks -->|blocked| ScopeFix["Fix plan, contract, worktree, or scope"]
+  Implement["Edit and run commands"] --> PreHooks["Pre-edit guards<br/>RepoScopeGuard, ExternalReferenceGuard, OpsPrivateGuard"]
+  PreHooks -->|blocked| ScopeFix["Fix the target path"]
   ScopeFix --> Implement
   PreHooks -->|allowed| Changes["Code, docs, tests, or config changes"]
-  Changes --> PostHooks["Post-edit and post-bash hooks<br/>trace, handoff, check evidence"]
+  Changes --> PostHooks["Bash observer and Stop hook<br/>repair circuit, owed architecture, handoff"]
   PostHooks --> ArchUpdate["Explicit architecture update<br/>archctx ChangeSet when responsibilities change<br/>architecture-projection apply"]
   ArchUpdate --> Verify["Run verification<br/>tests plus repo workflow checks"]
 
@@ -364,12 +364,12 @@ Campaign execution moved to the existing Bot skills on 2026-10-04. Use [repo-har
 ### Refactor recommendations
 
 ```bash
-repo-harness refactor recommendations                       # measured suggestions with evidence
-repo-harness refactor decide <id> accept|defer|reject --reason "<text>"
+repo-harness refactor recommendations [--import-node-limit <n>]   # measured suggestions with evidence
+repo-harness refactor decide <id> accept|defer|reject --reason "<text>" [--import-node-limit <n>]
 ```
 
 ArchContext は循環や依存方向の違反などの構造上の問題を計測します。repo-harness は
-各提案をその指標とモジュール統計とともに表示し、ユーザーの判断を記録します。
+各提案をその指標、上限付きの根拠、モジュール統計とともに表示し、ユーザーの判断を記録します。
 リファクタリング自体は実行しません。受け入れた提案は通常の plan と pull request の
 流れで進めます。
 
@@ -416,26 +416,11 @@ Herdr のない Claude デスクトップアプリでは `--launch app-terminal`
 
 ## Hooks
 
-インストールされた adapter は、8 本の共有 managed hook route を所有します。
-`event + routeId + matcher` の route tuple が安定した契約であり、各 tuple は
-exactly one の typed in-process handler に bind されます。
-
-| Route | Matcher | Handler | 機能 |
-| --- | --- | --- | --- |
-| `SessionStart.default` | all sessions | `src/cli/hook/session-context.ts` (in-process builder) | 作業開始前に、直前の handoff、sprint status、minimal-change guidance、read-only な config-security の findings を注入します。 |
-| `PreToolUse.edit` | `Edit\|Write` | `src/cli/hook/mutation-guard.ts` (in-process handler) | 実装編集の前に worktree policy と plan/contract の readiness を強制します。 |
-| `PreToolUse.subagent` | `Task\|Agent\|SendUserMessage` | `src/cli/hook/subagent-handler.ts` | delegate された作業が completion claim を漏らさず、parent session を経由して戻るようにします。 |
-| `PostToolUse.edit` | `Edit\|Write` | `src/cli/hook/mutation-observed.ts` (in-process handler) | 該当する編集ごとに、dirty bits を伴う小さな journal event を高々 1 件書き込みます。contract verification、architecture/context/capability sync、minimal-change evidence は編集ごとには実行されず、Stop まで遅延されます。 |
-| `PostToolUse.bash` | `Bash` | `src/cli/hook/command-observed.ts` | command runner を置き換えることなく、command の結果を観測し verification evidence を取得します。 |
-| `PostToolUse.always` | all tools | `src/cli/hook/trace-observer.ts` | low-noise で常時稼働する trace と runtime observation を提供します。 |
-| `UserPromptSubmit.default` | all prompts | `src/cli/hook/prompt-handler.ts` | prompt の intent を分類し、planning/check の hint を route し、host-safe な workflow guidance を描画します。 |
-| `Stop.default` | session stop | `src/cli/hook/stop-handler.ts` (in-process handler) | handoff を finalize し、未解決の draft-plan や completion evidence の gap を残したまま終了しないよう防ぎます。 |
-
-Codex はさらに、3 本の Codex 専用 bounded-delegation route —
-`UserPromptSubmit.delegation`、`SubagentStart.context`、`SubagentStop.quality`
-— をインストールし、すべて `src/cli/hook/subagent-handler.ts` に bind
-されます。Claude 側は共有の `PreToolUse.subagent` return-channel route だけを
-保持します。
+インストールされた adapter は 6 本の公開 hook route を bind します。Claude は 5 本、
+Codex は 5 本をインストールします。`event + routeId + matcher` の
+route tuple が安定した契約であり、各 tuple は exactly one の typed in-process
+handler に bind されます。Host 列つきの route 表は
+[`docs/reference-configs/hook-operations.md`](docs/reference-configs/hook-operations.md#hook-authority-map) にあります。
 
 `repo-harness-hook` とその typed handler registry が host-event の runtime
 です。`~/.claude/settings.json` と `~/.codex/hooks.json` が user-level の
@@ -445,13 +430,14 @@ adapter であり、Codex は hooks が動く前に Settings でそのファイ
 adapter config -> `repo-harness-hook` -> route registry -> typed handler の
 順に確認してください。
 
-hook が作業を block したときは、まず構造化された terminal 出力 — `guard`、
-`reason`、`fix`、`failure_class`、`run_id` — を読んでください。持続的な記録は
-`.ai/harness/failures/latest.jsonl` にあり、周辺の tool activity は
-`.claude/.trace.jsonl` にあります。よくある guard は `PlanStatusGuard`(active
-または実行可能な plan がない)、`ContractGuard`(contract scaffold が存在
-しない、または contract が通る前に completion を主張した)、`WorktreeGuard`
-(誤った worktree からの書き込み)です。完全な playbook は
+hook が作業を block したときは、まず terminal 出力を読んでください。
+`[<Guard>] <reason>` の行と `Fix:` の行が 1 行ずつ出ます。持続的な記録は
+`.ai/harness/failures/latest.jsonl` にあり、`guard`、`reason`、`fix`、
+`failure_class`、`run_id` を持ちます。`.ai/harness/runs/hook-events.jsonl` は
+各 hook event を記録します。edit guard は `RepoScopeGuard`(リポジトリ外の
+パス)、`ExternalReferenceGuard`(`_ref/`)、`OpsPrivateGuard`(`_ops/`)、
+そして `ApplyPatchScopeGuard` と `EditScopeGuard`(解析できる対象パスがない)
+です。完全な playbook は
 [`docs/reference-configs/hook-operations.md`](docs/reference-configs/hook-operations.md)
 を参照してください。
 
@@ -594,9 +580,11 @@ cd ~/Projects/repo-harness && bun src/cli/index.ts update
 Claude/Codex skill path は `scripts/sync-codex-installed-copies.sh` によって
 再構築される、symlink に裏打ちされた runtime entrypoint です。
 
-`bun run check:ci` が唯一の CI-equivalent gate であり、
-`bun run check:release` はそこへ委譲する前に npm の unpublished-version
-preflight を追加するだけです。
+`bun run check:ci` が唯一の CI-equivalent gate です。
+`bun run check:release` は npm の unpublished-version preflight の後に
+`release` lane を実行します。この lane は高コスト gate 付きのテストと
+tarball install smoke だけを実行します。2 回目の full suite でも CI gate
+でもありません。release はその release SHA の CI が green であることを前提にします。
 Runtime routing の回帰テストは保持します。旧 routing eval gate は廃止しました。
 
 ```bash
@@ -607,9 +595,8 @@ repo-harness docs show harness-overview
 bun scripts/assemble-template.ts --plan C --name "MyProject"
 ```
 
-Hook の変更は、まず canonical な `assets/hooks/` を更新し、その後
-`bun run sync:hooks` を実行し、verification で `bun run check:hooks` を
-使います。Reference docs は `assets/reference-configs/` 配下が canonical であり、
+Hook handler の変更は `src/cli/hook/` を編集します。Operator helper は `scripts/` にあり、
+`repo-harness run <helper>` で実行します。Reference docs は `assets/reference-configs/` 配下が canonical であり、
 `docs/reference-configs/` へ投射されます。`bun run check:reference-configs`
 がその投射を検証します。
 
@@ -645,8 +632,8 @@ commit script や hooks に組み込まないでください。
 
 ## 現在の Release
 
-- npm package：`repo-harness@0.22.1`
-- Generated workflow stamp：`repo-harness@0.22.1+template@0.22.1`
+- npm package：`repo-harness@0.23.0`
+- Generated workflow stamp：`repo-harness@0.23.0+template@0.23.0`
 - GitHub repository：`Ancienttwo/repo-harness`
 - Release notes and history：[`docs/CHANGELOG.md`](docs/CHANGELOG.md)