boxglow 0.5.2 → 0.6.0

package/README.md

@@ -3,7 +3,7 @@
 # Boxglow
 
 **Plans and progress as boxes and wires. See at a glance what your AI agents and your team are working on.**
-Tasks are boxes with inputs and outputs; a box goes New (BlackBox: dark, output decided but nothing inside yet) → In Progress (GrayBox: hatched) → Done (WhiteBox: paper) as its output gets confirmed. Humans and AI agents (Claude Code, Codex, ...) edit the same `boxglow.json`; the UI shows who is working where, what is waiting for your decision, and what is left. The CLI alone is enough for an agent; the UI is for people.
+Tasks are boxes with inputs and outputs; a box goes New (BlackBox: output decided but nothing inside yet) → In Progress (GrayBox) → Done (WhiteBox) as its output gets confirmed, and the card header shows the state at a glance. Humans and AI agents (Claude Code, Codex, ...) edit the same `boxglow.json`; the UI shows who is working where, what is waiting for your decision, and what is left. The CLI alone is enough for an agent; the UI is for people.
 
 **計画と進捗を、ボックスと線で。AI エージェントとチームが今どこを作っていて、何が終わり、どこで判断を待っているかが一目でわかる。**
 
@@ -11,29 +11,27 @@ Tasks are boxes with inputs and outputs; a box goes New (BlackBox: dark, output
 - CLI for agents: `npx boxglow` (status / start / done / split / ask / answer ...)
 - License: MIT
 
-## Agent workflow improvements (Unreleased)
+## What's new in 0.6.0
 
-The current development build adds three optional workflow aids. Existing plans still load as schema v5; no strict checks are enabled automatically.
+- **A diagram you can read at a glance**: boxes are cards (category, title, state, then inputs on the left and outputs on the right) with a header colored by state. In View mode boxes are laid out in dependency order as numbered stages; a vertical, top-to-bottom view is one click away. Your own layout in the file is untouched and is used in Edit mode.
+- **Several agents at once**: claims (opt-in per plan) let an agent or sub-agent hold a box for a while so others leave it alone. Edits to different boxes merge automatically; only a box both sides changed asks you to choose.
+- **Sync between machines (experimental, off by default)**: "Start syncing" in `serve` and the VS Code extension, plans listed on the server, delete with 30-day restore.
+- **Saving moves only what changed**: adding, moving or growing a box pushes only the boxes it now overlaps; the rest of the plan keeps its positions.
 
-- **Readiness:** CLI resume/status and the UI's Next list separate ready work from input waits and name missing inputs. start warns by default; --reason records why work can start early. done without output artifacts still warns. To opt in per plan, use policy --start reject --done reject (or choose Agent workflow checks in project settings). Human actions are never rejected. A start reason is allowed even in strict mode.
-- **Scope:** scope B12 --goal "Goal" --non-goals "Excluded" --acceptance "Checks" --consult "When to ask" records four optional fields. Read them at the start of context, or expand Current scope in the inspector. Edit through ⋯ → Edit work scope. focus B12 prioritizes that box and its descendants; focus none clears it. Read-only scope/focus/policy commands take no changing options.
-- **Resume:** current state comes first. Completed handoff notes show only a count unless --include-completed is requested. Descriptions and notes show when they were written and whether they predate the status change; legacy dates stay unknown. Done can suggest reviewing an outdated description, but never rewrites it.
+Details and compatibility notes: [CHANGELOG.md](CHANGELOG.md). Update the CLI, `serve` and the VS Code extension (0.5.0) together.
 
-With guard enabled, scope/focus/policy writes require the latest --context-token and return a new token when the context changes. MCP has matching scope/focus/policy tools, start.reason and resume.includeCompleted. Strict completion accepts existing output artifacts or new --artifact values; reference material on the box does not count. Textual acceptance criteria remain a checklist for the agent/person, not an automatic test runner.
+### Keeping agent work on track
 
-**Compatibility:** workflowPolicy, focusBlockId, block.scope, descriptionUpdatedAt and statusChangedAt are optional. Old versions (0.4.2 and earlier) can read the plan but do not apply the new behavior; saving with them drops the new plan-level policy/focus fields. Use a supporting build for every writer, including running serve and the extension's bundled app. No release/version bump is included in this development change.
+- **Readiness**: `resume`, `status --brief` and the Next tab separate boxes that are ready from boxes waiting for inputs and name the missing inputs. `start` warns on missing inputs (`--reason` records why); `policy --start reject --done reject` makes it strict for one plan. People are never blocked.
+- **Scope**: `scope <box> --goal ... --non-goals ... --acceptance ... --consult ...` records what the work is and is not; it leads the output of `context`. `focus <box>` puts one box and its descendants first.
+- **Resume**: `resume` shows the current state and the latest handoff notes first, so the next session (or another agent) picks up where the last one stopped.
 
-### 日本語: 着手確認・今回の範囲・再開情報
+### 日本語: 0.6.0 の要点
 
-開発中の変更です。旧計画は形式 v5 のまま読め、厳格な確認は自動で有効になりません。
-
-- resume / status --brief / 画面の Next で、着手できる候補と入力待ちを分け、不足する入力名を表示します。start は既定で警告しつつ開始、--reason 付きなら理由を活動とログに残して警告なしで開始します。成果物なしの done も既定は警告です。
-- 計画ごとに policy --start reject --done reject を選ぶと拒否にできます。画面ではプロジェクト名 →「AI の作業確認」。人の操作は拒否せず、理由付きの開始は厳格設定でも可能です。各設定は warn で戻せます。
-- scope B12 --goal "達成すること" --non-goals "今回扱わないこと" --acceptance "完了条件" --consult "相談条件" で任意の4項目を記録します。context の先頭と詳細パネルから読め、画面の ⋯ →「作業範囲を編集」で編集できます。空欄は普段の画面に出しません。none または空文字で項目を消せます。
-- focus B12 は対象と配下を優先し、対象外は別の組に残します。focus none で解除できます。guard 有効時の scope/focus/policy 変更には最新の --context-token を付け、出力の新しいトークンを次に使います。
-- resume は現況を先に表示し、完了した引き継ぎは件数だけ出します。--include-completed または画面の展開ボタンで履歴を読めます。説明・引き継ぎの日時と状態変更との前後関係を示し、古い記録の日時は推測しません。
-- Done 後に説明の古い状況が残る可能性があるときは見直しを促します。本文は自動変更しません。完了条件の達成や成果物の品質を自動で証明するものではありません。
-- **旧版との併用:** 0.4.2以前は新しい制御を行わず、保存すると計画の確認設定・優先対象を落とします。新機能を使う計画の書き手は対応ビルドに揃えてください。今回は版番号変更・公開を含みません。
+- **一目で読める図**: ボックスは、分類・題名・状態・入力 (左)・出力 (右) のカードになり、見出しの色で状態がわかります。View では依存の順に「工程」として並び、縦 (上から下) の表示にも切り替えられます。ファイルの配置は変わらず、Edit ではその配置を使います。
+- **複数の AI の並行作業**: 受け持ち (計画ごとに有効化) で、エージェントやサブエージェントが箱を一定時間持てます。別の箱への編集は自動で統合し、同じ箱を両側で変えたときだけ選びます。
+- **端末間の同期 (試験的・既定はオフ)**: `serve` と VS Code 拡張の「同期を始める」、サーバー上の計画の一覧、削除と 30 日間の復元。
+- **保存で動くのは変えた箱の周りだけ**: 追加・移動・拡大した箱が新たに重なった箱だけを押し出し、ほかの配置は保ちます。
 
 ## Quick start with an AI agent
 
@@ -85,6 +83,11 @@ MCP provides `boxglow_context`, `boxglow_checkpoint`, and `contextToken` on guar
 | `guard on\|off` | Enable or disable context checks (setup-agent enables them) |
 | `resume [--json]` | Handoff notes, answers not yet acknowledged and next actions in one overview (read-only) |
 | `status [--brief]` | Markdown summary (`--brief` omits the full tree): pending decisions, who is working where, tree with ids, next candidates |
+| `context <block>` | Context for the box (parents, input providers, decisions, handoff) with its `readiness` (ready / needs detail / waiting) |
+| `claim <block>` | Hold a box without starting it (before adding detail or splitting; "not needed" when claims are off) |
+| `review-split <parent>` / `split-ok <parent> --note` | Material and checklist for reviewing a breakdown / record the review with its basis (goes stale when the material changes) |
+| `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 |
 | `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 |
@@ -97,7 +100,7 @@ MCP provides `boxglow_context`, `boxglow_checkpoint`, and `contextToken` on guar
 | `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 |
 | `merge <base> <ours> <theirs>` / `git-setup` | Box-level 3-way merge for Git (see below) |
-| `blocked`, `review`, `leave`, `show`, `log`, `layout`, `validate`, `prompt`, `group*` | See `npx boxglow help` |
+| `blocked`, `review`, `leave`, `show`, `list`, `log`, `layout`, `validate`, `prompt`, `group*` | See `npx boxglow help` |
 
 ### Codex setup
 
@@ -153,7 +156,7 @@ The server finds `boxglow.json` like the CLI does (current directory upwards, or
 
 ## 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.4.1 goes with boxglow 0.5.2).
+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.0 goes with boxglow 0.6.0).
 
 `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...*).
 
