repo-harness 0.5.1 → 0.5.3

package/README.es.md

@@ -1,5 +1,9 @@
 # repo-harness
 
+<p align="center">
+  <img src="docs/images/image.png" alt="One next button joining Claude and Codex under repo-harness workflow rules" width="760">
+</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
@@ -43,43 +47,20 @@ Dirección del repositorio: `https://github.com/Ancienttwo/repo-harness`
   1KB o consulta el índice, en vez de gastar miles de tokens redescubriendo la
   estructura.
 
-## Novedades en 0.2.1
-
-- **Comando de inicialización global (`repo-harness init`).** Un solo comando
-  inicializa el entorno global de Claude: essential plugins, policy
-  hooks configurables (worktree guard, atomic commit/pending), LSP plugins
-  opcionales según el tipo de proyecto y cuatro hook profiles (`standard`,
-  `minimal`, `biome`, `biome-strict`). Ejecuta
-  `npx -y repo-harness init`; no necesitas clonar el repositorio fuente.
-- **Comando de adopción del repo (`repo-harness adopt`).** La instalación y el
-  refresco de repos existentes tienen su propia superficie de comando, manteniendo
-  la ruta de migración repo-local anterior mientras `init` queda dedicado al
-  runtime global.
-- **Auto-recuperación del índice CodeGraph.** Si el prompt hook detecta intención
-  de navegación estructural y el repo no tiene índice `.codegraph`, inicializa el
-  índice con el binario CodeGraph local o visible en PATH antes de emitir la pista.
-  Sigue siendo advisory: no instala dependencias, no ejecuta el readiness probe
-  pesado y no bloquea el prompt si CodeGraph no está disponible.
-- **Centinela de seguridad (`repo-harness security scan` + `security-sentinel.sh`).**
-  Una verificación de solo lectura sobre las superficies de inyección de
-  configuración de alto valor (`~/.claude/settings.json`, `~/.codex/hooks.json`,
-  el `.vscode/tasks.json` repo-local y los adapters legacy a nivel de proyecto
-  `.claude`/`.codex`). Marca patrones de comando sospechosos —pipes de remote
-  shell, base64-decode-to-exec, `osascript`, persistencia con
-  `launchctl`/`crontab`, netcat, ejecución inline de intérpretes—, además de
-  hooks no gestionados y tareas `folderOpen` de ejecución automática, y nunca
-  modifica ninguna configuración. El centinela de `SessionStart` toma una huella
-  de este conjunto y solo reescanea cuando la huella cambia, para no generar
-  ruido en el session-start. Auditoría bajo demanda:
-  `repo-harness security scan --json`.
-- **Ciclo de vida draft-plan de Claude/Codex.** El Plan mode tiene explícitamente
-  dos etapas: Draft y Approved. Los hooks reconocen la intención de crear un plan
-  y rastrean la pending orchestration; un stop gate (`stop-orchestrator.sh`) exige
-  que la sesión haga una pasada de autorevisión antes de terminar con el plan sin
-  definir. Captura un borrador con `scripts/capture-plan.sh --slug <slug> --title
-  <title> --status Draft`, después promociónalo a Approved y proyéctalo a
-  ejecución con `--execute` o `scripts/plan-to-todo.sh --plan <plan>`. Los plans
-  se convierten en la fuente de verdad a nivel de archivo en `plans/`.
+En un repositorio adoptado, la superficie se mantiene pequeña:
+
+| Surface | Propósito |
+| --- | --- |
+| `docs/spec.md` y `docs/reference-configs/` | Estándares compartidos e intención de producto estable que cada sesión de agente puede leer. |
+| `plans/`, `plans/prds/` y `plans/sprints/` | Work packages decision-complete antes de empezar la implementación. |
+| `tasks/contracts/`, `tasks/reviews/` y `.ai/harness/checks/` | Scope, verificación y evidencia de review para probar que el trabajo terminó. |
+| `.ai/harness/handoff/` y `tasks/current.md` | Session journal y estado resumible, derivados de workflow artifacts en vez de chat memory. |
+
+## Novedades en 0.5.3
+
+- **Runtime updates con versión fija.** `repo-harness update --version <version>` ahora instala el package `repo-harness@<version>` solicitado, en vez de ser interceptado por el shortcut global de versión de la CLI.
+- **Version shortcut preservado.** `repo-harness --version` y `repo-harness -V` siguen mostrando la versión de la CLI cuando se usan en el nivel superior.
+- **Patch-only surface.** No cambian hook routes, setup checks, security scan ni workflow contracts, salvo el fix del option del comando update.
 
 ## Qué hace el producto
 
