From 7d54941b75ed138707327622b1da45b5d11dfa09 Mon Sep 17 00:00:00 2001 From: Justin Parker Date: Sun, 4 Oct 2026 12:17:05 -0700 Subject: [PATCH] Port upstream skill scripts into v2.4.1: deterministic workflow steps run as Node scripts beside each SKILL.md (specs, pathfinder, feedback payload, commit message, review scope, agent files, handoff path) with tests, the prompt limit rises to 20,000 chars, upstream review fixes are folded in (linked agent files never overwrite AGENTS.md, review stops with no base, paste-safe commit commands, Pathfinder number high-water mark and dry runs), and web console workspace folders are remembered per project and spec, with Finalize forgetting an archived spec's list AI Assisted --- .agents-docs/AGENTS-architecture.md | 45 +- .agents-docs/AGENTS-code-style.md | 10 +- .agents-docs/AGENTS-development-commands.md | 5 +- .claude/skills/sync-repo/sync-repo.enc | 2 +- .gitattributes | 4 +- .readme/web-console-design.md | 2 +- .readme/web-console.md | 16 +- AGENTS.md | 9 +- CHANGELOG.md | 22 + install.js | 64 + package.json | 2 +- plan2code-metrics/README.md | 2 +- plan2code-metrics/src/applier.ts | 2 +- plan2code-metrics/src/improver.test.ts | 6 +- plan2code-metrics/src/improver.ts | 2 +- plan2code-metrics/src/prompts/improve.md | 4 +- scripts/skill-script-helpers.mjs | 61 + scripts/test-script-finalize.mjs | 174 +++ scripts/test-script-handoff.mjs | 55 + scripts/test-script-pathfinder.mjs | 545 +++++++ scripts/test-skill-scripts.mjs | 625 ++++++++ scripts/test-web-console.mjs | 106 +- scripts/validate-char-count.js | 2 +- skills/plan2code-0-pathfinder/SKILL.md | 55 +- .../references/brief.md | 34 +- .../references/chart.md | 13 +- .../references/github-issues.md | 2 + .../references/handoff.md | 32 +- .../references/questions.md | 4 +- .../references/resolve.md | 27 +- .../references/trail.md | 222 +-- .../references/web-console/console.md | 15 +- .../references/web-console/console.mjs | 32 +- .../references/web-console/lib.mjs | 133 +- .../references/web-console/public/app.css | 3 + .../references/web-console/public/app.js | 36 + .../references/web-console/public/index.html | 32 +- .../references/web-console/server.mjs | 113 +- .../references/web-console/version.json | 2 +- .../plan2code-0-pathfinder/scripts/common.mjs | 247 ++++ .../scripts/pathfinder.mjs | 1294 +++++++++++++++++ .../scripts/version.json | 22 + skills/plan2code-1-plan/SKILL.md | 2 +- .../references/web-console/console.md | 15 +- .../references/web-console/console.mjs | 32 +- .../references/web-console/lib.mjs | 133 +- .../references/web-console/public/app.css | 3 + .../references/web-console/public/app.js | 36 + .../references/web-console/public/index.html | 32 +- .../references/web-console/server.mjs | 113 +- .../references/web-console/version.json | 2 +- skills/plan2code-1-plan/scripts/common.mjs | 247 ++++ skills/plan2code-1-plan/scripts/specs.mjs | 676 +++++++++ skills/plan2code-1-plan/scripts/version.json | 22 + skills/plan2code-1b-revise-plan/SKILL.md | 25 +- .../references/web-console/console.md | 15 +- .../references/web-console/console.mjs | 32 +- .../references/web-console/lib.mjs | 133 +- .../references/web-console/public/app.css | 3 + .../references/web-console/public/app.js | 36 + .../references/web-console/public/index.html | 32 +- .../references/web-console/server.mjs | 113 +- .../references/web-console/version.json | 2 +- .../scripts/common.mjs | 247 ++++ .../scripts/specs.mjs | 676 +++++++++ .../scripts/version.json | 22 + skills/plan2code-2-document/SKILL.md | 23 +- .../references/web-console/console.md | 15 +- .../references/web-console/console.mjs | 32 +- .../references/web-console/lib.mjs | 133 +- .../references/web-console/public/app.css | 3 + .../references/web-console/public/app.js | 36 + .../references/web-console/public/index.html | 32 +- .../references/web-console/server.mjs | 113 +- .../references/web-console/version.json | 2 +- .../plan2code-2-document/scripts/common.mjs | 247 ++++ skills/plan2code-2-document/scripts/specs.mjs | 676 +++++++++ .../plan2code-2-document/scripts/version.json | 22 + skills/plan2code-3-implement-review/SKILL.md | 2 +- .../references/implement.md | 60 +- .../references/review.md | 20 +- .../references/session-end.md | 2 +- .../references/web-console/console.md | 15 +- .../references/web-console/console.mjs | 32 +- .../references/web-console/lib.mjs | 133 +- .../references/web-console/public/app.css | 3 + .../references/web-console/public/app.js | 36 + .../references/web-console/public/index.html | 32 +- .../references/web-console/server.mjs | 113 +- .../references/web-console/version.json | 2 +- .../scripts/commit-msg.mjs | 120 ++ .../scripts/common.mjs | 247 ++++ .../scripts/review-scope.mjs | 138 ++ .../scripts/specs.mjs | 676 +++++++++ .../scripts/version.json | 22 + skills/plan2code-3-implement/SKILL.md | 60 +- .../references/review.md | 20 +- .../references/session-end.md | 2 +- .../references/web-console/console.md | 15 +- .../references/web-console/console.mjs | 32 +- .../references/web-console/lib.mjs | 133 +- .../references/web-console/public/app.css | 3 + .../references/web-console/public/app.js | 36 + .../references/web-console/public/index.html | 32 +- .../references/web-console/server.mjs | 113 +- .../references/web-console/version.json | 2 +- .../scripts/commit-msg.mjs | 120 ++ .../plan2code-3-implement/scripts/common.mjs | 247 ++++ .../scripts/review-scope.mjs | 138 ++ .../plan2code-3-implement/scripts/specs.mjs | 676 +++++++++ .../scripts/version.json | 22 + skills/plan2code-4-finalize/SKILL.md | 54 +- .../community-feedback-submission.md | 86 +- .../references/web-console/console.md | 15 +- .../references/web-console/console.mjs | 32 +- .../references/web-console/lib.mjs | 133 +- .../references/web-console/public/app.css | 3 + .../references/web-console/public/app.js | 36 + .../references/web-console/public/index.html | 32 +- .../references/web-console/server.mjs | 113 +- .../references/web-console/version.json | 2 +- .../scripts/commit-msg.mjs | 120 ++ .../plan2code-4-finalize/scripts/common.mjs | 247 ++++ .../scripts/feedback-payload.mjs | 379 +++++ skills/plan2code-4-finalize/scripts/specs.mjs | 676 +++++++++ .../plan2code-4-finalize/scripts/version.json | 22 + skills/plan2code-handoff/SKILL.md | 43 +- .../references/web-console/console.md | 15 +- .../references/web-console/console.mjs | 32 +- .../references/web-console/lib.mjs | 133 +- .../references/web-console/public/app.css | 3 + .../references/web-console/public/app.js | 36 + .../references/web-console/public/index.html | 32 +- .../references/web-console/server.mjs | 113 +- .../references/web-console/version.json | 2 +- skills/plan2code-handoff/scripts/common.mjs | 247 ++++ .../scripts/handoff-path.mjs | 107 ++ skills/plan2code-handoff/scripts/specs.mjs | 676 +++++++++ skills/plan2code-handoff/scripts/version.json | 22 + skills/plan2code-init-update/SKILL.md | 47 +- .../references/ai-agent-file-sync.md | 77 +- .../references/web-console/console.md | 15 +- .../references/web-console/console.mjs | 32 +- .../references/web-console/lib.mjs | 133 +- .../references/web-console/public/app.css | 3 + .../references/web-console/public/app.js | 36 + .../references/web-console/public/index.html | 32 +- .../references/web-console/server.mjs | 113 +- .../references/web-console/version.json | 2 +- .../scripts/agent-files.mjs | 224 +++ .../scripts/agents-md.mjs | 157 ++ .../scripts/commit-msg.mjs | 120 ++ .../plan2code-init-update/scripts/common.mjs | 247 ++++ .../scripts/version.json | 22 + skills/plan2code-init/SKILL.md | 81 +- .../references/web-console/console.md | 15 +- .../references/web-console/console.mjs | 32 +- .../references/web-console/lib.mjs | 133 +- .../references/web-console/public/app.css | 3 + .../references/web-console/public/app.js | 36 + .../references/web-console/public/index.html | 32 +- .../references/web-console/server.mjs | 113 +- .../references/web-console/version.json | 2 +- skills/plan2code-init/scripts/agent-files.mjs | 224 +++ skills/plan2code-init/scripts/agents-md.mjs | 157 ++ skills/plan2code-init/scripts/common.mjs | 247 ++++ skills/plan2code-init/scripts/version.json | 22 + .../plan2code-quick-task/references/review.md | 20 +- .../references/session-end.md | 2 +- .../references/web-console/console.md | 15 +- .../references/web-console/console.mjs | 32 +- .../references/web-console/lib.mjs | 133 +- .../references/web-console/public/app.css | 3 + .../references/web-console/public/app.js | 36 + .../references/web-console/public/index.html | 32 +- .../references/web-console/server.mjs | 113 +- .../references/web-console/version.json | 2 +- .../scripts/commit-msg.mjs | 120 ++ .../plan2code-quick-task/scripts/common.mjs | 247 ++++ .../scripts/review-scope.mjs | 138 ++ skills/plan2code-quick-task/scripts/specs.mjs | 676 +++++++++ .../plan2code-quick-task/scripts/version.json | 22 + skills/plan2code-review/SKILL.md | 20 +- .../references/session-end.md | 2 +- .../references/web-console/console.md | 15 +- .../references/web-console/console.mjs | 32 +- .../references/web-console/lib.mjs | 133 +- .../references/web-console/public/app.css | 3 + .../references/web-console/public/app.js | 36 + .../references/web-console/public/index.html | 32 +- .../references/web-console/server.mjs | 113 +- .../references/web-console/version.json | 2 +- .../plan2code-review/scripts/commit-msg.mjs | 120 ++ skills/plan2code-review/scripts/common.mjs | 247 ++++ .../plan2code-review/scripts/review-scope.mjs | 138 ++ skills/plan2code-review/scripts/specs.mjs | 676 +++++++++ skills/plan2code-review/scripts/version.json | 22 + .../references/web-console/console.md | 15 +- .../references/web-console/console.mjs | 32 +- .../plan2code/references/web-console/lib.mjs | 133 +- .../references/web-console/public/app.css | 3 + .../references/web-console/public/app.js | 36 + .../references/web-console/public/index.html | 32 +- .../references/web-console/server.mjs | 113 +- .../references/web-console/version.json | 2 +- .../brief.md | 34 +- .../chart.md | 13 +- .../github-issues.md | 2 + .../handoff.md | 32 +- .../questions.md | 4 +- .../resolve.md | 27 +- .../trail.md | 222 +-- .../pathfinder.mjs | 1294 +++++++++++++++++ src/plan2code-0-pathfinder.md | 55 +- src/plan2code-1-plan.md | 2 +- src/plan2code-1b-revise-plan.md | 25 +- src/plan2code-2-document.md | 23 +- src/plan2code-3-implement-review.md | 2 +- src/plan2code-3-implement.md | 60 +- .../community-feedback-submission.md | 86 +- .../feedback-payload.mjs | 379 +++++ src/plan2code-4-finalize.md | 54 +- .../handoff-path.mjs | 107 ++ src/plan2code-handoff.md | 43 +- .../ai-agent-file-sync.md | 77 +- src/plan2code-init-update.md | 47 +- src/plan2code-init.md | 81 +- .../session-end.md | 2 +- src/plan2code-review.md | 20 +- src/skill-scripts/agent-files.mjs | 224 +++ src/skill-scripts/agents-md.mjs | 157 ++ src/skill-scripts/commit-msg.mjs | 120 ++ src/skill-scripts/common.mjs | 247 ++++ src/skill-scripts/review-scope.mjs | 138 ++ src/skill-scripts/specs.mjs | 676 +++++++++ src/web-console/console.md | 15 +- src/web-console/console.mjs | 32 +- src/web-console/lib.mjs | 133 +- src/web-console/public/app.css | 3 + src/web-console/public/app.js | 36 + src/web-console/public/index.html | 32 +- src/web-console/server.mjs | 113 +- version.json | 2 +- 243 files changed, 23698 insertions(+), 1607 deletions(-) create mode 100644 scripts/skill-script-helpers.mjs create mode 100644 scripts/test-script-finalize.mjs create mode 100644 scripts/test-script-handoff.mjs create mode 100644 scripts/test-script-pathfinder.mjs create mode 100644 scripts/test-skill-scripts.mjs create mode 100644 skills/plan2code-0-pathfinder/scripts/common.mjs create mode 100644 skills/plan2code-0-pathfinder/scripts/pathfinder.mjs create mode 100644 skills/plan2code-0-pathfinder/scripts/version.json create mode 100644 skills/plan2code-1-plan/scripts/common.mjs create mode 100644 skills/plan2code-1-plan/scripts/specs.mjs create mode 100644 skills/plan2code-1-plan/scripts/version.json create mode 100644 skills/plan2code-1b-revise-plan/scripts/common.mjs create mode 100644 skills/plan2code-1b-revise-plan/scripts/specs.mjs create mode 100644 skills/plan2code-1b-revise-plan/scripts/version.json create mode 100644 skills/plan2code-2-document/scripts/common.mjs create mode 100644 skills/plan2code-2-document/scripts/specs.mjs create mode 100644 skills/plan2code-2-document/scripts/version.json create mode 100644 skills/plan2code-3-implement-review/scripts/commit-msg.mjs create mode 100644 skills/plan2code-3-implement-review/scripts/common.mjs create mode 100644 skills/plan2code-3-implement-review/scripts/review-scope.mjs create mode 100644 skills/plan2code-3-implement-review/scripts/specs.mjs create mode 100644 skills/plan2code-3-implement-review/scripts/version.json create mode 100644 skills/plan2code-3-implement/scripts/commit-msg.mjs create mode 100644 skills/plan2code-3-implement/scripts/common.mjs create mode 100644 skills/plan2code-3-implement/scripts/review-scope.mjs create mode 100644 skills/plan2code-3-implement/scripts/specs.mjs create mode 100644 skills/plan2code-3-implement/scripts/version.json create mode 100644 skills/plan2code-4-finalize/scripts/commit-msg.mjs create mode 100644 skills/plan2code-4-finalize/scripts/common.mjs create mode 100644 skills/plan2code-4-finalize/scripts/feedback-payload.mjs create mode 100644 skills/plan2code-4-finalize/scripts/specs.mjs create mode 100644 skills/plan2code-4-finalize/scripts/version.json create mode 100644 skills/plan2code-handoff/scripts/common.mjs create mode 100644 skills/plan2code-handoff/scripts/handoff-path.mjs create mode 100644 skills/plan2code-handoff/scripts/specs.mjs create mode 100644 skills/plan2code-handoff/scripts/version.json create mode 100644 skills/plan2code-init-update/scripts/agent-files.mjs create mode 100644 skills/plan2code-init-update/scripts/agents-md.mjs create mode 100644 skills/plan2code-init-update/scripts/commit-msg.mjs create mode 100644 skills/plan2code-init-update/scripts/common.mjs create mode 100644 skills/plan2code-init-update/scripts/version.json create mode 100644 skills/plan2code-init/scripts/agent-files.mjs create mode 100644 skills/plan2code-init/scripts/agents-md.mjs create mode 100644 skills/plan2code-init/scripts/common.mjs create mode 100644 skills/plan2code-init/scripts/version.json create mode 100644 skills/plan2code-quick-task/scripts/commit-msg.mjs create mode 100644 skills/plan2code-quick-task/scripts/common.mjs create mode 100644 skills/plan2code-quick-task/scripts/review-scope.mjs create mode 100644 skills/plan2code-quick-task/scripts/specs.mjs create mode 100644 skills/plan2code-quick-task/scripts/version.json create mode 100644 skills/plan2code-review/scripts/commit-msg.mjs create mode 100644 skills/plan2code-review/scripts/common.mjs create mode 100644 skills/plan2code-review/scripts/review-scope.mjs create mode 100644 skills/plan2code-review/scripts/specs.mjs create mode 100644 skills/plan2code-review/scripts/version.json create mode 100644 src/plan2code-0-pathfinder-scripts/pathfinder.mjs create mode 100644 src/plan2code-4-finalize-scripts/feedback-payload.mjs create mode 100644 src/plan2code-handoff-scripts/handoff-path.mjs create mode 100644 src/skill-scripts/agent-files.mjs create mode 100644 src/skill-scripts/agents-md.mjs create mode 100644 src/skill-scripts/commit-msg.mjs create mode 100644 src/skill-scripts/common.mjs create mode 100644 src/skill-scripts/review-scope.mjs create mode 100644 src/skill-scripts/specs.mjs diff --git a/.agents-docs/AGENTS-architecture.md b/.agents-docs/AGENTS-architecture.md index 0663c3a..d56cf73 100644 --- a/.agents-docs/AGENTS-architecture.md +++ b/.agents-docs/AGENTS-architecture.md @@ -51,9 +51,10 @@ plan2code/ │ ├── parse-check.mjs # Imports every shipped browser module as real ESM │ ├── screenshots/ # JSON payloads posted per shot (`ask` reuses `question.json`; `finish` follows `signoff.json`) │ ├── test-web-console.mjs, test-launcher.mjs # node --test suites +│ ├── test-skill-scripts.mjs, test-script-.mjs, skill-script-helpers.mjs # Skill script suites and fixtures │ └── validate-char-count.js # Pre-commit character count validator ├── skills/ # Committed build artifact — one Agent Skill per src/ prompt -│ └── plan2code-/ # SKILL.md plus references/ where present +│ └── plan2code-/ # SKILL.md plus references/ and scripts/ where present │ # Generated by npm run build:skills; consumed by skills add ├── .husky/ # Git hooks (husky) │ └── pre-commit # Runs character count validation @@ -80,7 +81,7 @@ plan2code/ | `install.js` | Interactive installer — builds `skills/` from `src/`, then delegates installation to the skills CLI | | `src/plan2code-*.md` | Source workflow prompts (the "source of truth") | | `skills/` | Generated Agent Skills committed for installation and drift verification | -| `scripts/validate-char-count.js` | Pre-commit validator ensuring all source prompts ≤ 11,500 chars | +| `scripts/validate-char-count.js` | Pre-commit validator ensuring all source prompts ≤ 20,000 chars | | `version.json` | Version metadata (name, version, description) | | `QUICK-REFERENCE.md` | User quick-reference card | | `src/statusline-claude/` | Claude CLI status bar (see Status Line below) | @@ -118,13 +119,39 @@ Examples: ## Reference Files -Some workflows use companion reference files for depth that exceeds the 11.5k char limit. The orchestrator (main workflow file) loads them via `Read` directives during execution. +Some workflows use companion reference files for depth that does not need to load on every invocation. The orchestrator (main workflow file) loads them via `Read` directives during execution. **Pattern:** `src/-references/` (e.g., `plan2code-review-references/`) **How the installer handles them:** the directory is copied verbatim to `skills//references/`, so `Read references/.md` resolves consistently for every agent. There is one output format, with no flat-file sibling directory or path rewrite. -The review workflow pioneered this pattern (`verification-protocol`, `dimensions`, `false-positives`, `session-end`); the init-update workflow also uses it (`ai-agent-file-sync` for its Step 7), `plan2code-4-finalize.md` uses it for STEP 6.5 (`community-feedback-submission`), and `plan2code-0-pathfinder.md` leans on it hardest (`brief`, `chart`, `github-issues`, `grilling`, `questions`, `resolve`, `handoff`, `trail` — the orchestrator is a dispatcher, the depth lives in the references). Other workflows can adopt it when a source file's detail exceeds the 11.5k limit. The implement-review skill is a generated composition: `additionalReferences` in `SOURCE_PROMPTS` packages the canonical implement prompt, review prompt, and review reference directory into its own `references/` directory so those workflows are reused without source duplication. +Reference files are NOT subject to the 20,000 character limit. The review workflow pioneered this pattern (`verification-protocol`, `dimensions`, `false-positives`, `session-end`); the init-update workflow also uses it (`ai-agent-file-sync` for its Step 7), `plan2code-4-finalize.md` uses it for STEP 6.5 (`community-feedback-submission`), and `plan2code-0-pathfinder.md` leans on it hardest (`brief`, `chart`, `github-issues`, `grilling`, `questions`, `resolve`, `handoff`, `trail` — the orchestrator is a dispatcher, the depth lives in the references). Other workflows can adopt it when a source file carries detail that is only needed some of the time. The implement-review skill is a generated composition: `additionalReferences` in `SOURCE_PROMPTS` packages the canonical implement prompt, review prompt, and review reference directory into its own `references/` directory so those workflows are reused without source duplication. + +## Skill Scripts + +Anything a workflow step decides with one correct answer (parsing a spec's checkboxes, rebuilding Pathfinder's map markers, the commit message, which AI config files exist) lives in a script the agent runs, not in prose it follows. Prose keeps the judgment. + +| Source | Ships to | How | +|---|---|---| +| `src/skill-scripts/.mjs` | `skills//scripts/.mjs` | Shared: a skill lists the ones it runs in `scripts: [...]` on its `SOURCE_PROMPTS` entry. Skills install independently, so each gets its own copy | +| `src/skill-scripts/common.mjs` | every skill that has scripts | `SHARED_SCRIPTS_ALWAYS` in `install.js` | +| `src/-scripts/.mjs` | `skills//scripts/.mjs` | A skill's own scripts, mirroring `-references/`. A name that collides with a shared script is a build error | +| `version.json` (repo root) | `skills//scripts/version.json` | Copied at build, so an installed skill can report its version | + +| Script | Skills | Does | +|---|---|---| +| `specs.mjs` | plan, revise-plan, document, implement, implement-review, review, quick-task, finalize, handoff | `list` / `status` (Phase Checklist, groups, task markers, numbering, the implement selection verdict, consistency checks) / `metrics` / `mark` / `archive`. Imports `scanProject()` from the bundled `web-console/lib.mjs`, so the dashboard and the skills share one spec classifier | +| `commit-msg.mjs` | implement(-review), review, quick-task, finalize, init-update | The `` / ticket / `AI Assisted` command from the branch name | +| `review-scope.mjs` | review, implement(-review), quick-task | Review Mode's git fallback: files, lines, doc share, base branch | +| `agents-md.mjs` | init, init-update | AGENTS.md structure, budget, orphans, broken links, always-inline sections | +| `agent-files.mjs` | init, init-update | Detect and replace other agents' config files with AGENTS.md pointers | +| `pathfinder.mjs` (own) | 0-pathfinder | `reconcile`, `frontier`, `claim`, `resolve`, `rule-out`, `trail`, `gate`, `lint`, `brief-data` | +| `feedback-payload.mjs` (own) | 4-finalize | STEP 6.5's payload (real sha256 prompt hashes) and the gh / browser / print submission tiers | +| `handoff-path.mjs` (own) | handoff | Timestamped path, OS temp dir, git ignore check | + +**Conventions** (`common.mjs`): Node 18+ built-ins only; one JSON object on stdout (`ok: false` plus `error`, `message`, `next` on a handled failure, the same line on stderr); exit 0 ok, 1 crash, 2 bad arguments, 3 not found, 4 invalid or check failed, 5 refused; `--help` documents commands and exit codes; writes take `--dry-run`; `PLAN2CODE_NOW` pins the clock for tests. A SKILL.md names a script as `node "/.mjs"`, where `` is `scripts/` beside it. + +**Tests:** `scripts/test-skill-scripts.mjs` (installer plumbing and the shared scripts), `scripts/test-script-.mjs` (a skill's own), with fixtures from `scripts/skill-script-helpers.mjs`. They run the built `skills/` tree, and one test fails if any SKILL.md or shipped reference names a `/.mjs` that skill does not ship. The per-skill scripts import `./common.mjs`, which only sits beside them in the built tree, so run them from `skills/`, not `src/`. ## Repo-Local Skills (`.claude/skills/`) @@ -148,7 +175,7 @@ Optional local browser UI shipped with **every** skill. Source lives in `src/web | `public/` | `index.html`, `app.js`, `answers.js`, `labels.js`, `boot.js`, `chat.js`, `help.js`, `starters.js`, `workspace.js`, `meter.js`, `mentions.js`, `favicon.js`, `app.css`, `render.js`, `palette.js`, `favicon.svg` (Planny peeking up from the tab bar, served as `image/svg+xml`) with `favicon.png` (the same icon at 192 px, served as `image/png`) as the fallback, `vendor/marked.esm.js`, the chimes (`start-skill.mp3`, `bootup.mp3`, `start-stop.mp3`, `next.mp3`, `insert.mp3`, `sleeping.mp3`; which moment plays which is `SOUND_EVENTS` in `palette.js`, one switch per event saved in `looks.json`), and a `package.json` that only says `"type": "module"`, so Node (the server, `console.mjs`, `lib.mjs` and the tests import several `public/*.js` modules) parses them as ES modules without a reparse warning | | `public/help.js` | the Help dialog's PURE rules: `HELP_TABS` (16 tabs: ids, order, labels, diagram flags; every tab uses the chosen highlight color), `helpTabFor()` (which tab opens, FR-8 order, first match wins: finished → Stopping and finishing, server gone or agent adrift → When something looks stuck, opened from the Workspace dialog → Your workspace, then Ask, a red-meter dashboard → Session meter, dashboard, a doc or the Overview, a build, else What this page is) and `helpKeyTarget()` (roving arrow keys, Home, End, wrapping). No module-scope DOM, so `node --test` covers it | | `public/workspace.js` | PURE, no imports: the Workspace's name rules (`nameProblem()`, `NAME_MAX`, `defaultName()`, `freeName()` for the `-2` suggestion), the footer label and its width tiers (`footerLabel()`, `FOOTER_TIERS`) and `changeLine()`, the `Workspace: …` reply line an agent is handed per change. Imported by the server, `console.mjs`, `lib.mjs` and the page | -| `public/meter.js` | PURE, no imports: the session meter. `WEIGHTS` (the one place per-event points live; its keys are also `RUN_EVENTS`, the `run` events `post` accepts), `LAUNCH_COUNTED` (workflows whose launch itself scores), `pointsFrom()` (the count, folded from `ledger.ndjson` and deduplicated by id — never stored), `levelFor()` with `YELLOW_AT` 4 / `RED_AT` 6, `ringFraction()` (full at `RING_FULL` 8), `WORDS`, `tooltipFor()`, `RED_BANNER` and `meterView()` | +| `public/meter.js` | PURE, no imports: the session meter. `WEIGHTS` (the one place per-event points live; its keys are also `RUN_EVENTS`, the `run` events `post` accepts), `LAUNCH_COUNTED` (workflows whose launch itself scores), the built-phase sizing (`TASK_EVENTS`, the keys of `TASK_BONUS`: `implement-phase` +0 and `implement-review-phase` +1; `isTaskCount()` accepts a whole `tasks` from 1 to `MAX_TASKS` 999; `runPoints()` scores such a run `ceil(tasks / TASKS_PER_POINT)` (3) plus its bonus, and any other run its `WEIGHTS` value), `ANSWERS_PER_POINT` 2 (`answer` entries score per skill run, `floor(count / 2)`), `breakdownFrom()` (the click-the-ring list: one row per scoring entry plus one answers row per skill run), `pointsFrom()` (the count, its sum, folded from `ledger.ndjson` and deduplicated by id, never stored), `levelFor()` with `YELLOW_AT` 5 / `RED_AT` 10, `ringFraction()` (full at `RING_FULL` 15), `WORDS`, `tooltipFor()`, `RED_BANNER` and `meterView()` | | `public/mentions.js` | PURE, no imports: the `@name` popover's logic — `mentionAt()` finds an `@partial` at the caret, `matchNames()` filters the workspace names, `applyMention()` splices a pick in and returns the new caret. Used by the Ask box, notes and text answers | | `public/favicon.js` | The tab icon's status bar. `faviconState({ mood, spin, finished })` (PURE) maps the call `renderStatus()` makes for Planny's line to `busy` (the spinning ring), `ready` (`point`), `attention` (`adrift`, `gone`, or `work` without the ring — the stale line) or `plain` (finished, `happy`); `faviconSvg()` is `FAVICON_BODY` (kept equal to `favicon.svg` by a test) plus a bar along the bottom edge in the `FAVICON_COLORS` color (busy dashed on a white strip, so the states differ by pattern; the rest solid); `setFavicon()` swaps both `` hrefs only on a change — the SVG as a data URL, the PNG link drawn through a canvas. Called from `say()` in `renderStatus()`, which runs every second | | `picker.mjs` | the per-OS native folder picker behind **Browse…** (`pickerCommand()` → `{ command, args, env }` or `null`; `pickFolder()` runs it with async `spawn`, so the server keeps serving while the dialog is open). Copied from `src/launcher/plan2code.js` (self-contained CommonJS, so it cannot be shared) with the prompt as a parameter; a drift test keeps the two in step | @@ -179,15 +206,15 @@ Key design points: - **The socket handover.** `open` spawns the server first, then binds the loopback port itself (the first `listen()` blocks ~50ms on Windows, overlapped with the server's boot), launches the browser on that URL immediately (Chrome via `start` takes ~900ms to its first request, the longest step of all), and hands the listening socket to the server over IPC (`bindLoopback()`/`handOff()` in `lib.mjs`, `--handoff` in `server.mjs`). Requests queue in the socket until the server takes it; one `open` already accepted is passed across as a socket and acknowledged (`conn-held`) before the channel is closed. No channel, or no socket within 3s, and the server binds its own port; `open` then opens the real URL. - **The first paint needs no fetch.** `server.mjs` renders `index.html` with the session's title, badge and saved theme (`data-theme`, `data-looks-accent`, matched by accent rules generated from `palette.js` and appended to `app.css`) and the whole first state as an inline `