repo-harness 0.7.0 → 0.7.2

package/.agents/skills/repo-harness-chatgpt-browser/SKILL.md

@@ -18,32 +18,42 @@ Use this skill when the user asks to consult ChatGPT Web, GPT Pro, browser GPT,
 repo-harness chatgpt browser-consult --repo . --dry-run --prompt "<prompt>" --file <path>
 ```
 
-5. For readiness, run:
+5. For Oracle provider readiness, run:
 
 ```bash
-repo-harness chatgpt browser-doctor --repo .
+repo-harness chatgpt browser-doctor --repo . --provider oracle --json
 ```
 
-6. Use browser consult for planning, review, critique, and goal generation. Do not use it as the executor for code edits.
-7. Save useful results into repo-harness artifacts with repo-relative `--write-output` paths such as:
+6. Oracle's published CLI requires `node >=24`, but that requirement belongs to the resolved Oracle binary. Do not raise repo-harness' overall runtime floor or add Oracle as an implicit dependency just for a GPT Pro consult. If the Oracle doctor reports `nodeCompatible:false`, fix the Oracle install/runtime and rerun doctor.
+7. If the Oracle doctor JSON includes `agent_actions` such as `chatgpt-oracle-install-pinned`, `chatgpt-oracle-upgrade-pinned`, or `chatgpt-oracle-fix-configured-source`, run them only when the user has explicitly asked to set up or repair GPT Pro browser consults. Do not run Oracle bootstrap from default repo-harness install or unrelated setup checks.
+8. If the user wants Oracle to use an existing signed-in Chrome profile, record the selected profile metadata first:
+
+```bash
+repo-harness chatgpt browser-setup --repo . --profile-dir <user-selected-chrome-profile-dir> --browser-channel chrome
+repo-harness chatgpt browser-doctor --repo . --provider oracle --json
+```
+
+The Oracle path must fail closed rather than silently falling back to an unbound/default browser session. Use `browser-bind` only when the user explicitly asks for the experimental bridge provider; then report the printed `Local authorization URL: http://127.0.0.1:...` and `bridgeExtension=...`, keep the command running while they authorize, and stop it before `browser-consult --provider bridge`.
+9. Use browser consult for planning, review, critique, and goal generation. Do not use it as the executor for code edits.
+10. Save useful results into repo-harness artifacts with repo-relative, timestamped `--write-output` paths such as:
 
 ```text
-.ai/harness/handoff/chatgpt-review.md
-.ai/harness/handoff/codex-goal.md
+.ai/harness/handoff/chatgpt-review-<timestamp>.md
+.ai/harness/handoff/codex-goal-<timestamp>.md
 plans/prds/*.prd.md
 plans/sprints/*.sprint.md
 ```
 
-8. If login, captcha, workspace picker, or SSO is required, stop and ask the user to complete it in the browser.
-9. Do not enable remote CDP unless the user explicitly asked for remote browser control and the security boundary is documented.
-10. For MCP usage, require the server to be started with:
+11. If login, captcha, workspace picker, or SSO is required, stop and ask the user to complete it in the browser.
+12. Do not enable remote CDP unless the user explicitly asked for remote browser control and the security boundary is documented.
+13. For MCP usage, require the server to be started with:
 
 ```bash
 repo-harness mcp serve --repo . --enable-chatgpt-browser
 ```
 
-11. Do not rely on provider stdout `Artifact:` / `Output:` paths being imported. Browser engine session records save prompt, transcript, output, metadata, and trusted provider IDs; ordinary stdout paths are ignored.
-12. Native provider uses the current ChatGPT Web model selection. Do not pass `--model` or `--thinking` with `--provider native`; use Oracle when model selection is required.
+14. Do not rely on provider stdout `Artifact:` / `Output:` paths being imported. Browser engine session records save prompt, transcript, output, metadata, and trusted provider IDs; ordinary stdout paths are ignored.
+15. Native and bridge providers use the current ChatGPT Web model selection. Do not pass `--model` or `--thinking` with `--provider native` or `--provider bridge`; use Oracle when model selection is required.
 
 ## Common Commands
 
@@ -60,27 +70,28 @@ repo-harness chatgpt browser-consult \
 Oracle provider consult:
 
 ```bash
+stamp="$(date -u +%Y%m%dT%H%M%SZ)"
 repo-harness chatgpt browser-consult \
   --repo . \
   --provider oracle \
   --prompt "Review this PRD and return risks plus a smallest next step." \
   --file plans/prds/example.prd.md \
-  --write-output .ai/harness/handoff/chatgpt-review.md
+  --write-output ".ai/harness/handoff/chatgpt-review-${stamp}.md"
 ```
 