@@ -190,9 +193,9 @@ Boxglow never uploads your files. A deliverable is a **reference**: a URL, or fo
 
 | State | Meaning | Look |
 |---|---|---|
-| New (BlackBox) | Output decided, nothing inside yet | Dark fill, dashed border, ○ icon |
-| In Progress (GrayBox) | Being decomposed or worked on | Hatched fill, ◐ icon, progress bar |
-| Done (WhiteBox) | Output confirmed with a deliverable | Paper fill, ● with a check |
+| New (BlackBox) | Output decided, nothing inside yet | Slate header, ○ icon |
+| In Progress (GrayBox) | Being decomposed or 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.
 
@@ -203,12 +206,14 @@ Expanded boxes (containers) are drawn as frames: the shallower the level, the th
 - An input with no source is automatically promoted to the project's input (dashed line) until someone connects it.
 - Activity badges: CC (Claude Code) / CX (Codex) / human, states working / blocked / needs decision / waiting review. Decisions are answered in the UI and read back by the agent.
 - Ready inputs: a wire whose source already has a deliverable (or is done) is drawn thick and green, and the input name gets a dot, so you can see at a glance which inputs are available.
-- Me / unassigned: pick yourself in the drawer; your boxes get a teal stripe. Owners are not printed on boxes (open the box to see them); filter by owner or "unassigned" in the drawer.
+- Me / unassigned: pick yourself in the drawer; your boxes get a teal stripe. Owners are not printed on boxes (open the box to see them); filter by owner or "unassigned" in the drawer. The table icon (In charge) next to the horizontal / vertical switch at the bottom left lists one member's (or the unassigned) boxes as a sortable table with due dates, estimates, waiting inputs and open questions; `boxglow list --assignee <name>` prints the same table.
 - Decisions: `ask` records a question with candidates; the answer is kept together with the candidates that were not chosen, and `reopen` moves an answer to the history so you can change course later.
 - Issue link: a box can carry a JIRA / Redmine / GitHub issue URL (`--issue`, or the More tab); the key (PROJ-123, #45) is shown on the box and opens the issue.
 - Input groups: project inputs can be grouped (e.g. "PCIe specs", "DDR specs"); each group is its own input node, and a group can be exported / imported as `*.boxglow-inputs.json` to reuse in another project (`boxglow group`, `group-set`, `group-export`, `group-import`).
-- Boxes never overlap: siblings are pushed apart automatically after moves, resizes and additions.
-- Edit / View: a top-bar toggle; in View mode drag-and-drop editing and the Delete key are off.
+- Boxes never overlap: when a box is added, moved or grows, only the siblings it now overlaps are pushed right or down; the grown box stays put and the rest of the plan keeps its positions.
+- Readiness: "the inputs are in" and "the work is concrete enough to start" are judged separately. An output carries a planned deliverable (`expect`, e.g. `file:src/auth/callback.ts`; `note` for an investigation) next to the real deliverables, and the acceptance criteria live in the scope. `boxglow context` prints the `readiness` (ready / needs detail / waiting, with reasons and the next commands), candidates are grouped the same way, and the canvas, side panel and In charge table show "needs detail". `start` warns on such a box (`policy --unprepared reject` refuses AI starts; a reason does not bypass it), and `boxglow claim <block>` holds a box for planning without starting it. `split` takes `expect` / `acceptance` per child (only for the ones you start now) and `parentMakes` for outputs the parent makes itself.
+- Branches: a branch box (+ Block → Branch, or `boxglow branch "<title>" --options "A|B"`) shows a fork that is not decided yet (an existing box can be turned into one from its ⋯ menu, or `boxglow branch --box <block>`). Each option is a path (output). Boxes on the paths wait for the answer; once you pick a path (Choose a path at the top of the side panel, or `boxglow answer`), the paths not chosen are skipped (faded, left out of progress, next candidates and lists). A branch is drawn as a card with cut corners and an "IF" diamond on its edge. Where paths come together, a merge part drawn like an OR gate (+ Block → Merge, or `boxglow join`) passes the work on as soon as any one path arrives.
+- Edit / View: a top-bar toggle; in View mode drag-and-drop editing and the Delete key are off. View lays boxes out in dependency order as numbered stages (left to right, or top to bottom with the vertical view in the zoom panel); Edit shows and edits the layout saved in the file. You cannot zoom out further than the whole diagram (Fit), and selecting a box or opening a panel keeps your zoom and position.
 - Short IDs: every box gets `B1`, `B2`, ... shown on the box; search by ID or title from the top bar (`/`), and use the ID in the CLI.
 - Schedule: start date, due date, estimate and actual hours per box; overdue boxes are flagged.
 - One source of truth: an input's description is the description of the output it is connected to (edit it there); only unconnected inputs carry their own text.
@@ -236,7 +241,7 @@ Boxglow is open core: everything that works with the one file on your machine (w
 
 ```bash
 npm install
-npm run dev        # http://localhost:5173/apps/boxglow/
+npm run dev        # http://localhost:5173/
 npm test           # Vitest (graph rules, merge, routing helpers)
 npm run build      # web app -> dist/, CLI -> bin/boxglow.js
 node bin/boxglow.js help
@@ -248,7 +253,7 @@ The CLI speaks the plan's language: `npx boxglow init --lang en` (or `ja`; the d
 
 URL parameters: `?demo=1` (sample), `&readonly=1`, `&embed=1`, `&theme=dark|light`, `&lang=en|ja` (UI language; otherwise the browser language, remembered once switched from the ⋯ menu), `?view=article` (= demo + embed + readonly), `#p=<id>`.
 
-The web app is hosted on Cloudflare Pages (`npm run deploy:pages` builds with `VITE_BASE=/` into `dist-pages/` and uploads it). Any static host works: `vite build` with `VITE_BASE` set to the path you serve from (the default `/apps/boxglow/` is the author's blog mirror).
+The web app is hosted on Cloudflare Pages (`npm run deploy:pages` builds with `VITE_BASE=/` into `dist-pages/` and uploads it). Any static host works: the default build uses relative paths, so `dist/` can be served from any path (set `VITE_BASE` to use absolute paths).
 
 Browser checks live in `e2e/` (`npm run e2e`): wires never crossing boxes on every tab of the example plans (also with squeezed positions), tab switching time, double-click / selection / decision flows, the English UI and the VS Code webview mode. They need Playwright from outside this repository (`PLAYWRIGHT=<path>`; see `e2e/run.sh`) and are not part of CI; the unit and property tests (`npm test`) are.