repo-harness 0.9.2 → 0.11.0

package/AGENTS.md

@@ -17,15 +17,15 @@ This repository self-hosts the `repo-harness` contract; the former `repo-harness
 - `.ai/harness/policy.json` for the machine-readable workflow contract
 - `.ai/context/context-map.json` for progressive context loading
 - `docs/architecture/index.md` for umbrella architecture status, drift requests, snapshots, and diagram links
-- `docs/reference-configs/agentic-development-flow.md` for gstack/Waza routing rules
+- `docs/reference-configs/agentic-development-flow.md` for parent-agent/Waza routing and P1/P2/P3 rules
 
 ## Operating Rules
 
 - Sync `tasks/` whenever substantive repo changes are made.
 - Use `tasks/notes/<plan-stem>.notes.md` only for non-obvious slice decisions, deviations, tradeoffs, and open questions; `<plan-stem>` is the active plan filename without `plan-` and `.md` (for example `20260531-0045-governance-workflow`). Do not use notes as durable memory or a task log, and archive/promote them deliberately when the slice closes.
-- Treat hook execution as central-first: trusted repos run `~/.repo-harness/hooks/` (bash shim) or the packaged CLI copy; this self-host repo pins `"hook_source": "repo"` in `.ai/harness/policy.json` so `.ai/hooks/` stays the live development runtime, with `assets/hooks/` as the product source mirrored on install. User-level `~/.claude/settings.json` and `~/.codex/hooks.json` are the host adapters.
+- Treat hook execution as typed and user-level: `~/.claude/settings.json` and `~/.codex/hooks.json` invoke `repo-harness-hook`, whose route registry selects exactly one in-process handler. `.ai/hooks/lib/workflow-state.sh` is an operator-helper library, never a host-event dispatcher.
 - Keep the umbrella hierarchy explicit: architecture owns stable truth, capability contracts own local agent context, `tasks/workstreams/<domain>/<capability>/` owns durable progress, and `tasks/todos.md` owns only deferred medium/long-term goals with tradeoff and revisit trigger.
-- Treat `.ai/context/capabilities.json` as the source of truth for capability prefixes; `agent-context-blocks.txt` and nested agent files are compatibility inputs only.
+- Treat `.ai/context/capabilities.json` as the source of truth for capability prefixes; `agent-context-blocks.txt` and nested agent files are initialization inputs only, never runtime resolver authority.
 - Keep architecture drift handling split: `architecture-queue.sh` writes architecture requests/events, `workstream-sync.sh` maintains durable capability workstreams, and `context-contract-sync.sh` only updates controlled local `CLAUDE.md`/`AGENTS.md` architecture blocks.
 - Keep `assets/workflow-contract.v1.json` and `.ai/harness/workflow-contract.json` in sync.
 - Keep `CLAUDE.md` and `AGENTS.md` short; put detailed guidance in `docs/reference-configs/`.
@@ -33,22 +33,29 @@ This repository self-hosts the `repo-harness` contract; the former `repo-harness
 - Treat `.ai/harness/checks/*.latest.{json,md}` and `.ai/harness/runs/` as ignored runtime evidence cache; commit durable conclusions in `tasks/reviews/`, `tasks/contracts/`, `tasks/notes/`, or `docs/researches/` instead.
 - Treat architecture/spec/research docs as the human reading entrypoint. Before closing a workflow, promote durable conclusions into `docs/architecture/`, `docs/researches/`, `docs/spec.md`, or `tasks/lessons.md`; then archive fulfilled plan/contract/review/notes/todo artifacts so root workflow surfaces represent active work only. `.rgignore` hides archived workflow artifacts and runtime evidence from default `rg` searches; use explicit paths or `rg -uu` for audits.
 - Treat `_ref/` as an occasional ignored external reference checkout cache, not a commit surface or daily workflow. Agents may read or refresh it for comparison; when it influences a decision, cite the source repo plus commit/tag and path in `tasks/notes/` or `docs/researches/`.
-- Treat `deploy/` as the trackable deployment and operations surface for runbooks, submission materials, release checklists, helper scripts, ordered SQL files under `deploy/sql/`, and env examples.
+- Treat `deploy/` as the trackable deployment and operations surface for runbooks, submission materials, release checklists, helper scripts, ordered SQL files, and env examples; follow `.ai/harness/policy.json#operations.deploy_sql` for configured SQL roots and naming modes, otherwise keep SQL directly under `deploy/sql/` with 4-digit ascending prefixes.
 - Treat `_ops/` as ignored local operations state for secrets, real env files, provider state, artifacts, logs, and scratch files; do not commit or agent-edit `_ops/*`.
 - Treat contract-level task execution as worktree-first: `repo-harness run plan-to-todo --plan <approved-plan>` starts `repo-harness run contract-worktree start --plan <approved-plan>` when policy enables it, and completed blocks finish through Waza `/check` plus `repo-harness run contract-worktree finish`.
 - Treat the EXECUTION_BOUNDARY anti-extras clause as mandatory on every delegated runner surface (contract worker prompts, the Codex delegation advisor hook, subagent start context, and MCP `codex-goal` documents): absent requirements are forbidden design space, not permission to improve, and unrequested extras fail closed.
 - After Codex Plan mode, Waza `/think`, or `repo-harness-plan` produces a decision-complete work-package plan, capture it with `repo-harness run capture-plan --artifact-level work-package --slug <slug> --title <title>` so `plans/` becomes the file-backed source of truth; if the user has already approved implementation, capture with `--status Approved --execute --promotion-reason <merge_boundary|rollback_boundary|verification_boundary|risk_boundary|human_decision_boundary|worktree_boundary>` or run `repo-harness run plan-to-todo --plan <active-plan>`.
 - Promote work into a top-level `plans/plan-*.md` only when `Artifact Level: work-package` is justified by a merge/PR unit, rollback surface, independent verification boundary, review/acceptance boundary, high-risk surface, or otherwise cannot remain a checklist item in the current active plan or sprint backlog. Inline sprint rows and checklist rows stay in the sprint backlog or active plan `## Task Breakdown`; contract rows may expand into plan -> contract -> review -> notes only through the work-package gate.
 - If current repo state conflicts with the task, open an isolated `codex/<task-slug>` worktree, finish there, run Waza `/check`-style validation, then merge back to `main` without absorbing unrelated dirty changes.
