repo-harness 0.5.3 → 0.7.0

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

@@ -0,0 +1,106 @@
+---
+name: repo-harness-chatgpt-browser
+description: Use when the user wants Codex to consult their logged-in ChatGPT Web session through repo-harness browser engine for planning, architecture review, PRD critique, or Codex goal generation.
+---
+
+# repo-harness ChatGPT Browser
+
+Use this skill when the user asks to consult ChatGPT Web, GPT Pro, browser GPT, or a logged-in ChatGPT account through repo-harness.
+
+## Rules
+
+1. This uses the user's logged-in ChatGPT Web browser session, not the OpenAI API.
+2. Do not ask for or handle passwords, SSO secrets, 2FA codes, cookies, browser storage, or tokens.
+3. Before a non-dry-run consult, state that it may create or continue a real ChatGPT Web conversation.
+4. Prefer dry-run first when files are involved:
+
+```bash
+repo-harness chatgpt browser-consult --repo . --dry-run --prompt "<prompt>" --file <path>
+```
+
+5. For readiness, run:
+
+```bash
+repo-harness chatgpt browser-doctor --repo .
+```
+
+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:
+
+```text
+.ai/harness/handoff/chatgpt-review.md
+.ai/harness/handoff/codex-goal.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:
+
+```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.
+
+## Common Commands
+
+Dry-run consult:
+
+```bash
+repo-harness chatgpt browser-consult \
+  --repo . \
+  --dry-run \
+  --prompt "Review this sprint and return execution risks." \
+  --file plans/sprints/example.sprint.md
+```
+
+Oracle provider consult:
+
+```bash
+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
+```
+
+Native provider spike:
+
+```bash
+repo-harness chatgpt browser-doctor --repo . --provider native
+repo-harness chatgpt browser-consult \
+  --repo . \
+  --provider native \
+  --browser-channel chrome \
+  --keep-browser \
+  --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.
+
+Read the result:
+
+```bash
+repo-harness chatgpt browser-list --repo .
+repo-harness chatgpt browser-session --repo . <sessionId>
+repo-harness chatgpt browser-open --repo . <sessionId>
+```
+
+Continue from a saved session:
+
+```bash
+repo-harness chatgpt browser-followup \
+  --repo . \
+  --session <sessionId> \
+  --prompt "Challenge the previous result and return the smallest next step."
+```
+
+Plan cleanup before deleting local session records:
+
+```bash
+repo-harness chatgpt browser-cleanup --repo . --status dry_run --limit 20
+```

package/README.es.md

@@ -56,11 +56,17 @@ 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.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.
+## 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
 
@@ -377,8 +383,8 @@ Guards habituales:
 
 ## Release actual
 
-- npm package: `repo-harness@0.5.3`
-- Generated workflow stamp: `repo-harness@0.5.3+template@0.5.3`
+- npm package: `repo-harness@0.7.0`
+- Generated workflow stamp: `repo-harness@0.7.0+template@0.7.0`
 - GitHub repository: `Ancienttwo/repo-harness`
 - Release history: [`docs/CHANGELOG.md`](docs/CHANGELOG.md)
 

package/README.fr.md

@@ -56,11 +56,17 @@ Dans un dépôt adopté, la surface à comprendre reste volontairement réduite
 | `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.
+## Nouveautés de la 0.7.0
+
+- **ChatGPT browser engine.** `repo-harness chatgpt browser-*` crée des sessions
+  ChatGPT Web repo-locales avec des fichiers contrôlés par policy, sans OpenAI API.
+- **MCP browser tools opt-in.** `repo-harness mcp serve
+  --enable-chatgpt-browser` expose consult/read/list/continue/open, désactivés
+  par défaut.
+- **Oracle et native providers.** Le moteur inclut un Oracle browser wrapper et
+  un spike native via Chrome installé et CDP local.
+- **Hosted CI et release smoke.** Le dépôt ajoute un GitHub CI gate et un
+  tarball install smoke qui démarre les binaires packagés `repo-harness`.
 
 ## Ce que fait le produit
 
@@ -381,8 +387,8 @@ Guards courants :
 
 ## Release actuelle
 
