From f328406bb5705b048e498eeccf72ac8dc1e5206c Mon Sep 17 00:00:00 2001 From: Justin Parker Date: Sun, 11 Oct 2026 16:39:25 -0700 Subject: [PATCH] Sync upstream into v2.7.0: the git board skill replaces git-commit (ticket-free), and console docs and tests are split up AI Assisted --- .agents-docs/AGENTS-architecture.md | 51 +- .agents-docs/AGENTS-code-style.md | 2 +- .agents-docs/AGENTS-development-commands.md | 4 +- .claude/skills/sync-repo/sync-repo.enc | 2 +- .readme/web-console.md | 29 +- AGENTS.md | 4 +- CHANGELOG.md | 46 + QUICK-REFERENCE.md | 4 +- README.md | 11 +- docs/index.html | 4 + .../screenshots/dashboard-utilities-dark.webp | Bin 93930 -> 84968 bytes .../dashboard-utilities-light.webp | Bin 101418 -> 92058 bytes install.js | 14 +- package.json | 4 +- plan2code-loop/README.md | 4 +- scripts/capture-screenshots.mjs | 6 +- scripts/fixture-helpers.mjs | 66 + scripts/skill-script-helpers.mjs | 48 +- scripts/test-getting-started.mjs | 14 +- scripts/test-git-repo.mjs | 411 + scripts/test-launcher.mjs | 72 +- scripts/test-script-changelog.mjs | 23 +- scripts/test-script-git-commit.mjs | 299 - scripts/test-script-git.mjs | 1045 +++ scripts/test-skill-scripts.mjs | 7 + scripts/test-web-console-chat-stress.mjs | 331 + scripts/test-web-console-chat.mjs | 433 + scripts/test-web-console-concurrency.mjs | 420 + scripts/test-web-console-git.mjs | 619 ++ scripts/test-web-console-hardening.mjs | 184 + scripts/test-web-console-lifecycle.mjs | 923 +++ scripts/test-web-console-logic.mjs | 1885 +++++ scripts/test-web-console-qa.mjs | 349 + scripts/test-web-console-server.mjs | 718 ++ scripts/test-web-console-session.mjs | 1344 ++++ scripts/test-web-console-source.mjs | 438 + scripts/test-web-console-speed.mjs | 683 ++ scripts/test-web-console-subagents.mjs | 408 + scripts/test-web-console-workspace.mjs | 362 + scripts/test-web-console.mjs | 7103 ----------------- scripts/web-console-test-helpers.mjs | 306 + src/launcher/plan2code.js | 56 +- src/plan2code-0-pathfinder.md | 4 +- src/plan2code-1-plan.md | 6 +- src/plan2code-1b-revise-plan.md | 4 +- src/plan2code-2-document.md | 2 +- src/plan2code-3-implement-review.md | 2 +- src/plan2code-3-implement.md | 6 +- src/plan2code-4-finalize.md | 10 +- .../changelog-state.mjs | 2 +- src/plan2code-changelog.md | 10 +- .../git-state.mjs | 307 - src/plan2code-git-commit.md | 58 - src/plan2code-git-scripts/git.mjs | 883 ++ src/plan2code-git.md | 118 + src/plan2code-handoff.md | 2 +- src/plan2code-init-update.md | 2 +- src/plan2code-init.md | 2 +- src/plan2code-quick-task.md | 6 +- src/plan2code-review.md | 4 +- src/plan2code.md | 23 +- src/skill-scripts/common.mjs | 37 +- src/web-console/building-review.md | 148 + src/web-console/building.md | 458 +- src/web-console/console-attachments.md | 17 + src/web-console/console-chat.md | 142 + src/web-console/console-finish.md | 118 + src/web-console/console-launches.md | 65 + src/web-console/console-meter.md | 56 + src/web-console/console-stop.md | 97 + src/web-console/console-subagents.md | 85 + src/web-console/console-trouble.md | 20 + src/web-console/console-workspace.md | 80 + src/web-console/console.md | 1543 +--- src/web-console/console.mjs | 388 +- src/web-console/git-repo.mjs | 542 ++ src/web-console/lib.mjs | 330 +- src/web-console/notes/changelog.md | 23 + src/web-console/notes/document.md | 12 + src/web-console/notes/finalize.md | 32 + src/web-console/notes/git.md | 119 + src/web-console/notes/handoff.md | 11 + src/web-console/notes/implement.md | 155 + src/web-console/notes/init.md | 14 + src/web-console/notes/pathfinder.md | 76 + src/web-console/notes/plan.md | 17 + src/web-console/notes/quick-task.md | 90 + src/web-console/notes/review.md | 34 + src/web-console/notes/revise-plan.md | 18 + src/web-console/picker.mjs | 2 +- src/web-console/public/answers.js | 85 +- src/web-console/public/app.css | 251 +- src/web-console/public/app.js | 1395 +++- src/web-console/public/chat.js | 4 +- src/web-console/public/git-board.js | 382 + src/web-console/public/help.js | 2 + src/web-console/public/index.html | 310 +- src/web-console/public/meter.js | 43 +- src/web-console/public/pr-url.js | 36 + src/web-console/public/render.js | 83 +- src/web-console/public/subagents.js | 2 +- src/web-console/server.mjs | 118 +- version.json | 4 +- 103 files changed, 17636 insertions(+), 9991 deletions(-) create mode 100644 scripts/fixture-helpers.mjs create mode 100644 scripts/test-git-repo.mjs delete mode 100644 scripts/test-script-git-commit.mjs create mode 100644 scripts/test-script-git.mjs create mode 100644 scripts/test-web-console-chat-stress.mjs create mode 100644 scripts/test-web-console-chat.mjs create mode 100644 scripts/test-web-console-concurrency.mjs create mode 100644 scripts/test-web-console-git.mjs create mode 100644 scripts/test-web-console-hardening.mjs create mode 100644 scripts/test-web-console-lifecycle.mjs create mode 100644 scripts/test-web-console-logic.mjs create mode 100644 scripts/test-web-console-qa.mjs create mode 100644 scripts/test-web-console-server.mjs create mode 100644 scripts/test-web-console-session.mjs create mode 100644 scripts/test-web-console-source.mjs create mode 100644 scripts/test-web-console-speed.mjs create mode 100644 scripts/test-web-console-subagents.mjs create mode 100644 scripts/test-web-console-workspace.mjs delete mode 100644 scripts/test-web-console.mjs create mode 100644 scripts/web-console-test-helpers.mjs delete mode 100644 src/plan2code-git-commit-scripts/git-state.mjs delete mode 100644 src/plan2code-git-commit.md create mode 100644 src/plan2code-git-scripts/git.mjs create mode 100644 src/plan2code-git.md create mode 100644 src/web-console/building-review.md create mode 100644 src/web-console/console-attachments.md create mode 100644 src/web-console/console-chat.md create mode 100644 src/web-console/console-finish.md create mode 100644 src/web-console/console-launches.md create mode 100644 src/web-console/console-meter.md create mode 100644 src/web-console/console-stop.md create mode 100644 src/web-console/console-subagents.md create mode 100644 src/web-console/console-trouble.md create mode 100644 src/web-console/console-workspace.md create mode 100644 src/web-console/git-repo.mjs create mode 100644 src/web-console/notes/changelog.md create mode 100644 src/web-console/notes/document.md create mode 100644 src/web-console/notes/finalize.md create mode 100644 src/web-console/notes/git.md create mode 100644 src/web-console/notes/handoff.md create mode 100644 src/web-console/notes/implement.md create mode 100644 src/web-console/notes/init.md create mode 100644 src/web-console/notes/pathfinder.md create mode 100644 src/web-console/notes/plan.md create mode 100644 src/web-console/notes/quick-task.md create mode 100644 src/web-console/notes/review.md create mode 100644 src/web-console/notes/revise-plan.md create mode 100644 src/web-console/public/git-board.js create mode 100644 src/web-console/public/pr-url.js diff --git a/.agents-docs/AGENTS-architecture.md b/.agents-docs/AGENTS-architecture.md index f9e7c5a..2a03442 100644 --- a/.agents-docs/AGENTS-architecture.md +++ b/.agents-docs/AGENTS-architecture.md @@ -42,7 +42,7 @@ plan2code/ ├── src/web-console/ # Local browser UI bundled into every skill (Node.js, zero deps, no build) │ ├── console.mjs # CLI the agent drives: open, post, wait, chat, keep, status, stop, help │ ├── server.mjs, lib.mjs, picker.mjs -│ ├── console.md, building.md # Agent-facing contract +│ ├── console.md, console-*.md, notes/, building*.md # Agent-facing contract (console.md read once, the rest on demand) │ └── public/ # Page assets served to the browser ├── scripts/ # Development scripts │ ├── bench-web-console.mjs # Start-path timing @@ -50,8 +50,9 @@ plan2code/ │ ├── check-skill-table.mjs # src/plan2code.md "What each skill reads and writes" table vs each skill's prompt and references │ ├── parse-check.mjs # Imports every shipped browser module as real ESM │ ├── screenshots/ # JSON payloads posted per shot (`ask` reuses `question.json`; `finish` follows `signoff.json`) -│ ├── test-web-console.mjs, test-launcher.mjs, test-getting-started.mjs # node --test suites (the last keeps the newcomer docs in step) -│ ├── test-skill-scripts.mjs, test-script-.mjs, skill-script-helpers.mjs # Skill script suites and fixtures +│ ├── test-web-console-*.mjs, web-console-test-helpers.mjs # Web console suites, split by area, and their shared setup +│ ├── test-launcher.mjs, test-getting-started.mjs # Launcher suite; newcomer docs kept in step +│ ├── test-skill-scripts.mjs, test-script-.mjs, test-git-repo.mjs, skill-script-helpers.mjs, fixture-helpers.mjs # Skill script suites and fixtures │ └── validate-char-count.js # Pre-commit character count validator ├── skills/ # Generated, gitignored build output — one Agent Skill per src/ prompt │ └── plan2code-/ # SKILL.md plus references/ and scripts/ where present @@ -104,8 +105,8 @@ plan2code/ | `plan2code-review.md` | review | Post-implementation comprehensive review | | `plan2code-4-finalize.md` | 4 | Validate, summarize, feedback, archive (steps 1–7, +optional 6.5) | | `plan2code-handoff.md` | handoff | Compact the conversation into a self-contained handoff document for a fresh session | -| `plan2code-changelog.md` | changelog | Check the CHANGELOG version against the default branch, suggest editable entries for new work, keep `package.json` aligned, offer Git commit | -| `plan2code-git-commit.md` | git-commit | Commit with a clear message, suggested splits, a branch offer on the default branch, and an optional push | +| `plan2code-changelog.md` | changelog | Check the CHANGELOG version against the default branch, suggest editable entries for new work, keep `package.json` aligned, offer to commit the result through Git | +| `plan2code-git.md` | git | Branches, pull (with conflict help), push, publish and commits (clear message, suggested splits) on the web console's git board, or plain instructions in the terminal (`switch to main`, `commit and push`); asks before every push, publish and delete | ## Naming Convention @@ -143,7 +144,7 @@ Anything a workflow step decides with one correct answer (parsing a spec's check | Script | Skills | Does | |---|---|---| | `specs.mjs` | plan, revise-plan, document, implement, implement-review, review, quick-task, finalize, handoff | `list` / `status` (Phase Checklist, groups, task markers, numbering, the implement selection verdict, consistency checks) / `metrics` / `mark` / `archive`. Imports `scanProject()` from the bundled `web-console/lib.mjs`, so the dashboard and the skills share one spec classifier | -| `commit-msg.mjs` | implement(-review), review, quick-task, finalize, init-update | The `` / `AI Assisted` commit command (two `-m` flags), with optional `git add` | +| `commit-msg.mjs` | implement(-review), review, quick-task, finalize, init-update, git | The `` / `AI Assisted` commit command (two `-m` flags), with optional `git add` | | `review-scope.mjs` | review, implement(-review), quick-task | Review Mode's git fallback: files, lines, doc share, base branch | | `agents-md.mjs` | init, init-update | AGENTS.md structure, budget, orphans, broken links, always-inline sections | | `agent-files.mjs` | init, init-update | Detect and replace other agents' config files with AGENTS.md pointers | @@ -151,11 +152,11 @@ Anything a workflow step decides with one correct answer (parsing a spec's check | `feedback-payload.mjs` (own) | 4-finalize | STEP 6.5's payload (real sha256 prompt hashes) and the gh / browser / print submission tiers | | `handoff-path.mjs` (own) | handoff | Timestamped path, OS temp dir, git ignore check | | `changelog-state.mjs` (own) | changelog | `state`, `bump`, `set-package-version`: the default branch's version, whether the branch's entry can be extended (not released, not on another branch), the file's heading style, the gap since the entry was last touched; only `set-package-version` writes, and only the version field | -| `git-state.mjs` (own) | git-commit | `state`, `branch-check`, `init-check`: the repo snapshot, branch-name check and git init safety check, read-only | +| `git.mjs` (own) | git | `state`, `plan`, `branch-check`, `init-check`, `delete-check`, `cleanup-list`, `conflicts`, `pr-url`, `classify-error`: the repo snapshot, each action's exact command and confirm text (shared by the terminal and the board), branch-name, delete, cleanup and git init checks, a stopped rebase's conflicts, the pull-request link and git's errors sorted into kinds with a next step. Read-only: the agent runs every command it prints, and `guard()` refuses force push, hook skipping, amend, remote delete and blanket add | **Conventions** (`common.mjs`): Node 18+ built-ins only; one JSON object on stdout (`ok: false` plus `error`, `message`, `next` on a handled failure, the same line on stderr); exit 0 ok, 1 crash, 2 bad arguments, 3 not found, 4 invalid or check failed, 5 refused; `--help` documents commands and exit codes; writes take `--dry-run`; `PLAN2CODE_NOW` pins the clock for tests. A SKILL.md names a script as `node "/.mjs"`, where `` is `scripts/` beside it. -**Tests:** `scripts/test-skill-scripts.mjs` (installer plumbing and the shared scripts), `scripts/test-script-.mjs` (a skill's own), with fixtures from `scripts/skill-script-helpers.mjs`. They run the built `skills/` tree, and one test fails if any SKILL.md or shipped reference names a `/.mjs` that skill does not ship. The per-skill scripts import `./common.mjs`, which only sits beside them in the built tree, so run them from `skills/`, not `src/`. +**Tests:** `scripts/test-skill-scripts.mjs` (installer plumbing and the shared scripts), `scripts/test-script-.mjs` (a skill's own), with fixtures from `scripts/skill-script-helpers.mjs`. Importing that module rebuilds `skills/` unless `npm_lifecycle_event` is `test` (`npm test` has just built it). Git fixtures go through `copyFixture()` (`scripts/fixture-helpers.mjs`): built once per test file, copied per test, since every `git` process costs a few hundred milliseconds on Windows; a remote inside the fixture is added with `slashed()` so the copy's `.git/config` can be pointed at its own origin. They run the built `skills/` tree, and one test fails if any SKILL.md or shipped reference names a `/.mjs` that skill does not ship. The per-skill scripts import `./common.mjs`, which only sits beside them in the built tree, so run them from `skills/`, not `src/`. ## Repo-Local Skills (`.claude/skills/`) @@ -174,11 +175,14 @@ Optional local browser UI shipped with **every** skill. Source lives in `src/web | File | Role | |---|---| -| `console.mjs` | the CLI the agent drives: `open`, `post`, `wait`, `chat` (the instant Quick question check), `keep` (copy a cited note attachment into `specs//attachments/`), `status`, `stop`, `help` (a compact summary for an agent that found the binary but not `console.md`) | +| `console.mjs` | the CLI the agent drives: `open`, `post`, `wait`, `chat` (the instant Quick question check), `keep` (copy a cited note attachment into `specs//attachments/`), `status`, `stop`, `help` (a compact summary for an agent that found the binary but not `console.md`; `help ` prints one contract file, `help topics` lists them). `post --wait ` posts and waits in one command | | `server.mjs` | HTTP server, spawned **detached** by `open` (never as a harness background task, which get killed on compaction and at assorted timeouts) | | `lib.mjs` | session paths, atomic writes, the patch merge, `validate()` (which also allows `templates` only as `"idea"` on a `text` item; anything else exits 3), `attachmentName()` (the kept-file name `-.`: the same upload always gets the same name), `repoRoots()` (returns `{ project, worktree, branch }`), `readOverview()`, and the three sweeps `open` runs fire-and-forget after it prints (see the cleanup design point below): `sweepUploads()`, `staleSessions()` / `removeSessions()` and `staleScratch()` / `removeScratch()`; plus `cleanupFindings()` / `removeCleanup()` for User Preferences → Cleanup | -| `public/` | `index.html`, `app.js`, `answers.js`, `labels.js`, `boot.js`, `chat.js`, `help.js`, `starters.js`, `workspace.js`, `meter.js`, `subagents.js`, `mentions.js`, `favicon.js`, `app.css`, `render.js`, `palette.js`, `favicon.svg` (Planny peeking up from the tab bar, served as `image/svg+xml`) with `favicon.png` (the same icon at 192 px, served as `image/png`) as the fallback, `vendor/marked.esm.js`, the chimes (`start-skill.mp3`, `bootup.mp3`, `start-stop.mp3`, `next.mp3`, `insert.mp3`, `sleeping.mp3`; which moment plays which is `SOUND_EVENTS` in `palette.js`, one switch per event saved in `looks.json`), and a `package.json` that only says `"type": "module"`, so Node (the server, `console.mjs`, `lib.mjs` and the tests import several `public/*.js` modules) parses them as ES modules without a reparse warning | -| `public/help.js` | the Help dialog's PURE rules: `HELP_TABS` (17 tabs: ids, order, labels, diagram flags; every tab uses the chosen highlight color), `helpTabFor()` (which tab opens, FR-8 order, first match wins: finished → Stopping and finishing, server gone or agent adrift → When something looks stuck, opened from the Workspace dialog → Your workspace, then Ask, the Subagents tab → Helpers (subagents), a red-meter dashboard → Session meter, dashboard, a doc or the Overview, a build, else What this page is) and `helpKeyTarget()` (roving arrow keys, Home, End, wrapping). No module-scope DOM, so `node --test` covers it | +| `public/` | `index.html`, `app.js`, `answers.js`, `labels.js`, `boot.js`, `chat.js`, `help.js`, `starters.js`, `workspace.js`, `meter.js`, `subagents.js`, `mentions.js`, `favicon.js`, `git-board.js`, `pr-url.js`, `app.css`, `render.js`, `palette.js`, `favicon.svg` (Planny peeking up from the tab bar, served as `image/svg+xml`) with `favicon.png` (the same icon at 192 px, served as `image/png`) as the fallback, `vendor/marked.esm.js`, the chimes (`start-skill.mp3`, `bootup.mp3`, `start-stop.mp3`, `next.mp3`, `insert.mp3`, `sleeping.mp3`; which moment plays which is `SOUND_EVENTS` in `palette.js`, one switch per event saved in `looks.json`), and a `package.json` that only says `"type": "module"`, so Node (the server and the tests import `answers.js`, `palette.js`, `labels.js`, `boot.js`, `chat.js`, `help.js` and `starters.js`) parses them as ES modules without a reparse warning | +| `public/help.js` | the Help dialog's PURE rules: `HELP_TABS` (18 tabs: ids, order, labels, diagram flags; every tab uses the chosen highlight color; The git board sits right after Watching a build), `helpTabFor()` (which tab opens, FR-8 order, first match wins: finished → Stopping and finishing, server gone or agent adrift → When something looks stuck, opened from the Workspace dialog → Your workspace, then Ask, the Subagents tab → Helpers (subagents), a red-meter dashboard → Session meter, dashboard, a doc or the Overview, a git session → The git board, a build, else What this page is) and `helpKeyTarget()` (roving arrow keys, Home, End, wrapping). No module-scope DOM, so `node --test` covers it | +| `git-repo.mjs` | the one read-only reader of a git repository: the worktree status (`countPending()`, behind `pendingFiles()`), the branch table, the default branch, a merge or rebase in progress, the remotes and their web addresses, the last fetch and the pull-request link; `snapshot()` is what `open` and every `reread` store as `state.git`. Every git call carries `GIT_OPTIONAL_LOCKS=0`, so a background look never takes the index lock. Imported by `console.mjs` and `lib.mjs`; the git skill's `git.mjs` reaches it through `common.mjs` | +| `public/git-board.js` | PURE, one import (`pr-url.js`): the git board's rules from a `state.git` snapshot: branch order and the Remote only fold at `REMOTE_FOLD` 50, whether a new branch name is free, which buttons show and are enabled, whether the board still waits on the agent (`boardAwaiting()`: from a click until the agent's next post, not just until `wait` collects it), the plain sentence each click sends as `reply`, the "Last refreshed" line, which files start ticked in the commit dialog, and the pull-request link. `app.js` only renders what it says | +| `public/pr-url.js` | PURE, no imports: `prUrl()`, the "open a pull request" link for the GitHub, GitLab, Azure DevOps and Bitbucket shapes (`null` for an unknown kind, no web address, or a non-https result). `git-repo.mjs` re-exports it, and the board's base picker rebuilds the link in the browser with the same code | | `public/workspace.js` | PURE, no imports: the Workspace's name rules (`nameProblem()`, `NAME_MAX`, `defaultName()`, `freeName()` for the `-2` suggestion), the footer label and its width tiers (`footerLabel()`, `FOOTER_TIERS`) and `changeLine()`, the `Workspace: …` reply line an agent is handed per change. Imported by the server, `console.mjs`, `lib.mjs` and the page | | `public/meter.js` | PURE, no imports: the session meter. `WEIGHTS` (the one place per-event points live; its keys are also `RUN_EVENTS`, the `run` events `post` accepts), `LAUNCH_COUNTED` (workflows whose launch itself scores), the built-phase sizing (`TASK_EVENTS`, the keys of `TASK_BONUS`: `implement-phase` +0 and `implement-review-phase` +1; `isTaskCount()` accepts a whole `tasks` from 1 to `MAX_TASKS` 999; `runPoints()` scores such a run `ceil(tasks / TASKS_PER_POINT)` (3) plus its bonus, and any other run its `WEIGHTS` value), `ANSWERS_PER_POINT` 2 (`answer` entries score per skill run, `floor(count / 2)`), `breakdownFrom()` (the click-the-ring list: one row per scoring entry plus one answers row per skill run), `pointsFrom()` (the count, its sum, folded from `ledger.ndjson` and deduplicated by id, never stored), `levelFor()` with `YELLOW_AT` 5 / `RED_AT` 10, `ringFraction()` (full at `RING_FULL` 15), `WORDS`, `tooltipFor()`, `RED_BANNER` and `meterView()` | | `public/mentions.js` | PURE, no imports: the `@name` popover's logic — `mentionAt()` finds an `@partial` at the caret, `matchNames()` filters the workspace names, `applyMention()` splices a pick in and returns the new caret. Used by the Ask box, notes and text answers | @@ -188,11 +192,13 @@ Optional local browser UI shipped with **every** skill. Source lives in `src/web | `update-check.mjs` | the dashboard's release check, server-only (never in `SERVABLE`): `compareVersions()` (numeric X.Y.Z, `null` otherwise), `latestTag()` (the highest `refs/tags/vX.Y.Z`, peeled `^{}` and pre-release tags skipped), `checkForUpdate({ installed, cacheFile, now, run })` (never throws) and `runLsRemote()` (`git ls-remote --tags` on the repo: no shell, `GIT_TERMINAL_PROMPT=0`, `GCM_INTERACTIVE=never`, SSH `BatchMode` when `GIT_SSH_COMMAND` is unset, `windowsHide`, killed at 10 s; git authenticates itself, the console never touches a credential). The answer, failures included, is cached for an hour in `~/.plan2code/console/update-check.json` (`UPDATE_CHECK_FILE`, in `PROTECTED_CONSOLE_FILES` so no sweep removes it). `server.mjs` starts it after the ready line and never awaits it; `stateFrame()` carries `update: { installed, latest }` only when a newer release exists (its `latest` is part of `haveKey()`, so a page that connected first still gets it), and `GET /version` returns `{ version, latest }`. Tests seed a fresh cached failure in every console home, so no test server reaches the network | | `public/chat.js` | the Quick question chat's PURE rules, shared by the server and the page: `CHAT_LIMIT` / `CHAT_MAX_CHARS` / `CHAT_MAX_ATTACHMENTS` (the combined image + document cap; `CHAT_MAX_IMAGES` is kept as an alias of it), `chatOffline()` (the server's `409 offline` guard), and the page's view model (`chatView`, `sendState`, `nextAbout`, `contextOptions`, `unreadDot` / `shouldChime`). Ask context is the `{ history, about }` model: `nextAbout()` records the last 3 places visited in `history` and sets `about` only when the person picks one from **+ Add context** (`contextOptions()` lists that history plus *This spec*); dropping it or a successful send clears it, so the page never attaches context on its own. Imports only `answers.js`, no module-scope DOM, so `node --test` covers it | | `public/starters.js` | PURE, no imports: the Role list (`ROLES`, `ROLE_NOT_SET`, `normalizeRole()`, `needsRoleNudge()`: the dashboard banner shows until `looks.json` carries any `role`), the 19 starter templates (Markdown `## heading` sections, shape pinned by a test) and their per-role orders (`TEMPLATES`, `TEMPLATE_ORDERS`, `templatesFor()`, `templateSwap()` for the replace prompt), and the Ask starter sets (`STARTER_SETS`, `STARTER_SET_FOR`, `startersFor()`). Imported by `app.js` and the tests; in `SERVABLE`, preloaded by `index.html` and parse-checked. The page owns the wording; a skill only flags its fresh-idea `text` card with `"templates": "idea"` | -| `public/answers.js` | the page's PURE answer-shaping logic (what an answer reads as, what a placeholder offers, whether a send carries an answer at all). Split out of `app.js` because `app.js` cannot be imported outside a browser, so anything left in it is untestable. `scripts/test-web-console.mjs` imports this directly. | +| `public/answers.js` | the page's PURE answer-shaping logic (what an answer reads as, what a placeholder offers, whether a send carries an answer at all). Split out of `app.js` because `app.js` cannot be imported outside a browser, so anything left in it is untestable. The `scripts/test-web-console-*.mjs` tests import it directly. | | `public/labels.js` | `taskLabel()` / `activityLabel()`: rewrites a build's `Task 4.2 of 6` activity line to `Task 2 of 6` (only for `implement` / `implement-review`; a plan's `Task 2.1` is a real section number). A separate module for the same reason as `answers.js`: pure, so `node --test` can import it | | `public/boot.js` | `playWake()`: the dashboard's first-open wake-up. Self-contained (it owns its timers, the listeners that swallow input mid-run and the one measured glide transform; the page's `stir()` callback times the nudge between the click and the boot, which `app.js` fills with one snore; `skipEl` — the muted Skip button, and Escape — ends the run early with `onSkip` as the cue to silence queued sounds) and free of module-scope DOM access, so it can be imported by the tests and kept out of `app.js`'s render paths; `GLIDE_AT_MS` / `DONE_AT_MS` are its timings | -| `console.md` | the agent-facing contract, which is what every console prompt points at. Its **Workflow notes** section holds the per-workflow detail (Dashboard, Init and Init Update, Document, Review, Handoff, Pathfinder, Planning, Revision, Finalize), which keeps the prompts themselves to a one-line pointer | -| `building.md` | the build half of the contract, for `implement`, `implement-review` and `quick-task`: progress posts (`agent.activity`, `agent.quietMinutes`), the sign-off (with the review offer as a verdict), the finish, and running the review on the page mid-session | +| `console.md` | the core of the agent-facing contract, read once per conversation (every skill ships the same copy, so a dashboard hop never re-reads it): starting, the turn (`post --wait`, the exit codes, handling a send, `settle`), posting, the payload and its kinds, documents (including `file` blocks), the house rules, and an index of the topic files below with the moment each is read. A test caps it at 24,000 characters | +| `console-finish.md` · `console-stop.md` · `console-chat.md` · `console-workspace.md` · `console-subagents.md` · `console-launches.md` · `console-meter.md` · `console-attachments.md` · `console-trouble.md` | topic files, each read only when its moment first comes: finishing (the finish and its buttons), stop requests (the way home mid-workflow, `stopWarning`, resuming a pause), Quick questions, the Workspace, standing instructions and helper reports, dashboard launches and the menu payload, the session meter's `run` events (read only when a `run` is refused: the notes inline every `run`), keeping a cited note attachment, and recovery | +| `notes/.md` | per-workflow notes (`init` for both inits, `pathfinder` with Briefs, `plan`, `revise-plan`, `document`, `implement` for both builds, `quick-task`, `review`, `finalize`, `handoff`, `changelog`, `git`). Each skill's Interface line reads `/console.md` and its own notes file right after `open`; a test checks every skill names one that exists | +| `building.md` · `building-review.md` | the build half of the contract, for `implement`, `implement-review` and `quick-task`: progress posts (`agent.activity`, `agent.quietMinutes`, `file` blocks re-read with `refresh`), the chat check between tasks, questions mid-build and stop requests; `building-review.md` is the review run on the page (the sign-off's `review` verdict, **Review it now**, Implement + Review's Stage 2), read only when asked for | Key design points: @@ -201,15 +207,16 @@ Key design points: - **Version in Help.** `GET /version` reads `version.json` beside `server.mjs`, falling back to `../../version.json` for a run from `src/` (`server.mjs` `/version` route). `renderHelpVersion()` in `app.js` fills `#help-version`. `computeExpectedSkills()` in `install.js` injects the root `version.json` into every `references/web-console/`, so a version bump changes every skill. - **Models in User Preferences.** `GET` / `POST /models` in `server.mjs` read the shipped `~/.plan2code/bin/models.json` and read/write the user's `~/.plan2code/models.json` (`SHIPPED_MODELS_FILE` / `USER_MODELS_FILE` in `lib.mjs`). `PLAN2CODE_MODELS_DIR` relocates both for tests. The launcher reads the same two files for its model menu. - **The wait is bounded.** `wait --seconds 240` exits `0` (answers), `10` (still waiting, `message: "Waiting on your answer in the web console"` to relay), `20` (server gone, resume it) or `30` (cancelled). The agent loops. Nothing blocks for the whole time a person takes. +- **A turn is one command, and the CLI does the bookkeeping.** Agent speed is model round trips and typed tokens, not the console (`bench-web-console.mjs --roundtrip`: Send→agent ~70 ms, post→page ~180 ms), so the CLI absorbs every step with one right answer: `consume()` marks the agent `working` when it hands over a submit (`markWorking()`), and `wait` hands the turn back (`markWaiting()`) when it starts with an open question, a finish, or on the dashboard or git board; `post --wait ` posts and waits in one process; `settle: true | [ids]` (`settleItems()` in `lib.mjs`) records the latest send's cards as answered from their `submitted`; a new or reopened question with no stated status sets `waiting` and waiting drops `quietMinutes` (`settleAgent()`); a doc whose content changed with no `version` moves up one (`mergeDocs()`); a chat reply with no `id` is `r`; doc blocks with `file` (and `select: "tasks"`, doc-level `refresh: true`) are read from the worktree by `resolveDocFiles()` before the merge, refusing paths outside it; and a hop (`__launch`, `__dashboard`, `__commit`) comes with `resume` (the exact `open --resume` command) and `skillFile` (`hopFor()`). The wait loop's health check runs beside the 50 ms polling instead of blocking it, and is aborted on exit. `help ` prints any contract file; `help topics` lists them. `token` defaults to the option key in the page's `tokenFor()`, and nothing reads `fallbackText`, so the contract no longer asks for either. - **The CLI hands the agent its terminal line.** `open`, `post` and `wait` (exits `0` and `10`) print `terminalLine: "→ Look at the web console: "` (`terminalLine()` in `console.mjs`), and `console.md` asks the agent to end every terminal message with the latest one verbatim, so the tool builds the line rather than the model. In `wait` it is added to the printed result only; the collected `result.json` on disk never carries it. `open` also prints `swept: { sessions, scratch }` when it found anything to clean. - **State fields written by `open`, not the agent.** Every `open` (fresh or resume) records `state.worktree` and `state.branch` from `repoRoots()` — the branch is read off `/HEAD` on the walk that already finds the gitdir (`""` on a detached HEAD or outside git; env-relocated repos ask git, as before) — and the page shows them in the footer as the workspace label (`footerLabel()`: `folder · branch`, or `folder + N folders · branch` once folders are added, stepping down through narrower tiers); a click opens the Workspace dialog. `state.wake = true` is set only by a fresh `open --workflow dashboard` and deleted by every resume (server restart, launch, Back to the dashboard); the page also keeps a per-sid `sessionStorage` guard so a reload never replays it. - **`looks.width` is a person-level preference** alongside theme, accent and sounds in `looks.json`. `CARD_WIDTHS` in `public/palette.js` (`narrow` 720, `comfortable` 880 — default — `wide` 1080) is read by the page (`cardWidth()` validates a saved value) and by `server.mjs`, which paints `data-width` on first load; `app.css` maps `data-width` onto the single `--card-width` variable that every column rule uses. - **`GET /overview` is the one route that reads a project file.** It serves `/overview.md` as `text/markdown` with `cache-control: no-store` (so the Overview tab is always fresh), or `404 { "error": "no overview" }`. A dashboard session honours `?spec=` only when it equals a `dir` in `state.scan.specs`; every other workflow uses `state.specDir` and ignores the query. The root is `state.worktree` (fallback `state.project`), and `readOverview()` resolves and `realpath`s the file and refuses anything outside the root's realpath, so `../`, absolute paths and outward symlinks all 404. - **Month-old sessions are deleted whole.** `open` lists `staleSessions()` (directories matching the session-id pattern whose `state.json` mtime is older than 30 days, never the sid being opened — no exceptions for paused sessions or unread sends) and `staleScratch()` (top-level regular `.json` / `.mjs` files in the console folder older than 30 days, never `looks.json` or `console-dir` — `PROTECTED_CONSOLE_FILES` — never a directory or symlink) before it prints, and removes them after; `removeSessions()` / `removeScratch()` re-check every name against the session-id pattern / the scratch-name rule before deleting — not the age, the skipped sid or the file type, which the `stale*` listing already decided, so never hand them names that did not come from it. `console.md` tells agents to write temporary payload files into the session's own folder so they go with it. -- **User Preferences → Cleanup deletes on demand, from a list the server makes.** `POST /cleanup` (origin-checked) with `{ scan: true }` returns `cleanupFindings()`: `{ items: [{ id, where, name, kind, bytes }], bytes }`, ids `session:` (the `staleSessions()` rule, and every file in the folder that old too, never the serving sid), `console:` (anything at the top of the console home but `PROTECTED_CONSOLE_FILES`, `sessions` and `runtime`, directories too) and `root:` (anything at the top of `~/.plan2code` but `KEPT_PLAN2CODE_ENTRIES`: `console`, `bin`, `launcher.json`, `models.json`). Both stray kinds must be untouched for `STRAY_GRACE_MS` (an hour, by the newest `lstat` mtime anywhere inside, since rewriting a file never moves its folder's mtime; unreadable reads as fresh): the same folders hold `workspaces.json.lock` and `writeJsonAtomic()`'s `..tmp`, which live for milliseconds. `root:` is only scanned when the console home is `/console`, so a test or dev home never reaches the real folder. Paths never go to the page. `{ delete: [id] }` runs `removeCleanup()`, which re-scans and removes only ids still on the fresh list (symlinks unlinked, never followed), returning `{ removed, bytes, failed }`. The page always shows the list before **Delete these**. +- **User Preferences → Cleanup deletes on demand, from a list the server makes.** `POST /cleanup` (origin-checked) with `{ scan: true }` returns `cleanupFindings()`: `{ items: [{ id, where, name, kind, bytes }], bytes }`, ids `session:` (the `staleSessions()` rule, and every file in the folder that old too, never the serving sid), `console:` (anything at the top of the console home but `PROTECTED_CONSOLE_FILES`, `sessions` and `runtime`, directories too) and `root:` (anything at the top of `~/.plan2code` but `KEPT_PLAN2CODE_ENTRIES`: `console`, `bin`, `launcher.json`, `models.json`) and `completed:` (each folder or link directly under the session worktree's `specs--completed/` whose newest mtime is older than the session age, 30 days; loose files there stay; the server passes `project: sessionWorktree() || PROJECT`, and without a `project` the archive is never scanned). Both stray kinds must be untouched for `STRAY_GRACE_MS` (an hour, by the newest `lstat` mtime anywhere inside, since rewriting a file never moves its folder's mtime; unreadable reads as fresh): the same folders hold `workspaces.json.lock` and `writeJsonAtomic()`'s `..tmp`, which live for milliseconds. `root:` is only scanned when the console home is `/console`, so a test or dev home never reaches the real folder. Paths never go to the page. `{ delete: [id] }` runs `removeCleanup()`, which re-scans and removes only ids still on the fresh list (symlinks unlinked, never followed), returning `{ removed, bytes, failed }`. The page always shows the list before **Delete these**. - **The console's path is stated, not searched for.** Each Interface line names `references/web-console/` beside the SKILL.md and the `~/.plan2code/console/console-dir` fallback; the prompts with room (all but pathfinder, plan, document and finalize, which sit near the char limit) also name the canonical global install path `~/.agents/skills//references/web-console/` (the skills CLI's real store; every agent dir links into it), and every `console.mjs open` writes `HERE` to `~/.plan2code/console/console-dir` (only `open`, so a `help` or dev run from `src/` never repoints it) so a later session can read the path from a fixed place. Without these the agent hunts the skill install dirs on every session. -- **The dashboard scan knows whether the folder is a git repository.** `scanProject()` returns `{ hasAgents, isGit, pending, specs }`; `isGit` comes from `insideGitRepo()`, the same filesystem walk `findRoots()` does (no `git` process, linked worktrees and submodules count, a set `GIT_DIR` / `GIT_WORK_TREE` / `GIT_COMMON_DIR` counts as a repo). When it is `false` the Git commit card stays clickable and shows `GIT_INIT_NOTE` ("Not a git repository yet: it offers to start one") as its detail line; a scan with no `isGit` counts as a repo. In a repo, `pending` is `pendingFiles()` in `lib.mjs`: one `git status --porcelain -z` (3 second timeout, `null` when git cannot say) counting modified, staged, deleted and untracked paths. At `0` the card greys out with `GIT_CLEAN_REASON`; above it the detail line is `pendingNote(n)` ("3 files to commit"); `null` leaves it clickable. A finish with `commit: true` puts a **Commit it now** button on the finished screen (`commitOffer()`, `renderCommitOffer()`); its `__commit` press makes the agent resume as `git-commit` in the same session. A confirm item may carry `files: [{ path, state }]`, drawn as a collapsed table by `filesTable()`. Subagents is **on** by default for the five opted-in skills (`defaultSetting()`); a saved Off stays off. - **`open` needs no payload, and runs first.** `--file` and `--title` are optional (the title defaults to the folder name). Every skill's Interface line puts `node "/console.mjs" open --workflow ` BEFORE reading console.md or the project, and a test (`every skill opens the console before it reads anything`) keeps it that way; a blank session renders a starting screen ("Starting Pathfinder", Planny in flight) until the first post. Every skill replaces the flight with its own animated pose (init — init-update borrows it — pathfinder, plan — revise-plan borrows it — document, implement — implement-review borrows it — finalize, quick-task, review, handoff; only the dashboard keeps the flight), cloned by `startStage()` in `app.js` from `