Use US English spelling throughout and check it in npm test

AI Assisted
This commit is contained in:
jparkerweb committed 2026-10-26 06:36:46 -07:00
1 parent e67aaabdce
commit 899b3a48d8
84 files changed
+319 -240

No files matched your search

+2 -1
View File
@@ -10,6 +10,7 @@
- Interactive CLI via `@inquirer/prompts` (select, input, confirm)
- **File operations:** Synchronous fs by default; the web console's fire-and-forget sweeps and `readOverview()` use `fs.promises`
- **src/web-console:** ESM, Node built-ins only, no build step. It is bundled into every skill, so it must stay dependency-free and runnable as a plain `node console.mjs`. Anything added under `src/web-console/` ships to users — put tests in `scripts/` instead.
- **US English everywhere:** docs, comments, prompts, UI text, test names and commit messages use US spelling: color, gray, behavior, center, canceled, labeled, judgment, license, defense, and -ize / -yze verbs (normalize, analyze, summarize). `scripts/test-us-english.mjs` (in `npm test`) fails on common UK spellings in tracked files. A few names keep the UK spelling because they are data contracts read in several places, and that test allow-lists them: the `greyed` field on `skills.js` entries, `{ cancelled: true }` from the folder picker and `/workspace/browse`, the `"cancelled"` event `routes.mjs` broadcasts, and the loop's `result.cancelled`. Rename one only together with every reader. `aria-labelledby` is HTML and stays; vendored files (`public/vendor/`) stay as shipped.
## Gotchas / Pitfalls
@@ -29,7 +30,7 @@
- **Web console result-handoff invariant:** `result.json` holds answers a person pressed Send on. **An uncollected result (no `consumedAt`) is never overwritten and never deleted.** `/submit` and `/cancel` return 409 while one is pending, `open` clears the file only when it is already consumed, and `wait` stamps `consumedAt` **after** printing the result, never before, and exits by setting `process.exitCode` rather than calling `process.exit()`. That ordering is deliberate: an agent harness that kills a long shell command must not be able to land between "marked collected" and "handed over", and `process.exit()` can truncate an unflushed pipe. A repeat delivery is recoverable, a lost one is not. Two separate data-loss bugs came from breaking this in different places, and both were silent: the person sees "Sent", the agent never receives it. Any new code path that touches `result.json` must preserve the invariant, and `scripts/test-web-console-lifecycle.mjs` guards it (its "result handoff (regressions)" tests). Related: the server writes each submitted answer onto its item as `submitted`, and `validate()` in `patches.mjs` must keep excluding that field from the completion-marker and metrics-scraper scans, which are meant for agent-authored text only. A person who typed `TASK_COMPLETE` into an answer would otherwise make every later patch unpostable.
- **Web console oversized bodies:** `readBody()` and `readRaw()` (the `POST /upload` reader) in `routes.mjs` drain the rest of the body past `MAX_BODY` instead of calling `req.destroy()`, so an oversized body gets a 413 rather than a connection reset, and memory still stays capped. A new body reader must drain the same way.
- **Web console commands are tied to the directory `open` ran in:** `console.mjs` finds a running server through a handle file under a hash of the project directory (`handleFile(project, sid)` → `runtimeDirFor(project)` → `<RUNTIME_DIR>/<cwdHash(project)>/<sid>.json` in `sessions.mjs`, with `RUNTIME_DIR` = `os.tmpdir()/plan2code-console`, or `$PLAN2CODE_CONSOLE_HOME/runtime`), and the project is the working directory of `open` / `open --resume`. Run `status`, `chat`, `wait` and `stop` from that same directory. From anywhere else `status` says `live: false`, `chat` / `wait` report `server-gone` (exit 20) and `stop` stops nothing, while the server is in fact still running. It is easy to mistake for a crash when a scratch session is opened from the repo and then driven from its session folder; check `server.log` and `events.ndjson` (a real exit writes an `exit` event or a stack) before chasing one.
- **Windows temp paths in web console tests:** `os.tmpdir()` can be an 8.3 short path (`C:\Users\JUSTIN~1.PAR\...`), while `server.mjs` canonicalises its session dir with `fs.realpathSync.native` to the long form. Any test comparing a server-returned path (e.g. an upload's `path`) against the test's `session` must pass the test side through `fs.realpathSync.native()` first, and compare case-insensitively on Windows.
- **Windows temp paths in web console tests:** `os.tmpdir()` can be an 8.3 short path (`C:\Users\JUSTIN~1.PAR\...`), while `server.mjs` canonicalizes its session dir with `fs.realpathSync.native` to the long form. Any test comparing a server-returned path (e.g. an upload's `path`) against the test's `session` must pass the test side through `fs.realpathSync.native()` first, and compare case-insensitively on Windows.
- **Web console assets:** `computeExpectedSkills()` copies references as `Buffer`s, so binary files are fine. Adding a `public/` file needs the three edits in Architecture → Web Console. The vendored `marked.esm.js` sha256 is in `.readme/web-console.md`.
- **The default highlight color lives in two places:** changing it means editing `DEFAULT_ACCENT` in `public/palette.js` and the light, system-dark and explicit-dark `--accent*` values in `public/styles/tokens.css`. No test ties them together.
- **Reference file sizing guideline:** Files in `src/plan2code-*-references/` directories target ~100-200 lines each (soft guideline; evaluate splitting above 300). They are NOT subject to the 20,000 character limit. The pre-commit hook (`validate-char-count.js`) only checks `src/plan2code-*.md` flat files — subdirectory contents are automatically excluded.
+2 -2
View File
@@ -62,7 +62,7 @@ The root `npm test` does not run the metrics or bot vitest suites; run them in t
| `PLAN2CODE_NO_BROWSER` | `open` does not launch a browser (`NO_BROWSER` also works). |
| `PLAN2CODE_BROWSER` | Browser command line to run with the link appended, instead of the system default. |
| `PLAN2CODE_MODELS_DIR` | Moves the launcher model menus (`bin/models.json`, `models.json`) away from `~/.plan2code`, for tests. |
| `PLAN2CODE_PICKER_ECHO` | Tests only: `/workspace/browse` returns this as the picked folder instead of opening a picker (`-` means cancelled). |
| `PLAN2CODE_PICKER_ECHO` | Tests only: `/workspace/browse` returns this as the picked folder instead of opening a picker (`-` means canceled). |
| `PLAN2CODE_CONSOLE_TRACE` | Set to `1` on `open` to print a start-up step timeline to stderr. |
## Installer Menu Options
@@ -144,7 +144,7 @@ See the `skills/` build-artifact gotcha in [Code Style & Gotchas](./AGENTS-code-
1. Create `src/plan2code-<name>.md` with body content only and keep it under 20,000 characters.
2. Register it in `SOURCE_PROMPTS` in `install.js` (with the web-console `additionalReferences` entry every skill carries); add a `generateStepLabel()` case when needed. List any shared scripts it runs in `scripts: [...]`, and put its own scripts in `src/plan2code-<name>-scripts/` (with a `scripts/test-script-<name>.mjs` added to `package.json`'s `test` list).
3. Register it with the web console. The meter's points and labels, the resume command, Help's card list and `console.mjs help`'s workflow list are all derived from `skills.js`, so the edits are `skills.js`, `install.js` (step 2), the skill's prompt (step 1), its pose and its notes; `npm test` names anything else left out:
- `src/web-console/public/skills.js`: one entry (workflow, label, start pose, flags, subagents line, the meter's `weight`, `started` and `ran`, and `resume`) with its card (plus `help` when Help's line should differ from the blurb), and the card's `states` and `greyed`. Utilities go in group `"extra"` before Changelog.
- `src/web-console/public/skills.js`: one entry (workflow, label, start pose, flags, subagents line, the meter's `weight`, `started` and `ran`, and `resume`) with its card (plus `help` when Help's line should differ from the blurb), and the card's `states` and `grayed`. Utilities go in group `"extra"` before Changelog.
- `src/web-console/public/index.html`: its start pose, an `<svg class="pose pose-<workflow>" data-pose="<workflow>">` in `<template id="start-poses">` (pose CSS in `public/styles/poses.css`), unless its `pose` borrows an existing one (as Implement + Review borrows Implement's).
- Its help topic: a `src/web-console/notes/<workflow>.md` (named in the skill's Interface line) or a `HELP_TOPICS` alias in `src/web-console/cmd-help.mjs`.
- `src/plan2code.md`: the skill/workflow table and "What each skill reads and writes" (`scripts/check-skill-table.mjs`: every backticked token must appear in the skill's prompt).
+1 -1
View File
@@ -115,7 +115,7 @@ Conventions to follow, drawn from existing entries:
- Bold lead-in naming the prompt, file, or area, then an em dash (`—`), then the description.
- Reference prompts by their command (`/plan2code-1-plan`) or path (`src/plan2code-init.md`), not by informal name.
- One paragraph per bullet is fine — this CHANGELOG favours substantive entries over terse one-liners, and a bullet may carry extra indented paragraphs for detail.
- One paragraph per bullet is fine — this CHANGELOG favors substantive entries over terse one-liners, and a bullet may carry extra indented paragraphs for detail.
- A release with a big theme may open with a one-line summary paragraph directly under the `## vX.Y.Z` heading, before the first `###`.
Insert the new section directly below the `All notable changes...` line and above the previous version's heading.
@@ -51,13 +51,13 @@ For each CLI, compare the discovered list with the current one by `id` and show
| --- | --- | --- | --- | --- |
| added | `new-id` | — | New label | `devin models list` |
| gone | `old-id` | Old label | — | not in `devin models list` |
| relabelled | `same-id` | Old label | New label | Claude Code docs: <page> |
| relabeled | `same-id` | Old label | New label | Claude Code docs: <page> |
- **added:** offered by the CLI, not in the file.
- **gone:** in the file, no longer offered.
- **relabelled:** same `id`, a better or changed label. Propose a label in the file's existing style.
- **relabeled:** same `id`, a better or changed label. Propose a label in the file's existing style.
Summarise unchanged entries as a count under the table ("19 Devin entries unchanged") instead of listing them. If approving every **added** Devin row would take the list past 30 entries, say so above the table and by how many. Call out any likely rename before approval (see the rename warning under Validation rules). If both tables are empty, say the file is current and stop.
Summarize unchanged entries as a count under the table ("19 Devin entries unchanged") instead of listing them. If approving every **added** Devin row would take the list past 30 entries, say so above the table and by how many. Call out any likely rename before approval (see the rename warning under Validation rules). If both tables are empty, say the file is current and stop.
### Step 6 — Approve each change
@@ -68,7 +68,7 @@ Ask about each row, one at a time: **yes**, **no**, or **edit the label** (they
Apply only the approved rows:
- Keep `_note` verbatim.
- Keep the existing order. Remove a **gone** entry where it stands, change a **relabelled** label in place, and append each **added** entry at the end of its list.
- Keep the existing order. Remove a **gone** entry where it stands, change a **relabeled** label in place, and append each **added** entry at the end of its list.
- Write two-space-indented JSON with a trailing newline, matching the file's current formatting.
### Step 8 — Validate
+2 -2
View File
@@ -38,7 +38,7 @@ plan2code-metrics # → "View metrics status" the dashboard
|------|--------------|
| **1** | Raw data and a basic dashboard. Start here. |
| **3+** | AI analysis unlocks. Pattern detection starts working. |
| **5–10+** | Averages stabilise; generation-over-generation comparisons become meaningful. |
| **5–10+** | Averages stabilize; generation-over-generation comparisons become meaningful. |
You're looking for trends, not individual scores.
@@ -46,7 +46,7 @@ You're looking for trends, not individual scores.
## Sending feedback upstream
`/plan2code-4-finalize` can submit an anonymised metrics payload to the maintainers as a
`/plan2code-4-finalize` can submit an anonymized metrics payload to the maintainers as a
`community-feedback` issue on the repo. Community runs are cohorted by the Plan2Code version that
produced them, so your data improves the prompts everyone installs — without displacing the
maintainer's own measurements.
+9 -9
View File
@@ -32,7 +32,7 @@ Every console request carries two extra fields:
Clicking **Approve** in the browser is then byte-identical to typing `approved` in the terminal. No prompt logic ever forks. If the console is absent, refused, or times out, the agent prints `fallbackText` and the session continues in the terminal with nothing lost. Mid-session switching in either direction is free, because the markdown files under `specs/` remain the only source of truth.
This one decision is what keeps the integration from metastasising across twelve prompt files.
This one decision is what keeps the integration from metastasizing across twelve prompt files.
---
@@ -152,22 +152,22 @@ The waiter uses `fs.watch` on the session **directory** (watching a file breaks
| --- | --- |
| Port | `listen(0, '127.0.0.1')`, handle file in `os.tmpdir()/<tool>/<sha1(cwd).slice(0,8)>/`. This is Jupyter's `jpserver-<pid>.json` pattern and RFC 8252 §7.3. A fixed port is fatal here: you run git worktrees, so two agents in two checkouts of one repo is routine, and a fixed port makes that silently wrong. |
| Bind | the literal `127.0.0.1`, never `0.0.0.0`, never the string `localhost` (which may resolve to `::1` and produce the classic "server is up but the browser gets ECONNREFUSED" bug on Windows). |
| Auto-open | best-effort, never fatal. Skip when `DISPLAY` and `WAYLAND_DISPLAY` are both unset, or `SSH_CONNECTION` / `REMOTE_CONTAINERS` is set. Honour `BROWSER=` and `--no-open`. |
| Auto-open | best-effort, never fatal. Skip when `DISPLAY` and `WAYLAND_DISPLAY` are both unset, or `SSH_CONNECTION` / `REMOTE_CONTAINERS` is set. Honor `BROWSER=` and `--no-open`. |
| Orphan prevention | a **server-side idle deadline** (30 min, bumped by any authenticated request) is the mechanism, not a nicety. Windows has no real SIGTERM, and a detached server with no console never sees `SIGINT`, so signal handlers cannot be relied on. Plus a 4h absolute cap, a `pagehide` beacon, an explicit `stop`, and a reap sweep on every `start`. |
| Liveness test | `process.kill(pid, 0)` **and** a `/health` check whose returned session id matches the handle. PID reuse is real; the sid match is what disambiguates. |
Security, six controls, about 60 lines:
1. Bind `127.0.0.1`.
2. **`Host` header allowlist.** This is the DNS-rebinding defence and the highest-value line in the server. Vite shipped GHSA-vg6x-rcgg-rjx6 for exactly this omission.
2. **`Host` header allowlist.** This is the DNS-rebinding defense and the highest-value line in the server. Vite shipped GHSA-vg6x-rcgg-rjx6 for exactly this omission.
3. 128-bit token **in the URL path**, not the query string. Path placement also kills the Windows `cmd /c start` `&`-injection hazard, because the URL then contains no `&`.
4. First `GET /s/<token>/` sets `HttpOnly; SameSite=Strict` cookie and 302s to `/`. Token leaves the address bar, history and pasted screenshots; CSRF protection comes free.
5. `Origin` check on every mutating request.
6. Strict CSP with no `unsafe-inline`, which is why JS and CSS are separate files rather than one inlined HTML.
**On whether XSS matters here.** The tempting argument is "it is the user's own machine and the model would not write `<script>`". That misses the real risk. The page is same-origin with a server that reads and writes the user's files and holds the session token, so script in that page can post arbitrary answers back to the agent, which then acts on them with the agent's full tool permissions. And the markdown is only nominally agent-authored: in practice the agent is summarising a dependency README, a scraped page, a PR description, a log. Treat it as attacker-controlled.
**On whether XSS matters here.** The tempting argument is "it is the user's own machine and the model would not write `<script>`". That misses the real risk. The page is same-origin with a server that reads and writes the user's files and holds the session token, so script in that page can post arbitrary answers back to the agent, which then acts on them with the agent's full tool permissions. And the markdown is only nominally agent-authored: in practice the agent is summarizing a dependency README, a scraped page, a PR description, a log. Treat it as attacker-controlled.
The structural fix, rather than a filter: **vendor `marked` for `lexer()` only and render tokens to the DOM with `createElement` and `textContent`.** No HTML string is ever produced, so there is nothing for a sanitiser bypass to bypass, and the strict CSP holds. Roughly 120 lines of renderer. Hand-rolling the parser instead is a trap: hand-rolled markdown fails exactly where agent-authored technical documents live (a table inside a list item, a fenced block containing backticks) and its failure mode is usually an injection hole.
The structural fix, rather than a filter: **vendor `marked` for `lexer()` only and render tokens to the DOM with `createElement` and `textContent`.** No HTML string is ever produced, so there is nothing for a sanitizer bypass to bypass, and the strict CSP holds. Roughly 120 lines of renderer. Hand-rolling the parser instead is a trap: hand-rolled markdown fails exactly where agent-authored technical documents live (a table inside a list item, a fenced block containing backticks) and its failure mode is usually an injection hole.
### 3.4 Browser transport
@@ -283,7 +283,7 @@ Three panes, plus view tabs, closer to pathfinder's own vocabulary than to a gri
### What to take from grill-with-ui
- **Batch staging with one explicit Send.** Everything is local and reversible until one deliberate press. For a non-technical user this removes the terror of "did I just commit to that?"
- **The three-tier commitment vocabulary**: staged (amber, removable) → sent and pending (dashed, spinner) → recorded (green check). Honoured consistently on every surface.
- **The three-tier commitment vocabulary**: staged (amber, removable) → sent and pending (dashed, spinner) → recorded (green check). Honored consistently on every surface.
- **The whole stuck-agent apparatus**: live elapsed counter, disabled Send while working, a five-minute grace that re-enables Send with an explanation, server-gone detection with self-reconnect. About 40 lines, and more honest about agent latency than most commercial agent UIs.
- **Assumed regions.** The best idea in that repo: the generated artifact marks regions that depend on still-open questions with a dashed outline and "assumed, pending Q3". This transplants directly onto a plan taking shape.
- **Versioned artifacts with a staleness flag** and a one-line change note.
@@ -310,12 +310,12 @@ Built for a mixed product and engineering room reading one screen together.
- **One width variable.** `--card-width` on `:root` in `styles/tokens.css` sets the column the card, the pager and the document tabs share (`max-width: min(var(--card-width), 100%)`, so a narrow window still wins); no fixed `720px` column rule is left outside a media query. Three presets, picked under *Card width* in the looks panel and saved as `looks.width`: `narrow` 720px, `comfortable` 880px (the default, and the variable's own value), `wide` 1080px, applied as `:root[data-width="…"]`. `CARD_WIDTHS` in `palette.js` is the same list for the page's validation and the server's first-paint `data-width`; **`palette.js` and `app.css` must agree**, which is the one place the number is written twice. The dashboard keeps its own 860px layout. Inside the card the `62ch` / `68ch` measure caps come off (`.card .md, .card .prompt { max-width: none; }`) so a wider card is not a narrow column in a wide frame; documents keep `.md`'s 68ch.
- **One box grows.** On the primary card, the answer box that is being typed in — a `text` question's box, a choice's *Something else* box once picked, or the note under a verdict / confirm / recap once shown — is `textarea.grow`, and the card takes the column's full height above the pager (`.card.is-primary.has-grow { flex: 1 1 auto; }`). `fitGrowBox()` in `app.js` writes the card's free height as the box's `min-height`, **never under 160px**; a `ResizeObserver` watches the main column rather than the box, so the box growing can never retrigger it, and it writes only on a change over 1px. `resize: vertical` with that moving floor makes the handle taller-only; past the fill the card scrolls. Every other box keeps its ordinary size, and the notes panel is untouched.
- **A switch per sound.** Every cue is an event in `SOUND_EVENTS` (`palette.js`), each naming its file and rank: `startSkill` (`start-skill.mp3`, played once the dashboard's **Start** is accepted) 5, `bootup` 4, `sessionStart` / `sessionEnd` (`start-stop.mp3`) 3, `question` / `skillReady` / `chatReply` (`next.mp3`) 2, `newTab` (`insert.mp3`) 1, `snore` (`sleeping.mp3`, looped by the wake-up outside the queue) 0. The queue, the held slot and the one-at-a-time rule in `app.js` work on events, one `Audio` per file shared by the events that use it. User Preferences shows a *Play sounds* master (`looks.sound`) over one box per event, saved flat as `sound<Event>` (`soundStartSkill`, …) because `looks.json` only holds flat values; `soundPrefs()` turns any missing or non-boolean switch on, so a file from before the switches keeps every sound. A cue plays only while the master and its own switch are both on; the master off greys the boxes but keeps their ticks, and ticking a box plays it.
- **A switch per sound.** Every cue is an event in `SOUND_EVENTS` (`palette.js`), each naming its file and rank: `startSkill` (`start-skill.mp3`, played once the dashboard's **Start** is accepted) 5, `bootup` 4, `sessionStart` / `sessionEnd` (`start-stop.mp3`) 3, `question` / `skillReady` / `chatReply` (`next.mp3`) 2, `newTab` (`insert.mp3`) 1, `snore` (`sleeping.mp3`, looped by the wake-up outside the queue) 0. The queue, the held slot and the one-at-a-time rule in `app.js` work on events, one `Audio` per file shared by the events that use it. User Preferences shows a *Play sounds* master (`looks.sound`) over one box per event, saved flat as `sound<Event>` (`soundStartSkill`, …) because `looks.json` only holds flat values; `soundPrefs()` turns any missing or non-boolean switch on, so a file from before the switches keeps every sound. A cue plays only while the master and its own switch are both on; the master off grays the boxes but keeps their ticks, and ticking a box plays it.
- **Send breathes.** `#btn-send:not(:disabled)` runs `send-pulse`, a soft accent ring that spreads and fades every 2.4s; a disabled Send is still, and reduced motion switches it off.
- **Per-tab scroll memory.** An in-memory `Map` keyed by view id holds the scroller's position (the main column on a document or the Overview, the card on the questions view, with the item it belonged to), restored when the tab comes back. Page-local, never persisted, cleared when the session turns into or out of the dashboard.
- **The Overview tab.** Appears only while `GET /overview` returns a file for the session's spec (on the dashboard: the picker's spec; gone for *start from scratch*), fetched with `no-store` on load, on a spec change and on every tab click, so it always shows the file as it is on disk. Rendered through the same DOM-only markdown path as every doc, captioned read-only. It never becomes a doc: the page is not the record.
- **The footer slot.** The workspace label sits centred in the footer's middle track, 12px and muted: `footerLabel()` in `public/workspace.js` builds `folder · branch` (from the workspace's original folder and `state.branch`), or `folder + N folders · branch` once folders are added, and `renderWhere()` steps down through its narrower tiers (`FOOTER_TIERS`) until the text fits. A warning dot marks a missing or unreadable folder. A click opens the Workspace dialog (`#workspace-modal`), where each folder has its own **Copy path**. The notification pill is fixed over the same spot and covers it while it shows, on purpose: nothing there needs pressing while the pill is up. The dashboard keeps the footer for this label alone: `renderFooter()` puts `is-dash` on it, which hides the summary and Send (and on a narrow screen keeps the label, the one thing left in the bar); the footer only disappears there when there is no label to show.
- **The wake-up.** A fresh dashboard (`state.wake`, plus a per-sid `sessionStorage` guard) plays Planny powering on centre stage, as proven in `pathfinder/sketch-01`. The wake layer hides the dashboard behind a solid `var(--bg)` backdrop (`.wake::before`, so it follows the theme) whose opacity fades out over the same 0.6s as the glide, revealing the menu as he lands; the notification pill (`.banner`, z-index 46) stays above the layer (45). Before the first click or key he sleeps there on loop under a "Click to wake Planny" hint (`.wake.dormant`): Z's rising, slow breathing, slack arms swaying out of step, his feet pulsing like a standby light. While he sleeps the page tries to loop `sleeping.mp3` (browsers usually refuse until the first click, so this is normally silent). That click fades the hint and nudges him (`.wake.stirring`): he rocks gently about his feet (`wake-nudge`) while exactly one snore plays from the top, via the `stir()` callback `playWake()` awaits — timed by the snore's `ended`, capped at 6s, or a 2.6s timer when sounds are off or refused. Then the boot starts to `bootup.mp3` (in place of the opening chime; outranked only by the Start-skill cue, which cannot coincide with it because the wake layer swallows every click and key until the run ends), which fades out over 0.5s the moment the run ends or is aborted. The boot pops the Z's outward: 0.4s power-on and his feet blink · 1.35s feet plant · 1.5s / 1.9s arms lift off his sides · 2.5s the star opens lit, with a scan · 2.85s he glances left, right, then ahead · 3.2s smile · 3.6s hop and a cheer, star back to ink · 4.3s a 0.6s glide into the rail, measured once by `boot.js` and handed to CSS as `--wake-glide` · the menu groups rise in 60ms apart as he lands, and the note types in. Done by 5s (a fallback timer covers a hidden tab whose transition never fires). The beats are CSS keyframes on delays under `.wake.booting`, all inside `@media (prefers-reduced-motion: no-preference)`; there is no skip: from the waking click on, clicks and plain keys (no Ctrl/Meta/Alt) are swallowed so the nudge, boot and sound always play out; only a launch mid-run aborts it (snore stopped, boot-up faded), and under reduced motion `playWake()` resolves at once and the awake dashboard is simply there.
- **The footer slot.** The workspace label sits centered in the footer's middle track, 12px and muted: `footerLabel()` in `public/workspace.js` builds `folder · branch` (from the workspace's original folder and `state.branch`), or `folder + N folders · branch` once folders are added, and `renderWhere()` steps down through its narrower tiers (`FOOTER_TIERS`) until the text fits. A warning dot marks a missing or unreadable folder. A click opens the Workspace dialog (`#workspace-modal`), where each folder has its own **Copy path**. The notification pill is fixed over the same spot and covers it while it shows, on purpose: nothing there needs pressing while the pill is up. The dashboard keeps the footer for this label alone: `renderFooter()` puts `is-dash` on it, which hides the summary and Send (and on a narrow screen keeps the label, the one thing left in the bar); the footer only disappears there when there is no label to show.
- **The wake-up.** A fresh dashboard (`state.wake`, plus a per-sid `sessionStorage` guard) plays Planny powering on center stage, as proven in `pathfinder/sketch-01`. The wake layer hides the dashboard behind a solid `var(--bg)` backdrop (`.wake::before`, so it follows the theme) whose opacity fades out over the same 0.6s as the glide, revealing the menu as he lands; the notification pill (`.banner`, z-index 46) stays above the layer (45). Before the first click or key he sleeps there on loop under a "Click to wake Planny" hint (`.wake.dormant`): Z's rising, slow breathing, slack arms swaying out of step, his feet pulsing like a standby light. While he sleeps the page tries to loop `sleeping.mp3` (browsers usually refuse until the first click, so this is normally silent). That click fades the hint and nudges him (`.wake.stirring`): he rocks gently about his feet (`wake-nudge`) while exactly one snore plays from the top, via the `stir()` callback `playWake()` awaits — timed by the snore's `ended`, capped at 6s, or a 2.6s timer when sounds are off or refused. Then the boot starts to `bootup.mp3` (in place of the opening chime; outranked only by the Start-skill cue, which cannot coincide with it because the wake layer swallows every click and key until the run ends), which fades out over 0.5s the moment the run ends or is aborted. The boot pops the Z's outward: 0.4s power-on and his feet blink · 1.35s feet plant · 1.5s / 1.9s arms lift off his sides · 2.5s the star opens lit, with a scan · 2.85s he glances left, right, then ahead · 3.2s smile · 3.6s hop and a cheer, star back to ink · 4.3s a 0.6s glide into the rail, measured once by `boot.js` and handed to CSS as `--wake-glide` · the menu groups rise in 60ms apart as he lands, and the note types in. Done by 5s (a fallback timer covers a hidden tab whose transition never fires). The beats are CSS keyframes on delays under `.wake.booting`, all inside `@media (prefers-reduced-motion: no-preference)`; there is no skip: from the waking click on, clicks and plain keys (no Ctrl/Meta/Alt) are swallowed so the nudge, boot and sound always play out; only a launch mid-run aborts it (snore stopped, boot-up faded), and under reduced motion `playWake()` resolves at once and the awake dashboard is simply there.
---
+5 -4
View File
@@ -59,7 +59,7 @@ Details: [Development Commands](./.agents-docs/AGENTS-development-commands.md)
## Code Style & Gotchas
Language/toolchain conventions for `install.js` vs TypeScript packages, and pitfalls to avoid (version sync, `.gitignore` pre-flight, character limits, User Feedback table format).
Language/toolchain conventions for `install.js` vs TypeScript packages, US English spelling, and pitfalls to avoid (version sync, `.gitignore` pre-flight, character limits, User Feedback table format).
Details: [Code Style & Gotchas](./.agents-docs/AGENTS-code-style.md)
@@ -67,7 +67,7 @@ Details: [Code Style & Gotchas](./.agents-docs/AGENTS-code-style.md)
The project has a mascot called "Planny": a box with a star for an eye, stick arms and two small feet. He appears in installer output, workflow prompts, the loop, the Claude Code status line (box, star and feet, no arms) and the web console. ASCII variants are defined in the `MASCOT` constant in `install.js` (and `plan2code-loop/src/utils/logger.ts`) and appear in workflow markdown files: arms down at rest, one arm waving when he is asking something, both arms up when he is celebrating. The eye is always the star.
The web console draws him as inline SVG in `src/web-console/public/index.html`, where he doubles as the page's state indicator: his star lights in the highlight colour and he waves when something is yours to do, the star turns and his feet walk while the agent works, it goes green when all is done, he shows no arms at all when the agent is not answering, and he fades with his star shut when the connection drops. The parts are classed (`shell`, `eye`, `smile`, `foot`, and one `arms a-<mood>` set per mood) and `screens/core.js` switches mood with a single class, so the drawing stays in the markup and the styling in `styles/planny.css`. The nine skill start poses, the dashboard wake-up, `favicon.svg` / `favicon.js` and `src/launcher/plan2code.ico` all use the same design.
The web console draws him as inline SVG in `src/web-console/public/index.html`, where he doubles as the page's state indicator: his star lights in the highlight color and he waves when something is yours to do, the star turns and his feet walk while the agent works, it goes green when all is done, he shows no arms at all when the agent is not answering, and he fades with his star shut when the connection drops. The parts are classed (`shell`, `eye`, `smile`, `foot`, and one `arms a-<mood>` set per mood) and `screens/core.js` switches mood with a single class, so the drawing stays in the markup and the styling in `styles/planny.css`. The nine skill start poses, the dashboard wake-up, `favicon.svg` / `favicon.js` and `src/launcher/plan2code.ico` all use the same design.
```
╭───╮
@@ -82,7 +82,7 @@ The `Failure log` section below is a recording of mistakes made by previous AI A
When you make a mistake, get corrected, or discover something about this codebase that wasn't written down:
1. Add one line to the `Failure log` below, in the imperative, describing the correct behaviour.
1. Add one line to the `Failure log` below, in the imperative, describing the correct behavior.
2. Keep it specific to this repo. General advice belongs nowhere.
3. If this fix is a workflow rather than a rule, put it in `.claude/skills/` and link it from here.
4. Include the change in the same commit and mention it in your summary.
@@ -104,7 +104,8 @@ When you make a mistake, get corrected, or discover something about this codebas
- Register a new skill in `install.js` `SOURCE_PROMPTS` before running its `scripts/test-script-<name>.mjs`: importing `scripts/skill-script-helpers.mjs` rebuilds `skills/` and prunes any skill folder `install.js` does not list, so the script under test vanishes.
- When a `CHANGELOG.md` heading gets a version number, set the same number in `version.json` (with its `releaseDate`), the root `package.json` and README's `Version X.Y.Z` line in the same change, then run `npm run build:skills`. The changelog skill only touches `package.json`: v2.9.0 nearly shipped with `version.json` at 2.8.1, and README's line sat at 2.6.0 for three releases.
- When `npm test` fails only timing-bound suites (the chat stress test, the page-cards redraw test "a redraw keeps the place of...", then a cascade in the session suite starting at "no submitted frame within 5s") while the machine is busy, rerun those files alone, and the `node --test` list with `--test-concurrency=4`, before suspecting the change: they failed that way on untouched code under load during the web console file split, and the redraw test did again in three phases of web-console-health. In web-console-notepad, four more failed only in full runs and passed alone: the Workspace page's @-mention test, the dashboard page's handoff chip test, the session suite's document route (`connect ETIMEDOUT`) and the notepad page's 200 KB typing test (why its budget there is 200 ms, not the 92 ms it takes alone). In helper-strength, the page-cards test "a card cut by the window fades at its bottom edge..." did the same.
- Run `npm test` and `cargo test` from a terminal outside the desktop app, or with `PLAN2CODE_IN_APP`, `PLAN2CODE_APP_TOKEN`, `PLAN2CODE_APP_VERSION`, `PLAN2CODE_APP_ANNOUNCE`, `PLAN2CODE_EMBED_ORIGIN` and `PLAN2CODE_CONSOLE_SID` unset (`env -u ... npm test`): inherited from the app they fail about 34 tests that check behaviour outside the app (the update banner, the terminal line, cookies, open's browser launch), and a test console announces itself to the live window. A `cargo test` run mid-build once took the window over that way, then left an agent-less dashboard in it, and the build's question was never seen. The app now ignores sessions outside its console store (`take_announced` in `main.rs`), and the Rust console tests scrub the variables, but the JS suites do not.
- Run `npm test` and `cargo test` from a terminal outside the desktop app, or with `PLAN2CODE_IN_APP`, `PLAN2CODE_APP_TOKEN`, `PLAN2CODE_APP_VERSION`, `PLAN2CODE_APP_ANNOUNCE`, `PLAN2CODE_EMBED_ORIGIN` and `PLAN2CODE_CONSOLE_SID` unset (`env -u ... npm test`): inherited from the app they fail about 34 tests that check behavior outside the app (the update banner, the terminal line, cookies, open's browser launch), and a test console announces itself to the live window. A `cargo test` run mid-build once took the window over that way, then left an agent-less dashboard in it, and the build's question was never seen. The app now ignores sessions outside its console store (`take_announced` in `main.rs`), and the Rust console tests scrub the variables, but the JS suites do not.
- Post a helper as `done` or `failed` in the same turn its completion notice arrives: its row stays `running` on the Subagents tab until a post says otherwise (a build once reached its sign-off with one row spinning). A `finish` is now refused while any helper is `running`.
- Bring the Windows folder picker (`picker.mjs`, copied into `src/launcher/plan2code.js`) to the front with an Alt tap before `SetForegroundWindow`, never with `windowsHide`, the owner form's `TopMost`, `HWND_TOPMOST` or `AttachThreadInput`: measured on Windows 11, `SetWindowPos(HWND_TOPMOST)` returns true while the dialog stays non-topmost behind the browser, and only the Alt tap made it the foreground window. Check with `GetForegroundWindow` from a second process, since no test can see it.
- Add any new file or folder Plan2Code writes at the top of `~/.plan2code/` to `KEPT_PLAN2CODE_ENTRIES` in `src/web-console/sessions.mjs` and to the Cleanup test in `scripts/test-web-console-server.mjs`: User Preferences → Cleanup offers every other entry there for deletion once it is an hour old, and the desktop app's `app/` and `app.json` were about to be listed.
- When a test checks how `cmd.exe` finds a `.cmd`/`.bat` (current folder before PATH), clear `NoDefaultCurrentDirectoryInExePath` for the run under test (`env_remove` in Rust, `undefined` in a `test-launcher.mjs` `box.run` env): some shells (Claude Code's among them) already set it, and the decoy `.cmd` test for custom agents passed without its fix until it did.
+30 -23
View File
@@ -11,17 +11,24 @@ All notable changes to Plan2Code will be documented in this file.
- **desktop app**: the window's own title (and so its taskbar entry) now reads **Plan2Code - &lt;folder name&gt;** once a project is open, instead of a plain **Plan2Code** every window shares; two or more windows on different projects read apart without opening each one to check.
- **helpers**: a helper (subagent) no longer has to run on the session's own model and effort. A new shared reference, `helper-strength.md`, shipped in Pathfinder, Quick Task, Implement, Implement + Review and Review, matches each helper job to a strength (`light`, `standard`, `strongest` or `inherit`) and an effort (`low`, `medium` or `high`) from signals that can be checked, with floors, one-step escalation and a fallback order for tools that cannot set either, and never names a model or vendor. Review, Implement + Review and Pathfinder name the strength for the helpers they start, and the rules apply in terminal sessions too.
- **helpers**: Plan and Revise Plan now offer helpers (subagents), with the web console's **Subagents** button in the top bar, on by default like the other opted-in skills. Each skill has its own rule for what is independent enough to hand off. Plan uses helpers for reading the sources the person names, mapping separate areas of the codebase in Phase 2, gathering evidence on each open tech choice in Phase 4, and one fresh cross-check of the PLAN-DRAFT against the conversation in Phase 7; questions, decisions, sign-offs and the writing of the PLAN-DRAFT stay with the session. Revise Plan uses read-only lookups on the code behind affected and at-risk completed tasks at Steps 1 and 2 and, only after approval and when a revision touches 3 or more phase files, one helper per phase file to apply the approved edits under `specs/`. The rules live in each skill's Helpers section, so they apply in terminal sessions too. `helper-strength.md` now ships in both, with a row for each new kind of helper job (Plan's recon reuses the lookups row) and the PLAN-DRAFT cross-check held at `standard` or above, like a review.
- **web console**: the Subagents dialog has a **Helper strength** choice under Helpers: **Balanced** (the default), **Thrifty**, **Best** or **Match my session**, saved per project and skill and delivered to the agent as a `Helper strength:` line. Helper reports may say what each helper ran with (`strength`, `effort`), and the Subagents tab shows each as a colored badge with a small three-bar level mark (teal for low, amber for medium, violet for high; the session's own model in plain grey), while screen readers still hear one line, such as "Standard, medium effort".
- **web console**: the Subagents dialog has a **Helper strength** choice under Helpers: **Balanced** (the default), **Thrifty**, **Best** or **Match my session**, saved per project and skill and delivered to the agent as a `Helper strength:` line. Helper reports may say what each helper ran with (`strength`, `effort`), and the Subagents tab shows each as a colored badge with a small three-bar level mark (teal for low, amber for medium, violet for high; the session's own model in plain gray), while screen readers still hear one line, such as "Standard, medium effort".
- `plan2code` opens the app automatically when a desktop is available; `plan2code --classic` (or no desktop, e.g. over SSH) keeps today's terminal-only flow unchanged, and the installer brings the app in alongside the skills and the command.
- **custom agents**: add your own agent CLIs in the web console under **User Preferences → Agents** (name, command, arguments with `{prompt}` and `{model}` tokens, start prompt, bypass arguments, models) with a **Test** button that shows where the command is found. They are saved in `~/.plan2code/agents.json`, listed after Claude Code, Devin and Codex by both the `plan2code` command (`--cli <id>` picks one) and the desktop app, and New Session reuses the same agent. A broken file or entry is skipped with a warning and never stops anything. `/plan2code` only works in an agent that loads the installed Plan2Code skills; a blank start prompt starts the agent with nothing typed.
- **desktop app**: when no agent CLI is installed, the first-run checklist and the launch card explain what to install, with each agent's install command, an **Install page** link, and a **Check again** button that finds a newly installed agent (or a custom one) without restarting the app.
- **desktop app**: the taskbar entry now shows when Plan2Code needs you, mirroring the console's tab icon. Windows: a green dot on your move, a red dot on needs attention, none while busy or finished, and one short burst of flashes when the window is not focused (the button stays lit until focused). macOS: a red `!` dock badge on needs attention and one bounce (the system badge cannot be green). Linux: a count badge where the desktop supports it, plus the urgency hint. The dot clears when the agent ends, the page reloads or the page stops answering. **User Preferences → Desktop app** (inside the app only) has the switch **Show on the taskbar when Plan2Code needs me**, on by default and saved in the app's own `app.json`.
### 🔧 Changed
- **docs**: all prose, help text, skill prompts and comments now use US English spelling (color, gray, behavior, canceled, -ize), and `npm test` checks it (`scripts/test-us-english.mjs`).
- **web console**: **User Preferences → Highlight color** now offers 38 colors in two rows of nineteen, covering the range of a Paint-style picker: new **Maroon**, **Peach**, **Brown**, **Cream**, **Lemon**, **Forest**, **Mint**, **Aqua**, **Lavender**, **Pink** and **Mono** (near-black in light mode, near-white in dark). Five near twins were merged (Copper into Rust, Marigold into Gold, Mustard into Lemon, Jade into Emerald, Lilac into Violet); a saved choice of one of those keeps its twin instead of falling back to Ocean.
- **launcher**: when no agent CLI is installed, `plan2code` now prints each supported agent's install command and official page, and points at User Preferences → Agents for another CLI, before it exits.
- **desktop app**: the launch card's agent choice is built from the agents that are installed, so a machine with only Devin or Codex starts on it with Start enabled, instead of assuming Claude Code.
- **launcher**: `plan2code` no longer treats an SSH or service session on macOS or Windows as having a desktop, and asks before opening a folder that looks like it is not a project (no `.git`, `AGENTS.md` or `specs/`).
- **desktop app**: the app's own bar no longer repeats the open page as a second "page: " label; the console's own bar, inside the window, already names it. The web console now knows when the agent driving it is the desktop app (the same signal that already routed `open` to the app's window) and, only there, drops advice that assumed a plain terminal: its session meter, the finished-step guide and the dashboard's red-session banner point at the app's own **New Session** button instead of a command to paste into a new conversation; its own "update available" banner, a copy-pasted shell command, never shows, since **Update skills** already covers it in one click with no shell involved; and a slash command still offered to continue a step says to paste it into the app's terminal panel, which runs the real agent CLI, rather than "a new conversation" that does not exist there. Running a plain terminal is unchanged.
- **desktop app**: dropped the bar's own context-window meter and its restart nudge, front and back: a second, separately-tuned gauge beside the console's own Session meter (how much plan2code work this session has done) read as a duplicate of it, so there is now just the one, and it already points at New Session under the app (see above). The `agent_context` command, the Claude/Codex transcript readers behind it, and the context-nudge setting it read are removed from the Rust side too, not just unwired in the page. Every button that reconnects the console (after it stops, or after Update skills) is now labeled **Reconnect the console**, replacing the earlier mix of "Restart the console" and "Start it again" for the same action, and only one shows at a time.
- **desktop app**: the launch card's permission-mode tick is now **on by default** (checks off), matching how `plan2code` has always started an agent from the plain terminal. It previously defaulted off, the opposite of the terminal's own long-standing default; untick it for an agent that keeps its normal approval prompts.
- **web console**: Help's "When an update is out" line now knows when it is read inside the app too: there, it names **Update skills** in the bar instead of describing the dashboard's UPDATE AVAILABLE banner and a terminal command, since that banner never shows under the app and the command has no terminal to run in.
- **desktop app**: the top bar's **Restart** button is now **New Session**, and every place the console names it under the app (the session meter, the dashboard's red-session banner, the finished-step guide, the Welcome tip, Help's Ask and Finishing topics, the handoff copy button's description) says so too; the meter's own advice under the app is a single **Start a New Session** button in the user's highlight colour. Its confirmation no longer claims "What it was doing is not saved" (not always true).
- **desktop app**: the top bar's **Restart** button is now **New Session**, and every place the console names it under the app (the session meter, the dashboard's red-session banner, the finished-step guide, the Welcome tip, Help's Ask and Finishing topics, the handoff copy button's description) says so too; the meter's own advice under the app is a single **Start a New Session** button in the user's highlight color. Its confirmation no longer claims "What it was doing is not saved" (not always true).
- **desktop app**: with nothing saved yet, the terminal panel now starts docked right at a width that keeps the console's own side panels (such as Notes) from stacking under the main content, instead of the bottom dock it always opened with before; a saved choice from before is still kept exactly as it was.
- **desktop app**: docked right and collapsed, the terminal panel's **Expand** label now reads top to bottom instead of running off the edge of the narrow strip.
- **desktop app**: the agent no longer prints the console's web address in the terminal panel, since the page is already in the window beside it: `terminalLine` under the app points at the dashboard instead, and the agent contract says to give no link there.
@@ -31,7 +38,7 @@ All notable changes to Plan2Code will be documented in this file.
- **web console**: a plan's **Build order** card has a **Combine phases** button beside **No changes**. One click fills the box with a request to merge phases where possible while keeping each to a clear concern. It shows only in Plan and Revise plan, where the breakdown is phases.
- **web console**: Help now reads right in the desktop app throughout, not just in the topics fixed before: what this page is and how long it runs, the troubleshooting table and its diagram, scroll memory, drafts, the session meter's red advice, Ask's "no agent" line and Privacy's link and address notes all name the app's window, its terminal panel, **New Session** and **Reconnect the console** instead of a browser tab, a link or a new conversation. The status line's approval hint says "the terminal panel" there too. In a browser, Help is unchanged.
- **desktop app**: the top bar's buttons now look like the console's own: rounded, quiet until hovered, then in your highlight color from User Preferences (the app keeps it for the next launch), with **New Session** outlined in it as the likely next step.
- **desktop app**: the New Session confirmation shows Planny, drawn like the console's own (outlined shell, star eye, smile), holding a steaming cup of coffee, and its buttons use the console's style: **New Session** in your highlight colour, **Cancel** a plain button. The same highlight applies to the panel's other one-button prompts, such as **Retry** and **Reconnect the console**.
- **desktop app**: the New Session confirmation shows Planny, drawn like the console's own (outlined shell, star eye, smile), holding a steaming cup of coffee, and its buttons use the console's style: **New Session** in your highlight color, **Cancel** a plain button. The same highlight applies to the panel's other one-button prompts, such as **Retry** and **Reconnect the console**.
- **desktop app**: the top bar is rebuilt around two menus and one next step. The project shows as its folder name, with the full path and **Change project** in its menu; **New Session** always sits just left of the agent's menu, which carries a state dot, an amber **checks off** badge in place of the "Permission checks are off for ..." sentence, and **Change agent** once the agent has ended. The console's and the skills' messages share one slot at the right end that shows the most pressing step with its button (**Reconnect the console**, **Update skills**) and "+N more" for the rest, so the bar no longer overflows when several things go wrong at once. The repeated "Plan2Code" label, the full path, the "agent:" prefix and the long "Nothing starts until you press New Session" line are gone.
### 🐛 Fixed
@@ -93,12 +100,12 @@ All notable changes to Plan2Code will be documented in this file.
### ✨ Added
- **building habits**: Quick Task, Implement and Implement + Review now read one shared reference file, `references/building-habits.md`, at three moments. When a bug or an unexpected failing test turns up, they find the cause first: build a command that fails on the bug before changing code (or say why they cannot, rank their guesses with the evidence and let you decide), then keep the reproduction as a regression test in the project's existing test runner. When the plan asks for it, they build test first: write the test, see it fail for the right reason, then write the code. Before a restructure meant to change no behaviour, they pin the behaviour with tests that must pass unchanged afterwards. Adapted from Matt Pocock's [`diagnose`, `tdd` and `improve-codebase-architecture`](https://github.com/mattpocock/skills) skills and pstack's debugging playbook (both MIT).
- **plan**: the testing question gains a fourth choice, **Approach**: code first (the default) or test first. Test first is recorded in the PLAN-DRAFT's Testing Strategy table, and Document then orders each task's test before its code with a `Test:` line under the task naming where the test drives the behaviour.
- **building habits**: Quick Task, Implement and Implement + Review now read one shared reference file, `references/building-habits.md`, at three moments. When a bug or an unexpected failing test turns up, they find the cause first: build a command that fails on the bug before changing code (or say why they cannot, rank their guesses with the evidence and let you decide), then keep the reproduction as a regression test in the project's existing test runner. When the plan asks for it, they build test first: write the test, see it fail for the right reason, then write the code. Before a restructure meant to change no behavior, they pin the behavior with tests that must pass unchanged afterwards. Adapted from Matt Pocock's [`diagnose`, `tdd` and `improve-codebase-architecture`](https://github.com/mattpocock/skills) skills and pstack's debugging playbook (both MIT).
- **plan**: the testing question gains a fourth choice, **Approach**: code first (the default) or test first. Test first is recorded in the PLAN-DRAFT's Testing Strategy table, and Document then orders each task's test before its code with a `Test:` line under the task naming where the test drives the behavior.
- **review**: reviews run in a fresh helper that never saw the build; reports say how they ran. Wherever the tool can start a helper and the web console's Subagents switch is not off, every review (`/plan2code-review`, Implement + Review's Stage 2, Implement's "review" at sign-off and Quick Task's "Review it now") hands its analysis to one helper briefed only with the spec and the change set (the new `references/reviewer-brief.md`). The main session checks every finding in the source before you see it and drops what it cannot confirm. Each report carries a **Reviewed by** line: a fresh helper (with how many findings were checked and dropped), or this session, said once as not independent. Adapted from pstack's independent reviewer and Matt Pocock's [`code-review`](https://github.com/mattpocock/skills) guidance (both MIT).
- **xray**: a new skill, **Codebase X-ray** (`/plan2code-xray`), on the dashboard under *Useful any time*. Explain an area: how it works and why it is that way, citing files and the commits and pull requests behind it (git history always, `gh` when it is installed and signed in, and it says once which sources it could not use). Or find the rough spots: files that always change together, thin wrappers, tangled boundaries and busy code with no tests, ranked with a concrete "to change X today you must touch..." example each. You tick the ones worth fixing and only those go into `specs/<name>/ARCHITECTURE-BRIEF-<date>.md`, ready for Pathfinder or Plan. A new script, `xray.mjs`, does the counting from git history. Pathfinder and Plan point at it when the code is unfamiliar. Adapted from Matt Pocock's [`improve-codebase-architecture`](https://github.com/mattpocock/skills) skill (MIT) and pstack's codebase survey, `how` and `why`.
- **diagnose**: a new skill, **Diagnose a bug** (`/plan2code-diagnose`), on the dashboard under *Useful any time*. It finds a bug's cause and writes it up without fixing it, under the find-the-cause-first habit: a command that fails on the bug first (or, when it cannot build one, its guesses ranked with the evidence), then the cause in `specs/<bug-name>/DIAGNOSIS-<date>.md`. It then offers `/plan2code-quick-task` to fix it, or `/plan2code-1-plan` when the fix is big. The dashboard shows such a folder as a new spec state, **Bug diagnosed**, which lights Quick Task (suggested) and Plan and keeps Document, Implement, Implement + Review and Finalize greyed. Adapted from Matt Pocock's [`diagnose`](https://github.com/mattpocock/skills) skill and pstack's debugging playbook (both MIT).
- **quick-task**: asks "Write the test first?" when the change alters behaviour and the project already has a test runner, and names the test spot in the plan's Verify section. A bug fix starts with its reproduction.
- **diagnose**: a new skill, **Diagnose a bug** (`/plan2code-diagnose`), on the dashboard under *Useful any time*. It finds a bug's cause and writes it up without fixing it, under the find-the-cause-first habit: a command that fails on the bug first (or, when it cannot build one, its guesses ranked with the evidence), then the cause in `specs/<bug-name>/DIAGNOSIS-<date>.md`. It then offers `/plan2code-quick-task` to fix it, or `/plan2code-1-plan` when the fix is big. The dashboard shows such a folder as a new spec state, **Bug diagnosed**, which lights Quick Task (suggested) and Plan and keeps Document, Implement, Implement + Review and Finalize grayed. Adapted from Matt Pocock's [`diagnose`](https://github.com/mattpocock/skills) skill and pstack's debugging playbook (both MIT).
- **quick-task**: asks "Write the test first?" when the change alters behavior and the project already has a test runner, and names the test spot in the plan's Verify section. A bug fix starts with its reproduction.
- **show me it working**: Implement, Implement + Review, Quick Task and Finalize offer to show the change running before you approve, never required: reply `show me` in the terminal, or press **Show me it working** on the web console. The agent starts the app the way `AGENTS.md` says (working it out from the project and offering the line for `AGENTS.md` when it is missing, or asking you), looks at the change, stops what it started and records one line saying what was run and what was seen. Screenshots appear on the page only, never under `specs/`. Init and Init Update now ask how to start the app and where to view it. Adapted from pstack's proof-on-the-running-app idea (MIT).
- **web console**: a doc can show a picture. An image block (`"image": "shots/<name>.png"`) shows a PNG, JPEG or WebP the agent saved under the session's `shots/` folder; anything outside that folder, over 5 MB or not really an image is refused.
- **launcher**: `plan2code update` updates everything that was installed (the skills, the `plan2code` command and any of the status line, `plan2code-loop`, `plan2code-metrics` and `plan2code-bot`), with no menu and never uninstalling. Every global install now writes `~/.plan2code/install.json` listing what it installed, which `install.js --update` reads; with no record it updates the skills and the `plan2code` command.
@@ -119,9 +126,9 @@ All notable changes to Plan2Code will be documented in this file.
- **docs**: README, the quick reference and the web console guide say to update with `plan2code update` (or re-run the install command).
- **handoff**: every handoff now lives in `~/.plan2code/handoffs/` (a Markdown file plus a small `.json` beside it), owned by the web console, and handoffs older than 30 days are swept when the console opens. The Handoff skill writes there with no folder or `.gitignore` question, and Cleanup never lists the folder. Handoffs written to the OS temp folder or a `handoffs/` folder before this change are not listed.
- **dashboard**: a **Bug fixed** spec has a visible **Delete** that needs one confirm, and its chip no longer repeats the "bug fixed" line.
- **web console**: the review sign-off card lists **Approve this phase** before **Show me it working**, with the approve button outlined in the accent colour.
- **web console**: a sign-off's **yes** button (Quick Task's **Build it**, Finalize's **Archive it**) is outlined in your highlight colour too, like **Approve**. So is the yes of a yes/no question (such as Plan's **Write the plan**) and a recap's **Yes, that is right**, except on a question marked dangerous, whose yes stays red.
- **web console**: **Skip this one** (and **Do not skip**) on an optional question is a small button in your highlight colour, like a comment box's **No changes**, instead of an underlined link.
- **web console**: the review sign-off card lists **Approve this phase** before **Show me it working**, with the approve button outlined in the accent color.
- **web console**: a sign-off's **yes** button (Quick Task's **Build it**, Finalize's **Archive it**) is outlined in your highlight color too, like **Approve**. So is the yes of a yes/no question (such as Plan's **Write the plan**) and a recap's **Yes, that is right**, except on a question marked dangerous, whose yes stays red.
- **web console**: **Skip this one** (and **Do not skip**) on an optional question is a small button in your highlight color, like a comment box's **No changes**, instead of an underlined link.
- **init**, **init-update**: the *Keeping this file current* section they write into `AGENTS.md` gains three rules: a rule broken twice becomes an automated check, a new Failure log line first looks for one on the same topic to sharpen instead, and the log holds 17 entries at most (over the cap, merge entries that share a cause, then drop the lowest-value ones). Init update offers the missing rules to an existing section and tidies the log on every run, showing each merge and removal for a yes before it writes.
- **contributors**: this repo's `AGENTS.md` follows the same Failure log rules, and its three post-sync grep entries are merged into one.
- **contributors**: the web console's source is split by job: `lib.mjs`, `server.mjs`, `console.mjs`, `app.js` and `app.css` become `routes.mjs`, `static.mjs`, `cmd-*.mjs`, the by-job Node files, `public/screens/` and `public/styles/`. Nothing a person sees changes, and the page starts faster (ready in about 280 ms, was 450 ms).
@@ -132,7 +139,7 @@ All notable changes to Plan2Code will be documented in this file.
### 🗑️ Removed
- **handoff**: the Handoff skill's `handoff-path.mjs` script is retired in favour of `console.mjs handoff new`, which every skill can reach.
- **handoff**: the Handoff skill's `handoff-path.mjs` script is retired in favor of `console.mjs handoff new`, which every skill can reach.
### 🐛 Fixed
@@ -157,9 +164,9 @@ All notable changes to Plan2Code will be documented in this file.
- **git**: the web console's git board is now three tabs, **Changes**, **Branches** and **Sync**, and opens on the tab holding the likely next step. Ten fixed rules pick that step from the repository's state (fix or continue a stopped rebase or merge, make the first commit, make a branch on a detached HEAD, commit or start a branch for your changes, pull, push, publish, open a pull request, clean up branches) and show it as one main button with at most one quieter one beside it. Each tab badges what is waiting on it, and the other tabs say "Next step is on ‹tab›" with a link to it. Your own click moves you to the next step's tab once it lands; a refresh or a commit from the terminal leaves you where you are, and a reload keeps your tab.
- **git**: held-back files (secrets, files over 5 MB) no longer keep Commit as the next step forever. They get a quiet "held back" line and an **Add … to .gitignore** offer, which commits only `.gitignore`.
- **git**: a busy board is read-only. While a git command runs or the agent has not picked up your last click, every button, tick and picker greys out (switching tabs, search and folds still work), and what is running shows where the next step usually sits. Plan2Code's questions now appear under the tab strip.
- **git**: a busy board is read-only. While a git command runs or the agent has not picked up your last click, every button, tick and picker grays out (switching tabs, search and folds still work), and what is running shows where the next step usually sits. Plan2Code's questions now appear under the tab strip.
- **git**: a rebase or merge stopped on conflicts shows one block on Sync with the files marked *markers left* or *resolved*, one main button and **Abort** once; Changes and Branches wait until it is finished or aborted.
- **git**: **Done with git** is a normal button at the right of the tab strip. It greys while a git command runs (Stop session in the top bar still works), and while one of Plan2Code's questions waits it cancels that question and finishes.
- **git**: **Done with git** is a normal button at the right of the tab strip. It grays while a git command runs (Stop session in the top bar still works), and while one of Plan2Code's questions waits it cancels that question and finishes.
- **web-console**: Help → *The git board* is rewritten for the tabs, badges, the next step, the busy rules and Done with git. Handoff is described as packing the current session, not this conversation.
- **docs**: the docs site's "Any time" skills now list **Changelog** and **Git** beside Quick task, Review and Handoff.
- **tests**: `scripts/test-web-console-git-board.mjs` checks every sample repository state's next step, tab and badges, proves no control on a busy board is clickable, and that every board function is reachable on some tab.
@@ -168,7 +175,7 @@ All notable changes to Plan2Code will be documented in this file.
### 🐛 Fixed
- **implement**: Implement no longer says there is nothing left to do while the dashboard keeps Finalize greyed out. When every phase is approved but tasks under them are still open (usually manual steps an agent could not do, left blocked `[!]` with a "User action"), `specs.mjs status` now returns a `checkoff` verdict listing them, and Implement asks about each one in turn: "Is this done?" in the terminal, or a **Done, check it off** / **Not yet** card in the web console. A yes runs the new `specs.mjs tick <spec> --task <id>`, which marks the task `[x]` and adds a "Confirmed done by the user on <date>" line under it. Once nothing is left open, Implement points to `/plan2code-4-finalize` and the dashboard shows the spec as ready to finalize.
- **implement**: Implement no longer says there is nothing left to do while the dashboard keeps Finalize grayed out. When every phase is approved but tasks under them are still open (usually manual steps an agent could not do, left blocked `[!]` with a "User action"), `specs.mjs status` now returns a `checkoff` verdict listing them, and Implement asks about each one in turn: "Is this done?" in the terminal, or a **Done, check it off** / **Not yet** card in the web console. A yes runs the new `specs.mjs tick <spec> --task <id>`, which marks the task `[x]` and adds a "Confirmed done by the user on <date>" line under it. Once nothing is left open, Implement points to `/plan2code-4-finalize` and the dashboard shows the spec as ready to finalize.
## v2.7.0
@@ -213,7 +220,7 @@ All notable changes to Plan2Code will be documented in this file.
- **web-console**: the dashboard's spec card counts only a phase file's `**Task N.M:**` lines, so an Acceptance Criteria checkbox no longer shows as a task or keeps a built spec from reading "built". `post` and `status` stop reporting `phase: "submitted"` once a send has been collected. Several "New conversation" lines arriving together reach the agent as one. A posted finish (a pause included) no longer leaves the agent shown as working, and resuming a paused session starts a fresh working turn.
- **web-console**: **Commit it now** on a finished screen (and Changelog's "Commit this now?") no longer leaves the page stuck on the previous skill's ending. Resuming into Git now clears the previous skill's page, its ending included, as a dashboard launch does.
- **web-console**: the top bar's three right-side buttons (Help, Colors & theme, feedback) keep to the right edge when the progress bar is hidden; on the dashboard and the git board they used to sit beside the title.
- **web-console**: the git board's action bar (Refresh, Pull/Push, Commit, **Done**) stays pinned to the bottom of the pane while the branch table scrolls, and **Done** shows in the highlight colour when it is live.
- **web-console**: the git board's action bar (Refresh, Pull/Push, Commit, **Done**) stays pinned to the bottom of the pane while the branch table scrolls, and **Done** shows in the highlight color when it is live.
- **web-console**: a finished screen's buttons (**Review it now**, **Commit it now**, **Back to the dashboard**) stay live for as long as the session is open; the copy-the-command fallback only appears once the session has closed.
## v2.6.0
@@ -223,7 +230,7 @@ All notable changes to Plan2Code will be documented in this file.
- **web-console**: the breakdown question's "Anything else about this breakdown?" field has a **No changes** button. One click fills the box with "no changes", so you no longer type it. The old "(type 'no changes' if none)" hint is gone from the label.
- **git-commit**: a new `/plan2code-git-commit` skill and dashboard card. It reads what changed, drafts the commit message for your approval, offers a new branch first on the default branch, suggests splitting work that is really two jobs, and asks before every commit and push (never a force-push). Outside a git repository it offers to start one.
- **changelog**: a new `/plan2code-changelog` skill and dashboard card, just left of Git commit. It reads the default branch's latest version, classifies the branch's work and picks the version. When the branch already owns a version that is not released and not on another branch, it adds to that entry instead of starting a new one. It compares the branch with the newest entry, suggests the entries that are missing for you to edit, keeps `package.json` aligned, and offers to run Git commit next. The facts come from `changelog-state.mjs`, with tests in `scripts/test-script-changelog.mjs`.
- **web-console**: the Git commit card counts the files waiting ("3 files to commit") and greys out on a clean tree, from a bounded `git status` the scan runs when the dashboard opens. If git cannot answer, the card stays clickable.
- **web-console**: the Git commit card counts the files waiting ("3 files to commit") and grays out on a clean tree, from a bounded `git status` the scan runs when the dashboard opens. If git cannot answer, the card stays clickable.
- **web-console**: the Commit this? question in Git commit has a collapsed **Show the N files** table of every path and its state, so "15 files" can be read before you say yes.
- **web-console**: a finished quick task or phase build gets a **Commit it now** button beside the printed git command. It starts Git commit in the same session, as if you had clicked its dashboard card.
- **web-console**: the dashboard scan reports `isGit`, found from the filesystem without spawning git (linked worktrees count). The Git commit card stays clickable outside a repository and says "Not a git repository yet: it offers to start one". The skill has its own Planny pose and a Help entry.
@@ -245,7 +252,7 @@ All notable changes to Plan2Code will be documented in this file.
### ✨ Added
- **web-console**: six new starter templates, each slotted into every role's order. **Refactor** (Plan, Quick Task) asks what behaviour must not change. **Performance problem** (Plan, Quick Task) asks for today's number and the target. **Dependency upgrade** (Quick Task) asks for the known breaking changes. **Spike** (Pathfinder) is a time-boxed question with an "answered when". **Integration** (Pathfinder, Plan) covers the other side's auth and limits and what happens when it fails. **Data migration** (Plan) asks for a rollback plan. Pathfinder now offers 8 templates, Plan 10 and Quick Task 10, 19 in all.
- **web-console**: six new starter templates, each slotted into every role's order. **Refactor** (Plan, Quick Task) asks what behavior must not change. **Performance problem** (Plan, Quick Task) asks for today's number and the target. **Dependency upgrade** (Quick Task) asks for the known breaking changes. **Spike** (Pathfinder) is a time-boxed question with an "answered when". **Integration** (Pathfinder, Plan) covers the other side's auth and limits and what happens when it fails. **Data migration** (Plan) asks for a rollback plan. Pathfinder now offers 8 templates, Plan 10 and Quick Task 10, 19 in all.
### 🔧 Changed
@@ -337,7 +344,7 @@ All notable changes to Plan2Code will be documented in this file.
- **review**: with no `main` or `master` and no `--base`, `review-scope.mjs` now stops with `no-base` instead of quietly counting only uncommitted changes.
- **commit-msg.mjs**: the add step is `git add -- <paths>`, paths starting with `@` or `-` are quoted, and subjects with `\`, `!` or curly quotes are refused. The output also carries `add` and `commit` separately for Windows PowerShell 5.1, which has no `&&`.
- **specs.mjs**: `mark` reads a Status line written as `Status:` or `**Status**:` too, and warns when a phase file has none; a path that is not a folder directly under `specs/` is refused (`not-a-spec`).
- **pathfinder**: the map header carries `**Next NN:**`, so a deleted question's number is never handed out again. `claim`, `resolve` and `rule-out` honour `--dry-run`. Notes indented under a map row survive a marker change. Research questions are fired unclaimed; the one-claim rule is for the questions a person works through.
- **pathfinder**: the map header carries `**Next NN:**`, so a deleted question's number is never handed out again. `claim`, `resolve` and `rule-out` honor `--dry-run`. Notes indented under a map row survive a marker change. Research questions are fired unclaimed; the one-claim rule is for the questions a person works through.
- **finalize**: `feedback-payload.mjs` counts the same phase files `specs.mjs` does, `submit` refuses an oversize URL when `gh` is unavailable (`oversize`), and a bare spec name present in both `specs/` and `specs--completed/` is refused as ambiguous.
- Every script was checked against real specs and Pathfinder maps in other repositories and by four independent reviews; each issue found has a regression test.
@@ -347,7 +354,7 @@ All notable changes to Plan2Code will be documented in this file.
- **web-console**: when the agent stops checking in, the status line and Help now say to type **continue** in an idle terminal so it picks your answers up.
- **web-console**: `wait` exit 10 now carries a `next` instruction (relay one line, then wait again), and `console.md` opens with the one rule that keeps the page alive: every turn ends on a `wait` call, never on text.
- **web-console**: a finished quick task offers **Back to the dashboard** as well as **Review it now**, so the finished screen is never a dead end.
- **Windows**: the folder picker (the launcher's desktop shortcut and the Workspace **Browse…** button) now opens centred and in front of other windows instead of behind the terminal.
- **Windows**: the folder picker (the launcher's desktop shortcut and the Workspace **Browse…** button) now opens centered and in front of other windows instead of behind the terminal.
- **Launcher**: before asking which CLI to use, `plan2code` says what it is about to do and that running `/plan2code` inside your agent works too.
- **web-console**: the session meter now weighs the work a session actually did instead of a flat amount per step. A built phase scores one point per 3 tasks it completed (rounded up), plus 1 for Implement + Review, so a twelve-task phase weighs four times a three-task one; the agent reports the count as `run.tasks`. Every 2 questions you answer on the page add a point to the skill you answered them in, so a long back-and-forth in Plan or Pathfinder counts for more than a short one. Each Pathfinder research question adds 1 through a new `pathfinder-research` event, since research fills the context with nobody answering anything. The levels move to match: yellow from 5 points, red from 10, and the ring is full at 15.
@@ -373,7 +380,7 @@ All notable changes to Plan2Code will be documented in this file.
- **`plan2code-3-implement-review`**: a quality-gated Step 3 that implements one phase, runs a focused review and the selected fixes before sign-off, and marks the phase complete only after the reviewed result is approved. Step 2's hand-off now offers it first, with `/plan2code-3-implement` as the review-free alternative.
- **`--web` flag**: `/plan2code-1-plan --web plan a lunch voting app` opens the console without asking. Every next-step command the workflow prints (resume footers, NEXT STEP lines, the loop's completion banner) now carries `--web`.
- **Console pages for builds and reviews**: a build shows the current task, a task-count progress bar and the phase's task list ticking as tasks land. After an approved phase or a finished quick task, **Review it now** runs `/plan2code-review` on the page, with *Which to fix* presets for critical-and-warnings or everything.
- **Console conveniences**: nine question shapes with live validation and drag-to-reorder phases; drafts that survive a closed tab, reload, server restart or agent crash; an **Ask** tab for quick questions the agent answers at its next check-in (file edits need approval); image and document attachments; a read-only **Overview** tab; a **Workspace** of extra read-only folders addressed as `@name`; a green / yellow / red **session meter**; a **Role** preference that orders starter templates; nineteen highlight colours, light / dark themes and card widths; audio cues with per-event toggles; and a 16-topic Help dialog.
- **Console conveniences**: nine question shapes with live validation and drag-to-reorder phases; drafts that survive a closed tab, reload, server restart or agent crash; an **Ask** tab for quick questions the agent answers at its next check-in (file edits need approval); image and document attachments; a read-only **Overview** tab; a **Workspace** of extra read-only folders addressed as `@name`; a green / yellow / red **session meter**; a **Role** preference that orders starter templates; nineteen highlight colors, light / dark themes and card widths; audio cues with per-event toggles; and a 16-topic Help dialog.
- **Planny in the console**: drawn in SVG in his own dock above the question list, where he carries the page's state: his star lights and he waves when it is your turn, the star turns and he walks on the spot while the agent works, it goes green when all is caught up, he shows no arms when the agent is not answering, and he fades with his star shut when disconnected. He flies through a starfield while the agent thinks, wakes up on a fresh dashboard, and acts out each skill on its starting screen, arms holding that step's prop. The tab icon adds a busy, ready or attention bar, and the desktop shortcut uses him too.
- **Tests**: `scripts/test-web-console.mjs` and `scripts/test-launcher.mjs` (run by `node --test`), `scripts/parse-check.mjs` (every shipped browser module parses as an ES module) and `scripts/check-skill-table.mjs` (the dashboard's "What each skill reads and writes" table matches the skills), all wired into `npm test`. `scripts/bench-web-console.mjs` measures time to first paint.
- **install.js**: an animated progress indicator during the two long install phases, so the installer no longer looks hung.
@@ -463,7 +470,7 @@ All notable changes to Plan2Code will be documented in this file.
### 🔧 Changed
- **`src/plan2code-0-pathfinder.md` recompressed** to absorb the new `## Backend` section within the 11,000-character workflow-file limit — duplication between the orchestrator and its reference files was removed (the local layout and marker legend now live only in `questions.md`; Form A/B footer detail only in `trail.md`), and step text tightened. No behaviour was dropped.
- **`src/plan2code-0-pathfinder.md` recompressed** to absorb the new `## Backend` section within the 11,000-character workflow-file limit — duplication between the orchestrator and its reference files was removed (the local layout and marker legend now live only in `questions.md`; Form A/B footer detail only in `trail.md`), and step text tightened. No behavior was dropped.
## v2.0.0
@@ -473,7 +480,7 @@ Ports upstream v1.17.0 and v2.0.0 into Plan2Code.
- **Gemini CLI is no longer an install target.** The `.gemini/commands/*.toml` surface is removed, along with the build-time machinery it required: `generateTomlContent()`, `writeTomlToDestination()`, `inlineReferenceContent()`, and the `dest.type === 'toml'` branch in `syncPrompts()`. Every remaining target resolves `Read references/*.md` directives at runtime, so reference content no longer needs inlining at build time.
**Uninstall still cleans up Gemini files.** The `.gemini/commands` entry is deliberately retained in the uninstall target list (labelled `Gemini CLI (legacy — uninstall only)`) behind a new `uninstallOnly` flag, so `.toml` files written by v1.x installs can still be removed. Do not add it back to `LOCAL_DESTINATIONS` / `GLOBAL_DESTINATIONS`.
**Uninstall still cleans up Gemini files.** The `.gemini/commands` entry is deliberately retained in the uninstall target list (labeled `Gemini CLI (legacy — uninstall only)`) behind a new `uninstallOnly` flag, so `.toml` files written by v1.x installs can still be removed. Do not add it back to `LOCAL_DESTINATIONS` / `GLOBAL_DESTINATIONS`.
All other platforms are unaffected — Claude Code (skills *and* commands), Cursor, Windsurf, Continue, Codeium, GitHub Copilot, VS Code Copilot, Pi, Crush, Amp, Devin, OpenCode, and Zed all install exactly as before.
@@ -503,7 +510,7 @@ Ports upstream v1.17.0 and v2.0.0 into Plan2Code.
- **Docs site and README redesigned** around an "airmail" postcard theme — a fixed four-sided airmail-chevron page frame, sticky header, and the workflow presented as six posted letters, with Pathfinder and the optional Review step both surfaced. Adds a postage-stamp favicon set (`favicon.svg` / `.ico` / `.png` / `apple-touch-icon.png`) and a new README banner; removes three orphaned images (`desk.jpg`, `install-script.jpg`, `plan2code.jpg`).
- **`/plan2code-4-finalize` archives `pathfinder/` with the spec** — STEP 6 now names `pathfinder/` in the move list and no longer describes the cleanup target as "research or scratch files," wording that pointed an agent straight at `pathfinder/questions/`. The map is the rationale record behind the plan, in the same class as `PLAN-CONVERSATION-*.md`.
- **`/plan2code-1b-revise-plan` no longer deletes `pathfinder/`** — its Step 6 cleanup had the same "research or scratch files" wording.
- **`/plan2code-quick-task` is no longer labelled "Step 0"** — pathfinder now owns step 0, and quick-task was never a pipeline step. It registers as a utility (like `init`, `review`, and `handoff`), so its generated description reads `Plan2Code Quick Task: Quick Task Mode`. Filename, skill name, and command path are unchanged.
- **`/plan2code-quick-task` is no longer labeled "Step 0"** — pathfinder now owns step 0, and quick-task was never a pipeline step. It registers as a utility (like `init`, `review`, and `handoff`), so its generated description reads `Plan2Code Quick Task: Quick Task Mode`. Filename, skill name, and command path are unchanged.
- **`/plan2code-handoff` asks where to save** — the OS temp directory is now the default, with `./handoffs/` or any other path available on request. Adds a spec-awareness section: when the session worked inside `specs/<feature>/`, the handoff cites the in-progress `phase-X.md` and its actual checkbox state rather than relying on conversation memory.
- **`/plan2code-init-update` Step 7 offloaded to a reference file** — the AI Agent File Sync detail moves to `plan2code-init-update-references/ai-agent-file-sync.md` with an inline fallback. The `CLAUDE.md` MANDATORY-FIRST-STEP template is unchanged.
- **`/plan2code-review` Session End offloaded to a reference file** — next-step routing moves to `plan2code-review-references/session-end.md` with an inline fallback.
+2 -2
View File
@@ -1235,7 +1235,7 @@ function runInteractive() {
const exitCode = uninstallResult !== 0 ? uninstallResult : loopResult !== 0 ? loopResult : metricsResult !== 0 ? metricsResult : botResult !== 0 ? botResult : statusLineResult !== 0 ? statusLineResult : launcherResult;
process.exit(exitCode);
} else {
console.log(`\n${COLORS.YELLOW}${SYMBOLS.WARNING} CANCELLED${COLORS.RESET}\n`);
console.log(`\n${COLORS.YELLOW}${SYMBOLS.WARNING} CANCELED${COLORS.RESET}\n`);
rl.close();
process.exit(0);
}
@@ -1322,7 +1322,7 @@ function runInteractive() {
// Q — exit
if (input === 'Q') {
console.log(`\n${COLORS.YELLOW}${SYMBOLS.WARNING} CANCELLED${COLORS.RESET}\n`);
console.log(`\n${COLORS.YELLOW}${SYMBOLS.WARNING} CANCELED${COLORS.RESET}\n`);
rl.close();
process.exit(0);
}
+1 -1
View File
@@ -8,7 +8,7 @@
"scripts": {
"prepare": "husky",
"build:skills": "node install.js --build-skills",
"test": "node scripts/validate-char-count.js && node install.js --build-skills && node scripts/parse-check.mjs && node scripts/check-skill-table.mjs && node --test --test-concurrency=8 scripts/test-script-git.mjs scripts/test-git-repo.mjs scripts/test-skill-scripts.mjs scripts/test-script-changelog.mjs scripts/test-web-console-git.mjs scripts/test-web-console-git-board.mjs scripts/test-web-console-chat.mjs scripts/test-web-console-subagents.mjs scripts/test-web-console-speed.mjs scripts/test-web-console-qa.mjs scripts/test-web-console-concurrency.mjs scripts/test-web-console-workspace.mjs scripts/test-web-console-lifecycle.mjs scripts/test-web-console-chat-stress.mjs scripts/test-web-console-server.mjs scripts/test-web-console-session.mjs scripts/test-web-console-logic.mjs scripts/test-web-console-skills.mjs scripts/test-web-console-spec-states.mjs scripts/test-web-console-state.mjs scripts/test-web-console-shape.mjs scripts/test-script-pathfinder.mjs scripts/test-launcher.mjs scripts/test-agents-file.mjs scripts/test-web-console-source.mjs scripts/test-web-console-hardening.mjs scripts/test-web-console-embed.mjs scripts/test-web-console-in-app.mjs scripts/test-web-console-handoffs.mjs scripts/test-web-console-notepad.mjs scripts/test-script-xray.mjs scripts/test-script-finalize.mjs scripts/test-getting-started.mjs scripts/test-install-update.mjs scripts/test-browser-helper.mjs scripts/test-web-console-page-cards.mjs scripts/test-web-console-page-dashboard.mjs scripts/test-web-console-page-session.mjs scripts/test-web-console-page-ask.mjs scripts/test-web-console-page-workspace.mjs scripts/test-web-console-page-help.mjs scripts/test-web-console-page-prefs.mjs scripts/test-web-console-page-git.mjs scripts/test-web-console-page-notepad.mjs scripts/test-standalone-check.mjs scripts/test-check-versions.mjs scripts/test-app-meter.mjs"
"test": "node scripts/validate-char-count.js && node install.js --build-skills && node scripts/parse-check.mjs && node scripts/check-skill-table.mjs && node --test --test-concurrency=8 scripts/test-us-english.mjs scripts/test-script-git.mjs scripts/test-git-repo.mjs scripts/test-skill-scripts.mjs scripts/test-script-changelog.mjs scripts/test-web-console-git.mjs scripts/test-web-console-git-board.mjs scripts/test-web-console-chat.mjs scripts/test-web-console-subagents.mjs scripts/test-web-console-speed.mjs scripts/test-web-console-qa.mjs scripts/test-web-console-concurrency.mjs scripts/test-web-console-workspace.mjs scripts/test-web-console-lifecycle.mjs scripts/test-web-console-chat-stress.mjs scripts/test-web-console-server.mjs scripts/test-web-console-session.mjs scripts/test-web-console-logic.mjs scripts/test-web-console-skills.mjs scripts/test-web-console-spec-states.mjs scripts/test-web-console-state.mjs scripts/test-web-console-shape.mjs scripts/test-script-pathfinder.mjs scripts/test-launcher.mjs scripts/test-agents-file.mjs scripts/test-web-console-source.mjs scripts/test-web-console-hardening.mjs scripts/test-web-console-embed.mjs scripts/test-web-console-in-app.mjs scripts/test-web-console-handoffs.mjs scripts/test-web-console-notepad.mjs scripts/test-script-xray.mjs scripts/test-script-finalize.mjs scripts/test-getting-started.mjs scripts/test-install-update.mjs scripts/test-browser-helper.mjs scripts/test-web-console-page-cards.mjs scripts/test-web-console-page-dashboard.mjs scripts/test-web-console-page-session.mjs scripts/test-web-console-page-ask.mjs scripts/test-web-console-page-workspace.mjs scripts/test-web-console-page-help.mjs scripts/test-web-console-page-prefs.mjs scripts/test-web-console-page-git.mjs scripts/test-web-console-page-notepad.mjs scripts/test-standalone-check.mjs scripts/test-check-versions.mjs scripts/test-app-meter.mjs"
},
"devDependencies": {
"husky": "^9.0.0",
+1 -1
View File
@@ -75,7 +75,7 @@ impl PtyHost {
let mut command = CommandBuilder::new(&options.program);
command.args(&options.args);
// What the agent CLIs expect from a terminal that can show colour.
// What the agent CLIs expect from a terminal that can show color.
command.env("TERM", "xterm-256color");
command.env("COLORTERM", "truecolor");
for (key, value) in &options.env {
+3 -3
View File
@@ -106,7 +106,7 @@ export class Controller {
clearInterval(elapsedInterval);
spinner.stop();
// Cancelled or interrupted — return immediately, don't retry
// Canceled or interrupted — return immediately, don't retry
if (result.cancelled || this.interrupted) {
return result;
}
@@ -268,9 +268,9 @@ export class Controller {
const result = retryResult;
// Check if cancelled
// Check if canceled
if (result.cancelled || this.interrupted) {
logger.info('Agent process cancelled');
logger.info('Agent process canceled');
const entry: IterationLogEntry = {
iteration: iterNum,
+1 -1
View File
@@ -43,7 +43,7 @@ const CWD = path.resolve(args.cwd || ROOT);
const HOME = fs.mkdtempSync(path.join(os.tmpdir(), "p2c-bench-"));
const ENV = { ...process.env, PLAN2CODE_CONSOLE_HOME: HOME, PLAN2CODE_NO_BROWSER: "1" };
// A fresh cached failure: the boot-time release check stays off the network,
// so a slow GitHub never colours the timings.
// so a slow GitHub never colors the timings.
fs.writeFileSync(path.join(HOME, "update-check.json"), JSON.stringify({ checkedAt: Date.now(), latest: null }));
// Resolves at the first stdout line carrying a url, and again at exit.
+1 -1
View File
@@ -23,7 +23,7 @@ test("playwright-core is pinned exactly in the root devDependencies", () => {
// A fake file system holding only `present`.
const only = (...present) => (p) => present.includes(p);
test("findBrowser picks Chrome, then Edge, and honours PLAN2CODE_TEST_BROWSER", async () => {
test("findBrowser picks Chrome, then Edge, and honors PLAN2CODE_TEST_BROWSER", async () => {
const { findBrowser, BROWSER_PATHS } = await import("./browser.mjs");
const chrome = BROWSER_PATHS.chrome[0];
const edge = BROWSER_PATHS.msedge[0];
+1 -1
View File
@@ -378,7 +378,7 @@ test("pathfinder brief-data: calendar dates only, no future since, no NNs or lin
/* ===================================================== review-fix regressions */
test("pathfinder: claim, resolve and rule-out honour --dry-run", () => {
test("pathfinder: claim, resolve and rule-out honor --dry-run", () => {
const { root, pf } = mapFixture();
const P = (...a) => runScript("plan2code-0-pathfinder", "pathfinder.mjs", [...a, "--root", root]);
P("reconcile", "audit-export");
+1 -1
View File
@@ -158,7 +158,7 @@ test("specs status: checklist formats, groups, task markers, numbering, totals,
[3, "Web UI", "pending"],
[4, "Docs", "pending"],
]);
assert.deepEqual(j.parallelGroups.map((g) => [g.id, g.phases]), [["A", [3, 4]]], "a group labelled sequential is not a parallel group");
assert.deepEqual(j.parallelGroups.map((g) => [g.id, g.phases]), [["A", [3, 4]]], "a group labeled sequential is not a parallel group");
assert.deepEqual(j.totals, { total: 11, complete: 4, assumed: 1, pending: 5, "in-progress": 0, blocked: 1, unknown: 0, completed: 5, incomplete: 5 });
assert.equal(j.completionPercent, 45);
assert.equal(j.phases[0].tasks.total, 3, "a named testing task (1.T) counts");
+70
View File
@@ -0,0 +1,70 @@
// The project writes US English: docs, comments, prompts, UI text, test names.
// A rule in prose was missed once ("colours" slipped into a reply and ~100
// files carried UK spellings), so this keeps it.
// Run with: node --test scripts/test-us-english.mjs
import test from "node:test";
import assert from "node:assert/strict";
import fs from "node:fs";
import path from "node:path";
import { spawnSync } from "node:child_process";
import { fileURLToPath } from "node:url";
const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
const SELF = "scripts/test-us-english.mjs";
// Tracked text files. Vendored code stays as shipped, and binaries have no words.
const SKIP = /(^|\/)(node_modules|dist|target|vendor)\/|package-lock\.json$|\.(png|jpe?g|gif|ico|icns|mp3|wav|woff2?|ttf|lock)$/i;
// UK spellings with a clear US form. Whole words, any case.
const UK = new RegExp(
"\\b(" +
[
"colour\\w*", "grey\\w*", "behaviour\\w*", "centre[sd]?", "centred", "cancell(?:ed|ing)", "labell(?:ed|ing)",
"relabell\\w*", "travell(?:ed|ing|er)", "judgement", "neighbour\\w*", "honour\\w*", "favour\\w*", "licence",
"defence", "offence", "whilst", "amongst", "artefacts?", "catalogue[sd]?",
"analys(?:e|ed|ing)", "(?:organ|recogn|normal|summar|sanit|optim|final|initial|serial|custom|priorit|minim|maxim|util|canonical|material|stabil|anonym|synchron|standard|categor|author|visual|emphas|apolog|special|character|central|random|token|local|capital|critic|memor|synthes|real)is(?:e|es|ed|ing|ation|ations|er|ers|able)",
].join("|") +
")\\b",
"gi"
);
// Names that keep the UK spelling because they are data contracts read in
// several places (see Code Style in .agents-docs/AGENTS-code-style.md), plus
// HTML's own attribute. Removed before the scan.
const CONTRACTS = [
/aria-labelledby/g,
/\.greyed\b/g,
/\bgreyed(?=\s*:)/g,
/\bconst greyed\b/g,
/\bgreyed(?=, card)/g,
/^\/\/\s+greyed\b/gm,
/\bcancelled(?=\s*:)/g,
/\.cancelled\b/g,
/"cancelled"/g,
/\bconst cancelled\b/g,
/\bcancelled(?=\.[a-z])/g,
];
function trackedTextFiles() {
const r = spawnSync("git", ["ls-files"], { cwd: ROOT, encoding: "utf8" });
assert.equal(r.status, 0, r.stderr);
return r.stdout.split("\n").filter((f) => f && f !== SELF && !SKIP.test(f));
}
test("tracked text is written in US English", () => {
const found = [];
for (const rel of trackedTextFiles()) {
let text;
try {
text = fs.readFileSync(path.join(ROOT, rel), "utf8");
} catch {
continue; // listed but deleted in the working tree
}
for (const re of CONTRACTS) text = text.replace(re, "");
text.split("\n").forEach((line, i) => {
for (const m of line.matchAll(UK)) found.push(`${rel}:${i + 1}: ${m[0]}`);
});
}
assert.deepEqual(found, [], `UK spellings (use the US form, e.g. color, gray, behavior, canceled, -ize):\n${found.join("\n")}`);
});
+1 -1
View File
@@ -247,7 +247,7 @@ test("nextAbout: pick sets about, drop and sent clear it, the old Ask events do
assert.equal(JSON.stringify(picked), before, "prev is never mutated");
});
test("nextAbout: an old { about, frozen, dropped } tracker normalises to the new shape", () => {
test("nextAbout: an old { about, frozen, dropped } tracker normalizes to the new shape", () => {
const old = { about: CARD_Q1, frozen: true, dropped: false };
assert.deepEqual(nextAbout(old, { type: "leave-ask" }), { history: [], about: CARD_Q1 });
assert.deepEqual(nextAbout({ frozen: false, dropped: true }, {}), { history: [], about: null });
+1 -1
View File
@@ -190,7 +190,7 @@ test("two sessions keep their own cookies: each server reads only the one named
// state.json has two writers, `post` and the server's /submit. Both are held
// at the lock here until each has read nothing yet, then let go together:
// whichever writes second must be building on the first one's write.
test("a post and a submit that overlap both survive: the state lock serialises them", async () => {
test("a post and a submit that overlap both survive: the state lock serializes them", async () => {
const s = openSession();
try {
const lock = path.join(s.session, STATE_LOCK_FILE);
+2 -2
View File
@@ -368,7 +368,7 @@ test("git board view: no control leaks the busy lock, in any state, mode, tab or
assert.ok(["nav", "action", "done"].includes(gate), `${where}: "${words(c)}" (${c.tag}) has no data-gate`);
const own = c.attrs["data-own"] === "true";
if (!controlAllowed(mode, gate)) assert.ok(isOff(c), `${where}: "${words(c)}" is live while busy`);
else assert.equal(isOff(c), own, `${where}: "${words(c)}" is ${isOff(c) ? "greyed with no reason of its own" : "live despite its own reason"}`);
else assert.equal(isOff(c), own, `${where}: "${words(c)}" is ${isOff(c) ? "grayed with no reason of its own" : "live despite its own reason"}`);
checked++;
}
const done = all.filter((c) => c.textContent === "Done with git");
@@ -512,7 +512,7 @@ test("git board host: the host draws the board only through drawGitBoard, and th
// The commit table's ticks and the click that re-seeds them are page tests now
// ("the commit table keeps the person's ticks across an agent post, and a click
// re-seeds them" and its neighbours in test-web-console-page-git.mjs).
// re-seeds them" and its neighbors in test-web-console-page-git.mjs).
test("git board docs: the agent prose, Help topic and readme describe the tabbed board", () => {
const read = (p) => fs.readFileSync(new URL(p, import.meta.url), "utf8");
+1 -1
View File
@@ -281,7 +281,7 @@ test("git: commits on a run go only with git-commits, as a whole number", () =>
}
});
test("git: the Git card is never greyed, and its resume command is /plan2code-git", () => {
test("git: the Git card is never grayed, and its resume command is /plan2code-git", () => {
const entry = SKILL_CATALOG.find((e) => e.skill === "plan2code-git");
assert.equal(entry.workflow, "git");
assert.deepEqual(cardAvailability(entry, { hasAgents: true, isGit: false }, null), { on: true, note: GIT_INIT_NOTE });
+1 -1
View File
@@ -24,7 +24,7 @@ test("another console's cookie beside ours does not lock this one out", async ()
const theirsOnly = await fetch(s.base + "/state", { headers: { cookie: other } });
assert.equal(theirsOnly.status, 403);
await theirsOnly.arrayBuffer();
// The old shared name is no longer honoured.
// The old shared name is no longer honored.
const legacy = await fetch(s.base + "/state", { headers: { cookie: `p2c_console=${token}` } });
assert.equal(legacy.status, 403);
await legacy.arrayBuffer();
+1 -1
View File
@@ -310,7 +310,7 @@ test("reorderTabs needs exactly the current ids once each, and setLastTab rememb
refusal(() => readNotepad(folder, "../x"), "no-such-tab");
});
test("deleteTab: the folder goes, last moves to a neighbour, and the last tab left leaves an empty list", () => {
test("deleteTab: the folder goes, last moves to a neighbor, and the last tab left leaves an empty list", () => {
const folder = freshFolder();
const [a, b, c] = ["A", "B", "C"].map((n) => createTab(folder, n).id);
saveNote(folder, b, "bye");
+8 -8
View File
@@ -171,7 +171,7 @@ test("a sign-off card opens its document, and each verdict reaches the agent", a
await card.getByRole("button", { name: /Read .*Completion report.* in full/ }).click();
await s.page.getByText("Phase 3 adds the /tasks endpoints.").waitFor();
assert.ok(await s.page.getByText("Phase 3 adds the /tasks endpoints.").isVisible(), "the report is on screen");
// The danger verdict is marked as such: here the class is the behaviour.
// The danger verdict is marked as such: here the class is the behavior.
await s.page.locator("#views").getByRole("button", { name: /^Questions/ }).click();
card = itemCard(s.page, "so1");
assert.match(await card.getByRole("button", { name: "Throw it away" }).getAttribute("class"), /danger/);
@@ -338,16 +338,16 @@ test("a redraw keeps the place of the dashboard, the waiting screen and the fini
assert.equal(await itemCard(s.page, "q2").evaluate((el) => el.scrollTop), 0, "the new question opened part-way down");
});
// The accent colour as the browser resolves it, and a button's outline colour,
// The accent color as the browser resolves it, and a button's outline color,
// so "wears the accent" is read off the screen, not off a class name.
const accentOf = (page) =>
page.evaluate(() => {
const probe = document.createElement("i");
probe.style.color = "var(--accent)";
document.body.appendChild(probe);
const colour = getComputedStyle(probe).color;
const color = getComputedStyle(probe).color;
probe.remove();
return colour;
return color;
});
const outlineOf = (button) => button.evaluate((b) => getComputedStyle(b).borderTopColor);
const warnOf = (page) =>
@@ -355,9 +355,9 @@ const warnOf = (page) =>
const probe = document.createElement("i");
probe.style.color = "var(--warn)";
document.body.appendChild(probe);
const colour = getComputedStyle(probe).color;
const color = getComputedStyle(probe).color;
probe.remove();
return colour;
return color;
});
// What a person sees break: the way forward on a sign-off card looks like any
@@ -390,9 +390,9 @@ test("Skip this one and a comment box's quick answer are the same small accent b
const quick = card.getByRole("button", { name: "No changes" });
const look = (b) => b.evaluate((x) => { const c = getComputedStyle(x); return [c.fontSize, c.paddingTop, c.paddingLeft, c.color]; });
assert.deepEqual(await look(skip), await look(quick), "the two chips look alike");
const [size, , , colour] = await look(skip);
const [size, , , color] = await look(skip);
assert.equal(size, "12px", "small, not a full-size button");
assert.equal(colour, await accentOf(s.page), "in the accent");
assert.equal(color, await accentOf(s.page), "in the accent");
});
// What a person sees break: Combine phases is missing from a plan's breakdown,
+8 -8
View File
@@ -19,7 +19,7 @@ const suite = pageSuite(test);
// A project that is set up (AGENTS.md) with one spec holding a Plan draft.
// A PLAN-DRAFT whose Status line says only "Draft" (no "Resume at Phase N")
// scans as `planned`, which the picker labels "Ready to document". Plan is
// still lit for it (only exploring, fixed and documented-or-later grey Plan
// still lit for it (only exploring, fixed and documented-or-later gray Plan
// out); Document is the state's own next step.
const DRAFT_PROJECT = {
"AGENTS.md": "# AGENTS.md\n\nA small demo project.\n",
@@ -60,7 +60,7 @@ test("a Plan launch from the dashboard carries the picked spec, and its resume t
// The Plan card is lit for this spec; picking it asks to confirm.
const planCard = main.getByRole("button").filter({ has: s.page.locator("code", { hasText: /^\/plan2code-1-plan$/ }) });
assert.equal(await planCard.isEnabled(), true, "the Plan card is greyed for a drafted plan");
assert.equal(await planCard.isEnabled(), true, "the Plan card is grayed for a drafted plan");
await planCard.click();
await main.getByRole("button", { name: "Start Plan" }).click();
@@ -146,7 +146,7 @@ test("a fixed bug is hidden while unavailable workflows are, dimmed when they sh
assert.equal(await demo.getAttribute("aria-current"), "true", "the picker opens on the plan, not the newer fixed bug");
assert.equal(await chipFor(main, "old-bug").count(), 0, "the fixed bug's chip is hidden while unavailable workflows are");
// Switched off: the chip shows, labelled and dimmed, and still not picked.
// Switched off: the chip shows, labeled and dimmed, and still not picked.
await hideUnavailable(main, false);
const bug = chipFor(main, "old-bug");
await bug.waitFor();
@@ -180,7 +180,7 @@ test("a fixed bug's Delete asks once with no name to type, while any other spec
// The fixed bug: a visible Delete, its own warning, and one press sends it.
const del = main.getByRole("button", { name: "Delete the spec old-bug" });
assert.equal(await textOf(del), "Delete", "a fixed bug's Delete is a labelled button");
assert.equal(await textOf(del), "Delete", "a fixed bug's Delete is a labeled button");
await del.click({ force: true });
await dialog.waitFor();
assert.match(await textOf(s.page.locator("#delete-warn")), /The bug is fixed, so this only clears the write-up/);
@@ -203,17 +203,17 @@ const pickedChip = (main, name) => main.locator('button[aria-current="true"]', {
// What a person would see break: picking another target leaves the launch
// aimed at the old spec, or the cards lit for it.
test("picking Start from scratch instead of a spec greys Document, and a launch then carries no spec", async (t) => {
test("picking Start from scratch instead of a spec grays Document, and a launch then carries no spec", async (t) => {
const s = await openSession(await suite.browser(), { t, workflow: "dashboard", payload: MENU, project: tempProject(DRAFT_PROJECT) });
const main = await toTheMenu(s);
const document = lightOf(main, "/plan2code-2-document");
await pickedChip(main, "demo").waitFor();
assert.equal(await document.isEnabled(), true, "Document is lit for the drafted spec");
// From scratch there is no draft to document: the card greys.
// From scratch there is no draft to document: the card grays.
await chipFor(main, "Start from scratch").click();
await pickedChip(main, "Start from scratch").waitFor();
assert.equal(await document.isDisabled(), true, "Document is greyed with no spec picked");
assert.equal(await document.isDisabled(), true, "Document is grayed with no spec picked");
assert.equal(await chipFor(main, "demo").getAttribute("aria-current"), "false");
// Back on the spec it is lit again; then from scratch once more to launch.
@@ -270,7 +270,7 @@ async function openHandoffMenu(t, env) {
// project has, or picking it still shows the skill cards beside the preview.
test("a handoff shows as a dashed Handoff chip even with no spec, and picking it swaps the cards for a preview of four buttons", async (t) => {
const { main, chip } = await openHandoffMenu(t);
assert.match(await textOf(chip), /Handoff/i, "the chip is labelled Handoff");
assert.match(await textOf(chip), /Handoff/i, "the chip is labeled Handoff");
assert.equal(await chip.getAttribute("aria-current"), "false", "a handoff is offered, not picked for you");
assert.equal(await chip.evaluate((b) => getComputedStyle(b).borderTopStyle), "dashed", "the chip's border is dashed");
assert.ok(await lightOf(main, "/plan2code-1-plan").isVisible(), "the cards show before a handoff is picked");
+18 -18
View File
@@ -301,7 +301,7 @@ test("the editor follows the console's light and dark themes", async (t) => {
await openNotepad(s);
await setDoc(s, "# Heading\n\nText");
await s.page.locator("#notepad-editor .cm-h1").waitFor();
const colours = (theme) =>
const colors = (theme) =>
s.page.evaluate((th) => {
document.documentElement.setAttribute("data-theme", th);
const root = getComputedStyle(document.documentElement);
@@ -325,13 +325,13 @@ test("the editor follows the console's light and dark themes", async (t) => {
background: getComputedStyle(shadow.querySelector(".cm-editor")).backgroundColor,
};
}, theme);
const light = await colours("light");
const dark = await colours("dark");
const light = await colors("light");
const dark = await colors("dark");
for (const [name, c] of Object.entries({ light, dark })) {
assert.equal(c.text, c.ink, `${name}: text in the console's ink`);
assert.equal(c.heading, c.accent, `${name}: headings in the highlight colour`);
assert.equal(c.caret, c.accent, `${name}: the caret in the highlight colour`);
assert.equal(c.background, c.panel, `${name}: the editor on the panel colour`);
assert.equal(c.heading, c.accent, `${name}: headings in the highlight color`);
assert.equal(c.caret, c.accent, `${name}: the caret in the highlight color`);
assert.equal(c.background, c.panel, `${name}: the editor on the panel color`);
}
assert.notEqual(light.text, dark.text, "the two themes differ");
assert.notEqual(light.background, dark.background);
@@ -706,7 +706,7 @@ test("Delete asks twice, Escape backs out of either, and only the second confirm
await panel.waitFor({ state: "hidden" });
assert.equal(fs.existsSync(folder), true);
// Both confirms: gone, with its folder, and the neighbour is shown.
// Both confirms: gone, with its folder, and the neighbor is shown.
await s.page.click(X_SELECTED);
await s.page.click("#notepad-delete-go");
await s.page.click("#notepad-delete-go");
@@ -714,7 +714,7 @@ test("Delete asks twice, Escape backs out of either, and only the second confirm
await s.page.waitForFunction(() => document.querySelectorAll("#notepad-tabs .notepad-tab").length === 1);
assert.deepEqual(await selectedName(s), ["Notes"]);
assert.equal(await shows(s, "keep me"), "keep me");
assert.equal(listTabs(s.project).last, idOf(s, "Notes"), "the neighbour became the last tab");
assert.equal(listTabs(s.project).last, idOf(s, "Notes"), "the neighbor became the last tab");
// Delete the last tab: the empty state, with the focus on its button.
await s.page.click(X_SELECTED);
@@ -808,7 +808,7 @@ test("when the tab after a delete cannot be loaded, the deleted text is not left
await typeInto(s, "doomed text");
const ideas = idOf(s, "Ideas");
await until(() => readNotepad(s.project, ideas).text === "doomed text", 4000);
// The neighbour's read fails, as if the connection dropped right after the delete.
// The neighbor's read fails, as if the connection dropped right after the delete.
await s.page.route("**/notepad?tab=*", (route) => route.abort());
await s.page.click(X_SELECTED);
await s.page.click("#notepad-delete-go");
@@ -836,8 +836,8 @@ const readyCount = (s, n) =>
s.page.waitForFunction((want) => document.querySelectorAll("#notepad-strip > li.is-ready").length === want, n, { timeout: 5000 });
// A small PNG drawn in the page, as base64: a real picture for reencode() to
// decode, one colour per call so the pictures differ.
const pngBase64 = (s, colour) =>
// decode, one color per call so the pictures differ.
const pngBase64 = (s, color) =>
s.page.evaluate(async (fill) => {
const c = document.createElement("canvas");
c.width = 320;
@@ -849,13 +849,13 @@ const pngBase64 = (s, colour) =>
let bin = "";
for (const b of new Uint8Array(await blob.arrayBuffer())) bin += String.fromCharCode(b);
return btoa(bin);
}, colour);
}, color);
const pngFile = async (s, colour, name = "shot.png") => ({ name, mimeType: "image/png", buffer: Buffer.from(await pngBase64(s, colour), "base64") });
const pngFile = async (s, color, name = "shot.png") => ({ name, mimeType: "image/png", buffer: Buffer.from(await pngBase64(s, color), "base64") });
async function addViaButton(s, colour) {
async function addViaButton(s, color) {
const before = stored(s).length;
await s.page.setInputFiles("#notepad-file", await pngFile(s, colour));
await s.page.setInputFiles("#notepad-file", await pngFile(s, color));
await until(() => stored(s).length === before + 1 && filesOf(s, stored(s).at(-1).id).every(Boolean), 5000);
await readyCount(s, before + 1);
}
@@ -863,7 +863,7 @@ async function addViaButton(s, colour) {
// A synthetic paste or drop of one PNG, sent to the editor, where a person's
// would land. A paste answers whether the page took it from the editor, a
// drop whether the dialog lit up while it was dragged over.
const sendPicture = (s, kind, colour) =>
const sendPicture = (s, kind, color) =>
s.page.evaluate(
async ({ kind, fill }) => {
const c = document.createElement("canvas");
@@ -882,7 +882,7 @@ const sendPicture = (s, kind, colour) =>
ta.dispatchEvent(new DragEvent("drop", { dataTransfer: dt, bubbles: true, cancelable: true, composed: true }));
return lit;
},
{ kind, fill: colour },
{ kind, fill: color },
);
test("Add image, paste and drop each add a thumbnail whose files are on disk and which survives closing", async (t) => {
@@ -963,7 +963,7 @@ test("the X asks first: Keep keeps the picture, Delete removes both its files",
test("the preview opens at the clicked picture, steps and wraps, and Esc closes it before the Notebook", async (t) => {
const s = await openSession(await suite.browser(), { t, workflow: "plan", payload: PLAN_QUESTION });
await openNotepad(s);
for (const colour of ["#c33", "#3c3", "#33c"]) await addViaButton(s, colour);
for (const color of ["#c33", "#3c3", "#33c"]) await addViaButton(s, color);
const urls = stored(s).map((img) => img.url);
const shown = () =>
s.page.evaluate(() => ({
+4 -4
View File
@@ -164,7 +164,7 @@ test("Continue here is hidden once the session meter is red, and the command and
// Under the desktop app (PLAN2CODE_IN_APP=1) the fresh-session advice in the
// meter's popover and the dashboard's red banner must point at the app's own
// New Session, never a command to copy into a terminal that is not there:
// the popover's is a button filled with the user's highlight colour.
// the popover's is a button filled with the user's highlight color.
test("under the app, the meter popover and the dashboard's red banner point at New Session, not a command", async (t) => {
const s = await openSession(await suite.browser(), {
t,
@@ -185,11 +185,11 @@ test("under the app, the meter popover and the dashboard's red banner point at N
const probe = document.createElement("i");
probe.style.color = "var(--accent)";
n.append(probe);
const colour = getComputedStyle(probe).color;
const color = getComputedStyle(probe).color;
probe.remove();
return [getComputedStyle(n).backgroundColor, colour];
return [getComputedStyle(n).backgroundColor, color];
});
assert.equal(fill, highlight, "filled with the user's highlight colour");
assert.equal(fill, highlight, "filled with the user's highlight color");
assert.equal(await fresh.locator("code").count(), 0, "no command to copy under the app");
});
+5 -5
View File
@@ -671,7 +671,7 @@ test("help: the template's icons and panels match HELP_TABS in order, headed by
}
});
test("help: every diagram tab has one labelled picture, the rest none; no inline styles or scripts", () => {
test("help: every diagram tab has one labeled picture, the rest none; no inline styles or scripts", () => {
const tpl = helpTemplate();
assert.doesNotMatch(tpl, /\sstyle=/);
assert.doesNotMatch(tpl, /<script/i);
@@ -691,7 +691,7 @@ test("help: every diagram tab has one labelled picture, the rest none; no inline
assert.doesNotMatch(body, /<div class="help-figure"[^>]*><\/div>/, `${t.id}'s insertion point is filled`);
if (t.id === "planny") {
const fig = body.match(/<figure class="help-figure help-moods"[^>]*role="img"[^>]*aria-labelledby="hd-planny-title"/);
assert.ok(fig, "the Planny moods are one labelled role=img figure");
assert.ok(fig, "the Planny moods are one labeled role=img figure");
const label = body.match(/id="hd-planny-title"[^>]*>([^<]*)</);
assert.ok(label && label[1].trim(), "the moods figure's label exists and says something");
continue;
@@ -700,9 +700,9 @@ test("help: every diagram tab has one labelled picture, the rest none; no inline
assert.ok(svg, `${t.id} draws an svg diagram`);
const open = svg[0].slice(0, svg[0].indexOf(">"));
assert.match(open, /role="img"/, `${t.id}'s diagram is an image`);
const labelled = open.match(/aria-labelledby="([^"]+)"/);
assert.ok(labelled, `${t.id}'s diagram is labelled`);
for (const id of labelled[1].split(/\s+/)) {
const labeled = open.match(/aria-labelledby="([^"]+)"/);
assert.ok(labeled, `${t.id}'s diagram is labeled`);
for (const id of labeled[1].split(/\s+/)) {
const ref = svg[1].match(new RegExp(`<(title|desc) id="${id}">([\\s\\S]*?)</\\1>`));
assert.ok(ref && ref[2].trim(), `${t.id}'s diagram has a non-empty #${id}`);
}
+3 -3
View File
@@ -253,7 +253,7 @@ function appJsReaders(dir) {
const publicPath = /["']public["']\s*,\s*["']app\.js["']|\bpublic\/app\.js/.test(text) && /\breadFile(Sync)?\b/.test(text);
return oneStatement || handedToAHelper || publicPath;
})
.map((f) => `${f} reads public/app.js as text: test the behaviour in a page test, or read the screen file that holds it`);
.map((f) => `${f} reads public/app.js as text: test the behavior in a page test, or read the screen file that holds it`);
}
test("shape: no test in scripts/ reads public/app.js as text", () => {
@@ -266,10 +266,10 @@ test("shape: the app.js check names the test file that reads it", () => {
fs.writeFileSync(path.join(dir, "test-fine.mjs"), 'const r = await fetch(base + "/app.js");\nfs.appendFileSync(path.join(d, "src", "app.js"), "x");\n');
assert.deepEqual(appJsReaders(dir), []);
fs.writeFileSync(path.join(dir, "test-reads-it.mjs"), 'const app = fs.readFileSync(path.join(ROOT, "public", "app.js"), "utf8");\n');
assert.deepEqual(appJsReaders(dir), ["test-reads-it.mjs reads public/app.js as text: test the behaviour in a page test, or read the screen file that holds it"]);
assert.deepEqual(appJsReaders(dir), ["test-reads-it.mjs reads public/app.js as text: test the behavior in a page test, or read the screen file that holds it"]);
fs.rmSync(path.join(dir, "test-reads-it.mjs"));
fs.writeFileSync(path.join(dir, "test-alias.mjs"), 'const web = (f) => fs.readFileSync(path.join(ROOT, "public", f), "utf8");\nconst app = web("app.js");\n');
assert.deepEqual(appJsReaders(dir), ["test-alias.mjs reads public/app.js as text: test the behaviour in a page test, or read the screen file that holds it"]);
assert.deepEqual(appJsReaders(dir), ["test-alias.mjs reads public/app.js as text: test the behavior in a page test, or read the screen file that holds it"]);
} finally {
fs.rmSync(dir, { recursive: true, force: true });
}
+4 -4
View File
@@ -365,7 +365,7 @@ test("finished: any finished state is never the picker's default, not only fixed
assert.equal(defaultSpec(specs.slice(0, 2), lookup), null, "only finished specs: start from scratch");
assert.equal(defaultSpec(specs)?.dir, "specs/a", "the real table does not know archived, so it is in play");
// The cards greyed for a fixed bug give a made-up finished state the same reason.
// The cards grayed for a fixed bug give a made-up finished state the same reason.
const archived = { dir: "specs/a", name: "a", state: "archived" };
for (const entry of CARD_ENTRIES) {
const fixed = cardAvailability(entry, SCAN, { dir: "specs/b", name: "b", state: "fixed" });
@@ -463,12 +463,12 @@ test("card rules: every state still in play is taken by at least one card", () =
assert.deepEqual(untakenStates(without, TABLE), ["no card's states take planned: add it to the skills.js entries whose card it lights"]);
});
test("card rules: a card's states and greyed reasons name only real states", () => {
test("card rules: a card's states and grayed reasons name only real states", () => {
const known = new Set([...Object.keys(TABLE), "none"]);
for (const sk of SKILLS) {
if (Array.isArray(sk.states)) for (const st of sk.states) assert.ok(known.has(st), `${sk.skill} takes ${st}, which is no state`);
for (const key of Object.keys(sk.greyed || {})) assert.ok(key === "default" || key === "finished" || known.has(key), `${sk.skill}'s greyed names ${key}, which is no state`);
if (Array.isArray(sk.states) && sk.card) assert.ok(sk.greyed && sk.greyed.default, `${sk.skill} has a default greyed reason`);
for (const key of Object.keys(sk.greyed || {})) assert.ok(key === "default" || key === "finished" || known.has(key), `${sk.skill}'s grayed names ${key}, which is no state`);
if (Array.isArray(sk.states) && sk.card) assert.ok(sk.greyed && sk.greyed.default, `${sk.skill} has a default grayed reason`);
}
});
+3 -3
View File
@@ -718,10 +718,10 @@ test("a card with a note box over the git board flows at its own height, never s
test("a card and its pager in the git board's card slot fill the board's width, never shrink to their content", () => {
const css = joinedCss();
// .card and .pager centre with auto inline margins; in the slot's grid those
// .card and .pager center with auto inline margins; in the slot's grid those
// would shrink a short confirm, and the pager under it, to fit their content.
assert.match(css, /\.card\s*\{[^}]*margin:\s*0 auto/, "the base card still centres outside the board");
assert.match(css, /\.pager\s*\{[^}]*margin:\s*0 auto/, "the base pager still centres outside the board");
assert.match(css, /\.card\s*\{[^}]*margin:\s*0 auto/, "the base card still centers outside the board");
assert.match(css, /\.pager\s*\{[^}]*margin:\s*0 auto/, "the base pager still centers outside the board");
assert.match(css, /\.git-cards > \.card,\s*\.git-cards > \.pager\s*\{\s*margin:\s*0;\s*\}/, "the card slot drops the auto margins for both");
});
+1 -1
View File
@@ -251,7 +251,7 @@ test("workspace: the original can be renamed and described but never removed; ot
}
});
test("workspace: browse returns the picked folder, or cancelled, and is hidden when the session looks remote", async () => {
test("workspace: browse returns the picked folder, or canceled, and is hidden when the session looks remote", async () => {
const picked = tempFolder();
const echo = consoleSession(["--workflow", "plan"], { env: { PLAN2CODE_PICKER_ECHO: picked } });
const cancel = consoleSession(["--workflow", "plan"], { env: { PLAN2CODE_PICKER_ECHO: "-" } });
+1 -1
View File
@@ -35,7 +35,7 @@ export const VERSIONS = Object.freeze({
});
export const HEADER =
"/* CodeMirror 6 (state, view, language, commands, lang-markdown), MIT licence, (c) Marijn Haverbeke and others.\n" +
"/* CodeMirror 6 (state, view, language, commands, lang-markdown), MIT license, (c) Marijn Haverbeke and others.\n" +
" * https://codemirror.net/ . Bundled by scripts/vendor-codemirror.mjs; do not edit by hand.\n" +
" * Versions: " +
Object.entries(VERSIONS)
+2 -2
View File
@@ -11,7 +11,7 @@
//
// PLAN2CODE_PICKER_ECHO (tests only, beside PLAN2CODE_NO_BROWSER): when set
// in the server's environment, /workspace/browse returns it as the picked
// folder instead of opening a picker, and "-" as a cancelled one.
// folder instead of opening a picker, and "-" as a canceled one.
import test from "node:test";
import assert from "node:assert/strict";
@@ -26,7 +26,7 @@ import { readChat } from "../src/web-console/inbox.mjs";
export const ROOT = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
export const CONSOLE_CLI = path.join(ROOT, "src", "web-console", "console.mjs");
// Canonicalised the same way server.mjs canonicalises a session dir (DIR,
// Canonicalized the same way server.mjs canonicalizes a session dir (DIR,
// server.mjs): on a machine whose %TEMP% itself resolves through an 8.3
// short name (seen in the wild on Windows), a server started later writes
// `state.worktree` in its realpath'd form, while anything in a test that
@@ -1,9 +1,9 @@
# Chart Playbook
> Part of plan2code-0-pathfinder — loaded at the top of MODE A (Chart). Expands the numbered Chart steps.
>
> **Backend note.** Steps 0, 2, and 4 — the gates and the grills — are identical either way, and so is every judgement call below (fog vs question, in scope vs out, the destination test). What differs is where Steps 3 and 5-7 put the bytes: on `**Backend:** github`, `github-issues.md` overrides the `map.md` and question-file templates here, the single-pass rule under *Step 6: Numbering and dependency order*, and the timing of the recon. Read it alongside this file, not instead of it.
> **Backend note.** Steps 0, 2, and 4 — the gates and the grills — are identical either way, and so is every judgment call below (fog vs question, in scope vs out, the destination test). What differs is where Steps 3 and 5-7 put the bytes: on `**Backend:** github`, `github-issues.md` overrides the `map.md` and question-file templates here, the single-pass rule under *Step 6: Numbering and dependency order*, and the timing of the recon. Read it alongside this file, not instead of it.
Charting produces a map and a set of question files. It resolves nothing by hand. Every judgement below serves one goal: put a sharp question on the map for everything you can phrase now, and leave everything else honestly in the fog.
Charting produces a map and a set of question files. It resolves nothing by hand. Every judgment below serves one goal: put a sharp question on the map for everything you can phrase now, and leave everything else honestly in the fog.
---
@@ -33,7 +33,7 @@ This gate and the Step 4 no-fog off-ramp are the same instinct at two moments: t
## Step 2: The destination grill
The destination is settled **first** because it fixes scope. Every later judgement — is this a question or fog, is this in scope or past the edge, is this map cleared — is measured against it. A vague destination makes all three unanswerable, and you will spend the rest of the map arguing about boundaries instead of decisions.
The destination is settled **first** because it fixes scope. Every later judgment — is this a question or fog, is this in scope or past the edge, is this map cleared — is measured against it. A vague destination makes all three unanswerable, and you will spend the rest of the map arguing about boundaries instead of decisions.
A destination is **one or two lines** describing what exists when the map clears. It is not a feature description. It is not a value proposition. It names the artifact and draws the edge.
@@ -50,7 +50,7 @@ Recommend an answer with each probe — the human corrects faster than they comp
Two round trips, not six. Three probes each — exactly the cap, so neither batch needs splitting.
Batch 2 bends the independence test on purpose. The arrival signal (5) can shift under the smallest arrival (4), so strictly it should be held back — but holding it costs a third round trip to catch a conflict that is rare and cheap to spot. The trade is to send them together and reconcile at the recap: if the smallest arrival comes back materially smaller than the artifact you were told about, re-check the arrival signal against it before writing the destination. A knowing trade here, not a licence to batch dependent probes elsewhere.
Batch 2 bends the independence test on purpose. The arrival signal (5) can shift under the smallest arrival (4), so strictly it should be held back — but holding it costs a third round trip to catch a conflict that is rare and cheap to spot. The trade is to send them together and reconcile at the recap: if the smallest arrival comes back materially smaller than the artifact you were told about, re-check the arrival signal against it before writing the destination. A knowing trade here, not a license to batch dependent probes elsewhere.
**Both batches go through the structured question tool.** Give each probe genuine candidate options with trade-offs and a recommendation; the built-in `Other` path is where the human composes the actor, a further feature to leave out, the arrival signal, or forcing-function detail in their own words. A clicked option is not written verbatim as the destination — the recap-confirmation tool call turns all six answers into the agreed one-or-two-line destination before disk write.
@@ -141,7 +141,7 @@ Recon is `legwork · AFK` — you do it alone, and you write it down **already r
Two disciplines keep this file useful:
- **Verify behaviour against actual code, never against a filename.** A file called `auditLogger.ts` may log nothing.
- **Verify behavior against actual code, never against a filename.** A file called `auditLogger.ts` may log nothing.
- **Scope the recon to the destination.** A recon of the whole repo is unreadable and stale in a week. If a subtree cannot plausibly be touched by the destination, say so in one line and move on.
Record what you could **not** determine as an explicit gap. Gaps at recon time are often the first real fog bullets.
@@ -257,7 +257,7 @@ The destination grill went **deep on one thing**. This grill goes **wide on ever
**You are not resolving anything here.** You are taking inventory. The instant an answer feels satisfying, you are probably going deep.
### Recognising that you have gone deep
### Recognizing that you have gone deep
Watch for these. Any one of them means stop and pull back:
@@ -312,7 +312,7 @@ Record each answer as one line in your working notes with an area label. At the
## The fog-vs-question test
This is the single most important judgement in the skill. Get it wrong toward questions and the map fills with unanswerable stubs that block the frontier. Get it wrong toward fog and the map has nothing takeable on it.
This is the single most important judgment in the skill. Get it wrong toward questions and the map fills with unanswerable stubs that block the frontier. Get it wrong toward fog and the map has nothing takeable on it.
> **The test is whether you can STATE the question precisely now — not whether you can ANSWER it now.**
@@ -446,7 +446,7 @@ plan, not at shipped code. Continuous streaming to external systems is not on th
- Questions are put to the human in plain English. Technical terms only where the term is the decision.
- HITL questions are answered by the human in their own words. Never self-answered.
- No new runtime dependency is assumed without a `research` question backing it.
- Compliance language is reviewed by Dana before anything user-facing is finalised.
- Compliance language is reviewed by Dana before anything user-facing is finalized.
- Sketches are throwaway and live only under `pathfinder/sketch-NN/`.
## Glossary
@@ -4,7 +4,7 @@
>
> **Local-file maps never load this file.** If `## Ground rules` says `**Backend:** local`, close it and use `questions.md`.
Everything the skill says about *judgement* is unchanged by the backend: the fog-vs-question test, the destination grill, one question at a time, the decide-menu-checkpoint cadence, HITL is never self-answered, the Clearing Gate rubric. This file changes only *where the bytes go*.
Everything the skill says about *judgment* is unchanged by the backend: the fog-vs-question test, the destination grill, one question at a time, the decide-menu-checkpoint cadence, HITL is never self-answered, the Clearing Gate rubric. This file changes only *where the bytes go*.
---
@@ -17,13 +17,13 @@ A map on GitHub Issues buys three things local files cannot:
| | Local files | GitHub Issues |
|---|---|---|
| Visibility | One machine, one person | Anyone with repo access, in a UI they already have open |
| Blocking | A `Blocked by:` line only an agent reads | Native issue dependencies — GitHub greys out blocked issues in its own UI |
| Blocking | A `Blocked by:` line only an agent reads | Native issue dependencies — GitHub grays out blocked issues in its own UI |
| Concurrency | One session at a time by construction | Several people can work unblocked questions at once; the assignee is a real lock |
It costs three things too, and the human must know all three before they pick it:
1. **Issues on a public repo are public.** The destination, the rejected alternatives, the codebase recon, the technical debt in the blast radius — all of it is world-readable the moment it is written. Never chart to a public repo's tracker anything that would embarrass the project or leak a customer.
2. **It writes to shared state.** A local map costs nothing to abandon. Twelve stale issues labelled `pathfinder:grill-hitl` on a team's tracker is litter someone has to clean.
2. **It writes to shared state.** A local map costs nothing to abandon. Twelve stale issues labeled `pathfinder:grill-hitl` on a team's tracker is litter someone has to clean.
3. **It needs `gh`, auth, and issues enabled.** More that can break, in a step whose whole job is to remove friction.
---
@@ -69,7 +69,7 @@ This is the whole mapping. Everything below expands a row.
| Local file model | GitHub Issues model |
|---|---|
| `specs/<idea>/pathfinder/map.md` | One issue, labelled `pathfinder:map`, titled `Map: <idea>` |
| `specs/<idea>/pathfinder/map.md` | One issue, labeled `pathfinder:map`, titled `Map: <idea>` |
| `questions/NN-<slug>.md` | A **sub-issue** of the map, titled with the question name |
| `NN` ordering | The map's sub-issue order — the order they were created, which is dependency order |
| `## Question` in the file | The issue body |
@@ -79,7 +79,7 @@ This is the whole mapping. Everything below expands a row.
| `State: open` | Issue open, **no assignee** |
| `State: claimed` | Issue open, **assigned** |
| `State: resolved` | Issue **closed as completed**, with an `## Answer` comment |
| `State: out-of-scope` | Issue **closed as not planned**, labelled `pathfinder:out-of-scope`, no `## Answer` |
| `State: out-of-scope` | Issue **closed as not planned**, labeled `pathfinder:out-of-scope`, no `## Answer` |
| `Blocked by: 02, 04` | Native issue dependencies (`dependencies/blocked_by`) |
| `Locked: yes` | The `pathfinder:locked` label |
| `Claimed: <timestamp>` | GitHub's own assignment event in the timeline |
@@ -221,7 +221,7 @@ gh api --method POST repos/<owner>/<repo>/issues/<blocked-number>/dependencies/b
**The database id is the single most common failure in this backend.** `gh api repos/o/r/issues/42 --jq .id` returns something like `2716143027`. The `42` is the *number*; `I_kwDO...` is the *node id*. The node id is rejected outright. The *number* is worse: a small integer like `42` is itself a perfectly valid database id — of some unrelated issue created years ago — so the call can succeed and silently attach the wrong thing. Fetch `.id` for every issue you are about to reference, and never hand-assemble one.
Charting still writes `00-codebase-context`'s equivalent — the Step 3 recon you held. Create it **first**, labelled `pathfinder:legwork-afk`, post the recon as an `## Answer` comment, and close it as completed in the same pass. It is resolved on arrival, exactly as in local mode, and it is what the handoff's `## System Context` is built from.
Charting still writes `00-codebase-context`'s equivalent — the Step 3 recon you held. Create it **first**, labeled `pathfinder:legwork-afk`, post the recon as an `## Answer` comment, and close it as completed in the same pass. It is resolved on arrival, exactly as in local mode, and it is what the handoff's `## System Context` is built from.
### If the endpoints are unavailable
@@ -384,7 +384,7 @@ Research subagents work the same way with one substitution: the brief carries th
Identical in shape; the inputs come from the query instead of the checklist.
- **Heading** — `🧭 <idea> · <Status> · <closed>/<total> cleared`, where `<total>` excludes anything labelled `pathfinder:out-of-scope`.
- **Heading** — `🧭 <idea> · <Status> · <closed>/<total> cleared`, where `<total>` excludes anything labeled `pathfinder:out-of-scope`.
- **Glyph order** — sub-issue order, the same order Chart Step 6 created them in.
- **Glyphs** — `●` closed as completed · `◉` open and assigned to you · `○` open, unassigned, unblocked · `⊘` open with `blocked_by > 0` · `⊝` closed as not planned.
- **Named legend** — names, never `#numbers`. `(blocked:<name>)` names the blocker rather than numbering it, since there is no stable `NN` to point at.
@@ -112,13 +112,13 @@ The primary channel. One question object per probe, up to three in a single call
- **Header** — the decision in two or three plain words (`Export format`, `Size cap`). Not a type, not a marker, not a number.
- **Question** — the probe, with its why-it-matters. This is prose and it is not rationed; the same sentences you would have written in a Q block go here.
- **Options** — the genuine alternatives, each described by its trade-off, with the recommended one named as such in its description. Two to four; the free-text escape hatch covers the rest. Label plainly, then let the description carry the precise term: `One file per message` labelling the `.eml`-in-a-ZIP option, with `.eml` named in the description.
- **Options** — the genuine alternatives, each described by its trade-off, with the recommended one named as such in its description. Two to four; the free-text escape hatch covers the rest. Label plainly, then let the description carry the precise term: `One file per message` labeling the `.eml`-in-a-ZIP option, with `.eml` named in the description.
A short *label* is not a short *decision*. The label is a handle — `Fixed tick count` — and the description carries the trade-off that makes it choosable. A label bundling several independent answers is a probe that wants splitting.
**A click is a decision, not a sentence.** The HITL rule wants an `## Answer` traceable to something the human actually said, and a selected option label is thin evidence on its own. What makes tool-delivered answers legitimate is the recap turn in *Landing the grill* — you play the choices back in the tool's question text and they confirm or correct in their own words. Never skip the recap on the grounds that the tool already captured the answer; the tool captured the *pick*, and the recap captures the *agreement*.
**If a reply comes back thinner than the decision** — a bare click on something you now realise carries weight — do not paper over it. Fold the why into the recap turn as one more probe before writing the `## Answer`.
**If a reply comes back thinner than the decision** — a bare click on something you now realize carries weight — do not paper over it. Fold the why into the recap turn as one more probe before writing the `## Answer`.
#### Numbered Q blocks
@@ -102,7 +102,7 @@ Pathfinder writes `specs/<idea>/PLAN-DRAFT-<YYYYMMDD>.md` with the header line:
`**Status:** Phase 3 Complete - Resume at Phase 4`
`/plan2code-1-plan` **already recognises that exact string.** Its "Check for Existing Progress" block, which runs before Phase 1, reads:
`/plan2code-1-plan` **already recognizes that exact string.** Its "Check for Existing Progress" block, which runs before Phase 1, reads:
`- Status "Phase 3 Complete - Resume at Phase 4": Resume at Phase 4`
@@ -128,7 +128,7 @@ Everything in the draft traces to something on the map. Nothing is invented at h
| `## Destination` | Section 1 Executive Summary (2-3 sentences, present tense) and Section 7 Success Criteria (the destination restated as checkable outcomes) |
| Resolved `grill` answers describing behavior | Section 2.1 Functional Requirements, one `FR-N` per decided behavior |
| Resolved `grill` answers describing performance, security, scale, operability | Section 2.2 Non-Functional Requirements, one `NFR-N` each |
| `## Out of scope` | Section 2.3 Out of Scope — copied line for line, wording and order intact. The ONLY permitted change is the link prefix: `./questions/` becomes `./pathfinder/questions/`, because the draft sits one level above the map. Do not re-word, re-order, or summarise; a re-worded scope boundary is a re-litigated one. |
| `## Out of scope` | Section 2.3 Out of Scope — copied line for line, wording and order intact. The ONLY permitted change is the link prefix: `./questions/` becomes `./pathfinder/questions/`, because the draft sits one level above the map. Do not re-word, re-order, or summarize; a re-worded scope boundary is a re-litigated one. |
| The testing-posture question's answer | Section 2.4 Testing Strategy table (Types / Phase Testing / Coverage) |
| Resolved `research` answers and their `## Evidence` | Section 3 Tech Stack — the cited source becomes the Justification cell |
| `questions/00-codebase-context.md` | The `## System Context` section, and the components table in 4.3 |
@@ -211,7 +211,7 @@ next run rather than truncating.
| Entry points to change | `AuditExportJob`, registered in `HangfireStartup.ConfigureRecurringJobs()` | [Codebase context](./pathfinder/questions/00-codebase-context.md) |
| Existing patterns to follow | Jobs resolve tenant scope via `ITenantScopeFactory`; no job reads config directly | [Codebase context](./pathfinder/questions/00-codebase-context.md) |
| Integration surfaces | S3 (customer-owned), Hangfire scheduler, `TenantConfigStore` | [Destination auth](./pathfinder/questions/03-destination-auth.md), [Scheduling model](./pathfinder/questions/02-scheduling-model.md) |
| Technical debt in the path | `AuditQuery` materialises full result sets; streaming reader needed before FR-1 | [Codebase context](./pathfinder/questions/00-codebase-context.md) |
| Technical debt in the path | `AuditQuery` materializes full result sets; streaming reader needed before FR-1 | [Codebase context](./pathfinder/questions/00-codebase-context.md) |
| System boundaries | Read-only against the audit store; writes only to customer buckets and the run-log table | [Retention and replay](./pathfinder/questions/04-retention-and-replay.md) |
| Conventions in force | `AGENTS.md` present and read; its logging and DI conventions govern | `pathfinder/map.md` ## Ground rules |
@@ -280,7 +280,7 @@ Manifest sequence numbers are per tenant, monotonic, and reused on replay.
| Cross-account role assumption is unexercised in this codebase | Medium | High | Spike `S3RoleAssumer` against a second AWS account before any other component |
| A tenant exceeds the daily ceiling indefinitely | Medium | Medium | Spill oldest-first plus a three-run alarm — [Overflow behavior](./pathfinder/questions/08-overflow-behavior.md) |
| Partial objects visible after a failed run | Low | High | Upload to a run-scoped prefix, publish the manifest last — the manifest is the commit point |
| `AuditQuery` materialises full result sets | High | High | Streaming reader is a prerequisite, not an optimisation |
| `AuditQuery` materializes full result sets | High | High | Streaming reader is a prerequisite, not an optimization |
| Customer revokes the role mid-run | Low | Medium | Fail the run whole; replay window covers recovery |
## 7. Success Criteria
@@ -335,7 +335,7 @@ Ruled out of scope: [Failure notification](./pathfinder/questions/07-failure-not
**No scrapable confidence numbers anywhere in the file.** Write the confidence as `Requirements-clarity 22/25 · Feasibility-technical 21/25 · Integration-points 23/25 · Risk-assessment 20/25` — hyphenated dimension labels, sub-scores over 25, no total, no percent sign.
The reason is exact. When a PLAN-DRAFT carries no `METRICS_JSON` comment, the metrics collector falls back to scraping it by regex: an overall-confidence pattern that requires a literal `%`, and four breakdown patterns that match a bare `Requirements` / `Feasibility` / `Integration` / `Risk` followed directly by whitespace, a colon, or a pipe and then digits. **The breakdown patterns do not require a percent sign.** A pathfinder-written draft always lacks that comment until `/plan2code-1-plan` Phase 7 appends one, so both the percent sign *and* the bare dimension words have to be kept off the page — otherwise the pipeline records a planning-step confidence that no planning step ever produced. The hyphen in `Requirements-clarity` breaks the match; a table row reading `| Requirements | 11 |` does not, which is why the Scope Assessment row is labelled `Requirements decided`.
The reason is exact. When a PLAN-DRAFT carries no `METRICS_JSON` comment, the metrics collector falls back to scraping it by regex: an overall-confidence pattern that requires a literal `%`, and four breakdown patterns that match a bare `Requirements` / `Feasibility` / `Integration` / `Risk` followed directly by whitespace, a colon, or a pipe and then digits. **The breakdown patterns do not require a percent sign.** A pathfinder-written draft always lacks that comment until `/plan2code-1-plan` Phase 7 appends one, so both the percent sign *and* the bare dimension words have to be kept off the page — otherwise the pipeline records a planning-step confidence that no planning step ever produced. The hyphen in `Requirements-clarity` breaks the match; a table row reading `| Requirements | 11 |` does not, which is why the Scope Assessment row is labeled `Requirements decided`.
**The `**Next:**` footer must ship with both bullets.** Pathfinder cannot edit the planning skill, so those two instructions travel inside the artifact:
@@ -40,7 +40,7 @@ One idea per session, so there is only ever one trail.
Confidence: solid, but Risk is borderline.
WAITING ON YOU · answer here, in this conversation:
Q2 Ceiling behaviour past the cap (re-ask) · Q3 Who sees the truncation warning
Q2 Ceiling behavior past the cap (re-ask) · Q3 Who sees the truncation warning
```
- The heading counts resolved questions over every question except out-of-scope ones.
@@ -1097,31 +1097,31 @@ async function cmdLint(loc) {
if (b === q.nn) add("error", q.path, "is blocked by itself");
}
}
// Cycles in Blocked by: a three-colour depth-first search (grey = on the
// Cycles in Blocked by: a three-color depth-first search (gray = on the
// current path, black = fully explored), so each question is explored once
// however densely the questions block each other. Every back edge is a
// cycle, reported once, against the question it starts from.
const reported = new Set();
const colour = new Map();
const color = new Map();
const pathStack = [];
const visit = (nn) => {
colour.set(nn, "grey");
color.set(nn, "gray");
pathStack.push(nn);
for (const b of byNN.get(nn).blockedBy) {
if (!byNN.has(b)) continue;
if (colour.get(b) === "grey") {
if (color.get(b) === "gray") {
const c = [...pathStack.slice(pathStack.indexOf(b)), b];
const key = [...new Set(c)].sort().join(",");
if (!reported.has(key)) {
reported.add(key);
add("error", byNN.get(b).path, `Blocked by: cycle ${c.join(" -> ")}; a cycle is one decision phrased twice (merge them or drop an edge)`);
}
} else if (!colour.has(b)) visit(b);
} else if (!color.has(b)) visit(b);
}
pathStack.pop();
colour.set(nn, "black");
color.set(nn, "black");
};
for (const q of questions) if (!colour.has(q.nn)) visit(q.nn);
for (const q of questions) if (!color.has(q.nn)) visit(q.nn);
// Scraper bait in the files the collector or a reader treats as planning output.
const baitFiles = [loc.mapPath, ...walk(path.join(loc.pf, "briefs"))];
for (const n of fs.existsSync(loc.ideaDir) ? fs.readdirSync(loc.ideaDir) : []) {
+1 -1
View File
@@ -23,7 +23,7 @@ The map lives in ONE of two places — the human's pick at Chart Step 1, never y
Read references/github-issues.md — REQUIRED on `github`, skip on `local`.
> Fallback: map = a `pathfinder:map` issue titled `Map: <idea>`; questions = its sub-issues, labelled `pathfinder:<type>-<mode>`; blocking = native dependencies; claim = assign `@me`; resolve = `## Answer` comment, then close.
> Fallback: map = a `pathfinder:map` issue titled `Map: <idea>`; questions = its sub-issues, labeled `pathfinder:<type>-<mode>`; blocking = native dependencies; claim = assign `@me`; resolve = `## Answer` comment, then close.
Recorded as the first `## Ground rules` bullet (`**Backend:** local|github`), never re-asked or switched. Either way the PLAN-DRAFT lands in local `specs/<idea>/` — downstream steps read files, not issues.
+1 -1
View File
@@ -164,7 +164,7 @@ Use kebab-case for feature name (e.g., `user-authentication`).
- "Run after each phase": Add testing task block at end of EVERY phase
- "Dedicated phase only": Create final Phase N: Testing
- "None" or empty: Omit testing tasks
- `| Approach | Test first |` in 2.4: in every phase, order each task's test before its code and put a plain sub-bullet ` - Test: <where the test drives the behaviour>` directly under the task line (no checkbox, so the loop's task count is unchanged), for example `` - Test: through `POST /votes` ``
- `| Approach | Test first |` in 2.4: in every phase, order each task's test before its code and put a plain sub-bullet ` - Test: <where the test drives the behavior>` directly under the task line (no checkbox, so the loop's task count is unchanged), for example `` - Test: through `POST /votes` ``
**Small Projects (1-2 phases):** Combine sections, still create separate overview.md and phase-1.md. Note: "Small project - phases combined"
+1 -1
View File
@@ -26,7 +26,7 @@ The FIRST thing you do, before anything else in this file — before reading a s
- Run tests ONLY if a phase task or a task's `Test:` line lists them
- Do NOT run git commands - provide commit instructions for user
- Flag blockers clearly - never skip silently
- Read `references/building-habits.md` when a bug or unexpected failing test turns up, before any task in a Test first phase (its tasks carry `Test:` lines), and before any task that changes no behaviour; follow it.
- Read `references/building-habits.md` when a bug or unexpected failing test turns up, before any task in a Test first phase (its tasks carry `Test:` lines), and before any task that changes no behavior; follow it.
- No file tools: output contents in code blocks with a file path header; no filesystem: ask the user to paste file contents
## Required Context
+1 -1
View File
@@ -71,7 +71,7 @@ A reproduction written as a new test inside the project is offered, never assume
### Step 3: Narrow
- **A known-good version exists** (it worked before): `git bisect` with the reproduction as the check, in a throwaway worktree (`git worktree add <tmp> HEAD`, removed at the end) so the person's checkout never moves; in place only on a clean tree, with `git bisect reset` before you finish. Then read the commit it lands on.
- **Otherwise:** read the code path from the entry point the reproduction hits to where the wrong value or behaviour first appears.
- **Otherwise:** read the code path from the entry point the reproduction hits to where the wrong value or behavior first appears.
- Temporary logging only outside the source tree, or reverted at once.
Stop when you can name the line where right turns into wrong.
+2 -2
View File
@@ -59,7 +59,7 @@ On the console the page draws the board itself from `state.git`; you never post
1. Post an `activity` line ("Pulling from origin…"); collecting the click already set the page to working.
2. Run `git.mjs plan <op>` with the action's fields as flags.
3. With `ask: true`: a `confirm` becomes a `confirm` card, posted verbatim (`danger` and `consequences` as given; `files` as a `[{ path, state }]` table where the plan names files). A `card` of kind `switch`, `dirty` or `remote` becomes a `choice` card with exactly its `options`, labelled **Switch and bring them** (`bring`), **Commit first** (`commit-first`) and **Cancel** (`cancel`), or for `remote` one option per remote with `preset` recommended; put git's `reason` in `body` when given. Then wait for the answer. A `remote` pick plans `publish --remote <it>` again and asks its `confirm`.
3. With `ask: true`: a `confirm` becomes a `confirm` card, posted verbatim (`danger` and `consequences` as given; `files` as a `[{ path, state }]` table where the plan names files). A `card` of kind `switch`, `dirty` or `remote` becomes a `choice` card with exactly its `options`, labeled **Switch and bring them** (`bring`), **Commit first** (`commit-first`) and **Cancel** (`cancel`), or for `remote` one option per remote with `preset` recommended; put git's `reason` in `body` when given. Then wait for the answer. A `remote` pick plans `publish --remote <it>` again and asks its `confirm`.
4. Run the command(s).
5. In ONE post: `{ "reread": true }`, the `git-result` notice (one line: what happened, with short hashes, and after a push or publish the link from `pr-url`), `board: { describe }` when changes remain (a short kebab-case description of them, for the Create prompt), posted with `--wait`.
@@ -74,7 +74,7 @@ On a non-zero exit, save git's stderr to the session folder, run `classify-error
- **commit** commits only the paths in `files`. With `ignore[]`, first propose those `.gitignore` lines as a doc plus a `review` card (approve / change), write them on approve, and add `.gitignore` to the commit.
- **abort**, **continue**: `plan abort` / `plan continue`, then `reread`.
- **pr-host**: the server already saved the answer; post `reread` only.
- **done** (Done with git): Session End; a card of yours still open is cancelled first (notes/git.md).
- **done** (Done with git): Session End; a card of yours still open is canceled first (notes/git.md).
- Deleting a branch on the remote is never offered and never run.
## Conflict help
+2 -2
View File
@@ -71,7 +71,7 @@ The `Failure log` section below is a recording of mistakes made by previous AI A
When you make a mistake, get corrected, or discover something about this codebase that wasn't written down:
1. Add one line to the `Failure log` below, in the imperative, describing the correct behaviour.
1. Add one line to the `Failure log` below, in the imperative, describing the correct behavior.
2. Keep it specific to this repo. General advice belongs nowhere.
3. If this fix is a workflow rather than a rule, put it in `.claude/skills/` and link it from here.
4. Include the change in the same commit and mention it in your summary.
@@ -156,7 +156,7 @@ Present the user with update options:
| Testing | Commands? Fixtures? Mocking? |
| Environment | Local/CI/deploy? Env vars/files? |
| Rules | Project-wide or specific? Why? |
| Failure Log | What went wrong? Correct behaviour (imperative, one line)? Merge into an entry on the same topic if one exists; over 17 entries, propose what to prune (rule 7). |
| Failure Log | What went wrong? Correct behavior (imperative, one line)? Merge into an entry on the same topic if one exists; over 17 entries, propose what to prune (rule 7). |
| Other | "Tell me what to add." |
| Sync & Maintain | Scope: all surfaces or specific? Then follow the Sync & Maintain section. |
| Review | Per section: "Still accurate?" |
+1 -1
View File
@@ -74,7 +74,7 @@ The `Failure log` section below is a recording of mistakes made by previous AI A
When you make a mistake, get corrected, or discover something about this codebase that wasn't written down:
1. Add one line to the `Failure log` below, in the imperative, describing the correct behaviour.
1. Add one line to the `Failure log` below, in the imperative, describing the correct behavior.
2. Keep it specific to this repo. General advice belongs nowhere.
3. If this fix is a workflow rather than a rule, put it in `.claude/skills/` and link it from here.
4. Include the change in the same commit and mention it in your summary.
+2 -2
View File
@@ -40,7 +40,7 @@ Check for `./AGENTS.md` first:
- Standalone workflow - does NOT create spec files or feed into steps 2-4
- Launched with a spec folder holding a `DIAGNOSIS-*.md`: read it first, as the bug's context (its cause and suggested fix are already found; re-run its reproduction before and after the fix). Once it passes, set the diagnosis `**Status:**` to `Fixed`; escalating, use that folder rather than asking for a name. Fixed, with nothing in the folder past the diagnosis (no `PLAN-CONVERSATION`, `PLAN-DRAFT`, `pathfinder/map.md` or `overview.md`)? It is done: run `node "<S>/specs.mjs" archive <spec> --dry-run` from the project root (`<S>` is `scripts/` beside this SKILL.md, `~/.agents/skills/plan2code-quick-task/scripts/` globally), show its `files`, ask "Archive it to `specs--completed/`? (yes / no)", and on yes run it without `--dry-run`. On no it stays on the dashboard as "Bug fixed".
- Cause unclear or the fix big? Stop and suggest `/plan2code-diagnose`.
- Read `references/building-habits.md` when the ask is a bug fix or a test fails unexpectedly, after a yes to "Write the test first?", and before a change meant to alter no behaviour; follow it.
- Read `references/building-habits.md` when the ask is a bug fix or a test fails unexpectedly, after a yes to "Write the test first?", and before a change meant to alter no behavior; follow it.
```
⋅
@@ -52,7 +52,7 @@ Check for `./AGENTS.md` first:
Ask what feature the user wants, then ask follow-up questions until 100% clear. Console: that first card carries `"templates": "idea"` (console.md → The kinds).
**Write the test first?** Ask it with the follow-ups (or on its own if there are none) only when the change alters behaviour AND the project already has a test runner you can see (a `test` script in `package.json`, pytest config in `pytest.ini` or `pyproject.toml`, `go.mod` with `_test.go` files, or similar). Never for a pure refactor, a docs change, or a project with no runner. Console: one `confirm` card in the same batch as the other plan questions; terminal: one line in the same prompt. On yes, name the test spot in the plan's Verify section and follow the test-first habit.
**Write the test first?** Ask it with the follow-ups (or on its own if there are none) only when the change alters behavior AND the project already has a test runner you can see (a `test` script in `package.json`, pytest config in `pytest.ini` or `pyproject.toml`, `go.mod` with `_test.go` files, or similar). Never for a pure refactor, a docs change, or a project with no runner. Console: one `confirm` card in the same batch as the other plan questions; terminal: one line in the same prompt. On yes, name the test spot in the plan's Verify section and follow the test-first habit.
## Scope Validation
+2 -2
View File
@@ -19,7 +19,7 @@ If `open` fails outright, fall back without drama: list the skills in the termin
## The menu
The page draws the cards itself — you never send the list. It also knows the repo already: `open` scans `AGENTS.md` and `specs/` into `state.scan` (`{ hasAgents, isGit, specs: [{ dir, name, state, detail, touched }] }`), and the picker at the top enables or greys every card from it — the spec the person picks there is the target their launch carries. What you post is your judgment on top of that:
The page draws the cards itself — you never send the list. It also knows the repo already: `open` scans `AGENTS.md` and `specs/` into `state.scan` (`{ hasAgents, isGit, specs: [{ dir, name, state, detail, touched }] }`), and the picker at the top enables or grays every card from it — the spec the person picks there is the target their launch carries. What you post is your judgment on top of that:
```jsonc
{
@@ -137,6 +137,6 @@ You arrive here mid-conversation after a `__dashboard` press — from a finished
## While it waits
- Bounded slices per console.md, using the longest safe slice: exit 10 → relay one line and immediately wait again — never end the turn after an arbitrary number of slices; exit 20 → `open --resume <sid>` (no `--workflow` — it stays `dashboard` until a launch overwrites it); exit 30 → they cancelled, ask in the terminal what they want.
- Bounded slices per console.md, using the longest safe slice: exit 10 → relay one line and immediately wait again — never end the turn after an arbitrary number of slices; exit 20 → `open --resume <sid>` (no `--workflow` — it stays `dashboard` until a launch overwrites it); exit 30 → they canceled, ask in the terminal what they want.
- A `__stop` action is the person ending the session before picking: post `finish` (a headline that says paused, `"command": "/plan2code"`) then `stop`, per console-stop.md.
- The console keeps `agent.status` honest: collecting a pick sets `working`, and waiting on the menu sets `waiting`. Post an `activity` while a launch becomes a skill.
+4 -4
View File
@@ -15,17 +15,17 @@ When a bug is reported or turns up, or a test fails unexpectedly:
Applies only when the phase's tasks carry `Test:` lines (the plan picked Test first), or the person said yes to "Write the test first?" in Quick Task. For each task:
1. Write the test at the task's named test spot (its `Test:` line, or the plan's Verify section).
2. Run it and see it fail for the right reason: the behaviour is missing, not a typo or an import error.
2. Run it and see it fail for the right reason: the behavior is missing, not a typo or an import error.
3. Write the code until the test passes. Keep the change to what the test asks for.
4. Never weaken, skip or delete a test to make it pass. If the test itself is wrong, say so and fix the test on its own.
## Pin behaviour first
## Pin behavior first
For a task meant to change no behaviour (a restructure, a rename, a move):
For a task meant to change no behavior (a restructure, a rename, a move):
1. Before touching the code, add or confirm tests that cover what the task touches.
2. Run them and see them pass.
3. Make the change.
4. Run the same tests, unchanged. They must pass. A test that needs editing means behaviour changed: stop and say so.
4. Run the same tests, unchanged. They must pass. A test that needs editing means behavior changed: stop and say so.
Adapted from Matt Pocock's `diagnose` and `tdd` skills and pstack's debugging playbook (both MIT).
+1 -1
View File
@@ -177,7 +177,7 @@ export function writeIfChanged(file, content) {
return true;
}
/** Normalise line endings for parsing; keep the original for writing back. */
/** Normalize line endings for parsing; keep the original for writing back. */
export function eol(text) {
return text.includes("\r\n") ? "\r\n" : "\n";
}
+1 -1
View File
@@ -206,7 +206,7 @@ function parseGroups(overview) {
if (cells.length < 2 || /^group$/i.test(cells[0])) continue;
const id = plainText(cells[0]);
const phases = phaseList(cells[1]);
// "None", a dash, a single phase, a group its author labelled sequential
// "None", a dash, a single phase, a group its author labeled sequential
// ("A (sequential)"), or a Phases cell written as a chain ("1 → 2") is not
// a parallel group.
if (!id || /^(none|-|–|—)$/i.test(id) || /\bsequential\b/i.test(id) || /→|->|\bthen\b/i.test(cells[1]) || phases.length < 2) continue;
+1 -1
View File
@@ -73,7 +73,7 @@ port, and the filesystem as transport; this CLI is the whole agent surface.
A bounded wait slice, sized below your shell timeout. Exit 0 = the
result is on stdout, 10 = still waiting ("Waiting on your answer
in the web console"; call again), 20 = server gone (open --resume
<sid>), 30 = cancelled. Exits 0 and 10 carry terminalLine.
<sid>), 30 = canceled. Exits 0 and 10 carry terminalLine.
Exit 0 may carry "chat" (Quick questions); with no card send it
is type: "chat" and actions is empty. Exit 0 may also carry
"workspace" (changes since you last heard, each once, with a
+1 -1
View File
@@ -73,7 +73,7 @@ export function useCli(cli) {
// PLAN2CODE_CONSOLE_TRACE=1 prints where the time goes, to stderr: the
// start path is what stands between someone and their first look at the page,
// and it is only worth optimising with numbers in hand.
// and it is only worth optimizing with numbers in hand.
const TRACE = Boolean(process.env.PLAN2CODE_CONSOLE_TRACE);
function trace(what) {
if (TRACE) process.stderr.write(`trace ${Math.round(performance.now())}ms ${what}\n`);
+2 -2
View File
@@ -50,9 +50,9 @@ first, and post before anything slow.
`state.scan` is `{ hasAgents, isGit, pending, specs: [{ dir, name, state, detail, touched }], handoffs, handoffsDir }`,
a snapshot of the last `open` (a spec created mid-session appears the next time
the session resumes as a dashboard). `pending` is how many files a commit would
take (`null` when git cannot say): the Git card never greys out, shows the count
take (`null` when git cannot say): the Git card never grays out, shows the count
when there is one, and outside a repository says Git can start one. The picker
greys the cards that do not fit the selected spec — or hides them, while the
grays the cards that do not fit the selected spec — or hides them, while the
**Hide unavailable workflows** switch under it is on (the default).
The `menu` you post (`note`, `recommend`, `details`) describes the initially
+1 -1
View File
@@ -59,7 +59,7 @@ export class NotepadError extends Error {
/* ------------------------------------------------------------------ names */
// `<folder-name>-<first 12 hex of sha256(foldKey(folder))>`: recognisable in a
// `<folder-name>-<first 12 hex of sha256(foldKey(folder))>`: recognizable in a
// file browser, safe on every OS, and one notepad per folder however its case
// is typed where the file system ignores case.
export function notepadKey(folder) {
+4 -4
View File
@@ -64,7 +64,7 @@ answer. `__git` names no question, like `__stop`.
| `plan` says | On the page |
| --- | --- |
| `confirm` | A `confirm` card with its `title`, `body`, `danger` and `consequences` verbatim (the consequences end with the exact command). Where the plan names files, add them as `files: [{ "path", "state" }]`. |
| `card.kind: "switch"` | A `choice`, "Bring your changes?": exactly the `options` given, labelled **Switch and bring them** (`bring`), **Commit first** (`commit-first`), **Cancel** (`cancel`); the files in `body`, and `reason` when git would refuse (then there is no `bring`). `allowOther: false`. |
| `card.kind: "switch"` | A `choice`, "Bring your changes?": exactly the `options` given, labeled **Switch and bring them** (`bring`), **Commit first** (`commit-first`), **Cancel** (`cancel`); the files in `body`, and `reason` when git would refuse (then there is no `bring`). `allowOther: false`. |
| `card.kind: "dirty"` | The same `choice` for a pull that needs a clean tree: **Commit first** / **Cancel**, `reason` in `body`. |
| `card.kind: "remote"` | A `choice`, "Publish to which remote?": one option per remote, `preset` recommended. Then `plan publish --remote <it>` and its `confirm`. |
| `ask: false` | No card: run it on the click. |
@@ -109,9 +109,9 @@ after each commit step (N commits made), and `run: { "event": "git-conflict",
"id": "conflict-<n>" }` once per conflict help, resolved or aborted.
**Finishing** (`console-finish.md`). **Done with git** (`op: "done"`). A `done`
that arrives while one of your cards is still open is the person cancelling it:
record that card as cancelled (`{ "items": [{ "id": "<id>", "status":
"answered", "answer": { "text": "Cancelled by Done with git" } }] }`, not
that arrives while one of your cards is still open is the person canceling it:
record that card as canceled (`{ "items": [{ "id": "<id>", "status":
"answered", "answer": { "text": "Canceled by Done with git" } }] }`, not
`settle`, which refuses a card nothing was sent to) in the same post as the
finish, or, with nothing done, before resuming as the dashboard. Never run what
the card was asking for. With something done this session: a `finish` with a
+1 -1
View File
@@ -8,7 +8,7 @@
import { spawn } from "node:child_process";
/** The link to open, normalised, or null when it is not a plain http or https link. */
/** The link to open, normalized, or null when it is not a plain http or https link. */
export function linkToOpen(raw) {
if (typeof raw !== "string" || raw.length > 4096) return null;
let url;
+1 -1
View File
@@ -249,7 +249,7 @@ export function pickerCommand(start, prompt) {
* Show the picker and settle on what the person did: `{ path }` for a pick,
* `{ cancelled: true }` when they closed it, `{ error }` when the picker
* itself failed or this OS has none. Pickers exit 0 or 1 with nothing printed
* when cancelled.
* when canceled.
*/
export function pickFolder(start, prompt, { spawnImpl = spawn } = {}) {
const picker = pickerCommand(start, prompt);
+4 -4
View File
@@ -244,7 +244,7 @@ export function suggestionFrom(item) {
if (!raw) return "";
const stripped = raw.replace(EXAMPLE_LEAD, "").trim();
if (!stripped) return "";
// Recapitalise only when a lead-in was actually removed, and never on a
// Recapitalize only when a lead-in was actually removed, and never on a
// field with a shape to match: "audit-export" must not become "Audit-export".
if (stripped !== raw && !item.pattern && /^[a-z]/.test(stripped)) {
return stripped[0].toUpperCase() + stripped.slice(1);
@@ -358,7 +358,7 @@ export function stopAction({ handoff } = {}) {
* answers into the files, and a request landing then is how a question ends up
* half recorded. `waiting` is the caller's "the agent is working or a reply is
* owed, and it has not gone adrift" -- an agent that has stopped checking in
* never replies, and a button greyed out forever would lock the person in. An
* never replies, and a button grayed out forever would lock the person in. An
* uncollected send still blocks even then, because the server takes one at a
* time.
*/
@@ -665,7 +665,7 @@ export function dashNoteKind({ menu, hasMenu, onInitial, working }) {
* availability — but its folder still goes along on a Pathfinder or Plan
* launch, since the files may be reference docs.
*
* Returns { on, reason?, note?, next? } — `reason` is the one line a greyed card
* Returns { on, reason?, note?, next? } — `reason` is the one line a grayed card
* shows, `note` the one line a clickable card shows when there is something to
* know before launching it, `next` marks the state's natural step. `lookup` is
* stateFor unless a test hands in its own table.
@@ -681,7 +681,7 @@ export function cardAvailability(entry, scan, sel, lookup = stateFor) {
if (entry.skill === "plan2code-init") return hasAgents ? off(rule.greyed.default) : ON;
if (entry.skill === "plan2code-init-update") return hasAgents ? ON : off(rule.greyed.default);
if (entry.skill === "plan2code-git") {
// Never greyed: a clean tree still has branches to switch, pull and push.
// Never grayed: a clean tree still has branches to switch, pull and push.
if (scan && scan.isGit === false) return { on: true, note: GIT_INIT_NOTE };
if (scan && Number.isInteger(scan.pending) && scan.pending > 0) return { on: true, note: pendingNote(scan.pending) };
return ON;
+2 -2
View File
@@ -1,4 +1,4 @@
// Planny's wake-up on a freshly opened dashboard: he sits powered down centre
// Planny's wake-up on a freshly opened dashboard: he sits powered down center
// stage until the first click or key, gets nudged awake (he rocks side to side
// for one snore), then about five seconds of him powering on, then a glide
// into the rail as the menu comes in.
@@ -68,7 +68,7 @@ export function playWake({ stage, bot, target, skipEl, stir, onStart, onGlide, o
// between the two top-left corners and the scale is the width ratio.
// The target's own box, not its bounding rect: the rail's Planny is
// usually tilted mid-flight, and a tilted box measures wider than he
// is. Centred on the rect, which the tilt barely moves.
// is. Centered on the rect, which the tilt barely moves.
const from = bot.getBoundingClientRect();
const rect = target.getBoundingClientRect();
const w = target.clientWidth || rect.width;
+1 -1
View File
@@ -147,7 +147,7 @@ const ABOUT_HISTORY = 3;
*
* The tracker is `{ history, about }`; each entry and `about` are
* `{ kind, id, label }` (`about` may be null), in the exact shape POST /chat
* takes. An old `{ about, frozen, dropped }` tracker normalises to an empty
* takes. An old `{ about, frozen, dropped }` tracker normalizes to an empty
* history.
*/
export function nextAbout(prev, event) {
+2 -2
View File
@@ -12,7 +12,7 @@
// className, id, type, value, checked, disabled, textContent, placeholder,
// title, open, href, target, rel, tabIndex. Text runs are h.el("span", null, text).
//
// Every button, input and select is made through control(), which greys it
// Every button, input and select is made through control(), which grays it
// out whenever controlAllowed(mode, role) says no and stamps data-gate with
// its role; one disabled for a reason of the view's own also carries
// data-own. The guard test in scripts/test-web-console-git-board.mjs holds
@@ -64,7 +64,7 @@ function control(ctx, tag, className, label, { role = "action", onClick, onInput
return node;
}
// A copy button is a control like any other: greyed while busy.
// A copy button is a control like any other: grayed while busy.
function copy(ctx, text, cls, codeEl) {
const b = ctx.h.copyButton(text, cls, codeEl);
b.setAttribute("data-gate", "action");
+1 -1
View File
@@ -194,7 +194,7 @@ const button = (shown, enabled, label, title) => ({ shown, enabled: shown && ena
/**
* Every board button as `{ shown, enabled, label, title? }`. Pull is enabled
* only with an upstream to pull from; Push shows with an upstream, Publish
* without one. `busy` greys everything out but Done; an operation in
* without one. `busy` grays everything out but Done; an operation in
* progress hides everything but Done (its banner carries Abort / Continue).
*/
export function boardActions(git, { busy = false } = {}) {
+2 -2
View File
@@ -7,11 +7,11 @@
// that reads and writes the user's files and holds the session cookie. Script
// running here could post arbitrary answers back to the agent, which would then
// act on them with the agent's full tool permissions. And the markdown is only
// nominally agent-authored: in practice the agent is summarising a dependency
// nominally agent-authored: in practice the agent is summarizing a dependency
// README, a scraped page, a PR description, a log. Treat it as hostile.
//
// Building nodes rather than parsing a string makes injection structurally
// impossible instead of filtered, so there is nothing for a sanitiser bypass to
// impossible instead of filtered, so there is nothing for a sanitizer bypass to
// bypass. `html` tokens render as visible text, on purpose.
import { marked } from "./vendor/marked.esm.js";
+3 -3
View File
@@ -245,7 +245,7 @@ export function buildPager(item) {
// Once this question is answered, the step is the next unanswered one, not
// Send. Send lighting up the moment a single answer is staged pulls people
// into sending one question at a time, which is three round trips where the
// workflow wanted one. So the emphasis moves to whichever neighbour still
// workflow wanted one. So the emphasis moves to whichever neighbor still
// needs them, and Send goes quiet until nothing does.
const here = Boolean(page.local.staged[item.id]);
const nextT = open[at + 1];
@@ -257,7 +257,7 @@ export function buildPager(item) {
const leadNext = here && needs(nextT);
const leadPrev = here && !leadNext && needs(prevT);
// An end of the queue is an empty slot, not a disabled button. A greyed
// An end of the queue is an empty slot, not a disabled button. A grayed
// "Previous" pointing at nothing is a control that exists only to say no.
const mk = (target, back, lead) => {
if (!target) return el("span", "pager-slot");
@@ -1348,7 +1348,7 @@ function buildList(card, item, staged) {
// over the array from render time. A reorder replaces that array, so a stale
// closure would quietly undo the reorder the next time a rename committed.
// A name still being typed counts too: the tool buttons below keep the
// field's focus (their mousedown is cancelled), so its `change` has not
// field's focus (their mousedown is canceled), so its `change` has not
// fired yet when they act, and the re-render would otherwise drop it.
const ul = el("ul", "rows");
const baseRows = () => {
+2 -2
View File
@@ -225,7 +225,7 @@ export function renderDashboard(main) {
if (!page.local.launching && !page.launchScoping && wantScope !== page.scopeMine) hooks.syncWorkspaceScope();
// "Unavailable" is the scan's verdict for the selected spec, not the
// momentary greying while a launch is in flight or the server is away, so
// momentary graying while a launch is in flight or the server is away, so
// cards never blink out of the menu mid-handoff.
const hide = looks.hideUnavailable;
const sel = selSpec();
@@ -640,7 +640,7 @@ function dashCard(entry, menu) {
const presentation = cardPresentation(entry, scan(), selSpec(), menu);
// The agent's `recommend` and detail describe the initially selected spec.
// Other picker choices derive both from the scan, so stale context never
// follows a person to a different spec or to "start from scratch". A greyed
// follows a person to a different spec or to "start from scratch". A grayed
// recommendation also yields to the selected spec's actual next step.
const going = page.local.launching && (page.local.launching.skill === entry.skill || page.local.launching.skill === entry.review);
const b = el(
+1 -1
View File
@@ -333,7 +333,7 @@ async function reorder(order, focus) {
}
// A tab is no longer there (deleted here, or from another page): off the bar,
// its unsaved text dropped without a save, and its neighbour on screen.
// its unsaved text dropped without a save, and its neighbor on screen.
async function gone(id, index = tabs.findIndex((t) => t.id === id), announce = true) {
const here = id === activeId;
if (here || id === saveTab) discard();
+1 -1
View File
@@ -21,7 +21,7 @@ const LAUNCH_QUIPS = [
let launchTicker = null;
// Planny flies centre stage: the same drawing as the dock's, cloned so the
// Planny flies center stage: the same drawing as the dock's, cloned so the
// markup stays the single source of him, and the same sky the dock fills.
function flightStage() {
const stage = el("div", "launch-stage");
+1 -1
View File
@@ -33,7 +33,7 @@
// always on whatever is picked; null for no card
// marksNext the card can be a state's natural next step, so its answer
// always says whether it is (`next`)
// greyed its greyed reasons: `default`, plus one per state whose
// greyed (the field keeps its old spelling) its grayed reasons: `default`, plus one per state whose
// wording differs, and `finished` for any finished state
// (spec-states.js); Init and Init update use `default` for the
// AGENTS.md check, which is a rule on the scan, not on the spec
+2 -2
View File
@@ -2,7 +2,7 @@
//
// Each spec state the dashboard scan can report; data only, imported by the
// page and by Node. In the order the scan's SPEC_STATES lists them. Which
// cards a state lights or greys lives on the skill list (skills.js), and how
// cards a state lights or grays lives on the skill list (skills.js), and how
// a folder's files map to a state stays with the scan (classifySpec in
// scan.mjs). No imports and no DOM access: nothing runs at load but building
// the frozen data.
@@ -14,7 +14,7 @@
// null when it has none
// finished the work is done: the spec is hidden while unavailable
// workflows are, never the picker's default, deleted after one
// confirm, and greyed with the card's `finished` reason
// confirm, and grayed with the card's `finished` reason
// (skills.js) on the cards that would otherwise take it
function state(label, next, finished = false) {
+4 -4
View File
@@ -51,7 +51,7 @@ export const TEMPLATES = Object.freeze({
"The engineers who will build and review it.",
"",
"## What it should pin down",
"The behaviour, the parts of the code it touches, the interfaces between them, the simpler options we're turning down, and how we'll know it works.",
"The behavior, the parts of the code it touches, the interfaces between them, the simpler options we're turning down, and how we'll know it works.",
"",
"## Out of scope",
"[what this deliberately won't do]",
@@ -181,7 +181,7 @@ export const TEMPLATES = Object.freeze({
"[the screen or component]",
"",
"## What looks or feels off",
"[spacing, alignment, colour, states, small screens]",
"[spacing, alignment, color, states, small screens]",
"",
"## What good looks like",
"[a reference, screenshot or description]",
@@ -204,7 +204,7 @@ export const TEMPLATES = Object.freeze({
]),
"add-a-test": template("add-a-test", "Add a test", [
"## Add a test",
"[the function, behaviour or bug]",
"[the function, behavior or bug]",
"",
"## Cases to cover",
"- [the normal case]",
@@ -234,7 +234,7 @@ export const TEMPLATES = Object.freeze({
"## Why now",
"[what the current shape makes hard]",
"",
"## Behaviour that must not change",
"## Behavior that must not change",
"[the public API, outputs or tests that must stay the same]",
"",
"## Done when",
+1 -1
View File
@@ -33,7 +33,7 @@
padding: 18px 22px;
display: flex; flex-direction: column; gap: 10px;
}
/* An empty conversation's starter questions, centred where the list is empty. */
/* An empty conversation's starter questions, centered where the list is empty. */
.ask-starters { display: flex; flex-direction: column; gap: 6px; margin: auto 0; width: 100%; max-width: 520px; align-self: center; }
.ask-starters-lead { color: var(--ink-3); font-size: 13.5px; margin: 0 0 4px; text-align: center; }
.ask-starter {
+6 -6
View File
@@ -26,7 +26,7 @@
font-size: 14px;
}
.dash-nudge-text { flex: 1 1 16em; }
/* The session meter at red: the same slot, in the careful colour. */
/* The session meter at red: the same slot, in the careful color. */
.dash-nudge.meter-banner {
background: var(--warn-soft);
border-color: var(--warn);
@@ -57,7 +57,7 @@
cursor: pointer;
}
.update-banner-open:hover { text-decoration: underline; }
/* Pinned to the right edge, out of the flow, so the label centres on the
/* Pinned to the right edge, out of the flow, so the label centers on the
whole banner rather than on what the × leaves of it. */
.update-banner-dismiss {
position: absolute;
@@ -239,7 +239,7 @@
.dash-card-go { color: var(--accent); font-weight: 700; transition: transform 0.15s ease; }
.dash-card:hover:not(:disabled) .dash-card-go { transform: translateX(3px); }
/* The reason a card is off. The card greys via :disabled; this line is why,
/* The reason a card is off. The card grays via :disabled; this line is why,
so the menu teaches the pipeline instead of just refusing clicks. */
.dash-card-off { font-size: 12px; color: var(--ink-3); font-style: italic; }
@@ -276,7 +276,7 @@
}
.spec-chip:not(.is-sel) .spec-chip-state { color: var(--ink-3); }
.spec-chip-detail { font-size: 11.5px; color: var(--ink-3); }
/* A handoff in the picker: the same lozenge, dashed, in the stage colour. */
/* A handoff in the picker: the same lozenge, dashed, in the stage color. */
.spec-chip.is-handoff { border-style: dashed; }
.spec-chip.is-handoff .spec-chip-state, .spec-chip.is-handoff:not(.is-sel) .spec-chip-state { color: var(--stage); }
.spec-chip.is-handoff.is-sel { border-style: solid; border-color: var(--stage); }
@@ -379,7 +379,7 @@
/* ------------------------------------------------- dashboard confirm */
/* The beat between "I clicked a card" and "it is running": what the pick is,
what it will do, and a START that means it. Narrower than the menu, centred
what it will do, and a START that means it. Narrower than the menu, centered
like the launching pane it precedes. */
.dash-confirm {
max-width: 560px;
@@ -448,7 +448,7 @@
mask-image: radial-gradient(120% 100% at 50% 40%, #000 42%, transparent 78%);
}
.launch-sky { opacity: 0.9; }
/* The dock only animates its stars while .is-flying; centre stage they are
/* The dock only animates its stars while .is-flying; center stage they are
the show, so the flight runs unconditionally. */
.launch-stage .sky .star { animation: star-fly var(--dur, 5s) linear var(--delay, 0s) infinite; }
+2 -2
View File
@@ -91,8 +91,8 @@
.presets-label { font-size: 12.5px; color: var(--ink-3); }
/* "Before you close this": three rows on every finished screen. The icon sits
in a coloured circle and the label says the same thing, so no meaning rests
on colour alone. */
in a colored circle and the label says the same thing, so no meaning rests
on color alone. */
.handoff-guide {
margin: 20px 0 0; padding: 14px 16px;
background: var(--panel-2); border: 1px solid var(--rule-2); border-radius: var(--radius);
+1 -1
View File
@@ -25,7 +25,7 @@
it does not stretch), so a note box grows with what is typed instead, where
the browser can, rather than scrolling inside a 96px box. */
.git-cards > .card textarea { field-sizing: content; max-height: 50vh; }
/* The card and the pager centre themselves with auto inline margins, and a
/* The card and the pager center themselves with auto inline margins, and a
grid item with auto margins shrinks to its content, so a short confirm sat
narrow in the middle of the board. In the slot both fill the board's width
instead; the slot's gap spaces them. */
+1 -1
View File
@@ -144,7 +144,7 @@
.help-mood-bot { width: 40px; height: 56px; }
.help-mood span { font-size: 12.5px; color: var(--ink-2); text-align: center; }
/* The travelling highlight on the flow diagrams: only on the visible panel,
/* The traveling highlight on the flow diagrams: only on the visible panel,
only while the dialog is open, and only when the system allows motion.
Otherwise the dashes simply sit still. */
@media (prefers-reduced-motion: no-preference) {
+1 -1
View File
@@ -101,7 +101,7 @@
/* The full-screen preview: the whole viewport, the picture contained in it,
on a near-black backdrop in both themes (a picture is judged against dark,
whatever the page's theme), so its colours are fixed, not tokens. */
whatever the page's theme), so its colors are fixed, not tokens. */
.modal.notepad-preview {
inset: 0;
width: 100vw;
+5 -5
View File
@@ -153,7 +153,7 @@
@keyframes foot-step-a { 0%, 100% { transform: translateY(0); } 50% { transform: translateY(-1.1px); } }
@keyframes foot-step-b { 0%, 100% { transform: translateY(-1.1px); } 50% { transform: translateY(0); } }
/* Something for you to do: star lit in the highlight colour, a wave. */
/* Something for you to do: star lit in the highlight color, a wave. */
.planny.is-point { animation: planny-lean 2.6s ease-in-out infinite; }
.planny.is-point .eye { fill: var(--accent); }
@@ -167,7 +167,7 @@
/* The server is up, but nothing is answering at the other end of it. Not the
faded, eye-shut `gone` look: this page is working perfectly, and the thing
that is not is somewhere else. Grey, still, and no arms: he has nothing to
that is not is somewhere else. Gray, still, and no arms: he has nothing to
do with them until someone answers. */
.planny.is-adrift .eye { fill: var(--ink-3); animation: none; }
.planny.is-adrift .smile { opacity: 0.6; }
@@ -178,7 +178,7 @@
.planny.is-done .eye { fill: var(--ok); animation: none; }
.planny.is-done .smile { stroke-width: 1.5; }
/* No server: faded, eye shut in the warning colour, arms hanging. */
/* No server: faded, eye shut in the warning color, arms hanging. */
.planny.is-gone { opacity: 0.5; }
.planny.is-gone .eye { fill: var(--warn); animation: none; transform: scaleY(0.12); }
@@ -293,13 +293,13 @@
/* ------------------------------------------------------------ wake-up
A freshly opened dashboard: Planny powers on centre stage, then glides
A freshly opened dashboard: Planny powers on center stage, then glides
into the rail (boot.js). Each beat is a keyframe on a delay under
`.booting`, one class for the whole run; the glide's target depends on
where the rail sits, so boot.js hands it over as --wake-glide. The layer
takes clicks so none lands on a card underneath while he wakes. */
.wake { position: fixed; inset: 0; z-index: 45; pointer-events: auto; }
/* Solid page colour behind the sleeping bot, following light/dark via --bg. */
/* Solid page color behind the sleeping bot, following light/dark via --bg. */
.wake::before { content: ""; position: absolute; inset: 0; background: var(--bg); }
.wake[hidden] { display: none; }
.wake-bot {
+6 -6
View File
@@ -2,7 +2,7 @@
/* ------------------------------------------------------------- banner */
/* A pill floated over the footer, centred on the bar. It used to be the top
/* A pill floated over the footer, centered on the bar. It used to be the top
grid row, and every time it appeared it pushed the whole page down a track;
overlaying it means the message lands without the layout moving under the
reader's cursor. It covers the footer's middle while it is up, which is
@@ -100,8 +100,8 @@
.ident { display: flex; align-items: baseline; gap: 12px; min-width: 0; }
/* The session meter: a ring that fills with the points and a few words, in
the level's colour. Green, amber and red are the page's own done / staged /
careful colours, so both themes are covered by the variables. */
the level's color. Green, amber and red are the page's own done / staged /
careful colors, so both themes are covered by the variables. */
.meter-slot { position: relative; flex: none; align-self: center; }
.meter-pill {
--m: var(--ok);
@@ -478,8 +478,8 @@ h1 {
/* ------------------------------------------------------------- footer */
/* Three columns: summary, where, actions. Equal side tracks keep the middle
centred on the bar, and because they are tracks rather than an overlay, a
long summary wraps and a wide actions block nudges the centre over instead
centered on the bar, and because they are tracks rather than an overlay, a
long summary wraps and a wide actions block nudges the center over instead
of either running underneath it. The middle track gives way first: it can
shrink to an ellipsis, the summary and Send never do. */
.footer {
@@ -490,7 +490,7 @@ h1 {
}
.footer-summary { min-width: 200px; font-size: 13.5px; color: var(--ink-2); }
.footer-summary strong { color: var(--ink); }
/* Where this session is running: the workspace label, centred on the bar. A
/* Where this session is running: the workspace label, centered on the bar. A
click opens the Workspace dialog. The notification pill sits over the same
spot and covers it while it shows. */
.footer-where {
+2 -2
View File
@@ -1,4 +1,4 @@
/* tokens.css: Colours, type, sizes and the light and dark themes: the variables every other file reads. */
/* tokens.css: Colors, type, sizes and the light and dark themes: the variables every other file reads. */
/* Plan2Code Console.
Light by default, dark when the system asks. No external fonts: the page must
@@ -24,7 +24,7 @@
--warn: #9c3327;
--warn-soft: #fbe7e3;
--focus: #1f6feb;
/* Rank colours for low / mid / high badges (a helper's strength and effort). */
/* Rank colors for low / mid / high badges (a helper's strength and effort). */
--lvl-1: #23716a;
--lvl-1-soft: #e1f1ee;
--lvl-2: #9a6a12;
+3 -3
View File
@@ -11,7 +11,7 @@ import { SKILLS, subagentsFor } from "./skills.js";
// The skills that offer the switch, each with its instruction: an entry's
// `subagents` in skills.js is the one place a skill opts in (FR-1). Wording is
// behaviour-level and names no harness tool, so any agent can follow it or
// behavior-level and names no harness tool, so any agent can follow it or
// harmlessly ignore it.
export const SUBAGENT_WORKFLOWS = Object.freeze(
Object.fromEntries(
@@ -222,7 +222,7 @@ export function switchLabel(frame) {
// working-alone marker, so the note only draws when no helper was ever
// reported. A result shows once the helper ended, and a reported strength or
// effort as one line ("Standard, medium effort") plus a badge each, ranked 1-3
// so the page can colour them (0 for the session's own model, which has no rank).
// so the page can color them (0 for the session's own model, which has no rank).
export function helperRows(helpers) {
const list = Array.isArray(helpers) ? helpers.filter(isPlainObject) : [];
const real = list.filter((h) => h.alone !== true);
@@ -248,7 +248,7 @@ export function helperRows(helpers) {
}
const HELPER_STRENGTH_WORDS = Object.freeze({ light: "Light", standard: "Standard", strongest: "Strongest", inherit: "Session model" });
// Each value's rank for its badge colour; the session's own model has none.
// Each value's rank for its badge color; the session's own model has none.
const HELPER_STRENGTH_LEVELS = Object.freeze({ light: 1, standard: 2, strongest: 3, inherit: 0 });
const HELPER_EFFORT_LEVELS = Object.freeze({ low: 1, medium: 2, high: 3 });
+4 -4
View File
@@ -54,7 +54,7 @@ import { handle } from "./routes.mjs";
import { checkForUpdate } from "./update-check.mjs";
const args = parseArgs(process.argv.slice(2));
// Canonicalise before anything derives a path from it: a session dir reached
// Canonicalize before anything derives a path from it: a session dir reached
// through a junction or a subst'd drive is watched under the wrong spelling,
// which is the libuv assert described below. The native realpath resolves
// those AND expands 8.3 short names, which lets the watcher run in a TEMP
@@ -251,7 +251,7 @@ const subagents = serverSubagents({ dir: DIR, worktree: sessionWorktree });
// process's whole life (the env var that says so is set once, at spawn), so
// read once rather than on every frame. The page uses it to drop advice that
// only makes sense in a plain terminal (a command to copy into a new
// conversation) in favour of the app's own Restart and Update skills buttons.
// conversation) in favor of the app's own Restart and Update skills buttons.
const IN_APP = Boolean(inAppSignal());
// What the page needs to draw itself, in the shape of the SSE state frame.
@@ -525,12 +525,12 @@ setInterval(() => {
// This is the mechanism, not a nicety.
//
// Windows has no real SIGTERM, Node only synthesises SIGINT for Ctrl+C on an
// Windows has no real SIGTERM, Node only synthesizes SIGINT for Ctrl+C on an
// attached console, and this process is detached with no console at all.
// taskkill /F and Task Manager give zero cleanup opportunity. A Job Object with
// KILL_ON_JOB_CLOSE would be the proper fix and needs native code, which is out
// under zero-dependencies. So the only thing that reliably stops an orphan is
// the server deciding to stop. Do not "optimise" this away.
// the server deciding to stop. Do not "optimize" this away.
setInterval(() => {
const idle = Date.now() - lastContact;
// Answers nobody has collected yet keep the server up (bounded by MAX_LIFE_MS):
+1 -1
View File
@@ -1,4 +1,4 @@
// Plan2Code Web Console - serving the page's own files: the allow-list, types, caching and the accent colours.
// Plan2Code Web Console - serving the page's own files: the allow-list, types, caching and the accent colors.
import fs from "node:fs";
import path from "node:path";