-- npm package : `repo-harness@0.5.3`
-- Generated workflow stamp : `repo-harness@0.5.3+template@0.5.3`
+- npm package : `repo-harness@0.7.0`
+- Generated workflow stamp : `repo-harness@0.7.0+template@0.7.0`
 - GitHub repository : `Ancienttwo/repo-harness`
 - Release history : [`docs/CHANGELOG.md`](docs/CHANGELOG.md)
 

package/README.ja.md

@@ -47,11 +47,12 @@ Agent に完全な PRD または Sprint を渡せば、あとは review and `nex
 | `tasks/contracts/`, `tasks/reviews/`, `.ai/harness/checks/` | 作業完了を証明する scope、verification、review evidence。 |
 | `.ai/harness/handoff/` と `tasks/current.md` | chat memory ではなく workflow artifacts から派生する session journal と resumable status。 |
 
-## 0.5.3 の新機能
+## 0.7.0 の新機能
 
-- **Pinned runtime updates。** `repo-harness update --version <version>` は、top-level CLI version shortcut に横取りされず、指定された `repo-harness@<version>` package をインストールするようになりました。
-- **Version shortcut preserved。** `repo-harness --version` と `repo-harness -V` は、top level で使った場合は引き続き CLI version を出力します。
-- **Patch-only surface。** update command option fix 以外に、hook route、setup check、security scan、workflow contract の動作変更はありません。
+- **ChatGPT browser engine。** `repo-harness chatgpt browser-*` は、OpenAI API を使わず、policy-checked な repo-local ChatGPT Web consult session を作れます。
+- **Opt-in MCP browser tools。** `repo-harness mcp serve --enable-chatgpt-browser` のときだけ consult/read/list/continue/open tools を公開し、デフォルトでは無効です。
+- **Oracle and native providers。** Oracle browser wrapper と、installed Chrome + local CDP を使う native spike を含みます。
+- **Hosted CI and release smoke。** GitHub CI gate と、packaged `repo-harness` binaries を起動する tarball install smoke を追加しました。
 
 ## repo-harness は何をするか
 
@@ -351,8 +352,8 @@ hook がブロックしたときは、まず terminal の構造化された出
 
 ## 現在の Release
 
-- npm package：`repo-harness@0.5.3`
-- Generated workflow stamp：`repo-harness@0.5.3+template@0.5.3`
+- npm package：`repo-harness@0.7.0`
+- Generated workflow stamp：`repo-harness@0.7.0+template@0.7.0`
 - GitHub repository：`Ancienttwo/repo-harness`
 - Release history：[`docs/CHANGELOG.md`](docs/CHANGELOG.md)
 

package/README.md

@@ -50,15 +50,43 @@ In an adopted repo, the surface area is intentionally small:
 | `tasks/contracts/`, `tasks/reviews/`, and `.ai/harness/checks/` | Scope, verification, and review evidence for proving the work is done. |
 | `.ai/harness/handoff/` and `tasks/current.md` | Session journal and resumable status, derived from workflow artifacts instead of chat memory. |
 
-## What's New in 0.5.3
+## Human Review Path
 
-- **Pinned runtime updates.** `repo-harness update --version <version>` now
-  installs the requested `repo-harness@<version>` package instead of being
-  intercepted by the top-level CLI version shortcut.
-- **Version shortcut preserved.** `repo-harness --version` and
-  `repo-harness -V` still print the CLI version when used at the top level.
-- **Patch-only surface.** No hook route, setup check, security scan, or workflow
-  contract behavior changes beyond the update command option fix.
+Start with `tasks/reviews/<task>.review.md`. The `## Human Review Card` is the
+one-screen decision surface: verdict, change type, intended vs actual files,
+commands passed, external acceptance, residual risk, reviewer action, and
+rollback. Then inspect the active contract, latest trace in
+`.ai/harness/checks/latest.json`, and the changed files. Accept only when the
+review recommends pass, the card verdict is pass, and external acceptance is
+pass, `not_required`, or an explicit manual override.
+
+## Agent Tracking Path
+
+Agents read source artifacts before derived summaries:
+
+| Agent reads first | Human reviews first |
+| --- | --- |
+| Current user prompt and referenced files | `tasks/reviews/<task>.review.md` Human Review Card |
+| `AGENTS.md` / `CLAUDE.md` | Changed files and diff |
+| Active plan in `.ai/harness/active-plan` | Active contract allowed paths and exit criteria |
+| Active contract in `tasks/contracts/` | `.ai/harness/checks/latest.json` and run trace |
+| Latest handoff in `.ai/harness/handoff/` | Residual risks and rollback |
+
+`tasks/current.md` is only an orientation snapshot. If it disagrees with the
+active plan, contract, review, checks, or handoff, the source artifacts win.
+
+## What's New in 0.7.0
+
+- **ChatGPT browser engine.** `repo-harness chatgpt browser-*` can create
+  policy-checked, repo-local ChatGPT Web consult sessions without using the
+  OpenAI API.
+- **Opt-in MCP browser tools.** `repo-harness mcp serve
+  --enable-chatgpt-browser` exposes consult/read/list/continue/open tools while
+  keeping them disabled by default.
+- **Oracle and native providers.** The engine supports an Oracle browser wrapper
+  plus a native installed-Chrome CDP spike for logged-in ChatGPT Web runs.
+- **Hosted CI and release smoke.** The repo now ships a GitHub CI gate and a
+  tarball install smoke that starts the packaged `repo-harness` binaries.
 
 ## What repo-harness Does
 