-Native provider spike:
+Bridge provider for an existing signed-in profile:
 
 ```bash
-repo-harness chatgpt browser-doctor --repo . --provider native
+repo-harness chatgpt browser-doctor --repo . --provider bridge
+repo-harness chatgpt browser-setup --repo . --profile-dir <user-selected-chrome-profile-dir> --browser-channel chrome
+repo-harness chatgpt browser-bind --repo . --open
 repo-harness chatgpt browser-consult \
   --repo . \
-  --provider native \
-  --browser-channel chrome \
-  --keep-browser \
+  --provider bridge \
   --prompt "Reply exactly OK"
 ```
 
-Use native provider only when the user is ready for a visible ChatGPT Web run. If login is required, keep the browser open and have the user complete login manually; do not request or handle credentials.
+Use bridge/native providers only when the user is ready for a visible ChatGPT Web run. If login is required, have the user complete it from the local authorization page; do not request or handle credentials.
 
 Read the result:
 

package/README.es.md

@@ -1,7 +1,7 @@
 # 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">
+  <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
@@ -56,38 +56,36 @@ En un repositorio adoptado, la superficie se mantiene pequeña:
 | `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.7.0
-
-- **ChatGPT browser engine.** `repo-harness chatgpt browser-*` crea sesiones
-  ChatGPT Web repo-locales con archivos revisados por policy, sin usar OpenAI API.
-- **MCP browser tools opt-in.** `repo-harness mcp serve
-  --enable-chatgpt-browser` expone consult/read/list/continue/open; por defecto
-  estos tools siguen desactivados.
-- **Oracle y native providers.** El engine incluye un Oracle browser wrapper y
-  un spike native vía Chrome instalado + CDP local.
-- **Hosted CI y release smoke.** El repo añade un GitHub CI gate y un tarball
-  install smoke que arranca los binarios empaquetados de `repo-harness`.
-
-## Qué hace el producto
-
-`repo-harness` convierte el desarrollo asistido por IA de una "coordinación verbal
-en el historial de chat" en un "estado de workflow auditable en el repositorio".
-Instala en el repositorio objetivo un conjunto de contracts de archivos pequeño y
-explícito, para que Claude, Codex y las personas tengan una misma fuente de verdad
-sobre estas cuestiones:
-
-- cuál es la intención de producto estable
-- qué plan ya está aprobado para entrar en ejecución
-- qué scope permite modificar el sprint contract actual
-- qué checks, review y evidence prueban que la tarea está realmente completa
-- cómo deben los hooks advertir, bloquear, registrar trace y hacer handoff entre
-  sesiones
-
-No es un agent gateway, ni un runtime de producto, ni un servicio de base de
-datos, ni un MCP server. El límite del producto es claro: inspecciona el
-repositorio objetivo, instala o refresca los archivos de workflow, enruta los host
-events de Claude/Codex hacia los hooks repo-local, y luego verifica que esas
-workflow surfaces sigan siendo coherentes.
+## Human Review Path
+
+Empieza por `tasks/reviews/<task>.review.md`. La `## Human Review Card` es la
+superficie de decisión de una sola pantalla: verdict, change type, archivos
+previstos vs reales, comandos que pasaron, external acceptance, riesgo residual,
+acción del reviewer y rollback. Luego inspecciona el contract activo, el último
+trace en `.ai/harness/checks/latest.json` y los archivos modificados. Acepta solo
+cuando la review recomiende pass, el verdict de la card sea pass y el external
+acceptance sea pass, `not_required` o un manual override explícito.
+
+## Agent Tracking Path
+
+Los agentes leen los source artifacts antes que los resúmenes derivados:
+
+| Agent reads first | Human reviews first |
+| --- | --- |
+| Prompt actual del usuario y archivos referenciados | Human Review Card de `tasks/reviews/<task>.review.md` |
+| `AGENTS.md` / `CLAUDE.md` | Archivos modificados y diff |
+| Plan activo en `.ai/harness/active-plan` | Allowed paths y exit criteria del contract activo |
+| Contract activo en `tasks/contracts/` | `.ai/harness/checks/latest.json` y run trace |
+| Último handoff en `.ai/harness/handoff/` | Riesgos residuales y rollback |
+
+`tasks/current.md` es solo un snapshot de orientación. Si discrepa del plan
+activo, el contract, la review, los checks o el handoff, ganan los source
+artifacts.
+
+## Novedades
+
+Las notas de versión viven en [`docs/CHANGELOG.md`](docs/CHANGELOG.md). La línea
+actual es `0.7.2`.
 
 ## Cómo funciona
 
@@ -196,6 +194,10 @@ retoma contra un sprint concreto en vez de reinterpretar el chat original.
 Esta es la ruta más rápida para evaluar si un repositorio real es apto para
 adoptar este workflow.
 
+Prerrequisitos: un Git working tree, `bash` y `bun` (para la verificación
+posterior y el template assembly). `jq` es opcional para `--dry-run`, pero se
+recomienda al aplicar el settings merge.
+
 ### Instalar el CLI
 
 La ruta por defecto no requiere Node.js: el instalador usa Bun como runtime. Si
