boxglow 0.6.1 → 0.6.3

package/README.md

@@ -11,6 +11,36 @@ Tasks are boxes with inputs and outputs; a box goes New (BlackBox: output decide
 - CLI for agents: `npx boxglow` (status / start / done / split / ask / answer ...)
 - License: MIT
 
+## What's new in 0.6.3
+
+- **Policies**: share any output as a project-wide decision without wires (`port --policy`, MCP `boxglow_port`). Boxes in its scope wait for it before they start and are flagged "Policy: check again" when it changes after they are done.
+- **Send back** instead of wiring a loop: an evaluation that fails returns the work to the box that made it, with the reason (`boxglow sendback`, MCP `boxglow_sendback`, "↩ Send back" on the I/O tab).
+- **Wiring across levels**: drop a wire on a box in another level, connect from a list ("Connect from… / Connect to…"), or click two ports; inputs with the same name connect through the levels by themselves. A box can have several outputs, and connected ports share one name.
+- **Easier editing and a calmer canvas**: everything that can be added can be removed (Delete works on wires, boxes and picked ports), a single click selects without opening the details panel, auto save is a toggle, Top shows every level, and wires around nested boxes are straighter, cross less and stay visible when zoomed out.
+
+Details: [CHANGELOG.md](CHANGELOG.md). Update the CLI, `serve` and the VS Code extension (0.5.3) together.
+
+### 日本語: 0.6.3 の要点
+
+- **方針**: 出力を線なしで範囲全体に配る決定にできる (`port --policy`、MCP `boxglow_port`)。範囲の箱は着手の前に方針を待ち、完了後に方針が変わると「方針: 確かめ直し」が付く。
+- **差し戻し**: 評価が通らなかったら、線で戻さずに作った箱へ理由付きで戻す (`boxglow sendback`、MCP `boxglow_sendback`、I/O タブの「↩ 差し戻す」)。
+- **階層をまたぐ結線**: 別の階層の箱へ線を落とす、一覧から選ぶ (「供給元から選ぶ… / 使う箱を足す…」)、丸を 2 回クリックする、のどれでもつながる。同じ名前の入力は階層を通って自動でつながる。箱は出力を複数持て、つながった入出力は名前が 1 つにそろう。
+- **編集しやすく、見やすく**: 足せるものはすべて消せる (Delete で線・箱・選んだ丸)、1 回のクリックは選ぶだけで詳細は開かない、自動保存の切り替え、Top で全階層を表示、入れ子の箱の周りの線がまっすぐ・交差が少なく・縮小しても見える。
+
+## What's new in 0.6.2
+
+- **`setup-agent` sets up everything for Claude Code and Codex**: hooks (the plan's resume summary is injected when a session starts, resumes or is compacted; an agent about to finish with an unrecorded box is told to record first; direct edits of `boxglow.json` are blocked), MCP registration, a review subagent, and the context guard. `setup-agent --check` shows what is installed, when each hook last fired, and the one-time steps left to you (Codex: trust the project and approve the hooks in the terminal CLI).
+- **Verification at done**: `boxglow done --checked "<checks run and results>" [--not-checked …] [--limits …]` stays on the box and shows in `show`, `context` and the Status tab.
+- **Sync you can stop**: "Stop syncing / Resume syncing" and "Disconnect this plan on this device"; a **Constraints** field under the outputs; a safer merge into `~/.codex/config.toml`; a usability pass (fewer steps on Home, clearer buttons and labels, a scrolling account menu).
+
+Details: [CHANGELOG.md](CHANGELOG.md). Update the CLI, `serve` and the VS Code extension (0.5.2) together.
+
+### 日本語: 0.6.2 の要点
+
+- **`setup-agent` だけで Claude Code と Codex の両方が整う**: hooks (セッションの開始・再開・圧縮の後に計画の再開の概要を文脈へ、記録の無い箱を残したまま終えようとすると記録を促す、boxglow.json の直接編集を止める)、MCP の登録、レビュー用のサブエージェント、確認トークン。`setup-agent --check` で、入っているもの・各 hook の最後の発火・利用者が一度だけ行うこと (Codex はプロジェクトの信頼とターミナルの CLI での hooks の承認) を表示。
+- **完了のときの検査結果**: `boxglow done --checked "<実行した検査と結果>" [--not-checked …] [--limits …]` が箱に残り、show・context・Status タブに出る。
+- **止められる同期** (「同期を止める / 再開する」「この端末の結び付けを解除する」)、出力の下の**制約**の欄、`~/.codex/config.toml` への安全な併合、使いやすさの見直し (Home の手数、ボタンの見た目、アカウントメニューのスクロール)。
+
 ## What's new in 0.6.1
 
 - **Sync in the browser alone** at [boxglow.app](https://boxglow.app): sign in with GitHub or Google, put a plan on the server or receive one, and it syncs while the tab is open. `serve` and the VS Code extension sync the same way with a local file.
@@ -73,7 +103,7 @@ npx boxglow done "Build it" --artifact "app=src/App.tsx"                    # de
 
 Recommended flow for a new project: the agent reads the brief (README, request) and creates 3-7 top-level boxes with concrete outputs, asks the human to confirm the split (`ask`), and only then decomposes the box it starts (`split`). Decisions keep the candidates that were not chosen; `reopen` lets you change course later without losing the history.
 
-Then run `npx boxglow setup-agent` once. It installs agent instructions and skills and enables the context guard described below. Claude Code also receives a SessionStart hook and `.mcp.json`; Codex MCP registration is separate. Open `npx boxglow serve --open` or the [VS Code extension](https://marketplace.visualstudio.com/items?itemName=sukima.boxglow-vscode) to edit the same repository file as the agent.
+Then run `npx boxglow setup-agent` once. It installs everything the agents need so you do not have to know the mechanisms: the instructions (`CLAUDE.md` / `AGENTS.md`), the skill, the hooks (the plan's resume summary is injected when a session starts, resumes or is compacted; an agent that is about to finish with an unrecorded box is told to record first; direct edits of `boxglow.json` are blocked), the MCP server registration (`.mcp.json` for Claude Code, approved for boxglow only via `enabledMcpjsonServers`; `.codex/config.toml` for Codex), a review subagent, and the context guard described below. `npx boxglow setup-agent --check` lists what is installed and the one-time steps left to you (Codex: trust the project and approve the hooks in `/hooks` once). Open `npx boxglow serve --open` or the [VS Code extension](https://marketplace.visualstudio.com/items?itemName=sukima.boxglow-vscode) to edit the same repository file as the agent.
 
 ### Remember decisions across sessions
 
@@ -98,7 +128,8 @@ MCP provides `boxglow_context`, `boxglow_checkpoint`, and `contextToken` on guar
 
 | Command | What it does |
 |---|---|
-| `setup-agent [--agent codex\|claude-code\|all]` | Install only the selected agent’s instructions and skill (default: `all`). Claude Code also gets a SessionStart hook and `.mcp.json`. Existing unrelated settings are preserved; malformed settings stop setup. |
+| `setup-agent [--agent codex\|claude-code\|all] [--check]` | Install the selected agent's instructions, skill, hooks, MCP registration and review subagent (default: `all`). `--check` lists what is installed / missing. Existing unrelated settings are preserved; malformed settings stop setup. |
+| `hook session-start\|stop\|pre-tool` | Called by the agents' hooks (registered by setup-agent; JSON on stdin). Never stops the agent on its own failure. |
 | `mcp [--file path]` | MCP server over stdio: every command above as a tool (`boxglow_status`, `boxglow_add`, `boxglow_split`, `boxglow_start`, `boxglow_done`, `boxglow_ask`, `boxglow_answer`, ... and `boxglow_run` for the rest) |
 | `serve [--port 4174] [--open]` | Local server: the bundled web app at `http://localhost:4174/?serve=1` reading and writing your `boxglow.json` through a small API, with live reload when the CLI or an agent changes the file. Works in any browser (Firefox, Safari) |
 | `context <block> [--brief]` / `checkpoint <block> --note ... --context-token ...` | Read persistent context with a receipt (`--brief`: short form to read first, same token) / record a durable handoff |
@@ -111,13 +142,16 @@ MCP provides `boxglow_context`, `boxglow_checkpoint`, and `contextToken` on guar
 | `review-box <block>` / `box-ok <block> --note` | The same for a box's readiness (target, deliverable, checks, inputs, upstream branch answers) |
 | `lint [block] [--strict]` | Must-fix gaps (missing expect / acceptance, parent outputs nobody makes, exclusive branch paths both required) and review candidates (single child, unconnected outputs, token entries) |
 | `start <block> --note` / `done <block> --artifact name=url` | Record work in progress / completion with deliverables |
+| `port <block> --policy <output> [--policy-scope all\|<block>] [--advisory]` / `--skip-policy <box>.<output>` | Share a project-wide decision (technology choice, engine, style) with every box in scope without wires; they wait for it and read it in `context` |
+| `sendback <block> --to <block> --note "why"` | A check or evaluation failed: send the work back to the box that made it (it returns to In Progress, its artifacts are kept as rejected). Wires never go backwards |
 | `split <block> --spec '<json>'` | Decompose a box into child boxes with named inputs / outputs and connections |
 | `ask <block> "question" --options "A\|B"` / `answer <block> "A"` | Ask a human for a decision / answer it |
 | `project <name>` | Add another project box to the same file (the top level holds only the input node, the output node and project boxes) |
 | `export-block <block>` / `import-block <file> --parent <block>` | Reuse a box (with its sub-boxes, ports and wiring) across projects as a `*.boxglow-block.json` template |
 | `reopen <block> --note "why"` | Reopen an answered decision: the old answer goes to its history, the candidates stay |
-| `tidy` | Re-save the file by the rules: connected inputs take their source's name, major boxes collapsed, overlaps resolved (fixes files written before these rules) |
-| `port <block|project> --in/--out/--rename` / `disconnect` / `move <block> --parent <block>` / `remove <block> [--force]` | Edit ports, remove a wire, move a box to another parent (wires are re-routed through the boxes in between), delete a box (and its children with `--force`) |
+| `unask <block>` | Withdraw an unanswered question |
+| `tidy` | Re-save the file by the rules: connected inputs and outputs share one name, overlaps resolved (fixes files written before these rules) |
+| `port <block|project|inputs> --in/--out/--remove/--rename` / `disconnect` / `move <block> --parent <block>` / `remove <block> [--force]` | Edit ports (removing an input also removes the inputs it feeds), remove a wire, move a box to another parent (wires are re-routed through the boxes in between), delete a box (and its children with `--force`) |
 | `set <block> --status/--progress/--category/--due/--issue <url>/--repo` | Status, progress, category, schedule, JIRA / Redmine / GitHub issue link, repository |
 | `export --out docs/ROADMAP.md` / `export --format json` | Write the whole plan as Markdown (or JSON) |
 | `check` / `artifact` | Re-find deliverables after renames; attach a deliverable without finishing |
@@ -131,15 +165,9 @@ npx boxglow setup-agent --agent codex
 npx boxglow status --brief
 ```
 
-This installs `AGENTS.md` and `.agents/skills/boxglow/SKILL.md`; it does not create Claude Code settings. `--agent claude-code` installs only Claude Code files; omit `--agent` to install both. The CLI is sufficient for either agent. `status --brief` keeps decisions, unacknowledged answers, activity and next candidates while omitting the complete tree; `status --json` still returns the full project.
-
-For Codex MCP tools, register the server separately with an absolute path to your plan (run this in the same environment as Codex):
-
-```bash
-codex mcp add boxglow -- npx -y boxglow mcp --file /absolute/path/to/boxglow.json --actor codex
-```
+This installs `AGENTS.md`, `.agents/skills/boxglow/SKILL.md` (with `agents/openai.yaml` declaring the MCP dependency), `.codex/config.toml` (the local MCP server `boxglow`, tools auto-approved), `.codex/hooks.json` (session-start / stop / pre-tool) and `.codex/agents/boxglow-review.toml`; it does not create Claude Code settings. `--agent claude-code` installs only Claude Code files; omit `--agent` to install both. To use the tools before the project is trusted, you can also register the server in your Codex user config yourself: `codex mcp add boxglow -- npx -y boxglow mcp --actor codex` (setup-agent does not change your user config).
 
-Use `codex mcp list` to verify the registration. `.mcp.json` in a repository is the Claude Code setup; it is not the Codex MCP registration. MCP `boxglow_status` accepts `brief: true`, and validation failures are returned with `isError: true` so the agent can act on them.
+Two things Codex asks you to do once: trust the project when you first open it (project-level MCP and hooks only run in trusted projects), and approve the Boxglow hooks in `/hooks`. `npx boxglow setup-agent --check` shows these and what is installed. `.mcp.json` in a repository is the Claude Code setup; it is not the Codex MCP registration. MCP `boxglow_status` accepts `brief: true`.
 
 See the official [Codex skills locations](https://learn.chatgpt.com/docs/build-skills) and [Codex MCP configuration](https://learn.chatgpt.com/docs/extend/mcp?surface=cli).
 
@@ -192,7 +220,7 @@ Writes become new versions on the server and reach the synced devices on their n
 
 ## VS Code extension
 
-Install **Boxglow** from the [Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=sukima.boxglow-vscode): search for "Boxglow" in the Extensions view, or run `code --install-extension sukima.boxglow-vscode`. Keep the extension and the CLI on matching releases (extension 0.5.1 goes with boxglow 0.6.1).
+Install **Boxglow** from the [Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=sukima.boxglow-vscode): search for "Boxglow" in the Extensions view, or run `code --install-extension sukima.boxglow-vscode`. Keep the extension and the CLI on matching releases (extension 0.5.3 goes with boxglow 0.6.3).
 
 `vscode/` holds the extension's source. It opens `boxglow.json` as the same diagram inside the editor (custom editor "Boxglow"; right-click the file or use the editor title button / command *Boxglow: Open boxglow.json as a diagram*). The diagram follows the file when the CLI or an agent writes it, edits in the diagram are written back, and light / dark follow the VS Code theme. To build it yourself: `npm run build:vscode` (bundles the web app into `vscode/media/`), then `cd vscode && npm run package` (`.vsix`, install via *Extensions: Install from VSIX...*).
 
@@ -230,7 +258,7 @@ Boxglow never uploads your files. A deliverable is a **reference**: a URL, or fo
 | State | Meaning | Look |
 |---|---|---|
 | New (BlackBox) | Output decided, nothing inside yet | Slate header, ○ icon |
-| In Progress (GrayBox) | Being decomposed or worked on | Teal header, ◐ icon, progress bar |
+| In Progress (GrayBox) | Being worked on | Teal header, ◐ icon, progress bar |
 | Done (WhiteBox) | Output confirmed with a deliverable | Light header, ● with a check |
 
 Expanded boxes (containers) are drawn as frames: the shallower the level, the thicker the border, and the fill alternates per level so nesting is visible. Wires are thin and use colors never used for borders (thick green = the source already has a deliverable, thin amber = not yet). Selecting a wire highlights the whole signal in orange, through parent ports, from the original output to the final input.
@@ -256,7 +284,7 @@ Expanded boxes (containers) are drawn as frames: the shallower the level, the th
 - Progress: set a percentage per box (slider in the inspector or `boxglow set <block> --progress 60`); parents average their children, WhiteBox counts as 100.
 - Required inputs: every input is required by default; mark one as optional (任意) in the I/O tab if the box can start without it. A New box whose required inputs are all ready shows a `Ready` chip, and `boxglow status` lists such boxes first under next candidates.
 - Category: tag a box with what kind of work it is (study, research, design, ui, build, verify, evaluate, improve, fix, docs, ops, other). It shows as a colored stripe and a short label on the box, and the drawer's Filter can narrow by it. `boxglow add "..." --category design` / `boxglow set <block> --category verify|none`.
-- Saving: the top bar always shows Saved / Unsaved / Saving and a Save button. A local file opened directly in the browser is a read-only live view; edit it through `npx boxglow serve` or the VS Code extension.
+- Saving is automatic: the top bar shows where the plan lives (browser or file) and Saved / Unsaved / Saving; plans in a file, serve or VS Code have a Save button (Ctrl+S) and an **Auto save** toggle: a file opened directly starts with auto save off (changes stay Unsaved until you save), serve and VS Code start with it on; the choice is remembered per kind of source. Retry appears when a save failed. A plan kept in the browser can be turned into a file with **Save to file** (Chrome / Edge pick a location and keep saving there; other browsers download a copy; the ⋯ menu has the same). A local file opened directly in the browser is a read-only live view; edit it through `npx boxglow serve` or the VS Code extension.
 - `boxglow validate` reports broken wiring as errors and "holes in the plan" (unconnected ports, Done boxes without deliverables) as warnings; `done` without `--artifact` warns.
 
 When a person answers a question an agent asked (`ask`), the answer stays listed as "Answered" (and editable) until an agent picks it up with `npx boxglow ack <block>` or by recording work on that box (`start`, `done`, `set`, ...). `status` lists such answers under "回答あり" so an agent never misses them.