@@ -72,11 +100,71 @@ target repository so Claude, Codex, and humans can agree on:
 - which checks and review evidence prove the work is done
 - how hooks should warn, block, trace, and hand off work across sessions
 
-It is not an agent gateway, product runtime, database service, or MCP server.
 The product boundary is deliberately boring: inspect a repo, install or refresh
 workflow files, route host events through repo-local hooks, and verify that the
 workflow surfaces stay consistent.
 
+As an optional sidecar, `repo-harness mcp` exposes only workflow artifacts to
+MCP clients. ChatGPT can use it as a planner/reviewer to read state and move an
+idea through PRD, checklist Sprint, and Codex goal handoff artifacts; it does
+not get source-code write access, arbitrary shell execution, or a default Codex
+runner. Codex remains the executor. The generated manual setup guide lives at
+`docs/repo-harness-chatgpt-mcp-setup.md`, and the local CLI handoff is
+`repo-harness mcp prepare-goal --prd <prd> --sprint <sprint>`.
+
+### MCP Connector Quickstart
+
+Use the MCP sidecar when you want ChatGPT to plan against the real repo state
+and Codex to execute the resulting file-backed Sprint.
+
+```bash
+repo-harness mcp setup chatgpt --repo .
+repo-harness mcp serve --repo . --transport http --host 127.0.0.1 --port 8765 --profile planner
+```
+
+Expose that local server through an HTTPS tunnel and create a ChatGPT Connector
+with the `/mcp` URL. The generated guide is written to:
+
+```text
+docs/repo-harness-chatgpt-mcp-setup.md
+```
+
+The human workflow is:
+
+1. ChatGPT reads repo-harness workflow files through MCP.
+2. ChatGPT writes a PRD with `write_prd_from_idea`.
+3. ChatGPT writes a checklist Sprint with `write_checklist_sprint`.
+4. ChatGPT prepares `.ai/harness/handoff/codex-goal.md` with `prepare_codex_goal_from_sprint`.
+5. Codex runs the host-native `/goal` prompt and stages each completed Sprint phase.
+
+Local fallback for the last handoff step:
+
+```bash
+repo-harness mcp prepare-goal --repo . --prd plans/prds/<feature>.prd.md --sprint plans/sprints/<feature>.sprint.md
+```
+
+The agent-facing Skill is installed at:
+
+```text
+.agents/skills/repo-harness-chatgpt-bridge/SKILL.md
+```
+
+That Skill tells Codex how to consume ChatGPT-produced PRD/Sprint/Goal artifacts
+without granting ChatGPT source-code writes or shell execution.
+
+Dev Mode can opt into local agent execution through MCP. This is off by default.
+When the user enables the `orchestrator` profile with the dev runner setting,
+ChatGPT can call `run_agent_goal`, which reads only
+`.ai/harness/handoff/codex-goal.md` and runs the fixed handoff through an
+allowed local CLI such as `codex exec` or `claude -p`.
+
+```bash
+repo-harness mcp serve --repo . --transport http --profile orchestrator --enable-dev-runner --dev-runner-agents codex
+```
+
+This setting is for local Developer Mode only. It is timeout-bounded, audited,
+and not arbitrary shell.
+
 ## How It Works
 
 The design has three layers:
@@ -234,10 +322,10 @@ irm https://raw.githubusercontent.com/Ancienttwo/repo-harness/main/install.ps1 |
 ```bash
 # Bun
 bun add -g repo-harness
-repo-harness init
+repo-harness install
 
 # Node/npm, with Bun already on PATH because the CLI runs on Bun
-npx -y repo-harness init
+npx -y repo-harness install
 ```
 
 </details>
@@ -245,14 +333,15 @@ npx -y repo-harness init
 ### 2. Bootstrap the host runtime once
 
 ```bash
-repo-harness init
+repo-harness install
 ```
 
-`init` is the first-run global bootstrap path. It installs the current npm
+`install` is the first-run global bootstrap path. It installs the current npm
 package as the global CLI, refreshes repo-harness skill aliases, installs
 user-level hook adapters, configures Waza runtime skills, persists a brain root
 under `~/.repo-harness/config.json`, and configures CodeGraph MCP. It does not
-apply repo-local workflow files to the current directory.
+apply repo-local workflow files to the current directory. `repo-harness init`
+remains a compatibility alias for existing scripts.
 
 For an Agent-owned, read-only bootstrap audit, run `npx -y repo-harness setup
 check --json` or add `--check-updates` for version advisories. `setup check` is
@@ -265,11 +354,17 @@ optional command, and verification surface for the Agent to execute deliberately
 
 ```bash
 # First machine bootstrap after installing the CLI: skills, host adapters, Waza, brain, CodeGraph.
-repo-harness init
+repo-harness install
 
 # Refresh user-level CLI/runtime pieces after a package update.
 repo-harness update
 
+# Remove repo-harness managed host adapters without deleting sibling hooks or third-party tools.
+repo-harness uninstall
+
+# Install only the host hook adapters, preserving the older adapter-only surface.
+repo-harness install --target both --location global
+
 # Ask for read-only repair guidance without writing files.
 repo-harness update --check
 
@@ -455,8 +550,8 @@ Most common guards:
 
 ## Current Release
 
-- npm package: `repo-harness@0.5.3`
-- Generated workflow stamp: `repo-harness@0.5.3+template@0.5.3`
+- npm package: `repo-harness@0.7.0`
+- Generated workflow stamp: `repo-harness@0.7.0+template@0.7.0`
 - GitHub repository: `Ancienttwo/repo-harness`
 - Release history: [`docs/CHANGELOG.md`](docs/CHANGELOG.md)
 

package/README.zh-CN.md

@@ -43,14 +43,40 @@ handoff、检查结果和 review evidence 写回项目文件，让下一个 agen
 | `tasks/contracts/`、`tasks/reviews/`、`.ai/harness/checks/` | 证明完成所需的 scope、verification 和 review evidence。 |
 | `.ai/harness/handoff/` 和 `tasks/current.md` | session journal 与可恢复状态，从 workflow artifacts 派生，而不是依赖聊天记忆。 |
 
-## 0.5.3 新特性
+## Human Review Path
 
-- **可 pin 的 runtime update。** `repo-harness update --version <version>` 现在会
-  安装指定的 `repo-harness@<version>` package，不再被顶层 CLI version shortcut 抢占。
-- **保留 version shortcut。** `repo-harness --version` 和 `repo-harness -V` 在顶层使用时
-  仍然输出 CLI version。
-- **Patch-only surface。** 除 update command option 修复外，hook route、setup check、
-  security scan 和 workflow contract 行为不变。
+先读 `tasks/reviews/<task>.review.md`。`## Human Review Card` 是一屏决策面：
+verdict、change type、预期/实际改动文件、已通过命令、external acceptance、
+残余风险、reviewer action 和 rollback。然后检查 active contract、
+`.ai/harness/checks/latest.json` 里的 latest trace，以及实际 diff。只有当 review
+recommend pass、card verdict 为 pass，且 external acceptance 为 pass、not_required
+或明确 manual override 时，才进入 closeout。
+
+## Agent Tracking Path
+
+Agent 先读 source artifacts，再读派生摘要：
+
+| Agent reads first | Human reviews first |
+| --- | --- |
+| 当前用户 prompt 和引用文件 | `tasks/reviews/<task>.review.md` 的 Human Review Card |
+| `AGENTS.md` / `CLAUDE.md` | changed files 和 diff |
+| `.ai/harness/active-plan` 指向的 active plan | active contract 的 allowed paths 和 exit criteria |
+| `tasks/contracts/` 下的 active contract | `.ai/harness/checks/latest.json` 和 run trace |
+| `.ai/harness/handoff/` 下的 latest handoff | 残余风险和 rollback |
+
+`tasks/current.md` 只是 orientation snapshot。如果它和 active plan、contract、
+review、checks 或 handoff 冲突，以 source artifacts 为准。
+
+## 0.7.0 新特性
+
+- **ChatGPT browser engine。** `repo-harness chatgpt browser-*` 可以用
+  policy-checked 文件输入创建 repo-local ChatGPT Web consult session，不走 OpenAI API。
+- **Opt-in MCP browser tools。** `repo-harness mcp serve
+  --enable-chatgpt-browser` 才会暴露 consult/read/list/continue/open 工具，默认关闭。
+- **Oracle 和 native provider。** Browser engine 支持 Oracle browser wrapper，
+  也支持基于本机已安装 Chrome CDP 的 logged-in ChatGPT Web spike。
+- **Hosted CI 和 release smoke。** 仓库新增 GitHub CI gate，并用 tarball install
+  smoke 验证 packaged `repo-harness` binaries 能启动。
 
 ## 产品做什么
 
