boxglow 0.4.0 → 0.5.0

package/README.md

@@ -11,6 +11,30 @@ 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)
+
+The current development build adds three optional workflow aids. Existing plans still load as schema v5; no strict checks are enabled automatically.
+
+- **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.
+
+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.
+
+**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.
+
+### 日本語: 着手確認・今回の範囲・再開情報
+
+開発中の変更です。旧計画は形式 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以前は新しい制御を行わず、保存すると計画の確認設定・優先対象を落とします。新機能を使う計画の書き手は対応ビルドに揃えてください。今回は版番号変更・公開を含みません。
+
 ## Quick start with an AI agent
 
 ```bash
@@ -100,11 +124,22 @@ The web app opens a local `boxglow.json` directly only in Chrome / Edge (File Sy
 
 ### Save conflicts and recovery
 
-CLI, local server and VS Code writers share a file lock (a `<file>.boxglow-lock` folder that records its owner). Writers wait a few seconds for each other, a lock left behind by a crashed process is recovered automatically, and concurrent CLI commands reload and retry. CLI/server saves compare the read revision and replace the file atomically; a stale writer must reread instead of replacing newer changes. The local API requires `If-Match` from the GET response's ETag, same-origin requests, an allowed loopback Host, JSON content type, valid schema/references and a body of at most 5 MiB.
+CLI, local server and VS Code writers share a file lock (a `<file>.boxglow-lock` folder that records its owner: pid, host, OS, process-ID space and process start). Writers wait a few seconds for each other and concurrent CLI commands reload and retry. A lock is recovered automatically only when its owner is confirmed gone: same host, same OS, same process-ID space, and the pid no longer exists or now belongs to a different process. The process-ID space can be verified on Linux (including WSL); on Windows and macOS a leftover lock is never taken automatically and is removed with `boxglow unlock`. CLI/server saves compare the read revision and replace the file atomically; a stale writer must reread instead of replacing newer changes. The local API requires `If-Match` from the GET response's ETag, same-origin requests, an allowed loopback Host, JSON content type, valid schema/references and a body of at most 5 MiB.
 
 The GUI retains unsaved edits when a save fails or another writer changes the file. Its persistent notice offers retry, JSON export and an explicit three-way merge. Changes to different fields are both kept; for a field changed on both sides, **Compare and choose** shows the two values side by side and you pick one (the choice and both values are recorded in the activity log). Export unsaved JSON for a separate backup. VS Code shows Saved only after `applyEdit`, `document.save()` and disk-content confirmation succeed. A 10-second acknowledgement timeout remains Unsaved and permits retry.
 
-Direct File System Access opening is **read-only**, with live updates. Use `serve` or VS Code for shared editing; browser file handles cannot participate in the Node writer lock. Import JSON still creates a separate browser copy. All editors writing a shared file must use compatible Boxglow versions; unrelated programs and older versions do not honor the cooperative lock. **Versions and connection** at the bottom right of the UI shows the versions of the GUI, the connected CLI server and the VS Code extension; for the CLI alone use `boxglow --version` (`boxglow version --json` for details). If a process crashes leaving `<plan>.boxglow-lock`, first stop the associated Boxglow writers and verify no save is running, then remove that empty lock directory and retry. Never remove an active writer's lock.
+Direct File System Access opening is **read-only**, with live updates. Use `serve` or VS Code for shared editing; browser file handles cannot participate in the Node writer lock. Import JSON still creates a separate browser copy. All editors writing a shared file must use compatible Boxglow versions; unrelated programs and older versions do not honor the cooperative lock. **Versions and connection** at the bottom right of the UI shows the versions of the GUI, the connected CLI server and the VS Code extension; for the CLI alone use `boxglow --version` (`boxglow version --json` for details). A live writer's lock is never taken away just because a save takes a long time, and a lock whose owner cannot be verified is never taken automatically either: another host, another OS on the same machine name (Windows and WSL have separate process IDs), another container, Windows or macOS (no verifiable process-ID space), a lock written by 0.4.0 or older, a missing, unreadable or malformed owner record, or an interrupted recovery. In those cases commands stop with a message that names the owner and the verdict.
+
+```bash
+npx boxglow unlock                                             # show the lock: owner, verdict, token (read-only)
+npx boxglow unlock --remove --lock-token <token> --actor human # a person removes it
+```
+
+Before removing, stop every Boxglow that has the plan open (CLI, `serve`, VS Code; on every OS and machine involved). `unlock --remove` refuses when the owner is confirmed running, when another writer is confirmed to be in the middle of recovering it, or when the lock changed after it was shown. Release, automatic recovery and manual removal all take the same exclusive marker inside the lock before moving it and re-check which lock they hold it on, so a lock that a newer writer has taken in the meantime is not moved. A marker is published together with its owner record (never as an empty placeholder). Markers left by an interrupted recovery can only be taken over by `unlock --remove`, by adding a higher-numbered marker (existing markers are never renamed or deleted), and only when none of the existing markers belongs to a writer confirmed running. When that owner cannot be verified from here (another OS or machine, Windows, macOS), the takeover relies on you having stopped it: do not run two removals of the same lock from different environments at the same time. Agents may run `unlock` to read the status but ask a person to remove the lock.
+
+**Upgrading from 0.4.0**: update the CLI, `serve` and the VS Code extension together and restart any that are still running. 0.4.0 takes over locks by elapsed time and does not read the new owner fields, so mixing 0.4.0 and 0.4.1 writers on one plan is not safe.
+
+**VS Code on Windows with a plan inside WSL**: open the folder in a WSL window (Remote - WSL), where the extension runs inside WSL. A Windows window that opens `\\wsl.localhost\...` shows the plan read-only unless `security.allowedUNCHosts` contains `wsl.localhost`, because VS Code blocks extensions from that location; with the host allowed, saving works and locks taken on the other side are respected (never taken over, since Windows and WSL cannot check each other's processes).
 
 ## MCP server