-- Route product discovery to gstack `office-hours`, complex engineering plans to gstack `plan-eng-review`, design plans to gstack `plan-design-review`, and daily small/medium planning, bug hunts, and checks to Waza `/think`, `/hunt`, and `/check`.
+- Route product discovery and complex/design planning to the parent agent: use `geju` for pre-contract framing, complete P1/P2/P3 with the parent agent's own capabilities, and freeze the accepted direction into the plan and contract. Route daily small/medium planning, bug hunts, and checks to Waza `/think`, `/hunt`, and `/check`. Route a proactive multi-direction visual/UX choice mid-task to the design-options convention (`repo-harness docs show design-options`).
 - Codex automation profile is runtime-referenced, not vendored: required skills are `health`, `check`, and `diagram-design` from `~/.codex/skills`.
-- Route knowledge sync and handoff retrieval to `gbrain`.
-- Register valuable repo-authored docs in `.ai/harness/brain-manifest.json` with `sync.direction=repo-to-brain`; `scripts/sync-brain-docs.sh` and the PostEdit hook mirror only those explicit entries into the default brain vault.
+- Keep durable repo knowledge in `docs/researches/`, `tasks/lessons.md`, and the canonical workflow artifacts.
+- Treat `.ai/harness/brain-manifest.json` and `repo-harness run sync-brain-docs` as explicit operator-invoked export surfaces only; hooks and workflow checks must not read, write, or gate on external brain-vault state.
 - Treat Waza as Codex-first: `~/.codex/skills` is the Codex runtime source; `~/.agents/skills` is skills CLI staging/cache only. Update by staging upstream Waza, copying the eight managed `SKILL.md` files into Codex, and verifying with `cmp`.
 - Use `docs/reference-configs/external-tooling.md` and `bash scripts/check-agent-tooling.sh --host both --check-updates` for environment checks; this self-host repo vendors CodeGraph as a dev dependency while generated downstream repos keep the global MCP default unless local policy opts in.
-- When changing `scripts/migrate-project-template.sh` or `scripts/lib/project-init-lib.sh`, verify self-migration of this repo still works.
+- When changing adoption planner or transaction code, verify `repo-harness adopt --repo . --dry-run` and a fixture apply use the same TS operation model.
 - Treat repo-local `.claude/settings.json` and `.codex/hooks.json` hook adapters as retired legacy config; migration may back them up locally, but they are not product deliverables.
 
+## Code Optimization Principles
+
+- Reason from first principles: identify observable conditions, controllable inputs, the invariant, and the actual pressure point before changing structure.
+- Keep one source of truth for each datum; every other representation must be a deterministic projection with a drift check.
+- Do not add steady-state compatibility code, dual authority, semantic fallbacks, aliases, or shadow parsers. Explicit one-shot migrations must fail closed and remove the retired path in the same work-package.
+- Create shared components only for observed reuse or a cross-module invariant. Prefer an existing monorepo workspace only when independently meaningful consumers need the shared package; do not convert this single-package repo without that boundary.
+
 ## Required Checks
 
 ```bash
@@ -58,7 +65,7 @@ bash scripts/check-architecture-sync.sh
 bash scripts/check-task-sync.sh
 repo-harness run check-task-workflow --strict
 bun scripts/inspect-project-state.ts --repo . --format text
-bash scripts/migrate-project-template.sh --repo . --dry-run
+bun src/cli/index.ts adopt --repo . --dry-run
 ```
 
 <!-- BEGIN ARCHITECTURE CONTRACT -->

package/CLAUDE.md