@@ -301,7 +282,7 @@ El comando debería terminar imprimiendo `=== Migration Report ===`, e incluir:
 - `Host hook config target: user-level ~/.claude/settings.json and ~/.codex/hooks.json`: dónde está la capa del adapter
 - `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 scripts:`: la cadena de herramientas operativa que obtendrás tras aplicar
+- `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
 
 ### Los dos comandos siguientes
@@ -323,6 +304,22 @@ Si la salida del dry-run no es correcta, detente aquí primero y lee
 - 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/*`.
 
+
+The installed adapter owns eight managed hook routes. The route tuple
+`event + routeId + matcher` is the stable contract; script names are the current
+implementation under `assets/hooks/` or a repo-pinned `.ai/hooks/` copy.
+
+| Route | Matcher | Scripts | Function |
+| --- | --- | --- | --- |
+| `SessionStart.default` | all sessions | `session-start-context.sh`, `security-sentinel.sh` | Injects prior handoff, sprint status, and read-only config-security findings before work starts. |
+| `PreToolUse.edit` | `Edit|Write` | `worktree-guard.sh`, `pre-edit-guard.sh` | Enforces worktree policy and plan/contract readiness before implementation edits. |
+| `PreToolUse.subagent` | `Task|Agent|SendUserMessage` | `subagent-return-channel-guard.sh` | Keeps delegated work returning through the parent session instead of leaking completion claims. |
+| `PostToolUse.edit` | `Edit|Write` | `post-edit-guard.sh` | Records edit traces, refreshes handoff/task status, and queues architecture drift when controlled files change. |
+| `PostToolUse.bash` | `Bash` | `post-bash.sh` | Observes command results and captures verification evidence without replacing the command runner. |
+| `PostToolUse.always` | all tools | `post-tool-observer.sh` | Provides low-noise always-on trace and runtime observation; stale pinned copies soft-skip with a refresh hint. |
+| `UserPromptSubmit.default` | all prompts | `prompt-guard.sh` | Classifies prompt intent, routes planning/check/hunt hints, and renders host-safe workflow guidance. |
+| `Stop.default` | session stop | `stop-orchestrator.sh` | Finalizes handoff and guards against ending with unresolved draft-plan or completion evidence gaps. |
+
 `SessionStart` ejecuta dos scripts ordenados antes de empezar el trabajo:
 
 ```mermaid
@@ -380,8 +377,8 @@ Guards habituales:
 
 ## Release actual
 
-- npm package: `repo-harness@0.5.1`
-- Generated workflow stamp: `repo-harness@0.5.1+template@0.5.1`
+- npm package: `repo-harness@0.5.3`
+- Generated workflow stamp: `repo-harness@0.5.3+template@0.5.3`
 - GitHub repository: `Ancienttwo/repo-harness`
 - Release history: [`docs/CHANGELOG.md`](docs/CHANGELOG.md)
 
@@ -393,6 +390,13 @@ Guards habituales:
   - `scripts/inspect-project-state.ts`
   - `scripts/migrate-workflow-docs.ts`
   - `assets/workflow-contract.v1.json`
+- Runtime mode is configurable with template vars:
+  - `{{RUNTIME_MODE}}`
+  - `{{RUNTIME_PROFILE}}`
+  - `{{RECOVERY_PROFILE}}`
+  - `{{STATE_PROFILE}}`
+- Question-pack source of truth is in:
+  - `assets/initializer-question-pack.v4.json`
 - Los generated repos usan por defecto el repo-local harness flow:
   - `docs/spec.md -> plans/ -> tasks/contracts/ -> tasks/reviews/ -> .ai/context/context-map.json -> .ai/harness/*`
 - `repo-harness update` refresca las runtime pieces de usuario:
@@ -419,6 +423,17 @@ 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.
 
+
+### Atribución de contribuidor en GitHub
+
+Cuando Codex contribuya materialmente a un commit, usa el trailer co-author estándar de GitHub al final del commit message:
+
+```text
+Co-authored-by: codex <codex@openai.com>
+```
+
+Mantén esta atribución opt-in y visible por commit. No la incorpores en scripts de commit ni hooks downstream de repo-harness salvo que ese repo adopte explícitamente la misma política.
+
 ## Action Command Skills
 
 Los command facades públicos están en `assets/skill-commands/`; preservan la
@@ -462,6 +477,23 @@ bun scripts/inspect-project-state.ts --repo . --format text
 bash scripts/migrate-project-template.sh --repo . --dry-run
 ```
 
+
+### Runtime reference docs
+
+Generic repo-harness runtime/reference docs live in the installed package under
+`assets/reference-configs/` and are resolved through the CLI:
+
+```bash
+repo-harness docs list
+repo-harness docs path harness-overview
+repo-harness docs show harness-overview
+```
+
+Generated and migrated repos still keep `docs/reference-configs/*.md`, but
+those files are deterministic pointer stubs. Repo-local workflow state,
+policy, checks, runs, handoff packets, context maps, and helper snapshots stay
+under `.ai/`.
+
 ### Template assembly
 
 ```bash
@@ -478,7 +510,23 @@ 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
 bash scripts/check-agent-tooling.sh --host both --check-updates
-bun run benchmark:skills --dry-run
+bun run benchmark:skills --eval route-workflow-check
+```
+
+
+### Local benchmark skeleton
+
+```bash
+bun run benchmark:skills --eval route-workflow-check
+```
+
+Eval output is the release/readiness evidence path; dry-run benchmark wiring is only a smoke and is not skill-effectiveness evidence.
+
+
+### Run one eval across both Claude and Codex
+
+```bash
+bun run benchmark:skills --eval repair-agents-task-sync
 ```
 
 ## Key Files
@@ -488,8 +536,54 @@ bun run benchmark:skills --dry-run
 - Plan mapping: `assets/plan-map.json`
 - Question-pack: `assets/initializer-question-pack.v4.json`
 - Shared hooks: `assets/hooks/`
+- Runtime reference docs: `assets/reference-configs/` via `repo-harness docs`
 - Workflow contract: `assets/workflow-contract.v1.json`
 - Hook operations reference: `docs/reference-configs/hook-operations.md`
 - Template assembler: `scripts/assemble-template.ts`
 - State inspector: `scripts/inspect-project-state.ts`
+- External tooling detector: `scripts/check-agent-tooling.sh`
+- Scaffolding scripts:
+  - `scripts/init-project.sh`
+  - `scripts/create-project-dirs.sh`
 - Legacy-doc migrator: `scripts/migrate-workflow-docs.ts`
+
+## Generated vs Self-Hosted Hook Parity
+
+- El comportamiento downstream de hooks lo define la salida generada desde `assets/hooks/` y `assets/reference-configs/`.
+- Este repo dogfoodea el mismo contract, pero el comportamiento self-host no se sincroniza mágicamente con los generated repos; cada cambio debe actualizar explícitamente ambas superficies cuando aplique.
+- Todo cambio de hook debe indicar si afecta a `self-host`, `generated` o `both`.
+
+## Package Manager Defaults
+
+- Prioridad general por defecto: `bun > pnpm > npm`
+- **Plan G/H** (Python-centric) usa **`uv`** como primary package manager por defecto.
+
+## Runtime Profiles
+
+- `Plan-only (recommended)` (default)
+- `Plan + Permissionless`
+- `Standard (ask before each action)`
+
+Se configura en `assets/initializer-question-pack.v4.json` y lo consume `scripts/initializer-question-pack.ts`.
+
+## Verification
+
+Para release review usa el gate único equivalente a CI:
+
+```bash
+bun run check:ci
+```
+
+Ese gate se expande a los checks propios del repo; `bun run check:release` solo añade el preflight de npm unpublished-version antes de delegar al mismo gate.
+
+```bash
+bun test
+bash scripts/check-deploy-sql-order.sh
+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
+bash scripts/check-agent-tooling.sh --host both --check-updates
+bun run benchmark:skills --eval route-workflow-check
+```

package/README.fr.md

@@ -1,5 +1,9 @@
 # repo-harness
 
+<p align="center">
+  <img src="docs/images/image.png" alt="One next button joining Claude and Codex under repo-harness workflow rules" width="760">
+</p>
+
 `repo-harness` transforme les sessions de code Claude/Codex en workflow
 repo-local répétable. Il fournit un CLI et des hooks skill/runtime qui écrivent
 le contexte, les plans, les handoffs, les checks et les preuves de review dans le
@@ -43,45 +47,20 @@ Adresse du dépôt : `https://github.com/Ancienttwo/repo-harness`
   1 Ko ou interroge l'index, au lieu de dépenser des milliers de tokens à
   redécouvrir la structure.
 
-## Nouveautés de la 0.2.1
-
-- **Commande d'initialisation globale (`repo-harness init`).** Une seule commande
-  amorce l'environnement Claude global : essential plugins,
-  policy hooks configurables (worktree guard, atomic commit/pending), LSP plugins
-  optionnels selon le type de projet, et quatre hook profiles (`standard`,
-  `minimal`, `biome`, `biome-strict`). Exécutez
-  `npx -y repo-harness init` ; aucun clone du dépôt source n'est nécessaire.
-- **Commande d'adoption du dépôt (`repo-harness adopt`).** L'installation
-  et le rafraîchissement des dépôts existants ont leur propre surface de commande,
-  tout en conservant l'ancien chemin de migration repo-local et en gardant `init`
-  dédié au runtime global.
-- **Auto-réparation de l'index CodeGraph.** Quand le prompt hook détecte une
-  intention de navigation structurelle et que le dépôt n'a pas d'index
-  `.codegraph`, il initialise l'index avec le binaire CodeGraph local ou visible
-  dans PATH avant d'émettre l'indication de route. Cela reste advisory : pas
-  d'installation de dépendances, pas de readiness probe lourd, et pas de blocage
-  du prompt si CodeGraph est indisponible.
-- **Sentinelle de sécurité (`repo-harness security scan` +
-  `security-sentinel.sh`).** Une vérification en lecture seule sur les surfaces
-  d'injection de configuration à forte valeur (`~/.claude/settings.json`,
-  `~/.codex/hooks.json`, le `.vscode/tasks.json` repo-local, ainsi que les adapter
-  legacy de niveau projet `.claude`/`.codex`). Elle signale les motifs de commandes
-  dangereux — pipes vers un remote shell, base64 décodé puis exécuté, `osascript`,
-  persistance via `launchctl`/`crontab`, netcat, exécution d'interpréteur inline —
-  ainsi que les hooks non gérés et les tâches `folderOpen` auto-exécutées, et elle
-  ne réécrit jamais aucune configuration. La sentinelle `SessionStart` calcule une
-  empreinte de cet ensemble de fichiers et ne rescanne que lorsque l'empreinte
-  change, sans produire de bruit au démarrage de session. Audit à la demande :
-  `repo-harness security scan --json`.
-- **Cycle de vie draft-plan Claude/Codex.** Le Plan mode se divise explicitement en
-  deux étapes : Draft et Approved. Les hooks détectent l'intention de créer un plan
-  et suivent le pending orchestration ; le stop gate (`stop-orchestrator.sh`) exige
-  que la session fasse une passe d'auto-review avant de se terminer alors qu'un plan
-  n'est pas finalisé. Capturez un brouillon avec
-  `scripts/capture-plan.sh --slug <slug> --title <title> --status Draft`, puis
-  passez en Approved après validation et projetez-le dans l'exécution avec
-  `--execute` ou `scripts/plan-to-todo.sh --plan <plan>`. plans/ devient la source
-  de vérité au niveau fichier.
+Dans un dépôt adopté, la surface à comprendre reste volontairement réduite :
+
+| Surface | Rôle |
+| --- | --- |
+| `docs/spec.md` et `docs/reference-configs/` | Standards partagés et intention produit stable lisibles par chaque session d'agent. |
+| `plans/`, `plans/prds/` et `plans/sprints/` | Work packages decision-complete avant le début de l'implémentation. |
+| `tasks/contracts/`, `tasks/reviews/` et `.ai/harness/checks/` | Scope, vérification et preuves de review pour démontrer que le travail est terminé. |
+| `.ai/harness/handoff/` et `tasks/current.md` | Session journal et état resumable dérivés des workflow artifacts plutôt que de la chat memory. |
+
+## Nouveautés de la 0.5.3
+
+- **Runtime updates épinglés.** `repo-harness update --version <version>` installe maintenant le package `repo-harness@<version>` demandé au lieu d'être intercepté par le raccourci global de version de la CLI.
+- **Version shortcut préservé.** `repo-harness --version` et `repo-harness -V` continuent d'afficher la version CLI lorsqu'ils sont utilisés au niveau supérieur.
+- **Patch-only surface.** Aucun changement de hook route, setup check, security scan ou workflow contract au-delà du fix de l'option du command update.
 
 ## Ce que fait le produit
 
@@ -307,7 +286,7 @@ La commande doit se terminer par `=== Migration Report ===` et inclure :
 - `Host hook config target: user-level ~/.claude/settings.json and ~/.codex/hooks.json` : où se trouve la couche adapter
 - `Host hook adapters are user-level:` : rappel d'installer les global adapters, et de faire confiance à `~/.codex/hooks.json`
 - `Workflow migration:` : le plan de création ou de rafraîchissement des repo-local harness surfaces
-- `Helper scripts:` : la chaîne d'outils opérationnels obtenue après application
+- `Helper runtime:` : la chaîne d'outils opérationnels obtenue après application
 - `--- External Tooling ---` : le routing gstack/Waza/gbrain ainsi que les conseils d'installation/mise à jour advisory
 
 ### Les deux commandes à lancer ensuite
@@ -329,6 +308,22 @@ Si la sortie du dry-run est incorrecte, arrêtez-vous ici et lisez
 - Codex doit faire confiance à `~/.codex/hooks.json` dans Settings pour que les hooks s'exécutent.
 - Ordre de débogage : user-level adapter config -> `repo-harness-hook` ou fallback `repo-harness hook` -> route registry -> `.ai/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.
+
+| Route | Matcher | Scripts | Function |
+| --- | --- | --- | --- |
+| `SessionStart.default` | all sessions | `session-start-context.sh`, `security-sentinel.sh` | Injects prior handoff, sprint status, and read-only config-security findings before work starts. |
+| `PreToolUse.edit` | `Edit|Write` | `worktree-guard.sh`, `pre-edit-guard.sh` | Enforces worktree policy and plan/contract readiness before implementation edits. |
+| `PreToolUse.subagent` | `Task|Agent|SendUserMessage` | `subagent-return-channel-guard.sh` | Keeps delegated work returning through the parent session instead of leaking completion claims. |
+| `PostToolUse.edit` | `Edit|Write` | `post-edit-guard.sh` | Records edit traces, refreshes handoff/task status, and queues architecture drift when controlled files change. |
+| `PostToolUse.bash` | `Bash` | `post-bash.sh` | Observes command results and captures verification evidence without replacing the command runner. |
+| `PostToolUse.always` | all tools | `post-tool-observer.sh` | Provides low-noise always-on trace and runtime observation; stale pinned copies soft-skip with a refresh hint. |
+| `UserPromptSubmit.default` | all prompts | `prompt-guard.sh` | Classifies prompt intent, routes planning/check/hunt hints, and renders host-safe workflow guidance. |
+| `Stop.default` | session stop | `stop-orchestrator.sh` | Finalizes handoff and guards against ending with unresolved draft-plan or completion evidence gaps. |
+
 `SessionStart` exécute deux scripts ordonnés avant le début du travail :
 
 ```mermaid
@@ -386,8 +381,8 @@ Guards courants :
 
 ## Release actuelle
 
-- npm package : `repo-harness@0.5.1`
-- Generated workflow stamp : `repo-harness@0.5.1+template@0.5.1`
+- npm package : `repo-harness@0.5.3`
+- Generated workflow stamp : `repo-harness@0.5.3+template@0.5.3`
 - GitHub repository : `Ancienttwo/repo-harness`
 - Release history : [`docs/CHANGELOG.md`](docs/CHANGELOG.md)
 
@@ -399,6 +394,13 @@ Guards courants :
   - `scripts/inspect-project-state.ts`
   - `scripts/migrate-workflow-docs.ts`
   - `assets/workflow-contract.v1.json`
+- Runtime mode is configurable with template vars:
+  - `{{RUNTIME_MODE}}`
+  - `{{RUNTIME_PROFILE}}`
+  - `{{RECOVERY_PROFILE}}`
+  - `{{STATE_PROFILE}}`
+- Question-pack source of truth is in:
+  - `assets/initializer-question-pack.v4.json`
 - Les generated repos utilisent par défaut le repo-local harness flow :
   - `docs/spec.md -> plans/ -> tasks/contracts/ -> tasks/reviews/ -> .ai/context/context-map.json -> .ai/harness/*`
 - `repo-harness update` rafraîchit les runtime pieces utilisateur :
@@ -425,6 +427,17 @@ Merci à [Garry Tan](https://x.com/garrytan), auteur de gstack et gbrain. Ils on
 influencé le workflow de product discovery, plan/design review, release
 documentation, knowledge sync et handoff retrieval.
 
+
+### Attribution GitHub des contributeurs
+
+Lorsque Codex contribue matériellement à un commit, utilisez le trailer co-author standard de GitHub à la fin du commit message :
+
+```text
+Co-authored-by: codex <codex@openai.com>
+```
+
+Gardez cette attribution opt-in et visible commit par commit. Ne l'intégrez pas aux scripts de commit ni aux hooks repo-harness downstream sauf si ce dépôt adopte explicitement la même politique.
+
 ## Action Command Skills
 
 Les command facades publics se trouvent dans `assets/skill-commands/` ; ils
@@ -469,6 +482,23 @@ bun scripts/inspect-project-state.ts --repo . --format text
 bash scripts/migrate-project-template.sh --repo . --dry-run
 ```
 
+
+### Runtime reference docs
+
+Generic repo-harness runtime/reference docs live in the installed package under
+`assets/reference-configs/` and are resolved through the CLI:
+
+```bash
+repo-harness docs list
+repo-harness docs path harness-overview
+repo-harness docs show harness-overview
+```
+
+Generated and migrated repos still keep `docs/reference-configs/*.md`, but
+those files are deterministic pointer stubs. Repo-local workflow state,
+policy, checks, runs, handoff packets, context maps, and helper snapshots stay
+under `.ai/`.
+
 ### Template assembly
 
 ```bash
@@ -485,7 +515,23 @@ 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
 bash scripts/check-agent-tooling.sh --host both --check-updates
-bun run benchmark:skills --dry-run
+bun run benchmark:skills --eval route-workflow-check
+```
+
+
+### Local benchmark skeleton
+
+```bash
+bun run benchmark:skills --eval route-workflow-check
+```
+
+Eval output is the release/readiness evidence path; dry-run benchmark wiring is only a smoke and is not skill-effectiveness evidence.
+
+
+### Run one eval across both Claude and Codex
+
+```bash
+bun run benchmark:skills --eval repair-agents-task-sync
 ```
 
 ## Key Files
@@ -495,8 +541,54 @@ bun run benchmark:skills --dry-run
 - Plan mapping : `assets/plan-map.json`
 - Question-pack : `assets/initializer-question-pack.v4.json`
 - Shared hooks : `assets/hooks/`
+- Runtime reference docs: `assets/reference-configs/` via `repo-harness docs`
 - Workflow contract : `assets/workflow-contract.v1.json`
 - Hook operations reference : `docs/reference-configs/hook-operations.md`
 - Template assembler : `scripts/assemble-template.ts`
 - State inspector : `scripts/inspect-project-state.ts`
+- External tooling detector: `scripts/check-agent-tooling.sh`
+- Scaffolding scripts:
+  - `scripts/init-project.sh`
+  - `scripts/create-project-dirs.sh`
 - Legacy-doc migrator : `scripts/migrate-workflow-docs.ts`
+
+## Generated vs Self-Hosted Hook Parity
+
+- Le comportement downstream des hooks est défini par la sortie générée depuis `assets/hooks/` et `assets/reference-configs/`.
+- Ce repo dogfoode le même contract, mais le comportement self-host ne se synchronise pas magiquement avec les generated repos ; un changement doit mettre à jour explicitement les deux surfaces lorsque nécessaire.
+- Chaque changement de hook doit dire s'il affecte `self-host`, `generated` ou `both`.
+
+## Package Manager Defaults
+
+- Priorité générale par défaut : `bun > pnpm > npm`
+- **Plan G/H** (Python-centric) utilise **`uv`** comme primary package manager par défaut.
+
+## Runtime Profiles
+
+- `Plan-only (recommended)` (default)
+- `Plan + Permissionless`
+- `Standard (ask before each action)`
+
+Configuré dans `assets/initializer-question-pack.v4.json` et consommé par `scripts/initializer-question-pack.ts`.
+
+## Verification
+
+Pour la release review, utilisez le gate unique équivalent CI :
+
+```bash
+bun run check:ci
+```
+
+Ce gate se développe vers les checks possédés par le repo ; `bun run check:release` ajoute seulement le preflight npm unpublished-version avant de déléguer au même gate.
+
+```bash
+bun test
+bash scripts/check-deploy-sql-order.sh
+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
+bash scripts/check-agent-tooling.sh --host both --check-updates
+bun run benchmark:skills --eval route-workflow-check
+```