@@ -210,15 +212,15 @@ irm https://raw.githubusercontent.com/Ancienttwo/repo-harness/main/install.ps1 |
 ```
 
 <details>
-<summary>¿Ya tienes Bun o Node? Usa gestores de paquetes</summary>
+<summary>¿Ya tienes Bun? Usa Bun primero, o npx como fallback</summary>
 
 ```bash
-# Bun
+# Bun (recomendado)
 bun add -g repo-harness
-repo-harness init
+repo-harness install
 
-# Node/npm, con Bun ya en PATH porque el CLI corre sobre Bun
-npx -y repo-harness init
+# Fallback con npx, con Bun ya en PATH porque el CLI corre sobre Bun
+npx -y repo-harness install
 ```
 
 </details>
@@ -226,54 +228,27 @@ npx -y repo-harness init
 ### Bootstrap del runtime del host
 
 ```bash
-repo-harness init
+repo-harness install
 ```
 
-`repo-harness init` es el bootstrap global, `repo-harness update` es el refresco
-user-level y `repo-harness adopt` es el refresco repo-local. `repo-harness init`
+`repo-harness install` es el bootstrap global, `repo-harness update` es el refresco
+user-level y `repo-harness adopt` es el refresco repo-local. `repo-harness install`
 configura el CLI, los hook adapters de nivel usuario, Waza, Mermaid, el brain
 root y CodeGraph MCP; el viejo camino Claude plugin `scripts/setup-plugins.sh`
 queda retirado.
 
-Si trabajas desde un checkout del código fuente:
-
-```bash
-git clone https://github.com/Ancienttwo/repo-harness.git ~/Projects/repo-harness
-cd ~/Projects/repo-harness
-bun src/cli/index.ts init
-```
-
-Modelo de rutas locales:
-
-- Repositorio fuente: `~/Projects/repo-harness`
-- Claude skill alias: `~/.claude/skills/repo-harness`
-- Codex discoverable skill alias: `~/.codex/skills/repo-harness`
-
-`~/Projects/repo-harness` es la única source of truth editable. Las rutas locales
-de Claude/Codex son runtime entrypoints respaldados por symlinks. Los directorios
-de los runtimes ya retirados `repo-harness-skill` y `project-initializer` los
-elimina `scripts/sync-codex-installed-copies.sh`.
-
-### Prerrequisitos mínimos
-
-- Git working tree
-- `bash`
-- `bun`, para la verificación posterior y el template assembly
-- `jq` es opcional; se recomienda al hacer `--dry-run` y resulta más útil al
-  aplicar el settings merge
-
 ### Empieza por aquí
 
 En un repositorio existente, ejecuta desde el repo root:
 
 ```bash
-npx -y repo-harness adopt --dry-run
+repo-harness adopt --dry-run
 ```
 
 Aplica solo después de que el reporte del dry-run sea correcto:
 
 ```bash