@@ -17,15 +17,15 @@ This repository self-hosts the `repo-harness` contract; the former `repo-harness
 - `.ai/harness/policy.json` for the machine-readable workflow contract
 - `.ai/context/context-map.json` for progressive context loading
 - `docs/architecture/index.md` for umbrella architecture status, drift requests, snapshots, and diagram links
-- `docs/reference-configs/agentic-development-flow.md` for gstack/Waza routing rules
+- `docs/reference-configs/agentic-development-flow.md` for parent-agent/Waza routing and P1/P2/P3 rules
 
 ## Operating Rules
 
 - Sync `tasks/` whenever substantive repo changes are made.
 - Use `tasks/notes/<plan-stem>.notes.md` only for non-obvious slice decisions, deviations, tradeoffs, and open questions; `<plan-stem>` is the active plan filename without `plan-` and `.md` (for example `20260531-0045-governance-workflow`). Do not use notes as durable memory or a task log, and archive/promote them deliberately when the slice closes.
-- Treat hook execution as central-first: trusted repos run `~/.repo-harness/hooks/` (bash shim) or the packaged CLI copy; this self-host repo pins `"hook_source": "repo"` in `.ai/harness/policy.json` so `.ai/hooks/` stays the live development runtime, with `assets/hooks/` as the product source mirrored on install. User-level `~/.claude/settings.json` and `~/.codex/hooks.json` are the host adapters.
+- Treat hook execution as typed and user-level: `~/.claude/settings.json` and `~/.codex/hooks.json` invoke `repo-harness-hook`, whose route registry selects exactly one in-process handler. `.ai/hooks/lib/workflow-state.sh` is an operator-helper library, never a host-event dispatcher.
 - Keep the umbrella hierarchy explicit: architecture owns stable truth, capability contracts own local agent context, `tasks/workstreams/<domain>/<capability>/` owns durable progress, and `tasks/todos.md` owns only deferred medium/long-term goals with tradeoff and revisit trigger.
-- Treat `.ai/context/capabilities.json` as the source of truth for capability prefixes; `agent-context-blocks.txt` and nested agent files are compatibility inputs only.
+- Treat `.ai/context/capabilities.json` as the source of truth for capability prefixes; `agent-context-blocks.txt` and nested agent files are initialization inputs only, never runtime resolver authority.
 - Keep architecture drift handling split: `architecture-queue.sh` writes architecture requests/events, `workstream-sync.sh` maintains durable capability workstreams, and `context-contract-sync.sh` only updates controlled local `CLAUDE.md`/`AGENTS.md` architecture blocks.
 - Keep `assets/workflow-contract.v1.json` and `.ai/harness/workflow-contract.json` in sync.
 - Keep `CLAUDE.md` and `AGENTS.md` short; put detailed guidance in `docs/reference-configs/`.
@@ -33,22 +33,29 @@ This repository self-hosts the `repo-harness` contract; the former `repo-harness
 - Treat `.ai/harness/checks/*.latest.{json,md}` and `.ai/harness/runs/` as ignored runtime evidence cache; commit durable conclusions in `tasks/reviews/`, `tasks/contracts/`, `tasks/notes/`, or `docs/researches/` instead.
 - Treat architecture/spec/research docs as the human reading entrypoint. Before closing a workflow, promote durable conclusions into `docs/architecture/`, `docs/researches/`, `docs/spec.md`, or `tasks/lessons.md`; then archive fulfilled plan/contract/review/notes/todo artifacts so root workflow surfaces represent active work only. `.rgignore` hides archived workflow artifacts and runtime evidence from default `rg` searches; use explicit paths or `rg -uu` for audits.
 - Treat `_ref/` as an occasional ignored external reference checkout cache, not a commit surface or daily workflow. Agents may read or refresh it for comparison; when it influences a decision, cite the source repo plus commit/tag and path in `tasks/notes/` or `docs/researches/`.
-- Treat `deploy/` as the trackable deployment and operations surface for runbooks, submission materials, release checklists, helper scripts, ordered SQL files under `deploy/sql/`, and env examples.
+- Treat `deploy/` as the trackable deployment and operations surface for runbooks, submission materials, release checklists, helper scripts, ordered SQL files, and env examples; follow `.ai/harness/policy.json#operations.deploy_sql` for configured SQL roots and naming modes, otherwise keep SQL directly under `deploy/sql/` with 4-digit ascending prefixes.
 - Treat `_ops/` as ignored local operations state for secrets, real env files, provider state, artifacts, logs, and scratch files; do not commit or agent-edit `_ops/*`.
 - Treat contract-level task execution as worktree-first: `repo-harness run plan-to-todo --plan <approved-plan>` starts `repo-harness run contract-worktree start --plan <approved-plan>` when policy enables it, and completed blocks finish through Waza `/check` plus `repo-harness run contract-worktree finish`.
 - Treat the EXECUTION_BOUNDARY anti-extras clause as mandatory on every delegated runner surface (contract worker prompts, the Codex delegation advisor hook, subagent start context, and MCP `codex-goal` documents): absent requirements are forbidden design space, not permission to improve, and unrequested extras fail closed.
 - After Codex Plan mode, Waza `/think`, or `repo-harness-plan` produces a decision-complete work-package plan, capture it with `repo-harness run capture-plan --artifact-level work-package --slug <slug> --title <title>` so `plans/` becomes the file-backed source of truth; if the user has already approved implementation, capture with `--status Approved --execute --promotion-reason <merge_boundary|rollback_boundary|verification_boundary|risk_boundary|human_decision_boundary|worktree_boundary>` or run `repo-harness run plan-to-todo --plan <active-plan>`.
 - Promote work into a top-level `plans/plan-*.md` only when `Artifact Level: work-package` is justified by a merge/PR unit, rollback surface, independent verification boundary, review/acceptance boundary, high-risk surface, or otherwise cannot remain a checklist item in the current active plan or sprint backlog. Inline sprint rows and checklist rows stay in the sprint backlog or active plan `## Task Breakdown`; contract rows may expand into plan -> contract -> review -> notes only through the work-package gate.
 - If current repo state conflicts with the task, open an isolated `codex/<task-slug>` worktree, finish there, run Waza `/check`-style validation, then merge back to `main` without absorbing unrelated dirty changes.