@@ -204,10 +230,10 @@ irm https://raw.githubusercontent.com/Ancienttwo/repo-harness/main/install.ps1 |
 ```bash
 # Bun
 bun add -g repo-harness
-repo-harness init
+repo-harness install
 
 # Node/npm；仍要求 Bun 已在 PATH 上，因为 CLI runtime 是 Bun
-npx -y repo-harness init
+npx -y repo-harness install
 ```
 
 </details>
@@ -215,13 +241,13 @@ npx -y repo-harness init
 ### 2. 先做一次 host runtime bootstrap
 
 ```bash
-repo-harness init
+repo-harness install
 ```
 
-`init` 是首次全局引导入口。它把当前 npm 包安装成全局 CLI，刷新 repo-harness
+`install` 是首次全局引导入口。它把当前 npm 包安装成全局 CLI，刷新 repo-harness
 skill aliases，安装 user-level hook adapters，配置 Waza runtime skills，把 brain
 root 持久化到 `~/.repo-harness/config.json`，并配置 CodeGraph MCP。它不会把当前目录
-默认迁移成 repo-local workflow。
+默认迁移成 repo-local workflow。`repo-harness init` 保留为兼容 alias，给已有脚本用。
 
 如果要让 Agent 做只读 bootstrap audit，运行 `npx -y repo-harness setup check
 --json`；需要版本提示时加 `--check-updates`。`setup check` 不是 runtime hook：
@@ -233,11 +259,17 @@ targets、可选 command 和 verification 的 `agent_actions`，由 Agent 再显
 
 ```bash
 # 安装 CLI 后做首次机器级 bootstrap：skills、host adapters、Waza、brain、CodeGraph。
-repo-harness init
+repo-harness install
 
 # 包更新后刷新 user-level CLI/runtime。
 repo-harness update
 
+# 移除 repo-harness 管理的 host adapters，不删除 sibling hooks 或第三方工具。
+repo-harness uninstall
+
+# 只安装 host hook adapters，保留旧版 adapter-only surface。
+repo-harness install --target both --location global
+
 # 只读检查需要 agent 修复什么，不写文件。
 repo-harness update --check
 
@@ -410,8 +442,8 @@ hook block 工作时，先看 terminal 里的结构化输出。核心字段是
 
 ## 当前 Release
 
-- npm package：`repo-harness@0.5.3`
-- Generated workflow stamp：`repo-harness@0.5.3+template@0.5.3`
+- npm package：`repo-harness@0.7.0`
+- Generated workflow stamp：`repo-harness@0.7.0+template@0.7.0`
 - GitHub repository：`Ancienttwo/repo-harness`
 - Release history：[`docs/CHANGELOG.md`](docs/CHANGELOG.md)