-npx -y repo-harness adopt
+repo-harness adopt
 ```
 
 Para un proyecto o módulo nuevo, usa la branch command `repo-harness-scaffold`.
@@ -301,6 +276,67 @@ bun test
 Si la salida del dry-run no es correcta, detente aquí primero y lee
 [`docs/reference-configs/hook-operations.md`](docs/reference-configs/hook-operations.md).
 
+## MCP Connector Quickstart
+
+Como sidecar opcional, `repo-harness mcp` expone solo workflow artifacts a los
+clientes MCP. ChatGPT actúa como planner/reviewer que lee el estado y mueve una
+idea a través de PRD, Sprint checklist y artifacts de handoff de goal de Codex —
+sin acceso de escritura al código fuente, ejecución de shell arbitraria ni un
+runner de Codex por defecto. Codex sigue siendo el ejecutor.
+
+Este sidecar asume que el CLI ya está instalado según «Primeros 5 minutos» de
+arriba. Úsalo cuando quieras que ChatGPT planifique contra el estado real del
+repositorio y que Codex ejecute el Sprint file-backed resultante.
+
+```bash
+repo-harness mcp setup chatgpt --repo .
+repo-harness mcp serve --repo . --transport http --host 127.0.0.1 --port 8765 --profile planner
+```
+
+Expón ese server local a través de un túnel HTTPS y crea un Connector de ChatGPT
+con la URL `/mcp`. La guía generada se escribe en:
+
+```text
+docs/repo-harness-chatgpt-mcp-setup.md
+```
+
+El human workflow es:
+
+1. ChatGPT lee los archivos de workflow de repo-harness a través de MCP.
+2. ChatGPT escribe un PRD con `write_prd_from_idea`.
+3. ChatGPT escribe un Sprint checklist con `write_checklist_sprint`.
+4. ChatGPT prepara `.ai/harness/handoff/codex-goal.md` con `prepare_codex_goal_from_sprint`.
+5. Codex ejecuta el prompt host-native `/goal` y hace stage de cada Sprint phase completada.
+
+Alternativa local para el último paso de handoff:
+
+```bash
+repo-harness mcp prepare-goal --repo . --prd plans/prds/<feature>.prd.md --sprint plans/sprints/<feature>.sprint.md
+```
+
+El Skill orientado al agente se instala en:
+
+```text
+.agents/skills/repo-harness-chatgpt-bridge/SKILL.md
+```
+
+Ese Skill le indica a Codex cómo consumir los artifacts PRD/Sprint/Goal
+producidos por ChatGPT sin concederle a ChatGPT escritura sobre el source-code
+ni ejecución de shell.
+
+El Dev Mode puede optar por la ejecución local de agentes a través de MCP. Está
+desactivado por defecto. Cuando el usuario activa el profile `orchestrator` con
+el ajuste dev runner, ChatGPT puede llamar a `run_agent_goal`, que solo lee
+`.ai/harness/handoff/codex-goal.md` y ejecuta el handoff fijo a través de un CLI
+local permitido como `codex exec` o `claude -p`.
+
+```bash
+repo-harness mcp serve --repo . --transport http --profile orchestrator --enable-dev-runner --dev-runner-agents codex
+```
+
+Este ajuste es solo para el Developer Mode local. Tiene límite de timeout, está
+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.
@@ -383,37 +419,11 @@ Guards habituales:
 
 ## Release actual
 
-- npm package: `repo-harness@0.7.0`
-- Generated workflow stamp: `repo-harness@0.7.0+template@0.7.0`
+- npm package: `repo-harness@0.7.2`
+- Generated workflow stamp: `repo-harness@0.7.2+template@0.7.2`
 - GitHub repository: `Ancienttwo/repo-harness`
 - Release history: [`docs/CHANGELOG.md`](docs/CHANGELOG.md)
 
-## Current Model
-
-- El question flow usa **12 grouped decision points**, infiriendo primero los harness defaults.
-- El plan menu está por capas: los **Core Plans (A-F)** primero, los **Custom Presets (G-K)** solo cuando hace falta.
-- El skill routing es inspection-first:
-  - `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:
-  - los `repo-harness` skill aliases
-  - los global Codex/Claude hook adapters
-  - las Waza skills: `think`, `hunt`, `check`, `health`
-  - Mermaid
-- El resto del external tooling se mantiene advisory-only:
-  - `bash scripts/check-agent-tooling.sh --host both --check-updates`
-  - no configura automáticamente gstack, gbrain, CodeGraph MCP, daemon ni provider
-
 ## Agradecimientos
 
 Gracias a [Hylarucoder](https://x.com/hylarucoder) por su contribución
@@ -429,6 +439,12 @@ 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
+externo para los consults `gptpro`, sin descarga automática, y un binario ausente
+es un fallo explícito.
+
 
 ### Atribución de contribuidor en GitHub
 
@@ -474,15 +490,28 @@ queda como branch command para crear proyectos o módulos nuevos. `hooks-init`,
 
 ## Maintainer Reference
 
-### Verificar el workflow contract de este repositorio
+Quienes editan el propio paquete necesitan un checkout del código fuente:
 
 ```bash
-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
+git clone https://github.com/Ancienttwo/repo-harness.git ~/Projects/repo-harness
+cd ~/Projects/repo-harness
+bun src/cli/index.ts update
 ```
 
+`~/Projects/repo-harness` es la única source of truth editable; las rutas locales
+de Claude/Codex (`~/.claude/skills/repo-harness`, `~/.codex/skills/repo-harness`)
+son runtime entrypoints respaldados por symlinks. Solo
+`~/.codex/skills/repo-harness` expone `SKILL.md` y `assets/skill-commands/`;
+`scripts/sync-codex-installed-copies.sh` reconstruye estos alias y elimina los
+directorios retirados `repo-harness-skill` / `project-initializer`. El script
+enlaza las rutas al repo fuente por defecto; usa
+`AGENTIC_DEV_LINK_INSTALLED_COPIES=0` para staging por copia, o
+`CODEX_SKILLS_ROOT` / `CLAUDE_SKILLS_ROOT` para raíces alternativas.
+
+### Verificar el workflow contract de este repositorio
+
+Ejecuta el gate completo en [Verification](#verification); `bun run check:ci` es
+el único comando equivalente a CI.
 
 ### Runtime reference docs
 
@@ -495,10 +524,12 @@ 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/`.
+Los defaults del initializer y del runtime (question flow, plan menu, template
+vars, routing de external tooling) están documentados en `harness-overview.md`
+bajo **Initializer and Runtime Model**. 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