-- Route product discovery to gstack `office-hours`, complex engineering plans to gstack `plan-eng-review`, design plans to gstack `plan-design-review`, and daily small/medium planning, bug hunts, and checks to Waza `/think`, `/hunt`, and `/check`.
+- Route product discovery and complex/design planning to the parent agent: use `geju` for pre-contract framing, complete P1/P2/P3 with the parent agent's own capabilities, and freeze the accepted direction into the plan and contract. Route daily small/medium planning, bug hunts, and checks to Waza `/think`, `/hunt`, and `/check`. Route a proactive multi-direction visual/UX choice mid-task to the design-options convention (`repo-harness docs show design-options`).
 - Codex automation profile is runtime-referenced, not vendored: required skills are `health`, `check`, and `diagram-design` from `~/.codex/skills`.
-- Route knowledge sync and handoff retrieval to `gbrain`.
-- Register valuable repo-authored docs in `.ai/harness/brain-manifest.json` with `sync.direction=repo-to-brain`; `scripts/sync-brain-docs.sh` and the PostEdit hook mirror only those explicit entries into the default brain vault.
+- Keep durable repo knowledge in `docs/researches/`, `tasks/lessons.md`, and the canonical workflow artifacts.
+- Treat `.ai/harness/brain-manifest.json` and `repo-harness run sync-brain-docs` as explicit operator-invoked export surfaces only; hooks and workflow checks must not read, write, or gate on external brain-vault state.
 - Treat Waza as Codex-first: `~/.codex/skills` is the Codex runtime source; `~/.agents/skills` is skills CLI staging/cache only. Update by staging upstream Waza, copying the eight managed `SKILL.md` files into Codex, and verifying with `cmp`.
 - Use `docs/reference-configs/external-tooling.md` and `bash scripts/check-agent-tooling.sh --host both --check-updates` for environment checks; this self-host repo vendors CodeGraph as a dev dependency while generated downstream repos keep the global MCP default unless local policy opts in.
-- When changing `scripts/migrate-project-template.sh` or `scripts/lib/project-init-lib.sh`, verify self-migration of this repo still works.
+- When changing adoption planner or transaction code, verify `repo-harness adopt --repo . --dry-run` and a fixture apply use the same TS operation model.
 - Treat repo-local `.claude/settings.json` and `.codex/hooks.json` hook adapters as retired legacy config; migration may back them up locally, but they are not product deliverables.
 
+## Code Optimization Principles
+
+- Reason from first principles: identify observable conditions, controllable inputs, the invariant, and the actual pressure point before changing structure.
+- Keep one source of truth for each datum; every other representation must be a deterministic projection with a drift check.
+- Do not add steady-state compatibility code, dual authority, semantic fallbacks, aliases, or shadow parsers. Explicit one-shot migrations must fail closed and remove the retired path in the same work-package.
+- Create shared components only for observed reuse or a cross-module invariant. Prefer an existing monorepo workspace only when independently meaningful consumers need the shared package; do not convert this single-package repo without that boundary.
+
 ## Required Checks
 
 ```bash
@@ -58,7 +65,7 @@ bash scripts/check-architecture-sync.sh
 bash scripts/check-task-sync.sh
 repo-harness run check-task-workflow --strict
 bun scripts/inspect-project-state.ts --repo . --format text
-bash scripts/migrate-project-template.sh --repo . --dry-run
+bun src/cli/index.ts adopt --repo . --dry-run
 ```
 
 <!-- BEGIN ARCHITECTURE CONTRACT -->

package/README.es.md

@@ -1,9 +1,5 @@
 # repo-harness
 
-<p align="center">
-  <img src="docs/images/repo-harness-gptpro.png" alt="repo-harness architecture and ChatGPT Pro local planner workflow diagram" width="960">
-</p>
-
 `repo-harness` convierte las sesiones de programación con Claude/Codex en un
 workflow repo-local repetible. Incluye un CLI y hooks de skill/runtime que
 escriben contexto, planes, handoffs, checks y evidencias de review dentro del
@@ -30,10 +26,11 @@ Dirección del repositorio: `https://github.com/Ancienttwo/repo-harness`
 - **El estado de la sesión vive en archivos, no en el historial de chat.** Las
   distintas sesiones de agente —Claude, Codex, ahora o más tarde— se mantienen
   sincronizadas a través del repositorio en lugar de un hilo de chat. Cuando
-  arranca una sesión nueva, `.ai/hooks/session-start-context.sh` inyecta el
+  arranca una sesión nueva, el session-context builder in-process
+  (`src/cli/hook/session-context.ts`) inyecta el
   resume packet de la sesión anterior (`.ai/harness/handoff/resume.md`,
   `tasks/current.md`); al terminar la sesión y tras cada edición,
-  `finalize-handoff.sh` y `post-edit-guard.sh` escriben de vuelta el siguiente
+  los typed handlers `session-context`, `stop` y `mutation-observed` escriben de vuelta el siguiente
   handoff. Una tarea puede cortarse a mitad de camino y la siguiente sesión
   retoma directamente el next step exacto, los puntos de bloqueo y los archivos
   modificados sin tener que volver a inferirlos.
@@ -85,37 +82,32 @@ artifacts.
 ## Novedades
 
 Las notas de versión viven en [`docs/CHANGELOG.md`](docs/CHANGELOG.md). La línea
-actual es `0.9.2`.
+actual es `0.11.0`.
 
 ## Cómo funciona
 
-En conjunto hay tres capas:
+En conjunto hay tres capas y un único runtime typed para host events:
 
 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 adopt` o la
    migración escribe `docs/spec.md`, `plans/`, `tasks/`, `.ai/context/`,
-   `.ai/harness/`, helper scripts y `.ai/hooks/`.
+   `.ai/harness/` y helper scripts. `.ai/hooks/lib/workflow-state.sh` es solo
+   una proyección de operator helper.
 3. **Capa del host adapter**: el `~/.claude/settings.json` y el
    `~/.codex/hooks.json` a nivel de usuario enrutan los events de Claude/Codex
-   hacia `repo-harness-hook`. El hook entrypoint primero comprueba si el repo
-   actual tiene un `.ai/harness/workflow-contract.json`; si no hay opt in, sale en
-   silencio, y solo si hay opt in entra en los `.ai/hooks/*` del repo actual.
-
-Para `UserPromptSubmit`, el adapter contract público sigue siendo
-`repo-harness-hook UserPromptSubmit --route default`. El CLI route registry hace
-dispatch de esa route a `.ai/hooks/prompt-guard.sh`. El shell hook se sigue
-ocupando del parseo del host JSON, la lectura de los archivos de workflow, los
-side effects de plan capture, el render del quality gate y el stdout/stderr
-host-safe. La decisión sobre el prompt intent y el workflow state se delega al
-TypeScript decision engine detrás de `repo-harness-hook prompt-guard-decide`, que
-devuelve un action enum desde una decision table explícita. Así la configuración
-del host no cambia, pero la capa más propensa a errores —el classifier y la
-state-machine— deja de estar dispersa en ramas condicionales de shell.
+   hacia `repo-harness-hook`. Tras validar `.ai/harness/workflow-contract.json`,
+   el route registry usa `event + routeId + matcher` para invocar exactamente un
+   typed handler.
+
+Todos los events siguen `host adapter -> repo-harness-hook -> route registry ->
+typed handler`. `UserPromptSubmit.default` usa `prompt`; edit/bash/stop usan
+`mutation-observed`, `command-observed` y `stop`. No existe un segundo shell
+dispatcher ni un runtime distinto por provider.
 
 El invariante central: los hechos persistentes viven en el repositorio, no en la
-ventana de chat. Los hooks son solo aceleradores y guardrails; la verdadera
+ventana de chat. Los typed handlers son solo aceleradores y guardrails; la verdadera
 authority son los archivos de plan, contract, review, checks y handoff.
 
 ## Task Workflow: de Plan a Closeout
@@ -172,20 +164,20 @@ flowchart TD
 ## Bucles largos de producto
 
 Para trabajo Greenfield y Brownfield, adelanta la discovery y el juicio de
-engineering plan en Claude-Fable antes de pedirle a Codex que haga loops de
+engineering plan en el parent agent antes de pedirle a Codex que haga loops de
 ejecución:
 
-1. En Claude-Fable, usa gstack `office-hours` para product discovery o
-   `plan-eng-review` para review del plan de ingeniería. La salida debe ser los
-   development documents que fijan la intención de producto, la arquitectura, los
-   riesgos y el evidence contract.
+1. Antes de crear un contract, el parent agent invoca `geju` para abrir el marco y
+   después completa P1/P2/P3 con sus propias capacidades repo/runtime. Fija la
+   intención de producto, la arquitectura, los riesgos, el falsifier y el evidence
+   contract aceptados en los development documents.
 2. Convierte esos documentos en un PRD Sprint bajo `plans/prds/`, con un
    backlog ordenado y sub-plans detallados para cada execution slice.
 3. Crea un Codex Goal que apunte a ese archivo de sprint. repo-harness puede
    entonces proyectar cada sprint item por el flow normal plan -> contract ->
    worktree -> verification.
 
-Ese handoff mantiene precisos los loops largos: Claude-Fable se ocupa del juicio
+Ese handoff mantiene precisos los loops largos: el parent agent se ocupa del juicio
 amplio al inicio, el PRD Sprint es la durable source of truth, y Codex Goal mode
 retoma contra un sprint concreto en vez de reinterpretar el chat original.
 
@@ -200,8 +192,9 @@ recomienda al aplicar el settings merge.
 
 ### Instalar el CLI
 
-La ruta por defecto no requiere Node.js: el instalador usa Bun como runtime. Si
-Bun no existe, instala Bun primero y después instala el CLI `repo-harness`.
+La ruta por defecto no requiere Node.js: el instalador usa Bun >= 1.1.35 como
+runtime. Si Bun no existe o es anterior, lo instala o actualiza antes de
+instalar el CLI `repo-harness`.
 
 ```bash
 # macOS / Linux
@@ -212,7 +205,7 @@ irm https://raw.githubusercontent.com/Ancienttwo/repo-harness/main/install.ps1 |
 ```
 
 <details>
-<summary>¿Ya tienes Bun? Usa Bun primero, o npx como fallback</summary>
+<summary>¿Ya tienes Bun >= 1.1.35? Usa Bun primero, o npx como fallback</summary>
 
 ```bash
 # Bun (recomendado)
@@ -251,7 +244,7 @@ Aplica solo después de que el reporte del dry-run sea correcto:
 repo-harness adopt
 ```
 
-Para un proyecto o módulo nuevo, usa la branch command `repo-harness-scaffold`.
+Para un proyecto o módulo nuevo, usa el modo scaffold de `repo-harness-setup`.
 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.
 
@@ -264,7 +257,7 @@ El comando debería terminar imprimiendo `=== Migration Report ===`, e incluir:
 - `Host hook adapters are user-level:`: recordatorio de instalar los global adapters y de confiar en `~/.codex/hooks.json`
 - `Workflow migration:`: el plan de creación o refresco de las repo-local harness surfaces
 - `Helper runtime:`: la cadena de herramientas operativa que obtendrás tras aplicar
-- `--- External Tooling ---`: el routing de gstack/Waza/gbrain más las advisory de instalación/actualización
+- `--- External Tooling ---`: la guía de planning parent/Geju, la readiness de Waza y CodeGraph y las advisory de instalación/actualización
 
 ### Los dos comandos siguientes
 
@@ -339,36 +332,39 @@ auditado, y no es un shell arbitrario.
 
 ## Hook Authority Map
 
-- `.ai/hooks/` es la única shared hook implementation que se debe editar de forma prioritaria.
-- `~/.claude/settings.json` es el Claude adapter a nivel de usuario, encargado de hacer dispatch a los opted-in repos.
-- `~/.codex/hooks.json` es el Codex adapter a nivel de usuario, hace dispatch al mismo runner.
-- Los hook adapters repo-local `.claude/settings.json` y `.codex/hooks.json` son legacy project-level config y deben retirarse durante la migración.
-- Codex debe confiar en `~/.codex/hooks.json` en sus Settings para que los hooks se ejecuten.
-- Orden de depuración: user-level adapter config -> `repo-harness-hook` o el fallback `repo-harness hook` -> route registry -> `.ai/hooks/*`.
+`repo-harness-hook` es el único host-event runtime. El adapter a nivel de usuario
+solo entrega el event; route registry usa el tuple estable `event + routeId + matcher`
+para invocar exactamente un typed handler. `assets/hooks/lib/workflow-state.sh` y
+`.ai/hooks/lib/workflow-state.sh` son proyecciones de operator helper, no dispatchers.
 
+- `~/.claude/settings.json`: Claude adapter a nivel de usuario.
+- `~/.codex/hooks.json`: Codex adapter a nivel de usuario; requiere confianza en Settings.
+- `.claude/settings.json` / `.codex/hooks.json` repo-locales: inputs legacy que se retiran durante migration.
+- Los cambios de handler viven en `src/cli/hook/`; sincroniza la proyección con `bun run sync:hooks`.
 
-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.
+The installed adapter owns the managed hook routes. Each route invokes one typed
+handler; no existe un segundo runtime de shell ni un runtime específico por provider.
 
-| Route | Matcher | Scripts | Function |
+| Route | Matcher | Typed handler | 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.default` | all sessions | `src/cli/hook/session-context.ts` (in-process builder) | Injects prior handoff, sprint status, and read-only config-security findings before work starts. |
+| `PreToolUse.edit` | `Edit|Write` | `src/cli/hook/mutation-guard.ts` (in-process handler) | Enforces worktree policy and plan/contract readiness before implementation edits. |
+| `PreToolUse.subagent` | `Task|Agent|SendUserMessage` | `subagent` | Keeps delegated work returning through the parent session instead of leaking completion claims. |
+| `PostToolUse.edit` | `Edit|Write` | `mutation-observed` | Records the edit journal and controlled-file observations. |
+| `PostToolUse.bash` | `Bash` | `command-observed` | Observes command results and captures verification evidence without replacing the command runner. |
+| `PostToolUse.always` | all tools | `trace-observer` | Provides low-noise always-on trace and runtime observation. |
+| `UserPromptSubmit.default` | all prompts | `prompt` | Classifies prompt intent, routes planning/check/hunt hints, and renders host-safe workflow guidance. |
+| `Stop.default` | session stop | `src/cli/hook/stop-handler.ts` (in-process handler) | Finalizes handoff and guards against ending with unresolved draft-plan or completion evidence gaps. |
 
-`SessionStart` ejecuta dos scripts ordenados antes de empezar el trabajo:
+`SessionStart` ejecuta el session-context builder in-process, que ensambla el contexto antes de empezar el trabajo:
 
 ```mermaid
 flowchart LR
-  SessionStart["Claude/Codex SessionStart"] --> Ctx["session-start-context.sh<br/>contexto de resume + handoff"]
-  Ctx --> Sec["security-sentinel.sh<br/>escaneo de configuración de solo lectura, fingerprint-gated"]
-  Sec --> SSOut["SessionStart additionalContext<br/>estado de la sesión anterior + hallazgos de SecurityConfig"]
+  SessionStart["Claude/Codex SessionStart"] --> Ctx["session-context.ts<br/>in-process builder"]
+  Ctx --> Resume["contexto de resume + handoff"]
+  Ctx --> Sec["security scan<br/>escaneo de configuración de solo lectura, fingerprint-gated"]
+  Resume --> SSOut["SessionStart additionalContext<br/>estado de la sesión anterior + hallazgos de SecurityConfig"]
+  Sec --> SSOut
 ```
 
 El prompt guard tiene un paso interno adicional:
@@ -378,17 +374,14 @@ flowchart LR
   Host["Claude/Codex UserPromptSubmit"] --> Adapter["user-level adapter"]
   Adapter --> CLI["repo-harness-hook UserPromptSubmit --route default"]
   CLI --> Route["route registry"]
-  Route --> Shell[".ai/hooks/prompt-guard.sh"]
-  Shell --> Decision["repo-harness-hook prompt-guard-decide<br/>TypeScript decision table"]
-  Decision --> Action["single action enum"]
-  Action --> Shell
-  Shell --> RouteHint["Waza route hint<br/>think/planning explícito coincide primero → /think"]
-  Shell --> HostOutput["host-safe allow, advice, block, or done gate output"]
+  Route --> Handler["prompt handler<br/>typed decision table"]
+  Handler --> RouteHint["Waza route hint<br/>think/planning explícito coincide primero → /think"]
+  Handler --> HostOutput["host-safe allow, advice, block, or done gate output"]
 ```
 
-La capa de shell sigue teniendo la authority del sistema de archivos y los side
-effects. TypeScript solo tiene el classifier más la decision table de
-`intent x plan state`.
+El typed handler posee el parseo de entrada, el estado de archivos y los side effects
+declarados; el runtime solo unifica el host output. AcceptanceReceipt es la authority
+de closeout y review Markdown es una proyección.
 
 ## Hook Failure Playbook
 
@@ -410,7 +403,8 @@ Guards habituales:
 ## Repo Workflow
 
 - Root routing docs: `CLAUDE.md`, `AGENTS.md`
-- Shared hook layer: `.ai/hooks/`
+- Typed hook runtime: `src/cli/hook/` (a través de `repo-harness-hook`)
+- Operator helper projection: `.ai/hooks/lib/workflow-state.sh`
 - User-level adapter layer: `~/.claude/settings.json`, `~/.codex/hooks.json`
 - Active execution surface: `tasks/`
 - Plan source of truth: `plans/`
@@ -419,8 +413,8 @@ Guards habituales:
 
 ## Release actual
 
-- npm package: `repo-harness@0.9.2`
-- Generated workflow stamp: `repo-harness@0.9.2+template@0.9.2`
+- npm package: `repo-harness@0.11.0`
+- Generated workflow stamp: `repo-harness@0.11.0+template@0.11.0`
 - GitHub repository: `Ancienttwo/repo-harness`
 - Release history: [`docs/CHANGELOG.md`](docs/CHANGELOG.md)
 
@@ -435,10 +429,6 @@ Gracias a [TW93](https://x.com/HiTw93), autor de Waza. Los skills centrales
 `think`, `hunt`, `check` y `health` dan forma al ritmo diario de planning, bug
 hunt y verification de `repo-harness`.
 
-Gracias a [Garry Tan](https://x.com/garrytan), autor de gstack y gbrain. Ambos
-influyeron en el workflow de product discovery, plan/design review, release
-documentation, knowledge sync y handoff retrieval.
-
 Gracias a [Peter Steinberger](https://x.com/steipete), autor de Oracle
 (`@steipete/oracle`, MIT). Es el motor de consult de navegador GPT Pro / ChatGPT
 Web por defecto de `chatgpt-browser`: el provider Oracle ejecuta el binario oracle
@@ -458,35 +448,53 @@ Mantén esta atribución opt-in y visible por commit. No la incorpores en script
 
 ## Action Command Skills
 
-Los command facades públicos están en `assets/skill-commands/`; preservan la
-compatibilidad de discovery por skills, mientras el CLI y los hooks ejecutan:
-
-- Planning / review: `repo-harness-plan`, `repo-harness-review`, `repo-harness-autoplan`
-- Product planning layer: `repo-harness-prd` (activa `$geju`, luego usa drafting Claude-first con `claude -p --model opus`; Codex queda solo como fallback)
-- Sprint program layer: `repo-harness-sprint` (convierte un PRD en un backlog ordenado bajo `plans/sprints/`)
-- Goal session layer: `repo-harness-goal` / `repo-harness:goal` (prepara prompts `/goal` de Codex/Claude desde un PRD o Sprint detallado; si falta el documento, lo pide primero)
-- 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`
+Los packages canónicos están en `assets/skills/` (packages canónicos
+activados) y en `assets/skill-commands/` (sobrevivientes que evolucionan en su
+sitio); preservan el alcance de discovery por skills, mientras el CLI y los
+hooks ejecutan:
+
+- Router: `repo-harness` (Skill raíz, sincronizado sin condición en cada
+  profile)
+- Capa setup: `repo-harness-setup` (modos adopt/init, migrate, upgrade,
+  repair, scaffold, y capability-configuration; router-only, nunca
+  descubierto automáticamente por un profile)
+- Planning: `repo-harness-plan` (crea un plan decision-complete, o revisa uno
+  existente)
+- Capa product planning: `repo-harness-product` (modos PRD, Sprint, y Goal; el
+  modo PRD activa `$geju`, luego usa drafting Claude-first con `claude -p
+  --model opus`, Codex queda solo como fallback; el modo Sprint convierte un
+  PRD en un backlog ordenado bajo `plans/sprints/`, cada fila se expande con
+  `$think` antes del contract flow; el modo Goal prepara prompts `/goal` de
+  Codex/Claude desde un PRD o Sprint detallado y lo pide primero si falta)
+- Verificación: `repo-harness-check` (checks de workflow/release más una
+  referencia deploy-readiness)
+- Release: `repo-harness-ship`
+- Architecture: `repo-harness-architecture`
+- Cross-model review: `repo-harness-cross-review` (host-aware; se instala en
+  ambos hosts para el profile strict)
+- Integración ChatGPT: `repo-harness-chatgpt` (consult/continuation de Oracle
+  browser/GPT Pro, setup de MCP Connector, bridge handoff, y read-back
+  evidence; solo setup explícito, nunca implicado por product planning)
 
 La cadena de planning está separada por capas:
 
 ```text
-idea -> repo-harness-prd -> repo-harness-sprint from-prd -> repo-harness-goal
+idea -> repo-harness-product (modo PRD) -> repo-harness-product (modo Sprint, from-prd) -> repo-harness-product (modo Goal)
 ```
 
-Usa `repo-harness-prd` cuando la fuente todavía es una idea de producto: primero
-ejecuta un direction pass con `$geju`, luego pide a Claude vía `claude -p --model opus` que
-redacte el PRD, con Codex solo como fallback. Usa
-`repo-harness-sprint from-prd <plans/prds/*.prd.md>` para convertir un PRD
-aprobado en un Sprint backlog ordenado con acceptance lines verificables por
-máquina. Usa `repo-harness-goal` solo cuando ya exista un PRD o Sprint detallado;
-prepara un prompt `/goal` acotado para Codex/Claude y mantiene el PRD/Sprint como
-source of truth. Si falta ese documento, el goal command debe pedirlo antes de
-empezar implementación desde el chat.
+Usa el modo PRD de `repo-harness-product` cuando la fuente todavía es una idea
+de producto: primero ejecuta un direction pass con `$geju`, luego pide a
+Claude vía `claude -p --model opus` que redacte el PRD, con Codex solo como
+fallback. Usa su modo Sprint (`from-prd <plans/prds/*.prd.md>`) para convertir
+un PRD aprobado en un Sprint backlog ordenado con acceptance lines
+verificables por máquina. Usa su modo Goal solo cuando ya exista un PRD o
+Sprint detallado; prepara un prompt `/goal` acotado para Codex/Claude y
+mantiene el PRD/Sprint como source of truth. Si falta ese documento, el modo
+Goal debe pedirlo antes de empezar implementación desde el chat.
 
-`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.
+`repo-harness adopt` se usa para repositorios existentes; el modo scaffold de
+`repo-harness-setup` queda para crear proyectos o módulos nuevos. `hooks-init`,
+`docs-init` y `create-project-dirs` son pasos internos, no commands públicos.
 
 ## Maintainer Reference
 
@@ -545,7 +553,7 @@ bun test
 bash scripts/check-task-sync.sh
 bash scripts/check-task-workflow.sh --strict
 bun scripts/inspect-project-state.ts --repo . --format text
-bash scripts/migrate-project-template.sh --repo . --dry-run
+bun src/cli/index.ts adopt --repo . --dry-run
 bash scripts/check-agent-tooling.sh --host both --check-updates
 bun run benchmark:skills --eval route-workflow-check
 ```
@@ -582,7 +590,7 @@ bun run benchmark:skills --eval repair-agents-task-sync
 - Scaffolding scripts:
   - `scripts/init-project.sh`
   - `scripts/create-project-dirs.sh`
-- Legacy-doc migrator: `scripts/migrate-workflow-docs.ts`
+- Canonical adoption planner: `src/core/adoption/standard-plan.ts`
 
 ## Generated vs Self-Hosted Hook Projection
 
@@ -620,7 +628,7 @@ bash scripts/check-architecture-sync.sh
 bash scripts/check-task-sync.sh
 bash scripts/check-task-workflow.sh --strict
 bun scripts/inspect-project-state.ts --repo . --format text
-bash scripts/migrate-project-template.sh --repo . --dry-run
+bun src/cli/index.ts adopt --repo . --dry-run
 bash scripts/check-agent-tooling.sh --host both --check-updates
 bun run benchmark:skills --eval route-workflow-check
 ```