mirror of
https://github.com/jparkerweb/plan2code.git
synced 2026-11-16 04:45:33 -08:00
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
This commit is contained in:
1 parent
5cbc6edce2
commit
7d54941b75
243 files changed
+23698
-1607
No files matched your search
@@ -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-<skill>.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-<name>/ # SKILL.md plus references/ where present
|
||||
│ └── plan2code-<name>/ # 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/<source-filename-without-extension>-references/` (e.g., `plan2code-review-references/`)
|
||||
|
||||
**How the installer handles them:** the directory is copied verbatim to `skills/<skill-name>/references/`, so `Read references/<file>.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/<name>.mjs` | `skills/<skill>/scripts/<name>.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/<source>-scripts/<name>.mjs` | `skills/<skill>/scripts/<name>.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/<skill>/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 `<subject>` / 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 "<S>/<name>.mjs"`, where `<S>` is `scripts/` beside it.
|
||||
|
||||
**Tests:** `scripts/test-skill-scripts.mjs` (installer plumbing and the shared scripts), `scripts/test-script-<skill>.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 `<S>/<name>.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 `<link rel=icon>` 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 `<script type="application/json" id="boot">` (every `<` escaped; data blocks are not executed, so the CSP is unchanged). `modulepreload` hints fetch every module in parallel, the page draws in the same task as the script runs, and `/events?have=<key>` skips the opening frame when the page already holds that exact state. The chimes load on first use, not at start-up.
|
||||
- **Reads are stat-gated.** `fileStamp()` (mtime:size:ino) decides whether `state.json`, `result.json` and `looks.json` changed before anything reads or parses them — per request, per heartbeat and in the 1s poll; the parsed state is cached (`readState()` returns it; `/submit` clones before editing). `wait` stats `result.json` every 50ms instead of parsing it every 400ms. Static assets are held in memory for the server's life and revalidate by ETag.
|
||||
- **The Workspace and the session meter live beside `state.json`, one writer each, and outlive every hop.** Three session files, none of which `switchWorkflow()` ever touches, so both survive dashboard → skill → dashboard (a new console session starts with the original folder alone and a count of 0):
|
||||
- **The Workspace and the session meter live beside `state.json`, one writer each, and outlive every hop.** Three session files, none of which `switchWorkflow()` ever touches, so both survive dashboard → skill → dashboard (a new console session starts with a count of 0, and with the folders remembered for its folder and spec, below):
|
||||
|
||||
| File | Writer | Holds |
|
||||
|---|---|---|
|
||||
| `workspace.json` | `server.mjs` | the folders (`id`, `path`, `name`, `description`, `original`, `nested`), `version`, the `changes` log, `missing` ids, and `remote` (`remoteWarning()`, now in `lib.mjs`, computed by the server at boot) |
|
||||
| `ledger.ndjson` | `console.mjs` | append-only meter events — `launch` (every fresh `open` and every resume into another workflow), `run` (a post's `run`, id scoped by launch) — and `folder-issue` reports |
|
||||
| `ledger.ndjson` | `console.mjs` | append-only, one JSON line per entry. Meter events: `launch` (every fresh `open` and every resume into another workflow), `run` (a post's `run`, id scoped by launch, with `tasks` when a built phase reports one) and `answer` (one per item the person answered in a collected send, written by `ledgerAnswers()`, id `<launch>:answer:<send stamp>:<item>`). Also `folder-issue` reports |
|
||||
| `workspace-cursor.json` | `console.mjs` | the last workspace `version` handed to the agent; advanced after the print, never backwards |
|
||||
|
||||
The page changes the workspace only through five routes: `GET /workspace` (`?check=1` re-stats every folder first), `POST /workspace/add` (path resolved against `state.worktree`, `~` expanded, case-insensitive duplicate check on win32/darwin; `not-a-folder`, `duplicate`, `bad-name`, `name-taken` + `suggest`), `POST /workspace/edit`, `POST /workspace/remove` (the original folder refuses) and `POST /workspace/browse` (one picker at a time, 409 `busy`; 404 `no-picker` when `remote` is set or no picker exists; `PLAN2CODE_PICKER_ECHO` stands in for the dialog in tests). `stateFrame()` carries `workspace` (folders, `missing`, `remote`, the current launch's folder `issues`) and `meter` (`meterView()` over the ledger), and both files are on the 1s poll. The agent hears of the workspace through `open` output (`workspace: { folders, missing? }`, which also seeds the cursor) and then each change once, as `workspace: [...]` plus `Workspace: …` reply lines on `wait` exit 0 or `chat`; a change alone never ends a `wait` slice (`pendingWorkspace` on exit 10). `post` and `open --file` lift `run` and `folderIssue` out of the patch into the ledger, never into `state.json`; an unknown event or a malformed issue is exit 3. The contract is in `console.md` (Workspace; Posting an update → Session meter) and `building.md` (per-phase `run`), so the skill prompts stay unchanged.
|
||||
The page changes the workspace only through five routes: `GET /workspace` (`?check=1` re-stats every folder first), `POST /workspace/add` (path resolved against `state.worktree`, `~` expanded, case-insensitive duplicate check on win32/darwin; `not-a-folder`, `duplicate`, `bad-name`, `name-taken` + `suggest`), `POST /workspace/edit`, `POST /workspace/remove` (the original folder refuses) and `POST /workspace/browse` (one picker at a time, 409 `busy`; 404 `no-picker` when `remote` is set or no picker exists; `PLAN2CODE_PICKER_ECHO` stands in for the dialog in tests). `stateFrame()` carries `workspace` (folders, `missing`, `remote`, the current launch's folder `issues`) and `meter` (`meterView()` over the ledger), and both files are on the 1s poll. The agent hears of the workspace through `open` output (`workspace: { folders, missing? }`, which also seeds the cursor) and then each change once, as `workspace: [...]` plus `Workspace: …` reply lines on `wait` exit 0 or `chat`; a change alone never ends a `wait` slice (`pendingWorkspace` on exit 10). `post` and `open --file` lift `run` and `folderIssue` out of the patch into the ledger, never into `state.json`; an unknown event or a malformed issue is exit 3. **Remembered workspaces.** `lib.mjs` keeps `~/.plan2code/console/workspaces.json` (`WORKSPACES_FILE`, under `PLAN2CODE_CONSOLE_HOME` in tests): `projects[<case-folded worktree>] = { path, project, specs: { "specs/<name>": … } }`, each entry `{ original: { name, description }, folders: [{ path, name, description, nested? }], at }`. `rememberedWorkspace()` answers spec, else project, else nothing; `initialWorkspace(worktree, entry)` builds from it, both in the server's first `workspaceNow()` and in `open`'s read-only `workspaceOnOpen()`, so they agree. `workspace.json` carries `scope` (the spec key or `""`). Every user change (`bumpWorkspace`, not `missing`/`found`) calls `rememberWorkspace()`. `setScope()` swaps the list, logging `removed`/`added`/`renamed`/`described` changes so the cursor stays truthful; `POST /workspace/scope { spec }` (the dashboard picker, on selection and before a launch) seeds an unsaved spec from the project's list, and `followSpecDir()` (state poll, boot) moves the scope to a posted `specDir`, saving the current list as an unsaved spec's. Two writers, each a read-modify-write of one key: the server and `console.mjs forget --spec` (Finalize Step 6). The contract is in `console.md` (Workspace; Posting an update → Session meter) and `building.md` (per-phase `run`), so the skill prompts stay unchanged.
|
||||
- **The filesystem is the transport.** Sessions live in `~/.plan2code/console/sessions/<sid>/`, deliberately not under `specs/`, so the console cannot trip the metrics scraper or the loop's marker parser, and survives `git clean`. A result written after the agent dies is picked up by the next session.
|
||||
- **Attachments on notes and quick questions live in `<sid>/uploads/`**, never in the project: images as `<uuid>.jpg`, documents as `<uuid>.<ext>` with `ext` from `DOC_TYPES` in `answers.js` (text, code, PDF). The browser re-encodes images to JPEG and sends raw bytes to `POST /upload` as `image/jpeg`; documents go as-is as `application/octet-stream`, the extension taken by `docExt()` from the uncut `x-p2c-name`. `readRaw(req, limit, cb)` in `server.mjs` caps images at `MAX_BODY` (4 MB) and documents at `MAX_DOC_BYTES` (10 MB), and drains rather than destroys so the client gets its 413. Images need the `FF D8 FF` magic; documents pass `checkDocument()` in `lib.mjs` (`%PDF-` for PDF, strict UTF-8 with no NUL for text), else 415. The server names the file with `crypto.randomUUID()`. `GET /uploads/<id>.<ext>` serves images as `image/jpeg` and documents under a fixed type (`application/pdf`, else `text/plain`) with `nosniff` and, on text, CSP `sandbox` (a sandboxed PDF cannot open in the viewer), so a browser can show but never run one; `recordSubmitted()` writes every send's note onto its item as `sentNote { at, text, images, files }` (paths and names only), which `noteAwaiting()` in `answers.js` turns into the Sent box's attachment links and the Notes pane's pending note until the agent's next thread message; `DELETE /uploads/<id>.<ext>` takes any allowed extension; both stay contained under `uploads/`. `isOwnUpload()` returns the kind (`"image"` / `"file"` / `false`), and `attachmentsOk()` makes `/submit` comments and `/chat` messages carry images only in `images[]` and documents only in `files[]`, this session's uploads only, at most 5 together (`MAX_ATTACHMENTS`). A comment's `reply` gains one ` Image: <path> (<name>)` or ` File: <path> (<name>)` line per attachment, in attach order; a chat entry's lines come from `chatReplyLines()`, its images first, then its files. `sweepUploads()` bounds disk growth, and the session sweep removes the whole session a month after that. A note attachment a spec file cites is copied out first by `console.mjs keep` (`--session --upload --name --spec [--from]`): it checks both paths (the upload must sit under the session's `uploads/`, and the spec folder under `state.project`, real paths included, so a symlinked folder cannot carry the copy outside), copies with `COPYFILE_EXCL` and reuses an existing copy, prints `{ ok, path, link, image, reused }` with a forward-slash link relative to `--from`, and logs a `keep` event. It is the agent's hand, not the server's: it runs in the agent's shell only when the agent decides to cite a file, so the server still never writes into a project.
|
||||
- **Answers carry their terminal token.** Each item ships `fallbackText` and `token`, so a click resolves to the literal word the prompt already expects (`approved`, `a`, `skip`). No workflow needs a second code path, and declining the console degrades to prose with nothing lost.
|
||||
@@ -201,7 +228,7 @@ Key design points:
|
||||
- **Help is in the page, built on first open.** The **?** button (`#btn-about`) opens `<dialog id="help-modal">`, which replaced the old "What this page is" About dialog. Its 16 panels and their icon sheet are hand-written HTML and SVG in `<template id="help-content">` in `index.html` (after `#start-poses`), cloned into `#help-panels` the first time **?** is pressed, so first load builds nothing and Help still reads fully once the server is gone. `help.js` supplies the tab list and rules, `app.js` the wiring (tab buttons, roving focus, `renderAbout()` for the live connection line on tab 1, `lightDismiss()`, and a Ctrl/⌘+Enter guard scoped to this dialog). SVG is styled by class and CSS variables only — a `style=` attribute is dropped by the CSP, and a test fails on one — and every number the prose quotes sits in a `data-fact` span a test checks against the constant it comes from.
|
||||
- **Markdown is rendered to DOM nodes, never to an HTML string** (`public/render.js`), so agent-authored text that quotes a hostile source cannot execute. Only `marked.lexer()` is used.
|
||||
|
||||
Tests: `npm test` runs, in order, `validate-char-count.js`, `install.js --verify-skills`, `parse-check.mjs`, `check-skill-table.mjs`, then `node --test scripts/test-web-console.mjs scripts/test-launcher.mjs`. The parse check exists because `node --check` parses a `.js` file as a CommonJS script and has already let a browser-fatal string literal through; it imports each shipped module as a real ES module instead. They live in `scripts/`, not `src/web-console/`, because everything under the latter ships into every skill.
|
||||
Tests: `npm test` runs, in order, `validate-char-count.js`, `install.js --verify-skills`, `parse-check.mjs`, `check-skill-table.mjs`, then `node --test scripts/test-web-console.mjs scripts/test-launcher.mjs scripts/test-skill-scripts.mjs scripts/test-script-pathfinder.mjs scripts/test-script-finalize.mjs scripts/test-script-handoff.mjs`. The parse check exists because `node --check` parses a `.js` file as a CommonJS script and has already let a browser-fatal string literal through; it imports each shipped module as a real ES module instead. They live in `scripts/`, not `src/web-console/`, because everything under the latter ships into every skill.
|
||||
|
||||
**Adding a file under `public/` needs three edits, not one:** the file itself, the `SERVABLE` allow-list in `server.mjs`, and (for a module the page imports) a `<link rel="modulepreload">` in `index.html`. The set is hardcoded rather than a directory lookup so there is nothing to traverse; a new module missing from it 404s and the page dies at import with no useful error (a test fetches every import and fails naming the file). A module missing its preload still works, but loads serially after `app.js` and slows the first paint.
|
||||
|
||||
|
||||
@@ -19,11 +19,11 @@
|
||||
- **PowerShell mangles the CHANGELOG emoji:** `Get-Content` / `Select-String` render the `###` heading emoji as `?` under the default Windows console encoding, so a heading audit done that way reports garbage. Read `CHANGELOG.md` with a file-read or grep tool instead.
|
||||
- **`.claude/skills/` is tracked:** a new repo-local skill only needs `git add` (see Architecture → Repo-Local Skills). A correction that is a workflow belongs there as a skill, linked from AGENTS.md, not as a Failure log line.
|
||||
- **Loop `.gitignore` setup:** `ensureGitignore()` runs at startup in `Controller.run()` as a pre-flight step, not just inside `createTaskCommit()`. This is critical for phase mode where the Node controller doesn't handle commits — without it, `git add -A` would stage spec files.
|
||||
- **Workflow file character limit:** All `src/plan2code-*.md` files (and the dashboard prompt `src/plan2code.md`) must be ≤ 11,500 characters. A husky pre-commit hook enforces this, and `plan2code-metrics` (`improver.ts`, `applier.ts`) applies the same number to proposed prompt edits, so change them together. When a prompt runs short of room, move detail into a reference file rather than compressing rules.
|
||||
- **Keep LF line endings:** `.gitattributes` pins `eol=lf` because `validate-char-count.js` counts the characters on disk, and a CRLF checkout adds about one per line, pushing near-limit prompts over 11,500. `plan2code-1-plan.md` has under 10 chars of headroom (11,492); measure before adding a word.
|
||||
- **Workflow file character limit:** All `src/plan2code-*.md` files (and the dashboard prompt `src/plan2code.md`) must be ≤ 20,000 characters (about 5k tokens, the usual Agent Skills guidance for a SKILL.md body). A husky pre-commit hook enforces this, and `plan2code-metrics` (`improver.ts`, `applier.ts`) applies the same number to proposed prompt edits, so change them together. History: 11,000 originally (headroom under Windsurf's old 12,000-char limit for platform-specific files, gone since 2.1.0's single-format build), 11,500 in 2.4.0, 20,000 in 2.4.1. The limit is now a prompt-size discipline only: the whole SKILL.md loads on every invocation while references load on demand, so situational detail still belongs in a reference file, and anything with one correct answer belongs in a script (see Skill scripts in the architecture doc).
|
||||
- **Keep LF line endings:** `.gitattributes` pins `eol=lf` because `validate-char-count.js` counts the characters on disk, and a CRLF checkout adds about one per line to every prompt. Measure with `node scripts/validate-char-count.js` before trusting a near-limit prompt.
|
||||
- **The pre-commit hook runs only the char-count check:** `.husky/pre-commit` is `node scripts/validate-char-count.js` alone. `skills/` drift, parse errors and test failures are caught only by `npm test`, so run it before committing. Sub-package tests are separate; see [Development Commands](./AGENTS-development-commands.md).
|
||||
- **`skills/` is a committed build artifact:** edit `src/`, run `npm run build:skills`, and commit the regenerated skills in the same change. `npm test` runs `install.js --verify-skills` and fails on missing, unexpected, or stale files. Never edit `skills/` by hand.
|
||||
- **Metrics internal prompts have no char limit:** Files in `plan2code-metrics/src/prompts/` are NOT subject to the 11,500 char limit — only `src/plan2code-*.md` consumer-facing prompts are.
|
||||
- **Metrics internal prompts have no char limit:** Files in `plan2code-metrics/src/prompts/` are NOT subject to the 20,000 char limit — only `src/plan2code-*.md` consumer-facing prompts are.
|
||||
- **User Feedback table format:** The `## User Feedback` markdown table in `overview.md` has a strict format the collector regex depends on. Field names must be exactly `Rating`, `Reason`, `Went Well`, `Went Poorly`. Pipe characters in values must be escaped as `\|`.
|
||||
- **PLAN-DRAFT confidence numbers are scraped by regex:** `collector.ts` scrapes the latest `specs/<feature>/PLAN-DRAFT-*.md` prose. Overall confidence falls back to prose only when `<!-- METRICS_JSON ... -->` lacks `confidence` (`collector.ts:186-196`): `Confidence: 95%`, or a table row `| Confidence | 95` with no `%`. The four *breakdown* patterns (`collector.ts:200-203`) run on every draft, METRICS_JSON or not: `/[Rr]equirements?[:\s|]+(\d{1,2})/` and its siblings match a bare dimension word followed by whitespace, a colon, or a pipe and then digits. So a PLAN-DRAFT written by anything other than `/plan2code-1-plan` Phase 7 must keep `Confidence` followed by a number (with `%`, or as a table row) **and** bare `Requirements` / `Feasibility` / `Integration` / `Risk` followed by a number off the page — including innocent table rows like `| Requirements | 11 |`. Otherwise the metrics pipeline records a planning-step confidence that no planning step produced. `/plan2code-0-pathfinder` works around this by hyphenating the labels (`Requirements-clarity 22/25`), which breaks the character class.
|
||||
- **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.mjs` guards it. Related: the server writes each submitted answer onto its item as `submitted`, and `validate()` in `lib.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.
|
||||
@@ -32,7 +32,7 @@
|
||||
- **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.
|
||||
- **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/app.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 11,500 character limit. The pre-commit hook (`validate-char-count.js`) only checks `src/plan2code-*.md` flat files — subdirectory contents are automatically excluded.
|
||||
- **The splitting guideline has a hard ceiling — reference files cannot always be split:** each new reference costs the orchestrator a `Read references/<file>.md` line plus its fallback blockquote (~150-200 chars), and orchestrators near the 11,500 limit have no room to spend. When a reference legitimately exceeds 300 lines (e.g. `plan2code-0-pathfinder-references/chart.md`), that is an accepted trade-off, not an oversight.
|
||||
- **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.
|
||||
- **The splitting guideline has a hard ceiling — reference files cannot always be split:** each new reference costs the orchestrator a `Read references/<file>.md` line plus its fallback blockquote (~150-200 chars), which adds up across a prompt's 20,000-char budget. When a reference legitimately exceeds 300 lines (e.g. `plan2code-0-pathfinder-references/chart.md`), that is an accepted trade-off, not an oversight. Nested folders under `-references/` work: `references/` is the real path on every agent.
|
||||
- **Windows global bins for loop, metrics and bot are wrappers, not `npm link`:** on win32 the installer writes `<name>.cmd` and `<name>.ps1` into `npm config get prefix`, each running `node <package>/dist/bin/<name>.js` (`install.js:1302-1323` for the loop; the metrics and bot installers do the same). After a source change, `npm run build` in the package is enough; no reinstall.
|
||||
- **plan2code-metrics only runs from a repo checkout:** `analyzer.ts` and `improver.ts` load `src/prompts/analyze.md` / `improve.md` at runtime through `new URL('../src/prompts/...', import.meta.url)`, resolved relative to `dist/` (`analyzer.ts:11`, `improver.ts:13`). A packed or copied `dist/` without `src/prompts/` fails.
|
||||
@@ -117,6 +117,7 @@ The skills CLI owns distribution from step 4 onward. It stores canonical skills
|
||||
| Skill name | `generateSkillName(prompt)`, such as `plan2code-1-plan` or `plan2code-init` |
|
||||
| Frontmatter | `name`, `description`, `disable-model-invocation: true` |
|
||||
| Reference files | `skills/<skill-name>/references/<path>`, copied from `src/<prompt>-references/` and `additionalReferences` (any file type; every skill bundles `web-console/` plus a copy of `version.json`) |
|
||||
| Scripts | `skills/<skill-name>/scripts/<file>.mjs`, plus `common.mjs` and a generated `version.json` (see Skill Scripts in the architecture doc) |
|
||||
|
||||
`disable-model-invocation: true` is unconditional because these workflows are user-initiated. Agents that do not recognize the field ignore it.
|
||||
|
||||
@@ -132,7 +133,7 @@ See the `skills/` build-artifact gotcha in [Code Style & Gotchas](./AGENTS-code-
|
||||
|
||||
## Adding a New Workflow Prompt / Skill
|
||||
|
||||
1. Create `src/plan2code-<name>.md` with body content only and keep it under 11,500 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. Add it to the skill/workflow table and the "What each skill reads and writes" table in `src/plan2code.md` (the latter is checked by `scripts/check-skill-table.mjs`), and to the workflow lists in `src/web-console/public/answers.js`, `public/meter.js` and the `console.mjs` usage text.
|
||||
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/`. Add it to the skill/workflow table and the "What each skill reads and writes" table in `src/plan2code.md` (the latter is checked by `scripts/check-skill-table.mjs`), and to the workflow lists in `src/web-console/public/answers.js`, `public/meter.js` and the `console.mjs` usage text.
|
||||
3. Update command inventories in `README.md`, `QUICK-REFERENCE.md`, `.agents-docs/AGENTS-architecture.md`, and `CHANGELOG.md`. Update `docs/index.html` only for core pipeline steps.
|
||||
4. Run `npm run build:skills` and `npm test`.
|
||||
@@ -1 +1 @@
|
||||
U0VOQwErJ48kORFACZSnsphnJIwkZvzfvDDm32pRub1X968+xmjPhFzBYj4CZgfvy+A4aoKW4RgsV97CEx0Xa6YqvBybBT/M7RykZpBSDWrTtgLi5op0Hxk2eI5TDer52ID4z55AgOPrOW4fT0bSv0RMdP/fh7N5Q65TG5fduMeAxlqiPyVfYldmX9OqV6xDhSPsatfWaJQhJ3/i3xfVRHP7q4ChHQiUx5DnwnkV/WEPYw1KXcMzxLBQHrn/0POxfzQwVWpji9ref8ZbG//HmOCxWNA6Z087LVHIT7gyt9TcBD+Lq2VF3FjMGoR/40agNrbXXDMgpAKJrRk88+Q5q8IPJmQXG9txDZay9+bGIqM7xpuowg6OZbsXD4r/FHUiuOEtn1uBWTBKZ71UEprzo6Ips20Xa2SBBM6+poOVOlNDVhEdem652awNlzRdqoWAYEOtmSKdbnwUlhfFhewV0nfjgB2lMs8PA/oGSjevaO+5R9JAOSU2r+y1Nnfa3fRNvzuls+1FHo4y7FOeKKHpSbWGERYLnWxD4wnfzE1FW8jtglk06lzf7mrJFCS0ApjMAj6acHg2It7YDD4yOoC7Qe/bCSouyu5Zy32bdKAwGeg1H19WsT51bkRrV5N5vpW+PVFdUsb5vdsctNDwkYlJK46FJkvv07HokzDRSeJdfWznnvxwQyjpP04b5YCzcOeRQngH9w7DmjC4bpShtSGnnXrG/DTJMqWLHztvyPwiYKngqyZ181nuRoUZzpQvYeko6SH33HVpvp39xlHJCt4s4iIqVY6g52rzVWa6YSDnMqcB/zrX2OByNanoYtZE2wiioywxakZLQ8N+0trB1rXheF9RfWzlSYYB+gBzt/3r2Y3Jff3VjdaAxgM6c/JFOaAIquOHDA/L89VV9wQVXT9cdsJT0KNVFK0OWhToTzrdVm52YBSYO4aNTX0XCLk8aevaMVh6Dcz3pINK5k9Y7leVm3vHyreUVn0MvS89DX4kMbS8RyIvSZi8TJsIhpdaTTme4A8GuwzOTNdQ04+Bxe7nmrOIZYUjwPl/UXN8y3zoYBFttlY6ucr5Uwk22TZgbpFZw4ZU5+6HZd26hgaWzy006s/lXM4J5jGNKHJd8vSyVwewHHfpqstAekyc6laaXoOd9t0a1Y1hsgl8b69w6KFuX2MQnalZ1fjlz//XvClpUAEJ9KmSUwe6kpbcVUKgd0B00HBrLdjmAws8Est6zIGkETLdPd9dtUyDeYSljhAzv4TyV9Y5bFnazZUBvXZMDPok1HLxfSK3CNbnLc3NcSgRiPCytajIF1sLuPzZwsaW4hExejHIOQZGJmC/gq4M/ikLdeDWUo7rRTybbglpJm6bN3PIx6t/A/RbDsF81OaJ6F3Wlxen+uqRsRSyv0LJ5FvAzaqP68clpifrIlB7/h6O4364ugIAveDyV8U5J6SS9JPuqS4SbFiKYi5W4E5ARF4U9TQEhLHe25lh0In7bTRWgJnadh8R6+j2voLRk33qrhueOH7i5GMbyDEG8DbBuXkHs09zpo7HuZmx+yUhmKm2yMbs53w1IsZ99Li+wJaTdvUQDxzR1IpsRDjO1U3mD9Rdri3IE/v64ciSV2lrlL3ge94n/jivBORmXmyKRZQtfnvyBJspi7xBtuvqqIwc7mcIqCLZmML5KHKEYesz6EOzGlOC5p1VW1xaxxh7wEOgXD8UthCaO0/qg4jWTWQDOKhwVolYDCw3KsRT4l4QM2PRkakBsue2ZBSj1PGmX2QjvoXLj0orv9o0WwPvCpQHh5yIwfSNhha8EJm00OPBe+hBW8ttpp2vRBBmUEcuUg+bF5ZjWsmDSiUohwqgI5RsNtw5rgPZVo3Ys8glkoi9dzzlIdp/vMUj1rX4JlfRhijTNIia3WqVhtEvycTOanHdj57YSDhRlyHARxVGmU+eANVj+8D+jJJYWu2UnhnzCsw4awkqP8jH4LRVJdqe2WKDaX361KwuvUWGcNa7dm7NhNAep+QDoRVgmkKjP1IU99xpkko+e+zcU18lnJtIZ5C2gUHm+ma17uT5/JisFuTtp9Lj5dnzcoCj2bC/5wZMmDvFoBr7C8cedeY5YmFs7lAUNEzAVweiYyQA80tf6lh58rA0X+NHKAH7kHw5BxqBSJAH1ewa/S0qZV2UrX6ASoAbahHhf0R5B+qk7yx4qXx3/wH4DKssj5OMvcRvjj1CmeVY/ErE/6UsYlhkHH5J4O3wfbo5Z1AbMD4JJ2H41KxoUn6VEA080xcXGWdOcJkfN2uVTFoVaBgxyl2ZhaZmnS94ig5Yf8TVhK2ligb0S1XezmKgqldNF68cPNad1uyP7fnbBbmW81SJWbklMkshhjCJvFt6H8l4VhsQh/wmS8nMmqDsK+d6OcHb4JoUgE1T+g03QmAY4kWFnKPKnXcanxDCGQNy/IpgMez+C3NN87pKBjcejTI63ld8xtrgORLeWTA+EBtwIUIbnDpCaR0uRo37L3azuAUyFpjksNqCK4IikJd1jmfNOz7x7uWADcRyoxlVNytHT+7SbEgNKybMDTKzByUHe7zraVii7Wh0d4cNNsLMoYut+a4riq8ivQsYMf1Mdt0Yo3CtC/AFS/+iW7s6LGYi6XGnZz2JDySxRDcqNvE4rl4QyyA5X4a8RmnDn5wx/mFUOZA7M1t6L1sfc4bcuZ0yFiV03VSzoguM9YeJIxvog889oXbH4ayuJo6NfkX3z9TJ+SQKrRqXPOPN9CuEvDB469nZtldoj0apg3LWtto08k2Y5PZghO3PWx2D370cukIYadw21CJmmDgSc44cr9RK7VnqVGhvPjlSx21sj+TjaFdWh7AqCStxt0PnCXCHKs6J4xaY8kVUG5rsq8gjn/3HnlRzeb0eAh5QF937xbXmo91g0EpGgoAM9mfheXY7EkaNXa26lJ6qXsuBCehlB7QL66ayzme7DHP1vYB4gCX0IMwUanfUIP0XKLC/SZvfmCNBuHxZZLerlVJdDlmOavmURYlMViy0HUY4m8ES/ACncMWkPsdmv/ZRo6v/q/4l+Y4zE2yEZ3DOlddHcTPNvFhFIQnIdQihrGY35fTGrILmQqlqM4QbAKiPT9oJsGqXuURyBdxQeJuJmT4V4b28mAbr0Nn+sKcfeVNd4wJ7VK4SGrdYG4KOFLmpKEI5i89OGApwxJqti1wrveyJLxF2P8XDVBA5US0vLz5WemKGDNM2NJOnvomOW30YN9CjmgM/qak9AZDZQ4x/uciOYuvPLMAzCjsMPjgUueVIcZw9eJUMIcFOwEthAeMZJ60pJT7bO34S65RvRL5co7CUzhvNlT3CFcC4VVyxKInhNt1B9IFnzI+sYZuhHW4OQnUG8atoL42J0MX39MeNEf/sAVOt1N8fC3RbylftLO9XuKGEqo+WD6755p3dC5kRy2AMZG1zMmmk8baeMSHPyM7v6lf1nXYQvFAy7IFHAg9/qTAp992IgHImsggX6ZdSQmxZpc4OhtZ14oGy+zgy7Fffi9Iidnc2O9qEBHxDiRRgkcgOs0Dg9bZWCrseaqruSKcYs/xgHt5wpLF+68RSDQ3LRau3guGQ+oQCcLKupF/4yeXFCSyd5Wd5Zcq6o/KdFfQqh4wnYsLnguDxi/qsUTxG9rUPDW94IC1w1zwImlLLqqmCYs1TRmkC7d8gRDJsRrhlK+2OAzNhRm5yL8RIBHyLJVZz69e488FQPxoHFnJG1H3sI3m3Sdt3Xq8H5xQ85UiNNQDyu3nteVzNH8Ri44x+4TVtZDrtTrwUUvW9r1eRywhGRj+pBcpxSD0VxzkMby2Z2z9cN5Ryg+SA9VW2IdFhEmQRW4ryrU2tTDlsd/EMPuoHx0sEOwyS7L/S5+ai1ZjOa3Ooi1R8Yzg97DBrVTYwSWKrNky2SRILVNiT9PYaNpreB+sWGQGk2Ji/UX13Zk2R9VSi5YBQhm5ELG4hXeHJPIU45yRg1ASi6BekyFN2GZe7QvslCzhJXZpgpxIBPVehnv6KDrk0iUu6LVI8lPaq7VbIt1vwn7xt2YS/P231EhtA5yvLFyfr1Y/Gf5NxFQhn8RSdFzTgt/pYsg5lqllS4MjeTQFziSdP5AeY3xYjmAvjqoWZ1DLAhLEO7wOMihk6rEA7+BRvSroZ3iBZp+sphk4ysi0QdTu4Jkf0L7YWkCCJksEGWCFrYFkqHSXIYKleN6bSW4K3adWo9F1V1UdoE960ghAxDMLtHPuDnKpsB3T5fgOJSxrGNUfylEgi9ya7pY/iEkhWbylCHA64N2ldWLLG0xjMw7HFUqKfLfvIKUniRWgqTue50WZYcwOqvrnvHiYxDHXPH23thAjzio/7dWuJ/j5sgSXlxhVHcZyozxIPUAw7Qsb3aUFaQqxQWxSkkkDiT1nfm3bT0IVDCr4VwYXsLqiF+TjkQlGfNqJPkjqWTut4ZA8YhSPpSUmLJcOrJPEnzCekZXmWlutT9CaFc9GEokr2HGHy6lhRg2OZRSlYcBRo3Ai6OK3nTM09O9r7zyHJR91baG/kzuK3XqXH87HXe5q+svysGL67nRb+qN+uddzPhRCkPhjT45ZeWGDX9idY+t4jMOFmP176XjMphJRPjUbCaqaN3FAGaHtM7AvFlWMvuJjaRQ7rM4hDhroCkwD5gMJ3GSzCA9FbHaPb68y8qqaVJlO+ZEHjaPluNIVcJmw19y2lFpuJXWWyc9RvFjgwVqC+XUm1M/iSUkieOnLkpgl825md9u7+fUhCVczrOrx2sjSu5t3VLG7meD7CkUa/37wbRFbX2l9kBdFOvIlBDvpuG+/ViOhsQnscux3eduWzFXT9ojWqy33ORMHzHjYJMGuCVQUckN6no1gRB3IEcAYIVcR3JhGwLOi5WMVncCBeeASRF7VfF27ib2mC9x1FvQLRDwN/9bsLoMmHajXjdiOwvaTybBQQSKy47kN3nlnIz5384VzGhdGLVPsZK4OFYXtC1vA4qBIykSWv9XQ0rltkEHLcWVbLine truncated
|
||||
U0VOQwGHvlBAKBpANryoCdXbfPtfW6rftbEVcNYHSx1rwcmt5mK1z/0SJkc5SXJbEZQl6q639HxyFiGyLv13negwgwNcvEFOSnlhqVcClGqjZMXz0vavtWKpCqZP4B+OudqsaKbx7q4dd8FM6UWpP1h6lTlTG7DyNBgpWgfE9BQuOMJ0iE1L8xLoW49+hQh4of0T23jz1l00GHzaZwtaK1fH8QKV8SU2ENQGqMgY/WcJqoBcgq4yi+P5RHKdT2QxTuK8Hph9mFjaEbh5jbkmtuwrl5lzty3bqSHBFILZ+lJcicjKwrfbKowhYEEpK6LFrODIWCr/IhOoXfxVGzg1rwGVoAoEphjEq1S+LhnUciWJoghHfwPZtrDWnpoUSJ7SBLCKcDew8zPXUre3A9NHmd3G+FrDYKybDts8zGCKovJtOIff3U+6h0T3wy4UmKai4RSWR+LOvCFaPgHxGI49PtR5Bqtv9bhcW1LBUzjcv00vLsUQRcOqV7q5Dj6mq+pzm3ReD3J0HgUzFwE2sZPENtUJhTjPsWPI3llQlgcNT0u5knKvT2ERy5OVrSJK963Pl9vRqCGtVcBRPWidRY8EeH6vOFFuzS/FqsFGcLYPK6MGks9W/RNI/aQQN1eTANJgsnuKIT/RAlABgwh+l2X8JKTsH97/8DCakJVw4qPKWccysIYPNc3Ra4szlz/B71Z96FmgOA1xFE2S+j74vAKKwEmguFhdVIvjw16OQY0CIMpaK1rDl9MVfvRVVKHd8mDZI6I8jZr2MulFBpvWCpoUWFMGdfmNTfbvUFEt1Bd6idKFvy+E/chg54K+CdY7Ua4sOdTC3sx2+uIUYAPa40N42f8Nvi6gnmtMQK5+f4anQ7b5HrQ/PkVcrXEiG6VzMcd6s5wuPi0mqJ1P1g0Tqg15uIhu5fIr8YdbdouuWX59yptkPCTEVwkvYSS1UrpH2Zuhm7EHU6o008Iw0EpH2/V0IZxNGrbw8YvzeGBSg3yB2z5rZ5Mpw5NXzf1mtPaUAGQwRfL3gF5u863lqZYtDm4t10mYQ8Mq/SolCUelkiagpxG/MdAo5tA9Bql+8sRUbCxXEl7WGLrW8Skm5ls2y9mJ4pluw6N9vByyGUmHCB6Tr48rFzdEH5OMA4IRrIrXm99p/KamebSksoX1ahi2/Vf19Osq6sENF/sOHJSMxj+BOi4oIjaLlefIM35KsymXCzB3Nr+OLAXWkpjMAmt3ve8cvNYhXS85t+LqtCLhv8h38wmA1Sx+VSKqoMF9cjBlAhXo59flIMaxV5c1PGZc4+lPtWtb9SlK6xE5OKweehe49KZOCIKJxhO6yy9kAJC6CexnbfjYfWz0tFn98SYagZt4V55nqSp+6xtAUSp2CeIjlaBoKWQjD8xLALSxeZJO2HYfgJ/+acwEFKTnDdxYEVzhHOENpc5DD8IPeqUEHMEzzIuR4iTq75XGmPREmltAWq3xVulYHMjTc9svXi4S2ZeA8RzXvTx+wH5hPQ5lu1w9OaAxpqfHbxSRqM5tgEwhc1FoielbBdDpbg5kzHLP3sEi8fYWbBwcb5muWtz2d59ldGLM0XSSCojQC9Jpq4QpEeq0ziK9tTAELziJ/lFf9FpPPN9n+b6WBCgGgLX5yXt9FD+kNTR6rRgXY+YvTpSJLGZtXT0mwV7ejq0AqG59s+2mc1Cn/SwdKYnYTgaofnZDKDbGRVuoeC7i00DOaa2xL1Lpm1UA7pQRbvAh1C7lFc5P/ThdU9KVSFnW3nip6WSBYsKnAV82Q6yPVPWwoWaTsxAmpwMk7fRnZ+UdvmRgpYxr0XQYXa01twCxb38otzXf/BGQ9d+yGUVRjFtKbzPuFvRMIdJ1ZIpXXUedvifPOTay1KPps7DCfv+0BMaDPMQBnDH+WU4tQ4qgG/5PSxS0LVK1Em3+4C1pIe3j/nDmENRrdZA4a23pG2Pdexzi6tXWNq2a/jWyVKtyKnamJj245MegILjDiePkjGUgcCXty1/fRd72b480CWBqLt6zqARI7javJ/Q7bZuLIvZRxCMMq0SACnDq7eFj4Lhf59sg4qtMIay/55tS/lkcebGc/WSA4VeP7/A8R/f3OpCQ1UuBz4KkSDS/HE5TMCXIHOQ9dVGCJCPPAcxWtz8DiNBmOm3UoxQXo3C3on4eznlDd9/NLt1bE6chFXSwxRXf2zMVWymXQh7MCx4iijgMJN/V+zFag3aT8BZKFnPb7cSxJwSEmZRph/xLNctcyDmdOMpJSdYKN6LyRacfb6JohC1oNQVFrgCETWhmXbPfIf+ERCH4w/JycXO433CrRRWXVcGRidhMIZ5xeOzCWjz9uRpDuzKJfQFU71eBMZM5hubHGB65fYCBKJ9DllzdFQSbPtUq2RLPFTUHsIIyt3YIJy+/MR51U1Almf7lGqM5N4tZwU228H1g4lzxO53mul8c7p1T8/uZCM2bB6BOVmMXrunOeD5nvHm1CYP3Sd4iBBtORyEkEMaf+hKy5ZGfexP6xhWzU8LzsvRbIig87WvM0kkMW8plIN/g75HjlEycDhAuf+3QYp7vvb8FxF7gq9t67bkivMPqfj2YacL2Ip3GEJ8nJJZMtFePWDsThDI2BcvLfZPwEK/szxKBjJjz0r9HxU2rebpq4a7KnnayBg5Mr0l+iHTvx5bCfq74NYWcmrwp7kT45OhsA8lmO6I2dBFpq7nUUkGl3mNzGlJJzAWVdKWhQcGJJ19tT8AsKOXE7gED3hzcn89DqgW59mO5xpwdvmZOu5jdQ6kEpT2+sQqa7Y1Lrfa5EqG3hT1vByYuM7K8syo7ftO0qSi8NIO/h/9qY5oJWrS6GaDmKZZGvrSDDsM1A47dy/kavqYEszIeQUlg4VGFWXmP2WqRNRV/Kiee2P0ri9AysQY4gj8cknljNV8kKwIPpZNl4Vk+mx5rCEHFLG5C0CnvEq0UprzObyUaJ+jTHcURf12kqvWYiDCzpU4E8+GqqsEfknyLgWPn7YODJH7Elx9XxkRvoGSg5BM4OwN9mrBdpHmy6OYF/QGKc2tHBxD3B9cxT3auNA7Z0uyUi+erq1DrjIbpEukatpp8P0iIeQNsIDuJWBTz/Ybfw/ZhwPNbd85Y+QqviPPfhEFjYjFqZD1j/zHe68q6cR4ke50f9DYxzzZ1jyAdKYP2vRqTi8yggrtTEcQcXdY6OG6ckhwiV3ygaHLFLY+xrfONaWKHsPW5t5apn6VZV1jIpX+jEZIkDgkAWZAx8skZ/2eVUnElZ4I+gM+ButsUZeCX7qfpXsaI6P76P0bzOP88Yg+68spjxKZRef3qCaeVW3kEF+nSXk0L2fY552uwJDz4GA28U8LOWtALa/kHoA5zdisUndqF6PKmb7y2Xw+TgaY41M/Eqrolv9jka3WRi2WxRXj9LvmsUPUydgKltww9G3dnqEA4IuPDwLWB73oENQA5tz4FZ1IIZg3ccf2Zl12mrdSUTo7D5G+W7o2NQERSdby3T75CjAcOkAzKxngF7dhVtEBAWLdb4wsnhvE//R0qVKIWCm4iQ7SJDsejgHeYNMhZQh8EKGDQjBwA8MT9tgHsT/W1ycowsWoWleZ0F9KkGCOLVeUmFkJCi8Fzb980fF/LwwR3mvC9UB0ztDK7A5tsUA9/iczy+nAQz4DJatowGAEHzgr3hsJl1InH7dXdpdi53CstfqUf58DfQI3Ax5pJqvLVr6J5tZJe8ZkmcZAoqrDveizHlwZkE3voTB9HbwTDXr7KeEv0xB6muFrta07KAgrMS15EBSiGVKsguw4/UYUMOtF/Sh4nJVF0F6cPkFldBZnW5c2oKcy0dtMrtspdgBkXCDjAKp6bJoFocxmiwlGrkBUhN55H7dlyAyoG1ddAcAL8861QCSEbldHbBLKIKblGroTQzFMrX1XGwU/UYyGrkGf+1u/rYq0lJt3Nm6ozQGszpnQ5Bi4UrLyScY5vLYuYvzNEoIM0vrQ2T75TneK06CP4NlyoRqzuBm50ufCnTpWbH/NNmjB1M1w4bgU0QAuQQISqCqSSyROE/klQCde7vB9ogHBgestE/+wWOC7zJxleraQCGYwtQTzuSxJyiQzKcVxDSgcBI8As1Ksf/g1kpUbeOQjdnCVgERRYSOQzuLt4KBMkiplpWf0TeV7/05puNKijIpLoiQQYWYMLMaUBSQyjdQfF+TNJSeUfX86yI68iXtkwD1M46oDmzc0T9Yk5HfCEYKU8jfe679JoKg3F4axRHzi7M9VUi8gP03ovKzXicl/ajNQUXr951aqWHSDYyiRAhLU+ZwJC1l1ku71YrHFrkBi/tZEjhdbFSq2Oiu9118S9zMEKvO7Q96bg7BJztH2aygOW5TiTwM1Vm+Z5/KhSM4K70HVQZoTn8xu7wJeWLwteV7ZQrlE19WT2dpHnrqgiLvpOzZP++2N1ls3vulvrfDvF+GPlSqiCPr5qJ/m1liqkfl+f6ataFtljNnRXxrFu0MuoKTmensfrTT/RcFAcCZe7NmA0UqAQTTPlazmUMDapSYkyQ8lWlF5AoxpsfiwD82MxCbpfCVBSundpwfAQQQgGVQ+HVUhgsus9QIqTchOzZxxGfJ5Wk9GJCNKvzDz03svzwb1q7R3r6RBakU52jl/diFbPXVwqRC/TeiDSJGSqyBhWXOmpjO8NlrLVV4BhNhHTtB6Z0wukA0aixVkBzozTvmgEk0b2NLCy4a0CQ0pqhLsviq+/NSH5l2rzfQZxVllgo7mcv+FCKYQRbIXjNjfeSkgq+pGq7+qbUhL0c2cPLiIZ5sy7AQNLixBbdeowQCqYJZNUxy8Bt7zfo0Gbdjnt3CoaUFiPk0WjLu45/FvpQgL3LE8ML7SbAmto1LadKhK9WsgC7sBa0PR8SeT80tUu/Yz/hdiHfZgYpArE2K8J7ZZFF2W9+9+DVFNeCJZduqNoj73/rZGxtxQcFu0qAGkbVbP8FKV9VX16RGexD6En5Sx89MjdkGDIdAcnSUFkXjRh62ZLine truncated
|
||||
+2
-2
@@ -4,8 +4,8 @@
|
||||
# Git stores LF, and every text file is checked out as LF on all platforms.
|
||||
# This is not cosmetic: scripts/validate-char-count.js measures the characters
|
||||
# actually on disk, so a CRLF checkout adds ~1 character per line. The workflow
|
||||
# prompts in src/plan2code-*.md run close to their 11,500 character budget
|
||||
# (several sit above 10,800), and a CRLF working tree pushes them over — turning
|
||||
# prompts in src/plan2code-*.md are counted against a 20,000 character budget,
|
||||
# and a CRLF working tree inflates that count, turning
|
||||
# `npm test` into a check that passes or fails depending on how the repo was
|
||||
# cloned. Pinning eol=lf makes the count reproducible everywhere.
|
||||
# ─────────────────────────────────────────────────────────────────────────────
|
||||
|
||||
@@ -42,7 +42,7 @@ These are verified, not assumed. They shape everything below.
|
||||
|
||||
### 2.1 The character limit is the binding constraint
|
||||
|
||||
`scripts/validate-char-count.js` caps every flat `src/plan2code-*.md` at 11,500 characters (11,000 when the numbers below were measured), enforced by a husky pre-commit hook. Measured today:
|
||||
`scripts/validate-char-count.js` caps every flat `src/plan2code-*.md` at 20,000 characters since 2.4.1 (11,000 when the numbers below were measured), enforced by a husky pre-commit hook. Measured today:
|
||||
|
||||
```
|
||||
10995 5 plan2code-0-pathfinder.md <- 5 characters of headroom
|
||||
|
||||
+14
-2
@@ -324,8 +324,20 @@ context for this console session.
|
||||
Code with a copyable `/add-dir <path>` to run); *Inside another folder in
|
||||
the list* for a nested one.
|
||||
|
||||
The workspace carries across skills you start from the dashboard and back. A
|
||||
new console session starts with just the folder you started in.
|
||||
The workspace carries across skills you start from the dashboard and back, and
|
||||
it is remembered for next time:
|
||||
|
||||
- **Saved on every change**, in `~/.plan2code/console/workspaces.json` (beside
|
||||
`looks.json`, never in the project, since the paths are your machine's),
|
||||
keyed by the folder you started in.
|
||||
- **One list per spec.** *Start from scratch* on the dashboard shows the
|
||||
project's list. Picking a spec loads its own; the first time, it starts as a
|
||||
copy of the project's, and after that the two are separate. A spec created
|
||||
mid-run (Pathfinder, Plan) takes the list in force with it. The line under
|
||||
the dialog's title says whose list it is.
|
||||
- **Forgotten on archive.** Finalize's Spec Cleanup step says it will forget
|
||||
the spec's list and runs `console.mjs forget --spec specs/<name>` after the
|
||||
move.
|
||||
|
||||
### Session meter
|
||||
|
||||
|
||||
@@ -40,10 +40,16 @@ Details: [Architecture](./.agents-docs/AGENTS-architecture.md) (see Status Line
|
||||
|
||||
## Web Console
|
||||
|
||||
Optional local browser UI (`src/web-console/`, zero dependencies, detached `node` server on `127.0.0.1`) bundled into every skill via `additionalReferences`. The bare `plan2code` skill opens its dashboard, a card menu that launches any skill in the same session. Pages cover questions, sign-off gates (with an in-page code review), build progress, the living document, an **Ask** chat, a read-only **Workspace** of extra folders, a session meter, a built-in 16-topic Help, a first-run Welcome, User Preferences (gear) and a bug/idea link to GitHub issues. The agent-facing contract is `console.md` / `building.md`; the server never writes into a project.
|
||||
Optional local browser UI (`src/web-console/`, zero dependencies, detached `node` server on `127.0.0.1`) bundled into every skill via `additionalReferences`. The bare `plan2code` skill opens its dashboard, a card menu that launches any skill in the same session. Pages cover questions, sign-off gates (with an in-page code review), build progress, the living document, an **Ask** chat, a read-only **Workspace** of extra folders (remembered per folder and spec in `~/.plan2code/console/workspaces.json`), a session meter, a built-in 16-topic Help, a first-run Welcome, User Preferences (gear) and a bug/idea link to GitHub issues. The agent-facing contract is `console.md` / `building.md`; the server never writes into a project.
|
||||
|
||||
Details: [Architecture](./.agents-docs/AGENTS-architecture.md) (see Web Console section) and [.readme/web-console.md](./.readme/web-console.md)
|
||||
|
||||
## Skill Scripts
|
||||
|
||||
Deterministic workflow steps run as Node scripts shipped in each skill's `scripts/` (shared ones in `src/skill-scripts/`, a skill's own in `src/<skill>-scripts/`, listed per skill in `SOURCE_PROMPTS` → `scripts`). Prose keeps the judgment. JSON on stdout, documented exit codes, tests run against the built `skills/` tree.
|
||||
|
||||
Details: [Architecture](./.agents-docs/AGENTS-architecture.md) (see Skill Scripts section)
|
||||
|
||||
## Development Commands
|
||||
|
||||
Build commands, installer menu options, non-interactive skill-build verification, skills CLI delegation, skill format, and how to edit workflow prompts.
|
||||
@@ -86,3 +92,4 @@ When you make a mistake, get corrected, or discover something about this codebas
|
||||
- Sync upstream only through `/sync-repo`, and verify its baseline against the real tree before porting: an earlier sync silently skipped a whole upstream release (the `3-implement-review` skill) while the recorded version froze. Update the baseline with `.claude/skills/sync-repo/set-synced.mjs`, never with a shell pipe over the decrypted body.
|
||||
- After a sync merge, run `npm test` before trusting a "clean" file: when upstream and plan2code fixed the same bug, `git merge-file` keeps both copies without a conflict (a sync once left `let pattern` declared twice in `app.js`, caught only by `parse-check`).
|
||||
- When extracting upstream files in Git Bash, run `git show <ref>:<path>` with `MSYS_NO_PATHCONV=1` and `C:/` style paths (never `/c/`): path conversion rewrites `origin/main:.readme/x.md` into `origin\main;.readme\x.md`, the show fails, and the merge silently runs against an empty "theirs". Check every extracted file is non-empty before merging.
|
||||
- After a sync, grep the result for the upstream owner slug and company name in any case (the `/sync-repo` body lists them): the rebrand map only rewrites URLs, so a bare owner slug once slipped through into `feedback-payload.mjs` (and its test) until it was fixed by hand to `jparkerweb/plan2code`. No upstream name may appear in plain text anywhere in this repo.
|
||||
@@ -12,9 +12,31 @@ All notable changes to Plan2Code will be documented in this file.
|
||||
- **Web console welcome**: the first dashboard a person sees opens a Welcome dialog with Planny waving, four tips and a **Start building** button. Closing it by any route saves `looks.welcomeSeen` in `looks.json`; Help's first tab has **Show the welcome again**.
|
||||
- **Report a bug or idea from the console**: a megaphone button at the right of the top bar opens GitHub's new-issue chooser for `jparkerweb/plan2code`, with new **Bug** and **Idea** issue templates in `.github/ISSUE_TEMPLATE/` (blank issues off).
|
||||
- **Version in Help**: the Help dialog's footer shows the running Plan2Code version, served by a new `GET /version` route. The skill build copies `version.json` into each skill's `references/web-console/` so the console can find it.
|
||||
- **skills**: skill scripts. Every step a workflow decides with one correct answer now runs as a script the agent calls instead of prose it follows: Node 18+ built-ins only, one JSON object on stdout, documented exit codes, `--help`, `--dry-run` on writes. They install beside each `SKILL.md` in `scripts/`: shared ones from `src/skill-scripts/` (named per skill in `SOURCE_PROMPTS` → `scripts`), a skill's own from `src/<skill>-scripts/`, plus `common.mjs` and the release's `version.json`.
|
||||
- **specs.mjs** (plan, revise-plan, document, implement, implement-review, review, quick-task, finalize, handoff): `list`, `status`, `metrics`, `mark`, `archive`. It reads gitignored `specs/` directly, parses the Phase Checklist and Parallel Execution Groups in the formats real specs use, counts tasks by marker (including `3.6a` and named `1.T` tasks), applies Implementation Mode's phase-selection table, and flags drift such as a phase marked `[x]` with open tasks. It shares the dashboard's spec classifier by importing the bundled `web-console/lib.mjs`.
|
||||
- **pathfinder.mjs**: `reconcile`, `frontier`, `claim`, `resolve`, `rule-out`, `trail`, `gate`, `lint`, `brief-data` for maps on the `local` backend. The map's markers, the Trail Footer, the Clearing Gate's mechanical checks and hard caps, the standing-rule lint (loop tokens, checkboxes, reserved names, schema lines, `Blocked by:` cycles, the metrics collector's own scrape patterns) and a brief's date filtering are computed from the question files. Reconcile keeps each map row's own wording and only changes what the files contradict. Maps on the `github` backend keep doing these steps with `gh`, as `github-issues.md` describes.
|
||||
- **feedback-payload.mjs** (finalize STEP 6.5): builds the payload from the archive, with real 12-character sha256 prompt hashes (the prose admitted the agent could not compute them), renders the issue, checks the 8 KB URL limit with `--truncate`, and runs the gh / browser / print tiers against `jparkerweb/plan2code`.
|
||||
- **commit-msg.mjs**, **review-scope.mjs**, **agents-md.mjs**, **agent-files.mjs**, **handoff-path.mjs**: the commit command from the branch's ticket, Review's git scope and doc share, AGENTS.md's structure and orphans, the AI agent file sync, and the handoff's timestamped path and git ignore check.
|
||||
- **tests**: `scripts/test-skill-scripts.mjs` and `scripts/test-script-<skill>.mjs`, run by `npm test` against the built `skills/` tree. One test fails if a `SKILL.md` names a script its skill does not ship.
|
||||
- **web console**: the Workspace dialog's folders are remembered across console sessions, in `~/.plan2code/console/workspaces.json` beside `looks.json` (never in the project), keyed by the folder a session runs in and then by spec. Every change is saved. *Start from scratch* on the dashboard shows the project's list; picking a spec loads its own, which starts as a copy of the project's and is separate after that, and a spec created mid-run takes the list in force with it. The dialog says whose list it is. New `console.mjs forget --spec specs/<name>`, which Finalize's Spec Cleanup runs after archiving a spec.
|
||||
|
||||
### 🔧 Changed
|
||||
|
||||
- **skills**: the character limit for `src/plan2code-*.md` rises from 11,500 to 20,000 (about 5k tokens). It no longer guards Windsurf's old limit; it is a size discipline, applied by `validate-char-count.js` and the metrics improver alike.
|
||||
- **finalize**: a run at exactly 75% complete now finalizes with notice (the table said >75% and <75%). Assumed `[?]` tasks count as completed and are listed; started `[/]` tasks count as incomplete. `verification_items_added` and Step 7's two judgment counts are passed to the script, which computes the rest.
|
||||
- **finalize**: the community feedback issue title reads `[Feedback] v<version> - rating N/10`; ingestion matches on the `[Feedback]` prefix and is unaffected.
|
||||
- **init**, **init-update**: both write the same pointer templates, from `agent-files.mjs`. Replacing `.cursor/rules/` now also removes Cursor's own `.mdc` rule files, so AGENTS.md really is the single source there, and files that already point at AGENTS.md are no longer offered again.
|
||||
- **revise-plan**: re-opening a phase (`specs.mjs mark --to open`) also sets its phase file's Status back to In Progress.
|
||||
- **review**: the branch scope compares `base...HEAD` (what this branch added since it left the base) rather than `main..HEAD`, and a trunk other than `main` / `master` is passed with `--base`.
|
||||
- **pathfinder**: the Trail Footer's named legend numbers stops by position (`(blocked:3)` points at stop 3), and a brief's range is given as `this-week`, `since:<date>` or `<date>..<date>`.
|
||||
- **init**, **init-update**: a CLAUDE.md (or other agent file) that is a symlink or hard link to AGENTS.md is reported as `linkedToAgents` and never replaced, since writing the pointer through it would overwrite AGENTS.md. A pointer file checked out with CRLF line endings still counts as already pointing.
|
||||
- **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.
|
||||
- **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.
|
||||
|
||||
- **install.js**: the closing message beside Planny now names the dashboard first: `plan2code` from any project, or `/plan2code` in your agent when the command could not be installed. The docs link moves to the line under it.
|
||||
- **web-console**: User Preferences opens from a gear button instead of the three swatches, and the default highlight color is now ocean blue instead of rust.
|
||||
- **web-console**: the dashboard rail marks the suggested next step with a small dot, since the center pane's Suggested pill can scroll out of view. Send pulses only while it is the primary button.
|
||||
|
||||
+64
@@ -112,6 +112,11 @@ const SKILLS_DIR = path.join(__dirname, SKILLS_DIR_NAME);
|
||||
// Source prompts directory
|
||||
const SRC_DIR = path.join(__dirname, 'src');
|
||||
|
||||
// Shared skill scripts (src/skill-scripts/). A skill lists the ones it runs in its
|
||||
// `scripts` field; SHARED_SCRIPTS_ALWAYS ride along with any skill that has scripts.
|
||||
const SHARED_SCRIPTS_DIR = 'skill-scripts';
|
||||
const SHARED_SCRIPTS_ALWAYS = ['common.mjs'];
|
||||
|
||||
// ============================================================================
|
||||
// SYNC PROMPTS CONFIGURATION (merged from sync-prompts.js)
|
||||
// ============================================================================
|
||||
@@ -136,6 +141,7 @@ const SOURCE_PROMPTS = [
|
||||
displayName: 'Init Mode',
|
||||
description: 'Generate AGENTS.md file for project-specific guidance',
|
||||
isUtility: true,
|
||||
scripts: ['agents-md.mjs', 'agent-files.mjs'],
|
||||
additionalReferences: [{ source: 'web-console', target: 'web-console' }]
|
||||
},
|
||||
{
|
||||
@@ -145,6 +151,7 @@ const SOURCE_PROMPTS = [
|
||||
displayName: 'Init Update Mode',
|
||||
description: 'Update existing AGENTS.md with new learnings',
|
||||
isUtility: true,
|
||||
scripts: ['agents-md.mjs', 'agent-files.mjs', 'commit-msg.mjs'],
|
||||
additionalReferences: [{ source: 'web-console', target: 'web-console' }]
|
||||
},
|
||||
{
|
||||
@@ -164,6 +171,7 @@ const SOURCE_PROMPTS = [
|
||||
isUtility: true,
|
||||
// review.md rides along for the web console's "Review it now" button, which
|
||||
// runs the review in the same session once the quick task is built.
|
||||
scripts: ['specs.mjs', 'commit-msg.mjs', 'review-scope.mjs'],
|
||||
additionalReferences: [
|
||||
{ source: 'web-console', target: 'web-console' },
|
||||
{ source: 'plan2code-review.md', target: 'review.md' },
|
||||
@@ -176,6 +184,7 @@ const SOURCE_PROMPTS = [
|
||||
name: 'plan',
|
||||
displayName: 'Planning Mode',
|
||||
description: 'Requirements analysis and architecture design',
|
||||
scripts: ['specs.mjs'],
|
||||
additionalReferences: [{ source: 'web-console', target: 'web-console' }]
|
||||
},
|
||||
{
|
||||
@@ -184,6 +193,7 @@ const SOURCE_PROMPTS = [
|
||||
name: 'revise-plan',
|
||||
displayName: 'Revision Mode',
|
||||
description: 'Modify specs mid-implementation when requirements change',
|
||||
scripts: ['specs.mjs'],
|
||||
additionalReferences: [{ source: 'web-console', target: 'web-console' }]
|
||||
},
|
||||
{
|
||||
@@ -192,6 +202,7 @@ const SOURCE_PROMPTS = [
|
||||
name: 'document',
|
||||
displayName: 'Documentation Mode',
|
||||
description: 'Transform planning output into structured implementation docs',
|
||||
scripts: ['specs.mjs'],
|
||||
additionalReferences: [{ source: 'web-console', target: 'web-console' }]
|
||||
},
|
||||
{
|
||||
@@ -202,6 +213,7 @@ const SOURCE_PROMPTS = [
|
||||
description: 'Execute implementation phase by phase',
|
||||
// review.md rides along for the web console's review offer on the sign-off
|
||||
// card, which runs the review in the same session before the phase is approved.
|
||||
scripts: ['specs.mjs', 'commit-msg.mjs', 'review-scope.mjs'],
|
||||
additionalReferences: [
|
||||
{ source: 'web-console', target: 'web-console' },
|
||||
{ source: 'plan2code-review.md', target: 'review.md' },
|
||||
@@ -214,6 +226,7 @@ const SOURCE_PROMPTS = [
|
||||
name: 'implement-review',
|
||||
displayName: 'Implementation + Review Mode',
|
||||
description: 'Implement one phase, review it, then request sign-off',
|
||||
scripts: ['specs.mjs', 'commit-msg.mjs', 'review-scope.mjs'],
|
||||
additionalReferences: [
|
||||
{ source: 'web-console', target: 'web-console' },
|
||||
{ source: 'plan2code-3-implement.md', target: 'implement.md' },
|
||||
@@ -228,6 +241,7 @@ const SOURCE_PROMPTS = [
|
||||
displayName: 'Review Mode',
|
||||
description: 'Comprehensive post-implementation review with spec compliance checking',
|
||||
isUtility: true,
|
||||
scripts: ['specs.mjs', 'commit-msg.mjs', 'review-scope.mjs'],
|
||||
additionalReferences: [{ source: 'web-console', target: 'web-console' }]
|
||||
},
|
||||
{
|
||||
@@ -236,6 +250,7 @@ const SOURCE_PROMPTS = [
|
||||
name: 'finalize',
|
||||
displayName: 'Finalization Mode',
|
||||
description: 'Validate, summarize, and archive completed work',
|
||||
scripts: ['specs.mjs', 'commit-msg.mjs'],
|
||||
additionalReferences: [{ source: 'web-console', target: 'web-console' }]
|
||||
},
|
||||
{
|
||||
@@ -245,6 +260,7 @@ const SOURCE_PROMPTS = [
|
||||
displayName: 'Handoff Mode',
|
||||
description: 'Compact the conversation into a self-contained handoff document for a fresh session',
|
||||
isUtility: true,
|
||||
scripts: ['specs.mjs'],
|
||||
additionalReferences: [{ source: 'web-console', target: 'web-console' }]
|
||||
}
|
||||
];
|
||||
@@ -574,11 +590,57 @@ function computeExpectedSkills() {
|
||||
errors.push(`Could not include src/${reference.source} for ${skillName}: ${err.message}`);
|
||||
}
|
||||
}
|
||||
|
||||
// Scripts land flat in skills/<skill>/scripts/, beside the SKILL.md that runs them:
|
||||
// the skill's own src/<source>-scripts/ plus the shared ones it names in `scripts`
|
||||
// from src/skill-scripts/. Skills install independently, so shared code is copied
|
||||
// into each skill rather than referenced across skill directories.
|
||||
const scripts = new Map();
|
||||
const ownScriptsDir = path.join(SRC_DIR, prompt.source.replace(/\.md$/, '-scripts'));
|
||||
const sharedNames = prompt.scripts || [];
|
||||
if (sharedNames.length || fs.existsSync(ownScriptsDir)) {
|
||||
for (const name of [...SHARED_SCRIPTS_ALWAYS, ...sharedNames]) {
|
||||
const abs = path.join(SRC_DIR, SHARED_SCRIPTS_DIR, name);
|
||||
if (!fs.existsSync(abs)) {
|
||||
errors.push(`src/${SHARED_SCRIPTS_DIR}/${name} (named by ${skillName}) does not exist`);
|
||||
continue;
|
||||
}
|
||||
scripts.set(name, fs.readFileSync(abs));
|
||||
}
|
||||
if (fs.existsSync(ownScriptsDir)) {
|
||||
for (const relPath of listFilesRecursive(ownScriptsDir)) {
|
||||
const name = relPath.split(path.sep).join('/');
|
||||
if (scripts.has(name) || name === 'version.json') {
|
||||
errors.push(`src/${path.basename(ownScriptsDir)}/${name} collides with a ${name === 'version.json' ? 'generated file' : 'shared script'} of the same name`);
|
||||
continue;
|
||||
}
|
||||
scripts.set(name, fs.readFileSync(path.join(ownScriptsDir, relPath)));
|
||||
}
|
||||
}
|
||||
// The version the scripts report (the finalize feedback payload needs it, and an
|
||||
// installed skill has no repo version.json to read).
|
||||
scripts.set('version.json', fs.readFileSync(path.join(__dirname, 'version.json')));
|
||||
}
|
||||
for (const [name, content] of scripts) {
|
||||
expected.set(`${SKILLS_DIR_NAME}/${skillName}/scripts/${name}`, content);
|
||||
}
|
||||
}
|
||||
|
||||
return { expected, errors };
|
||||
}
|
||||
|
||||
/**
|
||||
* Remove empty directories below `dir` (never `dir` itself), deepest first.
|
||||
*/
|
||||
function removeEmptyDirs(dir) {
|
||||
for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
|
||||
if (!entry.isDirectory()) continue;
|
||||
const sub = path.join(dir, entry.name);
|
||||
removeEmptyDirs(sub);
|
||||
if (fs.readdirSync(sub).length === 0) fs.rmdirSync(sub);
|
||||
}
|
||||
}
|
||||
|
||||
function buildSkills(quiet = false) {
|
||||
const { expected, errors } = computeExpectedSkills();
|
||||
const stats = { written: 0, unchanged: 0, pruned: 0, errors: errors.length };
|
||||
@@ -606,6 +668,8 @@ function buildSkills(quiet = false) {
|
||||
stats.pruned++;
|
||||
if (!quiet) console.log(` ${COLORS.YELLOW}░░░${COLORS.RESET} Pruned: ${key}`);
|
||||
}
|
||||
// A folder the build no longer fills (a skill that lost all its scripts) goes too.
|
||||
removeEmptyDirs(skillDir);
|
||||
}
|
||||
|
||||
for (const [relPath, content] of expected) {
|
||||
|
||||
+1
-1
@@ -8,7 +8,7 @@
|
||||
"scripts": {
|
||||
"prepare": "husky",
|
||||
"build:skills": "node install.js --build-skills",
|
||||
"test": "node scripts/validate-char-count.js && node install.js --verify-skills && node scripts/parse-check.mjs && node scripts/check-skill-table.mjs && node --test scripts/test-web-console.mjs scripts/test-launcher.mjs"
|
||||
"test": "node scripts/validate-char-count.js && node install.js --verify-skills && node scripts/parse-check.mjs && node scripts/check-skill-table.mjs && node --test scripts/test-web-console.mjs scripts/test-launcher.mjs scripts/test-skill-scripts.mjs scripts/test-script-pathfinder.mjs scripts/test-script-finalize.mjs scripts/test-script-handoff.mjs"
|
||||
},
|
||||
"devDependencies": {
|
||||
"husky": "^9.0.0"
|
||||
|
||||
@@ -226,7 +226,7 @@ Output: `.plan2code-metrics/proposals/<timestamp>-diagnosis.md`
|
||||
Sends the diagnosis plus current prompt file contents to an AI model. The AI proposes surgical `old_text -> new_text` edits, each validated against:
|
||||
|
||||
- The `old_text` actually exists in the target file
|
||||
- The edited file stays under the 11,500 character limit
|
||||
- The edited file stays under the 20,000 character limit
|
||||
|
||||
Output: `.plan2code-metrics/proposals/prop-<timestamp>.json`
|
||||
|
||||
|
||||
@@ -11,7 +11,7 @@ import chalk from 'chalk';
|
||||
import type { PromptEdit, PromptProposal } from './types.js';
|
||||
import { validateEdit } from './improver.js';
|
||||
|
||||
const CHAR_LIMIT = 11_500;
|
||||
const CHAR_LIMIT = 20_000;
|
||||
|
||||
// ── Diff display ──────────────────────────────────────────────────────────────
|
||||
|
||||
|
||||
@@ -69,12 +69,12 @@ describe('validateEdit', () => {
|
||||
expect(result.warnings.some(w => /appears.*times/i.test(w))).toBe(true);
|
||||
});
|
||||
|
||||
it('errors when edit would exceed 11,500 char limit', () => {
|
||||
const bigText = 'x'.repeat(12_000);
|
||||
it('errors when edit would exceed 20,000 char limit', () => {
|
||||
const bigText = 'x'.repeat(21_000);
|
||||
const edit = makeEdit({ new_text: bigText });
|
||||
const result = validateEdit(edit, PROMPT_CONTENTS);
|
||||
expect(result.valid).toBe(false);
|
||||
expect(result.errors.some(e => /exceed.*11.?500/i.test(e))).toBe(true);
|
||||
expect(result.errors.some(e => /exceed.*20.?000/i.test(e))).toBe(true);
|
||||
});
|
||||
|
||||
it('warns when reported char counts diverge from actual (>10 chars off)', () => {
|
||||
|
||||
@@ -9,7 +9,7 @@ import path from 'path';
|
||||
import type { PromptEdit, PromptProposal } from './types.js';
|
||||
import { invokeLLM, type AgentType } from './invoke-llm.js';
|
||||
|
||||
const CHAR_LIMIT = 11_500;
|
||||
const CHAR_LIMIT = 20_000;
|
||||
const IMPROVE_PROMPT_PATH = new URL('../src/prompts/improve.md', import.meta.url).pathname
|
||||
.replace(/^\/([A-Za-z]:)/, '$1'); // Fix Windows path
|
||||
|
||||
|
||||
@@ -26,7 +26,7 @@ The following diagnosis was produced by the analysis step:
|
||||
|
||||
## Hard Constraints — ALL must be satisfied:
|
||||
|
||||
1. **Char limit:** Each target file MUST stay under 11,500 characters after your edit is applied. This is enforced by code — edits that violate it will be automatically rejected.
|
||||
1. **Char limit:** Each target file MUST stay under 20,000 characters after your edit is applied. This is enforced by code — edits that violate it will be automatically rejected.
|
||||
2. **Maximum 5 edits per cycle.** Focus on the highest-impact changes only.
|
||||
3. **Each edit must cite a specific metric** in its `expected_metric_impact` field (e.g., "avg_task_completion_rate", "avg_blocker_count").
|
||||
4. **`old_text` must be verbatim** from the file. Copy-paste exactly — include surrounding whitespace/newlines as they appear. Edits with mismatched old_text will be automatically rejected.
|
||||
@@ -85,7 +85,7 @@ Set `char_count_before`, `char_count_after`, and `char_count_delta` to your best
|
||||
|
||||
A table with columns: File | Before | Projected After | Delta | Limit | Status (✓/✗)
|
||||
|
||||
Verify that NO file exceeds 11,500 characters after your proposed edits.
|
||||
Verify that NO file exceeds 20,000 characters after your proposed edits.
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -0,0 +1,61 @@
|
||||
// Shared helpers for the skill-script tests (scripts/test-*script*.mjs).
|
||||
//
|
||||
// The tests run the scripts the way an agent does: as `node <skill>/scripts/x.mjs`
|
||||
// from the built skills/ tree, against throwaway fixtures in the OS temp dir,
|
||||
// with the clock pinned by PLAN2CODE_NOW. They live in scripts/ so nothing
|
||||
// here ships.
|
||||
|
||||
import fs from "node:fs";
|
||||
import os from "node:os";
|
||||
import path from "node:path";
|
||||
import { spawnSync, execFileSync } from "node:child_process";
|
||||
import { fileURLToPath } from "node:url";
|
||||
|
||||
export const ROOT = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
|
||||
export const SKILLS = path.join(ROOT, "skills");
|
||||
export const NOW = "2026-08-03 14:05";
|
||||
|
||||
// Rebuild skills/ on every import, not only when it is missing: a test file run
|
||||
// directly after an edit to src/ must not test a stale tree. The build is
|
||||
// idempotent and takes well under a second.
|
||||
execFileSync(process.execPath, [path.join(ROOT, "install.js"), "--build-skills"], { stdio: "ignore" });
|
||||
|
||||
export function runScript(skill, script, args, { cwd, env } = {}) {
|
||||
const r = spawnSync(process.execPath, [path.join(SKILLS, skill, "scripts", script), ...args], {
|
||||
cwd: cwd || ROOT,
|
||||
encoding: "utf8",
|
||||
env: { ...process.env, PLAN2CODE_NOW: NOW, GIT_CONFIG_NOSYSTEM: "1", ...env },
|
||||
});
|
||||
let json = null;
|
||||
try {
|
||||
json = JSON.parse(r.stdout);
|
||||
} catch {}
|
||||
return { code: r.status, json, stdout: r.stdout, stderr: r.stderr };
|
||||
}
|
||||
|
||||
export function tmp(name) {
|
||||
return fs.mkdtempSync(path.join(fs.realpathSync.native(os.tmpdir()), `p2c-${name}-`));
|
||||
}
|
||||
|
||||
export function write(root, rel, content) {
|
||||
const p = path.join(root, rel);
|
||||
fs.mkdirSync(path.dirname(p), { recursive: true });
|
||||
fs.writeFileSync(p, content);
|
||||
return p;
|
||||
}
|
||||
|
||||
export const read = (root, rel) => fs.readFileSync(path.join(root, rel), "utf8");
|
||||
|
||||
export function gitInit(dir, branch = "main") {
|
||||
const g = (...a) => execFileSync("git", a, { cwd: dir, stdio: "pipe", encoding: "utf8" });
|
||||
g("init", "-q", "-b", branch);
|
||||
g("config", "user.email", "t@example.com");
|
||||
g("config", "user.name", "Test");
|
||||
g("config", "commit.gpgsign", "false");
|
||||
return g;
|
||||
}
|
||||
|
||||
/** A phase-N.md in the Documentation template's shape. tasks: [[marker, id], ...] */
|
||||
export function phase(n, status, tasks, extra = "") {
|
||||
return `# Phase ${n}: Name ${n}\n\n**Status:** ${status}\n**Estimated Tasks:** ${tasks.length}\n\n## Overview\n\nPhase ${n} builds the thing. More words here.\n\n## Prerequisites\n\n- Something exists\n\n## Tasks\n\n${tasks.map(([m, id]) => `- [${m}] **Task ${id}:** Do ${id}`).join("\n")}\n${extra}\n## Acceptance Criteria\n\n- It works\n`;
|
||||
}
|
||||
@@ -0,0 +1,174 @@
|
||||
// Tests for plan2code-4-finalize's scripts/feedback-payload.mjs.
|
||||
//
|
||||
// See skill-script-helpers.mjs for how these run.
|
||||
|
||||
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 crypto from "node:crypto";
|
||||
import { ROOT, SKILLS, NOW, runScript, tmp, write, read, gitInit, phase } from "./skill-script-helpers.mjs";
|
||||
|
||||
/* ========================================================= feedback-payload.mjs */
|
||||
|
||||
test("feedback-payload: payload from the archive, real prompt hashes, size and truncation", () => {
|
||||
const root = tmp("fb");
|
||||
const spec = "specs--completed/lunch-vote";
|
||||
write(root, `${spec}/PLAN-DRAFT-20260801.md`, '# Plan\n\n<!-- METRICS_JSON {"confidence": 92, "clarification_rounds": 1, "functional_requirements_count": 5, "non_functional_requirements_count": 2, "risk_count": 3, "phase_count": 2, "verification_gaps_found": 0, "confidence_breakdown": {"requirements": 24, "feasibility": 23, "integration": 23, "risk": 22}} -->\n');
|
||||
write(root, `${spec}/overview.md`, '# O\n\n<!-- METRICS_JSON {"step": "document", "total_tasks": 3, "tasks_per_phase": [2, 1], "phase_count": 2, "parallel_groups_identified": 0, "verification_items_added": 1} -->\n\n## User Feedback\n| Field | Value |\n|-------|-------|\n| Rating | 8 |\n| Reason | Good \\| fast |\n| Went Well | Specs |\n| Went Poorly | Review |\n');
|
||||
write(root, `${spec}/phase-1.md`, phase(1, "Complete", [["x", "1.1"], ["x", "1.T"]]));
|
||||
write(root, `${spec}/phase-2.md`, phase(2, "Complete", [["!", "2.1"]]));
|
||||
const outDir = path.join(root, "out");
|
||||
const F = (...a) => runScript("plan2code-4-finalize", "feedback-payload.mjs", [...a, "--root", root]);
|
||||
assert.equal(F("build", "lunch-vote", "--out", outDir).code, 2, "the two judgment counts are required");
|
||||
const b = F("build", "lunch-vote", "--out", outDir, "--set", "verification_failures_found=1", "--set", "documentation_updates_needed=2");
|
||||
assert.equal(b.code, 0, b.stderr);
|
||||
const p = b.json.payload;
|
||||
assert.match(p.run_id, /^run-20260803-140500-[0-9a-f]{4}$/);
|
||||
assert.equal(p.plan2code_version, JSON.parse(fs.readFileSync(path.join(ROOT, "version.json"), "utf8")).version);
|
||||
const srcHash = crypto.createHash("sha256").update(fs.readFileSync(path.join(ROOT, "src", "plan2code-1-plan.md"), "utf8")).digest("hex").slice(0, 12);
|
||||
assert.equal(p.prompt_versions_short.plan, srcHash, "the hash is the src prompt's, recovered from the installed SKILL.md");
|
||||
assert.ok(Object.values(p.prompt_versions_short).every((v) => /^[0-9a-f]{12}$/.test(v)));
|
||||
assert.deepEqual(p.step1.confidence_breakdown, { requirements: 24, feasibility: 23, integration: 23, risk: 22 });
|
||||
assert.equal(p.step1.final_confidence, 92);
|
||||
assert.equal(p.step2.total_tasks, 3);
|
||||
assert.deepEqual(p.step3, { task_completion_rate: 0.67, tasks_completed: 2, tasks_total: 3, blocker_count: 1 });
|
||||
assert.deepEqual(p.step4, { completion_rate_at_audit: 0.67, verification_failures_found: 1, documentation_updates_needed: 2, archival_succeeded: true });
|
||||
assert.deepEqual(p.user_feedback, { overall_rating: 8, rating_reason: "Good | fast", what_went_well: "Specs", what_went_poorly: "Review" });
|
||||
assert.equal(b.json.title, `[Feedback] v${p.plan2code_version} - rating 8/10`);
|
||||
assert.match(b.json.body, /<!-- METRICS_JSON \{"schema_version":"1\.0"/);
|
||||
assert.ok(!/[—]/.test(b.json.title), "no em dash in the issue title");
|
||||
assert.equal(b.json.oversize, false);
|
||||
assert.ok(fs.existsSync(path.join(outDir, "body.md")));
|
||||
// The ingest side parses the body back.
|
||||
const parsed = JSON.parse(b.json.body.match(/<!--\s*METRICS_JSON\s+(\{[\s\S]*?\})\s*-->/)[1]);
|
||||
assert.equal(parsed.schema_version, "1.0");
|
||||
// Oversize, then truncate.
|
||||
const ov = path.join(root, spec, "overview.md");
|
||||
fs.writeFileSync(ov, fs.readFileSync(ov, "utf8").replace("| Good \\| fast |", `| ${"long reason ".repeat(500)} |`));
|
||||
const big = F("build", "lunch-vote", "--out", outDir, "--set", "verification_failures_found=1", "--set", "documentation_updates_needed=2");
|
||||
assert.equal(big.json.oversize, true);
|
||||
assert.match(big.json.next, /--truncate/);
|
||||
const cut = F("build", "lunch-vote", "--out", outDir, "--set", "verification_failures_found=1", "--set", "documentation_updates_needed=2", "--truncate");
|
||||
assert.equal(cut.json.oversize, false);
|
||||
assert.deepEqual(cut.json.truncated, ["rating_reason"]);
|
||||
const dry = runScript("plan2code-4-finalize", "feedback-payload.mjs", ["submit", "--from", outDir, "--dry-run"]);
|
||||
assert.equal(dry.code, 0);
|
||||
assert.match(dry.json.tiers[0], /^gh issue create --repo jparkerweb\/plan2code .*--label community-feedback$/);
|
||||
assert.equal(dry.json.oversize, false);
|
||||
assert.equal(dry.json.urlBytes, cut.json.urlBytes);
|
||||
fs.writeFileSync(ov, "# O\n");
|
||||
assert.equal(F("build", "lunch-vote", "--set", "verification_failures_found=1", "--set", "documentation_updates_needed=2").code, 3, "no feedback table, nothing to submit");
|
||||
});
|
||||
|
||||
/* ================================================= verification regressions */
|
||||
|
||||
test("feedback-payload: truncation always ends, '-->' survives ingest, lenient rating, absent steps are null", () => {
|
||||
const root = tmp("fb2");
|
||||
const spec = "specs--completed/x";
|
||||
const long = (w) => `${w} `.repeat(400).trim();
|
||||
// The visible answers carry markup that must stay text: a stray comment
|
||||
// opener, and a fake payload comment an ingest regex could match first.
|
||||
const fake = '<!-- METRICS_JSON {"schema_version":"1.0"} -->';
|
||||
const inputs = { rating_reason: `see {a} --> b <!-- x ${long("reason")}`, what_went_well: `${fake} ${long("well")}`, what_went_poorly: long("poorly") };
|
||||
write(root, `${spec}/overview.md`, `# O\n\n## User Feedback\n| field | value |\n|---|---|\n| rating | 8/10 |\n| reason | ${inputs.rating_reason} |\n| went well | ${inputs.what_went_well} |\n| went poorly | ${inputs.what_went_poorly} |\n`);
|
||||
write(root, `${spec}/phase-1.md`, phase(1, "Complete", [["x", "1.1"]]));
|
||||
const F = (...a) => runScript("plan2code-4-finalize", "feedback-payload.mjs", [...a, "--root", root]);
|
||||
const sets = ["--set", "verification_failures_found=0", "--set", "documentation_updates_needed=0"];
|
||||
assert.equal(F("build", "x", ...sets, "--set", "bogus=1").code, 2);
|
||||
// Untruncated, the first METRICS_JSON match is the real payload: its answers
|
||||
// come back exactly as typed, not the fake's bare schema_version.
|
||||
const whole = F("build", "x", ...sets, "--out", path.join(root, "whole"));
|
||||
assert.equal(whole.code, 0, whole.stderr);
|
||||
const first = JSON.parse(whole.json.body.match(/<!--\s*METRICS_JSON\s+(\{[\s\S]*?\})\s*-->/)[1]);
|
||||
assert.deepEqual(first.user_feedback, { overall_rating: 8, ...inputs });
|
||||
assert.equal(whole.json.body.split("<!--").length - 1, 1, "the payload's is the only comment that opens");
|
||||
assert.ok(!/<!--(?! METRICS_JSON \{"schema_version":"1\.0","run_id")/.test(whole.json.body), "no comment opens before the payload's");
|
||||
const r = spawnSync(process.execPath, [path.join(SKILLS, "plan2code-4-finalize", "scripts", "feedback-payload.mjs"), "build", "x", ...sets, "--truncate", "--out", path.join(root, "out"), "--root", root], { encoding: "utf8", timeout: 20000, env: { ...process.env, PLAN2CODE_NOW: NOW } });
|
||||
assert.equal(r.status, 0, "build --truncate finishes with every field long");
|
||||
const j = JSON.parse(r.stdout);
|
||||
assert.equal(j.oversize, false);
|
||||
assert.deepEqual(j.truncated, ["rating_reason", "what_went_well", "what_went_poorly"]);
|
||||
assert.equal(j.payload.user_feedback.overall_rating, 8, "8/10 reads as 8, field names in any case");
|
||||
assert.equal(j.payload.step1, null);
|
||||
assert.equal(j.payload.step2, null);
|
||||
// The ingest side's own extraction regex (plan2code-metrics collector.ts).
|
||||
const m = j.body.match(/<!--\s*METRICS_JSON\s+(\{[\s\S]*?\})\s*-->/);
|
||||
const back = JSON.parse(m[1]);
|
||||
assert.match(back.user_feedback.rating_reason, /^see \{a\} --> b <!-- x/);
|
||||
assert.equal(back.user_feedback.what_went_well, j.payload.user_feedback.what_went_well);
|
||||
assert.match(back.user_feedback.what_went_well, /^<!-- METRICS_JSON/, "the fake comment is still just text in the real payload");
|
||||
assert.ok(!/<!--(?! METRICS_JSON \{"schema_version":"1\.0","run_id")/.test(j.body), "no comment opens before the payload's");
|
||||
});
|
||||
|
||||
test("feedback-payload: --truncate never splits an emoji", () => {
|
||||
const root = tmp("fb3");
|
||||
const spec = "specs--completed/x";
|
||||
const reason = "a" + "\u{1F44D}".repeat(400);
|
||||
write(root, `${spec}/overview.md`, `# O\n\n## User Feedback\n| Field | Value |\n|---|---|\n| Rating | 9 |\n| Reason | ${reason} |\n| Went Well | ok |\n| Went Poorly | none |\n`);
|
||||
write(root, `${spec}/phase-1.md`, phase(1, "Complete", [["x", "1.1"]]));
|
||||
const r = runScript("plan2code-4-finalize", "feedback-payload.mjs", ["build", "x", "--set", "verification_failures_found=0", "--set", "documentation_updates_needed=0", "--truncate", "--out", path.join(root, "out"), "--root", root]);
|
||||
assert.equal(r.code, 0, r.stderr);
|
||||
assert.equal(r.json.oversize, false);
|
||||
assert.deepEqual(r.json.truncated, ["rating_reason"]);
|
||||
const back = JSON.parse(r.json.body.match(/<!--\s*METRICS_JSON\s+(\{[\s\S]*?\})\s*-->/)[1]);
|
||||
assert.equal(back.user_feedback.rating_reason, r.json.payload.user_feedback.rating_reason);
|
||||
assert.ok(!/[\uD800-\uDBFF](?![\uDC00-\uDFFF])/.test(back.user_feedback.rating_reason), "no lone high surrogate");
|
||||
assert.match(back.user_feedback.rating_reason, /^a(\u{1F44D})+\.\.\.$/u);
|
||||
});
|
||||
|
||||
test("feedback-payload: task counts read the same phase files specs.mjs does, never a stale sibling", () => {
|
||||
const root = tmp("fb5");
|
||||
const spec = "specs--completed/x";
|
||||
write(root, `${spec}/overview.md`, "# O\n\n## User Feedback\n| Field | Value |\n|---|---|\n| Rating | 7 |\n| Reason | r |\n| Went Well | w |\n| Went Poorly | p |\n");
|
||||
write(root, `${spec}/phase-1.md`, phase(1, "Complete", [["x", "1.1"], ["x", "1.2"]]));
|
||||
write(root, `${spec}/phase-1-old.md`, phase(1, "Not Started", [[" ", "1.1"], [" ", "1.2"], [" ", "1.3"]]));
|
||||
const r = runScript("plan2code-4-finalize", "feedback-payload.mjs", ["build", "x", "--set", "verification_failures_found=0", "--set", "documentation_updates_needed=0", "--out", path.join(root, "out"), "--root", root]);
|
||||
assert.equal(r.code, 0, r.stderr);
|
||||
assert.deepEqual(r.json.payload.step3, { task_completion_rate: 1, tasks_completed: 2, tasks_total: 2, blocker_count: 0 });
|
||||
const m = runScript("plan2code-4-finalize", "specs.mjs", ["metrics", spec, "--step", "finalize", "--set", "verification_failures_found=0", "--set", "documentation_updates_needed=0", "--root", root]);
|
||||
assert.equal(m.code, 0, m.stderr);
|
||||
assert.equal(m.json.metrics.tasks_total, r.json.payload.step3.tasks_total);
|
||||
assert.equal(m.json.metrics.tasks_completed, r.json.payload.step3.tasks_completed);
|
||||
});
|
||||
|
||||
test("feedback-payload: a bare name in both specs/ and specs--completed/ is ambiguous", () => {
|
||||
const root = tmp("fb4");
|
||||
const table = (rating) => `# O\n\n## User Feedback\n| Field | Value |\n|---|---|\n| Rating | ${rating} |\n| Reason | r |\n| Went Well | w |\n| Went Poorly | p |\n`;
|
||||
write(root, "specs--completed/x/overview.md", table(3));
|
||||
write(root, "specs/x/overview.md", table(7));
|
||||
const sets = ["--set", "verification_failures_found=0", "--set", "documentation_updates_needed=0"];
|
||||
const F = (...a) => runScript("plan2code-4-finalize", "feedback-payload.mjs", [...a, ...sets, "--out", path.join(root, "out"), "--root", root]);
|
||||
const bare = F("build", "x");
|
||||
assert.equal(bare.code, 5);
|
||||
assert.equal(bare.json.error, "ambiguous-spec");
|
||||
assert.match(bare.json.next, /specs\/x/);
|
||||
const live = F("build", "specs/x");
|
||||
assert.equal(live.code, 0, live.stderr);
|
||||
assert.equal(live.json.payload.user_feedback.overall_rating, 7, "the exact path reads this run, not the old archive");
|
||||
assert.equal(live.json.payload.step4.archival_succeeded, false);
|
||||
});
|
||||
|
||||
test("feedback-payload: submit refuses an oversize URL when gh fails, and dry-run says so", () => {
|
||||
const root = tmp("fb5");
|
||||
write(root, "specs--completed/x/overview.md", `# O\n\n## User Feedback\n| Field | Value |\n|---|---|\n| Rating | 6 |\n| Reason | ${"long reason ".repeat(800)} |\n| Went Well | w |\n| Went Poorly | p |\n`);
|
||||
const outDir = path.join(root, "out");
|
||||
const b = runScript("plan2code-4-finalize", "feedback-payload.mjs", ["build", "x", "--set", "verification_failures_found=0", "--set", "documentation_updates_needed=0", "--out", outDir, "--root", root]);
|
||||
assert.equal(b.json.oversize, true);
|
||||
const dry = runScript("plan2code-4-finalize", "feedback-payload.mjs", ["submit", "--from", outDir, "--dry-run"]);
|
||||
assert.equal(dry.code, 0);
|
||||
assert.equal(dry.json.oversize, true);
|
||||
assert.equal(dry.json.urlBytes, b.json.urlBytes);
|
||||
// gh must never succeed here: no PATH but node's own folder (so gh is not
|
||||
// found), and should one turn up anyway, an empty config, no token and a
|
||||
// host that does not resolve.
|
||||
const env = Object.fromEntries(Object.entries(process.env).filter(([k]) => !/^(path|gh_|github_token$)/i.test(k)));
|
||||
Object.assign(env, { PATH: path.dirname(process.execPath), GH_CONFIG_DIR: tmp("fb5-gh"), GH_HOST: "gh.invalid", PLAN2CODE_NOW: NOW });
|
||||
const r = spawnSync(process.execPath, [path.join(SKILLS, "plan2code-4-finalize", "scripts", "feedback-payload.mjs"), "submit", "--from", outDir], { cwd: root, encoding: "utf8", timeout: 70000, env });
|
||||
assert.equal(r.status, 4, r.stderr);
|
||||
const j = JSON.parse(r.stdout);
|
||||
assert.equal(j.error, "oversize");
|
||||
assert.match(j.next, /--truncate/);
|
||||
assert.match(j.next, /gh/);
|
||||
});
|
||||
@@ -0,0 +1,55 @@
|
||||
// Tests for plan2code-handoff's scripts/handoff-path.mjs.
|
||||
//
|
||||
// See skill-script-helpers.mjs for how these run.
|
||||
|
||||
import { test } from "node:test";
|
||||
import assert from "node:assert/strict";
|
||||
import fs from "node:fs";
|
||||
import path from "node:path";
|
||||
import { ROOT, SKILLS, NOW, runScript, tmp, write, read, gitInit, phase } from "./skill-script-helpers.mjs";
|
||||
|
||||
/* =========================================================== handoff-path.mjs */
|
||||
|
||||
test("handoff-path: timestamped name, no overwrite, git ignore check", () => {
|
||||
const repo = tmp("handoff");
|
||||
gitInit(repo);
|
||||
const H = (...a) => runScript("plan2code-handoff", "handoff-path.mjs", a, { cwd: repo });
|
||||
const first = H("--dir", "handoffs");
|
||||
assert.equal(first.code, 0, first.stderr);
|
||||
assert.equal(path.basename(first.json.path), "2026-08-03-1405-handoff.md");
|
||||
assert.equal(first.json.created, true);
|
||||
assert.equal(first.json.git.inRepo, true);
|
||||
assert.equal(first.json.git.ignored, false);
|
||||
assert.match(first.json.warning, /handoffs\//);
|
||||
fs.writeFileSync(first.json.path, "x");
|
||||
assert.equal(path.basename(H("--dir", "handoffs").json.path), "2026-08-03-1405-2-handoff.md");
|
||||
write(repo, ".gitignore", "handoffs/\n");
|
||||
assert.equal(H("--dir", "handoffs").json.git.ignored, true);
|
||||
const temp = H();
|
||||
assert.equal(temp.json.git.inRepo, false);
|
||||
assert.equal(temp.json.git.ignored, null);
|
||||
const dry = runScript("plan2code-handoff", "handoff-path.mjs", ["--dir", "later", "--dry-run"], { cwd: repo });
|
||||
assert.equal(dry.json.created, false);
|
||||
assert.ok(!fs.existsSync(path.join(repo, "later")));
|
||||
});
|
||||
|
||||
/* ================================================= verification regressions */
|
||||
|
||||
test("handoff-path: the repo root itself is never the line to ignore", () => {
|
||||
const repo = tmp("handoff2");
|
||||
gitInit(repo);
|
||||
const j = runScript("plan2code-handoff", "handoff-path.mjs", ["--dir", "."], { cwd: repo }).json;
|
||||
assert.equal(j.git.inRepo, true);
|
||||
assert.equal(j.git.ignoreLine, "*-handoff.md");
|
||||
});
|
||||
|
||||
test("handoff-path: --dir naming an existing file is refused", () => {
|
||||
const repo = tmp("handoff3");
|
||||
write(repo, "notes.txt", "x");
|
||||
const r = runScript("plan2code-handoff", "handoff-path.mjs", ["--dir", "notes.txt"], { cwd: repo });
|
||||
assert.equal(r.code, 5);
|
||||
assert.equal(r.json.ok, false);
|
||||
assert.equal(r.json.error, "not-a-folder");
|
||||
assert.match(r.json.next, /--dir temp/);
|
||||
assert.equal(runScript("plan2code-handoff", "handoff-path.mjs", ["--dir", "notes.txt", "--dry-run"], { cwd: repo }).code, 5, "dry-run refuses it too");
|
||||
});
|
||||
@@ -0,0 +1,545 @@
|
||||
// Tests for plan2code-0-pathfinder's scripts/pathfinder.mjs.
|
||||
//
|
||||
// See skill-script-helpers.mjs for how these run.
|
||||
|
||||
import { test } from "node:test";
|
||||
import assert from "node:assert/strict";
|
||||
import fs from "node:fs";
|
||||
import path from "node:path";
|
||||
import { ROOT, SKILLS, NOW, runScript, tmp, write, read, gitInit, phase } from "./skill-script-helpers.mjs";
|
||||
|
||||
/* ============================================================ pathfinder.mjs */
|
||||
|
||||
const B = "> Pathfinder planning note - decisions, not implementation work. Archive with the spec; do not delete.";
|
||||
|
||||
function q(name, { type = "grill · HITL", state = "open", blocked = "none", claimed = "none", resolved = "none", locked = "no", answer = null, evidence = null, skipResolved = false } = {}) {
|
||||
return [
|
||||
B, "", `# ${name}`, "", `Type: ${type}`, `State: ${state}`, `Blocked by: ${blocked}`, `Claimed: ${claimed}`,
|
||||
...(skipResolved ? [] : [`Resolved: ${resolved}`]), `Locked: ${locked}`, "", "## Question", "", `What about ${name}?`, "",
|
||||
...(answer ? ["## Answer", "", answer, ""] : []),
|
||||
...(evidence ? ["## Evidence", "", evidence, ""] : []),
|
||||
].join("\n");
|
||||
}
|
||||
|
||||
const MAP = `${B}
|
||||
|
||||
# Map: audit-export
|
||||
|
||||
*Decisions live in \`questions/\` — one file each. This file is just the index.*
|
||||
|
||||
**Status:** Working
|
||||
**Updated:** 2026-08-01
|
||||
**Confidence:** Requirements-clarity 19/25 · Feasibility-technical 14/25 · Integration-points 20/25 · Risk-assessment 18/25
|
||||
|
||||
## Destination
|
||||
|
||||
A locked plan for exporting audit events.
|
||||
|
||||
## Ground rules
|
||||
|
||||
- \`AGENTS.md\` exists and governs.
|
||||
|
||||
## Question Checklist
|
||||
|
||||
<!-- Rebuilt from questions/ every session. -->
|
||||
|
||||
- [x] [Codebase context](./questions/00-codebase-context.md) — Node and Postgres; a long gist
|
||||
that wraps onto a second line. *(2026-08-01)*
|
||||
- [ ] [Export format](./questions/01-export-format.md)
|
||||
- [ ] [Row-count
|
||||
ceiling](./questions/02-row-count-ceiling.md)
|
||||
- [ ] [Testing posture](./questions/03-testing-posture.md)
|
||||
- [ ] [Delivery channel](./questions/04-delivery-channel.md)
|
||||
- [ ] [Gone question](./questions/09-gone.md)
|
||||
|
||||
## Not yet specified
|
||||
|
||||
- How far back an export may reach.
|
||||
|
||||
## Out of scope
|
||||
|
||||
- Redesign of the schema.
|
||||
`;
|
||||
|
||||
function mapFixture() {
|
||||
const root = tmp("pf");
|
||||
write(root, "AGENTS.md", "# AGENTS.md\n");
|
||||
const pf = "specs/audit-export/pathfinder";
|
||||
write(root, `${pf}/map.md`, MAP);
|
||||
write(root, `${pf}/questions/00-codebase-context.md`, q("Codebase context", { type: "legwork · AFK", state: "resolved", claimed: "2026-08-01 09:00", resolved: "2026-08-01", answer: "Node.\n\n**Gist:** Node and Postgres." }));
|
||||
// An answer under State: open (a crash after writing the answer): reconcile resolves it and backfills the date.
|
||||
write(root, `${pf}/questions/01-export-format.md`, q("Export format", { claimed: "2026-08-02 10:00", locked: "yes", answer: "**Decision.** CSV.\n\n**Rejected**\n\n- *JSONL* - recipients use Excel.\n\n**Gist:** CSV with a BOM.", skipResolved: true }));
|
||||
// A stale claim with no answer: reset.
|
||||
write(root, `${pf}/questions/02-row-count-ceiling.md`, q("Row-count ceiling", { type: "research · AFK", state: "claimed", claimed: "2026-08-02 11:00", evidence: "- half done" }));
|
||||
write(root, `${pf}/questions/03-testing-posture.md`, q("Testing posture"));
|
||||
write(root, `${pf}/questions/04-delivery-channel.md`, q("Delivery channel", { blocked: "02" }));
|
||||
write(root, `${pf}/questions/05-siem-push.md`, q("SIEM push", { state: "out-of-scope" }));
|
||||
return { root, pf };
|
||||
}
|
||||
|
||||
test("pathfinder reconcile: files win, dates backfill, stale claims reset, rows keep their words", () => {
|
||||
const { root, pf } = mapFixture();
|
||||
const P = (...a) => runScript("plan2code-0-pathfinder", "pathfinder.mjs", [...a, "--root", root]);
|
||||
const dry = P("reconcile", "audit-export", "--dry-run");
|
||||
assert.equal(dry.code, 0, dry.stderr);
|
||||
assert.equal(read(root, `${pf}/map.md`), MAP, "dry-run writes nothing");
|
||||
const r = P("reconcile", "audit-export");
|
||||
assert.deepEqual(r.json.repairs.map((x) => [x.nn, x.repair]), [["01", "state-resolved"], ["01", "resolved-backfilled"], ["02", "stale-claim-reset"]]);
|
||||
assert.match(r.json.repairs[1].detail, /2026-08-02 \(from Claimed:\)/);
|
||||
assert.deepEqual(r.json.refire.map((x) => x.nn), ["02"], "research with no Research complete line is re-fired");
|
||||
assert.equal(r.json.refire[0].partialEvidence, true);
|
||||
const map = read(root, `${pf}/map.md`);
|
||||
assert.match(map, /- \[x\] \[Codebase context\]\(\.\/questions\/00-codebase-context\.md\) — Node and Postgres; a long gist\n that wraps onto a second line\. \*\(2026-08-01\)\*/, "an unchanged row keeps its own wrapped text");
|
||||
assert.match(map, /- \[x\] \[Export format\]\(\.\/questions\/01-export-format\.md\) — CSV with a BOM\. \*\(2026-08-02\)\*/);
|
||||
assert.match(map, /- \[ \] \[Row-count\n ceiling\]\(\.\/questions\/02-row-count-ceiling\.md\)/, "a wrapped link is still one row");
|
||||
assert.match(map, /- \[!\] \[Delivery channel\]\(\.\/questions\/04-delivery-channel\.md\) — Blocked by 02/);
|
||||
assert.match(map, /- \[-\] \[SIEM push\]\(\.\/questions\/05-siem-push\.md\) — out of scope, see below/);
|
||||
assert.ok(!map.includes("09-gone"), "a row with no file is dropped");
|
||||
assert.match(map, /<!-- Rebuilt from questions\/ every session\. -->/);
|
||||
const q1 = read(root, `${pf}/questions/01-export-format.md`);
|
||||
assert.match(q1, /State: resolved\nBlocked by: none\nClaimed: 2026-08-02 10:00\nResolved: 2026-08-02\nLocked: yes/, "Resolved: inserted in schema order");
|
||||
assert.match(read(root, `${pf}/questions/02-row-count-ceiling.md`), /State: open\nBlocked by: none\nClaimed: none/);
|
||||
const again = P("reconcile", "audit-export");
|
||||
assert.deepEqual([again.json.repairs.length, again.json.mapChanges.length, again.json.mapWritten], [0, 0, false], "idempotent");
|
||||
});
|
||||
|
||||
test("pathfinder frontier, claim, resolve, rule-out", () => {
|
||||
const { root, pf } = mapFixture();
|
||||
const P = (...a) => runScript("plan2code-0-pathfinder", "pathfinder.mjs", [...a, "--root", root]);
|
||||
P("reconcile", "audit-export");
|
||||
let f = P("frontier", `${pf}`).json;
|
||||
assert.deepEqual(f.frontier.map((x) => x.nn), ["02", "03"]);
|
||||
assert.deepEqual(f.blocked.map((x) => [x.nn, x.blockedBy.map((b) => b.nn)]), [["04", ["02"]]]);
|
||||
assert.equal(f.nextNN, "10", "09 was linked from the map before reconcile dropped its row: never reissued");
|
||||
assert.match(read(root, `${pf}/map.md`), /^\*\*Confidence:\*\*.*\n\*\*Next NN:\*\* 10$/m, "reconcile keeps the high-water mark at the end of the header block");
|
||||
assert.deepEqual(f.counts, { resolved: 2, total: 5, outOfScope: 1, fog: 1 });
|
||||
assert.deepEqual(f.drift, []);
|
||||
assert.equal(P("claim", "audit-export", "04").code, 5, "blocked");
|
||||
assert.equal(P("claim", "audit-export", "05").code, 5, "out of scope");
|
||||
assert.equal(P("claim", "audit-export", "77").code, 3);
|
||||
const c = P("claim", "audit-export", "2");
|
||||
assert.equal(c.code, 0, c.stderr);
|
||||
assert.equal(c.json.claimed, NOW);
|
||||
assert.match(read(root, `${pf}/questions/02-row-count-ceiling.md`), /State: claimed\nBlocked by: none\nClaimed: 2026-08-03 14:05/);
|
||||
assert.match(read(root, `${pf}/map.md`), /- \[\/\] \[Row-count\n ceiling\]/);
|
||||
assert.equal(P("claim", "audit-export", "03").json.error, "claim-open", "one claim at a time");
|
||||
assert.equal(P("resolve", "audit-export", "02").json.error, "no-answer");
|
||||
const qp = path.join(root, pf, "questions/02-row-count-ceiling.md");
|
||||
fs.appendFileSync(qp, "\n## Answer\n\nFacts.\n");
|
||||
assert.equal(P("resolve", "audit-export", "02").json.error, "no-gist");
|
||||
fs.appendFileSync(qp, "\n**Gist:** 2M rows at the 99th percentile.\n");
|
||||
const res = P("resolve", "audit-export", "02");
|
||||
assert.equal(res.code, 0, res.stderr);
|
||||
assert.deepEqual(res.json.unblocked, [{ nn: "04", name: "Delivery channel" }]);
|
||||
const map = read(root, `${pf}/map.md`);
|
||||
assert.match(map, /- \[x\] \[Row-count ceiling\]\(\.\/questions\/02-row-count-ceiling\.md\) — 2M rows at the 99th percentile\. \*\(2026-08-03\)\*/);
|
||||
assert.match(map, /- \[ \] \[Delivery channel\]\(\.\/questions\/04-delivery-channel\.md\)\n/, "the Blocked by tail goes with the [!] marker");
|
||||
assert.match(map, /^\*\*Updated:\*\* 2026-08-03$/m);
|
||||
const ro = P("rule-out", "audit-export", "03", "--reason", "testing is owned elsewhere");
|
||||
assert.equal(ro.code, 0, ro.stderr);
|
||||
assert.match(read(root, `${pf}/questions/03-testing-posture.md`), /State: out-of-scope[\s\S]*## Question\n\nOut of scope: testing is owned elsewhere/);
|
||||
assert.match(read(root, `${pf}/map.md`), /## Out of scope\n\n- Redesign of the schema\.\n- \[Testing posture\]\(\.\/questions\/03-testing-posture\.md\) — testing is owned elsewhere/);
|
||||
assert.equal(P("rule-out", "audit-export", "04").code, 2, "--reason is required");
|
||||
assert.equal(P("rule-out", "audit-export", "00", "--reason", "x").code, 5, "a resolved decision is not ruled out");
|
||||
});
|
||||
|
||||
test("pathfinder trail: exact footer for forms A, B and C", () => {
|
||||
const { root, pf } = mapFixture();
|
||||
const P = (...a) => runScript("plan2code-0-pathfinder", "pathfinder.mjs", [...a, "--root", root]);
|
||||
P("reconcile", "audit-export");
|
||||
P("claim", "audit-export", "03");
|
||||
const b = P("trail", "audit-export", "--form", "B", "--item", "Q1 Types", "--item", "Q2 Cadence", "--text");
|
||||
assert.equal(b.code, 0, b.stderr);
|
||||
assert.equal(b.stdout, [
|
||||
"🧭 audit-export · Working · 2/5 cleared",
|
||||
" START ●━●··○━◉··⊘··⊝ ····⚑",
|
||||
" ● done · ◉ here · ○ open · ⊘ blocked · ⊝ out of scope · ⚑ destination · ~1 fog",
|
||||
" 1 Codebase context ✔ · 2 Export format ✔ · 3 Row-count ceiling · 4 Testing posture ◀ here",
|
||||
" 5 Delivery channel (blocked:3) · 6 SIEM push (out of scope)",
|
||||
" Confidence: not yet — Feasibility still needs work.",
|
||||
"",
|
||||
"WAITING ON YOU · answer here, in this conversation:",
|
||||
"Q1 Types · Q2 Cadence",
|
||||
"",
|
||||
].join("\n"));
|
||||
assert.equal(P("trail", "audit-export", "--form", "B").code, 2, "Form B names its items");
|
||||
assert.equal(P("trail", "audit-export", "--form", "B", "--item", "1", "--item", "2", "--item", "3", "--item", "4").code, 5, "three-probe cap");
|
||||
assert.equal(P("trail", "audit-export", "--form", "C").json.error, "claim-open", "no menu while a claim is open");
|
||||
const a = P("trail", "audit-export", "--form", "A", "--text").stdout;
|
||||
assert.ok(a.endsWith("NEXT STEP · start a new conversation and run:\n`/plan2code-0-pathfinder specs/audit-export/pathfinder --web`\n"), a);
|
||||
fs.appendFileSync(path.join(root, pf, "questions/03-testing-posture.md"), "\n## Answer\n\nUnit; `Run after each phase`; `Critical paths`.\n\n**Gist:** Unit tests, run after each phase.\n");
|
||||
P("resolve", "audit-export", "03");
|
||||
const c = P("trail", "audit-export", "--form", "C", "--resolved-this-session", "3");
|
||||
assert.equal(c.code, 0, c.stderr);
|
||||
assert.ok(c.json.text.endsWith("OR START FRESH · new conversation, paste:\n`/plan2code-0-pathfinder specs/audit-export/pathfinder --web`"));
|
||||
assert.deepEqual(c.json.menu.options.map((o) => o.label), ["Row-count ceiling", "Start fresh"]);
|
||||
assert.equal(c.json.menu.recommended, "Start fresh", "the checkpoint after ~3 decisions");
|
||||
assert.equal(P("trail", "audit-export", "--form", "C").json.menu.recommended, "Row-count ceiling");
|
||||
});
|
||||
|
||||
test("pathfinder trail: a cleared map arrives; init first only while AGENTS.md is still missing", () => {
|
||||
const root = tmp("pfc");
|
||||
const pf = "specs/done/pathfinder";
|
||||
write(root, `${pf}/map.md`, MAP.replace("**Status:** Working", "**Status:** Cleared").replace("- `AGENTS.md` exists and governs.", "- `AGENTS.md` is absent; continued without it.").replace(/## Not yet specified\n\n- How far back an export may reach\.\n/, "## Not yet specified\n\n").replace("Feasibility-technical 14/25", "Feasibility-technical 22/25"));
|
||||
write(root, `${pf}/questions/00-codebase-context.md`, q("Codebase context", { state: "resolved", resolved: "2026-08-01", answer: "**Gist:** Node." }));
|
||||
write(root, `${pf}/questions/01-export-format.md`, q("Export format", { state: "resolved", resolved: "2026-08-02", answer: "**Gist:** CSV." }));
|
||||
const P = (...a) => runScript("plan2code-0-pathfinder", "pathfinder.mjs", [...a, "--root", root]);
|
||||
P("reconcile", "done");
|
||||
assert.equal(P("trail", "done", "--form", "A", "--text").stdout, [
|
||||
"🧭 done · Cleared · 2/2 cleared",
|
||||
" START ●━●━⚑ arrived",
|
||||
" Confidence: solid, but Requirements, Risk are borderline.",
|
||||
"",
|
||||
"NEXT STEP · start a new conversation and run:",
|
||||
"`/plan2code-init`, then `/plan2code-1-plan --web`",
|
||||
"",
|
||||
].join("\n"));
|
||||
write(root, "AGENTS.md", "# AGENTS.md\n");
|
||||
assert.match(P("trail", "done", "--form", "A", "--text").stdout, /run:\n`\/plan2code-1-plan --web`\n$/);
|
||||
assert.equal(P("trail", "done", "--form", "C").code, 5, "no menu on a cleared map");
|
||||
});
|
||||
|
||||
test("pathfinder gate: mechanical checks and hard caps", () => {
|
||||
const { root, pf } = mapFixture();
|
||||
const P = (...a) => runScript("plan2code-0-pathfinder", "pathfinder.mjs", [...a, "--root", root]);
|
||||
P("reconcile", "audit-export");
|
||||
let g = P("gate", "audit-export").json;
|
||||
assert.equal(g.mechanicalPass, false);
|
||||
const failed = g.checks.filter((c) => !c.pass).map((c) => c.id);
|
||||
assert.deepEqual(failed, ["no-open-claimed-blocked", "fog-empty", "hard-caps", "scores-at-least-18"]);
|
||||
assert.ok(g.caps.some((c) => c.dimension === "Requirements" && /not resolved/.test(c.why)));
|
||||
assert.ok(g.caps.some((c) => c.dimension === "Risk" && /Export format records no consequences/.test(c.why)));
|
||||
assert.equal(g.planDraftPath, "specs/audit-export/PLAN-DRAFT-20260803.md");
|
||||
// Settle everything.
|
||||
const qd = path.join(root, pf, "questions");
|
||||
fs.writeFileSync(path.join(qd, "01-export-format.md"), q("Export format", { state: "resolved", resolved: "2026-08-02", locked: "yes", answer: "CSV.\n\n**Consequences**\n\n- Excel.\n\n**Gist:** CSV." }));
|
||||
fs.writeFileSync(path.join(qd, "02-row-count-ceiling.md"), q("Row-count ceiling", { type: "research · AFK", state: "resolved", resolved: "2026-08-02", answer: "**Gist:** 2M." }));
|
||||
fs.writeFileSync(path.join(qd, "03-testing-posture.md"), q("Testing posture", { state: "resolved", resolved: "2026-08-02", answer: "Unit and integration. `Dedicated phase only`. `Moderate (~60-80%)`.\n\n**Gist:** Unit." }));
|
||||
fs.writeFileSync(path.join(qd, "04-delivery-channel.md"), q("Delivery channel", { state: "resolved", resolved: "2026-08-03", blocked: "02", answer: "**Gist:** Link." }));
|
||||
const mp = path.join(root, pf, "map.md");
|
||||
fs.writeFileSync(mp, fs.readFileSync(mp, "utf8").replace("- How far back an export may reach.\n", "").replace("Feasibility-technical 14/25", "Feasibility-technical 20/25"));
|
||||
P("reconcile", "audit-export");
|
||||
g = P("gate", "audit-export").json;
|
||||
assert.deepEqual(g.checks.filter((c) => !c.pass).map((c) => c.id), ["hard-caps"]);
|
||||
assert.match(g.caps[0].why, /research 02 Row-count ceiling is resolved with an empty ## Evidence/);
|
||||
fs.appendFileSync(path.join(qd, "02-row-count-ceiling.md"), "\n## Evidence\n\n- Query plan.\n\n**Research complete:** 2026-08-02\n");
|
||||
g = P("gate", "audit-export").json;
|
||||
assert.equal(g.mechanicalPass, true, JSON.stringify(g.checks));
|
||||
assert.ok(g.judgment.length >= 2, "the gate names what stays judgment");
|
||||
});
|
||||
|
||||
test("pathfinder lint: loop tokens, checkboxes, reserved names, schema, cycles, scraper bait", () => {
|
||||
const { root, pf } = mapFixture();
|
||||
const P = (...a) => runScript("plan2code-0-pathfinder", "pathfinder.mjs", [...a, "--root", root]);
|
||||
P("reconcile", "audit-export");
|
||||
let l = P("lint", "audit-export");
|
||||
assert.equal(l.code, 0, JSON.stringify(l.json.problems));
|
||||
const qd = path.join(root, pf, "questions");
|
||||
fs.appendFileSync(path.join(qd, "03-testing-posture.md"), "\n- [ ] a checkbox\nTASK_COMPLETE\n");
|
||||
fs.writeFileSync(path.join(qd, "06-loop-a.md"), q("Loop A", { blocked: "07" }));
|
||||
fs.writeFileSync(path.join(qd, "07-loop-b.md"), q("Loop B", { blocked: "06", type: "chat · HITL" }));
|
||||
write(root, `${pf}/overview.md`, "nope");
|
||||
write(root, `${pf}/briefs/brief-20260803.md`, "Requirements 18 and 90%\n");
|
||||
write(root, "specs/audit-export/PLAN-DRAFT-20260803.md", "**Charted by:** `/plan2code-0-pathfinder`\n**Confidence:** 85%\n| Requirements | 11 |\n");
|
||||
l = P("lint", "audit-export");
|
||||
assert.equal(l.code, 4);
|
||||
const msgs = l.json.problems.map((p) => `${p.file}: ${p.message}`).join("\n");
|
||||
for (const re of [/03-testing-posture\.md: has a checkbox/, /03-testing-posture\.md: contains the loop completion token TASK_COMPLETE/, /cycle 06 -> 07 -> 06|cycle 07 -> 06 -> 07/, /Type: "chat · HITL"/, /overview\.md is a reserved name/, /brief-20260803\.md: metrics-scraper bait \(bare Requirements/, /brief-20260803\.md: contains %/, /PLAN-DRAFT-20260803\.md: metrics-scraper bait \(overall confidence with %/, /PLAN-DRAFT-20260803\.md: metrics-scraper bait \(bare Requirements/]) {
|
||||
assert.match(msgs, re);
|
||||
}
|
||||
});
|
||||
|
||||
test("pathfinder brief-data: range filtering, frontier notes, plain sections", () => {
|
||||
const { root } = mapFixture();
|
||||
const P = (...a) => runScript("plan2code-0-pathfinder", "pathfinder.mjs", [...a, "--root", root]);
|
||||
P("reconcile", "audit-export");
|
||||
const today = P("brief-data", "audit-export").json;
|
||||
assert.equal(today.file, "specs/audit-export/pathfinder/briefs/brief-20260803.md");
|
||||
assert.deepEqual(today.decided, []);
|
||||
assert.equal(today.note, "No decisions were recorded in this period.");
|
||||
const full = P("brief-data", "audit-export", "--range", "full").json;
|
||||
assert.deepEqual(full.decided.map((d) => d.name), ["Codebase context", "Export format"]);
|
||||
assert.deepEqual(full.decided[1].rejected, ["*JSONL* - recipients use Excel."]);
|
||||
assert.equal(full.decided[1].hardToReverse, true);
|
||||
assert.equal(full.progress, "2 of 5 decisions made");
|
||||
assert.deepEqual(full.waiting, [{ name: "Delivery channel", waitingOn: ["Row-count ceiling"] }]);
|
||||
assert.deepEqual(full.fog, ["How far back an export may reach."]);
|
||||
assert.deepEqual(full.ruledOut, ["Redesign of the schema."]);
|
||||
assert.equal(full.confidence, "Confidence: not yet — Feasibility still needs work.");
|
||||
const since = P("brief-data", "audit-export", "--range", "since:2026-08-02").json;
|
||||
assert.deepEqual(since.decided.map((d) => d.name), ["Export format"]);
|
||||
assert.deepEqual(P("brief-data", "audit-export", "--range", "2026-08-01..2026-08-01").json.decided.map((d) => d.name), ["Codebase context"]);
|
||||
assert.equal(P("brief-data", "audit-export", "--range", "2026-08-05..2026-08-01").code, 2);
|
||||
assert.equal(P("brief-data", "audit-export", "--range", "yesterday").code, 2);
|
||||
assert.equal(P("brief-data", "nope").code, 3);
|
||||
});
|
||||
|
||||
/* ================================================= verification regressions */
|
||||
|
||||
test("pathfinder: a ## Answer inside a fenced sketch is content, not an answer", () => {
|
||||
const { root, pf } = mapFixture();
|
||||
const qd = path.join(root, pf, "questions");
|
||||
fs.writeFileSync(path.join(qd, "03-testing-posture.md"), q("Testing posture", { type: "sketch · HITL", evidence: "```markdown\n## Answer\n\n**Gist:** fake\n```" }));
|
||||
const P = (...a) => runScript("plan2code-0-pathfinder", "pathfinder.mjs", [...a, "--root", root]);
|
||||
const r = P("reconcile", "audit-export");
|
||||
assert.ok(!r.json.repairs.some((x) => x.nn === "03"), JSON.stringify(r.json.repairs));
|
||||
assert.match(read(root, `${pf}/questions/03-testing-posture.md`), /State: open/);
|
||||
});
|
||||
|
||||
test("pathfinder reconcile: an unrepairable file is skipped and named, nothing half-written, its row kept", () => {
|
||||
const { root, pf } = mapFixture();
|
||||
write(root, `${pf}/questions/07-bare.md`, `${B}\n\n# Bare\n\n## Answer\n\nYes.\n`);
|
||||
const mp = path.join(root, pf, "map.md");
|
||||
fs.writeFileSync(mp, fs.readFileSync(mp, "utf8").replace("- [ ] [Gone question]", "- [ ] [Bare](./questions/07-bare.md)\n- [ ] [Gone question]"));
|
||||
const r = runScript("plan2code-0-pathfinder", "pathfinder.mjs", ["reconcile", "audit-export", "--root", root]);
|
||||
assert.equal(r.code, 0, r.stderr);
|
||||
assert.deepEqual(r.json.findings.map((f) => [f.file, f.finding]), [["07-bare.md", "unrepairable"]]);
|
||||
assert.match(read(root, `${pf}/questions/01-export-format.md`), /State: resolved/, "the other repairs still landed");
|
||||
assert.equal(read(root, `${pf}/questions/07-bare.md`), `${B}\n\n# Bare\n\n## Answer\n\nYes.\n`, "left untouched");
|
||||
assert.ok(!r.json.mapChanges.some((c) => c.file === "07-bare.md"), JSON.stringify(r.json.mapChanges));
|
||||
assert.match(read(root, `${pf}/map.md`), /^- \[.\] \[Bare\]\(\.\/questions\/07-bare\.md\)$/m, "its row survives");
|
||||
});
|
||||
|
||||
test("pathfinder reconcile: rows stay in place among grouping lines, a re-opened row loses its gist, stray claims clear", () => {
|
||||
const { root, pf } = mapFixture();
|
||||
const mp = path.join(root, pf, "map.md");
|
||||
fs.writeFileSync(mp, fs.readFileSync(mp, "utf8").replace("- [ ] [Export format]", "### Group two\n\n- [x] [Export format]").replace("- [ ] [Export format](./questions/01-export-format.md)", "- [x] [Export format](./questions/01-export-format.md) — old gist *(2026-07-01)*"));
|
||||
fs.writeFileSync(path.join(root, pf, "questions/01-export-format.md"), q("Export format", { claimed: "2026-08-02 10:00" }));
|
||||
const r = runScript("plan2code-0-pathfinder", "pathfinder.mjs", ["reconcile", "audit-export", "--root", root]);
|
||||
assert.ok(r.json.repairs.some((x) => x.nn === "01" && x.repair === "stray-claim-cleared"));
|
||||
const map = read(root, `${pf}/map.md`);
|
||||
assert.match(map, /### Group two\n\n- \[ \] \[Export format\]\(\.\/questions\/01-export-format\.md\)\n/, "the group heading keeps its place and the row its old tail is gone");
|
||||
});
|
||||
|
||||
test("pathfinder gate: testing posture by keyword (never from Rejected), research-style consequences count", () => {
|
||||
const { root, pf } = mapFixture();
|
||||
const qd = path.join(root, pf, "questions");
|
||||
const P = (...a) => runScript("plan2code-0-pathfinder", "pathfinder.mjs", [...a, "--root", root]);
|
||||
fs.writeFileSync(path.join(qd, "03-testing-posture.md"), q("Testing posture", { state: "resolved", resolved: "2026-08-02", answer: "Unit + integration, run after each phase, moderate coverage.\n\n**Gist:** Unit." }));
|
||||
fs.writeFileSync(path.join(qd, "01-export-format.md"), q("Export format", { state: "resolved", resolved: "2026-08-02", locked: "yes", answer: "### What this implies\n\n- Excel only.\n\n**Gist:** CSV." }));
|
||||
P("reconcile", "audit-export");
|
||||
let caps = P("gate", "audit-export").json.caps;
|
||||
assert.ok(!caps.some((c) => c.dimension === "Requirements"), JSON.stringify(caps));
|
||||
assert.ok(!caps.some((c) => c.dimension === "Risk"), JSON.stringify(caps));
|
||||
fs.writeFileSync(path.join(qd, "03-testing-posture.md"), q("Testing posture", { state: "resolved", resolved: "2026-08-02", answer: "Unit tests.\n\n**Rejected**\n\n- Run after each phase with Moderate coverage: too slow.\n\n**Gist:** Unit." }));
|
||||
caps = P("gate", "audit-export").json.caps;
|
||||
assert.ok(caps.some((c) => c.dimension === "Requirements" && /cadence/.test(c.why)), "a cadence named only as rejected does not count");
|
||||
});
|
||||
|
||||
test("pathfinder: Form C needs a frontier; names come from the rows; NN is never handed out twice", () => {
|
||||
const { root, pf } = mapFixture();
|
||||
const P = (...a) => runScript("plan2code-0-pathfinder", "pathfinder.mjs", [...a, "--root", root]);
|
||||
P("reconcile", "audit-export");
|
||||
const mp = path.join(root, pf, "map.md");
|
||||
fs.writeFileSync(mp, fs.readFileSync(mp, "utf8").replace("[Testing posture](", "[How we test]("));
|
||||
const c = P("trail", "audit-export", "--form", "C").json;
|
||||
assert.deepEqual(c.menu.options.map((o) => o.label), ["Row-count ceiling", "How we test", "Start fresh"]);
|
||||
fs.rmSync(path.join(root, pf, "questions/05-siem-push.md"));
|
||||
// Without the high-water line (an older map), the links alone still count.
|
||||
fs.writeFileSync(mp, fs.readFileSync(mp, "utf8").replace(/^\*\*Next NN:\*\*.*\n/m, ""));
|
||||
assert.equal(P("frontier", "audit-export").json.nextNN, "06", "05 is still linked from the map");
|
||||
const qd = path.join(root, pf, "questions");
|
||||
fs.writeFileSync(path.join(qd, "02-row-count-ceiling.md"), q("Row-count ceiling", { blocked: "04" }));
|
||||
fs.writeFileSync(path.join(qd, "03-testing-posture.md"), q("Testing posture", { blocked: "04 (needs the channel)" }));
|
||||
P("reconcile", "audit-export");
|
||||
const none = P("trail", "audit-export", "--form", "C");
|
||||
assert.equal(none.code, 5);
|
||||
assert.equal(none.json.error, "no-frontier");
|
||||
});
|
||||
|
||||
test("pathfinder lint: map %, brief scores and checkboxes, Planning Metrics in a pathfinder draft", () => {
|
||||
const { root, pf } = mapFixture();
|
||||
runScript("plan2code-0-pathfinder", "pathfinder.mjs", ["reconcile", "audit-export", "--root", root]);
|
||||
const mp = path.join(root, pf, "map.md");
|
||||
fs.writeFileSync(mp, fs.readFileSync(mp, "utf8") + "\n80% sure.\n");
|
||||
write(root, `${pf}/briefs/brief-20260803.md`, "Solid at 22/25.\n- [ ] todo\n");
|
||||
write(root, "specs/audit-export/PLAN-DRAFT-20260803.md", "**Charted by:** `/plan2code-0-pathfinder`\n\n## Planning Metrics\n");
|
||||
const l = runScript("plan2code-0-pathfinder", "pathfinder.mjs", ["lint", "audit-export", "--root", root]).json;
|
||||
const msgs = l.problems.map((p) => `${p.level} ${p.message}`).join("\n");
|
||||
assert.match(msgs, /warn contains %; the map/);
|
||||
assert.match(msgs, /error contains a raw NN\/25 score/);
|
||||
assert.match(msgs, /error has a checkbox line/);
|
||||
assert.match(msgs, /error has a ## Planning Metrics section/);
|
||||
});
|
||||
|
||||
test("pathfinder brief-data: calendar dates only, no future since, no NNs or links in what a brief prints", () => {
|
||||
const { root, pf } = mapFixture();
|
||||
const P = (...a) => runScript("plan2code-0-pathfinder", "pathfinder.mjs", [...a, "--root", root]);
|
||||
P("reconcile", "audit-export");
|
||||
assert.equal(P("brief-data", "audit-export", "--range", "since:2026-13-99").json.error, "bad-date");
|
||||
assert.equal(P("brief-data", "audit-export", "--range", "since:2026-09-01").code, 2);
|
||||
const mp = path.join(root, pf, "map.md");
|
||||
fs.writeFileSync(mp, fs.readFileSync(mp, "utf8").replace("- Redesign of the schema.", "- [SIEM push](./questions/05-siem-push.md) — not ours.\n- Nothing yet."));
|
||||
fs.writeFileSync(path.join(root, pf, "questions/04-delivery-channel.md"), q("Delivery channel", { blocked: "09" }));
|
||||
const j = P("brief-data", "audit-export", "--range", "full").json;
|
||||
assert.deepEqual(j.ruledOut, ["SIEM push — not ours."]);
|
||||
assert.deepEqual(j.waiting.find((w) => w.name === "Delivery channel").waitingOn, ["a question that no longer exists"]);
|
||||
});
|
||||
|
||||
/* ===================================================== review-fix regressions */
|
||||
|
||||
test("pathfinder: claim, resolve and rule-out honour --dry-run", () => {
|
||||
const { root, pf } = mapFixture();
|
||||
const P = (...a) => runScript("plan2code-0-pathfinder", "pathfinder.mjs", [...a, "--root", root]);
|
||||
P("reconcile", "audit-export");
|
||||
const snap = () => fs.readdirSync(path.join(root, pf, "questions")).map((n) => read(root, `${pf}/questions/${n}`)).concat(read(root, `${pf}/map.md`));
|
||||
const before = snap();
|
||||
const c = P("claim", "audit-export", "03", "--dry-run");
|
||||
assert.equal(c.code, 0, c.stderr);
|
||||
assert.deepEqual([c.json.dryRun, c.json.mapWritten], [true, false]);
|
||||
assert.deepEqual(snap(), before, "claim --dry-run leaves every file unchanged");
|
||||
fs.appendFileSync(path.join(root, pf, "questions/03-testing-posture.md"), "\n## Answer\n\nUnit.\n\n**Gist:** Unit.\n");
|
||||
const withAnswer = snap();
|
||||
const r = P("resolve", "audit-export", "03", "--dry-run");
|
||||
assert.equal(r.code, 0, r.stderr);
|
||||
assert.deepEqual([r.json.dryRun, r.json.mapWritten], [true, false]);
|
||||
assert.deepEqual(snap(), withAnswer, "resolve --dry-run writes nothing");
|
||||
const o = P("rule-out", "audit-export", "02", "--reason", "not ours", "--dry-run");
|
||||
assert.equal(o.code, 0, o.stderr);
|
||||
assert.deepEqual([o.json.dryRun, o.json.mapWritten], [true, false]);
|
||||
assert.deepEqual(snap(), withAnswer, "rule-out --dry-run writes nothing");
|
||||
const real = P("claim", "audit-export", "02");
|
||||
assert.deepEqual([real.json.dryRun, real.json.mapWritten], [false, true]);
|
||||
});
|
||||
|
||||
test("pathfinder: a deleted top NN is never reissued, linked from an answer or not", () => {
|
||||
const { root, pf } = mapFixture();
|
||||
const P = (...a) => runScript("plan2code-0-pathfinder", "pathfinder.mjs", [...a, "--root", root]);
|
||||
const qd = path.join(root, pf, "questions");
|
||||
const mp = path.join(root, pf, "map.md");
|
||||
// Start from a map with no high-water line and no stale 09 link: reconcile adds the line.
|
||||
fs.writeFileSync(mp, MAP.replace("- [ ] [Gone question](./questions/09-gone.md)\n", ""));
|
||||
fs.writeFileSync(path.join(qd, "06-subsumed.md"), q("Subsumed"));
|
||||
let r = P("reconcile", "audit-export");
|
||||
assert.deepEqual(r.json.mapChanges.find((c) => c.change === "next-nn"), { change: "next-nn", from: null, to: "07" });
|
||||
assert.match(read(root, `${pf}/map.md`), /^\*\*Next NN:\*\* 07$/m);
|
||||
// resolve.md: delete the subsumed file, reconcile drops its row, the absorbing answer links to it.
|
||||
fs.rmSync(path.join(qd, "06-subsumed.md"));
|
||||
fs.appendFileSync(path.join(qd, "04-delivery-channel.md"), "\n## Answer\n\nAbsorbed [Subsumed](./questions/06-subsumed.md).\n\n**Gist:** Link.\n");
|
||||
r = P("reconcile", "audit-export");
|
||||
assert.ok(r.json.mapChanges.some((c) => c.change === "row-dropped" && c.file === "06-subsumed.md"));
|
||||
assert.ok(!read(root, `${pf}/map.md`).includes("06-subsumed"), "the map no longer links it");
|
||||
assert.equal(P("frontier", "audit-export").json.nextNN, "07", "linked from an answer");
|
||||
// Even with the answer's link gone, the high-water mark holds.
|
||||
fs.writeFileSync(path.join(qd, "04-delivery-channel.md"), q("Delivery channel", { blocked: "02" }));
|
||||
assert.equal(P("frontier", "audit-export").json.nextNN, "07", "the **Next NN:** line");
|
||||
assert.equal(P("reconcile", "audit-export").json.nextNN, "07", "reconcile never lowers it");
|
||||
assert.equal(P("lint", "audit-export").code, 0, "lint accepts the line");
|
||||
});
|
||||
|
||||
test("pathfinder: a name with brackets round-trips; reconcile is stable", () => {
|
||||
const { root, pf } = mapFixture();
|
||||
const P = (...a) => runScript("plan2code-0-pathfinder", "pathfinder.mjs", [...a, "--root", root]);
|
||||
write(root, `${pf}/questions/06-retention.md`, q("Retention [legal] hold"));
|
||||
for (let i = 0; i < 3; i++) assert.equal(P("reconcile", "audit-export").code, 0);
|
||||
const map = read(root, `${pf}/map.md`);
|
||||
assert.equal(map.split("\n").filter((l) => l.includes("06-retention.md")).length, 1, map);
|
||||
assert.match(map, /^- \[ \] \[Retention \[legal\] hold\]\(\.\/questions\/06-retention\.md\)$/m);
|
||||
assert.deepEqual(P("frontier", "audit-export").json.drift, []);
|
||||
assert.equal(P("reconcile", "audit-export").json.mapWritten, false);
|
||||
});
|
||||
|
||||
test("pathfinder: an author's sub-bullet under a row survives resolve, rule-out and a marker change", () => {
|
||||
const { root, pf } = mapFixture();
|
||||
const P = (...a) => runScript("plan2code-0-pathfinder", "pathfinder.mjs", [...a, "--root", root]);
|
||||
const mp = path.join(root, pf, "map.md");
|
||||
fs.writeFileSync(mp, fs.readFileSync(mp, "utf8")
|
||||
.replace("- [ ] [Testing posture](./questions/03-testing-posture.md)", "- [ ] [Testing posture](./questions/03-testing-posture.md)\n - note: ask Dana first")
|
||||
.replace("- [ ] [Delivery channel](./questions/04-delivery-channel.md)", "- [ ] [Delivery channel](./questions/04-delivery-channel.md)\n - note: depends on the volume\n and wraps"));
|
||||
P("reconcile", "audit-export");
|
||||
let map = read(root, `${pf}/map.md`);
|
||||
assert.match(map, /- \[!\] \[Delivery channel\]\(\.\/questions\/04-delivery-channel\.md\) — Blocked by 02\n - note: depends on the volume\n and wraps\n/, "kept under a regenerated [!] row");
|
||||
P("claim", "audit-export", "03");
|
||||
fs.appendFileSync(path.join(root, pf, "questions/03-testing-posture.md"), "\n## Answer\n\nUnit.\n\n**Gist:** Unit tests only.\n");
|
||||
assert.equal(P("resolve", "audit-export", "03").code, 0);
|
||||
map = read(root, `${pf}/map.md`);
|
||||
assert.match(map, /- \[x\] \[Testing posture\]\(\.\/questions\/03-testing-posture\.md\) — Unit tests only\. \*\(2026-08-03\)\*\n - note: ask Dana first\n/, "kept on resolve");
|
||||
assert.equal(P("rule-out", "audit-export", "04", "--reason", "not ours").code, 0);
|
||||
map = read(root, `${pf}/map.md`);
|
||||
assert.match(map, /- \[-\] \[Delivery channel\]\(\.\/questions\/04-delivery-channel\.md\) — out of scope, see below\n - note: depends on the volume\n and wraps\n/, "kept on rule-out");
|
||||
assert.deepEqual(P("frontier", "audit-export").json.drift, []);
|
||||
});
|
||||
|
||||
test("pathfinder: AGENTS.md absent reads in the canonical and the skill's own wording", () => {
|
||||
for (const line of ["- `AGENTS.md` is absent.", "- No `AGENTS.md`.", "- No AGENTS.md; init skipped."]) {
|
||||
const { root, pf } = mapFixture();
|
||||
fs.rmSync(path.join(root, "AGENTS.md"));
|
||||
const mp = path.join(root, pf, "map.md");
|
||||
fs.writeFileSync(mp, fs.readFileSync(mp, "utf8").replace("- `AGENTS.md` exists and governs.", line));
|
||||
const g = runScript("plan2code-0-pathfinder", "pathfinder.mjs", ["gate", "audit-export", "--root", root]).json;
|
||||
assert.deepEqual([g.agentsAbsent, g.initFirst], [true, true], line);
|
||||
}
|
||||
});
|
||||
|
||||
test("pathfinder lint: a failure carries error, message and next, on stderr too", () => {
|
||||
const { root, pf } = mapFixture();
|
||||
runScript("plan2code-0-pathfinder", "pathfinder.mjs", ["reconcile", "audit-export", "--root", root]);
|
||||
fs.appendFileSync(path.join(root, pf, "questions/03-testing-posture.md"), "\n- [ ] a checkbox\n");
|
||||
const l = runScript("plan2code-0-pathfinder", "pathfinder.mjs", ["lint", "audit-export", "--root", root]);
|
||||
assert.equal(l.code, 4);
|
||||
assert.deepEqual([l.json.ok, l.json.error, l.json.message, l.json.next], [false, "lint-failed", "lint found 1 error.", "Fix each error in problems, then rerun lint."]);
|
||||
assert.equal(l.json.errors, 1);
|
||||
assert.equal(l.json.problems.filter((p) => p.level === "error").length, 1);
|
||||
assert.match(l.stderr, /^error: lint found 1 error\.\nnext: Fix each error in problems, then rerun lint\.\n$/);
|
||||
});
|
||||
|
||||
test("pathfinder lint: densely blocked questions check in linear time", () => {
|
||||
const root = tmp("pfd");
|
||||
const pf = "specs/dense/pathfinder";
|
||||
write(root, `${pf}/map.md`, MAP);
|
||||
write(root, `${pf}/questions/00-codebase-context.md`, q("Codebase context", { type: "legwork · AFK", state: "resolved", resolved: "2026-08-01", answer: "**Gist:** Node." }));
|
||||
for (let i = 1; i < 40; i++) {
|
||||
const nn = String(i).padStart(2, "0");
|
||||
const blocked = i === 1 ? "00" : [i - 1, i - 2].map((n) => String(n).padStart(2, "0")).join(", ");
|
||||
write(root, `${pf}/questions/${nn}-q${nn}.md`, q(`Q ${nn}`, { blocked }));
|
||||
}
|
||||
const t0 = Date.now();
|
||||
const l = runScript("plan2code-0-pathfinder", "pathfinder.mjs", ["lint", "dense", "--root", root]);
|
||||
const ms = Date.now() - t0;
|
||||
assert.ok(!(l.json.problems || []).some((p) => /cycle/.test(p.message)), JSON.stringify(l.json.problems));
|
||||
assert.ok(ms < 2000, `lint took ${ms} ms`);
|
||||
// A cycle is still found, once, in the same format.
|
||||
write(root, `${pf}/questions/01-q01.md`, q("Q 01", { blocked: "39" }));
|
||||
const c = runScript("plan2code-0-pathfinder", "pathfinder.mjs", ["lint", "dense", "--root", root]).json;
|
||||
const cycles = c.problems.filter((p) => /cycle/.test(p.message));
|
||||
assert.ok(cycles.length >= 1, JSON.stringify(c.problems));
|
||||
assert.match(cycles[0].message, /^Blocked by: cycle (\d\d)( -> \d\d)+ -> \1;/);
|
||||
});
|
||||
|
||||
test("pathfinder: a one-digit NN is question 0N everywhere, and lint asks for the rename", () => {
|
||||
const { root, pf } = mapFixture();
|
||||
const P = (...a) => runScript("plan2code-0-pathfinder", "pathfinder.mjs", [...a, "--root", root]);
|
||||
write(root, `${pf}/questions/6-short.md`, q("Short"));
|
||||
write(root, `${pf}/questions/07-after.md`, q("After", { blocked: "06" }));
|
||||
P("reconcile", "audit-export");
|
||||
const f = P("frontier", "audit-export").json;
|
||||
assert.ok(f.frontier.some((x) => x.nn === "06" && x.name === "Short"), JSON.stringify(f.frontier));
|
||||
assert.deepEqual(f.blocked.find((x) => x.nn === "07").blockedBy, [{ nn: "06", name: "Short", state: "open" }]);
|
||||
assert.equal(P("claim", "audit-export", "6").json.nn, "06");
|
||||
const l = P("lint", "audit-export").json;
|
||||
assert.ok(l.problems.some((p) => p.level === "error" && /6-short\.md$/.test(p.file) && /rename it to 06-short\.md/.test(p.message)), JSON.stringify(l.problems));
|
||||
});
|
||||
|
||||
test("pathfinder: a duplicate map row is reported as drift and dropped by name", () => {
|
||||
const { root, pf } = mapFixture();
|
||||
const P = (...a) => runScript("plan2code-0-pathfinder", "pathfinder.mjs", [...a, "--root", root]);
|
||||
P("reconcile", "audit-export");
|
||||
const mp = path.join(root, pf, "map.md");
|
||||
fs.writeFileSync(mp, fs.readFileSync(mp, "utf8").replace("- [ ] [Testing posture](./questions/03-testing-posture.md)", "- [ ] [Testing posture](./questions/03-testing-posture.md)\n- [ ] [Testing again](./questions/03-testing-posture.md)"));
|
||||
assert.ok(P("frontier", "audit-export").json.drift.includes("map row 03-testing-posture.md appears 2 times"));
|
||||
const r = P("reconcile", "audit-export");
|
||||
assert.deepEqual(r.json.mapChanges, [{ change: "row-dropped", file: "03-testing-posture.md", name: "Testing again", why: "duplicate row" }]);
|
||||
assert.equal(read(root, `${pf}/map.md`).split("\n").filter((l) => l.includes("03-testing-posture.md")).length, 1);
|
||||
assert.deepEqual(P("frontier", "audit-export").json.drift, []);
|
||||
});
|
||||
|
||||
test("pathfinder lint: the chart.md map template lints clean", () => {
|
||||
const chart = fs.readFileSync(path.join(SKILLS, "plan2code-0-pathfinder", "references", "chart.md"), "utf8");
|
||||
const template = chart.split("## The `map.md` template")[1].match(/```markdown\r?\n([\s\S]*?)\r?\n```/)[1];
|
||||
assert.match(template, /^\*\*Next NN:\*\* \d+$/m, "the template carries the high-water line");
|
||||
const root = tmp("pft");
|
||||
write(root, "specs/audit-log-export/pathfinder/map.md", template + "\n");
|
||||
const l = runScript("plan2code-0-pathfinder", "pathfinder.mjs", ["lint", "audit-log-export", "--root", root]);
|
||||
assert.equal(l.code, 0, JSON.stringify(l.json.problems));
|
||||
assert.deepEqual([l.json.errors, l.json.warnings], [0, 0], JSON.stringify(l.json.problems));
|
||||
});
|
||||
@@ -0,0 +1,625 @@
|
||||
// Tests for the skill-script plumbing (installer) and the shared scripts in src/skill-scripts/.
|
||||
//
|
||||
// See skill-script-helpers.mjs for how these run.
|
||||
|
||||
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 { ROOT, SKILLS, NOW, runScript, tmp, write, read, gitInit, phase } from "./skill-script-helpers.mjs";
|
||||
|
||||
/* ================================================================ install */
|
||||
|
||||
test("every skill with scripts ships common.mjs and version.json; dashboard ships none", () => {
|
||||
const withScripts = fs.readdirSync(SKILLS).filter((s) => fs.existsSync(path.join(SKILLS, s, "scripts")));
|
||||
assert.ok(withScripts.length >= 11, `expected most skills to carry scripts, got ${withScripts.join(", ")}`);
|
||||
for (const s of withScripts) {
|
||||
for (const f of ["common.mjs", "version.json"]) assert.ok(fs.existsSync(path.join(SKILLS, s, "scripts", f)), `${s}/scripts/${f}`);
|
||||
}
|
||||
assert.ok(!fs.existsSync(path.join(SKILLS, "plan2code", "scripts")), "the dashboard needs no scripts");
|
||||
const v = JSON.parse(fs.readFileSync(path.join(ROOT, "version.json"), "utf8")).version;
|
||||
assert.equal(JSON.parse(fs.readFileSync(path.join(SKILLS, "plan2code-4-finalize", "scripts", "version.json"), "utf8")).version, v);
|
||||
});
|
||||
|
||||
test("every script a SKILL.md (or a reference it ships) runs exists beside it, and answers --help", () => {
|
||||
for (const skill of fs.readdirSync(SKILLS)) {
|
||||
const dir = path.join(SKILLS, skill);
|
||||
const texts = [];
|
||||
const walk = (d) => {
|
||||
for (const e of fs.readdirSync(d, { withFileTypes: true })) {
|
||||
const p = path.join(d, e.name);
|
||||
if (e.isDirectory()) {
|
||||
if (e.name !== "web-console" && e.name !== "scripts") walk(p);
|
||||
} else if (e.name.endsWith(".md")) texts.push(fs.readFileSync(p, "utf8"));
|
||||
}
|
||||
};
|
||||
walk(dir);
|
||||
const named = new Set();
|
||||
for (const t of texts) for (const m of t.matchAll(/<S>\/([a-z-]+\.mjs)/g)) named.add(m[1]);
|
||||
for (const script of named) {
|
||||
const p = path.join(dir, "scripts", script);
|
||||
assert.ok(fs.existsSync(p), `${skill} names <S>/${script} but scripts/${script} is not shipped`);
|
||||
const r = spawnSync(process.execPath, [p, "--help"], { encoding: "utf8" });
|
||||
assert.equal(r.status, 0, `${skill}/${script} --help`);
|
||||
assert.match(r.stdout, /Exit:/, `${skill}/${script} --help documents its exit codes`);
|
||||
}
|
||||
}
|
||||
});
|
||||
|
||||
test("scripts are self-contained: built-ins and siblings only", () => {
|
||||
for (const dir of [path.join(ROOT, "src", "skill-scripts"), ...fs.readdirSync(path.join(ROOT, "src")).filter((n) => n.endsWith("-scripts")).map((n) => path.join(ROOT, "src", n))]) {
|
||||
for (const f of fs.readdirSync(dir).filter((n) => n.endsWith(".mjs"))) {
|
||||
const t = fs.readFileSync(path.join(dir, f), "utf8");
|
||||
for (const m of t.matchAll(/^import .* from "([^"]+)";$/gm)) {
|
||||
assert.ok(m[1].startsWith("node:") || m[1] === "./common.mjs", `${f} imports ${m[1]}`);
|
||||
}
|
||||
assert.ok(!/[\u0000-\u0008]/.test(t), `${f} contains a control character (an escape lost in an edit?)`);
|
||||
}
|
||||
}
|
||||
});
|
||||
|
||||
/* ================================================================ specs.mjs */
|
||||
|
||||
const OVERVIEW = `# Lunch vote
|
||||
|
||||
## Phase Checklist
|
||||
|
||||
- [x] **[Phase 1: Data model](./phase-1.md)** - 3 tasks.
|
||||
- [/] [Phase 2: API](./phase-2.md) _(2 tasks)_
|
||||
- [ ] **Phase 3 — Web UI** — see [phase-3.md](./phase-3.md)
|
||||
- [ ] [Phase 4: Docs](./phase-4.md): readme **[Milestone 1]**
|
||||
|
||||
## Parallel Execution Groups
|
||||
|
||||
| Group | Phases | Reason |
|
||||
|-------|--------|--------|
|
||||
| A | 3, 4 | Separate files |
|
||||
| B (sequential) | 1, 2 | Not parallel |
|
||||
|
||||
## Quick Reference
|
||||
`;
|
||||
|
||||
function specFixture() {
|
||||
const root = tmp("specs");
|
||||
write(root, "AGENTS.md", "# AGENTS.md\n");
|
||||
write(root, "specs/lunch-vote/overview.md", OVERVIEW);
|
||||
write(root, "specs/lunch-vote/PLAN-DRAFT-20260801.md", "# Plan\n\n**Status:** Complete\n");
|
||||
write(root, "specs/lunch-vote/phase-1.md", phase(1, "Complete", [["x", "1.1"], ["x", "1.2"], ["x", "1.T"]]));
|
||||
write(root, "specs/lunch-vote/phase-2.md", phase(2, "In Progress", [["x", "2.1"], [" ", "2.2"]]));
|
||||
write(root, "specs/lunch-vote/phase-3.md", phase(3, "Not Started", [[" ", "3.1"], [" ", "3.2"], [" ", "3.2a"], [" ", "3.4"]], "\n## Phase Testing\n\n- [ ] Run unit tests\n"));
|
||||
write(root, "specs/lunch-vote/phase-4.md", phase(4, "Not Started", [["!", "4.1"], ["?", "4.2"]]));
|
||||
write(root, "specs/idea-only/pathfinder/map.md", "# Map\n\n**Status:** Working\n");
|
||||
write(root, "specs--completed/old-one/overview.md", "# Old\n");
|
||||
return root;
|
||||
}
|
||||
|
||||
test("specs list: active specs with state, drafts and archives, never specs--completed", () => {
|
||||
const root = specFixture();
|
||||
const r = runScript("plan2code-1-plan", "specs.mjs", ["list", "--root", root]);
|
||||
assert.equal(r.code, 0, r.stderr);
|
||||
const names = r.json.specs.map((s) => s.name).sort();
|
||||
assert.deepEqual(names, ["idea-only", "lunch-vote"]);
|
||||
const lv = r.json.specs.find((s) => s.name === "lunch-vote");
|
||||
assert.equal(lv.state, "building");
|
||||
assert.deepEqual(lv.planDrafts, [{ file: "PLAN-DRAFT-20260801.md", archived: false, status: "Complete" }]);
|
||||
assert.equal(lv.phaseFiles, 4);
|
||||
assert.deepEqual(r.json.completed, ["old-one"]);
|
||||
assert.equal(r.json.hasAgents, true);
|
||||
});
|
||||
|
||||
test("specs status: checklist formats, groups, task markers, numbering, totals, checks", () => {
|
||||
const root = specFixture();
|
||||
const r = runScript("plan2code-3-implement", "specs.mjs", ["status", "specs/lunch-vote/overview.md", "--root", root]);
|
||||
assert.equal(r.code, 0, r.stderr);
|
||||
const j = r.json;
|
||||
assert.deepEqual(j.phases.map((p) => [p.number, p.name, p.checklist]), [
|
||||
[1, "Data model", "complete"],
|
||||
[2, "API", "in-progress"],
|
||||
[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.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");
|
||||
assert.equal(j.phases[0].goal, "Phase 1 builds the thing.");
|
||||
const codes = j.checks.map((c) => c.code);
|
||||
assert.ok(j.checks.some((c) => c.code === "task-numbering" && /expected 3\.3, found 3\.4/.test(c.message)), JSON.stringify(j.checks));
|
||||
assert.ok(!codes.includes("criteria-checkbox"), "a Phase Testing checkbox block is the template's own");
|
||||
assert.ok(j.checks.some((c) => c.code === "unchecked-with-done-tasks" && /Phase 4/.test(c.message)), "an assumed [?] task counts as done, so a [ ] phase holding one is flagged");
|
||||
assert.equal(j.next.action, "ask-resume");
|
||||
assert.equal(j.next.phase.number, 2);
|
||||
assert.deepEqual(j.pending.map((p) => p.number), [2, 3, 4]);
|
||||
});
|
||||
|
||||
test("specs status: the implement selection table", () => {
|
||||
const root = specFixture();
|
||||
const ov = (m1, m2, m3, m4) => OVERVIEW.replace("- [x] **[Phase 1", `- [${m1}] **[Phase 1`).replace("- [/] [Phase 2", `- [${m2}] [Phase 2`).replace("- [ ] **Phase 3", `- [${m3}] **Phase 3`).replace("- [ ] [Phase 4", `- [${m4}] [Phase 4`);
|
||||
const next = (...m) => {
|
||||
write(root, "specs/lunch-vote/overview.md", ov(...m));
|
||||
return runScript("plan2code-3-implement", "specs.mjs", ["status", "lunch-vote", "--root", root]).json.next;
|
||||
};
|
||||
assert.deepEqual(next("x", "x", " ", " ").action, "choose");
|
||||
assert.deepEqual(next("x", "x", " ", " ").options.map((o) => o.number), [3, 4]);
|
||||
assert.ok(next("x", "x", "/", "/").warning, "all options already [/] warns about duplicated work");
|
||||
assert.equal(next("x", " ", " ", " ").action, "auto-start");
|
||||
assert.equal(next("x", "x", "x", " ").action, "auto-start");
|
||||
assert.equal(next("x", "x", "x", "x").action, "none");
|
||||
assert.equal(next("x", "x", "x", "x").reason, "every phase is complete");
|
||||
});
|
||||
|
||||
test("specs status: drift between the checklist and the phase files is an error", () => {
|
||||
const root = specFixture();
|
||||
write(root, "specs/lunch-vote/overview.md", OVERVIEW.replace("- [/] [Phase 2", "- [x] [Phase 2"));
|
||||
write(root, "specs/lunch-vote/phase-5.md", phase(5, "Not Started", [[" ", "5.1"]]));
|
||||
const j = runScript("plan2code-1b-revise-plan", "specs.mjs", ["status", "lunch-vote", "--root", root]).json;
|
||||
assert.ok(j.checks.some((c) => c.code === "checked-with-open-tasks" && /Phase 2/.test(c.message)));
|
||||
assert.ok(j.checks.some((c) => c.code === "missing-checklist-row" && /phase-5/.test(c.message)));
|
||||
});
|
||||
|
||||
test("specs status: errors are actionable and exit-coded", () => {
|
||||
const root = specFixture();
|
||||
const miss = runScript("plan2code-1-plan", "specs.mjs", ["status", "nope", "--root", root]);
|
||||
assert.equal(miss.code, 3);
|
||||
assert.equal(miss.json.error, "spec-not-found");
|
||||
assert.match(miss.json.next, /specs\.mjs list/);
|
||||
assert.equal(runScript("plan2code-1-plan", "specs.mjs", ["frobnicate"]).code, 2);
|
||||
assert.equal(runScript("plan2code-1-plan", "specs.mjs", ["status", "lunch-vote", "--bogus"]).code, 2);
|
||||
const archived = runScript("plan2code-4-finalize", "specs.mjs", ["mark", "specs--completed/old-one", "--phase", "1", "--to", "done", "--root", root]);
|
||||
assert.equal(archived.code, 5);
|
||||
});
|
||||
|
||||
test("specs mark: transitions, the no-reset rule, dry-run and idempotence", () => {
|
||||
const root = specFixture();
|
||||
const S = (...a) => runScript("plan2code-3-implement", "specs.mjs", [...a, "--root", root]);
|
||||
const dry = S("mark", "lunch-vote", "--phase", "3", "--to", "in-progress", "--dry-run");
|
||||
assert.equal(dry.code, 0);
|
||||
assert.equal(dry.json.changed, true);
|
||||
assert.match(read(root, "specs/lunch-vote/overview.md"), /- \[ \] \*\*Phase 3/, "dry-run writes nothing");
|
||||
assert.equal(S("mark", "lunch-vote", "--phase", "3", "--to", "in-progress").code, 0);
|
||||
assert.match(read(root, "specs/lunch-vote/overview.md"), /- \[\/\] \*\*Phase 3 — Web UI\*\* — see/, "only the marker changes");
|
||||
assert.equal(S("mark", "lunch-vote", "--phase", "3", "--to", "in-progress").json.changed, false);
|
||||
const reset = S("mark", "lunch-vote", "--phase", "3", "--to", "open");
|
||||
assert.equal(reset.code, 5);
|
||||
assert.equal(reset.json.error, "no-reset");
|
||||
const done = S("mark", "lunch-vote", "--phase", "2", "--to", "done");
|
||||
assert.equal(done.code, 0);
|
||||
assert.match(read(root, "specs/lunch-vote/overview.md"), /- \[x\] \[Phase 2: API\]/);
|
||||
assert.match(read(root, "specs/lunch-vote/phase-2.md"), /^\*\*Status:\*\* Complete$/m);
|
||||
assert.equal(S("mark", "lunch-vote", "--phase", "9", "--to", "done").code, 3);
|
||||
assert.equal(S("mark", "lunch-vote", "--phase", "1", "--to", "open").code, 0, "re-opening a complete phase (revise-plan) is allowed");
|
||||
});
|
||||
|
||||
test("specs metrics: document and finalize comments, judgment fields from --set", () => {
|
||||
const root = specFixture();
|
||||
const S = (...a) => runScript("plan2code-2-document", "specs.mjs", [...a, "--root", root]);
|
||||
assert.equal(S("metrics", "lunch-vote", "--step", "document").code, 2, "verification_items_added is the agent's number");
|
||||
write(root, "specs/lunch-vote/phase-3.md", read(root, "specs/lunch-vote/phase-3.md") + "\n<!-- VERIFICATION: Added (FR-2) -->\n");
|
||||
const doc = S("metrics", "lunch-vote", "--step", "document", "--set", "verification_items_added=1");
|
||||
assert.equal(doc.code, 0, doc.stderr);
|
||||
assert.equal(doc.json.comment, '<!-- METRICS_JSON {"step": "document", "total_tasks": 11, "tasks_per_phase": [3, 2, 4, 2], "phase_count": 4, "parallel_groups_identified": 1, "verification_items_added": 1} -->');
|
||||
assert.equal(doc.json.verificationCommentsFound, 1);
|
||||
assert.equal(S("metrics", "lunch-vote", "--step", "finalize").code, 2);
|
||||
const fin = S("metrics", "lunch-vote", "--step", "finalize", "--set", "verification_failures_found=1", "--set", "documentation_updates_needed=2");
|
||||
assert.equal(fin.json.comment, '<!-- METRICS_JSON {"step": "finalize", "completion_rate_at_audit": 0.45, "tasks_completed": 5, "tasks_total": 11, "verification_failures_found": 1, "documentation_updates_needed": 2} -->');
|
||||
});
|
||||
|
||||
test("specs archive: dry-run, move, refuse to clobber", () => {
|
||||
const root = specFixture();
|
||||
const S = (...a) => runScript("plan2code-4-finalize", "specs.mjs", [...a, "--root", root]);
|
||||
const dry = S("archive", "lunch-vote", "--dry-run");
|
||||
assert.equal(dry.code, 0);
|
||||
assert.ok(dry.json.files.includes("overview.md"));
|
||||
assert.ok(fs.existsSync(path.join(root, "specs/lunch-vote")));
|
||||
const moved = S("archive", "lunch-vote");
|
||||
assert.equal(moved.code, 0, moved.stdout);
|
||||
assert.equal(moved.json.sourceRemoved, true);
|
||||
assert.equal(moved.json.filesAtTarget, dry.json.files.length);
|
||||
assert.ok(fs.existsSync(path.join(root, "specs--completed/lunch-vote/phase-4.md")));
|
||||
write(root, "specs/idea-only/x.md", "x");
|
||||
fs.mkdirSync(path.join(root, "specs--completed/idea-only"));
|
||||
const clash = S("archive", "idea-only");
|
||||
assert.equal(clash.code, 5);
|
||||
assert.ok(fs.existsSync(path.join(root, "specs/idea-only/x.md")), "nothing moved on refusal");
|
||||
const after = S("status", "specs--completed/lunch-vote");
|
||||
assert.equal(after.code, 0, "status reads an archived spec (Finalize after Step 6)");
|
||||
});
|
||||
|
||||
/* ============================================================ commit-msg.mjs */
|
||||
|
||||
test("commit-msg: ticket from the branch, the three -m flags, subject rules", () => {
|
||||
const repo = tmp("commit");
|
||||
const g = gitInit(repo, "feature/ABC-10968-export-csv");
|
||||
write(repo, "a.txt", "a");
|
||||
g("add", "-A");
|
||||
g("commit", "-q", "-m", "init");
|
||||
const C = (...a) => runScript("plan2code-review", "commit-msg.mjs", a, { cwd: repo });
|
||||
const ok = C("--subject", "Add the export endpoint", "--add-all");
|
||||
assert.equal(ok.code, 0, ok.stderr);
|
||||
assert.equal(ok.json.ticket, "ABC-10968");
|
||||
assert.equal(ok.json.command, 'git add -A && git commit -m "Add the export endpoint" -m "ABC-10968" -m "AI Assisted"');
|
||||
assert.equal(ok.json.message, "Add the export endpoint\n\nABC-10968\nAI Assisted");
|
||||
assert.equal(C("--subject", "x".repeat(101)).code, 4);
|
||||
assert.equal(C("--subject", 'say "hi"').code, 4);
|
||||
assert.equal(C("--subject", "costs $5").code, 4);
|
||||
assert.equal(C().code, 2);
|
||||
assert.match(C("--subject", "Fix it", "--files", "src/a.ts", "--files", "my file.md").json.command, /^git add -- src\/a\.ts 'my file\.md' && git commit/);
|
||||
g("checkout", "-q", "-b", "chore/no-ticket-here");
|
||||
const none = C("--subject", "Fix it");
|
||||
assert.equal(none.code, 4);
|
||||
assert.equal(none.json.error, "no-ticket");
|
||||
assert.equal(C("--subject", "Fix it", "--ticket", "ABC-1").json.ticket, "ABC-1");
|
||||
assert.equal(C("--subject", "Fix it", "--ticket", "abc-1").code, 4);
|
||||
g("checkout", "-q", "-b", "PROJ2-7_underscore");
|
||||
assert.equal(C("--subject", "Fix it").json.ticket, "PROJ2-7");
|
||||
const notRepo = runScript("plan2code-review", "commit-msg.mjs", ["--subject", "x"], { cwd: tmp("norepo") });
|
||||
assert.equal(notRepo.code, 3);
|
||||
});
|
||||
|
||||
/* ============================================================ agent-files.mjs */
|
||||
|
||||
test("agent-files: detect, apply only what was chosen, rules folders, idempotent", () => {
|
||||
const root = tmp("agentfiles");
|
||||
write(root, "AGENTS.md", "# AGENTS.md\n");
|
||||
write(root, "CLAUDE.md", Array.from({ length: 12 }, (_, i) => `line ${i}`).join("\n") + "\n");
|
||||
write(root, "GEMINI.md", "# Gemini\nshort\n");
|
||||
write(root, ".github/copilot-instructions.md", "copilot\n");
|
||||
write(root, ".cursor/rules/a.md", "a\n");
|
||||
write(root, ".cursor/rules/b.md", "b\n");
|
||||
const A = (...a) => runScript("plan2code-init", "agent-files.mjs", [...a, "--root", root]);
|
||||
const d = A("detect");
|
||||
assert.equal(d.code, 0);
|
||||
assert.deepEqual(d.json.found.map((f) => f.id), ["CLAUDE.md", "GEMINI.md", ".github/copilot-instructions.md", ".cursor/rules"]);
|
||||
assert.equal(d.json.found[0].lines, 12);
|
||||
assert.equal(d.json.found[0].custom, true);
|
||||
assert.equal(d.json.found[1].custom, false);
|
||||
assert.match(d.json.warnings[0], /CLAUDE\.md has custom content/);
|
||||
const dry = A("apply", "CLAUDE.md", "--dry-run");
|
||||
assert.equal(dry.code, 0);
|
||||
assert.match(read(root, "CLAUDE.md"), /^line 0/, "dry-run writes nothing");
|
||||
assert.equal(A("apply", "CLAUDE.md", ".cursor/rules/", ".github/copilot-instructions.md").code, 0);
|
||||
assert.match(read(root, "CLAUDE.md"), /CRITICAL — MANDATORY FIRST STEP: You MUST read \[AGENTS\.md\]\(\.\/AGENTS\.md\)/);
|
||||
assert.match(read(root, ".github/copilot-instructions.md"), /^# Copilot Instructions\n\nSee \[AGENTS\.md\]\(\.\.\/AGENTS\.md\)/);
|
||||
for (const f of ["CLAUDE.md", ".github/copilot-instructions.md"]) {
|
||||
assert.match(read(root, f), /for complete project documentation including:\n- Development commands and setup\n[\s\S]*- Keeping this file current \/ Failure log\n- Section details in \.agents-docs\//, `${f} uses the bullet-list pointer`);
|
||||
}
|
||||
assert.deepEqual(fs.readdirSync(path.join(root, ".cursor/rules")), ["reference.md"]);
|
||||
assert.match(read(root, ".cursor/rules/reference.md"), /\]\(\.\.\/\.\.\/AGENTS\.md\)/);
|
||||
assert.match(read(root, "GEMINI.md"), /^# Gemini/, "unchosen files are untouched");
|
||||
const again = A("apply", "CLAUDE.md");
|
||||
assert.deepEqual(again.json.actions, [{ action: "unchanged", path: "CLAUDE.md" }]);
|
||||
assert.equal(A("detect").json.found.find((f) => f.id === "CLAUDE.md").alreadyPointer, true);
|
||||
fs.writeFileSync(path.join(root, "CLAUDE.md"), read(root, "CLAUDE.md").replace(/\n/g, "\r\n"));
|
||||
assert.equal(A("detect").json.found.find((f) => f.id === "CLAUDE.md").alreadyPointer, true, "a CRLF copy of the pointer still counts");
|
||||
assert.equal(A("apply", "GEMINI.md", "nope.md").code, 3);
|
||||
fs.rmSync(path.join(root, "AGENTS.md"));
|
||||
assert.equal(A("apply", "--all").code, 3);
|
||||
const empty = runScript("plan2code-init", "agent-files.mjs", ["detect", "--root", tmp("none")]);
|
||||
assert.deepEqual(empty.json.found, []);
|
||||
assert.match(empty.json.note, /skip this step silently/);
|
||||
});
|
||||
|
||||
/* ============================================================== agents-md.mjs */
|
||||
|
||||
test("agents-md: structure, budget, orphans, broken links, inline rules", () => {
|
||||
const root = tmp("agentsmd");
|
||||
write(root, "AGENTS.md", [
|
||||
"# AGENTS.md", "", "## Project Overview", "", "Thing.", "",
|
||||
"## Architecture", "", "Summary.", "", "Details: [Architecture](./.agents-docs/AGENTS-architecture.md)", "",
|
||||
"## Testing", "", "Details: [Testing](./.agents-docs/AGENTS-testing.md)", "",
|
||||
"## Failure log", "", "Details: [Git](./.agents-docs/AGENTS-git.md)", "",
|
||||
"```", "## not a heading inside a fence", "```", "",
|
||||
].join("\n"));
|
||||
write(root, ".agents-docs/AGENTS-architecture.md", "# Architecture\n> Part of [AGENTS.md](../AGENTS.md) — project guidance for AI coding agents.\n");
|
||||
write(root, ".agents-docs/AGENTS-git.md", "# Git\nno breadcrumb\n");
|
||||
write(root, ".agents-docs/AGENTS-orphan.md", "# Orphan\n> Part of [AGENTS.md](../AGENTS.md) — project guidance for AI coding agents.\n");
|
||||
const r = runScript("plan2code-init-update", "agents-md.mjs", ["inspect", "--root", root]);
|
||||
assert.equal(r.code, 0, r.stderr);
|
||||
const j = r.json;
|
||||
assert.equal(j.structure, "progressive");
|
||||
assert.equal(j.budget, `${j.lines}/500`);
|
||||
assert.deepEqual(j.sections.map((s) => s.name), ["Project Overview", "Architecture", "Testing", "Failure log"]);
|
||||
assert.deepEqual(j.brokenLinks, [".agents-docs/AGENTS-testing.md"]);
|
||||
assert.deepEqual(j.orphans, [".agents-docs/AGENTS-orphan.md"]);
|
||||
assert.ok(j.problems.some((p) => /Failure log must stay inline/.test(p)));
|
||||
assert.ok(j.problems.some((p) => /AGENTS-git\.md lacks the/.test(p)));
|
||||
const missing = runScript("plan2code-init", "agents-md.mjs", ["inspect", "--root", tmp("noagents")]);
|
||||
assert.equal(missing.json.exists, false);
|
||||
const fn = runScript("plan2code-init", "agents-md.mjs", ["filename", "Development Commands"]);
|
||||
assert.equal(fn.json.file, ".agents-docs/AGENTS-development-commands.md");
|
||||
assert.equal(fn.json.link, "Details: [Development Commands](./.agents-docs/AGENTS-development-commands.md)");
|
||||
});
|
||||
|
||||
/* ============================================================ review-scope.mjs */
|
||||
|
||||
test("review-scope: base detection, committed + staged + untracked, doc share", () => {
|
||||
const repo = tmp("scope");
|
||||
const g = gitInit(repo, "main");
|
||||
write(repo, "src/a.js", "1\n2\n");
|
||||
g("add", "-A");
|
||||
g("commit", "-q", "-m", "init");
|
||||
g("checkout", "-q", "-b", "feature/X-1-thing");
|
||||
write(repo, "src/a.js", "1\n2\n3\n");
|
||||
write(repo, "README.md", "# r\n");
|
||||
g("add", "-A");
|
||||
g("commit", "-q", "-m", "work");
|
||||
write(repo, "docs/new.md", "a\nb\n");
|
||||
write(repo, "src/b.js", "x\n");
|
||||
g("add", "src/b.js");
|
||||
const r = runScript("plan2code-review", "review-scope.mjs", [], { cwd: repo });
|
||||
assert.equal(r.code, 0, r.stderr);
|
||||
const j = r.json;
|
||||
assert.equal(j.base, "main");
|
||||
assert.equal(j.branch, "feature/X-1-thing");
|
||||
assert.deepEqual(j.files.map((f) => [f.path, f.status.join("+")]), [["docs/new.md", "untracked"], ["README.md", "committed"], ["src/a.js", "committed"], ["src/b.js", "staged"]]);
|
||||
assert.deepEqual(j.counts, { files: 4, lines: 5, added: 5, deleted: 0, docs: 2, code: 2 });
|
||||
assert.equal(j.mix, "mixed");
|
||||
assert.equal(j.commits.length, 1);
|
||||
assert.equal(j.empty, false);
|
||||
assert.equal(runScript("plan2code-review", "review-scope.mjs", ["--base", "nope"], { cwd: repo }).code, 3);
|
||||
assert.equal(runScript("plan2code-review", "review-scope.mjs", [], { cwd: tmp("plain") }).code, 3);
|
||||
});
|
||||
|
||||
/* ================================================= verification regressions */
|
||||
|
||||
test("specs: duplicate phase files and checklist rows are reported, and mark will not guess", () => {
|
||||
const root = specFixture();
|
||||
write(root, "specs/lunch-vote/phase-1-old.md", "# Old\n");
|
||||
write(root, "specs/lunch-vote/overview.md", OVERVIEW.replace("- [/] [Phase 2: API](./phase-2.md) _(2 tasks)_", "- [/] [Phase 2: API](./phase-2.md) _(2 tasks)_\n- [ ] Phase 2 again"));
|
||||
const j = runScript("plan2code-3-implement", "specs.mjs", ["status", "lunch-vote", "--root", root]).json;
|
||||
assert.equal(j.phases[0].file, "phase-1.md", "the exact phase-N.md wins over phase-1-old.md");
|
||||
assert.ok(j.checks.some((c) => c.code === "duplicate-phase-file" && /phase-1-old\.md/.test(c.message)));
|
||||
assert.ok(j.checks.some((c) => c.code === "duplicate-checklist-row" && /Phase 2/.test(c.message)));
|
||||
const m = runScript("plan2code-3-implement", "specs.mjs", ["mark", "lunch-vote", "--phase", "2", "--to", "done", "--root", root]);
|
||||
assert.equal(m.code, 5);
|
||||
assert.equal(m.json.error, "duplicate-row");
|
||||
});
|
||||
|
||||
test("specs: group ranges expand, chains are not parallel, [?] phases count as done, a blocked phase is skipped aloud", () => {
|
||||
const root = specFixture();
|
||||
const groups = (cells) => OVERVIEW.replace("| A | 3, 4 | Separate files |", cells);
|
||||
write(root, "specs/lunch-vote/overview.md", groups("| A | 2-4 | Separate files |"));
|
||||
assert.deepEqual(runScript("plan2code-3-implement", "specs.mjs", ["status", "lunch-vote", "--root", root]).json.parallelGroups[0].phases, [2, 3, 4]);
|
||||
write(root, "specs/lunch-vote/overview.md", groups("| A | 3 → 4 | 4 needs 3 |"));
|
||||
assert.deepEqual(runScript("plan2code-3-implement", "specs.mjs", ["status", "lunch-vote", "--root", root]).json.parallelGroups, []);
|
||||
write(root, "specs/lunch-vote/overview.md", OVERVIEW.replace("- [/] [Phase 2", "- [?] [Phase 2").replace("- [ ] **Phase 3", "- [?] **Phase 3").replace("- [ ] [Phase 4", "- [?] [Phase 4"));
|
||||
const done = runScript("plan2code-3-implement", "specs.mjs", ["status", "lunch-vote", "--root", root]).json;
|
||||
assert.equal(done.next.reason, "every phase is complete");
|
||||
assert.deepEqual(done.pending, []);
|
||||
write(root, "specs/lunch-vote/overview.md", OVERVIEW.replace("- [/] [Phase 2", "- [!] [Phase 2"));
|
||||
const skip = runScript("plan2code-3-implement", "specs.mjs", ["status", "lunch-vote", "--root", root]).json.next;
|
||||
assert.equal(skip.action, "choose");
|
||||
assert.deepEqual(skip.skipped.map((p) => p.number), [2]);
|
||||
assert.match(skip.warning, /skipping Phase 2 \[blocked\]/);
|
||||
});
|
||||
|
||||
test("specs: blocked tasks may stand at approval; a re-opened phase is normal; done warns on unfinished work", () => {
|
||||
const root = specFixture();
|
||||
write(root, "specs/lunch-vote/phase-1.md", phase(1, "Complete", [["x", "1.1"], ["!", "1.2"]]));
|
||||
let j = runScript("plan2code-1b-revise-plan", "specs.mjs", ["status", "lunch-vote", "--root", root]).json;
|
||||
assert.ok(!j.checks.some((c) => c.code === "checked-with-open-tasks"), JSON.stringify(j.checks));
|
||||
assert.ok(j.checks.some((c) => c.code === "approved-with-blocked"));
|
||||
write(root, "specs/lunch-vote/phase-1.md", phase(1, "Complete", [["x", "1.1"], ["x", "1.2"], [" ", "1.3"]]));
|
||||
const reopen = runScript("plan2code-1b-revise-plan", "specs.mjs", ["mark", "lunch-vote", "--phase", "1", "--to", "open", "--root", root]);
|
||||
assert.deepEqual(reopen.json.changes.map((c) => c.to), ["[ ]", "In Progress"]);
|
||||
j = runScript("plan2code-1b-revise-plan", "specs.mjs", ["status", "lunch-vote", "--root", root]).json;
|
||||
assert.ok(j.checks.some((c) => c.code === "partly-done-unchecked" && c.level === "info"));
|
||||
const done = runScript("plan2code-3-implement", "specs.mjs", ["mark", "lunch-vote", "--phase", "2", "--to", "done", "--root", root]);
|
||||
assert.deepEqual(done.json.unfinished, ["2.2"]);
|
||||
assert.match(done.json.warning, /unfinished/);
|
||||
});
|
||||
|
||||
test("specs: --set cannot override computed fields; empty overview exists; uncounted task lines are flagged", () => {
|
||||
const root = specFixture();
|
||||
assert.equal(runScript("plan2code-2-document", "specs.mjs", ["metrics", "lunch-vote", "--step", "document", "--set", "verification_items_added=1", "--set", "total_tasks=99", "--root", root]).code, 2);
|
||||
write(root, "specs/lunch-vote/phase-2.md", read(root, "specs/lunch-vote/phase-2.md") + "- [ ] **Task 2.4A:** odd\n1. [ ] **Task 2.5:** numbered\n");
|
||||
const j = runScript("plan2code-3-implement", "specs.mjs", ["status", "lunch-vote", "--root", root]).json;
|
||||
assert.equal(j.checks.filter((c) => c.code === "uncounted-task").length, 2);
|
||||
write(root, "specs/lunch-vote/overview.md", "");
|
||||
const e = runScript("plan2code-3-implement", "specs.mjs", ["status", "lunch-vote", "--root", root]).json;
|
||||
assert.equal(e.overview, "overview.md");
|
||||
assert.ok(e.checks.some((c) => c.code === "no-checklist"));
|
||||
assert.ok(!e.checks.some((c) => c.code === "no-overview"));
|
||||
});
|
||||
|
||||
test("commit-msg: a repo with no commits, stray arguments, and paths quoted for every shell", () => {
|
||||
const repo = tmp("commit2");
|
||||
gitInit(repo, "feature/ABC-12-x");
|
||||
const C = (...a) => runScript("plan2code-review", "commit-msg.mjs", a, { cwd: repo });
|
||||
assert.equal(C("--subject", "Add x").json.ticket, "ABC-12", "no commits yet");
|
||||
const stray = C("--subject", "Fix", "--files", "a.js", "b.js");
|
||||
assert.equal(stray.code, 2);
|
||||
assert.equal(stray.json.error, "stray-argument");
|
||||
assert.equal(C("--subject", "Fix", "--files", "src\\a.js", "--files", "my $file.md").json.command.split(" && ")[0], "git add -- src/a.js 'my $file.md'");
|
||||
assert.equal(C("--subject", "Fix", "--files", "it's.md").code, 4);
|
||||
});
|
||||
|
||||
test("review-scope: non-ASCII paths, empty untracked files, .txt is not a doc", () => {
|
||||
const repo = tmp("scope2");
|
||||
const g = gitInit(repo, "main");
|
||||
write(repo, "a.js", "1\n");
|
||||
g("add", "-A");
|
||||
g("commit", "-q", "-m", "init");
|
||||
write(repo, "café.md", "a\nb\n");
|
||||
write(repo, "empty.js", "");
|
||||
write(repo, "requirements.txt", "x\n");
|
||||
const j = runScript("plan2code-review", "review-scope.mjs", [], { cwd: repo }).json;
|
||||
const byPath = Object.fromEntries(j.files.map((f) => [f.path, f]));
|
||||
assert.equal(byPath["café.md"].added, 2);
|
||||
assert.equal(byPath["empty.js"].added, 0);
|
||||
assert.equal(j.counts.docs, 1, "only café.md is a doc");
|
||||
});
|
||||
|
||||
test("agents-md and agent-files: indirect links are not orphans, accents fold, Cursor .mdc rules are replaced", () => {
|
||||
const root = tmp("agents2");
|
||||
write(root, "AGENTS.md", "# AGENTS.md\n\n## Architecture\n\nDetails: [A](./.agents-docs/AGENTS-architecture.md)\n");
|
||||
write(root, ".agents-docs/AGENTS-architecture.md", "# Architecture\n> Part of [AGENTS.md](../AGENTS.md) — project guidance for AI coding agents.\n\nSee [deep](./AGENTS-deep.md).\n");
|
||||
write(root, ".agents-docs/AGENTS-deep.md", "# Deep\n> Part of [AGENTS.md](../AGENTS.md) — project guidance for AI coding agents.\n");
|
||||
const j = runScript("plan2code-init-update", "agents-md.mjs", ["inspect", "--root", root]).json;
|
||||
assert.deepEqual(j.orphans, []);
|
||||
assert.deepEqual(j.indirect, [".agents-docs/AGENTS-deep.md"]);
|
||||
assert.equal(runScript("plan2code-init", "agents-md.mjs", ["filename", "Café Ünïcode"]).json.file, ".agents-docs/AGENTS-cafe-unicode.md");
|
||||
write(root, ".cursor/rules/style.mdc", "---\nalwaysApply: true\n---\nrule\n");
|
||||
const d = runScript("plan2code-init", "agent-files.mjs", ["detect", "--root", root]).json;
|
||||
assert.deepEqual(d.found.find((f) => f.id === ".cursor/rules").files.map((f) => f.path), [".cursor/rules/style.mdc"]);
|
||||
runScript("plan2code-init", "agent-files.mjs", ["apply", ".cursor/rules", "--root", root]);
|
||||
assert.deepEqual(fs.readdirSync(path.join(root, ".cursor/rules")), ["reference.md"]);
|
||||
});
|
||||
|
||||
/* ================================================== code-review regressions */
|
||||
|
||||
test("agent-files: an entry that is AGENTS.md through a link is never written through", () => {
|
||||
const root = tmp("agentlink");
|
||||
const agents = "# AGENTS.md\n\nThe real instructions.\n";
|
||||
write(root, "AGENTS.md", agents);
|
||||
fs.linkSync(path.join(root, "AGENTS.md"), path.join(root, "CLAUDE.md"));
|
||||
write(root, "GEMINI.md", Array.from({ length: 12 }, (_, i) => `line ${i}`).join("\n") + "\n");
|
||||
const A = (...a) => runScript("plan2code-init", "agent-files.mjs", [...a, "--root", root]);
|
||||
const d = A("detect").json;
|
||||
assert.equal(d.found.find((f) => f.id === "CLAUDE.md").linkedToAgents, true, "a hard link to AGENTS.md is AGENTS.md");
|
||||
assert.equal(d.found.find((f) => f.id === "GEMINI.md").linkedToAgents, false);
|
||||
assert.ok(!d.warnings.some((w) => /CLAUDE\.md/.test(w)), "a linked entry is not warned as custom content");
|
||||
const refused = A("apply", "CLAUDE.md", "GEMINI.md");
|
||||
assert.equal(refused.code, 5);
|
||||
assert.equal(refused.json.error, "linked-to-agents");
|
||||
assert.match(refused.json.next, /already serves AGENTS\.md/);
|
||||
assert.equal(read(root, "AGENTS.md"), agents, "refused before anything was written");
|
||||
assert.match(read(root, "GEMINI.md"), /^line 0/, "a refusal writes nothing at all");
|
||||
const all = A("apply", "--all");
|
||||
assert.equal(all.code, 0, all.stderr);
|
||||
assert.ok(all.json.actions.some((a) => a.action === "skipped-linked" && a.path === "CLAUDE.md"));
|
||||
assert.deepEqual(all.json.updated, ["GEMINI.md"]);
|
||||
assert.equal(read(root, "AGENTS.md"), agents, "--all skips the linked entry");
|
||||
assert.match(read(root, "GEMINI.md"), /^# GEMINI\.md\n\nSee \[AGENTS\.md\]/);
|
||||
|
||||
// Symlinks need admin (or Developer Mode) on Windows: run this part only where they work.
|
||||
const sroot = tmp("agentsym");
|
||||
write(sroot, "AGENTS.md", agents);
|
||||
write(sroot, "shared/other.md", "someone else's file\n");
|
||||
try {
|
||||
fs.symlinkSync(path.join(sroot, "AGENTS.md"), path.join(sroot, "CLAUDE.md"));
|
||||
fs.symlinkSync(path.join(sroot, "shared/other.md"), path.join(sroot, "GEMINI.md"));
|
||||
} catch (err) {
|
||||
if (err.code === "EPERM" || err.code === "EACCES") return;
|
||||
throw err;
|
||||
}
|
||||
const S = (...a) => runScript("plan2code-init", "agent-files.mjs", [...a, "--root", sroot]);
|
||||
assert.equal(S("detect").json.found.find((f) => f.id === "CLAUDE.md").linkedToAgents, true);
|
||||
assert.equal(S("apply", "CLAUDE.md").code, 5);
|
||||
assert.equal(S("apply", "GEMINI.md").code, 0);
|
||||
assert.equal(read(sroot, "shared/other.md"), "someone else's file\n", "a symlink to another file is replaced, not written through");
|
||||
assert.equal(fs.lstatSync(path.join(sroot, "GEMINI.md")).isSymbolicLink(), false);
|
||||
assert.equal(read(sroot, "AGENTS.md"), agents);
|
||||
});
|
||||
|
||||
test("agent-files: a CRLF checkout of a pointer is still the pointer", () => {
|
||||
const root = tmp("agentcrlf");
|
||||
write(root, "AGENTS.md", "# AGENTS.md\n");
|
||||
write(root, "GEMINI.md", "x\n");
|
||||
write(root, ".windsurf/rules/a.md", "a\n");
|
||||
const A = (...a) => runScript("plan2code-init", "agent-files.mjs", [...a, "--root", root]);
|
||||
assert.equal(A("apply", "--all").code, 0);
|
||||
for (const f of ["GEMINI.md", ".windsurf/rules/reference.md"]) write(root, f, read(root, f).replace(/\n/g, "\r\n"));
|
||||
const d = A("detect").json;
|
||||
assert.equal(d.found.find((f) => f.id === "GEMINI.md").alreadyPointer, true);
|
||||
assert.equal(d.found.find((f) => f.id === ".windsurf/rules").alreadyPointer, true);
|
||||
assert.deepEqual(A("apply", "GEMINI.md", ".windsurf/rules").json.actions.map((a) => a.action), ["unchanged", "unchanged"]);
|
||||
assert.match(read(root, "GEMINI.md"), /\r\n/, "an unchanged CRLF pointer is left as it is");
|
||||
});
|
||||
|
||||
test("specs mark: a plain or bold Status: line is updated; a missing one is reported", () => {
|
||||
const root = specFixture();
|
||||
const S = (...a) => runScript("plan2code-3-implement", "specs.mjs", [...a, "--root", root]);
|
||||
write(root, "specs/lunch-vote/phase-3.md", phase(3, "x", [["x", "3.1"]]).replace("**Status:** x", "Status: In Progress"));
|
||||
const plain = S("mark", "lunch-vote", "--phase", "3", "--to", "done");
|
||||
assert.equal(plain.code, 0, plain.stderr);
|
||||
assert.match(read(root, "specs/lunch-vote/phase-3.md"), /^Status: Complete$/m, "the plain form is kept as written");
|
||||
assert.ok(!plain.json.warning);
|
||||
write(root, "specs/lunch-vote/phase-4.md", phase(4, "x", [["x", "4.1"]]).replace("**Status:** x", "- **Status**: Not Started"));
|
||||
assert.equal(S("status", "lunch-vote").json.phases[3].status, "Not Started");
|
||||
assert.equal(S("mark", "lunch-vote", "--phase", "4", "--to", "done").code, 0);
|
||||
assert.match(read(root, "specs/lunch-vote/phase-4.md"), /^- \*\*Status\*\*: Complete$/m);
|
||||
write(root, "specs/lunch-vote/phase-2.md", phase(2, "x", [["x", "2.1"]]).replace("**Status:** x\n", ""));
|
||||
const none = S("mark", "lunch-vote", "--phase", "2", "--to", "done");
|
||||
assert.equal(none.code, 0);
|
||||
assert.match(none.json.warning, /phase-2\.md has no Status line, so only the Phase Checklist checkbox changed/);
|
||||
assert.match(read(root, "specs/lunch-vote/overview.md"), /- \[x\] \[Phase 2: API\]/);
|
||||
});
|
||||
|
||||
test("specs: only a folder directly under specs/ is a spec; archive verification fails loudly", () => {
|
||||
const root = specFixture();
|
||||
write(root, "src/app.js", "x\n");
|
||||
const S = (...a) => runScript("plan2code-4-finalize", "specs.mjs", [...a, "--root", root]);
|
||||
for (const arg of [".", "./src", "./specs", "specs/lunch-vote/.."]) {
|
||||
const r = S("archive", arg, "--dry-run");
|
||||
assert.equal(r.code, 5, `archive ${arg}: ${r.stdout}`);
|
||||
assert.equal(r.json.error, "not-a-spec");
|
||||
assert.match(r.json.next, /specs\/<name>/);
|
||||
}
|
||||
assert.ok(fs.existsSync(path.join(root, "specs/lunch-vote/overview.md")));
|
||||
assert.equal(S("archive", "./specs/lunch-vote", "--dry-run").code, 0);
|
||||
assert.equal(S("archive", path.join(root, "specs", "lunch-vote"), "--dry-run").code, 0, "an absolute path under specs/ is fine");
|
||||
assert.equal(S("status", "specs--completed/old-one").code, 0, "a read may name an archived spec");
|
||||
assert.equal(S("status", "./src").json.error, "not-a-spec");
|
||||
});
|
||||
|
||||
test("specs: an em dash in a group range expands like a hyphen", () => {
|
||||
const root = specFixture();
|
||||
write(root, "specs/lunch-vote/overview.md", OVERVIEW.replace("| A | 3, 4 | Separate files |", "| A | 2\u20144 | Separate files |"));
|
||||
assert.deepEqual(runScript("plan2code-3-implement", "specs.mjs", ["status", "lunch-vote", "--root", root]).json.parallelGroups[0].phases, [2, 3, 4]);
|
||||
});
|
||||
|
||||
test("commit-msg: @ and - paths are quoted, git add ends its options, risky subjects are refused, add and commit apart", () => {
|
||||
const repo = tmp("commit3");
|
||||
gitInit(repo, "feature/ABC-12-x");
|
||||
const C = (...a) => runScript("plan2code-review", "commit-msg.mjs", a, { cwd: repo });
|
||||
const files = C("--subject", "Fix", "--files", "@types/x.d.ts", "--files", "-weird.md", "--files", "src/a@b.js");
|
||||
assert.equal(files.code, 0, files.stderr);
|
||||
assert.equal(files.json.add, "git add -- '@types/x.d.ts' '-weird.md' src/a@b.js");
|
||||
assert.equal(files.json.commit, 'git commit -m "Fix" -m "ABC-12" -m "AI Assisted"');
|
||||
assert.equal(files.json.command, `${files.json.add} && ${files.json.commit}`);
|
||||
assert.equal(C("--subject", "Fix", "--add-all").json.add, "git add -A");
|
||||
const bare = C("--subject", "Fix").json;
|
||||
assert.equal(bare.add, null);
|
||||
assert.equal(bare.command, bare.commit);
|
||||
for (const bad of ["back\\slash", "wow!", "a\rb", "say \u201Chi\u201D"]) {
|
||||
assert.equal(C("--subject", bad).code, 4, JSON.stringify(bad));
|
||||
}
|
||||
assert.equal(C("--subject", "wow!").json.error, "unsafe-subject");
|
||||
assert.equal(C("--subject", "Fix", "--files", "it\u2019s.md").json.error, "unsafe-path");
|
||||
});
|
||||
|
||||
test("review-scope: no main or master is no-base unless the repo has no commits; a move up a level keeps one slash", () => {
|
||||
const repo = tmp("scope3");
|
||||
const g = gitInit(repo, "develop");
|
||||
write(repo, "d/sub/f.txt", "1\n");
|
||||
write(repo, "top/h.txt", "3\n");
|
||||
g("add", "-A");
|
||||
g("commit", "-q", "-m", "init");
|
||||
g("checkout", "-q", "-b", "feature/X-2-thing");
|
||||
write(repo, "src/new.js", "x\n");
|
||||
g("add", "-A");
|
||||
g("commit", "-q", "-m", "feature work");
|
||||
const R = (...a) => runScript("plan2code-review", "review-scope.mjs", a, { cwd: repo });
|
||||
const none = R();
|
||||
assert.equal(none.code, 3);
|
||||
assert.equal(none.json.error, "no-base");
|
||||
assert.match(none.json.next, /--base <trunk>/);
|
||||
const dev = R("--base", "develop");
|
||||
assert.equal(dev.code, 0, dev.stderr);
|
||||
assert.deepEqual(dev.json.files.map((f) => f.path), ["src/new.js"]);
|
||||
g("mv", "d/sub/f.txt", "d/f.txt");
|
||||
g("mv", "top/h.txt", "h.txt");
|
||||
const moved = R("--base", "develop").json.files.map((f) => f.path);
|
||||
assert.ok(moved.includes("d/f.txt") && moved.includes("h.txt"), JSON.stringify(moved));
|
||||
assert.ok(!moved.some((p) => p.includes("//") || p.startsWith("/")), JSON.stringify(moved));
|
||||
const fresh = tmp("scope4");
|
||||
gitInit(fresh, "develop");
|
||||
write(fresh, "a.js", "1\n");
|
||||
const unborn = runScript("plan2code-review", "review-scope.mjs", [], { cwd: fresh });
|
||||
assert.equal(unborn.code, 0, unborn.stderr);
|
||||
assert.equal(unborn.json.base, null);
|
||||
assert.match(unborn.json.note, /No commits yet/);
|
||||
assert.deepEqual(unborn.json.files.map((f) => f.path), ["a.js"]);
|
||||
});
|
||||
@@ -3384,7 +3384,7 @@ test("the scratch sweep removes old patches and helpers, never looks, the pointe
|
||||
return p;
|
||||
};
|
||||
const removable = [file("p2.json"), file("helper.mjs")];
|
||||
const kept = [file("looks.json"), file("console-dir"), file("notes.txt"), file("p3.json", false)];
|
||||
const kept = [file("looks.json"), file("workspaces.json"), file("console-dir"), file("notes.txt"), file("p3.json", false)];
|
||||
const subdir = path.join(dir, "x.json");
|
||||
fs.mkdirSync(subdir);
|
||||
backdate(subdir);
|
||||
@@ -3393,12 +3393,12 @@ test("the scratch sweep removes old patches and helpers, never looks, the pointe
|
||||
const stale = staleScratch(dir, Date.now(), SESSION_MAX_AGE_MS).sort();
|
||||
assert.deepEqual(stale, ["helper.mjs", "p2.json"]);
|
||||
assert.deepEqual(
|
||||
(await removeScratch(dir, [...stale, "looks.json", "../p.json", "console-dir"])).sort(),
|
||||
(await removeScratch(dir, [...stale, "looks.json", "workspaces.json", "../p.json", "console-dir"])).sort(),
|
||||
["helper.mjs", "p2.json"]
|
||||
);
|
||||
for (const p of removable) assert.equal(fs.existsSync(p), false, p);
|
||||
for (const p of kept) assert.ok(fs.existsSync(p), p);
|
||||
assert.deepEqual([...PROTECTED_CONSOLE_FILES].sort(), ["console-dir", "looks.json"]);
|
||||
assert.deepEqual([...PROTECTED_CONSOLE_FILES].sort(), ["console-dir", "looks.json", "workspaces.json"]);
|
||||
} finally {
|
||||
fs.rmSync(dir, { recursive: true, force: true });
|
||||
}
|
||||
@@ -3594,6 +3594,8 @@ const RESULT_KEYS = ["type", "at", "sid", "rev", "actions", "reply", "consumedAt
|
||||
const WAITING_KEYS = ["status", "sid", "elapsed", "answered", "total", "staged", "url", "message", "next", "terminalLine"];
|
||||
|
||||
function openSession(extra = {}) {
|
||||
// A fresh page, and no folders remembered from an earlier test.
|
||||
fs.rmSync(path.join(HOME, "workspaces.json"), { force: true });
|
||||
const res = cli(["open", "--file", payload(`pin-${Date.now()}.json`, { ...BASE, ...extra }), "--no-open"]);
|
||||
const s = sessionUrl(res.json.url);
|
||||
const send = (pathname, body) =>
|
||||
@@ -4926,7 +4928,20 @@ test("initialWorkspace names the original folder after itself and marks it origi
|
||||
|
||||
/* ------------------------------------ workspace and meter: end to end */
|
||||
|
||||
// The folders remembered across console sessions (workspaces.json) are
|
||||
// cleared for every new test session unless it asks to keep them, so one
|
||||
// test's additions never seed the next one's workspace.
|
||||
const REMEMBERED = path.join(HOME, "workspaces.json");
|
||||
const remembered = () => JSON.parse(fs.readFileSync(REMEMBERED, "utf8"));
|
||||
const rememberedFor = (spec) => {
|
||||
const projects = Object.values(remembered().projects);
|
||||
const project = projects.find((p) => path.resolve(p.path).toLowerCase() === ROOT.toLowerCase());
|
||||
if (!project) return undefined;
|
||||
return spec ? (project.specs || {})[spec] : project.project;
|
||||
};
|
||||
|
||||
function consoleSession(openArgs, opts = {}) {
|
||||
if (!opts.keepRemembered) fs.rmSync(REMEMBERED, { force: true });
|
||||
const res = cli(["open", "--no-open", ...openArgs], opts);
|
||||
const s = sessionUrl(res.json.url);
|
||||
const send = (pathname, body) =>
|
||||
@@ -4974,9 +4989,18 @@ test("workspace: a folder added on the dashboard survives dashboard → plan →
|
||||
assert.equal(meterView(ledger).points, 2);
|
||||
assert.equal((await s.get("/state")).meter.points, 2, "the frame carries the meter");
|
||||
|
||||
const fresh = consoleSession(["--workflow", "dashboard"]);
|
||||
assert.deepEqual(
|
||||
rememberedFor("").folders.map((f) => [f.path, f.description]),
|
||||
[[extra, "the design notes"]],
|
||||
"the add was remembered for the project, outside the session folder"
|
||||
);
|
||||
const fresh = consoleSession(["--workflow", "dashboard"], { keepRemembered: true });
|
||||
try {
|
||||
assert.equal(fresh.opened.workspace.folders.length, 1, "a new console session starts with only the original folder");
|
||||
assert.deepEqual(
|
||||
fresh.opened.workspace.folders.map((f) => f.path),
|
||||
[ROOT, extra],
|
||||
"a new console session in the same folder opens with the remembered folders"
|
||||
);
|
||||
assert.equal(meterView(readLedger(fresh.session)).points, 0);
|
||||
} finally {
|
||||
cli(["stop", "--session", fresh.sid]);
|
||||
@@ -4987,6 +5011,78 @@ test("workspace: a folder added on the dashboard survives dashboard → plan →
|
||||
}
|
||||
});
|
||||
|
||||
test("workspace: a spec starts from the project's list, then stands alone, and the scope swaps lists with logged changes", async () => {
|
||||
const s = consoleSession(["--workflow", "dashboard"]);
|
||||
const shared = tempFolder();
|
||||
const specOnly = tempFolder();
|
||||
try {
|
||||
assert.equal((await addFolder(s, { path: shared })).status, 200);
|
||||
const toSpec = await s.send("/workspace/scope", { spec: "specs/demo" });
|
||||
assert.equal(toSpec.status, 200);
|
||||
const view = await toSpec.json();
|
||||
assert.equal(view.scope, "specs/demo");
|
||||
assert.deepEqual(view.folders.map((f) => f.path), [ROOT, shared], "seeded from the project's list");
|
||||
assert.equal(rememberedFor("specs/demo"), undefined, "nothing is saved for the spec until it changes");
|
||||
|
||||
assert.equal((await addFolder(s, { path: specOnly })).status, 200);
|
||||
assert.deepEqual(rememberedFor("specs/demo").folders.map((f) => f.path), [shared, specOnly]);
|
||||
assert.deepEqual(rememberedFor("").folders.map((f) => f.path), [shared], "the project's list is untouched");
|
||||
|
||||
const before = wsFile(s).version;
|
||||
const back = await (await s.send("/workspace/scope", { spec: "" })).json();
|
||||
assert.deepEqual([back.scope, back.folders.map((f) => f.path)], ["", [ROOT, shared]]);
|
||||
assert.deepEqual(
|
||||
wsFile(s).changes.filter((c) => c.version > before).map((c) => [c.kind, c.path]),
|
||||
[["removed", specOnly]],
|
||||
"the swap is logged, so the agent hears of it"
|
||||
);
|
||||
const again = await (await s.send("/workspace/scope", { spec: "specs/demo/" })).json();
|
||||
assert.deepEqual(again.folders.map((f) => f.path), [ROOT, shared, specOnly], "the spec's own list comes back");
|
||||
assert.equal((await s.send("/workspace/scope", { spec: "../elsewhere" })).status, 400);
|
||||
} finally {
|
||||
cli(["stop", "--session", s.sid]);
|
||||
fs.rmSync(shared, { recursive: true, force: true });
|
||||
fs.rmSync(specOnly, { recursive: true, force: true });
|
||||
}
|
||||
});
|
||||
|
||||
test("workspace: open --spec starts on that spec's list, a posted specDir takes the list with it, and forget drops only that spec", async () => {
|
||||
const s = consoleSession(["--workflow", "dashboard"]);
|
||||
const shared = tempFolder();
|
||||
const specOnly = tempFolder();
|
||||
let other = null;
|
||||
let planned = null;
|
||||
try {
|
||||
await addFolder(s, { path: shared });
|
||||
await s.send("/workspace/scope", { spec: "specs/demo" });
|
||||
await addFolder(s, { path: specOnly });
|
||||
cli(["stop", "--session", s.sid]);
|
||||
|
||||
other = consoleSession(["--workflow", "implement", "--spec", "specs/demo"], { keepRemembered: true });
|
||||
assert.deepEqual(other.opened.workspace.folders.map((f) => f.path), [ROOT, shared, specOnly]);
|
||||
assert.equal((await other.get("/workspace")).scope, "specs/demo");
|
||||
|
||||
planned = consoleSession(["--workflow", "plan"], { keepRemembered: true });
|
||||
assert.deepEqual(planned.opened.workspace.folders.map((f) => f.path), [ROOT, shared], "no spec: the project's list");
|
||||
cli(["post", "--session", planned.sid, "--file", payload("ws-spec.json", { specDir: "specs/brand-new" })]);
|
||||
let saved;
|
||||
for (let i = 0; i < 40 && !(saved = rememberedFor("specs/brand-new")); i++) await sleep(100);
|
||||
assert.deepEqual(saved && saved.folders.map((f) => f.path), [shared], "the list in force became the new spec's");
|
||||
|
||||
const forgot = cli(["forget", "--spec", "specs/demo/overview.md"]);
|
||||
assert.deepEqual(forgot.json, { ok: true, spec: "specs/demo", forgot: true });
|
||||
assert.equal(cli(["forget", "--spec", "specs/demo"]).json.forgot, false, "a second forget finds nothing");
|
||||
assert.equal(rememberedFor("specs/demo"), undefined);
|
||||
assert.ok(rememberedFor("specs/brand-new"), "other specs are kept");
|
||||
assert.ok(rememberedFor(""), "the project's list is kept");
|
||||
assert.equal(cli(["forget"], { expectFail: true }).status, 2);
|
||||
} finally {
|
||||
for (const x of [s, other, planned]) if (x) cli(["stop", "--session", x.sid]);
|
||||
fs.rmSync(shared, { recursive: true, force: true });
|
||||
fs.rmSync(specOnly, { recursive: true, force: true });
|
||||
}
|
||||
});
|
||||
|
||||
test("workspace: add resolves from the session's folder and refuses a file, a missing path, a duplicate and a name clash", async () => {
|
||||
// Opened from scripts/: the worktree is still the repo root, but the CLI
|
||||
// (and so the server it spawns) runs from elsewhere.
|
||||
|
||||
@@ -3,7 +3,7 @@
|
||||
const fs = require('fs');
|
||||
const path = require('path');
|
||||
|
||||
const CHAR_LIMIT = 11500;
|
||||
const CHAR_LIMIT = 20000;
|
||||
const srcDir = path.join(__dirname, '..', 'src');
|
||||
|
||||
// Note: readdirSync is non-recursive, so files in subdirectories like
|
||||
|
||||
@@ -33,9 +33,13 @@ Read references/github-issues.md — REQUIRED on `github`, skip on `local`.
|
||||
|
||||
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.
|
||||
|
||||
## Scripts
|
||||
|
||||
On `local`, the map's bookkeeping is a script; the decisions are yours. `node "<S>/pathfinder.mjs" <command> specs/<idea>/pathfinder`, run from the project root, where `<S>` is `scripts/` beside this SKILL.md (`~/.agents/skills/plan2code-0-pathfinder/scripts/` globally). It prints one JSON object. Exit 0 is success; anything else carries `message` and `next`, so do what `next` says. Exit 5 (refused) means a rule would break: never work around it by editing the files by hand. `--help` lists every command; they are named at the steps below. It reads local files only: on `github`, the backend playbook does each step with `gh` (except `lint`, which checks the local briefs and PLAN-DRAFT once one exists), and a `no-map` result there is expected, never a cue to chart.
|
||||
|
||||
## Project Context
|
||||
|
||||
Load `./AGENTS.md` if it exists — its conventions govern; never re-ask what it answers. If missing, fold it into the Step 0 gate batch: *"No `AGENTS.md`. Pathfinder can chart without it. Continue, or run `plan2code-init` first?"* Record it in `## Ground rules`.
|
||||
Load `./AGENTS.md` if it exists — its conventions govern; never re-ask what it answers. If missing, fold it into the Step 0 gate batch: *"No `AGENTS.md`. Pathfinder can chart without it. Continue, or run `plan2code-init` first?"* Record the outcome as the first line of `## Ground rules`: ``- `AGENTS.md` exists and governs.`` or, when missing, exactly ``- `AGENTS.md` is absent.`` (the handoff reads it).
|
||||
|
||||
## Rules
|
||||
|
||||
@@ -49,12 +53,13 @@ Load `./AGENTS.md` if it exists — its conventions govern; never re-ask what it
|
||||
- **Reserved names — never create inside `pathfinder/`:** `overview.md`, `phase-<N>.md`, `PLAN-DRAFT-*.md`, `PLAN-CONVERSATION-*.md`.
|
||||
- **Never emit the loop's completion tokens under `specs/`** — `TASK_COMPLETE`, `PHASE_COMPLETE`, `ALL_TASKS_COMPLETE`, `IMPLEMENTATION_COMPLETE`, `SPEC_COMPLETE`, `WORK_COMPLETE`. It scans for them.
|
||||
- **No `- [ ]` checkboxes inside question files**, and no `METRICS_JSON` anywhere.
|
||||
- **Lint before every Session End** (on `github`, once a brief or PLAN-DRAFT is on local disk; it checks those): `lint` checks the rules above, the schema lines, `Blocked by:` targets and cycles, and metrics-scraper bait. Fix every error it lists (exit 4) before you stop.
|
||||
|
||||
## Auto-Discovery and Mode Selection
|
||||
|
||||
⚠️ `specs/` is gitignored — NEVER use Glob. Shell only: `ls specs/` (Bash) or `Get-ChildItem specs/` (PS).
|
||||
|
||||
**Brief/recap/minutes asked?** → read references/brief.md: reconcile, write plain-English `briefs/brief-<YYYYMMDD>.md` (decisions in range, still open, next step), STOP. Never resolves.
|
||||
**Brief/recap/minutes asked?** → read references/brief.md: `reconcile`, then `brief-data --range <range>` (`github`: its brief section), write plain-English `briefs/brief-<YYYYMMDD>.md` from the output, STOP. Never resolves.
|
||||
|
||||
**Identify the idea FIRST** (from the argument, or ask), then evaluate for THAT idea — first match wins. An issue URL or number means `github`; else look for a local map, then `gh issue list --label pathfinder:map` for `Map: <idea>`.
|
||||
|
||||
@@ -81,15 +86,15 @@ Read references/chart.md
|
||||
|
||||
> Fallback: confirm the outcome with the human FIRST; only then grill the destination, then breadth-first; write the map and one question per sharp decision.
|
||||
|
||||
0. `[Step 0: Intent Gate]` **Before creating anything**, use AskUserQuestion for the outcome and WAIT: **chart a map** (foggy — Step 1), **`/plan2code-1-plan`** (clear — STOP), **`/plan2code-quick-task`** (tiny — STOP). HITL, never self-select "chart".
|
||||
1. `[Step 1: Name and backend]` Only after the gate says "chart." Confirm the kebab-case idea name, then ask — HITL, never self-picked — **local files or GitHub Issues?** Recommend `local` for solo work; offer `github` only if preflight passes, naming the repo's visibility. THEN the first write.
|
||||
2. `[Step 2: Destination]` Grill until it is one or two lines. It fixes scope — settle it first.
|
||||
3. `[Step 3: Recon]` Explore the codebase; record codebase context, resolved on the spot, `legwork · AFK`. On `github` hold it until Step 6 so a Step 4 off-ramp leaves no litter.
|
||||
4. `[Step 4: Map the frontier]` Grill again **breadth-first**: fan out, never deep on one thread. Surface the open decisions and what is takeable now.
|
||||
5. `[Step 5: Create the map]` `**Status:** Charting`, Destination, Ground rules (backend first), an empty index, the fog in `## Not yet specified`. Say once where it lives and who sees it.
|
||||
6. `[Step 6: Write the questions]` One per decision you can phrase sharply NOW, dependency order, `Blocked by:` filled the same pass — on `github`, create all first, wire edges second. The rest stays fog. Include a `grill · HITL` testing-posture question; `/plan2code-1-plan` Phase 1 needs it.
|
||||
7. `[Step 7: Index]` Fill `## Question Checklist` from the files (`local` only). Set `**Status:** Working`.
|
||||
8. `[Step 8: Fire research]` One subagent per `research` question, in parallel. Each writes only its `## Evidence`, never decides. **Wait for all** (they die with the terminal), then Session End.
|
||||
0. `[Chart - Step 0: Intent Gate]` **Before creating anything**, use AskUserQuestion for the outcome and WAIT: **chart a map** (foggy — Step 1), **`/plan2code-1-plan`** (clear — STOP), **`/plan2code-quick-task`** (tiny — STOP). HITL, never self-select "chart".
|
||||
1. `[Chart - Step 1: Name and backend]` Only after the gate says "chart." Confirm the kebab-case idea name, then ask — HITL, never self-picked — **local files or GitHub Issues?** Recommend `local` for solo work; offer `github` only if preflight passes, naming the repo's visibility. THEN the first write.
|
||||
2. `[Chart - Step 2: Destination]` Grill until it is one or two lines. It fixes scope — settle it first.
|
||||
3. `[Chart - Step 3: Recon]` Explore the codebase; record codebase context, resolved on the spot, `legwork · AFK`. On `github` hold it until Step 6 so a Step 4 off-ramp leaves no litter.
|
||||
4. `[Chart - Step 4: Map the frontier]` Grill again **breadth-first**: fan out, never deep on one thread. Surface the open decisions and what is takeable now.
|
||||
5. `[Chart - Step 5: Create the map]` `**Status:** Charting`, Destination, Ground rules (backend first), an empty index, the fog in `## Not yet specified`. Say once where it lives and who sees it.
|
||||
6. `[Chart - Step 6: Write the questions]` One per decision you can phrase sharply NOW, dependency order, `Blocked by:` filled the same pass — on `github`, create all first, wire edges second. The rest stays fog. Include a `grill · HITL` testing-posture question; `/plan2code-1-plan` Phase 1 needs it.
|
||||
7. `[Chart - Step 7: Index]` `local`: `reconcile` fills `## Question Checklist` from the files (every missing row, with its marker). Either backend: set `**Status:** Working`. `local`: then `lint`.
|
||||
8. `[Chart - Step 8: Fire research]` One subagent per `research` question, in parallel. Each writes only its `## Evidence`, never decides. **Wait for all** (they die with the terminal), then Session End.
|
||||
|
||||
**No fog at Step 4?** Small enough to plan directly: create no map, keep the recon as a local file, attach it to `/plan2code-1-plan`, STOP. Charting resolves nothing by hand — stop at Step 8.
|
||||
|
||||
@@ -101,15 +106,18 @@ Read references/resolve.md
|
||||
|
||||
Assume NO memory of any prior session.
|
||||
|
||||
1. `[Step 1: Load]` Read the map whole. No question yet.
|
||||
2. `[Step 2: Reconcile]` **Always.** Read every question. `## Answer` written but the state disagrees? The answer wins. Claimed with no `## Answer`? A crash: release it, say so. Rebuild every marker from the questions; backfill a missing `Resolved:` date from the claim. Research without `Research complete:`? Re-fire it.
|
||||
3. `[Step 3: Frontier]` Every question open, unclaimed, and unblocked. First in order.
|
||||
4. `[Step 4: Choose and claim]` The one the user named, else first on the frontier. Mark it claimed on the question and the map, **saved before any work.** Frontier empty but questions remain? All blocked — report the chain, STOP. Stranded on an `out-of-scope` blocker? Re-frame or rule out, re-run Step 3. Nothing open? The Clearing Gate.
|
||||
5. `[Step 5: Zoom]` Read the claimed question in full, plus any closed question it references. Obey `## Ground rules`.
|
||||
6. `[Step 6: Resolve]` Route by type per the resolve playbook. HITL needs the human's own words.
|
||||
7. `[Step 7: Record]` Write `## Answer`: the decision, what was rejected and why, consequences, a one-line `**Gist:**`. Sources under `## Evidence`. Mark it resolved, dated today, index the gist + date on the map, bump `**Updated:**`.
|
||||
8. `[Step 8: Graduate]` Fog now sharp? Write those questions, delete the graduated bullets. Past the destination? Rule it out of scope, one line in `## Out of scope`. Invalidated? Re-frame or rule out.
|
||||
9. `[Step 9: Menu]` Run The Clearing Gate. Not cleared: fork-menu (Form C) — pick → Step 4, stop → Session End.
|
||||
1. `[Work - Step 1: Load]` Read the map whole. No question yet.
|
||||
2. `[Work - Step 2: Reconcile]` **Always.** `local`: run `reconcile`. The answer wins: a question whose `## Answer` its state contradicts is resolved, a missing `Resolved:` is backfilled from the claim (today if none), a claim with no `## Answer` (a crash) is released, and every marker is rebuilt from the questions. Tell the human each `repairs` entry in one line. Re-fire every question in `refire` (research cut off before its `Research complete:` line; resolve.md → Interrupted research). `--dry-run` first if the map looks badly off. `github`: the reconcile checks in the backend playbook.
|
||||
3. `[Work - Step 3: Frontier]` Every question open, unclaimed, and unblocked, first in order. `local`: run `frontier` (`frontier`, `blocked` with each blocker, `stranded`, `nextNN`, `counts`).
|
||||
4. `[Work - Step 4: Choose and claim]` The one the user named, else first on the frontier. Mark it claimed on the question and the map, **saved before any work** (`local`: `claim <NN>`, which refuses a blocked or non-open question and a second open claim). A `research` pick fires unclaimed instead (resolve.md); then claim the next one.
|
||||
- Stranded on an `out-of-scope` blocker? Check this first: re-frame or rule out, re-run Step 3.
|
||||
- Frontier empty but questions remain (`allBlocked`)? Report the chain, STOP.
|
||||
- Nothing open (`nothingOpen`)? The Clearing Gate.
|
||||
5. `[Work - Step 5: Zoom]` Read the claimed question in full, plus any closed question it references. Obey `## Ground rules`.
|
||||
6. `[Work - Step 6: Resolve]` Route by type per the resolve playbook. HITL needs the human's own words.
|
||||
7. `[Work - Step 7: Record]` Write `## Answer`: the decision, what was rejected and why, consequences, a one-line `**Gist:**` last. Sources under `## Evidence`. Mark it resolved, dated today, index the gist + date on the map, bump `**Updated:**` (`local`: `resolve <NN>` does all four; its `unblocked` list feeds the menu).
|
||||
8. `[Work - Step 8: Graduate]` Fog now sharp? Write those questions (`local`: numbered from `nextNN`, then `reconcile` to index them), delete the graduated bullets. Past the destination? Rule it out of scope, one line in `## Out of scope` (`local`: `rule-out <NN> --reason "<why>"`; handle anything it reports `stranded`). Invalidated? Re-frame or rule out.
|
||||
9. `[Work - Step 9: Menu]` Run The Clearing Gate. Not cleared: fork-menu (Form C; resolve.md §Cadence) — pick → Step 4, stop → Session End.
|
||||
|
||||
## The Clearing Gate
|
||||
|
||||
@@ -124,7 +132,7 @@ The map clears only when ALL hold:
|
||||
3. The destination is reachable with nothing left to decide
|
||||
4. All four confidence dimensions score ≥ 18/25
|
||||
|
||||
Any failing: name it, keep working. All passing: follow the handoff playbook, set `**Status:** Cleared`, stop. The PLAN-DRAFT is always local — `/plan2code-1-plan` cannot read a tracker.
|
||||
Score the four dimensions (handoff.md rubric) and write them to the map's `**Confidence:**` line. `local`: run `gate`; it checks 1, 2 and 4 against the files, plus the handoff preflight and the Requirements, Feasibility and Risk caps; condition 3, the Integration cap and the scores stay yours (its `judgment` list). Any failing: name it, keep working. All passing: follow the handoff playbook, set `**Status:** Cleared`, run `lint`, stop. The PLAN-DRAFT is always local — `/plan2code-1-plan` cannot read a tracker.
|
||||
|
||||
## Trail Footer
|
||||
|
||||
@@ -132,6 +140,8 @@ Read references/trail.md
|
||||
|
||||
> Fallback: once the map exists, end every response with a marker path (`●` done · `◉` here · `○` open · `⊘` blocked · `⊝` out of scope) `START`→`⚑`, a named legend, a plain-English confidence note, then ONE closer: asking → Form B, `WAITING ON YOU`, no command; menu → Form C, `NEXT UP` + `OR START FRESH`; session end → Form A, `NEXT STEP` + resume command with `--web` (map issue URL on `github`).
|
||||
|
||||
Close EVERY response with the trail once the map exists. You pick the form by what the turn does. `local`: `trail` draws it from the files, so paste its output verbatim. Asking → Form B, `trail --form B --item "<probe>" ... --text` (one `--item` per open probe, up to three). Menu after a decision → Form C, `trail --form C` WITHOUT `--text`: paste its `text`, then build the question tool from its `menu`. Session end → Form A, `trail --form A --text`. `github`: draw it by hand per the backend playbook.
|
||||
|
||||
## Session End
|
||||
|
||||
Report each question resolved (name + gist), what graduated, what's still open; offer a brief for today. Nothing to commit — `local` is gitignored, `github` already on the tracker. Then the mascot, then the Trail Footer.
|
||||
@@ -152,7 +162,8 @@ Report each question resolved (name + gist), what graduated, what's still open;
|
||||
|
||||
| Issue | Action |
|
||||
|---|---|
|
||||
| Session stops mid-question, or map drift | Release the claim, note why. Work Step 2 repairs both; questions win. |
|
||||
| Session stops mid-question, or map drift | Release the claim, note why (or leave it: the next reconcile releases a claim with no answer). Work Step 2 repairs both; questions win. Never reconcile mid-question: it would release your own live claim. |
|
||||
| A script cannot run (no `node`) | Say so once; do the step by hand from questions.md (markers, blocking, schema) and the reference that names the step. Footer by hand: the trail's glyph path, then Form A `NEXT STEP · start a new conversation and run:` + the command, Form B `WAITING ON YOU · answer here, in this conversation:` + the items, or Form C `OR START FRESH · new conversation, paste:` + the command. |
|
||||
| Frontier empty, fog remains | Not sharp yet. Grill it into a question, or clear the map |
|
||||
| Reference file missing | Use the fallback blockquote under its `Read` line |
|
||||
| `gh` fails mid-session on a `github` map | Report and STOP. Falling back to local forks the map |
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
|
||||
> Loaded when the user's argument asks for a brief. Produces one plain-English report file for a date range — the artifact a PM pastes into Slack or reads aloud in a meeting. The only mutation BRIEF mode ever performs is the Work Step 2 reconcile; it never claims, resolves, or answers a question.
|
||||
|
||||
> **Backend note.** The report is IDENTICAL either way — same sections, same plain-English rules — and the brief file always lands on **local disk** under `specs/<idea>/pathfinder/briefs/`, even on `**Backend:** github`. What differs is where the inputs come from: on `github` the range filter reads each question issue's close date instead of a `Resolved:` line, and the open / blocked / out-of-scope sections come from the frontier query rather than the checklist — see `github-issues.md`.
|
||||
> **Backend note.** The report is IDENTICAL either way — same sections, same plain-English rules — and the brief file always lands on **local disk** under `specs/<idea>/pathfinder/briefs/`, even on `**Backend:** github`. What differs is where the inputs come from: on `github` the range filter reads each question issue's close date instead of a `Resolved:` line, and the open / blocked / out-of-scope sections come from the frontier query rather than the checklist — see `github-issues.md`. `pathfinder.mjs` reads local files only, so on `github` do each script step below except `lint` by hand with `gh`, as `github-issues.md` describes.
|
||||
|
||||
## When it fires
|
||||
|
||||
@@ -14,17 +14,17 @@ The argument (or message) asks for a `brief`, `summary`, `recap`, or `minutes` f
|
||||
/plan2code-0-pathfinder full brief for specs/<idea>/pathfinder
|
||||
```
|
||||
|
||||
Range grammar is deliberately loose: `today` (the default when unstated) · `this week` · `since <date>` · an explicit `<date>..<date>` · `full` (everything since the map was created). Get today's date from the shell — never guess it.
|
||||
Translate the person's words into the script's range: `today` (the default when unstated) · `this-week` (Monday through today) · `since:<YYYY-MM-DD>` · `<YYYY-MM-DD>..<YYYY-MM-DD>` · `full` (everything since the map was created). Resolve a relative phrase ("since Tuesday") to a date yourself; the script takes dates only and reads today from the clock.
|
||||
|
||||
No `map.md` for the idea? There is nothing to brief — say so and route to charting. `**Status:** Cleared`? A brief is still legitimate: cover the full history and point at the PLAN-DRAFT in `## Next step`.
|
||||
|
||||
## Procedure
|
||||
|
||||
1. **Resolve the idea** exactly as Auto-Discovery does (shell only — `specs/` is gitignored, Glob silently fails).
|
||||
2. **Reconcile first, in full** (Work Step 2): files win over markers, stale claims reset to `open`, absent `Resolved:` dates backfilled from `Claimed:`. Save the repaired map. A brief must never disagree with the map it summarizes — this is why BRIEF mode reconciles rather than reporting drift.
|
||||
3. **Filter**: resolved questions whose `Resolved:` date falls in the range. Out-of-scope rulings are NOT date-filtered — they are standing scope boundaries and appear in every brief.
|
||||
4. **Write** `specs/<idea>/pathfinder/briefs/brief-<YYYYMMDD>.md` (create `briefs/` if absent). The filename carries today's date regardless of range — the `**Covers:**` line disambiguates. Same-day re-runs overwrite: a brief is a report, not a record; the question files remain the record.
|
||||
5. **Report** in chat: the file path, the range, one line on any reconcile repairs. Then the Trail Footer, Form A (the session is over; the command routes by map status as usual).
|
||||
1. **Resolve the idea** exactly as Auto-Discovery does.
|
||||
2. **Reconcile first**: `node "<S>/pathfinder.mjs" reconcile specs/<idea>/pathfinder`. A brief must never disagree with the map it summarizes, which is why BRIEF mode repairs drift rather than reporting it. Keep its `repairs` for step 5.
|
||||
3. **Gather**: `node "<S>/pathfinder.mjs" brief-data specs/<idea>/pathfinder --range <range>`. It filters resolved questions by `Resolved:` date and returns every section's source (below), the file to write, and `drift` / `undatedResolved` (both empty after step 2; if not, rerun step 2). Out-of-scope rulings are never date-filtered: standing scope boundaries appear in every brief.
|
||||
4. **Write** the file at its `file` path (create `briefs/` if absent). The name carries today's date regardless of range; the `**Covers:**` line disambiguates. Same-day re-runs overwrite (`exists: true`): a brief is a report, not a record; the question files remain the record.
|
||||
5. **Report** in chat: the file path, the range, one line on any reconcile repairs. Then the Trail Footer, Form A (the session is over; the command routes by map status as usual). Run `lint` first: it checks the brief for percent signs and scraper bait.
|
||||
|
||||
## The template
|
||||
|
||||
@@ -78,17 +78,17 @@ Run: `/plan2code-0-pathfinder specs/audit-log-export/pathfinder`
|
||||
|
||||
**How each section is built:**
|
||||
|
||||
| Section | Source | Rendering rule |
|
||||
| Section | `brief-data` field | Rendering rule |
|
||||
|---|---|---|
|
||||
| Heading + `**Covers:**` | Idea name in words; the range; `<resolved>/<total>` using the trail's counting rule (out-of-scope rows excluded from the total) | |
|
||||
| Where this is headed | `## Destination`, verbatim | Never paraphrase it |
|
||||
| Decided `<in range>` | Resolved files with `Resolved:` in range | Question name bold, gist as the first line, rejected alternatives compressed to ONE line each with the why in parentheses. `Locked: yes` renders as *Recorded as hard to reverse.* — never the word "locked" |
|
||||
| Ruled out | `## Out of scope`, all of it | One line each: name + why |
|
||||
| Open - ready to decide next | The frontier (open, unclaimed, unblocked) | Flag anything a resolution in range just unblocked: "can now be decided; X landed <day>" |
|
||||
| Open - waiting on something first | `[!]` blocked rows | Name the blocker in plain words ("waiting on the export format decision"), never `Blocked by: 02` |
|
||||
| Still taking shape | `## Not yet specified` | Lightly rephrase each bullet into one plain sentence |
|
||||
| How solid is this? | The map's `**Confidence:**` line | ONLY via trail.md's plain-English mapping (solid / solid-but-borderline / not yet). Omit the section if the map has no confidence line |
|
||||
| Next step | Map status | `Working`/`Charting` → the pathed resume command; `Cleared` → point at the PLAN-DRAFT and `/plan2code-1-plan` |
|
||||
| Heading + `**Covers:**` | `title`, `covers`, `progress` | `progress` already uses the trail's counting rule (out-of-scope excluded from the total) |
|
||||
| Where this is headed | `destination` | Verbatim. Never paraphrase it |
|
||||
| Decided `<in range>` | `decidedHeading`, `decided` (`name`, `gist`, `rejected`, `hardToReverse`) | Question name bold, gist as the first line, each `rejected` entry compressed to ONE line with the why in parentheses. `hardToReverse` renders as *Recorded as hard to reverse.* — never the word "locked". Empty → `note` |
|
||||
| Ruled out | `ruledOut` | One line each: name + why, link markup dropped |
|
||||
| Open - ready to decide next | `ready` | Flag each `justUnblockedBy`: "can now be decided; X landed <day>" |
|
||||
| Open - waiting on something first | `waiting` | Name the blocker in plain words ("waiting on the export format decision"), never `Blocked by: 02` |
|
||||
| Still taking shape | `fog` | Lightly rephrase each bullet into one plain sentence |
|
||||
| How solid is this? | `confidence` | Already the plain-English line. Omit the section when it is null |
|
||||
| Next step | `nextStep` | `command` as given; with a `plan`, point at that PLAN-DRAFT too |
|
||||
|
||||
Nothing decided in the range? Keep the file honest: "No decisions were recorded in this period." under Decided, and render the open sections as usual — a meeting that only surfaced questions still gets minutes.
|
||||
|
||||
|
||||
@@ -351,7 +351,7 @@ Fog gathers **only toward the destination**. The destination fixes the scope, so
|
||||
| Reopening | Automatic, as answers land | Only if the destination is redrawn — and then as a fresh effort, not a resumption |
|
||||
| The act | An admission of ignorance | A scoping decision |
|
||||
|
||||
Ruling something out of scope is a **scoping act, not a step on the route**. When a question you already created turns out to sit past the destination — mis-scoped in during charting, or exposed by a later answer — set `State: out-of-scope`, mark its row `[-]`, and leave one line in `## Out of scope` giving the gist and the reason, linking the question by name. It does not get an `## Answer` and it is not a decision the route walked.
|
||||
Ruling something out of scope is a **scoping act, not a step on the route**. When a question you already created turns out to sit past the destination — mis-scoped in during charting, or exposed by a later answer — run `rule-out <NN> --reason "<why>"` (resolve.md, Ruling a question out of scope mid-work): it sets `State: out-of-scope`, marks its row `[-]` and leaves one linked line in `## Out of scope` with the reason. Then handle anything it reports `stranded`. It does not get an `## Answer` and it is not a decision the route walked.
|
||||
|
||||
Watch for **stranded** questions: a live question whose `Blocked by:` names something now out of scope will never unblock. Re-frame its `## Question` to drop the dependency, or rule it out too. Never leave it sitting.
|
||||
|
||||
@@ -369,7 +369,7 @@ The rules:
|
||||
2. **Blockers get lower numbers.** If *Row-count ceiling* blocks *Delivery channel*, the ceiling is `02` and delivery is `05`. This makes `Blocked by: 02` readable at a glance and makes "lowest `NN` first" on the frontier a sane traversal order.
|
||||
3. **`00` is always the codebase context.** Never anything else.
|
||||
4. **`NN` is never reused and never renumbered.** Not when a question is ruled out of scope, not when one is deleted, not to close a gap in the sequence. Links and `Blocked by:` lines would rot silently. Gaps in the numbering are normal and harmless.
|
||||
5. **The next number is max + 1**, computed from the directory listing, not from the map.
|
||||
5. **The next number is max + 1**, and `frontier` reports it as `nextNN`: one past the highest `NN` in the directory listing, on any `Blocked by:` line, or in any `questions/NN-` link in the map or a question file, and never below the map's `**Next NN:**` line. That line is a high-water mark the script keeps (every write command updates it, and it only rises), so even a deleted question that nothing links to any more never has its number handed out again. Never edit it by hand.
|
||||
6. **Only depend on what genuinely gates the question.** A `Blocked by:` chain that is really a preference for reading order strangles the frontier. Ask: could this question be answered — badly but honestly — without the blocker? If yes, it is not blocked.
|
||||
7. **Cycles are a phrasing bug.** If A blocks B and B blocks A, the two are one decision. Merge them or re-frame one to drop the edge.
|
||||
8. **Refer by name in prose.** Bare numbers appear only on `Blocked by:` lines.
|
||||
@@ -410,11 +410,16 @@ Say once, at Step 5: *"This map lives in gitignored `specs/` — local to you, n
|
||||
**Status:** Working
|
||||
**Updated:** 2026-08-03
|
||||
**Confidence:** Requirements-clarity 18/25 · Feasibility-technical 14/25 · Integration-points 16/25 · Risk-assessment 14/25
|
||||
**Next NN:** 07
|
||||
|
||||
<!-- Status: Charting while the map is being built (Chart Steps 1-6) -> Working once the
|
||||
checklist is indexed (Chart Step 7) -> Cleared only when the Clearing Gate passes.
|
||||
A fresh session routes on this line, so it must be correct before the session ends. -->
|
||||
|
||||
<!-- Next NN: the number the next new question file takes. Kept by the script (reconcile
|
||||
adds it at Chart Step 7 and every write command raises it); it never goes down, so a
|
||||
deleted question's number is never reused. Leave it out at Step 5; never edit it. -->
|
||||
|
||||
<!-- Confidence: four dimensions, each scored out of 25, re-scored at every resolution.
|
||||
The Clearing Gate requires all four at 18/25 or better. Score against evidence. -->
|
||||
|
||||
@@ -431,7 +436,9 @@ plan, not at shipped code. Continuous streaming to external systems is not on th
|
||||
## Ground rules
|
||||
|
||||
<!-- Standing constraints for every session on this map. Read before choosing a question,
|
||||
obeyed while resolving it. Nothing here is re-asked. -->
|
||||
obeyed while resolving it. Nothing here is re-asked. The first line records AGENTS.md:
|
||||
"- `AGENTS.md` exists and governs." or, when it is missing, exactly
|
||||
"- `AGENTS.md` is absent." (the handoff then routes to /plan2code-init first). -->
|
||||
|
||||
- `AGENTS.md` exists and governs. Its conventions are not re-litigated by any question here.
|
||||
- One question _file_ at a time; the fork-menu between decisions; a fresh session recommended after ~3. `research` questions may run as parallel subagents.
|
||||
|
||||
@@ -401,6 +401,8 @@ Form B is unchanged — a turn that asks the human something still says `WAITING
|
||||
|
||||
Form C — the fork-menu after a recorded decision — is unchanged in shape, with two substitutions: the takeable options come from the frontier query rather than the checklist rows, and the `OR START FRESH` command carries the map issue URL. The `RECOMMENDED` marker and the ~3-decision checkpoint work exactly as `trail.md` describes.
|
||||
|
||||
With no script to draw them, the labels are exact: Form A `NEXT STEP · start a new conversation and run:`, Form B `WAITING ON YOU · answer here, in this conversation:`, Form C `OR START FRESH · new conversation, paste:`. The Form C question tool uses the header `Next step` and the question "Continue here, or start fresh? Everything is saved." (add "I recommend starting fresh, to keep me sharp." at the ~3-decision checkpoint). Its options are up to three takeable question names plus `Start fresh`, one marked `RECOMMENDED`.
|
||||
|
||||
---
|
||||
|
||||
## BRIEF mode
|
||||
|
||||
@@ -2,22 +2,28 @@
|
||||
|
||||
Loaded at The Clearing Gate. Turns a cleared map into `specs/<idea>/PLAN-DRAFT-<YYYYMMDD>.md` that `/plan2code-1-plan` resumes from at Phase 4, then freezes `pathfinder/` as the rationale record.
|
||||
|
||||
**Backend note.** The scoring rubric, the hard caps, the honesty rules, the template, and the mapping table are the same either way — and the draft is written to local disk either way, because `/plan2code-1-plan` reads a file, not a tracker. On `**Backend:** github`, `github-issues.md` replaces only the preflight table, the question links (issue URLs, already absolute), and the freeze steps.
|
||||
**Backend note.** The scoring rubric, the hard caps, the honesty rules, the template, and the mapping table are the same either way — and the draft is written to local disk either way, because `/plan2code-1-plan` reads a file, not a tracker. On `**Backend:** github`, `github-issues.md` replaces only the preflight table, the question links (issue URLs, already absolute), and the freeze steps. `pathfinder.mjs` reads local files only, so on `github` do each script step below except `lint` by hand with `gh`, as `github-issues.md` describes.
|
||||
|
||||
Nothing here is creative. The gate is scored, the mapping is fixed, the template is literal. Follow it exactly or the resuming plan session silently loses work.
|
||||
|
||||
## Preflight — before scoring anything
|
||||
|
||||
| # | Check | If it fails |
|
||||
|---|---|---|
|
||||
| 1 | Re-run the reconcile pass: read every file in `questions/`, rebuild every map marker from the files | Fix the map first. Markers are derived, never authored. |
|
||||
| 2 | Zero `[ ]`, zero `[/]`, zero `[!]` rows in `## Question Checklist` | Not cleared. Return to the frontier. |
|
||||
| 3 | `## Not yet specified` is empty | Not cleared. Graduate the fog into questions, or admit it is out of scope. |
|
||||
| 4 | Every `[x]` row's file has a real `## Answer` with a `**Gist:**` | The file wins over the marker. Repair, then re-check. |
|
||||
| 5 | `ls specs/<idea>/` shows no existing `PLAN-DRAFT-*.md` | One already exists — read it. Update it in place; never add a second dated draft. |
|
||||
| 6 | The destination is reachable with nothing left to decide — no `## Answer` defers a choice to "whoever implements this" | Not cleared. Name the open decision and graduate it into a question. |
|
||||
Run `reconcile`, then `node "<S>/pathfinder.mjs" gate specs/<idea>/pathfinder`. Its `checks` cover the mechanical preflight, read from the files:
|
||||
|
||||
Only after all six pass do you score the four dimensions.
|
||||
| `checks` id | Means | If it fails |
|
||||
|---|---|---|
|
||||
| `markers-match-files` | The map's markers are the files' (reconcile ran) | Run `reconcile`. Markers are derived, never authored. |
|
||||
| `no-open-claimed-blocked` | Zero `[ ]`, `[/]`, `[!]` | Not cleared. Return to the frontier. |
|
||||
| `fog-empty` | `## Not yet specified` is empty | Not cleared. Graduate the fog into questions, or admit it is out of scope. |
|
||||
| `every-resolved-has-gist` | Every resolved file has a real `## Answer` with a `**Gist:**` | The file wins over the marker. Repair, then re-check. |
|
||||
| `hard-caps` | None of the Requirements, Feasibility or Risk caps below holds (the Integration cap is yours to check) | That dimension cannot exceed 17: fix the record first. |
|
||||
| `scores-at-least-18` | The map's `**Confidence:**` line has all four at 18 or better | Not cleared. Keep working the weak dimension. |
|
||||
|
||||
`existingPlanDraft` lists a `PLAN-DRAFT-*.md` already in `specs/<idea>/`: read it and update it in place, never add a second dated draft. `planDraftPath` is the file to write either way.
|
||||
|
||||
One preflight item stays yours: **the destination is reachable with nothing left to decide**: no `## Answer` defers a choice to "whoever implements this". If one does, the map is not cleared: name the open decision and graduate it into a question.
|
||||
|
||||
Score the four dimensions (below), write them to the map's `**Confidence:**` line, and rerun `gate` until `mechanicalPass` is true.
|
||||
|
||||
## The clearing-gate scoring rubric
|
||||
|
||||
@@ -45,7 +51,7 @@ The 18-boundary is the honest line between *"needs designing"* and *"needs decid
|
||||
|
||||
### Hard caps
|
||||
|
||||
A cap overrides your judgment. While a cap condition holds, the dimension **cannot** exceed 17, so the gate cannot pass.
|
||||
A cap overrides your judgment. While a cap condition holds, the dimension **cannot** exceed 17, so the gate cannot pass. `gate` reports the Requirements, Feasibility and Risk caps from the files (`caps`); the Integration cap needs you to match the destination's systems to questions.
|
||||
|
||||
| Cap | Condition |
|
||||
|---|---|
|
||||
@@ -107,7 +113,7 @@ Consequences of that being a literal string match:
|
||||
- Copy it byte for byte. Plain ASCII hyphen-minus surrounded by single spaces. An en dash, a colon, or "Phase 3 complete" in lower case breaks the match and 1-plan starts over at Phase 1 — throwing away every decision the map holds.
|
||||
- It goes on its own `**Status:**` line in the header block, not buried in prose.
|
||||
- The file must be named `PLAN-DRAFT-<YYYYMMDD>.md` and live directly in `specs/<idea>/`. `PLAN-DRAFT-*.md` is a reserved name inside `pathfinder/` — never write it there.
|
||||
- Get the date from the shell (`date +%Y%m%d` in Bash, `Get-Date -Format yyyyMMdd` in PowerShell). Do not guess it.
|
||||
- Use the date in `gate`'s `planDraftPath` (it reads the clock). Do not guess it. On `github` (no `gate`), take today's date from the shell and check `ls specs/<idea>/` for an existing draft.
|
||||
|
||||
**Discovery is shell-only.** `specs/` is gitignored, so Glob silently returns nothing and every downstream skill would report "no PLAN-DRAFT found". Use `ls specs/` and `ls specs/<idea>/` (Bash) or `Get-ChildItem specs/` (PowerShell) — the same rule 1-plan and `/plan2code-2-document` follow when they look for the file you are about to write.
|
||||
|
||||
@@ -338,6 +344,8 @@ The reason is exact. When a PLAN-DRAFT carries no `METRICS_JSON` comment, the me
|
||||
|
||||
Never drop the footer to make the file tidier. It is load-bearing.
|
||||
|
||||
After writing the draft, run `lint`: it scans a pathfinder-written PLAN-DRAFT with the metrics collector's own patterns and names any bait that reached the page.
|
||||
|
||||
## System Context and Scope Assessment — why they buy you Phase 4
|
||||
|
||||
These two named, unnumbered sections are what make "Resume at Phase 4" legitimate rather than a shortcut. They stand in for the phases pathfinder already did the work of:
|
||||
|
||||
@@ -19,7 +19,7 @@ specs/<idea>/
|
||||
|
||||
## Numbering
|
||||
|
||||
`NN` is zero-padded from `00`, assigned in dependency order (blockers lower), **never reused or renumbered** — links and `Blocked by:` would rot silently. Next = max + 1. `00` is always `00-codebase-context.md`, never anything else. Gaps in the sequence are normal and harmless.
|
||||
`NN` is zero-padded from `00`, assigned in dependency order (blockers lower), **never reused or renumbered** — links and `Blocked by:` would rot silently. Next = max + 1 (`frontier`'s `nextNN`), never below the map's `**Next NN:**` high-water line, which the script keeps so a deleted question's number stays retired (chart.md, Step 6 rule 5). A one-digit file name (`1-export.md`) still reads as `01`, but `lint` asks for the rename. `00` is always `00-codebase-context.md`, never anything else. Gaps in the sequence are normal and harmless.
|
||||
|
||||
## The six schema lines
|
||||
|
||||
@@ -42,4 +42,6 @@ Each question file carries six contiguous `Key: value` lines after its H1 — NO
|
||||
|
||||
**Map markers**, rebuilt from the files every session: `[ ]` open — **these rows ARE the frontier** · `[/]` claimed · `[x]` resolved · `[!]` open but blocked · `[-]` out of scope. Resolved rows carry the gist plus the `Resolved:` date in italics: `— <gist> *(YYYY-MM-DD)*`.
|
||||
|
||||
`scripts/pathfinder.mjs` implements exactly these rules (`reconcile` rebuilds the markers, `frontier` computes blocking, `lint` checks the schema), so this file is the reference for reading its output and for writing a question file. Apply the rules by hand only when the script cannot run.
|
||||
|
||||
**Unblocked** ⟺ every `NN` in `Blocked by:` is `resolved`. **Stranded:** a blocker gone `out-of-scope` never resolves — the question is not merely blocked. Re-frame its `## Question` to drop the dependency, or rule it out too. Never leave it sitting.
|
||||
@@ -2,7 +2,7 @@
|
||||
|
||||
> Loaded at the top of MODE B. Work Step 6 routes here by `Type:`; Work Step 8 uses the fog procedure at the end.
|
||||
>
|
||||
> **Backend note.** Every resolution technique here is backend-independent — the type table, the primary-source rule, the sketch tiers, the checklist discipline, the `## Answer` anatomy. On `**Backend:** github`, `Type:` is a `pathfinder:<type>-<mode>` label, `## Answer` and `## Evidence` are comments rather than file sections, and a research subagent gets an issue URL instead of a path; see `github-issues.md`. Sketches stay on local disk regardless.
|
||||
> **Backend note.** Every resolution technique here is backend-independent — the type table, the primary-source rule, the sketch tiers, the checklist discipline, the `## Answer` anatomy. On `**Backend:** github`, `Type:` is a `pathfinder:<type>-<mode>` label, `## Answer` and `## Evidence` are comments rather than file sections, and a research subagent gets an issue URL instead of a path; see `github-issues.md`. Sketches stay on local disk regardless. `pathfinder.mjs` reads local files only, so on `github` do each script step below except `lint` by hand with `gh`, as `github-issues.md` describes.
|
||||
|
||||
Every question resolves into the SAME shape — a filled `## Answer` plus whatever `## Evidence` backs it. The type only decides how you get there.
|
||||
|
||||
@@ -14,7 +14,7 @@ Every question resolves into the SAME shape — a filled `## Answer` plus whatev
|
||||
| `legwork · HITL` | Human does, agent waits | No | The human confirmed it is done |
|
||||
| `grill · HITL` | Human decides, agent interrogates | No — but probes batch, up to 3 per turn | The human said it in their own words |
|
||||
|
||||
**One question _file_ at a time** holds for every row except `research` — several may resolve in one session, but strictly in sequence, per the Cadence below. HITL rows are never self-answered — an agent that writes its own `## Answer` on a `grill` has broken the skill.
|
||||
**One question _file_ at a time** holds for every row except `research` — several may resolve in one session, but strictly in sequence, per the Cadence below. `research` is also the one type that is **never claimed**: its subagents fire unclaimed (the file stays `State: open`), so `claim` and its one-claim rule govern grill, sketch and legwork only, and a grill can be claimed while research runs. A research question is finished with `## Answer` plus `resolve` once its subagent is back, or re-fired from `reconcile`'s `refire` if it was cut off. HITL rows are never self-answered — an agent that writes its own `## Answer` on a `grill` has broken the skill.
|
||||
|
||||
Every file you create along the way — question files, sketch READMEs — opens with the banner:
|
||||
|
||||
@@ -42,7 +42,7 @@ The restart costs one paste and loses nothing: every claim, answer, and map upda
|
||||
|
||||
- Read only what the cycle needs: the claimed question file plus resolved neighbors' *gists* (Work Step 5). Never re-read the whole `questions/` directory between cycles — reconcile ran once at session start, and this session is the only writer.
|
||||
- The menu renders from the map's checklist rows, never from re-reading question files.
|
||||
- Strictly one claim open at any moment. Claim → record → release, then the menu. Never two.
|
||||
- Strictly one claim open at any moment. Claim → record → release, then the menu. Never two. (Research subagents run unclaimed beside it; see the top of this file.)
|
||||
|
||||
**Group sessions.** When Product and Engineering (or any room) work the map together, the grilling playbook's group-session rules apply: probes address the room, the recap captures the decision in the room's words, and a contested pick is never recorded as decided — both positions go under `## Evidence`, the question stays `open`, and the menu moves on (or offer to convert it to `sketch`; reacting to something concrete resolves more standoffs than argument). At Session End, offer `write a brief for today` — the brief doubles as the meeting minutes.
|
||||
|
||||
@@ -52,7 +52,7 @@ The restart costs one paste and loses nothing: every claim, answer, and map upda
|
||||
|
||||
## `research · AFK`
|
||||
|
||||
The only type an agent resolves alone, and the only type that may run several at once. Charting fires them in a batch at Chart Step 8; MODE B fires any that appear later the same way.
|
||||
The only type an agent resolves alone, and the only type that may run several at once. Charting fires them in a batch at Chart Step 8; MODE B fires any that appear later the same way, unclaimed: never run `claim` on a research question. When one tops the frontier at Work Step 4, fire it, then claim the first non-research question.
|
||||
|
||||
### Spin up a subagent
|
||||
|
||||
@@ -78,7 +78,7 @@ Subagents run inside this session's process, even when the harness runs them in
|
||||
|
||||
### Interrupted research
|
||||
|
||||
At Work Step 2 (Reconcile), any research question that is not resolved and whose `## Evidence` lacks the `**Research complete:**` line was never finished: a closed terminal, a crash, a rate limit. Re-fire its subagent with the same brief, plus one instruction: keep what is already in `## Evidence`, verify it, fill the gaps, then write the line. Say so in one line to the human. A map written before this line existed shows the same symptom; re-firing it costs a little time and nothing else.
|
||||
At Work Step 2, `reconcile` lists in `refire` every research question that is not resolved and whose `## Evidence` lacks the `**Research complete:**` line (with its path and `## Question` text for the brief): it was never finished, by a closed terminal, a crash, a rate limit. Re-fire its subagent with the same brief, plus one instruction: keep what is already in `## Evidence`, verify it, fill the gaps, then write the line. Say so in one line to the human. A map written before this line existed shows the same symptom; re-firing it costs a little time and nothing else.
|
||||
|
||||
### Primary sources only
|
||||
|
||||
@@ -421,7 +421,7 @@ If the legwork turns out to BE the deliverable rather than an unblocker — you
|
||||
|
||||
> "This has stopped being legwork that unblocks a decision and become the work itself. Pathfinder plans; it doesn't build. I'm ruling this out of scope and it belongs in planning."
|
||||
|
||||
Rule the question `out-of-scope`, mark the map row `[-]`, add one line to `## Out of scope` naming what it turned into, and hand off to `/plan2code-1-plan` for that piece. Never let pathfinder quietly become the implementation.
|
||||
Rule the question out with `rule-out <NN> --reason "<what it turned into>"` (it marks the row `[-]` and adds the `## Out of scope` line), and hand off to `/plan2code-1-plan` for that piece. Never let pathfinder quietly become the implementation.
|
||||
|
||||
---
|
||||
|
||||
@@ -446,7 +446,7 @@ A good grill `## Answer` contains four things:
|
||||
|
||||
## Writing the `## Answer`
|
||||
|
||||
Same anatomy for every type. Append it at Work Step 7; never edit `## Question` to match the answer. In the same write, set `State: resolved` **and** `Resolved:` to today's date (`YYYY-MM-DD`, from the shell, never guessed) — the date is what lets a brief report "decided on <day>", so a resolution without it is incomplete.
|
||||
Same anatomy for every type. Append it at Work Step 7; never edit `## Question` to match the answer. Then run `node "<S>/pathfinder.mjs" resolve specs/<idea>/pathfinder <NN>`: it sets `State: resolved` **and** `Resolved:` to today (from the clock; the date is what lets a brief report "decided on <day>"), and writes the map row from your `**Gist:**`. It refuses an Answer with no Gist line.
|
||||
|
||||
| Part | Required | Content |
|
||||
|---|---|---|
|
||||
@@ -519,7 +519,7 @@ The map row it produces — gist, then the `Resolved:` date in italics:
|
||||
|
||||
1. **Re-read `## Not yet specified` in full.** Every bullet, every session, after every resolution. Not the ones you remember — you are assuming no memory of prior sessions, and the bullet that graduates is usually the one you forgot was there.
|
||||
2. **Ask of each bullet: did the answer just make this sharp?** Can you now write a `## Question` paragraph a stranger could act on, without "we'll need to figure out" anywhere in it?
|
||||
3. **If yes, write the question file NOW** — in this same session, before Work Step 9. Next `NN` = max existing + 1, never reused. Fill all five metadata lines, with `Blocked by:` wired in the same pass. Add its `[ ]` or `[!]` row to `## Question Checklist`.
|
||||
3. **If yes, write the question file NOW** — in this same session, before Work Step 9. Its `NN` is `frontier`'s `nextNN` (max existing + 1, from the directory, never reused). Fill all six schema lines, with `Blocked by:` wired in the same pass. `reconcile` then adds its `[ ]` or `[!]` row to `## Question Checklist`.
|
||||
4. **DELETE the bullet from `## Not yet specified`.** Immediately, in the same edit as writing the file.
|
||||
5. **If no, leave the bullet alone** — untouched, not reworded into something that merely sounds sharper.
|
||||
6. **Re-check the counts.** One fog patch may graduate into three questions, or into none. Both are normal. A patch that graduates into three was written at the right coarseness; a patch that graduates into exactly one every time was probably a question all along.
|
||||
@@ -538,10 +538,9 @@ Detection is cheap: after writing any graduated question file, re-read `## Not y
|
||||
|
||||
The destination fixes the scope. When a resolution reveals that a question — the one you just claimed, or another on the map — sits past the destination:
|
||||
|
||||
1. Set that file's `State: out-of-scope`. Do NOT write a `## Answer`; there is no decision, only a scope boundary. Add one line under `## Question` saying why it is out.
|
||||
2. Set its map row to `[-]`.
|
||||
3. Add one line to `## Out of scope`: the name as a link, plus the reason.
|
||||
4. Check for **stranded** questions — anything whose `Blocked by:` names it. A blocker that is `out-of-scope` will never be `resolved`, so the dependent is permanently blocked. Re-frame its `## Question` to drop the dependency, or rule it out too. Never leave it sitting.
|
||||
1. Decide the one-line reason. Do NOT write a `## Answer`; there is no decision, only a scope boundary.
|
||||
2. Run `node "<S>/pathfinder.mjs" rule-out specs/<idea>/pathfinder <NN> --reason "<why>"`. It sets `State: out-of-scope`, adds the reason under `## Question`, marks the row `[-]` and adds the linked line to `## Out of scope`.
|
||||
3. Handle its `stranded` list: questions whose `Blocked by:` names it. A blocker that is `out-of-scope` will never be `resolved`, so the dependent is permanently blocked. Re-frame its `## Question` to drop the dependency, or rule it out too. Never leave it sitting.
|
||||
|
||||
Out-of-scope work never graduates back. The frontier stops at the destination. It returns only if the destination is redrawn, and then as a fresh effort with a fresh map.
|
||||
|
||||
@@ -559,9 +558,9 @@ An answer can also break questions that already exist. Three cases:
|
||||
| What happened | Do this |
|
||||
|---|---|
|
||||
| The question still matters but is asked wrong | **Re-frame.** Rewrite `## Question` in place. Keep `NN`, keep the file, keep the links. Add one line noting which answer forced the re-frame. |
|
||||
| The question no longer exists — the answer subsumed it | **Delete the file and its map row.** Add one line to the answering question's `## Answer` consequences saying what it absorbed. Do not renumber anything. |
|
||||
| The question no longer exists — the answer subsumed it | **Delete the file, then run `reconcile`** (it drops the map row). Add one line to the answering question's `## Answer` consequences saying what it absorbed. Do not renumber anything. |
|
||||
| The question is now two questions | **Re-frame the original to the narrower half; write a new file at max+1 for the other.** Wire `Blocked by:` between them if one gates the other. |
|
||||
|
||||
Never leave a question standing that you know is wrong on the theory that a later session will notice. It will not — it assumes no memory, and a well-formed `## Question` reads as intentional.
|
||||
|
||||
Two hard constraints on all three cases: **`NN` is never reused and never renumbered** — links and `Blocked by:` lines would rot silently. And every re-frame or deletion is reflected in the map's `## Question Checklist` in the same edit, so the index never disagrees with the files.
|
||||
Two hard constraints on all three cases: **`NN` is never reused and never renumbered** — links and `Blocked by:` lines would rot silently. And run `reconcile` straight after any re-frame or deletion, so the index never disagrees with the files (it drops the row of a deleted file and adds one for a new file).
|
||||
@@ -2,193 +2,85 @@
|
||||
|
||||
> Loaded at the top of the skill. Read once; it applies to EVERY response in both modes. Defines the map visual and the pathed resume command that close each turn.
|
||||
>
|
||||
> **Backend note.** The glyphs, the two forms, and the discipline are identical either way. On `**Backend:** github` the inputs come from the sub-issue query rather than the checklist, and Form A's command is the map issue URL — see `github-issues.md`.
|
||||
> **Backend note.** The glyphs, the two forms, and the discipline are identical either way. On `**Backend:** github` the inputs come from the sub-issue query rather than the checklist, and Form A's command is the map issue URL — see `github-issues.md`. `pathfinder.mjs` reads local files only, so on `github` do each script step below except `lint` by hand with `gh`, as `github-issues.md` describes.
|
||||
|
||||
The trail is how a human with no memory of the last session sees, at a glance, how far the map has come and what is left — and copies the exact command to resume without hunting for a path that lives in gitignored `specs/`. It closes every response once a map exists.
|
||||
|
||||
It is **presentation only**. Rebuild it fresh from `map.md` each response; never write it to disk, and never let it emit a loop token (`TASK_COMPLETE`, `PHASE_COMPLETE`, and the rest). It is an index of an index — the question files remain ground truth.
|
||||
|
||||
---
|
||||
|
||||
## When it renders
|
||||
|
||||
| Situation | Footer? |
|
||||
|---|---|
|
||||
| `map.md` exists and the turn **ends the session** — Session End, a cleared map, a fully blocked frontier | **Yes**, both parts: the trail, then the resume command (Form A) |
|
||||
| `map.md` exists and the turn **asks the human something** — a probe batch, a sketch put up for reaction, a `legwork · HITL` checklist | **Yes**, but with the waiting form of Part 2 (Form B). Never a resume command — see below |
|
||||
| `map.md` exists and the turn **offers the menu after a recorded decision** — the continue-or-stop fork of the Work cadence | **Yes**, the fork form of Part 2 (Form C): the takeable questions AND the resume command as the stop branch |
|
||||
| Intent Gate (Step 0), the no-fog off-ramp, or any route-and-stop before Step 5 | **No** — no map on disk yet, and no path to resume. There is nothing to draw. |
|
||||
|
||||
One idea per session, so there is only ever one trail. Draw the trail for the active idea and no other.
|
||||
|
||||
---
|
||||
|
||||
## The two parts
|
||||
|
||||
Always in this order, after everything else in the response:
|
||||
|
||||
1. **The trail** — the horizontal path plus its legend and confidence line. Identical on every turn.
|
||||
2. **The next line** — either the pathed resume command or the waiting notice, chosen by turn type.
|
||||
|
||||
### Part 1 — the trail
|
||||
It is **presentation only**, rebuilt fresh from the files every response and never written to disk. The script draws it; you choose its form.
|
||||
|
||||
```
|
||||
🧭 audit-log-export · Working · 2/7 cleared
|
||||
node "<S>/pathfinder.mjs" trail specs/<idea>/pathfinder --form A|B|C [--item "<probe>" ...] --text
|
||||
```
|
||||
|
||||
`--text` prints the footer itself: paste it verbatim as the last thing in the response. Use it for Forms A and B. For Form C leave `--text` off: the JSON carries the same `text` plus the `menu` the question tool needs. Run `reconcile` first in a session (Work Step 2) so the files it reads are settled.
|
||||
|
||||
---
|
||||
|
||||
## When it renders, and which form
|
||||
|
||||
The **turn type** picks the form, never the map's status. This is the one decision the script cannot make for you.
|
||||
|
||||
| Situation | Footer |
|
||||
|---|---|
|
||||
| `map.md` exists and the turn **ends the session** — Session End, a cleared map, a fully blocked frontier, a parked grill | **Form A**: the trail, then the resume command |
|
||||
| `map.md` exists and the turn **asks the human something** — a probe batch, a sketch put up for reaction, a `legwork · HITL` checklist, the Chart Step 2 destination grill, the Chart Step 4 frontier grill | **Form B**: the trail, then the waiting notice. Never a resume command |
|
||||
| `map.md` exists and the turn **offers the menu after a recorded decision** — the continue-or-stop fork of the Work cadence | **Form C**: the trail, the `OR START FRESH` command, then the question tool |
|
||||
| Intent Gate (Step 0), the no-fog off-ramp, or any route-and-stop before Step 5 | **None** — no map on disk yet, and no path to resume |
|
||||
|
||||
One idea per session, so there is only ever one trail.
|
||||
|
||||
### What the script draws (so you can read it, not build it)
|
||||
|
||||
```
|
||||
🧭 audit-log-export · Working · 2/6 cleared
|
||||
START ●━●━◉··○··○··⊘··⊝ ····⚑
|
||||
● done · ◉ here · ○ open · ⊘ blocked · ⊝ out of scope · ⚑ destination · ~4 fog
|
||||
1 Codebase context ✔ · 2 Export format ✔ · 3 Row-count ceiling ◀ here
|
||||
4 Export authorization · 5 Testing posture · 6 Delivery channel (blocked:3) · 7 SIEM push (out of scope)
|
||||
1 Codebase context ✔ · 2 Export format ✔ · 3 Row-count ceiling ◀ here · 4 Export authorization
|
||||
5 Testing posture · 6 Delivery channel (blocked:3) · 7 SIEM push (out of scope)
|
||||
Confidence: solid, but Risk is borderline.
|
||||
```
|
||||
|
||||
How each line is built, top to bottom:
|
||||
|
||||
- **Heading** — `🧭 <idea> · <Status> · <resolved>/<total> cleared`. `<Status>` is the map's `**Status:**` verbatim (`Charting` / `Working` / `Cleared`). `<resolved>` counts `[x]` rows; `<total>` counts every question row **except** out-of-scope `[-]` rows (a ruled-out question is off the route, not an unfinished stop).
|
||||
- **The path** — one glyph per question row in `NN` order, left to right, from `START` to the `⚑` destination. Connectors carry meaning: solid `━` joins stops already walked (everything up to and including `◉ here`); dashed `··` joins stops still ahead. After the last question glyph, a fog stretch `····` then `⚑` — drop both if there is no fog and join straight to `⚑` with `━`.
|
||||
- **The legend** — only the glyphs actually on this path, so a map with no blocked question does not advertise `⊘`. Append `~N fog` when `## Not yet specified` holds N bullets.
|
||||
- **The named legend** — the same `NN` order, `<NN> <Name>` each, `·`-separated, wrapping across lines as needed. Tag each: `✔` resolved, `◀ here` the claimed one, `(blocked:NN)` with its blocker, `(out of scope)`. Names come straight from the checklist rows.
|
||||
- **Confidence** — the map's four internal scores (Requirements / Feasibility / Integration / Risk, each out of 25) exist for the Clearing Gate, not the human. Never print the raw numbers or the `R·F·I·K` letters. Instead, reduce them to one plain-English line:
|
||||
|
||||
| Scores | Line |
|
||||
|---|---|
|
||||
| All four ≥ 20 | `Confidence: solid.` |
|
||||
| All four ≥ 18, one or more sitting at 18-19 | `Confidence: solid, but <Dimension> is borderline.` (name every dimension in that range, comma-separated) |
|
||||
| Any dimension < 18 | `Confidence: not yet — <Dimension(s)> still need work.` |
|
||||
|
||||
Omit the whole line if the map has no `**Confidence:**` line yet.
|
||||
|
||||
### Glyph reference
|
||||
|
||||
| Glyph | Map marker | Meaning |
|
||||
|---|---|---|
|
||||
| `●` | `[x]` | resolved — a stop already walked |
|
||||
| `◉` | `[/]` | the claimed question — you are here |
|
||||
| `○` | `[ ]` | open, on the frontier |
|
||||
| `⊘` | `[!]` | open but blocked |
|
||||
| `⊝` | `[-]` | ruled out of scope |
|
||||
| `⚑` | — | the destination |
|
||||
| `····` | — | the fog still between the last question and the destination |
|
||||
|
||||
### Part 2 — the next line
|
||||
|
||||
Part 2 answers exactly one question for the human: **is this turn over, or is it my move?** It has three forms, and the **turn type** picks between them — not the map's status.
|
||||
|
||||
#### Form A — the turn ends the session
|
||||
|
||||
```
|
||||
NEXT STEP · start a new conversation and run:
|
||||
`/plan2code-0-pathfinder specs/audit-log-export/pathfinder --web`
|
||||
```
|
||||
|
||||
The path is always relative and always ends `/pathfinder` — that is exactly the argument this skill's Auto-Discovery resolves an idea from, so the human pastes it back with zero edits. Fill `<idea>` from the active map's directory; never leave the `<spec-folder>` placeholder in a rendered footer.
|
||||
|
||||
The command target follows the map's status, but the sentence is always the same shape — `start a new conversation and run:` followed by the command on its own line:
|
||||
|
||||
| Status | Command |
|
||||
|---|---|
|
||||
| `Charting` / `Working` | `/plan2code-0-pathfinder specs/<idea>/pathfinder --web` |
|
||||
| `Cleared` | `/plan2code-1-plan --web` — point at the PLAN-DRAFT the Clearing Gate wrote |
|
||||
| `Cleared`, but `## Ground rules` records `AGENTS.md` **absent** | `/plan2code-init` FIRST (offer `questions/00-codebase-context.md`), then `/plan2code-1-plan --web` |
|
||||
|
||||
#### Form B — the turn asks the human something
|
||||
|
||||
Any turn whose next move is theirs and happens **in this same conversation**: a batch of grill probes, a sketch put up for reaction, a `legwork · HITL` checklist, the Chart Step 2 destination grill, the Chart Step 4 frontier grill.
|
||||
|
||||
```
|
||||
WAITING ON YOU · answer here, in this conversation:
|
||||
Q1 Duration model · Q2 Contract while held · Q3 Placement & restore
|
||||
```
|
||||
|
||||
Name every outstanding item at its stable number so a partial reply is cheap to give and a dropped probe is visible to both of you. `·`-separated on one line; one per line if the names run long. Never more items than the three-probe cap allows.
|
||||
|
||||
**Emit no resume command on a Form B turn.** There is nothing to resume — the session is alive and holding a claim. A resume command here reads as *we're done*, and the human either walks away mid-decision or burns the next turn asking what you meant. This is the single most common way the footer misfires, and it costs the batch the round trips batching was introduced to save.
|
||||
|
||||
One exception: `grilling.md`'s unreachable-human procedure. Parking a mid-grill question and stopping IS a session end — use Form A, and say in the body that the question is parked mid-grill with its batch outstanding.
|
||||
|
||||
#### Form C — the menu after a recorded decision
|
||||
|
||||
Used ONLY on the Work cadence's fork-menu turn (resolve.md §Cadence), immediately after an `## Answer` landed and the map row flipped `[x]`. It is the one legitimate hybrid: an *explicit* continue-or-stop fork where the resume command IS the stop branch, not a farewell.
|
||||
|
||||
First print the stop branch, clearly labeled:
|
||||
|
||||
```
|
||||
OR START FRESH · new conversation, paste:
|
||||
`/plan2code-0-pathfinder specs/audit-log-export/pathfinder --web`
|
||||
```
|
||||
|
||||
Then invoke the structured question tool (header `Next step`) asking: "Continue here, or start fresh? Everything is saved." Options: up to three takeable question names, then `Start fresh`. Put each question's gist / newly-unblocked note in its description. The automatic `Other` path lets the human name another frontier question not shown. Mark one option's description `RECOMMENDED` — early in the session that is a question; at the checkpoint it is `Start fresh`.
|
||||
|
||||
Rules for Form C:
|
||||
|
||||
- **The command label is mandatory and exact:** `OR START FRESH · new conversation, paste:`. It makes the command the stop branch, not a farewell. Never render a bare command on a menu turn.
|
||||
- **The choice itself always uses the structured tool.** Never print `NEXT UP` as a prose menu when the tool exists.
|
||||
- Options come from the map's checklist rows (names + gists), takeable questions only. Flag anything the decision just recorded unblocked. The fourth slot is `Start fresh`; `Other` covers a frontier question omitted from the top three.
|
||||
- **The recommendation carries the checkpoint** (resolve.md §Cadence): early in a session recommend a question; after ~3 resolved this session — or after a heavy, contested, or `Locked: yes` decision — recommend `Start fresh`, with the reason said in the question text ("to keep me sharp").
|
||||
- **Form C never replaces Form B.** A turn that asks probes, shows a sketch, or hands over a checklist is Form B, no command. Form C fires only between decisions, when nothing is claimed.
|
||||
- If the human walks away mid-menu, nothing is stranded: no claim is open, and the command to come back is already on screen.
|
||||
|
||||
---
|
||||
|
||||
## State-by-state examples
|
||||
|
||||
**Charting, mid-grill, no question claimed yet** (`◉` is omitted; the frontier head is the first `○`). The Chart Step 4 frontier grill is a Form B turn — the batch is above, so the footer says stay:
|
||||
|
||||
```
|
||||
🧭 audit-log-export · Charting · 1/5 cleared
|
||||
START ●··○··○··○··○ ····⚑
|
||||
● done · ○ open · ⚑ destination · ~6 fog
|
||||
1 Codebase context ✔ · 2 Export format · 3 Export authorization · 4 Testing posture · 5 Row-count ceiling
|
||||
Confidence: not yet — Requirements, Feasibility, Integration, Risk still need work.
|
||||
|
||||
WAITING ON YOU · answer here, in this conversation:
|
||||
Q1 Data · Q2 Surface · Q3 Permissions
|
||||
```
|
||||
|
||||
**Working, a claimed question mid-grill** — probes are out, the claim is held, nothing is resolved yet. Same trail, Form B again. Note that Q2 is a re-ask carried over at its original number from a batch that came back partial:
|
||||
|
||||
```
|
||||
🧭 audit-log-export · Working · 2/7 cleared
|
||||
START ●━●━◉··○··○··⊘··⊝ ····⚑
|
||||
● done · ◉ here · ○ open · ⊘ blocked · ⊝ out of scope · ⚑ destination · ~4 fog
|
||||
1 Codebase context ✔ · 2 Export format ✔ · 3 Row-count ceiling ◀ here
|
||||
4 Export authorization · 5 Testing posture · 6 Delivery channel (blocked:3) · 7 SIEM push (out of scope)
|
||||
Confidence: not yet — Feasibility, Integration, Risk still need work.
|
||||
|
||||
WAITING ON YOU · answer here, in this conversation:
|
||||
Q2 Ceiling behaviour past the cap (re-ask) · Q3 Who sees the truncation warning
|
||||
```
|
||||
|
||||
**Frontier fully blocked** — report the chain in the body; the trail shows why nothing is takeable. Work Step 4 stops the session here, so Form A:
|
||||
- The heading counts resolved questions over every question except out-of-scope ones.
|
||||
- One glyph per question in `NN` order: `●` resolved, `◉` claimed, `○` open, `⊘` blocked, `⊝` out of scope. A solid `━` leads into a walked stop (`●`, `◉`); `··` leads into one still ahead. `····⚑` stands for the fog; with no fog the path ends `━⚑` once every stop is walked (or ruled out) and `··⚑` while any is still ahead. A cleared map ends `━⚑ arrived` and drops both legend lines.
|
||||
- The named legend numbers stops by position, and `(blocked:3)` points at stop 3.
|
||||
- The confidence line is the map's four internal scores reduced to plain English: `solid` (all ≥ 20), `solid, but <Dimension> is borderline` (all ≥ 18, some at 18-19), `not yet — <Dimension(s)> still need work` (any < 18). The raw numbers never reach the human. No `**Confidence:**` line on the map, no confidence line in the trail.
|
||||
|
||||
```
|
||||
🧭 audit-log-export · Working · 5/7 cleared
|
||||
START ●━●━●━●━●━⊘··⊘ ⚑
|
||||
● done · ⊘ blocked · ⚑ destination
|
||||
6 Delivery channel (blocked:2) · 7 Notification (blocked:6)
|
||||
Confidence: not yet — Feasibility, Risk still need work.
|
||||
---
|
||||
|
||||
NEXT STEP · start a new conversation and run:
|
||||
`/plan2code-0-pathfinder specs/audit-log-export/pathfinder --web`
|
||||
```
|
||||
## Form A — the turn ends the session
|
||||
|
||||
**Cleared** — every stop walked, fog empty, command hands off:
|
||||
The command follows the map's status: `/plan2code-0-pathfinder specs/<idea>/pathfinder --web` while `Charting` / `Working`; `/plan2code-1-plan --web` once `Cleared`; and `/plan2code-init` first when `## Ground rules` records `AGENTS.md` absent and it still is. The path is the exact argument Auto-Discovery resolves an idea from, so the human pastes it back with zero edits.
|
||||
|
||||
```
|
||||
🧭 audit-log-export · Cleared · 8/8 cleared
|
||||
START ●━●━●━●━●━●━●━●━⚑ arrived
|
||||
Confidence: solid.
|
||||
## Form B — the turn asks the human something
|
||||
|
||||
NEXT STEP · start a new conversation and run:
|
||||
`/plan2code-1-plan --web`
|
||||
```
|
||||
Pass every outstanding item as `--item`, at its stable number (`--item "Q1 Duration model"`), so a partial reply is cheap and a dropped probe is visible to both of you. The script refuses more than three: the three-probe cap.
|
||||
|
||||
At `Cleared` the named legend is optional — the destination is reached and the PLAN-DRAFT is the thing to point at. Keep the confidence line; the Clearing Gate leaned on it.
|
||||
**Emit no resume command on a Form B turn.** There is nothing to resume — the session is alive and holding a claim. A resume command here reads as *we're done*, and the human either walks away mid-decision or burns the next turn asking what you meant. This is the single most common way the footer misfires, and it costs the batch the round trips batching was introduced to save.
|
||||
|
||||
One exception: `grilling.md`'s unreachable-human procedure. Parking a mid-grill question and stopping IS a session end — use Form A, and say in the body that the question is parked mid-grill with its batch outstanding.
|
||||
|
||||
## Form C — the menu after a recorded decision
|
||||
|
||||
Used ONLY on the Work cadence's fork-menu turn (resolve.md §Cadence), immediately after `resolve` recorded an `## Answer`. The script refuses it while a question is claimed or once the map is `Cleared`. Pass `--resolved-this-session <N>`, and `--heavy` when the decision just recorded was heavy, contested, or `Locked: yes`.
|
||||
|
||||
It prints the stop branch, labeled `OR START FRESH · new conversation, paste:`, and returns `menu`: the header, the question text, up to three takeable questions plus `Start fresh`, and which option to mark `RECOMMENDED` (a question early in the session; `Start fresh` after ~3 resolved or a heavy decision, with the reason in the question text, "to keep me sharp").
|
||||
|
||||
Then invoke the structured question tool with that menu. Put each question's gist or newly-unblocked note (from `resolve`'s `unblocked`) in its description. The automatic `Other` path lets the human name a frontier question not shown (`menu.more`).
|
||||
|
||||
Rules for Form C:
|
||||
|
||||
- **The command label is mandatory and exact.** It makes the command the stop branch, not a farewell. Never render a bare command on a menu turn.
|
||||
- **The choice itself always uses the structured tool.** Never print `NEXT UP` as a prose menu when the tool exists.
|
||||
- **Form C never replaces Form B.** A turn that asks probes, shows a sketch, or hands over a checklist is Form B, no command. Form C fires only between decisions, when nothing is claimed.
|
||||
- If the human walks away mid-menu, nothing is stranded: no claim is open, and the command to come back is already on screen.
|
||||
|
||||
---
|
||||
|
||||
## Discipline
|
||||
|
||||
- **Never print a bare resume command on a turn that asks a question.** The footer must not tell the human to leave a conversation you are still waiting in. Before you write Part 2, ask whether the response above it ends with something for them to answer: mid-question (probes, sketch, checklist) → Form B, no command, no exceptions but the parked-grill one; between decisions at the fork-menu → Form C, where the command appears ONLY under its `OR START FRESH` label as the explicit stop branch.
|
||||
- **Alignment is not the point.** Glyphs sit in `NN` order and the legend names them in the same order; do not burn effort column-aligning numbers under waypoints across variable-width glyphs. Legibility over pixels.
|
||||
- **Rebuild, never cache.** The markers come from the current `map.md`, which Work Step 2 has already reconciled against the question files this session. A footer that disagrees with the checklist above it means you drew from memory.
|
||||
- **Never print a bare resume command on a turn that asks a question.** Before you choose the form, ask whether the response above it ends with something for them to answer: mid-question (probes, sketch, checklist) → Form B, no exceptions but the parked-grill one; between decisions at the fork-menu → Form C.
|
||||
- **Draw it, never type it.** A hand-built trail drifts from the files; the script reads them every time. If the trail disagrees with the checklist above it, run `reconcile`, but only at session start or while nothing is claimed: `reconcile` resets a claim with no answer to `open`, so mid-question it would drop your own live claim. With a claim open, finish that question instead; `resolve` rebuilds the checklist, and the next trail is drawn from it. On `github` (the script cannot read the tracker), build it by hand from the sub-issue query, following "What the script draws" exactly.
|
||||
- **One trail.** Never render two ideas' trails, and never invent a stop the map does not list.
|
||||
@@ -556,8 +556,15 @@ enforces it, so never tell someone to keep asking past it.
|
||||
The person can add folders beside the one the session started in (a shared
|
||||
library, a design folder), from the footer's folder label. Together they are
|
||||
the session's **workspace**: context for every skill run in this console
|
||||
session, each folder addressed by a short `@name`. It outlives dashboard hops;
|
||||
a new console session starts with the original folder alone.
|
||||
session, each folder addressed by a short `@name`. It outlives dashboard hops,
|
||||
and it is remembered: every change is saved to `workspaces.json` beside
|
||||
`looks.json` (never into the project), keyed by the folder the session runs
|
||||
in and then by spec. A session with a spec opens on that spec's list, one with
|
||||
none on the project's; a spec with nothing saved starts as a copy of the
|
||||
project's list. The dashboard's picker swaps the list as the selection moves,
|
||||
and a `specDir` you post mid-run takes the current list with it. There is
|
||||
nothing for you to load: `open` prints the list, and a switch of spec on a
|
||||
resume reaches you as ordinary workspace changes on your next `wait`.
|
||||
|
||||
### What you are told
|
||||
|
||||
@@ -767,7 +774,7 @@ that is what the person is there to download. The finish carries no
|
||||
sees the Trail Footer, and without this their last screen promises a question
|
||||
that is never coming.
|
||||
- Post `run` `pathfinder-chart` (id `map`) when a new map is first written,
|
||||
and `pathfinder-research` (id = the question's file slug) as each research
|
||||
and `pathfinder-research` (id = the question's file slug; on `github`, `q<issue-number>`) as each research
|
||||
subagent reports back, or when you resolve a `research` question yourself
|
||||
(Posting an update → Session meter). Other questions score through their
|
||||
answers, so there is nothing to post for them.
|
||||
@@ -820,7 +827,7 @@ know:
|
||||
| 3, Implementation Summary | Written to `overview.md` as usual; mirror it as a doc (marked `saved`) so the page reader sees it land. |
|
||||
| 4, Documentation Review | The proposed-updates table as a doc, and a `multi` naming the documents to update — every option ticked is "approve", unticked ones are skipped. A `review` works instead when the set is all-or-nothing. |
|
||||
| 5, User Feedback | Optional items, `required: false`: the rating as a `choice` of 1 to 10 or a `text`, the three reasons as `text`. The submit-to-maintainer consent is a `confirm`. |
|
||||
| 6, Spec Cleanup | A `confirm` before moving anything, the archive paths in `consequences`. |
|
||||
| 6, Spec Cleanup | A `confirm` before moving anything, the archive paths in `consequences`, and a line that the spec's remembered workspace folders are forgotten too (`console.mjs forget --spec specs/<feature>` after the move). |
|
||||
|
||||
Pass `--spec specs/<feature>` to `open`, or post `specDir` once you know it.
|
||||
Stopping mid-finalize loses nothing
|
||||
|
||||
@@ -41,6 +41,7 @@ import {
|
||||
die,
|
||||
ensureDir,
|
||||
fileStamp,
|
||||
forgetWorkspace,
|
||||
handOff,
|
||||
handleFile,
|
||||
healthOk,
|
||||
@@ -65,6 +66,7 @@ import {
|
||||
readLedger,
|
||||
readWorkspace,
|
||||
reapHandles,
|
||||
rememberedWorkspace,
|
||||
remoteWarning,
|
||||
removeScratch,
|
||||
removeSessions,
|
||||
@@ -73,6 +75,7 @@ import {
|
||||
SESSION_MAX_AGE_MS,
|
||||
sessionDir,
|
||||
sleepSync,
|
||||
specKey,
|
||||
staleScratch,
|
||||
staleSessions,
|
||||
sweepUploads,
|
||||
@@ -317,7 +320,7 @@ async function cmdOpen() {
|
||||
if (launched) appendLedger(dir, { kind: "launch", id: nextLaunchId(readLedger(dir)), workflow: state.workflow });
|
||||
for (const line of ledgerFromPost(dir, openRun, openIssue, state.workflow)) appendLedger(dir, line);
|
||||
} catch {}
|
||||
const workspace = workspaceOnOpen(dir, worktree);
|
||||
const workspace = workspaceOnOpen(dir, worktree, state.specDir);
|
||||
|
||||
// Month-old sessions and scratch files: listed before the print so the
|
||||
// agent can see what went, removed after it so the page waits for nothing.
|
||||
@@ -403,10 +406,11 @@ async function cmdOpen() {
|
||||
* The workspace as `open` hands it to the agent, and the cursor seeded to
|
||||
* match: the agent now has the whole list, so no change up to here is owed.
|
||||
* Read-only on workspace.json, which only the server writes; on a fresh
|
||||
* session the server has not made it yet, so the original folder stands in.
|
||||
* session the server has not made it yet, so what was remembered for this
|
||||
* folder and spec stands in, the same list the server is about to make.
|
||||
*/
|
||||
function workspaceOnOpen(dir, worktree) {
|
||||
const ws = readWorkspace(dir) || initialWorkspace(worktree);
|
||||
function workspaceOnOpen(dir, worktree, specDir) {
|
||||
const ws = readWorkspace(dir) || initialWorkspace(worktree, rememberedWorkspace(worktree, specDir).entry);
|
||||
const missing = ws.folders.filter((f) => !isFolder(f.path)).map((f) => f.id);
|
||||
try {
|
||||
writeWorkspaceCursor(dir, ws.version || 0);
|
||||
@@ -946,6 +950,18 @@ function realNearest(p) {
|
||||
return path.join(fs.realpathSync(existing), path.relative(existing, p));
|
||||
}
|
||||
|
||||
/* --------------------------------------------------------------- forget */
|
||||
|
||||
// Drop the folder list remembered for one spec (Finalize, once the spec is
|
||||
// archived). The project's own list and every other spec's are untouched.
|
||||
function cmdForget() {
|
||||
if (typeof args.spec !== "string" || !args.spec.trim()) die("forget needs --spec specs/<idea>", 2);
|
||||
let spec = specKey(args.spec);
|
||||
if (/\.md$/i.test(spec)) spec = spec.slice(0, spec.lastIndexOf("/"));
|
||||
const worktree = repoRoots().worktree;
|
||||
print({ ok: true, spec, forgot: forgetWorkspace(worktree, spec) });
|
||||
}
|
||||
|
||||
/* ----------------------------------------------------------------- help */
|
||||
|
||||
function cmdHelp() {
|
||||
@@ -961,7 +977,8 @@ port, and the filesystem as transport; this CLI is the whole agent surface.
|
||||
first post. --file is optional, and --title defaults to the
|
||||
project's folder name. Also prints workspace: { folders: [{ name,
|
||||
path, description?, original? }], missing? }, the folders this
|
||||
console session reads as context, addressed as @name.
|
||||
console session reads as context, addressed as @name. The list is
|
||||
remembered per folder and spec in workspaces.json beside looks.json.
|
||||
post --session <sid> --file <patch.json>
|
||||
Merge a patch into the session. Prints terminalLine while the
|
||||
server is live. Exit 3 = rejected; stderr says why. A patch may
|
||||
@@ -988,6 +1005,10 @@ port, and the filesystem as transport; this CLI is the whole agent surface.
|
||||
Copy a cited note attachment into specs/<idea>/attachments/. Prints
|
||||
{ ok, path, link, image, reused }; exit 2 = bad usage, 3 = refused or
|
||||
missing. Paste link as it is.
|
||||
forget --spec specs/<idea>
|
||||
Drop the workspace folders remembered for that spec, in this
|
||||
folder (Finalize, after archiving it). Prints { ok, spec, forgot };
|
||||
forgot is false when nothing was saved. Exit 2 = bad usage.
|
||||
status [--session <sid>] [--all]
|
||||
One session, or every session belonging to this project.
|
||||
stop --session <sid> | --all
|
||||
@@ -1206,6 +1227,7 @@ const COMMANDS = {
|
||||
wait: cmdWait,
|
||||
chat: cmdChat,
|
||||
keep: cmdKeep,
|
||||
forget: cmdForget,
|
||||
status: cmdStatus,
|
||||
stop: cmdStop,
|
||||
help: cmdHelp,
|
||||
|
||||
@@ -178,8 +178,8 @@ function lockStale(lock) {
|
||||
// Run fn while holding the session's state lock, and release it however fn
|
||||
// ends. fn must not call process.exit(): the release would never run, and the
|
||||
// next writer would wait out the stale age.
|
||||
export function withStateLock(dir, fn) {
|
||||
const lock = path.join(dir, STATE_LOCK_FILE);
|
||||
export function withStateLock(dir, fn, lockName = STATE_LOCK_FILE) {
|
||||
const lock = path.join(dir, lockName);
|
||||
const deadline = Date.now() + LOCK_WAIT_MS;
|
||||
let fd = null;
|
||||
for (let attempt = 0; fd === null; attempt++) {
|
||||
@@ -188,7 +188,7 @@ export function withStateLock(dir, fn) {
|
||||
} catch (err) {
|
||||
// EPERM / EACCES: on Windows, a lock being deleted still blocks a create.
|
||||
if (!["EEXIST", "EPERM", "EACCES", "EBUSY"].includes(err.code)) throw err;
|
||||
if (Date.now() > deadline) throw new Error("state.json is busy with another writer; try again");
|
||||
if (Date.now() > deadline) throw new Error(`${lockName.replace(/.lock$/, "")} is busy with another writer; try again`);
|
||||
if (err.code === "EEXIST" && lockStale(lock)) {
|
||||
try {
|
||||
fs.rmSync(lock, { force: true });
|
||||
@@ -487,8 +487,9 @@ export async function removeSessions(sessionsDir, sids) {
|
||||
}
|
||||
|
||||
// The console folder's own files that no sweep may ever remove: the person's
|
||||
// looks and the pointer to this console's directory.
|
||||
export const PROTECTED_CONSOLE_FILES = new Set(["looks.json", "console-dir"]);
|
||||
// looks, the folders remembered per project and spec, and the pointer to
|
||||
// this console's directory.
|
||||
export const PROTECTED_CONSOLE_FILES = new Set(["looks.json", "workspaces.json", "console-dir"]);
|
||||
|
||||
function isScratchName(name) {
|
||||
return (
|
||||
@@ -1619,17 +1620,125 @@ export function readWorkspace(dir) {
|
||||
return readJson(path.join(dir, WORKSPACE_FILE), null);
|
||||
}
|
||||
|
||||
// A fresh workspace: just the original folder, named after itself.
|
||||
export function initialWorkspace(worktree) {
|
||||
// A fresh workspace: the original folder, named after itself, plus whatever
|
||||
// was remembered for this folder and spec (rememberedWorkspace() below).
|
||||
export function initialWorkspace(worktree, remembered = null) {
|
||||
const original = { id: "f0", path: worktree, name: defaultName(worktree), description: "", original: true };
|
||||
if (remembered && remembered.original) {
|
||||
if (remembered.original.name) original.name = remembered.original.name;
|
||||
if (remembered.original.description) original.description = remembered.original.description;
|
||||
}
|
||||
const added = ((remembered && remembered.folders) || []).map((f, i) => ({
|
||||
id: "f" + (i + 1),
|
||||
path: f.path,
|
||||
name: f.name,
|
||||
description: f.description || "",
|
||||
...(f.nested ? { nested: true } : {}),
|
||||
}));
|
||||
return { version: 0, folders: [original, ...added], missing: [], changes: [], remote: "" };
|
||||
}
|
||||
|
||||
/* ------------------------------------------------ remembered workspaces */
|
||||
|
||||
// The folder list outlives the console session: one file for the person,
|
||||
// beside looks.json, keyed by the folder a session runs in and then by spec.
|
||||
// Never under specs/: the paths are this machine's, and the server never
|
||||
// writes into a project.
|
||||
//
|
||||
// { "projects": { "<folded worktree>": {
|
||||
// "path": "<worktree>",
|
||||
// "project": { original, folders, at }, // no spec picked
|
||||
// "specs": { "specs/<name>": { original, folders, at } } } } }
|
||||
//
|
||||
// `original` holds the first folder's name and description only (its path is
|
||||
// always the session's own); `folders` the added ones as { path, name,
|
||||
// description, nested? }. Two writers, the server on every change and
|
||||
// `console.mjs forget`, each a read-modify-write of one key.
|
||||
export const WORKSPACES_FILE = path.join(HOME_DIR, "workspaces.json");
|
||||
|
||||
const foldKey = (p) => {
|
||||
const resolved = path.resolve(String(p || ""));
|
||||
return process.platform === "win32" || process.platform === "darwin" ? resolved.toLowerCase() : resolved;
|
||||
};
|
||||
|
||||
// `specs/<name>` with forward slashes and no trailing slash, or "" for none.
|
||||
export function specKey(specDir) {
|
||||
return String(specDir || "")
|
||||
.trim()
|
||||
.replace(/\\/g, "/")
|
||||
.replace(/^\.\//, "")
|
||||
.replace(/\/+$/, "");
|
||||
}
|
||||
|
||||
function readStore() {
|
||||
const saved = readJson(WORKSPACES_FILE, null);
|
||||
return saved && typeof saved.projects === "object" && saved.projects ? saved : { projects: {} };
|
||||
}
|
||||
|
||||
/**
|
||||
* What was remembered for this folder and spec: `{ entry, from }`, where
|
||||
* `from` is "spec" when the spec has its own list, "project" when it falls
|
||||
* back to the project's (a spec's list starts as a copy of it), and null
|
||||
* when nothing was ever saved.
|
||||
*/
|
||||
export function rememberedWorkspace(worktree, specDir) {
|
||||
const project = readStore().projects[foldKey(worktree)];
|
||||
if (!project) return { entry: null, from: null };
|
||||
const spec = specKey(specDir);
|
||||
if (spec && project.specs && project.specs[spec]) return { entry: project.specs[spec], from: "spec" };
|
||||
return project.project ? { entry: project.project, from: "project" } : { entry: null, from: null };
|
||||
}
|
||||
|
||||
// The workspace's folders as the store keeps them.
|
||||
export function rememberable(ws) {
|
||||
const folders = (ws && ws.folders) || [];
|
||||
const first = folders.find((f) => f.original) || {};
|
||||
return {
|
||||
version: 0,
|
||||
folders: [{ id: "f0", path: worktree, name: defaultName(worktree), description: "", original: true }],
|
||||
missing: [],
|
||||
changes: [],
|
||||
remote: "",
|
||||
original: { name: first.name || "", description: first.description || "" },
|
||||
folders: folders
|
||||
.filter((f) => !f.original)
|
||||
.map((f) => ({ path: f.path, name: f.name, description: f.description || "", ...(f.nested ? { nested: true } : {}) })),
|
||||
at: nowIso(),
|
||||
};
|
||||
}
|
||||
|
||||
// Every server and `console.mjs forget` writes the one file, so each
|
||||
// read-modify-write holds this lock beside it.
|
||||
const WORKSPACES_LOCK = "workspaces.json.lock";
|
||||
|
||||
// Save the list for this folder and spec ("" for the project's own).
|
||||
export function rememberWorkspace(worktree, specDir, ws) {
|
||||
ensureDir(path.dirname(WORKSPACES_FILE));
|
||||
withStateLock(path.dirname(WORKSPACES_FILE), () => saveRemembered(worktree, specDir, ws), WORKSPACES_LOCK);
|
||||
}
|
||||
|
||||
function saveRemembered(worktree, specDir, ws) {
|
||||
const store = readStore();
|
||||
const key = foldKey(worktree);
|
||||
const project = store.projects[key] || { path: path.resolve(worktree) };
|
||||
const spec = specKey(specDir);
|
||||
if (spec) project.specs = { ...(project.specs || {}), [spec]: rememberable(ws) };
|
||||
else project.project = rememberable(ws);
|
||||
store.projects[key] = project;
|
||||
writeJsonAtomic(WORKSPACES_FILE, store);
|
||||
}
|
||||
|
||||
// Drop one spec's list (Finalize, once the spec is archived). True when there was one.
|
||||
export function forgetWorkspace(worktree, specDir) {
|
||||
const spec = specKey(specDir);
|
||||
if (!spec || !fs.existsSync(WORKSPACES_FILE)) return false;
|
||||
return withStateLock(path.dirname(WORKSPACES_FILE), () => dropRemembered(worktree, spec), WORKSPACES_LOCK);
|
||||
}
|
||||
|
||||
function dropRemembered(worktree, spec) {
|
||||
const store = readStore();
|
||||
const project = store.projects[foldKey(worktree)];
|
||||
if (!spec || !project || !project.specs || !project.specs[spec]) return false;
|
||||
delete project.specs[spec];
|
||||
writeJsonAtomic(WORKSPACES_FILE, store);
|
||||
return true;
|
||||
}
|
||||
|
||||
// Single-writer rule: only server.mjs may call this.
|
||||
export function writeWorkspace(dir, ws) {
|
||||
return writeJsonAtomic(path.join(dir, WORKSPACE_FILE), ws);
|
||||
|
||||
@@ -2505,6 +2505,9 @@ a.icon-btn { box-sizing: border-box; text-decoration: none; }
|
||||
actions stay put. */
|
||||
.modal.workspace { max-width: 680px; }
|
||||
.modal.workspace[open] { display: flex; flex-direction: column; max-height: calc(100vh - 48px); }
|
||||
.workspace .modal-blurb { margin-bottom: 6px; }
|
||||
.workspace-scope { margin: 0 0 16px; color: var(--ink-3, var(--ink-2)); font-size: 12.5px; }
|
||||
|
||||
.workspace-list {
|
||||
list-style: none; margin: 0; padding: 0;
|
||||
display: grid; gap: 12px;
|
||||
|
||||
@@ -2542,6 +2542,7 @@ function renderDashboard(main) {
|
||||
const specs = specList();
|
||||
if (specs.length) wrap.appendChild(renderSpecPicker(specs));
|
||||
wrap.appendChild(hideUnavailableToggle());
|
||||
if (!local.launching && !launchScoping) 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
|
||||
@@ -2963,6 +2964,11 @@ async function launchSkill(entry) {
|
||||
// cards that take no spec (utilities, setup) launch untargeted even while
|
||||
// a spec is selected.
|
||||
if (target) action.spec = target.dir;
|
||||
// The skill opens on the folders remembered for what it was launched for.
|
||||
// Held until the launch is in flight: the swap's own frame re-renders the
|
||||
// dashboard, which would otherwise sync back to the picker's spec.
|
||||
launchScoping = true;
|
||||
await syncWorkspaceScope(target ? target.dir : "");
|
||||
try {
|
||||
const res = await fetch("/submit", {
|
||||
method: "POST",
|
||||
@@ -2973,6 +2979,7 @@ async function launchSkill(entry) {
|
||||
}),
|
||||
});
|
||||
if (res.status === 409) {
|
||||
launchScoping = false;
|
||||
pendingResult = true;
|
||||
banner("Your last pick is still being picked up. One moment.", "info");
|
||||
return;
|
||||
@@ -2980,10 +2987,12 @@ async function launchSkill(entry) {
|
||||
if (!res.ok) throw new Error(String(res.status));
|
||||
sound("startSkill");
|
||||
local.launching = { skill: entry.skill, title: entry.title, at: Date.now() };
|
||||
launchScoping = false;
|
||||
pendingResult = true;
|
||||
save();
|
||||
render();
|
||||
} catch {
|
||||
launchScoping = false;
|
||||
banner("That did not go through. Nothing was lost; try again.", "warn");
|
||||
}
|
||||
}
|
||||
@@ -5854,6 +5863,32 @@ async function postJson(url, body) {
|
||||
}
|
||||
}
|
||||
|
||||
/* The workspace follows the dashboard's picker: the folders remembered for
|
||||
the selected spec, or the project's own under "Start from scratch". The
|
||||
server swaps the list and remembers every change after it. */
|
||||
let scopeAsked = null;
|
||||
// True from a launch's scope sync until its send has gone (or failed).
|
||||
let launchScoping = false;
|
||||
async function syncWorkspaceScope(spec) {
|
||||
if (!S || S.workflow !== "dashboard" || gone || !wsFrame) return;
|
||||
const want = spec === undefined ? (selSpec() && selSpec().dir) || "" : spec;
|
||||
if ((wsFrame.scope || "") === want || scopeAsked === want) return;
|
||||
scopeAsked = want;
|
||||
const { status, body } = await postJson("/workspace/scope", { spec: want });
|
||||
if (status === 200 && body && Array.isArray(body.folders)) wsFrame = { ...wsFrame, ...body };
|
||||
scopeAsked = null;
|
||||
if ($("workspace-modal").open) renderWorkspace();
|
||||
}
|
||||
|
||||
// The dialog's "Remembered for" line: whose list this is.
|
||||
function workspaceScopeText() {
|
||||
const scope = (wsFrame && wsFrame.scope) || "";
|
||||
if (!scope) return "Remembered for this project, so your next console session here starts with these folders.";
|
||||
const spec = specList().find((s) => s.dir === scope);
|
||||
const name = spec ? spec.name : scope.split("/").pop();
|
||||
return `Remembered for the ${name} spec, and loaded again whenever it is picked.`;
|
||||
}
|
||||
|
||||
const NAME_RULE = "Names use lowercase letters, numbers and hyphens.";
|
||||
const BROWSE_UNAVAILABLE = "Browse isn't available here — type or paste the path.";
|
||||
// The folder whose Remove is waiting on its inline confirm, by id.
|
||||
@@ -5893,6 +5928,7 @@ function renderWorkspace() {
|
||||
}
|
||||
folders.forEach((f, i) => paintWorkspaceRow(list.children[i], f));
|
||||
$("workspace-browse").hidden = Boolean(wsFrame && wsFrame.remote);
|
||||
$("workspace-scope").textContent = workspaceScopeText();
|
||||
}
|
||||
|
||||
function workspaceRow(f) {
|
||||
|
||||
@@ -833,10 +833,28 @@
|
||||
Click the folder name in the middle of the bottom bar. It shows your
|
||||
folder's name and branch, such as <strong>shop · main</strong>, and
|
||||
<strong>shop + 2 folders · main</strong> once you have added some.
|
||||
The workspace lasts for this console session only: it carries across
|
||||
steps you start from the dashboard, and a new console session starts
|
||||
with just the folder you started in.
|
||||
It carries across steps you start from the dashboard.
|
||||
</p>
|
||||
<h4>Remembered for next time</h4>
|
||||
<ul>
|
||||
<li>
|
||||
Every change is saved as you make it, so the next console session in
|
||||
this folder starts with the same folders.
|
||||
</li>
|
||||
<li>
|
||||
Each spec keeps its own list. The first time you pick a spec on the
|
||||
dashboard it starts as a copy of the project's list (the one shown
|
||||
under <strong>Start from scratch</strong>), and after that the two
|
||||
are separate. Picking a spec loads its list; the line under the
|
||||
dialog's title says whose list you are looking at.
|
||||
</li>
|
||||
<li>
|
||||
The lists live in <code>workspaces.json</code> in your own
|
||||
Plan2Code settings folder, beside your look and feel, never in the
|
||||
project. Finalize offers to forget a spec's list when it archives the
|
||||
spec.
|
||||
</li>
|
||||
</ul>
|
||||
<h4>Adding a folder</h4>
|
||||
<ul>
|
||||
<li>
|
||||
@@ -1363,9 +1381,10 @@
|
||||
<h4>What it counts</h4>
|
||||
<p>
|
||||
Each step you run here adds points: a plan or a set of documents
|
||||
weighs more than a single answered question, and a built phase more
|
||||
still, by how many tasks it completed: a big phase adds more than a
|
||||
small one. Every two questions you answer add a point too, so a long
|
||||
weighs more than a quick task, and a built phase more still, by how
|
||||
many tasks it completed: a big phase adds more than a small one.
|
||||
Every two questions you answer within one step add a point too
|
||||
(rounded down, so a single answer adds nothing), so a long
|
||||
back-and-forth counts for more than a short one. Click the ring to see the count and a list of each step that added
|
||||
points, with what it added. It is a rule of thumb, not a
|
||||
reading of Plan2Code's real memory: long sessions tend to make it
|
||||
@@ -2003,6 +2022,7 @@
|
||||
The folders the agent uses as context this session. It reads the extra ones for
|
||||
reference and only changes them if you ask.
|
||||
</p>
|
||||
<p class="workspace-scope" id="workspace-scope"></p>
|
||||
<ul class="workspace-list" id="workspace-list"></ul>
|
||||
<div class="workspace-add">
|
||||
<label class="workspace-add-label" for="workspace-path">Add a folder</label>
|
||||
|
||||
@@ -45,7 +45,10 @@ import {
|
||||
readLedger,
|
||||
readOverview,
|
||||
readWorkspace,
|
||||
rememberWorkspace,
|
||||
rememberedWorkspace,
|
||||
remoteWarning,
|
||||
specKey,
|
||||
typedCount,
|
||||
withStateLock,
|
||||
writeJsonAtomic,
|
||||
@@ -326,7 +329,9 @@ function workspaceNow() {
|
||||
return ws;
|
||||
}
|
||||
const root = sessionWorktree();
|
||||
const fresh = { ...initialWorkspace(root || PROJECT), remote: remoteWarning().remote || "" };
|
||||
const scope = specKey(stateNow?.specDir);
|
||||
const remembered = root ? rememberedWorkspace(root, scope).entry : null;
|
||||
const fresh = { ...initialWorkspace(root || PROJECT, remembered), scope, remote: remoteWarning().remote || "" };
|
||||
// There but unreadable for now (a scanner's lock): never written over, and
|
||||
// never cached, so the next call reads it again.
|
||||
if (stamp) return workspaceSeen.ws || fresh;
|
||||
@@ -347,13 +352,87 @@ function saveWorkspace(ws) {
|
||||
|
||||
// One change: a new version, an entry in the change log the agent is handed,
|
||||
// the file, and every open page.
|
||||
function bumpWorkspace(ws, change) {
|
||||
function bumpWorkspace(ws, change, { remember = true } = {}) {
|
||||
ws.version = (ws.version || 0) + 1;
|
||||
ws.changes = [...(ws.changes || []), { ...change, version: ws.version }];
|
||||
saveWorkspace(ws);
|
||||
// Remembered for the next console session too. A folder gone missing or
|
||||
// found again is not a change of mind, so it is not saved.
|
||||
if (remember) rememberNow(ws);
|
||||
pushState();
|
||||
}
|
||||
|
||||
function rememberNow(ws) {
|
||||
const root = sessionWorktree();
|
||||
if (!root) return;
|
||||
try {
|
||||
rememberWorkspace(root, ws.scope || "", ws);
|
||||
} catch {}
|
||||
}
|
||||
|
||||
/**
|
||||
* Point the workspace at another spec ("" for the project's own list) and
|
||||
* swap in what was remembered there, logging each difference as a change so
|
||||
* the agent's cursor stays truthful. A spec with nothing saved starts from
|
||||
* the project's list (`seed: "project"`, the dashboard picker) or keeps the
|
||||
* list it has and saves it as the spec's (`seed: "current"`, a spec created
|
||||
* mid-run). Folders keep their ids when their path stays.
|
||||
*/
|
||||
function setScope(ws, spec, seed = "project") {
|
||||
const root = sessionWorktree();
|
||||
const next = specKey(spec);
|
||||
if (!root || (ws.scope || "") === next) return false;
|
||||
const found = rememberedWorkspace(root, next);
|
||||
ws.scope = next;
|
||||
if (next && found.from !== "spec" && seed === "current") {
|
||||
saveWorkspace(ws);
|
||||
rememberNow(ws);
|
||||
pushState();
|
||||
return true;
|
||||
}
|
||||
const want = initialWorkspace(root, found.entry).folders;
|
||||
const byPath = new Map(ws.folders.map((f) => [foldPath(path.resolve(f.path)), f]));
|
||||
const kept = new Set();
|
||||
const folders = [];
|
||||
const changes = [];
|
||||
for (const w of want) {
|
||||
const have = w.original ? ws.folders.find((f) => f.original) : byPath.get(foldPath(path.resolve(w.path)));
|
||||
if (!have) {
|
||||
folders.push({ ...w, id: "pending" });
|
||||
changes.push({ kind: "added", name: w.name, path: w.path, description: w.description });
|
||||
continue;
|
||||
}
|
||||
kept.add(have);
|
||||
if (have.name !== w.name) changes.push({ kind: "renamed", from: have.name, name: w.name, path: have.path });
|
||||
if ((have.description || "") !== (w.description || "")) {
|
||||
changes.push({ kind: "described", name: w.name, path: have.path, description: w.description || "" });
|
||||
}
|
||||
folders.push({ ...have, name: w.name, description: w.description || "" });
|
||||
}
|
||||
for (const f of ws.folders) {
|
||||
if (!kept.has(f)) changes.unshift({ kind: "removed", name: f.name, path: f.path });
|
||||
}
|
||||
ws.folders = folders.filter((f) => f.id !== "pending");
|
||||
for (const f of folders.filter((f) => f.id === "pending")) ws.folders.push({ ...f, id: nextFolderId(ws) });
|
||||
ws.missing = (ws.missing || []).filter((id) => ws.folders.some((f) => f.id === id));
|
||||
if (!changes.length) {
|
||||
saveWorkspace(ws);
|
||||
pushState();
|
||||
}
|
||||
for (const c of changes) bumpWorkspace(ws, c, { remember: false });
|
||||
checkFolders(ws);
|
||||
return true;
|
||||
}
|
||||
|
||||
// A spec posted mid-run (Pathfinder or Plan making its folder, a skill that
|
||||
// learns its spec late) takes the workspace with it.
|
||||
function followSpecDir(state) {
|
||||
const spec = specKey(state && state.specDir);
|
||||
if (!spec || !fileStamp(WORKSPACE_PATH)) return;
|
||||
const ws = workspaceNow();
|
||||
if ((ws.scope || "") !== spec) setScope(ws, spec, "current");
|
||||
}
|
||||
|
||||
function isFolder(p) {
|
||||
try {
|
||||
return fs.statSync(p).isDirectory();
|
||||
@@ -370,10 +449,10 @@ function checkFolders(ws) {
|
||||
const marked = ws.missing.includes(f.id);
|
||||
if (!there && !marked) {
|
||||
ws.missing = [...ws.missing, f.id];
|
||||
bumpWorkspace(ws, { kind: "missing", name: f.name, path: f.path });
|
||||
bumpWorkspace(ws, { kind: "missing", name: f.name, path: f.path }, { remember: false });
|
||||
} else if (there && marked) {
|
||||
ws.missing = ws.missing.filter((id) => id !== f.id);
|
||||
bumpWorkspace(ws, { kind: "found", name: f.name, path: f.path });
|
||||
bumpWorkspace(ws, { kind: "found", name: f.name, path: f.path }, { remember: false });
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -402,8 +481,8 @@ function folderIssues(entries) {
|
||||
}
|
||||
|
||||
function workspaceView() {
|
||||
const { folders, missing, remote } = workspaceNow();
|
||||
return { folders, missing: missing || [], remote: remote || "", issues: folderIssues(ledgerEntries()) };
|
||||
const { folders, missing, remote, scope } = workspaceNow();
|
||||
return { folders, missing: missing || [], remote: remote || "", scope: scope || "", issues: folderIssues(ledgerEntries()) };
|
||||
}
|
||||
|
||||
// Whether child sits strictly under parent.
|
||||
@@ -492,6 +571,7 @@ function bootWorkspace() {
|
||||
saveWorkspace(ws);
|
||||
}
|
||||
checkFolders(ws);
|
||||
followSpecDir(stateNow);
|
||||
}
|
||||
|
||||
/**
|
||||
@@ -1403,6 +1483,24 @@ const server = http.createServer((req, res) => {
|
||||
});
|
||||
}
|
||||
|
||||
// Which list the workspace is: a spec's, or the project's (`spec` empty).
|
||||
// The dashboard's picker sends it as the selection moves and before a
|
||||
// launch, so a skill opens on the list of the spec it was launched for.
|
||||
if (pathname === "/workspace/scope" && req.method === "POST") {
|
||||
if (!originOk(req, port)) return json(res, 403, { error: "bad origin" });
|
||||
return readBody(req, (err, body) => {
|
||||
if (err || !body || typeof body !== "object" || Array.isArray(body)) return json(res, 400, { error: "bad" });
|
||||
const spec = typeof body.spec === "string" ? body.spec : "";
|
||||
if (spec && !/^specs\/[^/\\]+$/.test(specKey(spec))) return json(res, 400, { reason: "bad-spec" });
|
||||
try {
|
||||
setScope(workspaceNow(), spec, "project");
|
||||
} catch (e) {
|
||||
return json(res, 500, { error: String(e.message) });
|
||||
}
|
||||
return json(res, 200, workspaceView());
|
||||
});
|
||||
}
|
||||
|
||||
// Only ever returns a path: the page then adds it through /workspace/add.
|
||||
if (pathname === "/workspace/browse" && req.method === "POST") {
|
||||
if (!originOk(req, port)) return json(res, 403, { error: "bad origin" });
|
||||
@@ -1561,6 +1659,9 @@ function checkState() {
|
||||
try {
|
||||
ensureConversation(parsed);
|
||||
} catch {}
|
||||
try {
|
||||
followSpecDir(parsed);
|
||||
} catch {}
|
||||
pushState();
|
||||
}
|
||||
lastStateStamp = stamp;
|
||||
|
||||
@@ -17,6 +17,6 @@
|
||||
"url": "https://github.com/jparkerweb/plan2code"
|
||||
},
|
||||
"homepage": "https://github.com/jparkerweb/plan2code",
|
||||
"releaseDate": "2026-10-02",
|
||||
"releaseDate": "2026-10-04",
|
||||
"mode": "utility"
|
||||
}
|
||||
@@ -0,0 +1,247 @@
|
||||
// Plan2Code skill scripts: shared plumbing.
|
||||
//
|
||||
// Every script in a skill's scripts/ directory imports this file. It owns the
|
||||
// conventions the SKILL.md prompts rely on, so they are identical everywhere:
|
||||
//
|
||||
// stdout one JSON object, always. `{ "ok": true, ... }` on success,
|
||||
// `{ "ok": false, "error": "<code>", "message": "...", "next": "..." }`
|
||||
// on a handled failure.
|
||||
// stderr a one-line human diagnostic on failure (the same message + next).
|
||||
// exit 0 ok · 1 unexpected crash · 2 bad arguments · 3 not found ·
|
||||
// 4 invalid input or a check that failed · 5 refused (would clobber
|
||||
// or break a rule).
|
||||
//
|
||||
// Node 18+ built-ins only, no build step: this ships inside every skill.
|
||||
|
||||
import fs from "node:fs";
|
||||
import path from "node:path";
|
||||
import { fileURLToPath, pathToFileURL } from "node:url";
|
||||
|
||||
export const HERE = path.dirname(fileURLToPath(import.meta.url));
|
||||
|
||||
export const EXIT = { OK: 0, CRASH: 1, USAGE: 2, NOT_FOUND: 3, INVALID: 4, REFUSED: 5 };
|
||||
|
||||
export class CliError extends Error {
|
||||
constructor(exit, error, message, next) {
|
||||
super(message);
|
||||
this.exit = exit;
|
||||
this.error = error;
|
||||
this.next = next;
|
||||
}
|
||||
}
|
||||
|
||||
/** Throw a handled failure: the run() wrapper prints it and sets the exit code. */
|
||||
export function fail(exit, error, message, next) {
|
||||
throw new CliError(exit, error, message, next);
|
||||
}
|
||||
|
||||
export function out(obj) {
|
||||
process.stdout.write(JSON.stringify(obj, null, 2) + "\n");
|
||||
}
|
||||
|
||||
/**
|
||||
* Parse argv into { _: positionals, <flag>: value }.
|
||||
* `booleans` names flags that take no value; every other `--flag` takes the
|
||||
* next argument, and repeats of a flag listed in `lists` collect into an array.
|
||||
* `--flag=value` works too. Unknown flags are a usage error, so a typo never
|
||||
* silently changes behavior.
|
||||
*/
|
||||
export function parseArgs(argv, { booleans = [], values = [], lists = [] } = {}) {
|
||||
const known = new Set([...booleans, ...values, ...lists, "help"]);
|
||||
const args = { _: [] };
|
||||
for (let i = 0; i < argv.length; i++) {
|
||||
const a = argv[i];
|
||||
if (!a.startsWith("--")) {
|
||||
args._.push(a);
|
||||
continue;
|
||||
}
|
||||
let name = a.slice(2);
|
||||
let value;
|
||||
const eq = name.indexOf("=");
|
||||
if (eq !== -1) {
|
||||
value = name.slice(eq + 1);
|
||||
name = name.slice(0, eq);
|
||||
}
|
||||
if (!known.has(name)) {
|
||||
fail(EXIT.USAGE, "unknown-flag", `Unknown flag --${name}.`, "Run with --help for the flags this script takes.");
|
||||
}
|
||||
if (name === "help" || booleans.includes(name)) {
|
||||
args[name] = true;
|
||||
continue;
|
||||
}
|
||||
if (value === undefined) {
|
||||
if (i + 1 >= argv.length) {
|
||||
fail(EXIT.USAGE, "missing-value", `--${name} needs a value.`, "Run with --help for usage.");
|
||||
}
|
||||
value = argv[++i];
|
||||
}
|
||||
if (lists.includes(name)) (args[name] ||= []).push(value);
|
||||
else args[name] = value;
|
||||
}
|
||||
return args;
|
||||
}
|
||||
|
||||
/**
|
||||
* Run a script's main(). Prints usage on --help, turns CliError into the JSON
|
||||
* failure shape plus an exit code, and anything else into exit 1 with the stack
|
||||
* on stderr. Sets process.exitCode rather than calling process.exit(), so
|
||||
* stdout is never cut off mid-write.
|
||||
*/
|
||||
export async function run(usage, main) {
|
||||
try {
|
||||
const argv = process.argv.slice(2);
|
||||
if (argv.includes("--help") || argv.includes("-h")) {
|
||||
process.stdout.write(usage.trim() + "\n");
|
||||
return;
|
||||
}
|
||||
await main(argv);
|
||||
} catch (err) {
|
||||
if (err instanceof CliError) {
|
||||
out({ ok: false, error: err.error, message: err.message, ...(err.next ? { next: err.next } : {}) });
|
||||
process.stderr.write(`error: ${err.message}${err.next ? `\nnext: ${err.next}` : ""}\n`);
|
||||
process.exitCode = err.exit;
|
||||
return;
|
||||
}
|
||||
process.stderr.write(`unexpected error: ${err && err.stack ? err.stack : err}\n`);
|
||||
out({ ok: false, error: "crash", message: String(err && err.message ? err.message : err) });
|
||||
process.exitCode = EXIT.CRASH;
|
||||
}
|
||||
}
|
||||
|
||||
/* ------------------------------------------------------------------ time */
|
||||
|
||||
// PLAN2CODE_NOW ("YYYY-MM-DD HH:mm" or any Date-parsable string) pins the
|
||||
// clock, for tests and for reproducing a run. Otherwise: the local clock, which
|
||||
// is what "today" means to the person reading the date in their files.
|
||||
export function now() {
|
||||
const pinned = process.env.PLAN2CODE_NOW;
|
||||
if (pinned) {
|
||||
const m = pinned.match(/^(\d{4})-(\d{2})-(\d{2})(?:[ T](\d{2}):(\d{2})(?::(\d{2}))?)?$/);
|
||||
if (m) return new Date(+m[1], +m[2] - 1, +m[3], +(m[4] || 0), +(m[5] || 0), +(m[6] || 0));
|
||||
const d = new Date(pinned);
|
||||
if (!Number.isNaN(d.getTime())) return d;
|
||||
}
|
||||
return new Date();
|
||||
}
|
||||
|
||||
const pad = (n) => String(n).padStart(2, "0");
|
||||
|
||||
/** YYYY-MM-DD */
|
||||
export function isoDate(d = now()) {
|
||||
return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}`;
|
||||
}
|
||||
|
||||
/** YYYYMMDD */
|
||||
export function compactDate(d = now()) {
|
||||
return isoDate(d).replace(/-/g, "");
|
||||
}
|
||||
|
||||
/** YYYY-MM-DD HH:mm */
|
||||
export function stamp(d = now()) {
|
||||
return `${isoDate(d)} ${pad(d.getHours())}:${pad(d.getMinutes())}`;
|
||||
}
|
||||
|
||||
/** HHMMSS */
|
||||
export function clock(d = now()) {
|
||||
return `${pad(d.getHours())}${pad(d.getMinutes())}${pad(d.getSeconds())}`;
|
||||
}
|
||||
|
||||
/* ----------------------------------------------------------------- files */
|
||||
|
||||
export function readText(file) {
|
||||
try {
|
||||
return fs.readFileSync(file, "utf8");
|
||||
} catch {
|
||||
return null;
|
||||
}
|
||||
}
|
||||
|
||||
export function isDir(p) {
|
||||
try {
|
||||
return fs.statSync(p).isDirectory();
|
||||
} catch {
|
||||
return false;
|
||||
}
|
||||
}
|
||||
|
||||
/** Write a file only when its content changes. Returns true when it wrote. */
|
||||
export function writeIfChanged(file, content) {
|
||||
const current = readText(file);
|
||||
if (current === content) return false;
|
||||
fs.mkdirSync(path.dirname(file), { recursive: true });
|
||||
fs.writeFileSync(file, content);
|
||||
return true;
|
||||
}
|
||||
|
||||
/** Normalise line endings for parsing; keep the original for writing back. */
|
||||
export function eol(text) {
|
||||
return text.includes("\r\n") ? "\r\n" : "\n";
|
||||
}
|
||||
|
||||
/**
|
||||
* phase-N.md per phase number. An exact phase-N.md always wins over a sibling
|
||||
* such as phase-1-old.md; more than one candidate is reported, never guessed.
|
||||
* Shared so every script that counts a spec's tasks reads the same files.
|
||||
*/
|
||||
export function phaseFiles(dir) {
|
||||
const files = new Map();
|
||||
const extra = new Map();
|
||||
for (const name of fs.readdirSync(dir).sort()) {
|
||||
const m = name.match(/^phase-(\d+)\b[^/]*\.md$/i);
|
||||
if (!m) continue;
|
||||
const n = Number(m[1]);
|
||||
const exact = new RegExp(`^phase-0*${n}\\.md$`, "i").test(name);
|
||||
if (!files.has(n)) files.set(n, name);
|
||||
else if (exact) {
|
||||
(extra.get(n) || extra.set(n, []).get(n)).push(files.get(n));
|
||||
files.set(n, name);
|
||||
} else (extra.get(n) || extra.set(n, []).get(n)).push(name);
|
||||
}
|
||||
files.extra = extra;
|
||||
return files;
|
||||
}
|
||||
|
||||
/** Forward-slash path relative to root, for output the agent pastes into prompts. */
|
||||
export function rel(root, p) {
|
||||
return path.relative(root, p).split(path.sep).join("/") || ".";
|
||||
}
|
||||
|
||||
/* --------------------------------------------------------- the web console */
|
||||
|
||||
// The web console ships beside these scripts in every installed skill
|
||||
// (references/web-console/), and in this repo it sits at src/web-console/. Its
|
||||
// lib.mjs is the one home of the spec-state classifier and the loop-marker /
|
||||
// metrics-bait scan, so the scripts import it rather than keep a second copy.
|
||||
const CONSOLE_LIB_CANDIDATES = [
|
||||
path.join(HERE, "..", "references", "web-console", "lib.mjs"), // installed skill
|
||||
path.join(HERE, "..", "web-console", "lib.mjs"), // src/skill-scripts in the repo
|
||||
];
|
||||
|
||||
let consoleLibPromise;
|
||||
export function consoleLib() {
|
||||
consoleLibPromise ||= (async () => {
|
||||
for (const candidate of CONSOLE_LIB_CANDIDATES) {
|
||||
if (fs.existsSync(candidate)) return import(pathToFileURL(candidate).href);
|
||||
}
|
||||
fail(
|
||||
EXIT.NOT_FOUND,
|
||||
"console-lib-missing",
|
||||
`The web console's lib.mjs is not beside this script (looked in ${CONSOLE_LIB_CANDIDATES.join(", ")}).`,
|
||||
"The skill install is incomplete; reinstall the Plan2Code skills (node install.js)."
|
||||
);
|
||||
})();
|
||||
return consoleLibPromise;
|
||||
}
|
||||
|
||||
/** The version these scripts shipped with (scripts/version.json, or the repo's). */
|
||||
export function version() {
|
||||
for (const file of [path.join(HERE, "version.json"), path.join(HERE, "..", "..", "version.json")]) {
|
||||
const text = readText(file);
|
||||
if (!text) continue;
|
||||
try {
|
||||
const v = JSON.parse(text).version;
|
||||
if (typeof v === "string") return v;
|
||||
} catch {}
|
||||
}
|
||||
return null;
|
||||
}
|
||||
File diff suppressed because it is too large.
Load diff
@@ -0,0 +1,22 @@
|
||||
{
|
||||
"name": "Plan2Code",
|
||||
"version": "2.4.1",
|
||||
"description": "A structured 4-step workflow methodology for AI-assisted software development",
|
||||
"keywords": [
|
||||
"ai",
|
||||
"workflow",
|
||||
"development",
|
||||
"planning",
|
||||
"implementation",
|
||||
"plan"
|
||||
],
|
||||
"author": "Justin Parker",
|
||||
"license": "MIT",
|
||||
"repository": {
|
||||
"type": "git",
|
||||
"url": "https://github.com/jparkerweb/plan2code"
|
||||
},
|
||||
"homepage": "https://github.com/jparkerweb/plan2code",
|
||||
"releaseDate": "2026-10-04",
|
||||
"mode": "utility"
|
||||
}
|
||||
@@ -54,7 +54,7 @@ Check if `./AGENTS.md` exists:
|
||||
|
||||
### Check for Existing Progress
|
||||
|
||||
Before Phase 1, check for existing `PLAN-DRAFT-*.md` under `specs/` (`ls specs/` via shell — never Glob; it is gitignored):
|
||||
Before Phase 1, run `node "<S>/specs.mjs" list` from the project root (`<S>`: `scripts/` beside this SKILL.md, `~/.agents/skills/plan2code-1-plan/scripts/` globally). It reads gitignored `specs/` (Glob silently finds nothing there) and gives each spec's `planDrafts` with its **Status:** line (`-prev` copies are `archived`; ignore them). Route on that status:
|
||||
- Status "Phase 3 Complete - Resume at Phase 4": Resume at Phase 4
|
||||
- Status "Escalated from Quick Task - Resume at Phase 2": Acknowledge, verify requirements, skip to Phase 2
|
||||
- Status "Draft" or "Complete": Ask user how to proceed
|
||||
|
||||
@@ -556,8 +556,15 @@ enforces it, so never tell someone to keep asking past it.
|
||||
The person can add folders beside the one the session started in (a shared
|
||||
library, a design folder), from the footer's folder label. Together they are
|
||||
the session's **workspace**: context for every skill run in this console
|
||||
session, each folder addressed by a short `@name`. It outlives dashboard hops;
|
||||
a new console session starts with the original folder alone.
|
||||
session, each folder addressed by a short `@name`. It outlives dashboard hops,
|
||||
and it is remembered: every change is saved to `workspaces.json` beside
|
||||
`looks.json` (never into the project), keyed by the folder the session runs
|
||||
in and then by spec. A session with a spec opens on that spec's list, one with
|
||||
none on the project's; a spec with nothing saved starts as a copy of the
|
||||
project's list. The dashboard's picker swaps the list as the selection moves,
|
||||
and a `specDir` you post mid-run takes the current list with it. There is
|
||||
nothing for you to load: `open` prints the list, and a switch of spec on a
|
||||
resume reaches you as ordinary workspace changes on your next `wait`.
|
||||
|
||||
### What you are told
|
||||
|
||||
@@ -767,7 +774,7 @@ that is what the person is there to download. The finish carries no
|
||||
sees the Trail Footer, and without this their last screen promises a question
|
||||
that is never coming.
|
||||
- Post `run` `pathfinder-chart` (id `map`) when a new map is first written,
|
||||
and `pathfinder-research` (id = the question's file slug) as each research
|
||||
and `pathfinder-research` (id = the question's file slug; on `github`, `q<issue-number>`) as each research
|
||||
subagent reports back, or when you resolve a `research` question yourself
|
||||
(Posting an update → Session meter). Other questions score through their
|
||||
answers, so there is nothing to post for them.
|
||||
@@ -820,7 +827,7 @@ know:
|
||||
| 3, Implementation Summary | Written to `overview.md` as usual; mirror it as a doc (marked `saved`) so the page reader sees it land. |
|
||||
| 4, Documentation Review | The proposed-updates table as a doc, and a `multi` naming the documents to update — every option ticked is "approve", unticked ones are skipped. A `review` works instead when the set is all-or-nothing. |
|
||||
| 5, User Feedback | Optional items, `required: false`: the rating as a `choice` of 1 to 10 or a `text`, the three reasons as `text`. The submit-to-maintainer consent is a `confirm`. |
|
||||
| 6, Spec Cleanup | A `confirm` before moving anything, the archive paths in `consequences`. |
|
||||
| 6, Spec Cleanup | A `confirm` before moving anything, the archive paths in `consequences`, and a line that the spec's remembered workspace folders are forgotten too (`console.mjs forget --spec specs/<feature>` after the move). |
|
||||
|
||||
Pass `--spec specs/<feature>` to `open`, or post `specDir` once you know it.
|
||||
Stopping mid-finalize loses nothing
|
||||
|
||||
@@ -41,6 +41,7 @@ import {
|
||||
die,
|
||||
ensureDir,
|
||||
fileStamp,
|
||||
forgetWorkspace,
|
||||
handOff,
|
||||
handleFile,
|
||||
healthOk,
|
||||
@@ -65,6 +66,7 @@ import {
|
||||
readLedger,
|
||||
readWorkspace,
|
||||
reapHandles,
|
||||
rememberedWorkspace,
|
||||
remoteWarning,
|
||||
removeScratch,
|
||||
removeSessions,
|
||||
@@ -73,6 +75,7 @@ import {
|
||||
SESSION_MAX_AGE_MS,
|
||||
sessionDir,
|
||||
sleepSync,
|
||||
specKey,
|
||||
staleScratch,
|
||||
staleSessions,
|
||||
sweepUploads,
|
||||
@@ -317,7 +320,7 @@ async function cmdOpen() {
|
||||
if (launched) appendLedger(dir, { kind: "launch", id: nextLaunchId(readLedger(dir)), workflow: state.workflow });
|
||||
for (const line of ledgerFromPost(dir, openRun, openIssue, state.workflow)) appendLedger(dir, line);
|
||||
} catch {}
|
||||
const workspace = workspaceOnOpen(dir, worktree);
|
||||
const workspace = workspaceOnOpen(dir, worktree, state.specDir);
|
||||
|
||||
// Month-old sessions and scratch files: listed before the print so the
|
||||
// agent can see what went, removed after it so the page waits for nothing.
|
||||
@@ -403,10 +406,11 @@ async function cmdOpen() {
|
||||
* The workspace as `open` hands it to the agent, and the cursor seeded to
|
||||
* match: the agent now has the whole list, so no change up to here is owed.
|
||||
* Read-only on workspace.json, which only the server writes; on a fresh
|
||||
* session the server has not made it yet, so the original folder stands in.
|
||||
* session the server has not made it yet, so what was remembered for this
|
||||
* folder and spec stands in, the same list the server is about to make.
|
||||
*/
|
||||
function workspaceOnOpen(dir, worktree) {
|
||||
const ws = readWorkspace(dir) || initialWorkspace(worktree);
|
||||
function workspaceOnOpen(dir, worktree, specDir) {
|
||||
const ws = readWorkspace(dir) || initialWorkspace(worktree, rememberedWorkspace(worktree, specDir).entry);
|
||||
const missing = ws.folders.filter((f) => !isFolder(f.path)).map((f) => f.id);
|
||||
try {
|
||||
writeWorkspaceCursor(dir, ws.version || 0);
|
||||
@@ -946,6 +950,18 @@ function realNearest(p) {
|
||||
return path.join(fs.realpathSync(existing), path.relative(existing, p));
|
||||
}
|
||||
|
||||
/* --------------------------------------------------------------- forget */
|
||||
|
||||
// Drop the folder list remembered for one spec (Finalize, once the spec is
|
||||
// archived). The project's own list and every other spec's are untouched.
|
||||
function cmdForget() {
|
||||
if (typeof args.spec !== "string" || !args.spec.trim()) die("forget needs --spec specs/<idea>", 2);
|
||||
let spec = specKey(args.spec);
|
||||
if (/\.md$/i.test(spec)) spec = spec.slice(0, spec.lastIndexOf("/"));
|
||||
const worktree = repoRoots().worktree;
|
||||
print({ ok: true, spec, forgot: forgetWorkspace(worktree, spec) });
|
||||
}
|
||||
|
||||
/* ----------------------------------------------------------------- help */
|
||||
|
||||
function cmdHelp() {
|
||||
@@ -961,7 +977,8 @@ port, and the filesystem as transport; this CLI is the whole agent surface.
|
||||
first post. --file is optional, and --title defaults to the
|
||||
project's folder name. Also prints workspace: { folders: [{ name,
|
||||
path, description?, original? }], missing? }, the folders this
|
||||
console session reads as context, addressed as @name.
|
||||
console session reads as context, addressed as @name. The list is
|
||||
remembered per folder and spec in workspaces.json beside looks.json.
|
||||
post --session <sid> --file <patch.json>
|
||||
Merge a patch into the session. Prints terminalLine while the
|
||||
server is live. Exit 3 = rejected; stderr says why. A patch may
|
||||
@@ -988,6 +1005,10 @@ port, and the filesystem as transport; this CLI is the whole agent surface.
|
||||
Copy a cited note attachment into specs/<idea>/attachments/. Prints
|
||||
{ ok, path, link, image, reused }; exit 2 = bad usage, 3 = refused or
|
||||
missing. Paste link as it is.
|
||||
forget --spec specs/<idea>
|
||||
Drop the workspace folders remembered for that spec, in this
|
||||
folder (Finalize, after archiving it). Prints { ok, spec, forgot };
|
||||
forgot is false when nothing was saved. Exit 2 = bad usage.
|
||||
status [--session <sid>] [--all]
|
||||
One session, or every session belonging to this project.
|
||||
stop --session <sid> | --all
|
||||
@@ -1206,6 +1227,7 @@ const COMMANDS = {
|
||||
wait: cmdWait,
|
||||
chat: cmdChat,
|
||||
keep: cmdKeep,
|
||||
forget: cmdForget,
|
||||
status: cmdStatus,
|
||||
stop: cmdStop,
|
||||
help: cmdHelp,
|
||||
|
||||
@@ -178,8 +178,8 @@ function lockStale(lock) {
|
||||
// Run fn while holding the session's state lock, and release it however fn
|
||||
// ends. fn must not call process.exit(): the release would never run, and the
|
||||
// next writer would wait out the stale age.
|
||||
export function withStateLock(dir, fn) {
|
||||
const lock = path.join(dir, STATE_LOCK_FILE);
|
||||
export function withStateLock(dir, fn, lockName = STATE_LOCK_FILE) {
|
||||
const lock = path.join(dir, lockName);
|
||||
const deadline = Date.now() + LOCK_WAIT_MS;
|
||||
let fd = null;
|
||||
for (let attempt = 0; fd === null; attempt++) {
|
||||
@@ -188,7 +188,7 @@ export function withStateLock(dir, fn) {
|
||||
} catch (err) {
|
||||
// EPERM / EACCES: on Windows, a lock being deleted still blocks a create.
|
||||
if (!["EEXIST", "EPERM", "EACCES", "EBUSY"].includes(err.code)) throw err;
|
||||
if (Date.now() > deadline) throw new Error("state.json is busy with another writer; try again");
|
||||
if (Date.now() > deadline) throw new Error(`${lockName.replace(/.lock$/, "")} is busy with another writer; try again`);
|
||||
if (err.code === "EEXIST" && lockStale(lock)) {
|
||||
try {
|
||||
fs.rmSync(lock, { force: true });
|
||||
@@ -487,8 +487,9 @@ export async function removeSessions(sessionsDir, sids) {
|
||||
}
|
||||
|
||||
// The console folder's own files that no sweep may ever remove: the person's
|
||||
// looks and the pointer to this console's directory.
|
||||
export const PROTECTED_CONSOLE_FILES = new Set(["looks.json", "console-dir"]);
|
||||
// looks, the folders remembered per project and spec, and the pointer to
|
||||
// this console's directory.
|
||||
export const PROTECTED_CONSOLE_FILES = new Set(["looks.json", "workspaces.json", "console-dir"]);
|
||||
|
||||
function isScratchName(name) {
|
||||
return (
|
||||
@@ -1619,17 +1620,125 @@ export function readWorkspace(dir) {
|
||||
return readJson(path.join(dir, WORKSPACE_FILE), null);
|
||||
}
|
||||
|
||||
// A fresh workspace: just the original folder, named after itself.
|
||||
export function initialWorkspace(worktree) {
|
||||
// A fresh workspace: the original folder, named after itself, plus whatever
|
||||
// was remembered for this folder and spec (rememberedWorkspace() below).
|
||||
export function initialWorkspace(worktree, remembered = null) {
|
||||
const original = { id: "f0", path: worktree, name: defaultName(worktree), description: "", original: true };
|
||||
if (remembered && remembered.original) {
|
||||
if (remembered.original.name) original.name = remembered.original.name;
|
||||
if (remembered.original.description) original.description = remembered.original.description;
|
||||
}
|
||||
const added = ((remembered && remembered.folders) || []).map((f, i) => ({
|
||||
id: "f" + (i + 1),
|
||||
path: f.path,
|
||||
name: f.name,
|
||||
description: f.description || "",
|
||||
...(f.nested ? { nested: true } : {}),
|
||||
}));
|
||||
return { version: 0, folders: [original, ...added], missing: [], changes: [], remote: "" };
|
||||
}
|
||||
|
||||
/* ------------------------------------------------ remembered workspaces */
|
||||
|
||||
// The folder list outlives the console session: one file for the person,
|
||||
// beside looks.json, keyed by the folder a session runs in and then by spec.
|
||||
// Never under specs/: the paths are this machine's, and the server never
|
||||
// writes into a project.
|
||||
//
|
||||
// { "projects": { "<folded worktree>": {
|
||||
// "path": "<worktree>",
|
||||
// "project": { original, folders, at }, // no spec picked
|
||||
// "specs": { "specs/<name>": { original, folders, at } } } } }
|
||||
//
|
||||
// `original` holds the first folder's name and description only (its path is
|
||||
// always the session's own); `folders` the added ones as { path, name,
|
||||
// description, nested? }. Two writers, the server on every change and
|
||||
// `console.mjs forget`, each a read-modify-write of one key.
|
||||
export const WORKSPACES_FILE = path.join(HOME_DIR, "workspaces.json");
|
||||
|
||||
const foldKey = (p) => {
|
||||
const resolved = path.resolve(String(p || ""));
|
||||
return process.platform === "win32" || process.platform === "darwin" ? resolved.toLowerCase() : resolved;
|
||||
};
|
||||
|
||||
// `specs/<name>` with forward slashes and no trailing slash, or "" for none.
|
||||
export function specKey(specDir) {
|
||||
return String(specDir || "")
|
||||
.trim()
|
||||
.replace(/\\/g, "/")
|
||||
.replace(/^\.\//, "")
|
||||
.replace(/\/+$/, "");
|
||||
}
|
||||
|
||||
function readStore() {
|
||||
const saved = readJson(WORKSPACES_FILE, null);
|
||||
return saved && typeof saved.projects === "object" && saved.projects ? saved : { projects: {} };
|
||||
}
|
||||
|
||||
/**
|
||||
* What was remembered for this folder and spec: `{ entry, from }`, where
|
||||
* `from` is "spec" when the spec has its own list, "project" when it falls
|
||||
* back to the project's (a spec's list starts as a copy of it), and null
|
||||
* when nothing was ever saved.
|
||||
*/
|
||||
export function rememberedWorkspace(worktree, specDir) {
|
||||
const project = readStore().projects[foldKey(worktree)];
|
||||
if (!project) return { entry: null, from: null };
|
||||
const spec = specKey(specDir);
|
||||
if (spec && project.specs && project.specs[spec]) return { entry: project.specs[spec], from: "spec" };
|
||||
return project.project ? { entry: project.project, from: "project" } : { entry: null, from: null };
|
||||
}
|
||||
|
||||
// The workspace's folders as the store keeps them.
|
||||
export function rememberable(ws) {
|
||||
const folders = (ws && ws.folders) || [];
|
||||
const first = folders.find((f) => f.original) || {};
|
||||
return {
|
||||
version: 0,
|
||||
folders: [{ id: "f0", path: worktree, name: defaultName(worktree), description: "", original: true }],
|
||||
missing: [],
|
||||
changes: [],
|
||||
remote: "",
|
||||
original: { name: first.name || "", description: first.description || "" },
|
||||
folders: folders
|
||||
.filter((f) => !f.original)
|
||||
.map((f) => ({ path: f.path, name: f.name, description: f.description || "", ...(f.nested ? { nested: true } : {}) })),
|
||||
at: nowIso(),
|
||||
};
|
||||
}
|
||||
|
||||
// Every server and `console.mjs forget` writes the one file, so each
|
||||
// read-modify-write holds this lock beside it.
|
||||
const WORKSPACES_LOCK = "workspaces.json.lock";
|
||||
|
||||
// Save the list for this folder and spec ("" for the project's own).
|
||||
export function rememberWorkspace(worktree, specDir, ws) {
|
||||
ensureDir(path.dirname(WORKSPACES_FILE));
|
||||
withStateLock(path.dirname(WORKSPACES_FILE), () => saveRemembered(worktree, specDir, ws), WORKSPACES_LOCK);
|
||||
}
|
||||
|
||||
function saveRemembered(worktree, specDir, ws) {
|
||||
const store = readStore();
|
||||
const key = foldKey(worktree);
|
||||
const project = store.projects[key] || { path: path.resolve(worktree) };
|
||||
const spec = specKey(specDir);
|
||||
if (spec) project.specs = { ...(project.specs || {}), [spec]: rememberable(ws) };
|
||||
else project.project = rememberable(ws);
|
||||
store.projects[key] = project;
|
||||
writeJsonAtomic(WORKSPACES_FILE, store);
|
||||
}
|
||||
|
||||
// Drop one spec's list (Finalize, once the spec is archived). True when there was one.
|
||||
export function forgetWorkspace(worktree, specDir) {
|
||||
const spec = specKey(specDir);
|
||||
if (!spec || !fs.existsSync(WORKSPACES_FILE)) return false;
|
||||
return withStateLock(path.dirname(WORKSPACES_FILE), () => dropRemembered(worktree, spec), WORKSPACES_LOCK);
|
||||
}
|
||||
|
||||
function dropRemembered(worktree, spec) {
|
||||
const store = readStore();
|
||||
const project = store.projects[foldKey(worktree)];
|
||||
if (!spec || !project || !project.specs || !project.specs[spec]) return false;
|
||||
delete project.specs[spec];
|
||||
writeJsonAtomic(WORKSPACES_FILE, store);
|
||||
return true;
|
||||
}
|
||||
|
||||
// Single-writer rule: only server.mjs may call this.
|
||||
export function writeWorkspace(dir, ws) {
|
||||
return writeJsonAtomic(path.join(dir, WORKSPACE_FILE), ws);
|
||||
|
||||
@@ -2505,6 +2505,9 @@ a.icon-btn { box-sizing: border-box; text-decoration: none; }
|
||||
actions stay put. */
|
||||
.modal.workspace { max-width: 680px; }
|
||||
.modal.workspace[open] { display: flex; flex-direction: column; max-height: calc(100vh - 48px); }
|
||||
.workspace .modal-blurb { margin-bottom: 6px; }
|
||||
.workspace-scope { margin: 0 0 16px; color: var(--ink-3, var(--ink-2)); font-size: 12.5px; }
|
||||
|
||||
.workspace-list {
|
||||
list-style: none; margin: 0; padding: 0;
|
||||
display: grid; gap: 12px;
|
||||
|
||||
@@ -2542,6 +2542,7 @@ function renderDashboard(main) {
|
||||
const specs = specList();
|
||||
if (specs.length) wrap.appendChild(renderSpecPicker(specs));
|
||||
wrap.appendChild(hideUnavailableToggle());
|
||||
if (!local.launching && !launchScoping) 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
|
||||
@@ -2963,6 +2964,11 @@ async function launchSkill(entry) {
|
||||
// cards that take no spec (utilities, setup) launch untargeted even while
|
||||
// a spec is selected.
|
||||
if (target) action.spec = target.dir;
|
||||
// The skill opens on the folders remembered for what it was launched for.
|
||||
// Held until the launch is in flight: the swap's own frame re-renders the
|
||||
// dashboard, which would otherwise sync back to the picker's spec.
|
||||
launchScoping = true;
|
||||
await syncWorkspaceScope(target ? target.dir : "");
|
||||
try {
|
||||
const res = await fetch("/submit", {
|
||||
method: "POST",
|
||||
@@ -2973,6 +2979,7 @@ async function launchSkill(entry) {
|
||||
}),
|
||||
});
|
||||
if (res.status === 409) {
|
||||
launchScoping = false;
|
||||
pendingResult = true;
|
||||
banner("Your last pick is still being picked up. One moment.", "info");
|
||||
return;
|
||||
@@ -2980,10 +2987,12 @@ async function launchSkill(entry) {
|
||||
if (!res.ok) throw new Error(String(res.status));
|
||||
sound("startSkill");
|
||||
local.launching = { skill: entry.skill, title: entry.title, at: Date.now() };
|
||||
launchScoping = false;
|
||||
pendingResult = true;
|
||||
save();
|
||||
render();
|
||||
} catch {
|
||||
launchScoping = false;
|
||||
banner("That did not go through. Nothing was lost; try again.", "warn");
|
||||
}
|
||||
}
|
||||
@@ -5854,6 +5863,32 @@ async function postJson(url, body) {
|
||||
}
|
||||
}
|
||||
|
||||
/* The workspace follows the dashboard's picker: the folders remembered for
|
||||
the selected spec, or the project's own under "Start from scratch". The
|
||||
server swaps the list and remembers every change after it. */
|
||||
let scopeAsked = null;
|
||||
// True from a launch's scope sync until its send has gone (or failed).
|
||||
let launchScoping = false;
|
||||
async function syncWorkspaceScope(spec) {
|
||||
if (!S || S.workflow !== "dashboard" || gone || !wsFrame) return;
|
||||
const want = spec === undefined ? (selSpec() && selSpec().dir) || "" : spec;
|
||||
if ((wsFrame.scope || "") === want || scopeAsked === want) return;
|
||||
scopeAsked = want;
|
||||
const { status, body } = await postJson("/workspace/scope", { spec: want });
|
||||
if (status === 200 && body && Array.isArray(body.folders)) wsFrame = { ...wsFrame, ...body };
|
||||
scopeAsked = null;
|
||||
if ($("workspace-modal").open) renderWorkspace();
|
||||
}
|
||||
|
||||
// The dialog's "Remembered for" line: whose list this is.
|
||||
function workspaceScopeText() {
|
||||
const scope = (wsFrame && wsFrame.scope) || "";
|
||||
if (!scope) return "Remembered for this project, so your next console session here starts with these folders.";
|
||||
const spec = specList().find((s) => s.dir === scope);
|
||||
const name = spec ? spec.name : scope.split("/").pop();
|
||||
return `Remembered for the ${name} spec, and loaded again whenever it is picked.`;
|
||||
}
|
||||
|
||||
const NAME_RULE = "Names use lowercase letters, numbers and hyphens.";
|
||||
const BROWSE_UNAVAILABLE = "Browse isn't available here — type or paste the path.";
|
||||
// The folder whose Remove is waiting on its inline confirm, by id.
|
||||
@@ -5893,6 +5928,7 @@ function renderWorkspace() {
|
||||
}
|
||||
folders.forEach((f, i) => paintWorkspaceRow(list.children[i], f));
|
||||
$("workspace-browse").hidden = Boolean(wsFrame && wsFrame.remote);
|
||||
$("workspace-scope").textContent = workspaceScopeText();
|
||||
}
|
||||
|
||||
function workspaceRow(f) {
|
||||
|
||||
@@ -833,10 +833,28 @@
|
||||
Click the folder name in the middle of the bottom bar. It shows your
|
||||
folder's name and branch, such as <strong>shop · main</strong>, and
|
||||
<strong>shop + 2 folders · main</strong> once you have added some.
|
||||
The workspace lasts for this console session only: it carries across
|
||||
steps you start from the dashboard, and a new console session starts
|
||||
with just the folder you started in.
|
||||
It carries across steps you start from the dashboard.
|
||||
</p>
|
||||
<h4>Remembered for next time</h4>
|
||||
<ul>
|
||||
<li>
|
||||
Every change is saved as you make it, so the next console session in
|
||||
this folder starts with the same folders.
|
||||
</li>
|
||||
<li>
|
||||
Each spec keeps its own list. The first time you pick a spec on the
|
||||
dashboard it starts as a copy of the project's list (the one shown
|
||||
under <strong>Start from scratch</strong>), and after that the two
|
||||
are separate. Picking a spec loads its list; the line under the
|
||||
dialog's title says whose list you are looking at.
|
||||
</li>
|
||||
<li>
|
||||
The lists live in <code>workspaces.json</code> in your own
|
||||
Plan2Code settings folder, beside your look and feel, never in the
|
||||
project. Finalize offers to forget a spec's list when it archives the
|
||||
spec.
|
||||
</li>
|
||||
</ul>
|
||||
<h4>Adding a folder</h4>
|
||||
<ul>
|
||||
<li>
|
||||
@@ -1363,9 +1381,10 @@
|
||||
<h4>What it counts</h4>
|
||||
<p>
|
||||
Each step you run here adds points: a plan or a set of documents
|
||||
weighs more than a single answered question, and a built phase more
|
||||
still, by how many tasks it completed: a big phase adds more than a
|
||||
small one. Every two questions you answer add a point too, so a long
|
||||
weighs more than a quick task, and a built phase more still, by how
|
||||
many tasks it completed: a big phase adds more than a small one.
|
||||
Every two questions you answer within one step add a point too
|
||||
(rounded down, so a single answer adds nothing), so a long
|
||||
back-and-forth counts for more than a short one. Click the ring to see the count and a list of each step that added
|
||||
points, with what it added. It is a rule of thumb, not a
|
||||
reading of Plan2Code's real memory: long sessions tend to make it
|
||||
@@ -2003,6 +2022,7 @@
|
||||
The folders the agent uses as context this session. It reads the extra ones for
|
||||
reference and only changes them if you ask.
|
||||
</p>
|
||||
<p class="workspace-scope" id="workspace-scope"></p>
|
||||
<ul class="workspace-list" id="workspace-list"></ul>
|
||||
<div class="workspace-add">
|
||||
<label class="workspace-add-label" for="workspace-path">Add a folder</label>
|
||||
|
||||
@@ -45,7 +45,10 @@ import {
|
||||
readLedger,
|
||||
readOverview,
|
||||
readWorkspace,
|
||||
rememberWorkspace,
|
||||
rememberedWorkspace,
|
||||
remoteWarning,
|
||||
specKey,
|
||||
typedCount,
|
||||
withStateLock,
|
||||
writeJsonAtomic,
|
||||
@@ -326,7 +329,9 @@ function workspaceNow() {
|
||||
return ws;
|
||||
}
|
||||
const root = sessionWorktree();
|
||||
const fresh = { ...initialWorkspace(root || PROJECT), remote: remoteWarning().remote || "" };
|
||||
const scope = specKey(stateNow?.specDir);
|
||||
const remembered = root ? rememberedWorkspace(root, scope).entry : null;
|
||||
const fresh = { ...initialWorkspace(root || PROJECT, remembered), scope, remote: remoteWarning().remote || "" };
|
||||
// There but unreadable for now (a scanner's lock): never written over, and
|
||||
// never cached, so the next call reads it again.
|
||||
if (stamp) return workspaceSeen.ws || fresh;
|
||||
@@ -347,13 +352,87 @@ function saveWorkspace(ws) {
|
||||
|
||||
// One change: a new version, an entry in the change log the agent is handed,
|
||||
// the file, and every open page.
|
||||
function bumpWorkspace(ws, change) {
|
||||
function bumpWorkspace(ws, change, { remember = true } = {}) {
|
||||
ws.version = (ws.version || 0) + 1;
|
||||
ws.changes = [...(ws.changes || []), { ...change, version: ws.version }];
|
||||
saveWorkspace(ws);
|
||||
// Remembered for the next console session too. A folder gone missing or
|
||||
// found again is not a change of mind, so it is not saved.
|
||||
if (remember) rememberNow(ws);
|
||||
pushState();
|
||||
}
|
||||
|
||||
function rememberNow(ws) {
|
||||
const root = sessionWorktree();
|
||||
if (!root) return;
|
||||
try {
|
||||
rememberWorkspace(root, ws.scope || "", ws);
|
||||
} catch {}
|
||||
}
|
||||
|
||||
/**
|
||||
* Point the workspace at another spec ("" for the project's own list) and
|
||||
* swap in what was remembered there, logging each difference as a change so
|
||||
* the agent's cursor stays truthful. A spec with nothing saved starts from
|
||||
* the project's list (`seed: "project"`, the dashboard picker) or keeps the
|
||||
* list it has and saves it as the spec's (`seed: "current"`, a spec created
|
||||
* mid-run). Folders keep their ids when their path stays.
|
||||
*/
|
||||
function setScope(ws, spec, seed = "project") {
|
||||
const root = sessionWorktree();
|
||||
const next = specKey(spec);
|
||||
if (!root || (ws.scope || "") === next) return false;
|
||||
const found = rememberedWorkspace(root, next);
|
||||
ws.scope = next;
|
||||
if (next && found.from !== "spec" && seed === "current") {
|
||||
saveWorkspace(ws);
|
||||
rememberNow(ws);
|
||||
pushState();
|
||||
return true;
|
||||
}
|
||||
const want = initialWorkspace(root, found.entry).folders;
|
||||
const byPath = new Map(ws.folders.map((f) => [foldPath(path.resolve(f.path)), f]));
|
||||
const kept = new Set();
|
||||
const folders = [];
|
||||
const changes = [];
|
||||
for (const w of want) {
|
||||
const have = w.original ? ws.folders.find((f) => f.original) : byPath.get(foldPath(path.resolve(w.path)));
|
||||
if (!have) {
|
||||
folders.push({ ...w, id: "pending" });
|
||||
changes.push({ kind: "added", name: w.name, path: w.path, description: w.description });
|
||||
continue;
|
||||
}
|
||||
kept.add(have);
|
||||
if (have.name !== w.name) changes.push({ kind: "renamed", from: have.name, name: w.name, path: have.path });
|
||||
if ((have.description || "") !== (w.description || "")) {
|
||||
changes.push({ kind: "described", name: w.name, path: have.path, description: w.description || "" });
|
||||
}
|
||||
folders.push({ ...have, name: w.name, description: w.description || "" });
|
||||
}
|
||||
for (const f of ws.folders) {
|
||||
if (!kept.has(f)) changes.unshift({ kind: "removed", name: f.name, path: f.path });
|
||||
}
|
||||
ws.folders = folders.filter((f) => f.id !== "pending");
|
||||
for (const f of folders.filter((f) => f.id === "pending")) ws.folders.push({ ...f, id: nextFolderId(ws) });
|
||||
ws.missing = (ws.missing || []).filter((id) => ws.folders.some((f) => f.id === id));
|
||||
if (!changes.length) {
|
||||
saveWorkspace(ws);
|
||||
pushState();
|
||||
}
|
||||
for (const c of changes) bumpWorkspace(ws, c, { remember: false });
|
||||
checkFolders(ws);
|
||||
return true;
|
||||
}
|
||||
|
||||
// A spec posted mid-run (Pathfinder or Plan making its folder, a skill that
|
||||
// learns its spec late) takes the workspace with it.
|
||||
function followSpecDir(state) {
|
||||
const spec = specKey(state && state.specDir);
|
||||
if (!spec || !fileStamp(WORKSPACE_PATH)) return;
|
||||
const ws = workspaceNow();
|
||||
if ((ws.scope || "") !== spec) setScope(ws, spec, "current");
|
||||
}
|
||||
|
||||
function isFolder(p) {
|
||||
try {
|
||||
return fs.statSync(p).isDirectory();
|
||||
@@ -370,10 +449,10 @@ function checkFolders(ws) {
|
||||
const marked = ws.missing.includes(f.id);
|
||||
if (!there && !marked) {
|
||||
ws.missing = [...ws.missing, f.id];
|
||||
bumpWorkspace(ws, { kind: "missing", name: f.name, path: f.path });
|
||||
bumpWorkspace(ws, { kind: "missing", name: f.name, path: f.path }, { remember: false });
|
||||
} else if (there && marked) {
|
||||
ws.missing = ws.missing.filter((id) => id !== f.id);
|
||||
bumpWorkspace(ws, { kind: "found", name: f.name, path: f.path });
|
||||
bumpWorkspace(ws, { kind: "found", name: f.name, path: f.path }, { remember: false });
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -402,8 +481,8 @@ function folderIssues(entries) {
|
||||
}
|
||||
|
||||
function workspaceView() {
|
||||
const { folders, missing, remote } = workspaceNow();
|
||||
return { folders, missing: missing || [], remote: remote || "", issues: folderIssues(ledgerEntries()) };
|
||||
const { folders, missing, remote, scope } = workspaceNow();
|
||||
return { folders, missing: missing || [], remote: remote || "", scope: scope || "", issues: folderIssues(ledgerEntries()) };
|
||||
}
|
||||
|
||||
// Whether child sits strictly under parent.
|
||||
@@ -492,6 +571,7 @@ function bootWorkspace() {
|
||||
saveWorkspace(ws);
|
||||
}
|
||||
checkFolders(ws);
|
||||
followSpecDir(stateNow);
|
||||
}
|
||||
|
||||
/**
|
||||
@@ -1403,6 +1483,24 @@ const server = http.createServer((req, res) => {
|
||||
});
|
||||
}
|
||||
|
||||
// Which list the workspace is: a spec's, or the project's (`spec` empty).
|
||||
// The dashboard's picker sends it as the selection moves and before a
|
||||
// launch, so a skill opens on the list of the spec it was launched for.
|
||||
if (pathname === "/workspace/scope" && req.method === "POST") {
|
||||
if (!originOk(req, port)) return json(res, 403, { error: "bad origin" });
|
||||
return readBody(req, (err, body) => {
|
||||
if (err || !body || typeof body !== "object" || Array.isArray(body)) return json(res, 400, { error: "bad" });
|
||||
const spec = typeof body.spec === "string" ? body.spec : "";
|
||||
if (spec && !/^specs\/[^/\\]+$/.test(specKey(spec))) return json(res, 400, { reason: "bad-spec" });
|
||||
try {
|
||||
setScope(workspaceNow(), spec, "project");
|
||||
} catch (e) {
|
||||
return json(res, 500, { error: String(e.message) });
|
||||
}
|
||||
return json(res, 200, workspaceView());
|
||||
});
|
||||
}
|
||||
|
||||
// Only ever returns a path: the page then adds it through /workspace/add.
|
||||
if (pathname === "/workspace/browse" && req.method === "POST") {
|
||||
if (!originOk(req, port)) return json(res, 403, { error: "bad origin" });
|
||||
@@ -1561,6 +1659,9 @@ function checkState() {
|
||||
try {
|
||||
ensureConversation(parsed);
|
||||
} catch {}
|
||||
try {
|
||||
followSpecDir(parsed);
|
||||
} catch {}
|
||||
pushState();
|
||||
}
|
||||
lastStateStamp = stamp;
|
||||
|
||||
@@ -17,6 +17,6 @@
|
||||
"url": "https://github.com/jparkerweb/plan2code"
|
||||
},
|
||||
"homepage": "https://github.com/jparkerweb/plan2code",
|
||||
"releaseDate": "2026-10-02",
|
||||
"releaseDate": "2026-10-04",
|
||||
"mode": "utility"
|
||||
}
|
||||
@@ -0,0 +1,247 @@
|
||||
// Plan2Code skill scripts: shared plumbing.
|
||||
//
|
||||
// Every script in a skill's scripts/ directory imports this file. It owns the
|
||||
// conventions the SKILL.md prompts rely on, so they are identical everywhere:
|
||||
//
|
||||
// stdout one JSON object, always. `{ "ok": true, ... }` on success,
|
||||
// `{ "ok": false, "error": "<code>", "message": "...", "next": "..." }`
|
||||
// on a handled failure.
|
||||
// stderr a one-line human diagnostic on failure (the same message + next).
|
||||
// exit 0 ok · 1 unexpected crash · 2 bad arguments · 3 not found ·
|
||||
// 4 invalid input or a check that failed · 5 refused (would clobber
|
||||
// or break a rule).
|
||||
//
|
||||
// Node 18+ built-ins only, no build step: this ships inside every skill.
|
||||
|
||||
import fs from "node:fs";
|
||||
import path from "node:path";
|
||||
import { fileURLToPath, pathToFileURL } from "node:url";
|
||||
|
||||
export const HERE = path.dirname(fileURLToPath(import.meta.url));
|
||||
|
||||
export const EXIT = { OK: 0, CRASH: 1, USAGE: 2, NOT_FOUND: 3, INVALID: 4, REFUSED: 5 };
|
||||
|
||||
export class CliError extends Error {
|
||||
constructor(exit, error, message, next) {
|
||||
super(message);
|
||||
this.exit = exit;
|
||||
this.error = error;
|
||||
this.next = next;
|
||||
}
|
||||
}
|
||||
|
||||
/** Throw a handled failure: the run() wrapper prints it and sets the exit code. */
|
||||
export function fail(exit, error, message, next) {
|
||||
throw new CliError(exit, error, message, next);
|
||||
}
|
||||
|
||||
export function out(obj) {
|
||||
process.stdout.write(JSON.stringify(obj, null, 2) + "\n");
|
||||
}
|
||||
|
||||
/**
|
||||
* Parse argv into { _: positionals, <flag>: value }.
|
||||
* `booleans` names flags that take no value; every other `--flag` takes the
|
||||
* next argument, and repeats of a flag listed in `lists` collect into an array.
|
||||
* `--flag=value` works too. Unknown flags are a usage error, so a typo never
|
||||
* silently changes behavior.
|
||||
*/
|
||||
export function parseArgs(argv, { booleans = [], values = [], lists = [] } = {}) {
|
||||
const known = new Set([...booleans, ...values, ...lists, "help"]);
|
||||
const args = { _: [] };
|
||||
for (let i = 0; i < argv.length; i++) {
|
||||
const a = argv[i];
|
||||
if (!a.startsWith("--")) {
|
||||
args._.push(a);
|
||||
continue;
|
||||
}
|
||||
let name = a.slice(2);
|
||||
let value;
|
||||
const eq = name.indexOf("=");
|
||||
if (eq !== -1) {
|
||||
value = name.slice(eq + 1);
|
||||
name = name.slice(0, eq);
|
||||
}
|
||||
if (!known.has(name)) {
|
||||
fail(EXIT.USAGE, "unknown-flag", `Unknown flag --${name}.`, "Run with --help for the flags this script takes.");
|
||||
}
|
||||
if (name === "help" || booleans.includes(name)) {
|
||||
args[name] = true;
|
||||
continue;
|
||||
}
|
||||
if (value === undefined) {
|
||||
if (i + 1 >= argv.length) {
|
||||
fail(EXIT.USAGE, "missing-value", `--${name} needs a value.`, "Run with --help for usage.");
|
||||
}
|
||||
value = argv[++i];
|
||||
}
|
||||
if (lists.includes(name)) (args[name] ||= []).push(value);
|
||||
else args[name] = value;
|
||||
}
|
||||
return args;
|
||||
}
|
||||
|
||||
/**
|
||||
* Run a script's main(). Prints usage on --help, turns CliError into the JSON
|
||||
* failure shape plus an exit code, and anything else into exit 1 with the stack
|
||||
* on stderr. Sets process.exitCode rather than calling process.exit(), so
|
||||
* stdout is never cut off mid-write.
|
||||
*/
|
||||
export async function run(usage, main) {
|
||||
try {
|
||||
const argv = process.argv.slice(2);
|
||||
if (argv.includes("--help") || argv.includes("-h")) {
|
||||
process.stdout.write(usage.trim() + "\n");
|
||||
return;
|
||||
}
|
||||
await main(argv);
|
||||
} catch (err) {
|
||||
if (err instanceof CliError) {
|
||||
out({ ok: false, error: err.error, message: err.message, ...(err.next ? { next: err.next } : {}) });
|
||||
process.stderr.write(`error: ${err.message}${err.next ? `\nnext: ${err.next}` : ""}\n`);
|
||||
process.exitCode = err.exit;
|
||||
return;
|
||||
}
|
||||
process.stderr.write(`unexpected error: ${err && err.stack ? err.stack : err}\n`);
|
||||
out({ ok: false, error: "crash", message: String(err && err.message ? err.message : err) });
|
||||
process.exitCode = EXIT.CRASH;
|
||||
}
|
||||
}
|
||||
|
||||
/* ------------------------------------------------------------------ time */
|
||||
|
||||
// PLAN2CODE_NOW ("YYYY-MM-DD HH:mm" or any Date-parsable string) pins the
|
||||
// clock, for tests and for reproducing a run. Otherwise: the local clock, which
|
||||
// is what "today" means to the person reading the date in their files.
|
||||
export function now() {
|
||||
const pinned = process.env.PLAN2CODE_NOW;
|
||||
if (pinned) {
|
||||
const m = pinned.match(/^(\d{4})-(\d{2})-(\d{2})(?:[ T](\d{2}):(\d{2})(?::(\d{2}))?)?$/);
|
||||
if (m) return new Date(+m[1], +m[2] - 1, +m[3], +(m[4] || 0), +(m[5] || 0), +(m[6] || 0));
|
||||
const d = new Date(pinned);
|
||||
if (!Number.isNaN(d.getTime())) return d;
|
||||
}
|
||||
return new Date();
|
||||
}
|
||||
|
||||
const pad = (n) => String(n).padStart(2, "0");
|
||||
|
||||
/** YYYY-MM-DD */
|
||||
export function isoDate(d = now()) {
|
||||
return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}`;
|
||||
}
|
||||
|
||||
/** YYYYMMDD */
|
||||
export function compactDate(d = now()) {
|
||||
return isoDate(d).replace(/-/g, "");
|
||||
}
|
||||
|
||||
/** YYYY-MM-DD HH:mm */
|
||||
export function stamp(d = now()) {
|
||||
return `${isoDate(d)} ${pad(d.getHours())}:${pad(d.getMinutes())}`;
|
||||
}
|
||||
|
||||
/** HHMMSS */
|
||||
export function clock(d = now()) {
|
||||
return `${pad(d.getHours())}${pad(d.getMinutes())}${pad(d.getSeconds())}`;
|
||||
}
|
||||
|
||||
/* ----------------------------------------------------------------- files */
|
||||
|
||||
export function readText(file) {
|
||||
try {
|
||||
return fs.readFileSync(file, "utf8");
|
||||
} catch {
|
||||
return null;
|
||||
}
|
||||
}
|
||||
|
||||
export function isDir(p) {
|
||||
try {
|
||||
return fs.statSync(p).isDirectory();
|
||||
} catch {
|
||||
return false;
|
||||
}
|
||||
}
|
||||
|
||||
/** Write a file only when its content changes. Returns true when it wrote. */
|
||||
export function writeIfChanged(file, content) {
|
||||
const current = readText(file);
|
||||
if (current === content) return false;
|
||||
fs.mkdirSync(path.dirname(file), { recursive: true });
|
||||
fs.writeFileSync(file, content);
|
||||
return true;
|
||||
}
|
||||
|
||||
/** Normalise line endings for parsing; keep the original for writing back. */
|
||||
export function eol(text) {
|
||||
return text.includes("\r\n") ? "\r\n" : "\n";
|
||||
}
|
||||
|
||||
/**
|
||||
* phase-N.md per phase number. An exact phase-N.md always wins over a sibling
|
||||
* such as phase-1-old.md; more than one candidate is reported, never guessed.
|
||||
* Shared so every script that counts a spec's tasks reads the same files.
|
||||
*/
|
||||
export function phaseFiles(dir) {
|
||||
const files = new Map();
|
||||
const extra = new Map();
|
||||
for (const name of fs.readdirSync(dir).sort()) {
|
||||
const m = name.match(/^phase-(\d+)\b[^/]*\.md$/i);
|
||||
if (!m) continue;
|
||||
const n = Number(m[1]);
|
||||
const exact = new RegExp(`^phase-0*${n}\\.md$`, "i").test(name);
|
||||
if (!files.has(n)) files.set(n, name);
|
||||
else if (exact) {
|
||||
(extra.get(n) || extra.set(n, []).get(n)).push(files.get(n));
|
||||
files.set(n, name);
|
||||
} else (extra.get(n) || extra.set(n, []).get(n)).push(name);
|
||||
}
|
||||
files.extra = extra;
|
||||
return files;
|
||||
}
|
||||
|
||||
/** Forward-slash path relative to root, for output the agent pastes into prompts. */
|
||||
export function rel(root, p) {
|
||||
return path.relative(root, p).split(path.sep).join("/") || ".";
|
||||
}
|
||||
|
||||
/* --------------------------------------------------------- the web console */
|
||||
|
||||
// The web console ships beside these scripts in every installed skill
|
||||
// (references/web-console/), and in this repo it sits at src/web-console/. Its
|
||||
// lib.mjs is the one home of the spec-state classifier and the loop-marker /
|
||||
// metrics-bait scan, so the scripts import it rather than keep a second copy.
|
||||
const CONSOLE_LIB_CANDIDATES = [
|
||||
path.join(HERE, "..", "references", "web-console", "lib.mjs"), // installed skill
|
||||
path.join(HERE, "..", "web-console", "lib.mjs"), // src/skill-scripts in the repo
|
||||
];
|
||||
|
||||
let consoleLibPromise;
|
||||
export function consoleLib() {
|
||||
consoleLibPromise ||= (async () => {
|
||||
for (const candidate of CONSOLE_LIB_CANDIDATES) {
|
||||
if (fs.existsSync(candidate)) return import(pathToFileURL(candidate).href);
|
||||
}
|
||||
fail(
|
||||
EXIT.NOT_FOUND,
|
||||
"console-lib-missing",
|
||||
`The web console's lib.mjs is not beside this script (looked in ${CONSOLE_LIB_CANDIDATES.join(", ")}).`,
|
||||
"The skill install is incomplete; reinstall the Plan2Code skills (node install.js)."
|
||||
);
|
||||
})();
|
||||
return consoleLibPromise;
|
||||
}
|
||||
|
||||
/** The version these scripts shipped with (scripts/version.json, or the repo's). */
|
||||
export function version() {
|
||||
for (const file of [path.join(HERE, "version.json"), path.join(HERE, "..", "..", "version.json")]) {
|
||||
const text = readText(file);
|
||||
if (!text) continue;
|
||||
try {
|
||||
const v = JSON.parse(text).version;
|
||||
if (typeof v === "string") return v;
|
||||
} catch {}
|
||||
}
|
||||
return null;
|
||||
}
|
||||
@@ -0,0 +1,676 @@
|
||||
#!/usr/bin/env node
|
||||
// specs.mjs: where every spec under specs/ stands, read from its files.
|
||||
//
|
||||
// The pipeline skills (plan, document, implement, revise-plan, finalize,
|
||||
// review, handoff) all need the same filesystem facts: which specs exist, what
|
||||
// a spec's PLAN-DRAFT says, which phases are open, how many tasks are done.
|
||||
// Those have one correct answer, so this script computes them instead of each
|
||||
// prompt re-deriving them by hand. It also performs the two mechanical writes
|
||||
// (a Phase Checklist marker, the archive move), with --dry-run.
|
||||
//
|
||||
// Shell listing only matters to people: specs/ is gitignored, so editor search
|
||||
// tools skip it. This script reads the disk directly and does not care.
|
||||
|
||||
import fs from "node:fs";
|
||||
import path from "node:path";
|
||||
import { EXIT, fail, out, parseArgs, run, readText, isDir, rel, eol, consoleLib, isoDate, phaseFiles } from "./common.mjs";
|
||||
|
||||
const USAGE = `
|
||||
specs.mjs: spec state for the Plan2Code pipeline skills. JSON on stdout.
|
||||
|
||||
node specs.mjs list [--root <dir>]
|
||||
Every active spec under specs/ (never specs--completed/), newest first:
|
||||
state, detail, PLAN-DRAFT files with their **Status:** line, overview,
|
||||
phase count. Also the names already archived in specs--completed/.
|
||||
|
||||
node specs.mjs status <spec> [--root <dir>]
|
||||
One spec in full: the overview's Phase Checklist, Parallel Execution
|
||||
Groups, per-phase task counts by marker, task-numbering problems,
|
||||
completion, the implement phase-selection verdict ("next"), the pending
|
||||
phases, and consistency checks. <spec> is specs/<name>, <name>, or a path
|
||||
to its overview.md.
|
||||
|
||||
node specs.mjs metrics <spec> --step document|finalize [--set key=value ...]
|
||||
The METRICS_JSON comment for that step, countable fields computed from
|
||||
the files; judgment fields come from --set (numbers only).
|
||||
document: total_tasks, tasks_per_phase, phase_count,
|
||||
parallel_groups_identified computed; pass
|
||||
--set verification_items_added=N (your Verification Summary's
|
||||
Added total; the VERIFICATION comments are reported as a check).
|
||||
finalize: completion_rate_at_audit, tasks_completed, tasks_total; pass
|
||||
--set verification_failures_found=N
|
||||
--set documentation_updates_needed=N.
|
||||
|
||||
node specs.mjs mark <spec> --phase <N> --to open|in-progress|done [--dry-run]
|
||||
Set phase N's Phase Checklist marker in overview.md ([ ], [/], [x]).
|
||||
done also sets the phase file's Status line (**Status:**, **Status**:
|
||||
or Status:) to Complete (and warns if tasks are unfinished); open on a
|
||||
Complete phase sets it to In Progress. Warns when the phase file has no
|
||||
Status line. Refuses a phase with duplicate checklist rows, and refuses
|
||||
in-progress -> open (started work stays marked).
|
||||
|
||||
node specs.mjs archive <spec> [--dry-run]
|
||||
Move specs/<name>/ to specs--completed/<name>/. Refuses if the target
|
||||
exists, or if <spec> is not a folder directly under specs/.
|
||||
|
||||
Markers: [ ] pending · [/] in progress · [x] complete · [!] blocked · [?] assumed.
|
||||
Exit: 0 ok · 2 bad arguments · 3 spec not found · 4 cannot parse / check
|
||||
failed · 5 refused.
|
||||
`;
|
||||
|
||||
/* ------------------------------------------------------------- resolving */
|
||||
|
||||
function realOrResolved(p) {
|
||||
try {
|
||||
return fs.realpathSync.native(p);
|
||||
} catch {
|
||||
return path.resolve(p);
|
||||
}
|
||||
}
|
||||
|
||||
const samePath = (a, b) => (process.platform === "win32" ? a.toLowerCase() === b.toLowerCase() : a === b);
|
||||
|
||||
// Read-only commands (status, metrics) accept an archived spec, because
|
||||
// Finalize reads its own spec after Step 6 moved it. Writes never do.
|
||||
function resolveSpec(root, arg, { allowArchived = false } = {}) {
|
||||
if (!arg) fail(EXIT.USAGE, "missing-spec", "Name the spec: specs/<name>, <name>, or its overview.md path.", "Run `specs.mjs list` to see the active specs.");
|
||||
let p = arg.replace(/\\/g, "/").replace(/\/+$/, "");
|
||||
if (/\/overview\.md$/i.test(p) || /\/phase-[^/]*\.md$/i.test(p)) p = p.replace(/\/[^/]+$/, "");
|
||||
const abs = path.isAbsolute(p) ? p : p.includes("/") ? path.join(root, p) : path.join(root, "specs", p);
|
||||
const relPath = rel(root, abs);
|
||||
if (!allowArchived && /(^|\/)specs--completed(\/|$)/.test(relPath)) {
|
||||
fail(EXIT.REFUSED, "archived-spec", `${relPath} is archived; the pipeline only changes active specs under specs/.`, "Pick an active spec from `specs.mjs list`.");
|
||||
}
|
||||
// A spec is a folder directly under specs/ (or specs--completed/ for a read).
|
||||
// Without this, `archive .` would move all of specs/ and `archive ./src` a
|
||||
// source folder.
|
||||
const homes = [path.join(root, "specs"), ...(allowArchived ? [path.join(root, "specs--completed")] : [])].map(realOrResolved);
|
||||
const parent = realOrResolved(path.dirname(path.resolve(abs)));
|
||||
if (!homes.some((h) => samePath(h, parent))) {
|
||||
fail(EXIT.REFUSED, "not-a-spec", `${relPath} is not a spec folder: a spec sits directly under specs/${allowArchived ? " (or specs--completed/)" : ""}.`, "Pass specs/<name> or <name>; run `specs.mjs list` to see the active specs.");
|
||||
}
|
||||
if (!isDir(abs)) {
|
||||
fail(EXIT.NOT_FOUND, "spec-not-found", `No spec folder at ${relPath}.`, "Run `specs.mjs list` from the project root (or pass --root) to see the active specs.");
|
||||
}
|
||||
return { dir: abs, rel: relPath, name: path.basename(abs) };
|
||||
}
|
||||
|
||||
/* -------------------------------------------------------------- parsing */
|
||||
|
||||
const MARKERS = { " ": "pending", "/": "in-progress", x: "complete", X: "complete", "!": "blocked", "?": "assumed" };
|
||||
// Task 2.3, a lettered sub-task 3.6a, or a named one such as a testing task 1.T.
|
||||
const TASK_RE = /^\s*[-*] \[(.)\]\s+\*\*Task\s+(\d+)\.(\d+|[A-Za-z]+)([a-z]*)\b/;
|
||||
const CHECKBOX_RE = /^\s*[-*] \[(.)\]/;
|
||||
// The Status line in any of the forms people write it: **Status:**, **Status**:
|
||||
// or a plain Status:, optionally as a list item. Groups: everything up to the
|
||||
// value (kept as written when the value is rewritten), the value, trailing blanks.
|
||||
const STATUS_RE = /^([ \t]*(?:[-*][ \t]*)?(?:\*\*Status:\*\*|\*\*Status\*\*:|Status:)[ \t]*)(.+?)([ \t]*)$/m;
|
||||
|
||||
function statusOf(text) {
|
||||
const m = (text || "").match(STATUS_RE);
|
||||
return m ? m[2] : null;
|
||||
}
|
||||
|
||||
/** A markdown section's lines: from its heading to the next heading of the same or higher level. */
|
||||
function section(text, headingRe) {
|
||||
const lines = text.split(/\r?\n/);
|
||||
const start = lines.findIndex((l) => /^#{1,6}\s/.test(l) && headingRe.test(l));
|
||||
if (start === -1) return null;
|
||||
const level = lines[start].match(/^#+/)[0].length;
|
||||
let end = lines.length;
|
||||
for (let i = start + 1; i < lines.length; i++) {
|
||||
const m = lines[i].match(/^(#+)\s/);
|
||||
if (m && m[1].length <= level) {
|
||||
end = i;
|
||||
break;
|
||||
}
|
||||
}
|
||||
return { start, end, lines: lines.slice(start + 1, end) };
|
||||
}
|
||||
|
||||
function plainText(s) {
|
||||
return s
|
||||
.replace(/\[([^\]]*)\]\([^)]*\)/g, "$1")
|
||||
.replace(/[*_`]/g, "")
|
||||
.replace(/\s+/g, " ")
|
||||
.trim();
|
||||
}
|
||||
|
||||
/** Phase Checklist rows: the first "Phase N" on each checkbox line names the phase. */
|
||||
function parseChecklist(overview) {
|
||||
const sec = section(overview, /Phase Checklist/i);
|
||||
if (!sec) return { found: false, phases: [], unparsed: [] };
|
||||
const phases = [];
|
||||
const unparsed = [];
|
||||
sec.lines.forEach((line, i) => {
|
||||
const m = line.match(CHECKBOX_RE);
|
||||
if (!m) return;
|
||||
const text = plainText(line.replace(CHECKBOX_RE, ""));
|
||||
const num = text.match(/\bPhase\s+(\d+)\b/i);
|
||||
if (!num) {
|
||||
unparsed.push({ line: sec.start + 2 + i, text: line.trim() });
|
||||
return;
|
||||
}
|
||||
const after = text.slice(num.index + num[0].length).replace(/^\s*[:\-–—]\s*/, "");
|
||||
const name = after.split(/\s+[-–—]\s+|\s+\(|\s+_\(|:\s|\s+see\s+phase-/i)[0].replace(/\s*phase-\d+\.md\s*$/i, "").trim();
|
||||
phases.push({
|
||||
number: Number(num[1]),
|
||||
marker: m[1],
|
||||
state: MARKERS[m[1]] || "unknown",
|
||||
name: name.replace(/\s*\[Milestone[^\]]*\]\s*$/i, "") || `Phase ${num[1]}`,
|
||||
line: sec.start + 2 + i,
|
||||
});
|
||||
});
|
||||
return { found: true, phases, unparsed };
|
||||
}
|
||||
|
||||
/** "2, 3", "2-4" and "2–4" (or an em dash) alike: ranges expand, so a group cell never loses a phase. */
|
||||
function phaseList(cell) {
|
||||
const outList = [];
|
||||
for (const part of cell.match(/\d+\s*[-–\u2014]\s*\d+|\d+/g) || []) {
|
||||
const r = part.match(/^(\d+)\s*[-–\u2014]\s*(\d+)$/);
|
||||
if (r && Number(r[2]) >= Number(r[1]) && Number(r[2]) - Number(r[1]) < 100) {
|
||||
for (let n = Number(r[1]); n <= Number(r[2]); n++) outList.push(n);
|
||||
} else outList.push(...part.match(/\d+/g).map(Number));
|
||||
}
|
||||
return [...new Set(outList)];
|
||||
}
|
||||
|
||||
/** Parallel Execution Groups table: real groups only (a named group with 2+ phases). */
|
||||
function parseGroups(overview) {
|
||||
const sec = section(overview, /Parallel Execution Groups/i);
|
||||
if (!sec) return { found: false, groups: [] };
|
||||
const groups = [];
|
||||
const seen = new Set();
|
||||
for (const line of sec.lines) {
|
||||
if (!/^\s*\|/.test(line) || /^\s*\|[\s:|-]+\|\s*$/.test(line)) continue;
|
||||
const cells = line.split("|").slice(1, -1).map((c) => c.trim());
|
||||
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
|
||||
// ("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;
|
||||
const key = `${id}:${phases.join(",")}`;
|
||||
if (seen.has(key)) continue;
|
||||
seen.add(key);
|
||||
groups.push({ id, phases, reason: plainText(cells[2] || "") });
|
||||
}
|
||||
return { found: true, groups };
|
||||
}
|
||||
|
||||
function firstSentence(text) {
|
||||
const t = plainText(text);
|
||||
const m = t.match(/^(.+?[.!?])(\s|$)/);
|
||||
return (m ? m[1] : t).slice(0, 240);
|
||||
}
|
||||
|
||||
function parsePhaseFile(file, number) {
|
||||
const text = readText(file) || "";
|
||||
const lines = text.split(/\r?\n/);
|
||||
const title = (lines.find((l) => /^#\s/.test(l)) || "").replace(/^#\s+/, "").trim();
|
||||
const status = statusOf(text);
|
||||
const counts = { pending: 0, "in-progress": 0, complete: 0, blocked: 0, assumed: 0, unknown: 0 };
|
||||
const tasks = [];
|
||||
const strayCheckboxes = [];
|
||||
const unmatchedTasks = [];
|
||||
let heading = "";
|
||||
lines.forEach((line, i) => {
|
||||
const h = line.match(/^#{1,6}\s+(.*)$/);
|
||||
if (h) heading = plainText(h[1]);
|
||||
const t = line.match(TASK_RE);
|
||||
if (t) {
|
||||
const state = MARKERS[t[1]] || "unknown";
|
||||
counts[state]++;
|
||||
const named = !/^\d+$/.test(t[3]);
|
||||
tasks.push({ id: `${t[2]}.${t[3]}${t[4]}`, phase: Number(t[2]), seq: named ? null : Number(t[3]), named, suffix: t[4], marker: t[1], state, line: i + 1 });
|
||||
return;
|
||||
}
|
||||
// A line that looks like a task but is not counted as one (Task 1.4A,
|
||||
// "1. [ ] **Task", a non-bold "- [ ] Task 1.3") would make the audit undercount.
|
||||
if (/^\s*(?:[-*]|\d+\.)\s+\[.\].*\bTask\s+\d+\./i.test(line)) unmatchedTasks.push({ line: i + 1, text: line.trim().slice(0, 120) });
|
||||
if (CHECKBOX_RE.test(line)) strayCheckboxes.push({ line: i + 1, section: heading, text: line.trim().slice(0, 120) });
|
||||
});
|
||||
|
||||
// Numbering: every task belongs to this phase, the base numbers run 1..n with
|
||||
// no gaps or repeats, and a lettered task (3.6a) sits after its base (3.6).
|
||||
// Named tasks (1.T) are outside the numeric sequence.
|
||||
const numbering = [];
|
||||
const bases = [];
|
||||
for (const t of tasks) {
|
||||
if (t.phase !== number) numbering.push(`Task ${t.id} is in phase-${number}.md but numbered for Phase ${t.phase}`);
|
||||
if (!t.suffix && !t.named) bases.push(t.seq);
|
||||
}
|
||||
const seenIds = new Set();
|
||||
for (const t of tasks) {
|
||||
if (seenIds.has(t.id)) numbering.push(`Task ${t.id} appears more than once`);
|
||||
seenIds.add(t.id);
|
||||
if (t.suffix && !t.named && !bases.includes(t.seq)) numbering.push(`Task ${t.id} has no base Task ${t.phase}.${t.seq}`);
|
||||
}
|
||||
bases.forEach((seq, i) => {
|
||||
if (seq !== i + 1 && !numbering.some((n) => n.startsWith("Task numbering"))) {
|
||||
numbering.push(`Task numbering is not sequential: expected ${number}.${i + 1}, found ${number}.${seq}`);
|
||||
}
|
||||
});
|
||||
|
||||
const overviewSec = section(text, /^#{1,6}\s+Overview\b/i);
|
||||
const goalText = overviewSec ? overviewSec.lines.join("\n").split(/\n\s*\n/).map((p) => p.trim()).find((p) => p && !/^[-*|>]/.test(p)) : "";
|
||||
return {
|
||||
title,
|
||||
status,
|
||||
goal: goalText ? firstSentence(goalText) : null,
|
||||
total: tasks.length,
|
||||
counts,
|
||||
open: counts.pending + counts["in-progress"] + counts.blocked + counts.unknown,
|
||||
// Open work a phase cannot be approved over; blocked tasks may stand ([!] is allowed at sign-off).
|
||||
unfinished: counts.pending + counts["in-progress"] + counts.unknown,
|
||||
tasks,
|
||||
numbering,
|
||||
strayCheckboxes,
|
||||
unmatchedTasks,
|
||||
};
|
||||
}
|
||||
|
||||
function planDrafts(dir) {
|
||||
return fs
|
||||
.readdirSync(dir)
|
||||
.filter((n) => /^PLAN-DRAFT.*\.md$/i.test(n))
|
||||
.sort()
|
||||
.map((file) => ({
|
||||
file,
|
||||
archived: /-prev\.md$/i.test(file),
|
||||
status: statusOf(readText(path.join(dir, file))),
|
||||
}));
|
||||
}
|
||||
|
||||
/* ---------------------------------------------------------------- status */
|
||||
|
||||
function specStatus(spec) {
|
||||
const overviewPath = path.join(spec.dir, "overview.md");
|
||||
const overview = readText(overviewPath);
|
||||
const files = phaseFiles(spec.dir);
|
||||
// An empty overview.md still exists; only a missing one is "no overview".
|
||||
const hasOverview = overview !== null;
|
||||
const checklist = hasOverview ? parseChecklist(overview) : { found: false, phases: [], unparsed: [] };
|
||||
const groups = hasOverview ? parseGroups(overview) : { found: false, groups: [] };
|
||||
const checks = [];
|
||||
const check = (level, code, message) => checks.push({ level, code, message });
|
||||
for (const [n, names] of files.extra) {
|
||||
check("warn", "duplicate-phase-file", `Phase ${n} has more than one file: using ${files.get(n)}, ignoring ${names.join(", ")}`);
|
||||
}
|
||||
const rowsByNumber = new Map();
|
||||
for (const r of checklist.phases) rowsByNumber.set(r.number, [...(rowsByNumber.get(r.number) || []), r]);
|
||||
for (const [n, rows] of rowsByNumber) {
|
||||
if (rows.length > 1) check("error", "duplicate-checklist-row", `Phase ${n} has ${rows.length} rows in the Phase Checklist (overview.md lines ${rows.map((r) => r.line).join(", ")}); the first one is used`);
|
||||
}
|
||||
|
||||
const phases = [];
|
||||
const numbers = new Set([...checklist.phases.map((p) => p.number), ...files.keys()]);
|
||||
for (const number of [...numbers].sort((a, b) => a - b)) {
|
||||
const row = checklist.phases.find((p) => p.number === number) || null;
|
||||
const file = files.get(number) || null;
|
||||
const parsed = file ? parsePhaseFile(path.join(spec.dir, file), number) : null;
|
||||
phases.push({
|
||||
number,
|
||||
name: row ? row.name : parsed ? parsed.title.replace(/^Phase\s+\d+\s*[:\-–—]?\s*/i, "") : `Phase ${number}`,
|
||||
checklist: row ? row.state : null,
|
||||
marker: row ? row.marker : null,
|
||||
file,
|
||||
status: parsed ? parsed.status : null,
|
||||
goal: parsed ? parsed.goal : null,
|
||||
tasks: parsed ? { total: parsed.total, open: parsed.open, ...parsed.counts } : null,
|
||||
blockedTasks: parsed ? parsed.tasks.filter((t) => t.state === "blocked").map((t) => t.id) : [],
|
||||
assumedTasks: parsed ? parsed.tasks.filter((t) => t.state === "assumed").map((t) => t.id) : [],
|
||||
openTasks: parsed ? parsed.tasks.filter((t) => ["pending", "in-progress", "blocked", "unknown"].includes(t.state)).map((t) => t.id) : [],
|
||||
});
|
||||
if (!row && hasOverview) check("error", "missing-checklist-row", `phase-${number}.md has no row in overview.md's Phase Checklist`);
|
||||
if (row && !file) check("error", "missing-phase-file", `Phase Checklist lists Phase ${number} but there is no phase-${number}.md`);
|
||||
if (parsed) {
|
||||
for (const n of parsed.numbering) check("error", "task-numbering", `phase-${number}.md: ${n}`);
|
||||
// Prerequisites and criteria are plain bullets by rule; other checkbox
|
||||
// blocks (a Phase Testing list) are the template's own and are not tasks.
|
||||
for (const s of parsed.strayCheckboxes.filter((c) => /prerequisite|criteria/i.test(c.section))) {
|
||||
check("warn", "criteria-checkbox", `phase-${number}.md:${s.line} is a checkbox under "${s.section}"; prerequisites and criteria use plain bullets`);
|
||||
}
|
||||
if (parsed.total === 0) check("warn", "no-tasks", `phase-${number}.md has no **Task ${number}.N:** checkbox lines`);
|
||||
for (const u of parsed.unmatchedTasks) {
|
||||
check("warn", "uncounted-task", `phase-${number}.md:${u.line} looks like a task but is not counted (a task line is "- [ ] **Task ${number}.N:**"): ${u.text}`);
|
||||
}
|
||||
const done = parsed.counts.complete + parsed.counts.assumed;
|
||||
const rowDone = row && (row.state === "complete" || row.state === "assumed");
|
||||
// A phase may be approved with blocked [!] tasks left (Implementation
|
||||
// Mode's self-review allows "[x] or blocked [!]"); only unfinished work is an error.
|
||||
if (rowDone && parsed.unfinished > 0) {
|
||||
check("error", "checked-with-open-tasks", `Phase ${number} is [${row.marker}] in overview.md but ${parsed.unfinished} task(s) are not done (${phases.at(-1).openTasks.filter((id) => !phases.at(-1).blockedTasks.includes(id)).join(", ")})`);
|
||||
} else if (rowDone && parsed.counts.blocked > 0) {
|
||||
check("info", "approved-with-blocked", `Phase ${number} is [${row.marker}] with ${parsed.counts.blocked} blocked task(s) (${phases.at(-1).blockedTasks.join(", ")})`);
|
||||
}
|
||||
if (row && row.state === "pending" && parsed.total > 0 && done > 0) {
|
||||
// Done tasks under a [ ] phase with work still open is what a re-opened
|
||||
// phase looks like (revise-plan); with nothing open it is a missed mark.
|
||||
if (parsed.unfinished > 0) check("info", "partly-done-unchecked", `Phase ${number} is [ ] with ${done} task(s) done and ${parsed.unfinished} open (normal for a re-opened phase)`);
|
||||
else check("warn", "unchecked-with-done-tasks", `Phase ${number} is [ ] in overview.md but all ${done} unblocked task(s) are done`);
|
||||
}
|
||||
if (row && !rowDone && row.state !== "pending" && parsed.total > 0 && parsed.unfinished === 0) {
|
||||
check("info", "done-not-approved", `Phase ${number}: every task is done but overview.md still shows [${row.marker}] (normal until the user approves the phase)`);
|
||||
}
|
||||
}
|
||||
}
|
||||
if (!hasOverview) check("error", "no-overview", `${spec.rel} has no overview.md`);
|
||||
else if (!checklist.found) check("error", "no-checklist", "overview.md has no ## Phase Checklist section");
|
||||
for (const u of checklist.unparsed) check("warn", "unparsed-checklist-row", `overview.md:${u.line} is a checkbox in the Phase Checklist with no "Phase N" in it: ${u.text}`);
|
||||
for (const g of groups.groups) {
|
||||
for (const n of g.phases) if (!numbers.has(n)) check("error", "group-unknown-phase", `Parallel group ${g.id} names Phase ${n}, which does not exist`);
|
||||
}
|
||||
|
||||
// Totals. Completed = [x] plus [?] (assumed complete); [?] is reported on its own too.
|
||||
// Incomplete = [ ] + [/] (+ unreadable markers); Blocked is its own column.
|
||||
const totals = { total: 0, complete: 0, assumed: 0, pending: 0, "in-progress": 0, blocked: 0, unknown: 0 };
|
||||
for (const p of phases) if (p.tasks) for (const k of Object.keys(totals)) totals[k] += p.tasks[k] || 0;
|
||||
const completed = totals.complete + totals.assumed;
|
||||
const completion = totals.total ? completed / totals.total : null;
|
||||
|
||||
return {
|
||||
ok: true,
|
||||
spec: spec.rel,
|
||||
name: spec.name,
|
||||
overview: hasOverview ? "overview.md" : null,
|
||||
planDrafts: planDrafts(spec.dir),
|
||||
phases,
|
||||
parallelGroups: groups.groups,
|
||||
totals: { ...totals, completed, incomplete: totals.pending + totals["in-progress"] + totals.unknown },
|
||||
completion: completion === null ? null : Number(completion.toFixed(4)),
|
||||
completionPercent: completion === null ? null : Math.round(completion * 100),
|
||||
next: nextPhase(phases, groups.groups, checklist.found),
|
||||
pending: phases
|
||||
.filter((p) => p.checklist && p.checklist !== "complete" && p.checklist !== "assumed")
|
||||
.map((p) => ({ number: p.number, name: p.name, state: p.checklist, tasks: p.tasks ? p.tasks.total : null, open: p.tasks ? p.tasks.open : null, goal: p.goal })),
|
||||
checks,
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Implementation Mode's phase-selection table, applied mechanically.
|
||||
* 2+ workable phases in the same parallel group, consecutive -> choose (warn if all [/])
|
||||
* a single [/] -> ask-resume · a single [ ] -> auto-start · nothing workable -> none
|
||||
*/
|
||||
function nextPhase(phases, groups, haveChecklist) {
|
||||
if (!haveChecklist) return { action: "none", reason: "no Phase Checklist in overview.md" };
|
||||
const ordered = phases.filter((p) => p.checklist);
|
||||
const isDone = (p) => p.checklist === "complete" || p.checklist === "assumed";
|
||||
const workable = ordered.filter((p) => p.checklist === "pending" || p.checklist === "in-progress");
|
||||
if (!workable.length) {
|
||||
return { action: "none", reason: ordered.length && ordered.every(isDone) ? "every phase is complete" : "no [ ] or [/] phase in the Phase Checklist" };
|
||||
}
|
||||
const first = workable[0];
|
||||
const brief = (p) => ({ number: p.number, name: p.name, state: p.checklist, tasks: p.tasks ? p.tasks.total : null });
|
||||
// A blocked [!] phase ahead of the pick is skipped, but never silently.
|
||||
const skipped = ordered.slice(0, ordered.indexOf(first)).filter((p) => !isDone(p)).map(brief);
|
||||
const note = skipped.length ? { skipped, warning: `skipping ${skipped.map((p) => `Phase ${p.number} [${p.state}]`).join(", ")} ahead of it` } : {};
|
||||
const group = groups.find((g) => g.phases.includes(first.number));
|
||||
if (group) {
|
||||
// Consecutive same-group incomplete phases, in checklist order, starting at the first workable one.
|
||||
const run = [];
|
||||
for (const p of ordered.slice(ordered.indexOf(first))) {
|
||||
if (!group.phases.includes(p.number)) break;
|
||||
if (isDone(p)) continue;
|
||||
if (p.checklist === "pending" || p.checklist === "in-progress") run.push(p);
|
||||
else break;
|
||||
}
|
||||
if (run.length >= 2) {
|
||||
const allStarted = run.every((p) => p.checklist === "in-progress");
|
||||
const warnings = [
|
||||
...(allStarted ? ["every option is already [/]: another agent may be working on it, so picking one risks duplicated work"] : []),
|
||||
...(note.warning ? [note.warning] : []),
|
||||
];
|
||||
return {
|
||||
action: "choose",
|
||||
group: group.id,
|
||||
options: run.map(brief),
|
||||
...(note.skipped ? { skipped: note.skipped } : {}),
|
||||
...(warnings.length ? { warning: warnings.join("; ") } : {}),
|
||||
};
|
||||
}
|
||||
}
|
||||
return { action: first.checklist === "in-progress" ? "ask-resume" : "auto-start", phase: brief(first), ...note };
|
||||
}
|
||||
|
||||
/* --------------------------------------------------------------- commands */
|
||||
|
||||
async function cmdList(args) {
|
||||
const root = path.resolve(args.root || ".");
|
||||
const { scanProject } = await consoleLib();
|
||||
const scan = scanProject(root);
|
||||
const specs = scan.specs.map((s) => {
|
||||
const dir = path.join(root, s.dir);
|
||||
let names = [];
|
||||
try {
|
||||
names = fs.readdirSync(dir);
|
||||
} catch {}
|
||||
return {
|
||||
dir: s.dir,
|
||||
name: s.name,
|
||||
state: s.state,
|
||||
detail: s.detail,
|
||||
touched: s.touched ? new Date(s.touched).toISOString() : null,
|
||||
planDrafts: planDrafts(dir),
|
||||
overview: names.includes("overview.md"),
|
||||
phaseFiles: names.filter((n) => /^phase-\d+\b.*\.md$/i.test(n)).length,
|
||||
pathfinder: isDir(path.join(dir, "pathfinder")),
|
||||
};
|
||||
});
|
||||
let completed = [];
|
||||
try {
|
||||
completed = fs.readdirSync(path.join(root, "specs--completed")).filter((n) => isDir(path.join(root, "specs--completed", n))).sort();
|
||||
} catch {}
|
||||
out({
|
||||
ok: true,
|
||||
root,
|
||||
hasAgents: scan.hasAgents,
|
||||
specsDir: isDir(path.join(root, "specs")),
|
||||
specs,
|
||||
completed,
|
||||
...(specs.length ? {} : { note: "No active specs under specs/." }),
|
||||
});
|
||||
}
|
||||
|
||||
async function cmdStatus(args) {
|
||||
const root = path.resolve(args.root || ".");
|
||||
out(specStatus(resolveSpec(root, args._[1], { allowArchived: true })));
|
||||
}
|
||||
|
||||
function countVerificationAdded(dir) {
|
||||
let n = 0;
|
||||
for (const name of fs.readdirSync(dir)) {
|
||||
if (!/\.md$/i.test(name) || /^PLAN-/i.test(name)) continue;
|
||||
n += ((readText(path.join(dir, name)) || "").match(/<!--\s*VERIFICATION:\s*Added\b/gi) || []).length;
|
||||
}
|
||||
return n;
|
||||
}
|
||||
|
||||
async function cmdMetrics(args) {
|
||||
const root = path.resolve(args.root || ".");
|
||||
const spec = resolveSpec(root, args._[1], { allowArchived: true });
|
||||
const step = args.step;
|
||||
if (step !== "document" && step !== "finalize") fail(EXIT.USAGE, "bad-step", "--step must be document or finalize.", "Plan's METRICS_JSON is written by hand in its Phase 7.");
|
||||
const sets = {};
|
||||
for (const kv of args.set || []) {
|
||||
const m = kv.match(/^([a-z_]+)=(-?\d+(?:\.\d+)?)$/);
|
||||
if (!m) fail(EXIT.USAGE, "bad-set", `--set ${kv} is not key=number.`, "Example: --set verification_failures_found=1");
|
||||
sets[m[1]] = Number(m[2]);
|
||||
}
|
||||
// --set supplies the judgment fields only; the computed ones are never overridden.
|
||||
const SETTABLE = { document: ["verification_items_added"], finalize: ["verification_failures_found", "documentation_updates_needed"] };
|
||||
for (const k of Object.keys(sets)) {
|
||||
if (!SETTABLE[step].includes(k)) fail(EXIT.USAGE, "bad-set", `--set ${k} is not a field you supply for --step ${step}.`, `Only ${SETTABLE[step].join(", ")}; the rest is computed from the files.`);
|
||||
}
|
||||
const st = specStatus(spec);
|
||||
const withTasks = st.phases.filter((p) => p.tasks);
|
||||
let metrics;
|
||||
let hint;
|
||||
if (step === "document") {
|
||||
// verification_items_added is the Added total of the Verification Summary
|
||||
// you presented, not something the files record, so it comes from --set.
|
||||
// The <!-- VERIFICATION: Added --> comments are a cross-check only.
|
||||
if (!("verification_items_added" in sets)) fail(EXIT.USAGE, "missing-set", "document needs --set verification_items_added=N (the Added column total of your Verification Summary).", `The spec has ${countVerificationAdded(spec.dir)} <!-- VERIFICATION: Added --> comment(s), as a cross-check.`);
|
||||
metrics = {
|
||||
step: "document",
|
||||
total_tasks: st.totals.total,
|
||||
tasks_per_phase: withTasks.map((p) => p.tasks.total),
|
||||
phase_count: st.phases.length,
|
||||
parallel_groups_identified: st.parallelGroups.length,
|
||||
...sets,
|
||||
};
|
||||
hint = { verificationCommentsFound: countVerificationAdded(spec.dir) };
|
||||
} else {
|
||||
const missing = ["verification_failures_found", "documentation_updates_needed"].filter((k) => !(k in sets));
|
||||
if (missing.length) fail(EXIT.USAGE, "missing-set", `finalize needs ${missing.map((k) => `--set ${k}=N`).join(" and ")}.`, "Those two counts are your judgment from Steps 2 and 4.");
|
||||
metrics = {
|
||||
step: "finalize",
|
||||
completion_rate_at_audit: st.completion === null ? 0 : Number(st.completion.toFixed(2)),
|
||||
tasks_completed: st.totals.completed,
|
||||
tasks_total: st.totals.total,
|
||||
...sets,
|
||||
};
|
||||
}
|
||||
out({ ok: true, spec: spec.rel, metrics, comment: `<!-- METRICS_JSON ${spacedJson(metrics)} -->`, ...(hint || {}), checks: st.checks.filter((c) => c.level === "error") });
|
||||
}
|
||||
|
||||
// The house style of every METRICS_JSON comment: {"key": value, "list": [1, 2]}.
|
||||
function spacedJson(obj) {
|
||||
const v = (x) => (Array.isArray(x) ? `[${x.map(v).join(", ")}]` : x && typeof x === "object" ? spacedJson(x) : JSON.stringify(x));
|
||||
return `{${Object.entries(obj).map(([k, x]) => `${JSON.stringify(k)}: ${v(x)}`).join(", ")}}`;
|
||||
}
|
||||
|
||||
const TO = { open: " ", "in-progress": "/", done: "x" };
|
||||
|
||||
async function cmdMark(args) {
|
||||
const root = path.resolve(args.root || ".");
|
||||
const spec = resolveSpec(root, args._[1]);
|
||||
const number = Number(args.phase);
|
||||
if (!Number.isInteger(number) || number < 0) fail(EXIT.USAGE, "bad-phase", "--phase needs a phase number.", "Example: --phase 2");
|
||||
if (!(args.to in TO)) fail(EXIT.USAGE, "bad-to", "--to must be open, in-progress or done.", "open = [ ], in-progress = [/], done = [x]");
|
||||
const overviewPath = path.join(spec.dir, "overview.md");
|
||||
const overview = readText(overviewPath);
|
||||
if (overview === null) fail(EXIT.NOT_FOUND, "no-overview", `${spec.rel} has no overview.md.`, "Run /plan2code-2-document first.");
|
||||
const checklist = parseChecklist(overview);
|
||||
const rows = checklist.phases.filter((p) => p.number === number);
|
||||
const row = rows[0];
|
||||
if (!row) fail(EXIT.NOT_FOUND, "no-row", `overview.md's Phase Checklist has no row for Phase ${number}.`, "Run `specs.mjs status` to see the phases it lists.");
|
||||
if (rows.length > 1) fail(EXIT.REFUSED, "duplicate-row", `Phase ${number} has ${rows.length} rows in the Phase Checklist (lines ${rows.map((r) => r.line).join(", ")}); marking one would be a guess.`, "Remove the duplicate row, then rerun.");
|
||||
const target = TO[args.to];
|
||||
if (row.marker === "/" && target === " ") {
|
||||
fail(EXIT.REFUSED, "no-reset", `Phase ${number} is [/]; started work is never reset to [ ].`, "Leave it [/] (a later session resumes it), or mark it done once approved.");
|
||||
}
|
||||
const changes = [];
|
||||
const lines = overview.split(/\r?\n/);
|
||||
const idx = row.line - 1;
|
||||
const next = lines[idx].replace(/\[(.)\]/, `[${target}]`);
|
||||
if (next !== lines[idx]) {
|
||||
lines[idx] = next;
|
||||
changes.push({ file: `${spec.rel}/overview.md`, line: row.line, from: `[${row.marker}]`, to: `[${target}]` });
|
||||
}
|
||||
// The phase file's Status line follows: done -> Complete; re-opening a Complete
|
||||
// phase -> In Progress (revise-plan), so the two files never disagree.
|
||||
let phaseText = null;
|
||||
let phasePath = null;
|
||||
let unfinished = [];
|
||||
const warnings = [];
|
||||
const file = phaseFiles(spec.dir).get(number);
|
||||
if (file) {
|
||||
phasePath = path.join(spec.dir, file);
|
||||
const text = readText(phasePath) || "";
|
||||
const parsed = parsePhaseFile(phasePath, number);
|
||||
unfinished = parsed.tasks.filter((t) => ["pending", "in-progress", "unknown"].includes(t.state)).map((t) => t.id);
|
||||
const status = statusOf(text);
|
||||
const want = target === "x" ? "Complete" : target === " " && status && /^complete$/i.test(status) ? "In Progress" : null;
|
||||
if (status && want && status !== want) {
|
||||
phaseText = text.replace(STATUS_RE, (_, before, _value, after) => before + want + after);
|
||||
changes.push({ file: `${spec.rel}/${file}`, field: "Status", from: status, to: want });
|
||||
}
|
||||
// done and open keep the Status line in step; with none to find, say so.
|
||||
if (!status && target !== "/") warnings.push(`${file} has no Status line, so only the Phase Checklist checkbox changed; add a "**Status:** <value>" line under its title.`);
|
||||
}
|
||||
if (!args["dry-run"]) {
|
||||
if (changes.some((c) => c.file.endsWith("overview.md"))) fs.writeFileSync(overviewPath, lines.join(eol(overview)));
|
||||
if (phaseText !== null) fs.writeFileSync(phasePath, phaseText);
|
||||
}
|
||||
const doneEarly = target === "x" && unfinished.length > 0;
|
||||
if (doneEarly) warnings.unshift(`Phase ${number} was marked done with ${unfinished.length} unfinished task(s): ${unfinished.join(", ")}. Mark only a phase the user approved.`);
|
||||
out({
|
||||
ok: true,
|
||||
spec: spec.rel,
|
||||
phase: number,
|
||||
name: row.name,
|
||||
dryRun: !!args["dry-run"],
|
||||
changed: changes.length > 0,
|
||||
changes,
|
||||
...(warnings.length ? { warning: warnings.join(" ") } : {}),
|
||||
...(doneEarly ? { unfinished } : {}),
|
||||
});
|
||||
}
|
||||
|
||||
function listRel(dir, base = dir) {
|
||||
const outList = [];
|
||||
for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
|
||||
const p = path.join(dir, e.name);
|
||||
if (e.isDirectory()) outList.push(...listRel(p, base));
|
||||
else outList.push(rel(base, p));
|
||||
}
|
||||
return outList.sort();
|
||||
}
|
||||
|
||||
async function cmdArchive(args) {
|
||||
const root = path.resolve(args.root || ".");
|
||||
const spec = resolveSpec(root, args._[1]);
|
||||
const target = path.join(root, "specs--completed", spec.name);
|
||||
if (fs.existsSync(target)) {
|
||||
fail(EXIT.REFUSED, "target-exists", `specs--completed/${spec.name}/ already exists; nothing was moved.`, "Ask the user whether to merge by hand or archive under another name.");
|
||||
}
|
||||
const files = listRel(spec.dir);
|
||||
if (!args["dry-run"]) {
|
||||
fs.mkdirSync(path.dirname(target), { recursive: true });
|
||||
try {
|
||||
fs.renameSync(spec.dir, target);
|
||||
} catch (err) {
|
||||
// A rename across volumes (or a locked file on Windows) fails; copy then remove.
|
||||
try {
|
||||
fs.cpSync(spec.dir, target, { recursive: true, errorOnExist: true, force: false });
|
||||
} catch (copyErr) {
|
||||
fail(EXIT.INVALID, "archive-failed", `Could not move or copy ${spec.rel} (${err.code || err.message}; copy: ${copyErr.code || copyErr.message}).`, `Close anything holding files in ${spec.rel} open, check specs--completed/${spec.name} for a partial copy, then rerun.`);
|
||||
}
|
||||
try {
|
||||
fs.rmSync(spec.dir, { recursive: true, force: true });
|
||||
} catch (rmErr) {
|
||||
fail(EXIT.INVALID, "source-not-removed", `Copied to specs--completed/${spec.name}/ but could not remove ${spec.rel} (${rmErr.code || rmErr.message}); both copies now exist.`, `Close whatever holds files in ${spec.rel} open, then delete it by hand. The archive is complete.`);
|
||||
}
|
||||
}
|
||||
}
|
||||
const sourceGone = args["dry-run"] ? null : !fs.existsSync(spec.dir);
|
||||
const moved = args["dry-run"] ? null : listRel(target);
|
||||
if (!args["dry-run"] && !(sourceGone && moved.length === files.length)) {
|
||||
fail(
|
||||
EXIT.INVALID,
|
||||
"archive-unverified",
|
||||
`The move of ${spec.rel} to specs--completed/${spec.name}/ did not verify: ${moved.length} of ${files.length} file(s) at the target, and ${spec.rel} ${sourceGone ? "is gone" : "still exists"}.`,
|
||||
`Compare ${spec.rel} with specs--completed/${spec.name}/ and finish the move by hand; archive refuses to rerun while the target exists.`
|
||||
);
|
||||
}
|
||||
out({
|
||||
ok: true,
|
||||
dryRun: !!args["dry-run"],
|
||||
from: spec.rel,
|
||||
to: `specs--completed/${spec.name}`,
|
||||
files,
|
||||
...(args["dry-run"] ? {} : { sourceRemoved: sourceGone, filesAtTarget: moved.length, archivedOn: isoDate() }),
|
||||
});
|
||||
}
|
||||
|
||||
run(USAGE, async (argv) => {
|
||||
const args = parseArgs(argv, { booleans: ["dry-run"], values: ["root", "step", "phase", "to"], lists: ["set"] });
|
||||
const cmd = args._[0];
|
||||
const commands = { list: cmdList, status: cmdStatus, metrics: cmdMetrics, mark: cmdMark, archive: cmdArchive };
|
||||
if (!commands[cmd]) fail(EXIT.USAGE, "unknown-command", cmd ? `Unknown command "${cmd}".` : "No command given.", "Commands: list, status, metrics, mark, archive. Run with --help.");
|
||||
await commands[cmd](args);
|
||||
});
|
||||
@@ -0,0 +1,22 @@
|
||||
{
|
||||
"name": "Plan2Code",
|
||||
"version": "2.4.1",
|
||||
"description": "A structured 4-step workflow methodology for AI-assisted software development",
|
||||
"keywords": [
|
||||
"ai",
|
||||
"workflow",
|
||||
"development",
|
||||
"planning",
|
||||
"implementation",
|
||||
"plan"
|
||||
],
|
||||
"author": "Justin Parker",
|
||||
"license": "MIT",
|
||||
"repository": {
|
||||
"type": "git",
|
||||
"url": "https://github.com/jparkerweb/plan2code"
|
||||
},
|
||||
"homepage": "https://github.com/jparkerweb/plan2code",
|
||||
"releaseDate": "2026-10-04",
|
||||
"mode": "utility"
|
||||
}
|
||||
@@ -29,11 +29,17 @@ The FIRST thing you do, before anything else in this file — before Step 1, bef
|
||||
- **Question options:** Never offer 'execute', 'implement', or any execution-shaped synonym. Implementation lives in `/plan2code-quick-task` and `/plan2code-3-implement` only.
|
||||
- **Web console exception:** the console's temporary payload files (outside the repo, in the session folder `open` prints) are the one allowed write outside `specs/`. They are messages to the page, never project files.
|
||||
|
||||
## Scripts
|
||||
|
||||
`<S>` is `scripts/` beside this SKILL.md (`~/.agents/skills/plan2code-1b-revise-plan/scripts/` globally). Run from the project root; each prints one JSON object, and on a non-zero exit `next` says what to do. They only ever touch `specs/`.
|
||||
|
||||
- `node "<S>/specs.mjs" list`: the active specs (it reads gitignored `specs/`, where Glob silently finds nothing).
|
||||
- `node "<S>/specs.mjs" status <spec>`: phases, task counts by marker, `checks`, `pending`.
|
||||
- `node "<S>/specs.mjs" mark <spec> --phase <N> --to open`: re-open a completed phase in overview.md.
|
||||
|
||||
## Required Context
|
||||
|
||||
⚠️ IMPORTANT: `specs/` is gitignored — NEVER use Glob (silently fails). Shell only: `ls specs/` (Bash) or `Get-ChildItem specs/` (PS).
|
||||
|
||||
Request these files if not provided:
|
||||
Find the spec with `specs.mjs list`, then request these files if not provided:
|
||||
- `specs/<feature-name>/overview.md`
|
||||
- All `specs/<feature-name>/phase-X.md` files
|
||||
|
||||
@@ -89,13 +95,11 @@ Present findings and confirm understanding before continuing.
|
||||
1. [Change description]
|
||||
2. [Change description]
|
||||
|
||||
```
|
||||
⋅
|
||||
╭───╮
|
||||
│ ★ │╱
|
||||
╱│ ~ │ Here's the plan. What do you think?
|
||||
╰┬─┬╯
|
||||
```
|
||||
|
||||
Approve the spec-update plan? (approve / refine / abort). Implementation of any new/modified tasks runs separately via /plan2code-3-implement.
|
||||
```
|
||||
@@ -130,24 +134,21 @@ Approve the spec-update plan? (approve / refine / abort). Implementation of any
|
||||
- Added: [date]
|
||||
- Reason: [reason]
|
||||
```
|
||||
- Update overview.md: `[x]` → `[ ]`
|
||||
- Update overview.md: `[x]` → `[ ]` (`specs.mjs mark <spec> --phase <N> --to open`, which also sets that phase file's `**Status:**` back to In Progress)
|
||||
- Add comment: `<!-- Re-opened: [date] - [reason] -->`
|
||||
|
||||
### STEP 4: Consistency Check
|
||||
|
||||
`🔄 [REVISION] Step 4: Consistency Check`
|
||||
|
||||
Verify updated specs are consistent:
|
||||
Run `specs.mjs status <spec>`. Its `checks` cover the mechanical items: task numbers sequential (`task-numbering`), overview.md checklist matches the phase files (`missing-checklist-row`, `missing-phase-file`), incomplete phases unchecked and complete ones checked (`checked-with-open-tasks`, `unchecked-with-done-tasks`; `partly-done-unchecked` is the normal look of a phase you just re-opened). Then verify the rest yourself:
|
||||
|
||||
- [ ] Task numbers sequential
|
||||
- [ ] Phase dependencies valid
|
||||
- [ ] No orphaned references
|
||||
- [ ] Tech stack updated if needed
|
||||
- [ ] Success criteria achievable
|
||||
- [ ] overview.md checklist matches phase files
|
||||
- [ ] Incomplete phases unchecked, complete phases checked
|
||||
|
||||
Report and resolve issues before continuing.
|
||||
Report and resolve issues (every `error` in `checks` included), then rerun `status` before continuing.
|
||||
|
||||
### STEP 5: Summary
|
||||
|
||||
@@ -241,7 +242,7 @@ If user says "abort" or "cancel":
|
||||
|
||||
Work summary — tell user: change type, tasks added/modified/removed, phases re-opened (if any).
|
||||
|
||||
**Pending phases after revision** — read overview.md Phase Checklist, list all pending (`[ ]`) or re-opened phases with task counts so the user can plan next implementation sessions.
|
||||
**Pending phases after revision** — list `status`'s `pending` (every phase not `[x]`, re-opened ones included) with its task count so the user can plan next implementation sessions.
|
||||
|
||||
Returning context: Revised specs in `specs/<feature-name>/`. Run `/plan2code-3-implement --web` in a new conversation to continue implementation.
|
||||
|
||||
|
||||
@@ -556,8 +556,15 @@ enforces it, so never tell someone to keep asking past it.
|
||||
The person can add folders beside the one the session started in (a shared
|
||||
library, a design folder), from the footer's folder label. Together they are
|
||||
the session's **workspace**: context for every skill run in this console
|
||||
session, each folder addressed by a short `@name`. It outlives dashboard hops;
|
||||
a new console session starts with the original folder alone.
|
||||
session, each folder addressed by a short `@name`. It outlives dashboard hops,
|
||||
and it is remembered: every change is saved to `workspaces.json` beside
|
||||
`looks.json` (never into the project), keyed by the folder the session runs
|
||||
in and then by spec. A session with a spec opens on that spec's list, one with
|
||||
none on the project's; a spec with nothing saved starts as a copy of the
|
||||
project's list. The dashboard's picker swaps the list as the selection moves,
|
||||
and a `specDir` you post mid-run takes the current list with it. There is
|
||||
nothing for you to load: `open` prints the list, and a switch of spec on a
|
||||
resume reaches you as ordinary workspace changes on your next `wait`.
|
||||
|
||||
### What you are told
|
||||
|
||||
@@ -767,7 +774,7 @@ that is what the person is there to download. The finish carries no
|
||||
sees the Trail Footer, and without this their last screen promises a question
|
||||
that is never coming.
|
||||
- Post `run` `pathfinder-chart` (id `map`) when a new map is first written,
|
||||
and `pathfinder-research` (id = the question's file slug) as each research
|
||||
and `pathfinder-research` (id = the question's file slug; on `github`, `q<issue-number>`) as each research
|
||||
subagent reports back, or when you resolve a `research` question yourself
|
||||
(Posting an update → Session meter). Other questions score through their
|
||||
answers, so there is nothing to post for them.
|
||||
@@ -820,7 +827,7 @@ know:
|
||||
| 3, Implementation Summary | Written to `overview.md` as usual; mirror it as a doc (marked `saved`) so the page reader sees it land. |
|
||||
| 4, Documentation Review | The proposed-updates table as a doc, and a `multi` naming the documents to update — every option ticked is "approve", unticked ones are skipped. A `review` works instead when the set is all-or-nothing. |
|
||||
| 5, User Feedback | Optional items, `required: false`: the rating as a `choice` of 1 to 10 or a `text`, the three reasons as `text`. The submit-to-maintainer consent is a `confirm`. |
|
||||
| 6, Spec Cleanup | A `confirm` before moving anything, the archive paths in `consequences`. |
|
||||
| 6, Spec Cleanup | A `confirm` before moving anything, the archive paths in `consequences`, and a line that the spec's remembered workspace folders are forgotten too (`console.mjs forget --spec specs/<feature>` after the move). |
|
||||
|
||||
Pass `--spec specs/<feature>` to `open`, or post `specDir` once you know it.
|
||||
Stopping mid-finalize loses nothing
|
||||
|
||||
@@ -41,6 +41,7 @@ import {
|
||||
die,
|
||||
ensureDir,
|
||||
fileStamp,
|
||||
forgetWorkspace,
|
||||
handOff,
|
||||
handleFile,
|
||||
healthOk,
|
||||
@@ -65,6 +66,7 @@ import {
|
||||
readLedger,
|
||||
readWorkspace,
|
||||
reapHandles,
|
||||
rememberedWorkspace,
|
||||
remoteWarning,
|
||||
removeScratch,
|
||||
removeSessions,
|
||||
@@ -73,6 +75,7 @@ import {
|
||||
SESSION_MAX_AGE_MS,
|
||||
sessionDir,
|
||||
sleepSync,
|
||||
specKey,
|
||||
staleScratch,
|
||||
staleSessions,
|
||||
sweepUploads,
|
||||
@@ -317,7 +320,7 @@ async function cmdOpen() {
|
||||
if (launched) appendLedger(dir, { kind: "launch", id: nextLaunchId(readLedger(dir)), workflow: state.workflow });
|
||||
for (const line of ledgerFromPost(dir, openRun, openIssue, state.workflow)) appendLedger(dir, line);
|
||||
} catch {}
|
||||
const workspace = workspaceOnOpen(dir, worktree);
|
||||
const workspace = workspaceOnOpen(dir, worktree, state.specDir);
|
||||
|
||||
// Month-old sessions and scratch files: listed before the print so the
|
||||
// agent can see what went, removed after it so the page waits for nothing.
|
||||
@@ -403,10 +406,11 @@ async function cmdOpen() {
|
||||
* The workspace as `open` hands it to the agent, and the cursor seeded to
|
||||
* match: the agent now has the whole list, so no change up to here is owed.
|
||||
* Read-only on workspace.json, which only the server writes; on a fresh
|
||||
* session the server has not made it yet, so the original folder stands in.
|
||||
* session the server has not made it yet, so what was remembered for this
|
||||
* folder and spec stands in, the same list the server is about to make.
|
||||
*/
|
||||
function workspaceOnOpen(dir, worktree) {
|
||||
const ws = readWorkspace(dir) || initialWorkspace(worktree);
|
||||
function workspaceOnOpen(dir, worktree, specDir) {
|
||||
const ws = readWorkspace(dir) || initialWorkspace(worktree, rememberedWorkspace(worktree, specDir).entry);
|
||||
const missing = ws.folders.filter((f) => !isFolder(f.path)).map((f) => f.id);
|
||||
try {
|
||||
writeWorkspaceCursor(dir, ws.version || 0);
|
||||
@@ -946,6 +950,18 @@ function realNearest(p) {
|
||||
return path.join(fs.realpathSync(existing), path.relative(existing, p));
|
||||
}
|
||||
|
||||
/* --------------------------------------------------------------- forget */
|
||||
|
||||
// Drop the folder list remembered for one spec (Finalize, once the spec is
|
||||
// archived). The project's own list and every other spec's are untouched.
|
||||
function cmdForget() {
|
||||
if (typeof args.spec !== "string" || !args.spec.trim()) die("forget needs --spec specs/<idea>", 2);
|
||||
let spec = specKey(args.spec);
|
||||
if (/\.md$/i.test(spec)) spec = spec.slice(0, spec.lastIndexOf("/"));
|
||||
const worktree = repoRoots().worktree;
|
||||
print({ ok: true, spec, forgot: forgetWorkspace(worktree, spec) });
|
||||
}
|
||||
|
||||
/* ----------------------------------------------------------------- help */
|
||||
|
||||
function cmdHelp() {
|
||||
@@ -961,7 +977,8 @@ port, and the filesystem as transport; this CLI is the whole agent surface.
|
||||
first post. --file is optional, and --title defaults to the
|
||||
project's folder name. Also prints workspace: { folders: [{ name,
|
||||
path, description?, original? }], missing? }, the folders this
|
||||
console session reads as context, addressed as @name.
|
||||
console session reads as context, addressed as @name. The list is
|
||||
remembered per folder and spec in workspaces.json beside looks.json.
|
||||
post --session <sid> --file <patch.json>
|
||||
Merge a patch into the session. Prints terminalLine while the
|
||||
server is live. Exit 3 = rejected; stderr says why. A patch may
|
||||
@@ -988,6 +1005,10 @@ port, and the filesystem as transport; this CLI is the whole agent surface.
|
||||
Copy a cited note attachment into specs/<idea>/attachments/. Prints
|
||||
{ ok, path, link, image, reused }; exit 2 = bad usage, 3 = refused or
|
||||
missing. Paste link as it is.
|
||||
forget --spec specs/<idea>
|
||||
Drop the workspace folders remembered for that spec, in this
|
||||
folder (Finalize, after archiving it). Prints { ok, spec, forgot };
|
||||
forgot is false when nothing was saved. Exit 2 = bad usage.
|
||||
status [--session <sid>] [--all]
|
||||
One session, or every session belonging to this project.
|
||||
stop --session <sid> | --all
|
||||
@@ -1206,6 +1227,7 @@ const COMMANDS = {
|
||||
wait: cmdWait,
|
||||
chat: cmdChat,
|
||||
keep: cmdKeep,
|
||||
forget: cmdForget,
|
||||
status: cmdStatus,
|
||||
stop: cmdStop,
|
||||
help: cmdHelp,
|
||||
|
||||
@@ -178,8 +178,8 @@ function lockStale(lock) {
|
||||
// Run fn while holding the session's state lock, and release it however fn
|
||||
// ends. fn must not call process.exit(): the release would never run, and the
|
||||
// next writer would wait out the stale age.
|
||||
export function withStateLock(dir, fn) {
|
||||
const lock = path.join(dir, STATE_LOCK_FILE);
|
||||
export function withStateLock(dir, fn, lockName = STATE_LOCK_FILE) {
|
||||
const lock = path.join(dir, lockName);
|
||||
const deadline = Date.now() + LOCK_WAIT_MS;
|
||||
let fd = null;
|
||||
for (let attempt = 0; fd === null; attempt++) {
|
||||
@@ -188,7 +188,7 @@ export function withStateLock(dir, fn) {
|
||||
} catch (err) {
|
||||
// EPERM / EACCES: on Windows, a lock being deleted still blocks a create.
|
||||
if (!["EEXIST", "EPERM", "EACCES", "EBUSY"].includes(err.code)) throw err;
|
||||
if (Date.now() > deadline) throw new Error("state.json is busy with another writer; try again");
|
||||
if (Date.now() > deadline) throw new Error(`${lockName.replace(/.lock$/, "")} is busy with another writer; try again`);
|
||||
if (err.code === "EEXIST" && lockStale(lock)) {
|
||||
try {
|
||||
fs.rmSync(lock, { force: true });
|
||||
@@ -487,8 +487,9 @@ export async function removeSessions(sessionsDir, sids) {
|
||||
}
|
||||
|
||||
// The console folder's own files that no sweep may ever remove: the person's
|
||||
// looks and the pointer to this console's directory.
|
||||
export const PROTECTED_CONSOLE_FILES = new Set(["looks.json", "console-dir"]);
|
||||
// looks, the folders remembered per project and spec, and the pointer to
|
||||
// this console's directory.
|
||||
export const PROTECTED_CONSOLE_FILES = new Set(["looks.json", "workspaces.json", "console-dir"]);
|
||||
|
||||
function isScratchName(name) {
|
||||
return (
|
||||
@@ -1619,17 +1620,125 @@ export function readWorkspace(dir) {
|
||||
return readJson(path.join(dir, WORKSPACE_FILE), null);
|
||||
}
|
||||
|
||||
// A fresh workspace: just the original folder, named after itself.
|
||||
export function initialWorkspace(worktree) {
|
||||
// A fresh workspace: the original folder, named after itself, plus whatever
|
||||
// was remembered for this folder and spec (rememberedWorkspace() below).
|
||||
export function initialWorkspace(worktree, remembered = null) {
|
||||
const original = { id: "f0", path: worktree, name: defaultName(worktree), description: "", original: true };
|
||||
if (remembered && remembered.original) {
|
||||
if (remembered.original.name) original.name = remembered.original.name;
|
||||
if (remembered.original.description) original.description = remembered.original.description;
|
||||
}
|
||||
const added = ((remembered && remembered.folders) || []).map((f, i) => ({
|
||||
id: "f" + (i + 1),
|
||||
path: f.path,
|
||||
name: f.name,
|
||||
description: f.description || "",
|
||||
...(f.nested ? { nested: true } : {}),
|
||||
}));
|
||||
return { version: 0, folders: [original, ...added], missing: [], changes: [], remote: "" };
|
||||
}
|
||||
|
||||
/* ------------------------------------------------ remembered workspaces */
|
||||
|
||||
// The folder list outlives the console session: one file for the person,
|
||||
// beside looks.json, keyed by the folder a session runs in and then by spec.
|
||||
// Never under specs/: the paths are this machine's, and the server never
|
||||
// writes into a project.
|
||||
//
|
||||
// { "projects": { "<folded worktree>": {
|
||||
// "path": "<worktree>",
|
||||
// "project": { original, folders, at }, // no spec picked
|
||||
// "specs": { "specs/<name>": { original, folders, at } } } } }
|
||||
//
|
||||
// `original` holds the first folder's name and description only (its path is
|
||||
// always the session's own); `folders` the added ones as { path, name,
|
||||
// description, nested? }. Two writers, the server on every change and
|
||||
// `console.mjs forget`, each a read-modify-write of one key.
|
||||
export const WORKSPACES_FILE = path.join(HOME_DIR, "workspaces.json");
|
||||
|
||||
const foldKey = (p) => {
|
||||
const resolved = path.resolve(String(p || ""));
|
||||
return process.platform === "win32" || process.platform === "darwin" ? resolved.toLowerCase() : resolved;
|
||||
};
|
||||
|
||||
// `specs/<name>` with forward slashes and no trailing slash, or "" for none.
|
||||
export function specKey(specDir) {
|
||||
return String(specDir || "")
|
||||
.trim()
|
||||
.replace(/\\/g, "/")
|
||||
.replace(/^\.\//, "")
|
||||
.replace(/\/+$/, "");
|
||||
}
|
||||
|
||||
function readStore() {
|
||||
const saved = readJson(WORKSPACES_FILE, null);
|
||||
return saved && typeof saved.projects === "object" && saved.projects ? saved : { projects: {} };
|
||||
}
|
||||
|
||||
/**
|
||||
* What was remembered for this folder and spec: `{ entry, from }`, where
|
||||
* `from` is "spec" when the spec has its own list, "project" when it falls
|
||||
* back to the project's (a spec's list starts as a copy of it), and null
|
||||
* when nothing was ever saved.
|
||||
*/
|
||||
export function rememberedWorkspace(worktree, specDir) {
|
||||
const project = readStore().projects[foldKey(worktree)];
|
||||
if (!project) return { entry: null, from: null };
|
||||
const spec = specKey(specDir);
|
||||
if (spec && project.specs && project.specs[spec]) return { entry: project.specs[spec], from: "spec" };
|
||||
return project.project ? { entry: project.project, from: "project" } : { entry: null, from: null };
|
||||
}
|
||||
|
||||
// The workspace's folders as the store keeps them.
|
||||
export function rememberable(ws) {
|
||||
const folders = (ws && ws.folders) || [];
|
||||
const first = folders.find((f) => f.original) || {};
|
||||
return {
|
||||
version: 0,
|
||||
folders: [{ id: "f0", path: worktree, name: defaultName(worktree), description: "", original: true }],
|
||||
missing: [],
|
||||
changes: [],
|
||||
remote: "",
|
||||
original: { name: first.name || "", description: first.description || "" },
|
||||
folders: folders
|
||||
.filter((f) => !f.original)
|
||||
.map((f) => ({ path: f.path, name: f.name, description: f.description || "", ...(f.nested ? { nested: true } : {}) })),
|
||||
at: nowIso(),
|
||||
};
|
||||
}
|
||||
|
||||
// Every server and `console.mjs forget` writes the one file, so each
|
||||
// read-modify-write holds this lock beside it.
|
||||
const WORKSPACES_LOCK = "workspaces.json.lock";
|
||||
|
||||
// Save the list for this folder and spec ("" for the project's own).
|
||||
export function rememberWorkspace(worktree, specDir, ws) {
|
||||
ensureDir(path.dirname(WORKSPACES_FILE));
|
||||
withStateLock(path.dirname(WORKSPACES_FILE), () => saveRemembered(worktree, specDir, ws), WORKSPACES_LOCK);
|
||||
}
|
||||
|
||||
function saveRemembered(worktree, specDir, ws) {
|
||||
const store = readStore();
|
||||
const key = foldKey(worktree);
|
||||
const project = store.projects[key] || { path: path.resolve(worktree) };
|
||||
const spec = specKey(specDir);
|
||||
if (spec) project.specs = { ...(project.specs || {}), [spec]: rememberable(ws) };
|
||||
else project.project = rememberable(ws);
|
||||
store.projects[key] = project;
|
||||
writeJsonAtomic(WORKSPACES_FILE, store);
|
||||
}
|
||||
|
||||
// Drop one spec's list (Finalize, once the spec is archived). True when there was one.
|
||||
export function forgetWorkspace(worktree, specDir) {
|
||||
const spec = specKey(specDir);
|
||||
if (!spec || !fs.existsSync(WORKSPACES_FILE)) return false;
|
||||
return withStateLock(path.dirname(WORKSPACES_FILE), () => dropRemembered(worktree, spec), WORKSPACES_LOCK);
|
||||
}
|
||||
|
||||
function dropRemembered(worktree, spec) {
|
||||
const store = readStore();
|
||||
const project = store.projects[foldKey(worktree)];
|
||||
if (!spec || !project || !project.specs || !project.specs[spec]) return false;
|
||||
delete project.specs[spec];
|
||||
writeJsonAtomic(WORKSPACES_FILE, store);
|
||||
return true;
|
||||
}
|
||||
|
||||
// Single-writer rule: only server.mjs may call this.
|
||||
export function writeWorkspace(dir, ws) {
|
||||
return writeJsonAtomic(path.join(dir, WORKSPACE_FILE), ws);
|
||||
|
||||
@@ -2505,6 +2505,9 @@ a.icon-btn { box-sizing: border-box; text-decoration: none; }
|
||||
actions stay put. */
|
||||
.modal.workspace { max-width: 680px; }
|
||||
.modal.workspace[open] { display: flex; flex-direction: column; max-height: calc(100vh - 48px); }
|
||||
.workspace .modal-blurb { margin-bottom: 6px; }
|
||||
.workspace-scope { margin: 0 0 16px; color: var(--ink-3, var(--ink-2)); font-size: 12.5px; }
|
||||
|
||||
.workspace-list {
|
||||
list-style: none; margin: 0; padding: 0;
|
||||
display: grid; gap: 12px;
|
||||
|
||||
@@ -2542,6 +2542,7 @@ function renderDashboard(main) {
|
||||
const specs = specList();
|
||||
if (specs.length) wrap.appendChild(renderSpecPicker(specs));
|
||||
wrap.appendChild(hideUnavailableToggle());
|
||||
if (!local.launching && !launchScoping) 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
|
||||
@@ -2963,6 +2964,11 @@ async function launchSkill(entry) {
|
||||
// cards that take no spec (utilities, setup) launch untargeted even while
|
||||
// a spec is selected.
|
||||
if (target) action.spec = target.dir;
|
||||
// The skill opens on the folders remembered for what it was launched for.
|
||||
// Held until the launch is in flight: the swap's own frame re-renders the
|
||||
// dashboard, which would otherwise sync back to the picker's spec.
|
||||
launchScoping = true;
|
||||
await syncWorkspaceScope(target ? target.dir : "");
|
||||
try {
|
||||
const res = await fetch("/submit", {
|
||||
method: "POST",
|
||||
@@ -2973,6 +2979,7 @@ async function launchSkill(entry) {
|
||||
}),
|
||||
});
|
||||
if (res.status === 409) {
|
||||
launchScoping = false;
|
||||
pendingResult = true;
|
||||
banner("Your last pick is still being picked up. One moment.", "info");
|
||||
return;
|
||||
@@ -2980,10 +2987,12 @@ async function launchSkill(entry) {
|
||||
if (!res.ok) throw new Error(String(res.status));
|
||||
sound("startSkill");
|
||||
local.launching = { skill: entry.skill, title: entry.title, at: Date.now() };
|
||||
launchScoping = false;
|
||||
pendingResult = true;
|
||||
save();
|
||||
render();
|
||||
} catch {
|
||||
launchScoping = false;
|
||||
banner("That did not go through. Nothing was lost; try again.", "warn");
|
||||
}
|
||||
}
|
||||
@@ -5854,6 +5863,32 @@ async function postJson(url, body) {
|
||||
}
|
||||
}
|
||||
|
||||
/* The workspace follows the dashboard's picker: the folders remembered for
|
||||
the selected spec, or the project's own under "Start from scratch". The
|
||||
server swaps the list and remembers every change after it. */
|
||||
let scopeAsked = null;
|
||||
// True from a launch's scope sync until its send has gone (or failed).
|
||||
let launchScoping = false;
|
||||
async function syncWorkspaceScope(spec) {
|
||||
if (!S || S.workflow !== "dashboard" || gone || !wsFrame) return;
|
||||
const want = spec === undefined ? (selSpec() && selSpec().dir) || "" : spec;
|
||||
if ((wsFrame.scope || "") === want || scopeAsked === want) return;
|
||||
scopeAsked = want;
|
||||
const { status, body } = await postJson("/workspace/scope", { spec: want });
|
||||
if (status === 200 && body && Array.isArray(body.folders)) wsFrame = { ...wsFrame, ...body };
|
||||
scopeAsked = null;
|
||||
if ($("workspace-modal").open) renderWorkspace();
|
||||
}
|
||||
|
||||
// The dialog's "Remembered for" line: whose list this is.
|
||||
function workspaceScopeText() {
|
||||
const scope = (wsFrame && wsFrame.scope) || "";
|
||||
if (!scope) return "Remembered for this project, so your next console session here starts with these folders.";
|
||||
const spec = specList().find((s) => s.dir === scope);
|
||||
const name = spec ? spec.name : scope.split("/").pop();
|
||||
return `Remembered for the ${name} spec, and loaded again whenever it is picked.`;
|
||||
}
|
||||
|
||||
const NAME_RULE = "Names use lowercase letters, numbers and hyphens.";
|
||||
const BROWSE_UNAVAILABLE = "Browse isn't available here — type or paste the path.";
|
||||
// The folder whose Remove is waiting on its inline confirm, by id.
|
||||
@@ -5893,6 +5928,7 @@ function renderWorkspace() {
|
||||
}
|
||||
folders.forEach((f, i) => paintWorkspaceRow(list.children[i], f));
|
||||
$("workspace-browse").hidden = Boolean(wsFrame && wsFrame.remote);
|
||||
$("workspace-scope").textContent = workspaceScopeText();
|
||||
}
|
||||
|
||||
function workspaceRow(f) {
|
||||
|
||||
@@ -833,10 +833,28 @@
|
||||
Click the folder name in the middle of the bottom bar. It shows your
|
||||
folder's name and branch, such as <strong>shop · main</strong>, and
|
||||
<strong>shop + 2 folders · main</strong> once you have added some.
|
||||
The workspace lasts for this console session only: it carries across
|
||||
steps you start from the dashboard, and a new console session starts
|
||||
with just the folder you started in.
|
||||
It carries across steps you start from the dashboard.
|
||||
</p>
|
||||
<h4>Remembered for next time</h4>
|
||||
<ul>
|
||||
<li>
|
||||
Every change is saved as you make it, so the next console session in
|
||||
this folder starts with the same folders.
|
||||
</li>
|
||||
<li>
|
||||
Each spec keeps its own list. The first time you pick a spec on the
|
||||
dashboard it starts as a copy of the project's list (the one shown
|
||||
under <strong>Start from scratch</strong>), and after that the two
|
||||
are separate. Picking a spec loads its list; the line under the
|
||||
dialog's title says whose list you are looking at.
|
||||
</li>
|
||||
<li>
|
||||
The lists live in <code>workspaces.json</code> in your own
|
||||
Plan2Code settings folder, beside your look and feel, never in the
|
||||
project. Finalize offers to forget a spec's list when it archives the
|
||||
spec.
|
||||
</li>
|
||||
</ul>
|
||||
<h4>Adding a folder</h4>
|
||||
<ul>
|
||||
<li>
|
||||
@@ -1363,9 +1381,10 @@
|
||||
<h4>What it counts</h4>
|
||||
<p>
|
||||
Each step you run here adds points: a plan or a set of documents
|
||||
weighs more than a single answered question, and a built phase more
|
||||
still, by how many tasks it completed: a big phase adds more than a
|
||||
small one. Every two questions you answer add a point too, so a long
|
||||
weighs more than a quick task, and a built phase more still, by how
|
||||
many tasks it completed: a big phase adds more than a small one.
|
||||
Every two questions you answer within one step add a point too
|
||||
(rounded down, so a single answer adds nothing), so a long
|
||||
back-and-forth counts for more than a short one. Click the ring to see the count and a list of each step that added
|
||||
points, with what it added. It is a rule of thumb, not a
|
||||
reading of Plan2Code's real memory: long sessions tend to make it
|
||||
@@ -2003,6 +2022,7 @@
|
||||
The folders the agent uses as context this session. It reads the extra ones for
|
||||
reference and only changes them if you ask.
|
||||
</p>
|
||||
<p class="workspace-scope" id="workspace-scope"></p>
|
||||
<ul class="workspace-list" id="workspace-list"></ul>
|
||||
<div class="workspace-add">
|
||||
<label class="workspace-add-label" for="workspace-path">Add a folder</label>
|
||||
|
||||
@@ -45,7 +45,10 @@ import {
|
||||
readLedger,
|
||||
readOverview,
|
||||
readWorkspace,
|
||||
rememberWorkspace,
|
||||
rememberedWorkspace,
|
||||
remoteWarning,
|
||||
specKey,
|
||||
typedCount,
|
||||
withStateLock,
|
||||
writeJsonAtomic,
|
||||
@@ -326,7 +329,9 @@ function workspaceNow() {
|
||||
return ws;
|
||||
}
|
||||
const root = sessionWorktree();
|
||||
const fresh = { ...initialWorkspace(root || PROJECT), remote: remoteWarning().remote || "" };
|
||||
const scope = specKey(stateNow?.specDir);
|
||||
const remembered = root ? rememberedWorkspace(root, scope).entry : null;
|
||||
const fresh = { ...initialWorkspace(root || PROJECT, remembered), scope, remote: remoteWarning().remote || "" };
|
||||
// There but unreadable for now (a scanner's lock): never written over, and
|
||||
// never cached, so the next call reads it again.
|
||||
if (stamp) return workspaceSeen.ws || fresh;
|
||||
@@ -347,13 +352,87 @@ function saveWorkspace(ws) {
|
||||
|
||||
// One change: a new version, an entry in the change log the agent is handed,
|
||||
// the file, and every open page.
|
||||
function bumpWorkspace(ws, change) {
|
||||
function bumpWorkspace(ws, change, { remember = true } = {}) {
|
||||
ws.version = (ws.version || 0) + 1;
|
||||
ws.changes = [...(ws.changes || []), { ...change, version: ws.version }];
|
||||
saveWorkspace(ws);
|
||||
// Remembered for the next console session too. A folder gone missing or
|
||||
// found again is not a change of mind, so it is not saved.
|
||||
if (remember) rememberNow(ws);
|
||||
pushState();
|
||||
}
|
||||
|
||||
function rememberNow(ws) {
|
||||
const root = sessionWorktree();
|
||||
if (!root) return;
|
||||
try {
|
||||
rememberWorkspace(root, ws.scope || "", ws);
|
||||
} catch {}
|
||||
}
|
||||
|
||||
/**
|
||||
* Point the workspace at another spec ("" for the project's own list) and
|
||||
* swap in what was remembered there, logging each difference as a change so
|
||||
* the agent's cursor stays truthful. A spec with nothing saved starts from
|
||||
* the project's list (`seed: "project"`, the dashboard picker) or keeps the
|
||||
* list it has and saves it as the spec's (`seed: "current"`, a spec created
|
||||
* mid-run). Folders keep their ids when their path stays.
|
||||
*/
|
||||
function setScope(ws, spec, seed = "project") {
|
||||
const root = sessionWorktree();
|
||||
const next = specKey(spec);
|
||||
if (!root || (ws.scope || "") === next) return false;
|
||||
const found = rememberedWorkspace(root, next);
|
||||
ws.scope = next;
|
||||
if (next && found.from !== "spec" && seed === "current") {
|
||||
saveWorkspace(ws);
|
||||
rememberNow(ws);
|
||||
pushState();
|
||||
return true;
|
||||
}
|
||||
const want = initialWorkspace(root, found.entry).folders;
|
||||
const byPath = new Map(ws.folders.map((f) => [foldPath(path.resolve(f.path)), f]));
|
||||
const kept = new Set();
|
||||
const folders = [];
|
||||
const changes = [];
|
||||
for (const w of want) {
|
||||
const have = w.original ? ws.folders.find((f) => f.original) : byPath.get(foldPath(path.resolve(w.path)));
|
||||
if (!have) {
|
||||
folders.push({ ...w, id: "pending" });
|
||||
changes.push({ kind: "added", name: w.name, path: w.path, description: w.description });
|
||||
continue;
|
||||
}
|
||||
kept.add(have);
|
||||
if (have.name !== w.name) changes.push({ kind: "renamed", from: have.name, name: w.name, path: have.path });
|
||||
if ((have.description || "") !== (w.description || "")) {
|
||||
changes.push({ kind: "described", name: w.name, path: have.path, description: w.description || "" });
|
||||
}
|
||||
folders.push({ ...have, name: w.name, description: w.description || "" });
|
||||
}
|
||||
for (const f of ws.folders) {
|
||||
if (!kept.has(f)) changes.unshift({ kind: "removed", name: f.name, path: f.path });
|
||||
}
|
||||
ws.folders = folders.filter((f) => f.id !== "pending");
|
||||
for (const f of folders.filter((f) => f.id === "pending")) ws.folders.push({ ...f, id: nextFolderId(ws) });
|
||||
ws.missing = (ws.missing || []).filter((id) => ws.folders.some((f) => f.id === id));
|
||||
if (!changes.length) {
|
||||
saveWorkspace(ws);
|
||||
pushState();
|
||||
}
|
||||
for (const c of changes) bumpWorkspace(ws, c, { remember: false });
|
||||
checkFolders(ws);
|
||||
return true;
|
||||
}
|
||||
|
||||
// A spec posted mid-run (Pathfinder or Plan making its folder, a skill that
|
||||
// learns its spec late) takes the workspace with it.
|
||||
function followSpecDir(state) {
|
||||
const spec = specKey(state && state.specDir);
|
||||
if (!spec || !fileStamp(WORKSPACE_PATH)) return;
|
||||
const ws = workspaceNow();
|
||||
if ((ws.scope || "") !== spec) setScope(ws, spec, "current");
|
||||
}
|
||||
|
||||
function isFolder(p) {
|
||||
try {
|
||||
return fs.statSync(p).isDirectory();
|
||||
@@ -370,10 +449,10 @@ function checkFolders(ws) {
|
||||
const marked = ws.missing.includes(f.id);
|
||||
if (!there && !marked) {
|
||||
ws.missing = [...ws.missing, f.id];
|
||||
bumpWorkspace(ws, { kind: "missing", name: f.name, path: f.path });
|
||||
bumpWorkspace(ws, { kind: "missing", name: f.name, path: f.path }, { remember: false });
|
||||
} else if (there && marked) {
|
||||
ws.missing = ws.missing.filter((id) => id !== f.id);
|
||||
bumpWorkspace(ws, { kind: "found", name: f.name, path: f.path });
|
||||
bumpWorkspace(ws, { kind: "found", name: f.name, path: f.path }, { remember: false });
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -402,8 +481,8 @@ function folderIssues(entries) {
|
||||
}
|
||||
|
||||
function workspaceView() {
|
||||
const { folders, missing, remote } = workspaceNow();
|
||||
return { folders, missing: missing || [], remote: remote || "", issues: folderIssues(ledgerEntries()) };
|
||||
const { folders, missing, remote, scope } = workspaceNow();
|
||||
return { folders, missing: missing || [], remote: remote || "", scope: scope || "", issues: folderIssues(ledgerEntries()) };
|
||||
}
|
||||
|
||||
// Whether child sits strictly under parent.
|
||||
@@ -492,6 +571,7 @@ function bootWorkspace() {
|
||||
saveWorkspace(ws);
|
||||
}
|
||||
checkFolders(ws);
|
||||
followSpecDir(stateNow);
|
||||
}
|
||||
|
||||
/**
|
||||
@@ -1403,6 +1483,24 @@ const server = http.createServer((req, res) => {
|
||||
});
|
||||
}
|
||||
|
||||
// Which list the workspace is: a spec's, or the project's (`spec` empty).
|
||||
// The dashboard's picker sends it as the selection moves and before a
|
||||
// launch, so a skill opens on the list of the spec it was launched for.
|
||||
if (pathname === "/workspace/scope" && req.method === "POST") {
|
||||
if (!originOk(req, port)) return json(res, 403, { error: "bad origin" });
|
||||
return readBody(req, (err, body) => {
|
||||
if (err || !body || typeof body !== "object" || Array.isArray(body)) return json(res, 400, { error: "bad" });
|
||||
const spec = typeof body.spec === "string" ? body.spec : "";
|
||||
if (spec && !/^specs\/[^/\\]+$/.test(specKey(spec))) return json(res, 400, { reason: "bad-spec" });
|
||||
try {
|
||||
setScope(workspaceNow(), spec, "project");
|
||||
} catch (e) {
|
||||
return json(res, 500, { error: String(e.message) });
|
||||
}
|
||||
return json(res, 200, workspaceView());
|
||||
});
|
||||
}
|
||||
|
||||
// Only ever returns a path: the page then adds it through /workspace/add.
|
||||
if (pathname === "/workspace/browse" && req.method === "POST") {
|
||||
if (!originOk(req, port)) return json(res, 403, { error: "bad origin" });
|
||||
@@ -1561,6 +1659,9 @@ function checkState() {
|
||||
try {
|
||||
ensureConversation(parsed);
|
||||
} catch {}
|
||||
try {
|
||||
followSpecDir(parsed);
|
||||
} catch {}
|
||||
pushState();
|
||||
}
|
||||
lastStateStamp = stamp;
|
||||
|
||||
@@ -17,6 +17,6 @@
|
||||
"url": "https://github.com/jparkerweb/plan2code"
|
||||
},
|
||||
"homepage": "https://github.com/jparkerweb/plan2code",
|
||||
"releaseDate": "2026-10-02",
|
||||
"releaseDate": "2026-10-04",
|
||||
"mode": "utility"
|
||||
}
|
||||
@@ -0,0 +1,247 @@
|
||||
// Plan2Code skill scripts: shared plumbing.
|
||||
//
|
||||
// Every script in a skill's scripts/ directory imports this file. It owns the
|
||||
// conventions the SKILL.md prompts rely on, so they are identical everywhere:
|
||||
//
|
||||
// stdout one JSON object, always. `{ "ok": true, ... }` on success,
|
||||
// `{ "ok": false, "error": "<code>", "message": "...", "next": "..." }`
|
||||
// on a handled failure.
|
||||
// stderr a one-line human diagnostic on failure (the same message + next).
|
||||
// exit 0 ok · 1 unexpected crash · 2 bad arguments · 3 not found ·
|
||||
// 4 invalid input or a check that failed · 5 refused (would clobber
|
||||
// or break a rule).
|
||||
//
|
||||
// Node 18+ built-ins only, no build step: this ships inside every skill.
|
||||
|
||||
import fs from "node:fs";
|
||||
import path from "node:path";
|
||||
import { fileURLToPath, pathToFileURL } from "node:url";
|
||||
|
||||
export const HERE = path.dirname(fileURLToPath(import.meta.url));
|
||||
|
||||
export const EXIT = { OK: 0, CRASH: 1, USAGE: 2, NOT_FOUND: 3, INVALID: 4, REFUSED: 5 };
|
||||
|
||||
export class CliError extends Error {
|
||||
constructor(exit, error, message, next) {
|
||||
super(message);
|
||||
this.exit = exit;
|
||||
this.error = error;
|
||||
this.next = next;
|
||||
}
|
||||
}
|
||||
|
||||
/** Throw a handled failure: the run() wrapper prints it and sets the exit code. */
|
||||
export function fail(exit, error, message, next) {
|
||||
throw new CliError(exit, error, message, next);
|
||||
}
|
||||
|
||||
export function out(obj) {
|
||||
process.stdout.write(JSON.stringify(obj, null, 2) + "\n");
|
||||
}
|
||||
|
||||
/**
|
||||
* Parse argv into { _: positionals, <flag>: value }.
|
||||
* `booleans` names flags that take no value; every other `--flag` takes the
|
||||
* next argument, and repeats of a flag listed in `lists` collect into an array.
|
||||
* `--flag=value` works too. Unknown flags are a usage error, so a typo never
|
||||
* silently changes behavior.
|
||||
*/
|
||||
export function parseArgs(argv, { booleans = [], values = [], lists = [] } = {}) {
|
||||
const known = new Set([...booleans, ...values, ...lists, "help"]);
|
||||
const args = { _: [] };
|
||||
for (let i = 0; i < argv.length; i++) {
|
||||
const a = argv[i];
|
||||
if (!a.startsWith("--")) {
|
||||
args._.push(a);
|
||||
continue;
|
||||
}
|
||||
let name = a.slice(2);
|
||||
let value;
|
||||
const eq = name.indexOf("=");
|
||||
if (eq !== -1) {
|
||||
value = name.slice(eq + 1);
|
||||
name = name.slice(0, eq);
|
||||
}
|
||||
if (!known.has(name)) {
|
||||
fail(EXIT.USAGE, "unknown-flag", `Unknown flag --${name}.`, "Run with --help for the flags this script takes.");
|
||||
}
|
||||
if (name === "help" || booleans.includes(name)) {
|
||||
args[name] = true;
|
||||
continue;
|
||||
}
|
||||
if (value === undefined) {
|
||||
if (i + 1 >= argv.length) {
|
||||
fail(EXIT.USAGE, "missing-value", `--${name} needs a value.`, "Run with --help for usage.");
|
||||
}
|
||||
value = argv[++i];
|
||||
}
|
||||
if (lists.includes(name)) (args[name] ||= []).push(value);
|
||||
else args[name] = value;
|
||||
}
|
||||
return args;
|
||||
}
|
||||
|
||||
/**
|
||||
* Run a script's main(). Prints usage on --help, turns CliError into the JSON
|
||||
* failure shape plus an exit code, and anything else into exit 1 with the stack
|
||||
* on stderr. Sets process.exitCode rather than calling process.exit(), so
|
||||
* stdout is never cut off mid-write.
|
||||
*/
|
||||
export async function run(usage, main) {
|
||||
try {
|
||||
const argv = process.argv.slice(2);
|
||||
if (argv.includes("--help") || argv.includes("-h")) {
|
||||
process.stdout.write(usage.trim() + "\n");
|
||||
return;
|
||||
}
|
||||
await main(argv);
|
||||
} catch (err) {
|
||||
if (err instanceof CliError) {
|
||||
out({ ok: false, error: err.error, message: err.message, ...(err.next ? { next: err.next } : {}) });
|
||||
process.stderr.write(`error: ${err.message}${err.next ? `\nnext: ${err.next}` : ""}\n`);
|
||||
process.exitCode = err.exit;
|
||||
return;
|
||||
}
|
||||
process.stderr.write(`unexpected error: ${err && err.stack ? err.stack : err}\n`);
|
||||
out({ ok: false, error: "crash", message: String(err && err.message ? err.message : err) });
|
||||
process.exitCode = EXIT.CRASH;
|
||||
}
|
||||
}
|
||||
|
||||
/* ------------------------------------------------------------------ time */
|
||||
|
||||
// PLAN2CODE_NOW ("YYYY-MM-DD HH:mm" or any Date-parsable string) pins the
|
||||
// clock, for tests and for reproducing a run. Otherwise: the local clock, which
|
||||
// is what "today" means to the person reading the date in their files.
|
||||
export function now() {
|
||||
const pinned = process.env.PLAN2CODE_NOW;
|
||||
if (pinned) {
|
||||
const m = pinned.match(/^(\d{4})-(\d{2})-(\d{2})(?:[ T](\d{2}):(\d{2})(?::(\d{2}))?)?$/);
|
||||
if (m) return new Date(+m[1], +m[2] - 1, +m[3], +(m[4] || 0), +(m[5] || 0), +(m[6] || 0));
|
||||
const d = new Date(pinned);
|
||||
if (!Number.isNaN(d.getTime())) return d;
|
||||
}
|
||||
return new Date();
|
||||
}
|
||||
|
||||
const pad = (n) => String(n).padStart(2, "0");
|
||||
|
||||
/** YYYY-MM-DD */
|
||||
export function isoDate(d = now()) {
|
||||
return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}`;
|
||||
}
|
||||
|
||||
/** YYYYMMDD */
|
||||
export function compactDate(d = now()) {
|
||||
return isoDate(d).replace(/-/g, "");
|
||||
}
|
||||
|
||||
/** YYYY-MM-DD HH:mm */
|
||||
export function stamp(d = now()) {
|
||||
return `${isoDate(d)} ${pad(d.getHours())}:${pad(d.getMinutes())}`;
|
||||
}
|
||||
|
||||
/** HHMMSS */
|
||||
export function clock(d = now()) {
|
||||
return `${pad(d.getHours())}${pad(d.getMinutes())}${pad(d.getSeconds())}`;
|
||||
}
|
||||
|
||||
/* ----------------------------------------------------------------- files */
|
||||
|
||||
export function readText(file) {
|
||||
try {
|
||||
return fs.readFileSync(file, "utf8");
|
||||
} catch {
|
||||
return null;
|
||||
}
|
||||
}
|
||||
|
||||
export function isDir(p) {
|
||||
try {
|
||||
return fs.statSync(p).isDirectory();
|
||||
} catch {
|
||||
return false;
|
||||
}
|
||||
}
|
||||
|
||||
/** Write a file only when its content changes. Returns true when it wrote. */
|
||||
export function writeIfChanged(file, content) {
|
||||
const current = readText(file);
|
||||
if (current === content) return false;
|
||||
fs.mkdirSync(path.dirname(file), { recursive: true });
|
||||
fs.writeFileSync(file, content);
|
||||
return true;
|
||||
}
|
||||
|
||||
/** Normalise line endings for parsing; keep the original for writing back. */
|
||||
export function eol(text) {
|
||||
return text.includes("\r\n") ? "\r\n" : "\n";
|
||||
}
|
||||
|
||||
/**
|
||||
* phase-N.md per phase number. An exact phase-N.md always wins over a sibling
|
||||
* such as phase-1-old.md; more than one candidate is reported, never guessed.
|
||||
* Shared so every script that counts a spec's tasks reads the same files.
|
||||
*/
|
||||
export function phaseFiles(dir) {
|
||||
const files = new Map();
|
||||
const extra = new Map();
|
||||
for (const name of fs.readdirSync(dir).sort()) {
|
||||
const m = name.match(/^phase-(\d+)\b[^/]*\.md$/i);
|
||||
if (!m) continue;
|
||||
const n = Number(m[1]);
|
||||
const exact = new RegExp(`^phase-0*${n}\\.md$`, "i").test(name);
|
||||
if (!files.has(n)) files.set(n, name);
|
||||
else if (exact) {
|
||||
(extra.get(n) || extra.set(n, []).get(n)).push(files.get(n));
|
||||
files.set(n, name);
|
||||
} else (extra.get(n) || extra.set(n, []).get(n)).push(name);
|
||||
}
|
||||
files.extra = extra;
|
||||
return files;
|
||||
}
|
||||
|
||||
/** Forward-slash path relative to root, for output the agent pastes into prompts. */
|
||||
export function rel(root, p) {
|
||||
return path.relative(root, p).split(path.sep).join("/") || ".";
|
||||
}
|
||||
|
||||
/* --------------------------------------------------------- the web console */
|
||||
|
||||
// The web console ships beside these scripts in every installed skill
|
||||
// (references/web-console/), and in this repo it sits at src/web-console/. Its
|
||||
// lib.mjs is the one home of the spec-state classifier and the loop-marker /
|
||||
// metrics-bait scan, so the scripts import it rather than keep a second copy.
|
||||
const CONSOLE_LIB_CANDIDATES = [
|
||||
path.join(HERE, "..", "references", "web-console", "lib.mjs"), // installed skill
|
||||
path.join(HERE, "..", "web-console", "lib.mjs"), // src/skill-scripts in the repo
|
||||
];
|
||||
|
||||
let consoleLibPromise;
|
||||
export function consoleLib() {
|
||||
consoleLibPromise ||= (async () => {
|
||||
for (const candidate of CONSOLE_LIB_CANDIDATES) {
|
||||
if (fs.existsSync(candidate)) return import(pathToFileURL(candidate).href);
|
||||
}
|
||||
fail(
|
||||
EXIT.NOT_FOUND,
|
||||
"console-lib-missing",
|
||||
`The web console's lib.mjs is not beside this script (looked in ${CONSOLE_LIB_CANDIDATES.join(", ")}).`,
|
||||
"The skill install is incomplete; reinstall the Plan2Code skills (node install.js)."
|
||||
);
|
||||
})();
|
||||
return consoleLibPromise;
|
||||
}
|
||||
|
||||
/** The version these scripts shipped with (scripts/version.json, or the repo's). */
|
||||
export function version() {
|
||||
for (const file of [path.join(HERE, "version.json"), path.join(HERE, "..", "..", "version.json")]) {
|
||||
const text = readText(file);
|
||||
if (!text) continue;
|
||||
try {
|
||||
const v = JSON.parse(text).version;
|
||||
if (typeof v === "string") return v;
|
||||
} catch {}
|
||||
}
|
||||
return null;
|
||||
}
|
||||
@@ -0,0 +1,676 @@
|
||||
#!/usr/bin/env node
|
||||
// specs.mjs: where every spec under specs/ stands, read from its files.
|
||||
//
|
||||
// The pipeline skills (plan, document, implement, revise-plan, finalize,
|
||||
// review, handoff) all need the same filesystem facts: which specs exist, what
|
||||
// a spec's PLAN-DRAFT says, which phases are open, how many tasks are done.
|
||||
// Those have one correct answer, so this script computes them instead of each
|
||||
// prompt re-deriving them by hand. It also performs the two mechanical writes
|
||||
// (a Phase Checklist marker, the archive move), with --dry-run.
|
||||
//
|
||||
// Shell listing only matters to people: specs/ is gitignored, so editor search
|
||||
// tools skip it. This script reads the disk directly and does not care.
|
||||
|
||||
import fs from "node:fs";
|
||||
import path from "node:path";
|
||||
import { EXIT, fail, out, parseArgs, run, readText, isDir, rel, eol, consoleLib, isoDate, phaseFiles } from "./common.mjs";
|
||||
|
||||
const USAGE = `
|
||||
specs.mjs: spec state for the Plan2Code pipeline skills. JSON on stdout.
|
||||
|
||||
node specs.mjs list [--root <dir>]
|
||||
Every active spec under specs/ (never specs--completed/), newest first:
|
||||
state, detail, PLAN-DRAFT files with their **Status:** line, overview,
|
||||
phase count. Also the names already archived in specs--completed/.
|
||||
|
||||
node specs.mjs status <spec> [--root <dir>]
|
||||
One spec in full: the overview's Phase Checklist, Parallel Execution
|
||||
Groups, per-phase task counts by marker, task-numbering problems,
|
||||
completion, the implement phase-selection verdict ("next"), the pending
|
||||
phases, and consistency checks. <spec> is specs/<name>, <name>, or a path
|
||||
to its overview.md.
|
||||
|
||||
node specs.mjs metrics <spec> --step document|finalize [--set key=value ...]
|
||||
The METRICS_JSON comment for that step, countable fields computed from
|
||||
the files; judgment fields come from --set (numbers only).
|
||||
document: total_tasks, tasks_per_phase, phase_count,
|
||||
parallel_groups_identified computed; pass
|
||||
--set verification_items_added=N (your Verification Summary's
|
||||
Added total; the VERIFICATION comments are reported as a check).
|
||||
finalize: completion_rate_at_audit, tasks_completed, tasks_total; pass
|
||||
--set verification_failures_found=N
|
||||
--set documentation_updates_needed=N.
|
||||
|
||||
node specs.mjs mark <spec> --phase <N> --to open|in-progress|done [--dry-run]
|
||||
Set phase N's Phase Checklist marker in overview.md ([ ], [/], [x]).
|
||||
done also sets the phase file's Status line (**Status:**, **Status**:
|
||||
or Status:) to Complete (and warns if tasks are unfinished); open on a
|
||||
Complete phase sets it to In Progress. Warns when the phase file has no
|
||||
Status line. Refuses a phase with duplicate checklist rows, and refuses
|
||||
in-progress -> open (started work stays marked).
|
||||
|
||||
node specs.mjs archive <spec> [--dry-run]
|
||||
Move specs/<name>/ to specs--completed/<name>/. Refuses if the target
|
||||
exists, or if <spec> is not a folder directly under specs/.
|
||||
|
||||
Markers: [ ] pending · [/] in progress · [x] complete · [!] blocked · [?] assumed.
|
||||
Exit: 0 ok · 2 bad arguments · 3 spec not found · 4 cannot parse / check
|
||||
failed · 5 refused.
|
||||
`;
|
||||
|
||||
/* ------------------------------------------------------------- resolving */
|
||||
|
||||
function realOrResolved(p) {
|
||||
try {
|
||||
return fs.realpathSync.native(p);
|
||||
} catch {
|
||||
return path.resolve(p);
|
||||
}
|
||||
}
|
||||
|
||||
const samePath = (a, b) => (process.platform === "win32" ? a.toLowerCase() === b.toLowerCase() : a === b);
|
||||
|
||||
// Read-only commands (status, metrics) accept an archived spec, because
|
||||
// Finalize reads its own spec after Step 6 moved it. Writes never do.
|
||||
function resolveSpec(root, arg, { allowArchived = false } = {}) {
|
||||
if (!arg) fail(EXIT.USAGE, "missing-spec", "Name the spec: specs/<name>, <name>, or its overview.md path.", "Run `specs.mjs list` to see the active specs.");
|
||||
let p = arg.replace(/\\/g, "/").replace(/\/+$/, "");
|
||||
if (/\/overview\.md$/i.test(p) || /\/phase-[^/]*\.md$/i.test(p)) p = p.replace(/\/[^/]+$/, "");
|
||||
const abs = path.isAbsolute(p) ? p : p.includes("/") ? path.join(root, p) : path.join(root, "specs", p);
|
||||
const relPath = rel(root, abs);
|
||||
if (!allowArchived && /(^|\/)specs--completed(\/|$)/.test(relPath)) {
|
||||
fail(EXIT.REFUSED, "archived-spec", `${relPath} is archived; the pipeline only changes active specs under specs/.`, "Pick an active spec from `specs.mjs list`.");
|
||||
}
|
||||
// A spec is a folder directly under specs/ (or specs--completed/ for a read).
|
||||
// Without this, `archive .` would move all of specs/ and `archive ./src` a
|
||||
// source folder.
|
||||
const homes = [path.join(root, "specs"), ...(allowArchived ? [path.join(root, "specs--completed")] : [])].map(realOrResolved);
|
||||
const parent = realOrResolved(path.dirname(path.resolve(abs)));
|
||||
if (!homes.some((h) => samePath(h, parent))) {
|
||||
fail(EXIT.REFUSED, "not-a-spec", `${relPath} is not a spec folder: a spec sits directly under specs/${allowArchived ? " (or specs--completed/)" : ""}.`, "Pass specs/<name> or <name>; run `specs.mjs list` to see the active specs.");
|
||||
}
|
||||
if (!isDir(abs)) {
|
||||
fail(EXIT.NOT_FOUND, "spec-not-found", `No spec folder at ${relPath}.`, "Run `specs.mjs list` from the project root (or pass --root) to see the active specs.");
|
||||
}
|
||||
return { dir: abs, rel: relPath, name: path.basename(abs) };
|
||||
}
|
||||
|
||||
/* -------------------------------------------------------------- parsing */
|
||||
|
||||
const MARKERS = { " ": "pending", "/": "in-progress", x: "complete", X: "complete", "!": "blocked", "?": "assumed" };
|
||||
// Task 2.3, a lettered sub-task 3.6a, or a named one such as a testing task 1.T.
|
||||
const TASK_RE = /^\s*[-*] \[(.)\]\s+\*\*Task\s+(\d+)\.(\d+|[A-Za-z]+)([a-z]*)\b/;
|
||||
const CHECKBOX_RE = /^\s*[-*] \[(.)\]/;
|
||||
// The Status line in any of the forms people write it: **Status:**, **Status**:
|
||||
// or a plain Status:, optionally as a list item. Groups: everything up to the
|
||||
// value (kept as written when the value is rewritten), the value, trailing blanks.
|
||||
const STATUS_RE = /^([ \t]*(?:[-*][ \t]*)?(?:\*\*Status:\*\*|\*\*Status\*\*:|Status:)[ \t]*)(.+?)([ \t]*)$/m;
|
||||
|
||||
function statusOf(text) {
|
||||
const m = (text || "").match(STATUS_RE);
|
||||
return m ? m[2] : null;
|
||||
}
|
||||
|
||||
/** A markdown section's lines: from its heading to the next heading of the same or higher level. */
|
||||
function section(text, headingRe) {
|
||||
const lines = text.split(/\r?\n/);
|
||||
const start = lines.findIndex((l) => /^#{1,6}\s/.test(l) && headingRe.test(l));
|
||||
if (start === -1) return null;
|
||||
const level = lines[start].match(/^#+/)[0].length;
|
||||
let end = lines.length;
|
||||
for (let i = start + 1; i < lines.length; i++) {
|
||||
const m = lines[i].match(/^(#+)\s/);
|
||||
if (m && m[1].length <= level) {
|
||||
end = i;
|
||||
break;
|
||||
}
|
||||
}
|
||||
return { start, end, lines: lines.slice(start + 1, end) };
|
||||
}
|
||||
|
||||
function plainText(s) {
|
||||
return s
|
||||
.replace(/\[([^\]]*)\]\([^)]*\)/g, "$1")
|
||||
.replace(/[*_`]/g, "")
|
||||
.replace(/\s+/g, " ")
|
||||
.trim();
|
||||
}
|
||||
|
||||
/** Phase Checklist rows: the first "Phase N" on each checkbox line names the phase. */
|
||||
function parseChecklist(overview) {
|
||||
const sec = section(overview, /Phase Checklist/i);
|
||||
if (!sec) return { found: false, phases: [], unparsed: [] };
|
||||
const phases = [];
|
||||
const unparsed = [];
|
||||
sec.lines.forEach((line, i) => {
|
||||
const m = line.match(CHECKBOX_RE);
|
||||
if (!m) return;
|
||||
const text = plainText(line.replace(CHECKBOX_RE, ""));
|
||||
const num = text.match(/\bPhase\s+(\d+)\b/i);
|
||||
if (!num) {
|
||||
unparsed.push({ line: sec.start + 2 + i, text: line.trim() });
|
||||
return;
|
||||
}
|
||||
const after = text.slice(num.index + num[0].length).replace(/^\s*[:\-–—]\s*/, "");
|
||||
const name = after.split(/\s+[-–—]\s+|\s+\(|\s+_\(|:\s|\s+see\s+phase-/i)[0].replace(/\s*phase-\d+\.md\s*$/i, "").trim();
|
||||
phases.push({
|
||||
number: Number(num[1]),
|
||||
marker: m[1],
|
||||
state: MARKERS[m[1]] || "unknown",
|
||||
name: name.replace(/\s*\[Milestone[^\]]*\]\s*$/i, "") || `Phase ${num[1]}`,
|
||||
line: sec.start + 2 + i,
|
||||
});
|
||||
});
|
||||
return { found: true, phases, unparsed };
|
||||
}
|
||||
|
||||
/** "2, 3", "2-4" and "2–4" (or an em dash) alike: ranges expand, so a group cell never loses a phase. */
|
||||
function phaseList(cell) {
|
||||
const outList = [];
|
||||
for (const part of cell.match(/\d+\s*[-–\u2014]\s*\d+|\d+/g) || []) {
|
||||
const r = part.match(/^(\d+)\s*[-–\u2014]\s*(\d+)$/);
|
||||
if (r && Number(r[2]) >= Number(r[1]) && Number(r[2]) - Number(r[1]) < 100) {
|
||||
for (let n = Number(r[1]); n <= Number(r[2]); n++) outList.push(n);
|
||||
} else outList.push(...part.match(/\d+/g).map(Number));
|
||||
}
|
||||
return [...new Set(outList)];
|
||||
}
|
||||
|
||||
/** Parallel Execution Groups table: real groups only (a named group with 2+ phases). */
|
||||
function parseGroups(overview) {
|
||||
const sec = section(overview, /Parallel Execution Groups/i);
|
||||
if (!sec) return { found: false, groups: [] };
|
||||
const groups = [];
|
||||
const seen = new Set();
|
||||
for (const line of sec.lines) {
|
||||
if (!/^\s*\|/.test(line) || /^\s*\|[\s:|-]+\|\s*$/.test(line)) continue;
|
||||
const cells = line.split("|").slice(1, -1).map((c) => c.trim());
|
||||
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
|
||||
// ("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;
|
||||
const key = `${id}:${phases.join(",")}`;
|
||||
if (seen.has(key)) continue;
|
||||
seen.add(key);
|
||||
groups.push({ id, phases, reason: plainText(cells[2] || "") });
|
||||
}
|
||||
return { found: true, groups };
|
||||
}
|
||||
|
||||
function firstSentence(text) {
|
||||
const t = plainText(text);
|
||||
const m = t.match(/^(.+?[.!?])(\s|$)/);
|
||||
return (m ? m[1] : t).slice(0, 240);
|
||||
}
|
||||
|
||||
function parsePhaseFile(file, number) {
|
||||
const text = readText(file) || "";
|
||||
const lines = text.split(/\r?\n/);
|
||||
const title = (lines.find((l) => /^#\s/.test(l)) || "").replace(/^#\s+/, "").trim();
|
||||
const status = statusOf(text);
|
||||
const counts = { pending: 0, "in-progress": 0, complete: 0, blocked: 0, assumed: 0, unknown: 0 };
|
||||
const tasks = [];
|
||||
const strayCheckboxes = [];
|
||||
const unmatchedTasks = [];
|
||||
let heading = "";
|
||||
lines.forEach((line, i) => {
|
||||
const h = line.match(/^#{1,6}\s+(.*)$/);
|
||||
if (h) heading = plainText(h[1]);
|
||||
const t = line.match(TASK_RE);
|
||||
if (t) {
|
||||
const state = MARKERS[t[1]] || "unknown";
|
||||
counts[state]++;
|
||||
const named = !/^\d+$/.test(t[3]);
|
||||
tasks.push({ id: `${t[2]}.${t[3]}${t[4]}`, phase: Number(t[2]), seq: named ? null : Number(t[3]), named, suffix: t[4], marker: t[1], state, line: i + 1 });
|
||||
return;
|
||||
}
|
||||
// A line that looks like a task but is not counted as one (Task 1.4A,
|
||||
// "1. [ ] **Task", a non-bold "- [ ] Task 1.3") would make the audit undercount.
|
||||
if (/^\s*(?:[-*]|\d+\.)\s+\[.\].*\bTask\s+\d+\./i.test(line)) unmatchedTasks.push({ line: i + 1, text: line.trim().slice(0, 120) });
|
||||
if (CHECKBOX_RE.test(line)) strayCheckboxes.push({ line: i + 1, section: heading, text: line.trim().slice(0, 120) });
|
||||
});
|
||||
|
||||
// Numbering: every task belongs to this phase, the base numbers run 1..n with
|
||||
// no gaps or repeats, and a lettered task (3.6a) sits after its base (3.6).
|
||||
// Named tasks (1.T) are outside the numeric sequence.
|
||||
const numbering = [];
|
||||
const bases = [];
|
||||
for (const t of tasks) {
|
||||
if (t.phase !== number) numbering.push(`Task ${t.id} is in phase-${number}.md but numbered for Phase ${t.phase}`);
|
||||
if (!t.suffix && !t.named) bases.push(t.seq);
|
||||
}
|
||||
const seenIds = new Set();
|
||||
for (const t of tasks) {
|
||||
if (seenIds.has(t.id)) numbering.push(`Task ${t.id} appears more than once`);
|
||||
seenIds.add(t.id);
|
||||
if (t.suffix && !t.named && !bases.includes(t.seq)) numbering.push(`Task ${t.id} has no base Task ${t.phase}.${t.seq}`);
|
||||
}
|
||||
bases.forEach((seq, i) => {
|
||||
if (seq !== i + 1 && !numbering.some((n) => n.startsWith("Task numbering"))) {
|
||||
numbering.push(`Task numbering is not sequential: expected ${number}.${i + 1}, found ${number}.${seq}`);
|
||||
}
|
||||
});
|
||||
|
||||
const overviewSec = section(text, /^#{1,6}\s+Overview\b/i);
|
||||
const goalText = overviewSec ? overviewSec.lines.join("\n").split(/\n\s*\n/).map((p) => p.trim()).find((p) => p && !/^[-*|>]/.test(p)) : "";
|
||||
return {
|
||||
title,
|
||||
status,
|
||||
goal: goalText ? firstSentence(goalText) : null,
|
||||
total: tasks.length,
|
||||
counts,
|
||||
open: counts.pending + counts["in-progress"] + counts.blocked + counts.unknown,
|
||||
// Open work a phase cannot be approved over; blocked tasks may stand ([!] is allowed at sign-off).
|
||||
unfinished: counts.pending + counts["in-progress"] + counts.unknown,
|
||||
tasks,
|
||||
numbering,
|
||||
strayCheckboxes,
|
||||
unmatchedTasks,
|
||||
};
|
||||
}
|
||||
|
||||
function planDrafts(dir) {
|
||||
return fs
|
||||
.readdirSync(dir)
|
||||
.filter((n) => /^PLAN-DRAFT.*\.md$/i.test(n))
|
||||
.sort()
|
||||
.map((file) => ({
|
||||
file,
|
||||
archived: /-prev\.md$/i.test(file),
|
||||
status: statusOf(readText(path.join(dir, file))),
|
||||
}));
|
||||
}
|
||||
|
||||
/* ---------------------------------------------------------------- status */
|
||||
|
||||
function specStatus(spec) {
|
||||
const overviewPath = path.join(spec.dir, "overview.md");
|
||||
const overview = readText(overviewPath);
|
||||
const files = phaseFiles(spec.dir);
|
||||
// An empty overview.md still exists; only a missing one is "no overview".
|
||||
const hasOverview = overview !== null;
|
||||
const checklist = hasOverview ? parseChecklist(overview) : { found: false, phases: [], unparsed: [] };
|
||||
const groups = hasOverview ? parseGroups(overview) : { found: false, groups: [] };
|
||||
const checks = [];
|
||||
const check = (level, code, message) => checks.push({ level, code, message });
|
||||
for (const [n, names] of files.extra) {
|
||||
check("warn", "duplicate-phase-file", `Phase ${n} has more than one file: using ${files.get(n)}, ignoring ${names.join(", ")}`);
|
||||
}
|
||||
const rowsByNumber = new Map();
|
||||
for (const r of checklist.phases) rowsByNumber.set(r.number, [...(rowsByNumber.get(r.number) || []), r]);
|
||||
for (const [n, rows] of rowsByNumber) {
|
||||
if (rows.length > 1) check("error", "duplicate-checklist-row", `Phase ${n} has ${rows.length} rows in the Phase Checklist (overview.md lines ${rows.map((r) => r.line).join(", ")}); the first one is used`);
|
||||
}
|
||||
|
||||
const phases = [];
|
||||
const numbers = new Set([...checklist.phases.map((p) => p.number), ...files.keys()]);
|
||||
for (const number of [...numbers].sort((a, b) => a - b)) {
|
||||
const row = checklist.phases.find((p) => p.number === number) || null;
|
||||
const file = files.get(number) || null;
|
||||
const parsed = file ? parsePhaseFile(path.join(spec.dir, file), number) : null;
|
||||
phases.push({
|
||||
number,
|
||||
name: row ? row.name : parsed ? parsed.title.replace(/^Phase\s+\d+\s*[:\-–—]?\s*/i, "") : `Phase ${number}`,
|
||||
checklist: row ? row.state : null,
|
||||
marker: row ? row.marker : null,
|
||||
file,
|
||||
status: parsed ? parsed.status : null,
|
||||
goal: parsed ? parsed.goal : null,
|
||||
tasks: parsed ? { total: parsed.total, open: parsed.open, ...parsed.counts } : null,
|
||||
blockedTasks: parsed ? parsed.tasks.filter((t) => t.state === "blocked").map((t) => t.id) : [],
|
||||
assumedTasks: parsed ? parsed.tasks.filter((t) => t.state === "assumed").map((t) => t.id) : [],
|
||||
openTasks: parsed ? parsed.tasks.filter((t) => ["pending", "in-progress", "blocked", "unknown"].includes(t.state)).map((t) => t.id) : [],
|
||||
});
|
||||
if (!row && hasOverview) check("error", "missing-checklist-row", `phase-${number}.md has no row in overview.md's Phase Checklist`);
|
||||
if (row && !file) check("error", "missing-phase-file", `Phase Checklist lists Phase ${number} but there is no phase-${number}.md`);
|
||||
if (parsed) {
|
||||
for (const n of parsed.numbering) check("error", "task-numbering", `phase-${number}.md: ${n}`);
|
||||
// Prerequisites and criteria are plain bullets by rule; other checkbox
|
||||
// blocks (a Phase Testing list) are the template's own and are not tasks.
|
||||
for (const s of parsed.strayCheckboxes.filter((c) => /prerequisite|criteria/i.test(c.section))) {
|
||||
check("warn", "criteria-checkbox", `phase-${number}.md:${s.line} is a checkbox under "${s.section}"; prerequisites and criteria use plain bullets`);
|
||||
}
|
||||
if (parsed.total === 0) check("warn", "no-tasks", `phase-${number}.md has no **Task ${number}.N:** checkbox lines`);
|
||||
for (const u of parsed.unmatchedTasks) {
|
||||
check("warn", "uncounted-task", `phase-${number}.md:${u.line} looks like a task but is not counted (a task line is "- [ ] **Task ${number}.N:**"): ${u.text}`);
|
||||
}
|
||||
const done = parsed.counts.complete + parsed.counts.assumed;
|
||||
const rowDone = row && (row.state === "complete" || row.state === "assumed");
|
||||
// A phase may be approved with blocked [!] tasks left (Implementation
|
||||
// Mode's self-review allows "[x] or blocked [!]"); only unfinished work is an error.
|
||||
if (rowDone && parsed.unfinished > 0) {
|
||||
check("error", "checked-with-open-tasks", `Phase ${number} is [${row.marker}] in overview.md but ${parsed.unfinished} task(s) are not done (${phases.at(-1).openTasks.filter((id) => !phases.at(-1).blockedTasks.includes(id)).join(", ")})`);
|
||||
} else if (rowDone && parsed.counts.blocked > 0) {
|
||||
check("info", "approved-with-blocked", `Phase ${number} is [${row.marker}] with ${parsed.counts.blocked} blocked task(s) (${phases.at(-1).blockedTasks.join(", ")})`);
|
||||
}
|
||||
if (row && row.state === "pending" && parsed.total > 0 && done > 0) {
|
||||
// Done tasks under a [ ] phase with work still open is what a re-opened
|
||||
// phase looks like (revise-plan); with nothing open it is a missed mark.
|
||||
if (parsed.unfinished > 0) check("info", "partly-done-unchecked", `Phase ${number} is [ ] with ${done} task(s) done and ${parsed.unfinished} open (normal for a re-opened phase)`);
|
||||
else check("warn", "unchecked-with-done-tasks", `Phase ${number} is [ ] in overview.md but all ${done} unblocked task(s) are done`);
|
||||
}
|
||||
if (row && !rowDone && row.state !== "pending" && parsed.total > 0 && parsed.unfinished === 0) {
|
||||
check("info", "done-not-approved", `Phase ${number}: every task is done but overview.md still shows [${row.marker}] (normal until the user approves the phase)`);
|
||||
}
|
||||
}
|
||||
}
|
||||
if (!hasOverview) check("error", "no-overview", `${spec.rel} has no overview.md`);
|
||||
else if (!checklist.found) check("error", "no-checklist", "overview.md has no ## Phase Checklist section");
|
||||
for (const u of checklist.unparsed) check("warn", "unparsed-checklist-row", `overview.md:${u.line} is a checkbox in the Phase Checklist with no "Phase N" in it: ${u.text}`);
|
||||
for (const g of groups.groups) {
|
||||
for (const n of g.phases) if (!numbers.has(n)) check("error", "group-unknown-phase", `Parallel group ${g.id} names Phase ${n}, which does not exist`);
|
||||
}
|
||||
|
||||
// Totals. Completed = [x] plus [?] (assumed complete); [?] is reported on its own too.
|
||||
// Incomplete = [ ] + [/] (+ unreadable markers); Blocked is its own column.
|
||||
const totals = { total: 0, complete: 0, assumed: 0, pending: 0, "in-progress": 0, blocked: 0, unknown: 0 };
|
||||
for (const p of phases) if (p.tasks) for (const k of Object.keys(totals)) totals[k] += p.tasks[k] || 0;
|
||||
const completed = totals.complete + totals.assumed;
|
||||
const completion = totals.total ? completed / totals.total : null;
|
||||
|
||||
return {
|
||||
ok: true,
|
||||
spec: spec.rel,
|
||||
name: spec.name,
|
||||
overview: hasOverview ? "overview.md" : null,
|
||||
planDrafts: planDrafts(spec.dir),
|
||||
phases,
|
||||
parallelGroups: groups.groups,
|
||||
totals: { ...totals, completed, incomplete: totals.pending + totals["in-progress"] + totals.unknown },
|
||||
completion: completion === null ? null : Number(completion.toFixed(4)),
|
||||
completionPercent: completion === null ? null : Math.round(completion * 100),
|
||||
next: nextPhase(phases, groups.groups, checklist.found),
|
||||
pending: phases
|
||||
.filter((p) => p.checklist && p.checklist !== "complete" && p.checklist !== "assumed")
|
||||
.map((p) => ({ number: p.number, name: p.name, state: p.checklist, tasks: p.tasks ? p.tasks.total : null, open: p.tasks ? p.tasks.open : null, goal: p.goal })),
|
||||
checks,
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Implementation Mode's phase-selection table, applied mechanically.
|
||||
* 2+ workable phases in the same parallel group, consecutive -> choose (warn if all [/])
|
||||
* a single [/] -> ask-resume · a single [ ] -> auto-start · nothing workable -> none
|
||||
*/
|
||||
function nextPhase(phases, groups, haveChecklist) {
|
||||
if (!haveChecklist) return { action: "none", reason: "no Phase Checklist in overview.md" };
|
||||
const ordered = phases.filter((p) => p.checklist);
|
||||
const isDone = (p) => p.checklist === "complete" || p.checklist === "assumed";
|
||||
const workable = ordered.filter((p) => p.checklist === "pending" || p.checklist === "in-progress");
|
||||
if (!workable.length) {
|
||||
return { action: "none", reason: ordered.length && ordered.every(isDone) ? "every phase is complete" : "no [ ] or [/] phase in the Phase Checklist" };
|
||||
}
|
||||
const first = workable[0];
|
||||
const brief = (p) => ({ number: p.number, name: p.name, state: p.checklist, tasks: p.tasks ? p.tasks.total : null });
|
||||
// A blocked [!] phase ahead of the pick is skipped, but never silently.
|
||||
const skipped = ordered.slice(0, ordered.indexOf(first)).filter((p) => !isDone(p)).map(brief);
|
||||
const note = skipped.length ? { skipped, warning: `skipping ${skipped.map((p) => `Phase ${p.number} [${p.state}]`).join(", ")} ahead of it` } : {};
|
||||
const group = groups.find((g) => g.phases.includes(first.number));
|
||||
if (group) {
|
||||
// Consecutive same-group incomplete phases, in checklist order, starting at the first workable one.
|
||||
const run = [];
|
||||
for (const p of ordered.slice(ordered.indexOf(first))) {
|
||||
if (!group.phases.includes(p.number)) break;
|
||||
if (isDone(p)) continue;
|
||||
if (p.checklist === "pending" || p.checklist === "in-progress") run.push(p);
|
||||
else break;
|
||||
}
|
||||
if (run.length >= 2) {
|
||||
const allStarted = run.every((p) => p.checklist === "in-progress");
|
||||
const warnings = [
|
||||
...(allStarted ? ["every option is already [/]: another agent may be working on it, so picking one risks duplicated work"] : []),
|
||||
...(note.warning ? [note.warning] : []),
|
||||
];
|
||||
return {
|
||||
action: "choose",
|
||||
group: group.id,
|
||||
options: run.map(brief),
|
||||
...(note.skipped ? { skipped: note.skipped } : {}),
|
||||
...(warnings.length ? { warning: warnings.join("; ") } : {}),
|
||||
};
|
||||
}
|
||||
}
|
||||
return { action: first.checklist === "in-progress" ? "ask-resume" : "auto-start", phase: brief(first), ...note };
|
||||
}
|
||||
|
||||
/* --------------------------------------------------------------- commands */
|
||||
|
||||
async function cmdList(args) {
|
||||
const root = path.resolve(args.root || ".");
|
||||
const { scanProject } = await consoleLib();
|
||||
const scan = scanProject(root);
|
||||
const specs = scan.specs.map((s) => {
|
||||
const dir = path.join(root, s.dir);
|
||||
let names = [];
|
||||
try {
|
||||
names = fs.readdirSync(dir);
|
||||
} catch {}
|
||||
return {
|
||||
dir: s.dir,
|
||||
name: s.name,
|
||||
state: s.state,
|
||||
detail: s.detail,
|
||||
touched: s.touched ? new Date(s.touched).toISOString() : null,
|
||||
planDrafts: planDrafts(dir),
|
||||
overview: names.includes("overview.md"),
|
||||
phaseFiles: names.filter((n) => /^phase-\d+\b.*\.md$/i.test(n)).length,
|
||||
pathfinder: isDir(path.join(dir, "pathfinder")),
|
||||
};
|
||||
});
|
||||
let completed = [];
|
||||
try {
|
||||
completed = fs.readdirSync(path.join(root, "specs--completed")).filter((n) => isDir(path.join(root, "specs--completed", n))).sort();
|
||||
} catch {}
|
||||
out({
|
||||
ok: true,
|
||||
root,
|
||||
hasAgents: scan.hasAgents,
|
||||
specsDir: isDir(path.join(root, "specs")),
|
||||
specs,
|
||||
completed,
|
||||
...(specs.length ? {} : { note: "No active specs under specs/." }),
|
||||
});
|
||||
}
|
||||
|
||||
async function cmdStatus(args) {
|
||||
const root = path.resolve(args.root || ".");
|
||||
out(specStatus(resolveSpec(root, args._[1], { allowArchived: true })));
|
||||
}
|
||||
|
||||
function countVerificationAdded(dir) {
|
||||
let n = 0;
|
||||
for (const name of fs.readdirSync(dir)) {
|
||||
if (!/\.md$/i.test(name) || /^PLAN-/i.test(name)) continue;
|
||||
n += ((readText(path.join(dir, name)) || "").match(/<!--\s*VERIFICATION:\s*Added\b/gi) || []).length;
|
||||
}
|
||||
return n;
|
||||
}
|
||||
|
||||
async function cmdMetrics(args) {
|
||||
const root = path.resolve(args.root || ".");
|
||||
const spec = resolveSpec(root, args._[1], { allowArchived: true });
|
||||
const step = args.step;
|
||||
if (step !== "document" && step !== "finalize") fail(EXIT.USAGE, "bad-step", "--step must be document or finalize.", "Plan's METRICS_JSON is written by hand in its Phase 7.");
|
||||
const sets = {};
|
||||
for (const kv of args.set || []) {
|
||||
const m = kv.match(/^([a-z_]+)=(-?\d+(?:\.\d+)?)$/);
|
||||
if (!m) fail(EXIT.USAGE, "bad-set", `--set ${kv} is not key=number.`, "Example: --set verification_failures_found=1");
|
||||
sets[m[1]] = Number(m[2]);
|
||||
}
|
||||
// --set supplies the judgment fields only; the computed ones are never overridden.
|
||||
const SETTABLE = { document: ["verification_items_added"], finalize: ["verification_failures_found", "documentation_updates_needed"] };
|
||||
for (const k of Object.keys(sets)) {
|
||||
if (!SETTABLE[step].includes(k)) fail(EXIT.USAGE, "bad-set", `--set ${k} is not a field you supply for --step ${step}.`, `Only ${SETTABLE[step].join(", ")}; the rest is computed from the files.`);
|
||||
}
|
||||
const st = specStatus(spec);
|
||||
const withTasks = st.phases.filter((p) => p.tasks);
|
||||
let metrics;
|
||||
let hint;
|
||||
if (step === "document") {
|
||||
// verification_items_added is the Added total of the Verification Summary
|
||||
// you presented, not something the files record, so it comes from --set.
|
||||
// The <!-- VERIFICATION: Added --> comments are a cross-check only.
|
||||
if (!("verification_items_added" in sets)) fail(EXIT.USAGE, "missing-set", "document needs --set verification_items_added=N (the Added column total of your Verification Summary).", `The spec has ${countVerificationAdded(spec.dir)} <!-- VERIFICATION: Added --> comment(s), as a cross-check.`);
|
||||
metrics = {
|
||||
step: "document",
|
||||
total_tasks: st.totals.total,
|
||||
tasks_per_phase: withTasks.map((p) => p.tasks.total),
|
||||
phase_count: st.phases.length,
|
||||
parallel_groups_identified: st.parallelGroups.length,
|
||||
...sets,
|
||||
};
|
||||
hint = { verificationCommentsFound: countVerificationAdded(spec.dir) };
|
||||
} else {
|
||||
const missing = ["verification_failures_found", "documentation_updates_needed"].filter((k) => !(k in sets));
|
||||
if (missing.length) fail(EXIT.USAGE, "missing-set", `finalize needs ${missing.map((k) => `--set ${k}=N`).join(" and ")}.`, "Those two counts are your judgment from Steps 2 and 4.");
|
||||
metrics = {
|
||||
step: "finalize",
|
||||
completion_rate_at_audit: st.completion === null ? 0 : Number(st.completion.toFixed(2)),
|
||||
tasks_completed: st.totals.completed,
|
||||
tasks_total: st.totals.total,
|
||||
...sets,
|
||||
};
|
||||
}
|
||||
out({ ok: true, spec: spec.rel, metrics, comment: `<!-- METRICS_JSON ${spacedJson(metrics)} -->`, ...(hint || {}), checks: st.checks.filter((c) => c.level === "error") });
|
||||
}
|
||||
|
||||
// The house style of every METRICS_JSON comment: {"key": value, "list": [1, 2]}.
|
||||
function spacedJson(obj) {
|
||||
const v = (x) => (Array.isArray(x) ? `[${x.map(v).join(", ")}]` : x && typeof x === "object" ? spacedJson(x) : JSON.stringify(x));
|
||||
return `{${Object.entries(obj).map(([k, x]) => `${JSON.stringify(k)}: ${v(x)}`).join(", ")}}`;
|
||||
}
|
||||
|
||||
const TO = { open: " ", "in-progress": "/", done: "x" };
|
||||
|
||||
async function cmdMark(args) {
|
||||
const root = path.resolve(args.root || ".");
|
||||
const spec = resolveSpec(root, args._[1]);
|
||||
const number = Number(args.phase);
|
||||
if (!Number.isInteger(number) || number < 0) fail(EXIT.USAGE, "bad-phase", "--phase needs a phase number.", "Example: --phase 2");
|
||||
if (!(args.to in TO)) fail(EXIT.USAGE, "bad-to", "--to must be open, in-progress or done.", "open = [ ], in-progress = [/], done = [x]");
|
||||
const overviewPath = path.join(spec.dir, "overview.md");
|
||||
const overview = readText(overviewPath);
|
||||
if (overview === null) fail(EXIT.NOT_FOUND, "no-overview", `${spec.rel} has no overview.md.`, "Run /plan2code-2-document first.");
|
||||
const checklist = parseChecklist(overview);
|
||||
const rows = checklist.phases.filter((p) => p.number === number);
|
||||
const row = rows[0];
|
||||
if (!row) fail(EXIT.NOT_FOUND, "no-row", `overview.md's Phase Checklist has no row for Phase ${number}.`, "Run `specs.mjs status` to see the phases it lists.");
|
||||
if (rows.length > 1) fail(EXIT.REFUSED, "duplicate-row", `Phase ${number} has ${rows.length} rows in the Phase Checklist (lines ${rows.map((r) => r.line).join(", ")}); marking one would be a guess.`, "Remove the duplicate row, then rerun.");
|
||||
const target = TO[args.to];
|
||||
if (row.marker === "/" && target === " ") {
|
||||
fail(EXIT.REFUSED, "no-reset", `Phase ${number} is [/]; started work is never reset to [ ].`, "Leave it [/] (a later session resumes it), or mark it done once approved.");
|
||||
}
|
||||
const changes = [];
|
||||
const lines = overview.split(/\r?\n/);
|
||||
const idx = row.line - 1;
|
||||
const next = lines[idx].replace(/\[(.)\]/, `[${target}]`);
|
||||
if (next !== lines[idx]) {
|
||||
lines[idx] = next;
|
||||
changes.push({ file: `${spec.rel}/overview.md`, line: row.line, from: `[${row.marker}]`, to: `[${target}]` });
|
||||
}
|
||||
// The phase file's Status line follows: done -> Complete; re-opening a Complete
|
||||
// phase -> In Progress (revise-plan), so the two files never disagree.
|
||||
let phaseText = null;
|
||||
let phasePath = null;
|
||||
let unfinished = [];
|
||||
const warnings = [];
|
||||
const file = phaseFiles(spec.dir).get(number);
|
||||
if (file) {
|
||||
phasePath = path.join(spec.dir, file);
|
||||
const text = readText(phasePath) || "";
|
||||
const parsed = parsePhaseFile(phasePath, number);
|
||||
unfinished = parsed.tasks.filter((t) => ["pending", "in-progress", "unknown"].includes(t.state)).map((t) => t.id);
|
||||
const status = statusOf(text);
|
||||
const want = target === "x" ? "Complete" : target === " " && status && /^complete$/i.test(status) ? "In Progress" : null;
|
||||
if (status && want && status !== want) {
|
||||
phaseText = text.replace(STATUS_RE, (_, before, _value, after) => before + want + after);
|
||||
changes.push({ file: `${spec.rel}/${file}`, field: "Status", from: status, to: want });
|
||||
}
|
||||
// done and open keep the Status line in step; with none to find, say so.
|
||||
if (!status && target !== "/") warnings.push(`${file} has no Status line, so only the Phase Checklist checkbox changed; add a "**Status:** <value>" line under its title.`);
|
||||
}
|
||||
if (!args["dry-run"]) {
|
||||
if (changes.some((c) => c.file.endsWith("overview.md"))) fs.writeFileSync(overviewPath, lines.join(eol(overview)));
|
||||
if (phaseText !== null) fs.writeFileSync(phasePath, phaseText);
|
||||
}
|
||||
const doneEarly = target === "x" && unfinished.length > 0;
|
||||
if (doneEarly) warnings.unshift(`Phase ${number} was marked done with ${unfinished.length} unfinished task(s): ${unfinished.join(", ")}. Mark only a phase the user approved.`);
|
||||
out({
|
||||
ok: true,
|
||||
spec: spec.rel,
|
||||
phase: number,
|
||||
name: row.name,
|
||||
dryRun: !!args["dry-run"],
|
||||
changed: changes.length > 0,
|
||||
changes,
|
||||
...(warnings.length ? { warning: warnings.join(" ") } : {}),
|
||||
...(doneEarly ? { unfinished } : {}),
|
||||
});
|
||||
}
|
||||
|
||||
function listRel(dir, base = dir) {
|
||||
const outList = [];
|
||||
for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
|
||||
const p = path.join(dir, e.name);
|
||||
if (e.isDirectory()) outList.push(...listRel(p, base));
|
||||
else outList.push(rel(base, p));
|
||||
}
|
||||
return outList.sort();
|
||||
}
|
||||
|
||||
async function cmdArchive(args) {
|
||||
const root = path.resolve(args.root || ".");
|
||||
const spec = resolveSpec(root, args._[1]);
|
||||
const target = path.join(root, "specs--completed", spec.name);
|
||||
if (fs.existsSync(target)) {
|
||||
fail(EXIT.REFUSED, "target-exists", `specs--completed/${spec.name}/ already exists; nothing was moved.`, "Ask the user whether to merge by hand or archive under another name.");
|
||||
}
|
||||
const files = listRel(spec.dir);
|
||||
if (!args["dry-run"]) {
|
||||
fs.mkdirSync(path.dirname(target), { recursive: true });
|
||||
try {
|
||||
fs.renameSync(spec.dir, target);
|
||||
} catch (err) {
|
||||
// A rename across volumes (or a locked file on Windows) fails; copy then remove.
|
||||
try {
|
||||
fs.cpSync(spec.dir, target, { recursive: true, errorOnExist: true, force: false });
|
||||
} catch (copyErr) {
|
||||
fail(EXIT.INVALID, "archive-failed", `Could not move or copy ${spec.rel} (${err.code || err.message}; copy: ${copyErr.code || copyErr.message}).`, `Close anything holding files in ${spec.rel} open, check specs--completed/${spec.name} for a partial copy, then rerun.`);
|
||||
}
|
||||
try {
|
||||
fs.rmSync(spec.dir, { recursive: true, force: true });
|
||||
} catch (rmErr) {
|
||||
fail(EXIT.INVALID, "source-not-removed", `Copied to specs--completed/${spec.name}/ but could not remove ${spec.rel} (${rmErr.code || rmErr.message}); both copies now exist.`, `Close whatever holds files in ${spec.rel} open, then delete it by hand. The archive is complete.`);
|
||||
}
|
||||
}
|
||||
}
|
||||
const sourceGone = args["dry-run"] ? null : !fs.existsSync(spec.dir);
|
||||
const moved = args["dry-run"] ? null : listRel(target);
|
||||
if (!args["dry-run"] && !(sourceGone && moved.length === files.length)) {
|
||||
fail(
|
||||
EXIT.INVALID,
|
||||
"archive-unverified",
|
||||
`The move of ${spec.rel} to specs--completed/${spec.name}/ did not verify: ${moved.length} of ${files.length} file(s) at the target, and ${spec.rel} ${sourceGone ? "is gone" : "still exists"}.`,
|
||||
`Compare ${spec.rel} with specs--completed/${spec.name}/ and finish the move by hand; archive refuses to rerun while the target exists.`
|
||||
);
|
||||
}
|
||||
out({
|
||||
ok: true,
|
||||
dryRun: !!args["dry-run"],
|
||||
from: spec.rel,
|
||||
to: `specs--completed/${spec.name}`,
|
||||
files,
|
||||
...(args["dry-run"] ? {} : { sourceRemoved: sourceGone, filesAtTarget: moved.length, archivedOn: isoDate() }),
|
||||
});
|
||||
}
|
||||
|
||||
run(USAGE, async (argv) => {
|
||||
const args = parseArgs(argv, { booleans: ["dry-run"], values: ["root", "step", "phase", "to"], lists: ["set"] });
|
||||
const cmd = args._[0];
|
||||
const commands = { list: cmdList, status: cmdStatus, metrics: cmdMetrics, mark: cmdMark, archive: cmdArchive };
|
||||
if (!commands[cmd]) fail(EXIT.USAGE, "unknown-command", cmd ? `Unknown command "${cmd}".` : "No command given.", "Commands: list, status, metrics, mark, archive. Run with --help.");
|
||||
await commands[cmd](args);
|
||||
});
|
||||
@@ -0,0 +1,22 @@
|
||||
{
|
||||
"name": "Plan2Code",
|
||||
"version": "2.4.1",
|
||||
"description": "A structured 4-step workflow methodology for AI-assisted software development",
|
||||
"keywords": [
|
||||
"ai",
|
||||
"workflow",
|
||||
"development",
|
||||
"planning",
|
||||
"implementation",
|
||||
"plan"
|
||||
],
|
||||
"author": "Justin Parker",
|
||||
"license": "MIT",
|
||||
"repository": {
|
||||
"type": "git",
|
||||
"url": "https://github.com/jparkerweb/plan2code"
|
||||
},
|
||||
"homepage": "https://github.com/jparkerweb/plan2code",
|
||||
"releaseDate": "2026-10-04",
|
||||
"mode": "utility"
|
||||
}
|
||||
@@ -16,6 +16,14 @@ Technical writer transforming planning documents into precise, complete implemen
|
||||
|
||||
The FIRST thing you do, before anything else — before Auto-Discovery: ask **web console** (suggested) or **terminal**? Console → run `node "<D>/console.mjs" open --workflow document` before reading (<D>: references/web-console/ beside this SKILL.md, or the dir in ~/.plan2code/console/console-dir; `--spec` once known), then <D>/console.md → Documentation. Switchable anytime. `--web` or `Use the web console for this session.` in the argument answers it; drop the flag. Dashboard-launched? Resume its open session (console.md → Launches), then Auto-Discovery. `__stop` ends it; post `finish` BEFORE `stop` at every end.
|
||||
|
||||
## Scripts
|
||||
|
||||
`<S>` is `scripts/` beside this SKILL.md (`~/.agents/skills/plan2code-2-document/scripts/` globally). Run from the project root; each prints one JSON object, and on a non-zero exit `next` says what to do.
|
||||
|
||||
- `node "<S>/specs.mjs" list`: every active spec with its `planDrafts` (file and **Status:** line).
|
||||
- `node "<S>/specs.mjs" status <spec>`: once written, the phases, task counts, goals, parallel groups and `checks` the files produce.
|
||||
- `node "<S>/specs.mjs" metrics <spec> --step document --set verification_items_added=<N>`: the METRICS_JSON line.
|
||||
|
||||
## Rules
|
||||
|
||||
- Follow `./AGENTS.md` if it exists
|
||||
@@ -28,11 +36,11 @@ The FIRST thing you do, before anything else — before Auto-Discovery: ask **we
|
||||
|
||||
## Auto-Discovery
|
||||
|
||||
⚠️ IMPORTANT: `specs/` is gitignored — NEVER use Glob (silently fails). Shell only: `ls specs/` (Bash) or `Get-ChildItem specs/` (PS).
|
||||
`specs/` is gitignored, so Glob silently finds nothing there; `specs.mjs` reads it directly.
|
||||
|
||||
**Before asking user for input:**
|
||||
|
||||
1. Run `ls specs/` then check each folder for `PLAN-DRAFT-*.md`
|
||||
1. Run `specs.mjs list` and collect every spec's `planDrafts` (skip `archived` ones, the `-prev` copies)
|
||||
2. **One found:** Use it, inform user: "Found: `specs/<feature>/PLAN-DRAFT-<date>.md`"
|
||||
3. **Multiple found:** List all, ask which to document
|
||||
4. **None found:** Fall back to Required Context below
|
||||
@@ -107,6 +115,7 @@ Line numbers may only appear as SUPPLEMENTAL context alongside a semantic refere
|
||||
- Quick Reference (Key Files, Environment Variables, External Dependencies)
|
||||
7. **Write** each `phase-X.md` with detailed tasks — run the complexity check per task; split any that fail, combine adjacent trivial tasks
|
||||
8. **Analyze** parallel execution eligibility
|
||||
8a. **Check the structure:** `specs.mjs status specs/<feature-name>`. Fix every `error` and `warn` in `checks` (task numbering, a checkbox under Prerequisites or criteria, a checklist row with no phase file), and confirm `phases` and `parallelGroups` read back as you wrote them
|
||||
9. **Verify** all PLAN-DRAFT requirements covered:
|
||||
- 9A: Re-read PLAN-DRAFT as source of truth
|
||||
- 9B: Cross-reference each section against docs
|
||||
@@ -176,13 +185,13 @@ Use kebab-case for feature name (e.g., `user-authentication`).
|
||||
|
||||
### overview.md
|
||||
|
||||
Header: Title, Created date, Source (PLAN-DRAFT path), Status (Not Started | In Progress | Complete).
|
||||
Header: Title, Created date, Source (PLAN-DRAFT path), Status on its own line as `**Status:** <value>` (Not Started | In Progress | Complete).
|
||||
|
||||
Sections: Summary (from Executive Summary), Tech Stack table (exact copy from PLAN-DRAFT), Architecture (Pattern + Component Overview table), Risks and Mitigations table, Success Criteria checklist, Phase Checklist, Parallel Execution Groups table (from analysis), Quick Reference (Key Files, Environment Variables, External Dependencies), Completion Summary (filled during finalization).
|
||||
|
||||
### phase-X.md
|
||||
|
||||
Header: Phase name, Status, Estimated Tasks count.
|
||||
Header: Phase name, Status on its own line as `**Status:** <value>` (Not Started | In Progress | Complete; `specs.mjs mark` updates it), Estimated Tasks count.
|
||||
|
||||
Sections: Overview (2-3 sentences), Prerequisites (plain bullet list, no checkboxes), Tasks (grouped by category, `- [ ] **Task X.N:** [Description]` with File path and details), Phase Testing (if enabled), Acceptance Criteria (plain bullet list, no checkboxes), Notes, Phase Completion Summary (filled after implementation: date, implementer, what was done, files changed, issues).
|
||||
|
||||
@@ -216,13 +225,13 @@ Total tasks: Y
|
||||
Parallel Execution: [Groups or "None - sequential only"]
|
||||
```
|
||||
|
||||
Also append a machine-parseable metrics comment to the END of `overview.md` for the metrics pipeline:
|
||||
Also append a machine-parseable metrics comment to the END of `overview.md` for the metrics pipeline, shaped like:
|
||||
|
||||
```
|
||||
<!-- METRICS_JSON {"step": "document", "total_tasks": 28, "tasks_per_phase": [7, 7, 7, 7], "phase_count": 4, "parallel_groups_identified": 2, "verification_items_added": 3} -->
|
||||
```
|
||||
|
||||
Replace values with actuals. `verification_items_added` = total Added column from the Verification Summary table.
|
||||
Paste the `comment` from `specs.mjs metrics specs/<feature-name> --step document --set verification_items_added=<N>`, where N is the Added column total of your Verification Summary. It counts the tasks, phases and parallel groups from the files.
|
||||
|
||||
**Tell user:**
|
||||
1. What was created (spec files list)
|
||||
@@ -230,7 +239,7 @@ Replace values with actuals. `verification_items_added` = total Added column fro
|
||||
3. Next command: `/plan2code-3-implement-review --web` (quality-gated) or `/plan2code-3-implement --web` (implementation only)
|
||||
4. Start NEW conversation for implementation
|
||||
|
||||
**Phase Overview** — read each `phase-X.md` and present a table: phase name, task count, one-sentence goal. Helps the user plan sessions and identify review gates.
|
||||
**Phase Overview** — present a table from `status`'s `phases`: phase name, task count (`tasks.total`), one-sentence goal (`goal`, tightened if it runs long; write one yourself when it is null). Helps the user plan sessions and identify review gates.
|
||||
|
||||
```
|
||||
⋅
|
||||
|
||||
@@ -556,8 +556,15 @@ enforces it, so never tell someone to keep asking past it.
|
||||
The person can add folders beside the one the session started in (a shared
|
||||
library, a design folder), from the footer's folder label. Together they are
|
||||
the session's **workspace**: context for every skill run in this console
|
||||
session, each folder addressed by a short `@name`. It outlives dashboard hops;
|
||||
a new console session starts with the original folder alone.
|
||||
session, each folder addressed by a short `@name`. It outlives dashboard hops,
|
||||
and it is remembered: every change is saved to `workspaces.json` beside
|
||||
`looks.json` (never into the project), keyed by the folder the session runs
|
||||
in and then by spec. A session with a spec opens on that spec's list, one with
|
||||
none on the project's; a spec with nothing saved starts as a copy of the
|
||||
project's list. The dashboard's picker swaps the list as the selection moves,
|
||||
and a `specDir` you post mid-run takes the current list with it. There is
|
||||
nothing for you to load: `open` prints the list, and a switch of spec on a
|
||||
resume reaches you as ordinary workspace changes on your next `wait`.
|
||||
|
||||
### What you are told
|
||||
|
||||
@@ -767,7 +774,7 @@ that is what the person is there to download. The finish carries no
|
||||
sees the Trail Footer, and without this their last screen promises a question
|
||||
that is never coming.
|
||||
- Post `run` `pathfinder-chart` (id `map`) when a new map is first written,
|
||||
and `pathfinder-research` (id = the question's file slug) as each research
|
||||
and `pathfinder-research` (id = the question's file slug; on `github`, `q<issue-number>`) as each research
|
||||
subagent reports back, or when you resolve a `research` question yourself
|
||||
(Posting an update → Session meter). Other questions score through their
|
||||
answers, so there is nothing to post for them.
|
||||
@@ -820,7 +827,7 @@ know:
|
||||
| 3, Implementation Summary | Written to `overview.md` as usual; mirror it as a doc (marked `saved`) so the page reader sees it land. |
|
||||
| 4, Documentation Review | The proposed-updates table as a doc, and a `multi` naming the documents to update — every option ticked is "approve", unticked ones are skipped. A `review` works instead when the set is all-or-nothing. |
|
||||
| 5, User Feedback | Optional items, `required: false`: the rating as a `choice` of 1 to 10 or a `text`, the three reasons as `text`. The submit-to-maintainer consent is a `confirm`. |
|
||||
| 6, Spec Cleanup | A `confirm` before moving anything, the archive paths in `consequences`. |
|
||||
| 6, Spec Cleanup | A `confirm` before moving anything, the archive paths in `consequences`, and a line that the spec's remembered workspace folders are forgotten too (`console.mjs forget --spec specs/<feature>` after the move). |
|
||||
|
||||
Pass `--spec specs/<feature>` to `open`, or post `specDir` once you know it.
|
||||
Stopping mid-finalize loses nothing
|
||||
|
||||
@@ -41,6 +41,7 @@ import {
|
||||
die,
|
||||
ensureDir,
|
||||
fileStamp,
|
||||
forgetWorkspace,
|
||||
handOff,
|
||||
handleFile,
|
||||
healthOk,
|
||||
@@ -65,6 +66,7 @@ import {
|
||||
readLedger,
|
||||
readWorkspace,
|
||||
reapHandles,
|
||||
rememberedWorkspace,
|
||||
remoteWarning,
|
||||
removeScratch,
|
||||
removeSessions,
|
||||
@@ -73,6 +75,7 @@ import {
|
||||
SESSION_MAX_AGE_MS,
|
||||
sessionDir,
|
||||
sleepSync,
|
||||
specKey,
|
||||
staleScratch,
|
||||
staleSessions,
|
||||
sweepUploads,
|
||||
@@ -317,7 +320,7 @@ async function cmdOpen() {
|
||||
if (launched) appendLedger(dir, { kind: "launch", id: nextLaunchId(readLedger(dir)), workflow: state.workflow });
|
||||
for (const line of ledgerFromPost(dir, openRun, openIssue, state.workflow)) appendLedger(dir, line);
|
||||
} catch {}
|
||||
const workspace = workspaceOnOpen(dir, worktree);
|
||||
const workspace = workspaceOnOpen(dir, worktree, state.specDir);
|
||||
|
||||
// Month-old sessions and scratch files: listed before the print so the
|
||||
// agent can see what went, removed after it so the page waits for nothing.
|
||||
@@ -403,10 +406,11 @@ async function cmdOpen() {
|
||||
* The workspace as `open` hands it to the agent, and the cursor seeded to
|
||||
* match: the agent now has the whole list, so no change up to here is owed.
|
||||
* Read-only on workspace.json, which only the server writes; on a fresh
|
||||
* session the server has not made it yet, so the original folder stands in.
|
||||
* session the server has not made it yet, so what was remembered for this
|
||||
* folder and spec stands in, the same list the server is about to make.
|
||||
*/
|
||||
function workspaceOnOpen(dir, worktree) {
|
||||
const ws = readWorkspace(dir) || initialWorkspace(worktree);
|
||||
function workspaceOnOpen(dir, worktree, specDir) {
|
||||
const ws = readWorkspace(dir) || initialWorkspace(worktree, rememberedWorkspace(worktree, specDir).entry);
|
||||
const missing = ws.folders.filter((f) => !isFolder(f.path)).map((f) => f.id);
|
||||
try {
|
||||
writeWorkspaceCursor(dir, ws.version || 0);
|
||||
@@ -946,6 +950,18 @@ function realNearest(p) {
|
||||
return path.join(fs.realpathSync(existing), path.relative(existing, p));
|
||||
}
|
||||
|
||||
/* --------------------------------------------------------------- forget */
|
||||
|
||||
// Drop the folder list remembered for one spec (Finalize, once the spec is
|
||||
// archived). The project's own list and every other spec's are untouched.
|
||||
function cmdForget() {
|
||||
if (typeof args.spec !== "string" || !args.spec.trim()) die("forget needs --spec specs/<idea>", 2);
|
||||
let spec = specKey(args.spec);
|
||||
if (/\.md$/i.test(spec)) spec = spec.slice(0, spec.lastIndexOf("/"));
|
||||
const worktree = repoRoots().worktree;
|
||||
print({ ok: true, spec, forgot: forgetWorkspace(worktree, spec) });
|
||||
}
|
||||
|
||||
/* ----------------------------------------------------------------- help */
|
||||
|
||||
function cmdHelp() {
|
||||
@@ -961,7 +977,8 @@ port, and the filesystem as transport; this CLI is the whole agent surface.
|
||||
first post. --file is optional, and --title defaults to the
|
||||
project's folder name. Also prints workspace: { folders: [{ name,
|
||||
path, description?, original? }], missing? }, the folders this
|
||||
console session reads as context, addressed as @name.
|
||||
console session reads as context, addressed as @name. The list is
|
||||
remembered per folder and spec in workspaces.json beside looks.json.
|
||||
post --session <sid> --file <patch.json>
|
||||
Merge a patch into the session. Prints terminalLine while the
|
||||
server is live. Exit 3 = rejected; stderr says why. A patch may
|
||||
@@ -988,6 +1005,10 @@ port, and the filesystem as transport; this CLI is the whole agent surface.
|
||||
Copy a cited note attachment into specs/<idea>/attachments/. Prints
|
||||
{ ok, path, link, image, reused }; exit 2 = bad usage, 3 = refused or
|
||||
missing. Paste link as it is.
|
||||
forget --spec specs/<idea>
|
||||
Drop the workspace folders remembered for that spec, in this
|
||||
folder (Finalize, after archiving it). Prints { ok, spec, forgot };
|
||||
forgot is false when nothing was saved. Exit 2 = bad usage.
|
||||
status [--session <sid>] [--all]
|
||||
One session, or every session belonging to this project.
|
||||
stop --session <sid> | --all
|
||||
@@ -1206,6 +1227,7 @@ const COMMANDS = {
|
||||
wait: cmdWait,
|
||||
chat: cmdChat,
|
||||
keep: cmdKeep,
|
||||
forget: cmdForget,
|
||||
status: cmdStatus,
|
||||
stop: cmdStop,
|
||||
help: cmdHelp,
|
||||
|
||||
@@ -178,8 +178,8 @@ function lockStale(lock) {
|
||||
// Run fn while holding the session's state lock, and release it however fn
|
||||
// ends. fn must not call process.exit(): the release would never run, and the
|
||||
// next writer would wait out the stale age.
|
||||
export function withStateLock(dir, fn) {
|
||||
const lock = path.join(dir, STATE_LOCK_FILE);
|
||||
export function withStateLock(dir, fn, lockName = STATE_LOCK_FILE) {
|
||||
const lock = path.join(dir, lockName);
|
||||
const deadline = Date.now() + LOCK_WAIT_MS;
|
||||
let fd = null;
|
||||
for (let attempt = 0; fd === null; attempt++) {
|
||||
@@ -188,7 +188,7 @@ export function withStateLock(dir, fn) {
|
||||
} catch (err) {
|
||||
// EPERM / EACCES: on Windows, a lock being deleted still blocks a create.
|
||||
if (!["EEXIST", "EPERM", "EACCES", "EBUSY"].includes(err.code)) throw err;
|
||||
if (Date.now() > deadline) throw new Error("state.json is busy with another writer; try again");
|
||||
if (Date.now() > deadline) throw new Error(`${lockName.replace(/.lock$/, "")} is busy with another writer; try again`);
|
||||
if (err.code === "EEXIST" && lockStale(lock)) {
|
||||
try {
|
||||
fs.rmSync(lock, { force: true });
|
||||
@@ -487,8 +487,9 @@ export async function removeSessions(sessionsDir, sids) {
|
||||
}
|
||||
|
||||
// The console folder's own files that no sweep may ever remove: the person's
|
||||
// looks and the pointer to this console's directory.
|
||||
export const PROTECTED_CONSOLE_FILES = new Set(["looks.json", "console-dir"]);
|
||||
// looks, the folders remembered per project and spec, and the pointer to
|
||||
// this console's directory.
|
||||
export const PROTECTED_CONSOLE_FILES = new Set(["looks.json", "workspaces.json", "console-dir"]);
|
||||
|
||||
function isScratchName(name) {
|
||||
return (
|
||||
@@ -1619,17 +1620,125 @@ export function readWorkspace(dir) {
|
||||
return readJson(path.join(dir, WORKSPACE_FILE), null);
|
||||
}
|
||||
|
||||
// A fresh workspace: just the original folder, named after itself.
|
||||
export function initialWorkspace(worktree) {
|
||||
// A fresh workspace: the original folder, named after itself, plus whatever
|
||||
// was remembered for this folder and spec (rememberedWorkspace() below).
|
||||
export function initialWorkspace(worktree, remembered = null) {
|
||||
const original = { id: "f0", path: worktree, name: defaultName(worktree), description: "", original: true };
|
||||
if (remembered && remembered.original) {
|
||||
if (remembered.original.name) original.name = remembered.original.name;
|
||||
if (remembered.original.description) original.description = remembered.original.description;
|
||||
}
|
||||
const added = ((remembered && remembered.folders) || []).map((f, i) => ({
|
||||
id: "f" + (i + 1),
|
||||
path: f.path,
|
||||
name: f.name,
|
||||
description: f.description || "",
|
||||
...(f.nested ? { nested: true } : {}),
|
||||
}));
|
||||
return { version: 0, folders: [original, ...added], missing: [], changes: [], remote: "" };
|
||||
}
|
||||
|
||||
/* ------------------------------------------------ remembered workspaces */
|
||||
|
||||
// The folder list outlives the console session: one file for the person,
|
||||
// beside looks.json, keyed by the folder a session runs in and then by spec.
|
||||
// Never under specs/: the paths are this machine's, and the server never
|
||||
// writes into a project.
|
||||
//
|
||||
// { "projects": { "<folded worktree>": {
|
||||
// "path": "<worktree>",
|
||||
// "project": { original, folders, at }, // no spec picked
|
||||
// "specs": { "specs/<name>": { original, folders, at } } } } }
|
||||
//
|
||||
// `original` holds the first folder's name and description only (its path is
|
||||
// always the session's own); `folders` the added ones as { path, name,
|
||||
// description, nested? }. Two writers, the server on every change and
|
||||
// `console.mjs forget`, each a read-modify-write of one key.
|
||||
export const WORKSPACES_FILE = path.join(HOME_DIR, "workspaces.json");
|
||||
|
||||
const foldKey = (p) => {
|
||||
const resolved = path.resolve(String(p || ""));
|
||||
return process.platform === "win32" || process.platform === "darwin" ? resolved.toLowerCase() : resolved;
|
||||
};
|
||||
|
||||
// `specs/<name>` with forward slashes and no trailing slash, or "" for none.
|
||||
export function specKey(specDir) {
|
||||
return String(specDir || "")
|
||||
.trim()
|
||||
.replace(/\\/g, "/")
|
||||
.replace(/^\.\//, "")
|
||||
.replace(/\/+$/, "");
|
||||
}
|
||||
|
||||
function readStore() {
|
||||
const saved = readJson(WORKSPACES_FILE, null);
|
||||
return saved && typeof saved.projects === "object" && saved.projects ? saved : { projects: {} };
|
||||
}
|
||||
|
||||
/**
|
||||
* What was remembered for this folder and spec: `{ entry, from }`, where
|
||||
* `from` is "spec" when the spec has its own list, "project" when it falls
|
||||
* back to the project's (a spec's list starts as a copy of it), and null
|
||||
* when nothing was ever saved.
|
||||
*/
|
||||
export function rememberedWorkspace(worktree, specDir) {
|
||||
const project = readStore().projects[foldKey(worktree)];
|
||||
if (!project) return { entry: null, from: null };
|
||||
const spec = specKey(specDir);
|
||||
if (spec && project.specs && project.specs[spec]) return { entry: project.specs[spec], from: "spec" };
|
||||
return project.project ? { entry: project.project, from: "project" } : { entry: null, from: null };
|
||||
}
|
||||
|
||||
// The workspace's folders as the store keeps them.
|
||||
export function rememberable(ws) {
|
||||
const folders = (ws && ws.folders) || [];
|
||||
const first = folders.find((f) => f.original) || {};
|
||||
return {
|
||||
version: 0,
|
||||
folders: [{ id: "f0", path: worktree, name: defaultName(worktree), description: "", original: true }],
|
||||
missing: [],
|
||||
changes: [],
|
||||
remote: "",
|
||||
original: { name: first.name || "", description: first.description || "" },
|
||||
folders: folders
|
||||
.filter((f) => !f.original)
|
||||
.map((f) => ({ path: f.path, name: f.name, description: f.description || "", ...(f.nested ? { nested: true } : {}) })),
|
||||
at: nowIso(),
|
||||
};
|
||||
}
|
||||
|
||||
// Every server and `console.mjs forget` writes the one file, so each
|
||||
// read-modify-write holds this lock beside it.
|
||||
const WORKSPACES_LOCK = "workspaces.json.lock";
|
||||
|
||||
// Save the list for this folder and spec ("" for the project's own).
|
||||
export function rememberWorkspace(worktree, specDir, ws) {
|
||||
ensureDir(path.dirname(WORKSPACES_FILE));
|
||||
withStateLock(path.dirname(WORKSPACES_FILE), () => saveRemembered(worktree, specDir, ws), WORKSPACES_LOCK);
|
||||
}
|
||||
|
||||
function saveRemembered(worktree, specDir, ws) {
|
||||
const store = readStore();
|
||||
const key = foldKey(worktree);
|
||||
const project = store.projects[key] || { path: path.resolve(worktree) };
|
||||
const spec = specKey(specDir);
|
||||
if (spec) project.specs = { ...(project.specs || {}), [spec]: rememberable(ws) };
|
||||
else project.project = rememberable(ws);
|
||||
store.projects[key] = project;
|
||||
writeJsonAtomic(WORKSPACES_FILE, store);
|
||||
}
|
||||
|
||||
// Drop one spec's list (Finalize, once the spec is archived). True when there was one.
|
||||
export function forgetWorkspace(worktree, specDir) {
|
||||
const spec = specKey(specDir);
|
||||
if (!spec || !fs.existsSync(WORKSPACES_FILE)) return false;
|
||||
return withStateLock(path.dirname(WORKSPACES_FILE), () => dropRemembered(worktree, spec), WORKSPACES_LOCK);
|
||||
}
|
||||
|
||||
function dropRemembered(worktree, spec) {
|
||||
const store = readStore();
|
||||
const project = store.projects[foldKey(worktree)];
|
||||
if (!spec || !project || !project.specs || !project.specs[spec]) return false;
|
||||
delete project.specs[spec];
|
||||
writeJsonAtomic(WORKSPACES_FILE, store);
|
||||
return true;
|
||||
}
|
||||
|
||||
// Single-writer rule: only server.mjs may call this.
|
||||
export function writeWorkspace(dir, ws) {
|
||||
return writeJsonAtomic(path.join(dir, WORKSPACE_FILE), ws);
|
||||
|
||||
@@ -2505,6 +2505,9 @@ a.icon-btn { box-sizing: border-box; text-decoration: none; }
|
||||
actions stay put. */
|
||||
.modal.workspace { max-width: 680px; }
|
||||
.modal.workspace[open] { display: flex; flex-direction: column; max-height: calc(100vh - 48px); }
|
||||
.workspace .modal-blurb { margin-bottom: 6px; }
|
||||
.workspace-scope { margin: 0 0 16px; color: var(--ink-3, var(--ink-2)); font-size: 12.5px; }
|
||||
|
||||
.workspace-list {
|
||||
list-style: none; margin: 0; padding: 0;
|
||||
display: grid; gap: 12px;
|
||||
|
||||
@@ -2542,6 +2542,7 @@ function renderDashboard(main) {
|
||||
const specs = specList();
|
||||
if (specs.length) wrap.appendChild(renderSpecPicker(specs));
|
||||
wrap.appendChild(hideUnavailableToggle());
|
||||
if (!local.launching && !launchScoping) 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
|
||||
@@ -2963,6 +2964,11 @@ async function launchSkill(entry) {
|
||||
// cards that take no spec (utilities, setup) launch untargeted even while
|
||||
// a spec is selected.
|
||||
if (target) action.spec = target.dir;
|
||||
// The skill opens on the folders remembered for what it was launched for.
|
||||
// Held until the launch is in flight: the swap's own frame re-renders the
|
||||
// dashboard, which would otherwise sync back to the picker's spec.
|
||||
launchScoping = true;
|
||||
await syncWorkspaceScope(target ? target.dir : "");
|
||||
try {
|
||||
const res = await fetch("/submit", {
|
||||
method: "POST",
|
||||
@@ -2973,6 +2979,7 @@ async function launchSkill(entry) {
|
||||
}),
|
||||
});
|
||||
if (res.status === 409) {
|
||||
launchScoping = false;
|
||||
pendingResult = true;
|
||||
banner("Your last pick is still being picked up. One moment.", "info");
|
||||
return;
|
||||
@@ -2980,10 +2987,12 @@ async function launchSkill(entry) {
|
||||
if (!res.ok) throw new Error(String(res.status));
|
||||
sound("startSkill");
|
||||
local.launching = { skill: entry.skill, title: entry.title, at: Date.now() };
|
||||
launchScoping = false;
|
||||
pendingResult = true;
|
||||
save();
|
||||
render();
|
||||
} catch {
|
||||
launchScoping = false;
|
||||
banner("That did not go through. Nothing was lost; try again.", "warn");
|
||||
}
|
||||
}
|
||||
@@ -5854,6 +5863,32 @@ async function postJson(url, body) {
|
||||
}
|
||||
}
|
||||
|
||||
/* The workspace follows the dashboard's picker: the folders remembered for
|
||||
the selected spec, or the project's own under "Start from scratch". The
|
||||
server swaps the list and remembers every change after it. */
|
||||
let scopeAsked = null;
|
||||
// True from a launch's scope sync until its send has gone (or failed).
|
||||
let launchScoping = false;
|
||||
async function syncWorkspaceScope(spec) {
|
||||
if (!S || S.workflow !== "dashboard" || gone || !wsFrame) return;
|
||||
const want = spec === undefined ? (selSpec() && selSpec().dir) || "" : spec;
|
||||
if ((wsFrame.scope || "") === want || scopeAsked === want) return;
|
||||
scopeAsked = want;
|
||||
const { status, body } = await postJson("/workspace/scope", { spec: want });
|
||||
if (status === 200 && body && Array.isArray(body.folders)) wsFrame = { ...wsFrame, ...body };
|
||||
scopeAsked = null;
|
||||
if ($("workspace-modal").open) renderWorkspace();
|
||||
}
|
||||
|
||||
// The dialog's "Remembered for" line: whose list this is.
|
||||
function workspaceScopeText() {
|
||||
const scope = (wsFrame && wsFrame.scope) || "";
|
||||
if (!scope) return "Remembered for this project, so your next console session here starts with these folders.";
|
||||
const spec = specList().find((s) => s.dir === scope);
|
||||
const name = spec ? spec.name : scope.split("/").pop();
|
||||
return `Remembered for the ${name} spec, and loaded again whenever it is picked.`;
|
||||
}
|
||||
|
||||
const NAME_RULE = "Names use lowercase letters, numbers and hyphens.";
|
||||
const BROWSE_UNAVAILABLE = "Browse isn't available here — type or paste the path.";
|
||||
// The folder whose Remove is waiting on its inline confirm, by id.
|
||||
@@ -5893,6 +5928,7 @@ function renderWorkspace() {
|
||||
}
|
||||
folders.forEach((f, i) => paintWorkspaceRow(list.children[i], f));
|
||||
$("workspace-browse").hidden = Boolean(wsFrame && wsFrame.remote);
|
||||
$("workspace-scope").textContent = workspaceScopeText();
|
||||
}
|
||||
|
||||
function workspaceRow(f) {
|
||||
|
||||
@@ -833,10 +833,28 @@
|
||||
Click the folder name in the middle of the bottom bar. It shows your
|
||||
folder's name and branch, such as <strong>shop · main</strong>, and
|
||||
<strong>shop + 2 folders · main</strong> once you have added some.
|
||||
The workspace lasts for this console session only: it carries across
|
||||
steps you start from the dashboard, and a new console session starts
|
||||
with just the folder you started in.
|
||||
It carries across steps you start from the dashboard.
|
||||
</p>
|
||||
<h4>Remembered for next time</h4>
|
||||
<ul>
|
||||
<li>
|
||||
Every change is saved as you make it, so the next console session in
|
||||
this folder starts with the same folders.
|
||||
</li>
|
||||
<li>
|
||||
Each spec keeps its own list. The first time you pick a spec on the
|
||||
dashboard it starts as a copy of the project's list (the one shown
|
||||
under <strong>Start from scratch</strong>), and after that the two
|
||||
are separate. Picking a spec loads its list; the line under the
|
||||
dialog's title says whose list you are looking at.
|
||||
</li>
|
||||
<li>
|
||||
The lists live in <code>workspaces.json</code> in your own
|
||||
Plan2Code settings folder, beside your look and feel, never in the
|
||||
project. Finalize offers to forget a spec's list when it archives the
|
||||
spec.
|
||||
</li>
|
||||
</ul>
|
||||
<h4>Adding a folder</h4>
|
||||
<ul>
|
||||
<li>
|
||||
@@ -1363,9 +1381,10 @@
|
||||
<h4>What it counts</h4>
|
||||
<p>
|
||||
Each step you run here adds points: a plan or a set of documents
|
||||
weighs more than a single answered question, and a built phase more
|
||||
still, by how many tasks it completed: a big phase adds more than a
|
||||
small one. Every two questions you answer add a point too, so a long
|
||||
weighs more than a quick task, and a built phase more still, by how
|
||||
many tasks it completed: a big phase adds more than a small one.
|
||||
Every two questions you answer within one step add a point too
|
||||
(rounded down, so a single answer adds nothing), so a long
|
||||
back-and-forth counts for more than a short one. Click the ring to see the count and a list of each step that added
|
||||
points, with what it added. It is a rule of thumb, not a
|
||||
reading of Plan2Code's real memory: long sessions tend to make it
|
||||
@@ -2003,6 +2022,7 @@
|
||||
The folders the agent uses as context this session. It reads the extra ones for
|
||||
reference and only changes them if you ask.
|
||||
</p>
|
||||
<p class="workspace-scope" id="workspace-scope"></p>
|
||||
<ul class="workspace-list" id="workspace-list"></ul>
|
||||
<div class="workspace-add">
|
||||
<label class="workspace-add-label" for="workspace-path">Add a folder</label>
|
||||
|
||||
@@ -45,7 +45,10 @@ import {
|
||||
readLedger,
|
||||
readOverview,
|
||||
readWorkspace,
|
||||
rememberWorkspace,
|
||||
rememberedWorkspace,
|
||||
remoteWarning,
|
||||
specKey,
|
||||
typedCount,
|
||||
withStateLock,
|
||||
writeJsonAtomic,
|
||||
@@ -326,7 +329,9 @@ function workspaceNow() {
|
||||
return ws;
|
||||
}
|
||||
const root = sessionWorktree();
|
||||
const fresh = { ...initialWorkspace(root || PROJECT), remote: remoteWarning().remote || "" };
|
||||
const scope = specKey(stateNow?.specDir);
|
||||
const remembered = root ? rememberedWorkspace(root, scope).entry : null;
|
||||
const fresh = { ...initialWorkspace(root || PROJECT, remembered), scope, remote: remoteWarning().remote || "" };
|
||||
// There but unreadable for now (a scanner's lock): never written over, and
|
||||
// never cached, so the next call reads it again.
|
||||
if (stamp) return workspaceSeen.ws || fresh;
|
||||
@@ -347,13 +352,87 @@ function saveWorkspace(ws) {
|
||||
|
||||
// One change: a new version, an entry in the change log the agent is handed,
|
||||
// the file, and every open page.
|
||||
function bumpWorkspace(ws, change) {
|
||||
function bumpWorkspace(ws, change, { remember = true } = {}) {
|
||||
ws.version = (ws.version || 0) + 1;
|
||||
ws.changes = [...(ws.changes || []), { ...change, version: ws.version }];
|
||||
saveWorkspace(ws);
|
||||
// Remembered for the next console session too. A folder gone missing or
|
||||
// found again is not a change of mind, so it is not saved.
|
||||
if (remember) rememberNow(ws);
|
||||
pushState();
|
||||
}
|
||||
|
||||
function rememberNow(ws) {
|
||||
const root = sessionWorktree();
|
||||
if (!root) return;
|
||||
try {
|
||||
rememberWorkspace(root, ws.scope || "", ws);
|
||||
} catch {}
|
||||
}
|
||||
|
||||
/**
|
||||
* Point the workspace at another spec ("" for the project's own list) and
|
||||
* swap in what was remembered there, logging each difference as a change so
|
||||
* the agent's cursor stays truthful. A spec with nothing saved starts from
|
||||
* the project's list (`seed: "project"`, the dashboard picker) or keeps the
|
||||
* list it has and saves it as the spec's (`seed: "current"`, a spec created
|
||||
* mid-run). Folders keep their ids when their path stays.
|
||||
*/
|
||||
function setScope(ws, spec, seed = "project") {
|
||||
const root = sessionWorktree();
|
||||
const next = specKey(spec);
|
||||
if (!root || (ws.scope || "") === next) return false;
|
||||
const found = rememberedWorkspace(root, next);
|
||||
ws.scope = next;
|
||||
if (next && found.from !== "spec" && seed === "current") {
|
||||
saveWorkspace(ws);
|
||||
rememberNow(ws);
|
||||
pushState();
|
||||
return true;
|
||||
}
|
||||
const want = initialWorkspace(root, found.entry).folders;
|
||||
const byPath = new Map(ws.folders.map((f) => [foldPath(path.resolve(f.path)), f]));
|
||||
const kept = new Set();
|
||||
const folders = [];
|
||||
const changes = [];
|
||||
for (const w of want) {
|
||||
const have = w.original ? ws.folders.find((f) => f.original) : byPath.get(foldPath(path.resolve(w.path)));
|
||||
if (!have) {
|
||||
folders.push({ ...w, id: "pending" });
|
||||
changes.push({ kind: "added", name: w.name, path: w.path, description: w.description });
|
||||
continue;
|
||||
}
|
||||
kept.add(have);
|
||||
if (have.name !== w.name) changes.push({ kind: "renamed", from: have.name, name: w.name, path: have.path });
|
||||
if ((have.description || "") !== (w.description || "")) {
|
||||
changes.push({ kind: "described", name: w.name, path: have.path, description: w.description || "" });
|
||||
}
|
||||
folders.push({ ...have, name: w.name, description: w.description || "" });
|
||||
}
|
||||
for (const f of ws.folders) {
|
||||
if (!kept.has(f)) changes.unshift({ kind: "removed", name: f.name, path: f.path });
|
||||
}
|
||||
ws.folders = folders.filter((f) => f.id !== "pending");
|
||||
for (const f of folders.filter((f) => f.id === "pending")) ws.folders.push({ ...f, id: nextFolderId(ws) });
|
||||
ws.missing = (ws.missing || []).filter((id) => ws.folders.some((f) => f.id === id));
|
||||
if (!changes.length) {
|
||||
saveWorkspace(ws);
|
||||
pushState();
|
||||
}
|
||||
for (const c of changes) bumpWorkspace(ws, c, { remember: false });
|
||||
checkFolders(ws);
|
||||
return true;
|
||||
}
|
||||
|
||||
// A spec posted mid-run (Pathfinder or Plan making its folder, a skill that
|
||||
// learns its spec late) takes the workspace with it.
|
||||
function followSpecDir(state) {
|
||||
const spec = specKey(state && state.specDir);
|
||||
if (!spec || !fileStamp(WORKSPACE_PATH)) return;
|
||||
const ws = workspaceNow();
|
||||
if ((ws.scope || "") !== spec) setScope(ws, spec, "current");
|
||||
}
|
||||
|
||||
function isFolder(p) {
|
||||
try {
|
||||
return fs.statSync(p).isDirectory();
|
||||
@@ -370,10 +449,10 @@ function checkFolders(ws) {
|
||||
const marked = ws.missing.includes(f.id);
|
||||
if (!there && !marked) {
|
||||
ws.missing = [...ws.missing, f.id];
|
||||
bumpWorkspace(ws, { kind: "missing", name: f.name, path: f.path });
|
||||
bumpWorkspace(ws, { kind: "missing", name: f.name, path: f.path }, { remember: false });
|
||||
} else if (there && marked) {
|
||||
ws.missing = ws.missing.filter((id) => id !== f.id);
|
||||
bumpWorkspace(ws, { kind: "found", name: f.name, path: f.path });
|
||||
bumpWorkspace(ws, { kind: "found", name: f.name, path: f.path }, { remember: false });
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -402,8 +481,8 @@ function folderIssues(entries) {
|
||||
}
|
||||
|
||||
function workspaceView() {
|
||||
const { folders, missing, remote } = workspaceNow();
|
||||
return { folders, missing: missing || [], remote: remote || "", issues: folderIssues(ledgerEntries()) };
|
||||
const { folders, missing, remote, scope } = workspaceNow();
|
||||
return { folders, missing: missing || [], remote: remote || "", scope: scope || "", issues: folderIssues(ledgerEntries()) };
|
||||
}
|
||||
|
||||
// Whether child sits strictly under parent.
|
||||
@@ -492,6 +571,7 @@ function bootWorkspace() {
|
||||
saveWorkspace(ws);
|
||||
}
|
||||
checkFolders(ws);
|
||||
followSpecDir(stateNow);
|
||||
}
|
||||
|
||||
/**
|
||||
@@ -1403,6 +1483,24 @@ const server = http.createServer((req, res) => {
|
||||
});
|
||||
}
|
||||
|
||||
// Which list the workspace is: a spec's, or the project's (`spec` empty).
|
||||
// The dashboard's picker sends it as the selection moves and before a
|
||||
// launch, so a skill opens on the list of the spec it was launched for.
|
||||
if (pathname === "/workspace/scope" && req.method === "POST") {
|
||||
if (!originOk(req, port)) return json(res, 403, { error: "bad origin" });
|
||||
return readBody(req, (err, body) => {
|
||||
if (err || !body || typeof body !== "object" || Array.isArray(body)) return json(res, 400, { error: "bad" });
|
||||
const spec = typeof body.spec === "string" ? body.spec : "";
|
||||
if (spec && !/^specs\/[^/\\]+$/.test(specKey(spec))) return json(res, 400, { reason: "bad-spec" });
|
||||
try {
|
||||
setScope(workspaceNow(), spec, "project");
|
||||
} catch (e) {
|
||||
return json(res, 500, { error: String(e.message) });
|
||||
}
|
||||
return json(res, 200, workspaceView());
|
||||
});
|
||||
}
|
||||
|
||||
// Only ever returns a path: the page then adds it through /workspace/add.
|
||||
if (pathname === "/workspace/browse" && req.method === "POST") {
|
||||
if (!originOk(req, port)) return json(res, 403, { error: "bad origin" });
|
||||
@@ -1561,6 +1659,9 @@ function checkState() {
|
||||
try {
|
||||
ensureConversation(parsed);
|
||||
} catch {}
|
||||
try {
|
||||
followSpecDir(parsed);
|
||||
} catch {}
|
||||
pushState();
|
||||
}
|
||||
lastStateStamp = stamp;
|
||||
|
||||
@@ -17,6 +17,6 @@
|
||||
"url": "https://github.com/jparkerweb/plan2code"
|
||||
},
|
||||
"homepage": "https://github.com/jparkerweb/plan2code",
|
||||
"releaseDate": "2026-10-02",
|
||||
"releaseDate": "2026-10-04",
|
||||
"mode": "utility"
|
||||
}
|
||||
@@ -0,0 +1,247 @@
|
||||
// Plan2Code skill scripts: shared plumbing.
|
||||
//
|
||||
// Every script in a skill's scripts/ directory imports this file. It owns the
|
||||
// conventions the SKILL.md prompts rely on, so they are identical everywhere:
|
||||
//
|
||||
// stdout one JSON object, always. `{ "ok": true, ... }` on success,
|
||||
// `{ "ok": false, "error": "<code>", "message": "...", "next": "..." }`
|
||||
// on a handled failure.
|
||||
// stderr a one-line human diagnostic on failure (the same message + next).
|
||||
// exit 0 ok · 1 unexpected crash · 2 bad arguments · 3 not found ·
|
||||
// 4 invalid input or a check that failed · 5 refused (would clobber
|
||||
// or break a rule).
|
||||
//
|
||||
// Node 18+ built-ins only, no build step: this ships inside every skill.
|
||||
|
||||
import fs from "node:fs";
|
||||
import path from "node:path";
|
||||
import { fileURLToPath, pathToFileURL } from "node:url";
|
||||
|
||||
export const HERE = path.dirname(fileURLToPath(import.meta.url));
|
||||
|
||||
export const EXIT = { OK: 0, CRASH: 1, USAGE: 2, NOT_FOUND: 3, INVALID: 4, REFUSED: 5 };
|
||||
|
||||
export class CliError extends Error {
|
||||
constructor(exit, error, message, next) {
|
||||
super(message);
|
||||
this.exit = exit;
|
||||
this.error = error;
|
||||
this.next = next;
|
||||
}
|
||||
}
|
||||
|
||||
/** Throw a handled failure: the run() wrapper prints it and sets the exit code. */
|
||||
export function fail(exit, error, message, next) {
|
||||
throw new CliError(exit, error, message, next);
|
||||
}
|
||||
|
||||
export function out(obj) {
|
||||
process.stdout.write(JSON.stringify(obj, null, 2) + "\n");
|
||||
}
|
||||
|
||||
/**
|
||||
* Parse argv into { _: positionals, <flag>: value }.
|
||||
* `booleans` names flags that take no value; every other `--flag` takes the
|
||||
* next argument, and repeats of a flag listed in `lists` collect into an array.
|
||||
* `--flag=value` works too. Unknown flags are a usage error, so a typo never
|
||||
* silently changes behavior.
|
||||
*/
|
||||
export function parseArgs(argv, { booleans = [], values = [], lists = [] } = {}) {
|
||||
const known = new Set([...booleans, ...values, ...lists, "help"]);
|
||||
const args = { _: [] };
|
||||
for (let i = 0; i < argv.length; i++) {
|
||||
const a = argv[i];
|
||||
if (!a.startsWith("--")) {
|
||||
args._.push(a);
|
||||
continue;
|
||||
}
|
||||
let name = a.slice(2);
|
||||
let value;
|
||||
const eq = name.indexOf("=");
|
||||
if (eq !== -1) {
|
||||
value = name.slice(eq + 1);
|
||||
name = name.slice(0, eq);
|
||||
}
|
||||
if (!known.has(name)) {
|
||||
fail(EXIT.USAGE, "unknown-flag", `Unknown flag --${name}.`, "Run with --help for the flags this script takes.");
|
||||
}
|
||||
if (name === "help" || booleans.includes(name)) {
|
||||
args[name] = true;
|
||||
continue;
|
||||
}
|
||||
if (value === undefined) {
|
||||
if (i + 1 >= argv.length) {
|
||||
fail(EXIT.USAGE, "missing-value", `--${name} needs a value.`, "Run with --help for usage.");
|
||||
}
|
||||
value = argv[++i];
|
||||
}
|
||||
if (lists.includes(name)) (args[name] ||= []).push(value);
|
||||
else args[name] = value;
|
||||
}
|
||||
return args;
|
||||
}
|
||||
|
||||
/**
|
||||
* Run a script's main(). Prints usage on --help, turns CliError into the JSON
|
||||
* failure shape plus an exit code, and anything else into exit 1 with the stack
|
||||
* on stderr. Sets process.exitCode rather than calling process.exit(), so
|
||||
* stdout is never cut off mid-write.
|
||||
*/
|
||||
export async function run(usage, main) {
|
||||
try {
|
||||
const argv = process.argv.slice(2);
|
||||
if (argv.includes("--help") || argv.includes("-h")) {
|
||||
process.stdout.write(usage.trim() + "\n");
|
||||
return;
|
||||
}
|
||||
await main(argv);
|
||||
} catch (err) {
|
||||
if (err instanceof CliError) {
|
||||
out({ ok: false, error: err.error, message: err.message, ...(err.next ? { next: err.next } : {}) });
|
||||
process.stderr.write(`error: ${err.message}${err.next ? `\nnext: ${err.next}` : ""}\n`);
|
||||
process.exitCode = err.exit;
|
||||
return;
|
||||
}
|
||||
process.stderr.write(`unexpected error: ${err && err.stack ? err.stack : err}\n`);
|
||||
out({ ok: false, error: "crash", message: String(err && err.message ? err.message : err) });
|
||||
process.exitCode = EXIT.CRASH;
|
||||
}
|
||||
}
|
||||
|
||||
/* ------------------------------------------------------------------ time */
|
||||
|
||||
// PLAN2CODE_NOW ("YYYY-MM-DD HH:mm" or any Date-parsable string) pins the
|
||||
// clock, for tests and for reproducing a run. Otherwise: the local clock, which
|
||||
// is what "today" means to the person reading the date in their files.
|
||||
export function now() {
|
||||
const pinned = process.env.PLAN2CODE_NOW;
|
||||
if (pinned) {
|
||||
const m = pinned.match(/^(\d{4})-(\d{2})-(\d{2})(?:[ T](\d{2}):(\d{2})(?::(\d{2}))?)?$/);
|
||||
if (m) return new Date(+m[1], +m[2] - 1, +m[3], +(m[4] || 0), +(m[5] || 0), +(m[6] || 0));
|
||||
const d = new Date(pinned);
|
||||
if (!Number.isNaN(d.getTime())) return d;
|
||||
}
|
||||
return new Date();
|
||||
}
|
||||
|
||||
const pad = (n) => String(n).padStart(2, "0");
|
||||
|
||||
/** YYYY-MM-DD */
|
||||
export function isoDate(d = now()) {
|
||||
return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}`;
|
||||
}
|
||||
|
||||
/** YYYYMMDD */
|
||||
export function compactDate(d = now()) {
|
||||
return isoDate(d).replace(/-/g, "");
|
||||
}
|
||||
|
||||
/** YYYY-MM-DD HH:mm */
|
||||
export function stamp(d = now()) {
|
||||
return `${isoDate(d)} ${pad(d.getHours())}:${pad(d.getMinutes())}`;
|
||||
}
|
||||
|
||||
/** HHMMSS */
|
||||
export function clock(d = now()) {
|
||||
return `${pad(d.getHours())}${pad(d.getMinutes())}${pad(d.getSeconds())}`;
|
||||
}
|
||||
|
||||
/* ----------------------------------------------------------------- files */
|
||||
|
||||
export function readText(file) {
|
||||
try {
|
||||
return fs.readFileSync(file, "utf8");
|
||||
} catch {
|
||||
return null;
|
||||
}
|
||||
}
|
||||
|
||||
export function isDir(p) {
|
||||
try {
|
||||
return fs.statSync(p).isDirectory();
|
||||
} catch {
|
||||
return false;
|
||||
}
|
||||
}
|
||||
|
||||
/** Write a file only when its content changes. Returns true when it wrote. */
|
||||
export function writeIfChanged(file, content) {
|
||||
const current = readText(file);
|
||||
if (current === content) return false;
|
||||
fs.mkdirSync(path.dirname(file), { recursive: true });
|
||||
fs.writeFileSync(file, content);
|
||||
return true;
|
||||
}
|
||||
|
||||
/** Normalise line endings for parsing; keep the original for writing back. */
|
||||
export function eol(text) {
|
||||
return text.includes("\r\n") ? "\r\n" : "\n";
|
||||
}
|
||||
|
||||
/**
|
||||
* phase-N.md per phase number. An exact phase-N.md always wins over a sibling
|
||||
* such as phase-1-old.md; more than one candidate is reported, never guessed.
|
||||
* Shared so every script that counts a spec's tasks reads the same files.
|
||||
*/
|
||||
export function phaseFiles(dir) {
|
||||
const files = new Map();
|
||||
const extra = new Map();
|
||||
for (const name of fs.readdirSync(dir).sort()) {
|
||||
const m = name.match(/^phase-(\d+)\b[^/]*\.md$/i);
|
||||
if (!m) continue;
|
||||
const n = Number(m[1]);
|
||||
const exact = new RegExp(`^phase-0*${n}\\.md$`, "i").test(name);
|
||||
if (!files.has(n)) files.set(n, name);
|
||||
else if (exact) {
|
||||
(extra.get(n) || extra.set(n, []).get(n)).push(files.get(n));
|
||||
files.set(n, name);
|
||||
} else (extra.get(n) || extra.set(n, []).get(n)).push(name);
|
||||
}
|
||||
files.extra = extra;
|
||||
return files;
|
||||
}
|
||||
|
||||
/** Forward-slash path relative to root, for output the agent pastes into prompts. */
|
||||
export function rel(root, p) {
|
||||
return path.relative(root, p).split(path.sep).join("/") || ".";
|
||||
}
|
||||
|
||||
/* --------------------------------------------------------- the web console */
|
||||
|
||||
// The web console ships beside these scripts in every installed skill
|
||||
// (references/web-console/), and in this repo it sits at src/web-console/. Its
|
||||
// lib.mjs is the one home of the spec-state classifier and the loop-marker /
|
||||
// metrics-bait scan, so the scripts import it rather than keep a second copy.
|
||||
const CONSOLE_LIB_CANDIDATES = [
|
||||
path.join(HERE, "..", "references", "web-console", "lib.mjs"), // installed skill
|
||||
path.join(HERE, "..", "web-console", "lib.mjs"), // src/skill-scripts in the repo
|
||||
];
|
||||
|
||||
let consoleLibPromise;
|
||||
export function consoleLib() {
|
||||
consoleLibPromise ||= (async () => {
|
||||
for (const candidate of CONSOLE_LIB_CANDIDATES) {
|
||||
if (fs.existsSync(candidate)) return import(pathToFileURL(candidate).href);
|
||||
}
|
||||
fail(
|
||||
EXIT.NOT_FOUND,
|
||||
"console-lib-missing",
|
||||
`The web console's lib.mjs is not beside this script (looked in ${CONSOLE_LIB_CANDIDATES.join(", ")}).`,
|
||||
"The skill install is incomplete; reinstall the Plan2Code skills (node install.js)."
|
||||
);
|
||||
})();
|
||||
return consoleLibPromise;
|
||||
}
|
||||
|
||||
/** The version these scripts shipped with (scripts/version.json, or the repo's). */
|
||||
export function version() {
|
||||
for (const file of [path.join(HERE, "version.json"), path.join(HERE, "..", "..", "version.json")]) {
|
||||
const text = readText(file);
|
||||
if (!text) continue;
|
||||
try {
|
||||
const v = JSON.parse(text).version;
|
||||
if (typeof v === "string") return v;
|
||||
} catch {}
|
||||
}
|
||||
return null;
|
||||
}
|
||||
@@ -0,0 +1,676 @@
|
||||
#!/usr/bin/env node
|
||||
// specs.mjs: where every spec under specs/ stands, read from its files.
|
||||
//
|
||||
// The pipeline skills (plan, document, implement, revise-plan, finalize,
|
||||
// review, handoff) all need the same filesystem facts: which specs exist, what
|
||||
// a spec's PLAN-DRAFT says, which phases are open, how many tasks are done.
|
||||
// Those have one correct answer, so this script computes them instead of each
|
||||
// prompt re-deriving them by hand. It also performs the two mechanical writes
|
||||
// (a Phase Checklist marker, the archive move), with --dry-run.
|
||||
//
|
||||
// Shell listing only matters to people: specs/ is gitignored, so editor search
|
||||
// tools skip it. This script reads the disk directly and does not care.
|
||||
|
||||
import fs from "node:fs";
|
||||
import path from "node:path";
|
||||
import { EXIT, fail, out, parseArgs, run, readText, isDir, rel, eol, consoleLib, isoDate, phaseFiles } from "./common.mjs";
|
||||
|
||||
const USAGE = `
|
||||
specs.mjs: spec state for the Plan2Code pipeline skills. JSON on stdout.
|
||||
|
||||
node specs.mjs list [--root <dir>]
|
||||
Every active spec under specs/ (never specs--completed/), newest first:
|
||||
state, detail, PLAN-DRAFT files with their **Status:** line, overview,
|
||||
phase count. Also the names already archived in specs--completed/.
|
||||
|
||||
node specs.mjs status <spec> [--root <dir>]
|
||||
One spec in full: the overview's Phase Checklist, Parallel Execution
|
||||
Groups, per-phase task counts by marker, task-numbering problems,
|
||||
completion, the implement phase-selection verdict ("next"), the pending
|
||||
phases, and consistency checks. <spec> is specs/<name>, <name>, or a path
|
||||
to its overview.md.
|
||||
|
||||
node specs.mjs metrics <spec> --step document|finalize [--set key=value ...]
|
||||
The METRICS_JSON comment for that step, countable fields computed from
|
||||
the files; judgment fields come from --set (numbers only).
|
||||
document: total_tasks, tasks_per_phase, phase_count,
|
||||
parallel_groups_identified computed; pass
|
||||
--set verification_items_added=N (your Verification Summary's
|
||||
Added total; the VERIFICATION comments are reported as a check).
|
||||
finalize: completion_rate_at_audit, tasks_completed, tasks_total; pass
|
||||
--set verification_failures_found=N
|
||||
--set documentation_updates_needed=N.
|
||||
|
||||
node specs.mjs mark <spec> --phase <N> --to open|in-progress|done [--dry-run]
|
||||
Set phase N's Phase Checklist marker in overview.md ([ ], [/], [x]).
|
||||
done also sets the phase file's Status line (**Status:**, **Status**:
|
||||
or Status:) to Complete (and warns if tasks are unfinished); open on a
|
||||
Complete phase sets it to In Progress. Warns when the phase file has no
|
||||
Status line. Refuses a phase with duplicate checklist rows, and refuses
|
||||
in-progress -> open (started work stays marked).
|
||||
|
||||
node specs.mjs archive <spec> [--dry-run]
|
||||
Move specs/<name>/ to specs--completed/<name>/. Refuses if the target
|
||||
exists, or if <spec> is not a folder directly under specs/.
|
||||
|
||||
Markers: [ ] pending · [/] in progress · [x] complete · [!] blocked · [?] assumed.
|
||||
Exit: 0 ok · 2 bad arguments · 3 spec not found · 4 cannot parse / check
|
||||
failed · 5 refused.
|
||||
`;
|
||||
|
||||
/* ------------------------------------------------------------- resolving */
|
||||
|
||||
function realOrResolved(p) {
|
||||
try {
|
||||
return fs.realpathSync.native(p);
|
||||
} catch {
|
||||
return path.resolve(p);
|
||||
}
|
||||
}
|
||||
|
||||
const samePath = (a, b) => (process.platform === "win32" ? a.toLowerCase() === b.toLowerCase() : a === b);
|
||||
|
||||
// Read-only commands (status, metrics) accept an archived spec, because
|
||||
// Finalize reads its own spec after Step 6 moved it. Writes never do.
|
||||
function resolveSpec(root, arg, { allowArchived = false } = {}) {
|
||||
if (!arg) fail(EXIT.USAGE, "missing-spec", "Name the spec: specs/<name>, <name>, or its overview.md path.", "Run `specs.mjs list` to see the active specs.");
|
||||
let p = arg.replace(/\\/g, "/").replace(/\/+$/, "");
|
||||
if (/\/overview\.md$/i.test(p) || /\/phase-[^/]*\.md$/i.test(p)) p = p.replace(/\/[^/]+$/, "");
|
||||
const abs = path.isAbsolute(p) ? p : p.includes("/") ? path.join(root, p) : path.join(root, "specs", p);
|
||||
const relPath = rel(root, abs);
|
||||
if (!allowArchived && /(^|\/)specs--completed(\/|$)/.test(relPath)) {
|
||||
fail(EXIT.REFUSED, "archived-spec", `${relPath} is archived; the pipeline only changes active specs under specs/.`, "Pick an active spec from `specs.mjs list`.");
|
||||
}
|
||||
// A spec is a folder directly under specs/ (or specs--completed/ for a read).
|
||||
// Without this, `archive .` would move all of specs/ and `archive ./src` a
|
||||
// source folder.
|
||||
const homes = [path.join(root, "specs"), ...(allowArchived ? [path.join(root, "specs--completed")] : [])].map(realOrResolved);
|
||||
const parent = realOrResolved(path.dirname(path.resolve(abs)));
|
||||
if (!homes.some((h) => samePath(h, parent))) {
|
||||
fail(EXIT.REFUSED, "not-a-spec", `${relPath} is not a spec folder: a spec sits directly under specs/${allowArchived ? " (or specs--completed/)" : ""}.`, "Pass specs/<name> or <name>; run `specs.mjs list` to see the active specs.");
|
||||
}
|
||||
if (!isDir(abs)) {
|
||||
fail(EXIT.NOT_FOUND, "spec-not-found", `No spec folder at ${relPath}.`, "Run `specs.mjs list` from the project root (or pass --root) to see the active specs.");
|
||||
}
|
||||
return { dir: abs, rel: relPath, name: path.basename(abs) };
|
||||
}
|
||||
|
||||
/* -------------------------------------------------------------- parsing */
|
||||
|
||||
const MARKERS = { " ": "pending", "/": "in-progress", x: "complete", X: "complete", "!": "blocked", "?": "assumed" };
|
||||
// Task 2.3, a lettered sub-task 3.6a, or a named one such as a testing task 1.T.
|
||||
const TASK_RE = /^\s*[-*] \[(.)\]\s+\*\*Task\s+(\d+)\.(\d+|[A-Za-z]+)([a-z]*)\b/;
|
||||
const CHECKBOX_RE = /^\s*[-*] \[(.)\]/;
|
||||
// The Status line in any of the forms people write it: **Status:**, **Status**:
|
||||
// or a plain Status:, optionally as a list item. Groups: everything up to the
|
||||
// value (kept as written when the value is rewritten), the value, trailing blanks.
|
||||
const STATUS_RE = /^([ \t]*(?:[-*][ \t]*)?(?:\*\*Status:\*\*|\*\*Status\*\*:|Status:)[ \t]*)(.+?)([ \t]*)$/m;
|
||||
|
||||
function statusOf(text) {
|
||||
const m = (text || "").match(STATUS_RE);
|
||||
return m ? m[2] : null;
|
||||
}
|
||||
|
||||
/** A markdown section's lines: from its heading to the next heading of the same or higher level. */
|
||||
function section(text, headingRe) {
|
||||
const lines = text.split(/\r?\n/);
|
||||
const start = lines.findIndex((l) => /^#{1,6}\s/.test(l) && headingRe.test(l));
|
||||
if (start === -1) return null;
|
||||
const level = lines[start].match(/^#+/)[0].length;
|
||||
let end = lines.length;
|
||||
for (let i = start + 1; i < lines.length; i++) {
|
||||
const m = lines[i].match(/^(#+)\s/);
|
||||
if (m && m[1].length <= level) {
|
||||
end = i;
|
||||
break;
|
||||
}
|
||||
}
|
||||
return { start, end, lines: lines.slice(start + 1, end) };
|
||||
}
|
||||
|
||||
function plainText(s) {
|
||||
return s
|
||||
.replace(/\[([^\]]*)\]\([^)]*\)/g, "$1")
|
||||
.replace(/[*_`]/g, "")
|
||||
.replace(/\s+/g, " ")
|
||||
.trim();
|
||||
}
|
||||
|
||||
/** Phase Checklist rows: the first "Phase N" on each checkbox line names the phase. */
|
||||
function parseChecklist(overview) {
|
||||
const sec = section(overview, /Phase Checklist/i);
|
||||
if (!sec) return { found: false, phases: [], unparsed: [] };
|
||||
const phases = [];
|
||||
const unparsed = [];
|
||||
sec.lines.forEach((line, i) => {
|
||||
const m = line.match(CHECKBOX_RE);
|
||||
if (!m) return;
|
||||
const text = plainText(line.replace(CHECKBOX_RE, ""));
|
||||
const num = text.match(/\bPhase\s+(\d+)\b/i);
|
||||
if (!num) {
|
||||
unparsed.push({ line: sec.start + 2 + i, text: line.trim() });
|
||||
return;
|
||||
}
|
||||
const after = text.slice(num.index + num[0].length).replace(/^\s*[:\-–—]\s*/, "");
|
||||
const name = after.split(/\s+[-–—]\s+|\s+\(|\s+_\(|:\s|\s+see\s+phase-/i)[0].replace(/\s*phase-\d+\.md\s*$/i, "").trim();
|
||||
phases.push({
|
||||
number: Number(num[1]),
|
||||
marker: m[1],
|
||||
state: MARKERS[m[1]] || "unknown",
|
||||
name: name.replace(/\s*\[Milestone[^\]]*\]\s*$/i, "") || `Phase ${num[1]}`,
|
||||
line: sec.start + 2 + i,
|
||||
});
|
||||
});
|
||||
return { found: true, phases, unparsed };
|
||||
}
|
||||
|
||||
/** "2, 3", "2-4" and "2–4" (or an em dash) alike: ranges expand, so a group cell never loses a phase. */
|
||||
function phaseList(cell) {
|
||||
const outList = [];
|
||||
for (const part of cell.match(/\d+\s*[-–\u2014]\s*\d+|\d+/g) || []) {
|
||||
const r = part.match(/^(\d+)\s*[-–\u2014]\s*(\d+)$/);
|
||||
if (r && Number(r[2]) >= Number(r[1]) && Number(r[2]) - Number(r[1]) < 100) {
|
||||
for (let n = Number(r[1]); n <= Number(r[2]); n++) outList.push(n);
|
||||
} else outList.push(...part.match(/\d+/g).map(Number));
|
||||
}
|
||||
return [...new Set(outList)];
|
||||
}
|
||||
|
||||
/** Parallel Execution Groups table: real groups only (a named group with 2+ phases). */
|
||||
function parseGroups(overview) {
|
||||
const sec = section(overview, /Parallel Execution Groups/i);
|
||||
if (!sec) return { found: false, groups: [] };
|
||||
const groups = [];
|
||||
const seen = new Set();
|
||||
for (const line of sec.lines) {
|
||||
if (!/^\s*\|/.test(line) || /^\s*\|[\s:|-]+\|\s*$/.test(line)) continue;
|
||||
const cells = line.split("|").slice(1, -1).map((c) => c.trim());
|
||||
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
|
||||
// ("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;
|
||||
const key = `${id}:${phases.join(",")}`;
|
||||
if (seen.has(key)) continue;
|
||||
seen.add(key);
|
||||
groups.push({ id, phases, reason: plainText(cells[2] || "") });
|
||||
}
|
||||
return { found: true, groups };
|
||||
}
|
||||
|
||||
function firstSentence(text) {
|
||||
const t = plainText(text);
|
||||
const m = t.match(/^(.+?[.!?])(\s|$)/);
|
||||
return (m ? m[1] : t).slice(0, 240);
|
||||
}
|
||||
|
||||
function parsePhaseFile(file, number) {
|
||||
const text = readText(file) || "";
|
||||
const lines = text.split(/\r?\n/);
|
||||
const title = (lines.find((l) => /^#\s/.test(l)) || "").replace(/^#\s+/, "").trim();
|
||||
const status = statusOf(text);
|
||||
const counts = { pending: 0, "in-progress": 0, complete: 0, blocked: 0, assumed: 0, unknown: 0 };
|
||||
const tasks = [];
|
||||
const strayCheckboxes = [];
|
||||
const unmatchedTasks = [];
|
||||
let heading = "";
|
||||
lines.forEach((line, i) => {
|
||||
const h = line.match(/^#{1,6}\s+(.*)$/);
|
||||
if (h) heading = plainText(h[1]);
|
||||
const t = line.match(TASK_RE);
|
||||
if (t) {
|
||||
const state = MARKERS[t[1]] || "unknown";
|
||||
counts[state]++;
|
||||
const named = !/^\d+$/.test(t[3]);
|
||||
tasks.push({ id: `${t[2]}.${t[3]}${t[4]}`, phase: Number(t[2]), seq: named ? null : Number(t[3]), named, suffix: t[4], marker: t[1], state, line: i + 1 });
|
||||
return;
|
||||
}
|
||||
// A line that looks like a task but is not counted as one (Task 1.4A,
|
||||
// "1. [ ] **Task", a non-bold "- [ ] Task 1.3") would make the audit undercount.
|
||||
if (/^\s*(?:[-*]|\d+\.)\s+\[.\].*\bTask\s+\d+\./i.test(line)) unmatchedTasks.push({ line: i + 1, text: line.trim().slice(0, 120) });
|
||||
if (CHECKBOX_RE.test(line)) strayCheckboxes.push({ line: i + 1, section: heading, text: line.trim().slice(0, 120) });
|
||||
});
|
||||
|
||||
// Numbering: every task belongs to this phase, the base numbers run 1..n with
|
||||
// no gaps or repeats, and a lettered task (3.6a) sits after its base (3.6).
|
||||
// Named tasks (1.T) are outside the numeric sequence.
|
||||
const numbering = [];
|
||||
const bases = [];
|
||||
for (const t of tasks) {
|
||||
if (t.phase !== number) numbering.push(`Task ${t.id} is in phase-${number}.md but numbered for Phase ${t.phase}`);
|
||||
if (!t.suffix && !t.named) bases.push(t.seq);
|
||||
}
|
||||
const seenIds = new Set();
|
||||
for (const t of tasks) {
|
||||
if (seenIds.has(t.id)) numbering.push(`Task ${t.id} appears more than once`);
|
||||
seenIds.add(t.id);
|
||||
if (t.suffix && !t.named && !bases.includes(t.seq)) numbering.push(`Task ${t.id} has no base Task ${t.phase}.${t.seq}`);
|
||||
}
|
||||
bases.forEach((seq, i) => {
|
||||
if (seq !== i + 1 && !numbering.some((n) => n.startsWith("Task numbering"))) {
|
||||
numbering.push(`Task numbering is not sequential: expected ${number}.${i + 1}, found ${number}.${seq}`);
|
||||
}
|
||||
});
|
||||
|
||||
const overviewSec = section(text, /^#{1,6}\s+Overview\b/i);
|
||||
const goalText = overviewSec ? overviewSec.lines.join("\n").split(/\n\s*\n/).map((p) => p.trim()).find((p) => p && !/^[-*|>]/.test(p)) : "";
|
||||
return {
|
||||
title,
|
||||
status,
|
||||
goal: goalText ? firstSentence(goalText) : null,
|
||||
total: tasks.length,
|
||||
counts,
|
||||
open: counts.pending + counts["in-progress"] + counts.blocked + counts.unknown,
|
||||
// Open work a phase cannot be approved over; blocked tasks may stand ([!] is allowed at sign-off).
|
||||
unfinished: counts.pending + counts["in-progress"] + counts.unknown,
|
||||
tasks,
|
||||
numbering,
|
||||
strayCheckboxes,
|
||||
unmatchedTasks,
|
||||
};
|
||||
}
|
||||
|
||||
function planDrafts(dir) {
|
||||
return fs
|
||||
.readdirSync(dir)
|
||||
.filter((n) => /^PLAN-DRAFT.*\.md$/i.test(n))
|
||||
.sort()
|
||||
.map((file) => ({
|
||||
file,
|
||||
archived: /-prev\.md$/i.test(file),
|
||||
status: statusOf(readText(path.join(dir, file))),
|
||||
}));
|
||||
}
|
||||
|
||||
/* ---------------------------------------------------------------- status */
|
||||
|
||||
function specStatus(spec) {
|
||||
const overviewPath = path.join(spec.dir, "overview.md");
|
||||
const overview = readText(overviewPath);
|
||||
const files = phaseFiles(spec.dir);
|
||||
// An empty overview.md still exists; only a missing one is "no overview".
|
||||
const hasOverview = overview !== null;
|
||||
const checklist = hasOverview ? parseChecklist(overview) : { found: false, phases: [], unparsed: [] };
|
||||
const groups = hasOverview ? parseGroups(overview) : { found: false, groups: [] };
|
||||
const checks = [];
|
||||
const check = (level, code, message) => checks.push({ level, code, message });
|
||||
for (const [n, names] of files.extra) {
|
||||
check("warn", "duplicate-phase-file", `Phase ${n} has more than one file: using ${files.get(n)}, ignoring ${names.join(", ")}`);
|
||||
}
|
||||
const rowsByNumber = new Map();
|
||||
for (const r of checklist.phases) rowsByNumber.set(r.number, [...(rowsByNumber.get(r.number) || []), r]);
|
||||
for (const [n, rows] of rowsByNumber) {
|
||||
if (rows.length > 1) check("error", "duplicate-checklist-row", `Phase ${n} has ${rows.length} rows in the Phase Checklist (overview.md lines ${rows.map((r) => r.line).join(", ")}); the first one is used`);
|
||||
}
|
||||
|
||||
const phases = [];
|
||||
const numbers = new Set([...checklist.phases.map((p) => p.number), ...files.keys()]);
|
||||
for (const number of [...numbers].sort((a, b) => a - b)) {
|
||||
const row = checklist.phases.find((p) => p.number === number) || null;
|
||||
const file = files.get(number) || null;
|
||||
const parsed = file ? parsePhaseFile(path.join(spec.dir, file), number) : null;
|
||||
phases.push({
|
||||
number,
|
||||
name: row ? row.name : parsed ? parsed.title.replace(/^Phase\s+\d+\s*[:\-–—]?\s*/i, "") : `Phase ${number}`,
|
||||
checklist: row ? row.state : null,
|
||||
marker: row ? row.marker : null,
|
||||
file,
|
||||
status: parsed ? parsed.status : null,
|
||||
goal: parsed ? parsed.goal : null,
|
||||
tasks: parsed ? { total: parsed.total, open: parsed.open, ...parsed.counts } : null,
|
||||
blockedTasks: parsed ? parsed.tasks.filter((t) => t.state === "blocked").map((t) => t.id) : [],
|
||||
assumedTasks: parsed ? parsed.tasks.filter((t) => t.state === "assumed").map((t) => t.id) : [],
|
||||
openTasks: parsed ? parsed.tasks.filter((t) => ["pending", "in-progress", "blocked", "unknown"].includes(t.state)).map((t) => t.id) : [],
|
||||
});
|
||||
if (!row && hasOverview) check("error", "missing-checklist-row", `phase-${number}.md has no row in overview.md's Phase Checklist`);
|
||||
if (row && !file) check("error", "missing-phase-file", `Phase Checklist lists Phase ${number} but there is no phase-${number}.md`);
|
||||
if (parsed) {
|
||||
for (const n of parsed.numbering) check("error", "task-numbering", `phase-${number}.md: ${n}`);
|
||||
// Prerequisites and criteria are plain bullets by rule; other checkbox
|
||||
// blocks (a Phase Testing list) are the template's own and are not tasks.
|
||||
for (const s of parsed.strayCheckboxes.filter((c) => /prerequisite|criteria/i.test(c.section))) {
|
||||
check("warn", "criteria-checkbox", `phase-${number}.md:${s.line} is a checkbox under "${s.section}"; prerequisites and criteria use plain bullets`);
|
||||
}
|
||||
if (parsed.total === 0) check("warn", "no-tasks", `phase-${number}.md has no **Task ${number}.N:** checkbox lines`);
|
||||
for (const u of parsed.unmatchedTasks) {
|
||||
check("warn", "uncounted-task", `phase-${number}.md:${u.line} looks like a task but is not counted (a task line is "- [ ] **Task ${number}.N:**"): ${u.text}`);
|
||||
}
|
||||
const done = parsed.counts.complete + parsed.counts.assumed;
|
||||
const rowDone = row && (row.state === "complete" || row.state === "assumed");
|
||||
// A phase may be approved with blocked [!] tasks left (Implementation
|
||||
// Mode's self-review allows "[x] or blocked [!]"); only unfinished work is an error.
|
||||
if (rowDone && parsed.unfinished > 0) {
|
||||
check("error", "checked-with-open-tasks", `Phase ${number} is [${row.marker}] in overview.md but ${parsed.unfinished} task(s) are not done (${phases.at(-1).openTasks.filter((id) => !phases.at(-1).blockedTasks.includes(id)).join(", ")})`);
|
||||
} else if (rowDone && parsed.counts.blocked > 0) {
|
||||
check("info", "approved-with-blocked", `Phase ${number} is [${row.marker}] with ${parsed.counts.blocked} blocked task(s) (${phases.at(-1).blockedTasks.join(", ")})`);
|
||||
}
|
||||
if (row && row.state === "pending" && parsed.total > 0 && done > 0) {
|
||||
// Done tasks under a [ ] phase with work still open is what a re-opened
|
||||
// phase looks like (revise-plan); with nothing open it is a missed mark.
|
||||
if (parsed.unfinished > 0) check("info", "partly-done-unchecked", `Phase ${number} is [ ] with ${done} task(s) done and ${parsed.unfinished} open (normal for a re-opened phase)`);
|
||||
else check("warn", "unchecked-with-done-tasks", `Phase ${number} is [ ] in overview.md but all ${done} unblocked task(s) are done`);
|
||||
}
|
||||
if (row && !rowDone && row.state !== "pending" && parsed.total > 0 && parsed.unfinished === 0) {
|
||||
check("info", "done-not-approved", `Phase ${number}: every task is done but overview.md still shows [${row.marker}] (normal until the user approves the phase)`);
|
||||
}
|
||||
}
|
||||
}
|
||||
if (!hasOverview) check("error", "no-overview", `${spec.rel} has no overview.md`);
|
||||
else if (!checklist.found) check("error", "no-checklist", "overview.md has no ## Phase Checklist section");
|
||||
for (const u of checklist.unparsed) check("warn", "unparsed-checklist-row", `overview.md:${u.line} is a checkbox in the Phase Checklist with no "Phase N" in it: ${u.text}`);
|
||||
for (const g of groups.groups) {
|
||||
for (const n of g.phases) if (!numbers.has(n)) check("error", "group-unknown-phase", `Parallel group ${g.id} names Phase ${n}, which does not exist`);
|
||||
}
|
||||
|
||||
// Totals. Completed = [x] plus [?] (assumed complete); [?] is reported on its own too.
|
||||
// Incomplete = [ ] + [/] (+ unreadable markers); Blocked is its own column.
|
||||
const totals = { total: 0, complete: 0, assumed: 0, pending: 0, "in-progress": 0, blocked: 0, unknown: 0 };
|
||||
for (const p of phases) if (p.tasks) for (const k of Object.keys(totals)) totals[k] += p.tasks[k] || 0;
|
||||
const completed = totals.complete + totals.assumed;
|
||||
const completion = totals.total ? completed / totals.total : null;
|
||||
|
||||
return {
|
||||
ok: true,
|
||||
spec: spec.rel,
|
||||
name: spec.name,
|
||||
overview: hasOverview ? "overview.md" : null,
|
||||
planDrafts: planDrafts(spec.dir),
|
||||
phases,
|
||||
parallelGroups: groups.groups,
|
||||
totals: { ...totals, completed, incomplete: totals.pending + totals["in-progress"] + totals.unknown },
|
||||
completion: completion === null ? null : Number(completion.toFixed(4)),
|
||||
completionPercent: completion === null ? null : Math.round(completion * 100),
|
||||
next: nextPhase(phases, groups.groups, checklist.found),
|
||||
pending: phases
|
||||
.filter((p) => p.checklist && p.checklist !== "complete" && p.checklist !== "assumed")
|
||||
.map((p) => ({ number: p.number, name: p.name, state: p.checklist, tasks: p.tasks ? p.tasks.total : null, open: p.tasks ? p.tasks.open : null, goal: p.goal })),
|
||||
checks,
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Implementation Mode's phase-selection table, applied mechanically.
|
||||
* 2+ workable phases in the same parallel group, consecutive -> choose (warn if all [/])
|
||||
* a single [/] -> ask-resume · a single [ ] -> auto-start · nothing workable -> none
|
||||
*/
|
||||
function nextPhase(phases, groups, haveChecklist) {
|
||||
if (!haveChecklist) return { action: "none", reason: "no Phase Checklist in overview.md" };
|
||||
const ordered = phases.filter((p) => p.checklist);
|
||||
const isDone = (p) => p.checklist === "complete" || p.checklist === "assumed";
|
||||
const workable = ordered.filter((p) => p.checklist === "pending" || p.checklist === "in-progress");
|
||||
if (!workable.length) {
|
||||
return { action: "none", reason: ordered.length && ordered.every(isDone) ? "every phase is complete" : "no [ ] or [/] phase in the Phase Checklist" };
|
||||
}
|
||||
const first = workable[0];
|
||||
const brief = (p) => ({ number: p.number, name: p.name, state: p.checklist, tasks: p.tasks ? p.tasks.total : null });
|
||||
// A blocked [!] phase ahead of the pick is skipped, but never silently.
|
||||
const skipped = ordered.slice(0, ordered.indexOf(first)).filter((p) => !isDone(p)).map(brief);
|
||||
const note = skipped.length ? { skipped, warning: `skipping ${skipped.map((p) => `Phase ${p.number} [${p.state}]`).join(", ")} ahead of it` } : {};
|
||||
const group = groups.find((g) => g.phases.includes(first.number));
|
||||
if (group) {
|
||||
// Consecutive same-group incomplete phases, in checklist order, starting at the first workable one.
|
||||
const run = [];
|
||||
for (const p of ordered.slice(ordered.indexOf(first))) {
|
||||
if (!group.phases.includes(p.number)) break;
|
||||
if (isDone(p)) continue;
|
||||
if (p.checklist === "pending" || p.checklist === "in-progress") run.push(p);
|
||||
else break;
|
||||
}
|
||||
if (run.length >= 2) {
|
||||
const allStarted = run.every((p) => p.checklist === "in-progress");
|
||||
const warnings = [
|
||||
...(allStarted ? ["every option is already [/]: another agent may be working on it, so picking one risks duplicated work"] : []),
|
||||
...(note.warning ? [note.warning] : []),
|
||||
];
|
||||
return {
|
||||
action: "choose",
|
||||
group: group.id,
|
||||
options: run.map(brief),
|
||||
...(note.skipped ? { skipped: note.skipped } : {}),
|
||||
...(warnings.length ? { warning: warnings.join("; ") } : {}),
|
||||
};
|
||||
}
|
||||
}
|
||||
return { action: first.checklist === "in-progress" ? "ask-resume" : "auto-start", phase: brief(first), ...note };
|
||||
}
|
||||
|
||||
/* --------------------------------------------------------------- commands */
|
||||
|
||||
async function cmdList(args) {
|
||||
const root = path.resolve(args.root || ".");
|
||||
const { scanProject } = await consoleLib();
|
||||
const scan = scanProject(root);
|
||||
const specs = scan.specs.map((s) => {
|
||||
const dir = path.join(root, s.dir);
|
||||
let names = [];
|
||||
try {
|
||||
names = fs.readdirSync(dir);
|
||||
} catch {}
|
||||
return {
|
||||
dir: s.dir,
|
||||
name: s.name,
|
||||
state: s.state,
|
||||
detail: s.detail,
|
||||
touched: s.touched ? new Date(s.touched).toISOString() : null,
|
||||
planDrafts: planDrafts(dir),
|
||||
overview: names.includes("overview.md"),
|
||||
phaseFiles: names.filter((n) => /^phase-\d+\b.*\.md$/i.test(n)).length,
|
||||
pathfinder: isDir(path.join(dir, "pathfinder")),
|
||||
};
|
||||
});
|
||||
let completed = [];
|
||||
try {
|
||||
completed = fs.readdirSync(path.join(root, "specs--completed")).filter((n) => isDir(path.join(root, "specs--completed", n))).sort();
|
||||
} catch {}
|
||||
out({
|
||||
ok: true,
|
||||
root,
|
||||
hasAgents: scan.hasAgents,
|
||||
specsDir: isDir(path.join(root, "specs")),
|
||||
specs,
|
||||
completed,
|
||||
...(specs.length ? {} : { note: "No active specs under specs/." }),
|
||||
});
|
||||
}
|
||||
|
||||
async function cmdStatus(args) {
|
||||
const root = path.resolve(args.root || ".");
|
||||
out(specStatus(resolveSpec(root, args._[1], { allowArchived: true })));
|
||||
}
|
||||
|
||||
function countVerificationAdded(dir) {
|
||||
let n = 0;
|
||||
for (const name of fs.readdirSync(dir)) {
|
||||
if (!/\.md$/i.test(name) || /^PLAN-/i.test(name)) continue;
|
||||
n += ((readText(path.join(dir, name)) || "").match(/<!--\s*VERIFICATION:\s*Added\b/gi) || []).length;
|
||||
}
|
||||
return n;
|
||||
}
|
||||
|
||||
async function cmdMetrics(args) {
|
||||
const root = path.resolve(args.root || ".");
|
||||
const spec = resolveSpec(root, args._[1], { allowArchived: true });
|
||||
const step = args.step;
|
||||
if (step !== "document" && step !== "finalize") fail(EXIT.USAGE, "bad-step", "--step must be document or finalize.", "Plan's METRICS_JSON is written by hand in its Phase 7.");
|
||||
const sets = {};
|
||||
for (const kv of args.set || []) {
|
||||
const m = kv.match(/^([a-z_]+)=(-?\d+(?:\.\d+)?)$/);
|
||||
if (!m) fail(EXIT.USAGE, "bad-set", `--set ${kv} is not key=number.`, "Example: --set verification_failures_found=1");
|
||||
sets[m[1]] = Number(m[2]);
|
||||
}
|
||||
// --set supplies the judgment fields only; the computed ones are never overridden.
|
||||
const SETTABLE = { document: ["verification_items_added"], finalize: ["verification_failures_found", "documentation_updates_needed"] };
|
||||
for (const k of Object.keys(sets)) {
|
||||
if (!SETTABLE[step].includes(k)) fail(EXIT.USAGE, "bad-set", `--set ${k} is not a field you supply for --step ${step}.`, `Only ${SETTABLE[step].join(", ")}; the rest is computed from the files.`);
|
||||
}
|
||||
const st = specStatus(spec);
|
||||
const withTasks = st.phases.filter((p) => p.tasks);
|
||||
let metrics;
|
||||
let hint;
|
||||
if (step === "document") {
|
||||
// verification_items_added is the Added total of the Verification Summary
|
||||
// you presented, not something the files record, so it comes from --set.
|
||||
// The <!-- VERIFICATION: Added --> comments are a cross-check only.
|
||||
if (!("verification_items_added" in sets)) fail(EXIT.USAGE, "missing-set", "document needs --set verification_items_added=N (the Added column total of your Verification Summary).", `The spec has ${countVerificationAdded(spec.dir)} <!-- VERIFICATION: Added --> comment(s), as a cross-check.`);
|
||||
metrics = {
|
||||
step: "document",
|
||||
total_tasks: st.totals.total,
|
||||
tasks_per_phase: withTasks.map((p) => p.tasks.total),
|
||||
phase_count: st.phases.length,
|
||||
parallel_groups_identified: st.parallelGroups.length,
|
||||
...sets,
|
||||
};
|
||||
hint = { verificationCommentsFound: countVerificationAdded(spec.dir) };
|
||||
} else {
|
||||
const missing = ["verification_failures_found", "documentation_updates_needed"].filter((k) => !(k in sets));
|
||||
if (missing.length) fail(EXIT.USAGE, "missing-set", `finalize needs ${missing.map((k) => `--set ${k}=N`).join(" and ")}.`, "Those two counts are your judgment from Steps 2 and 4.");
|
||||
metrics = {
|
||||
step: "finalize",
|
||||
completion_rate_at_audit: st.completion === null ? 0 : Number(st.completion.toFixed(2)),
|
||||
tasks_completed: st.totals.completed,
|
||||
tasks_total: st.totals.total,
|
||||
...sets,
|
||||
};
|
||||
}
|
||||
out({ ok: true, spec: spec.rel, metrics, comment: `<!-- METRICS_JSON ${spacedJson(metrics)} -->`, ...(hint || {}), checks: st.checks.filter((c) => c.level === "error") });
|
||||
}
|
||||
|
||||
// The house style of every METRICS_JSON comment: {"key": value, "list": [1, 2]}.
|
||||
function spacedJson(obj) {
|
||||
const v = (x) => (Array.isArray(x) ? `[${x.map(v).join(", ")}]` : x && typeof x === "object" ? spacedJson(x) : JSON.stringify(x));
|
||||
return `{${Object.entries(obj).map(([k, x]) => `${JSON.stringify(k)}: ${v(x)}`).join(", ")}}`;
|
||||
}
|
||||
|
||||
const TO = { open: " ", "in-progress": "/", done: "x" };
|
||||
|
||||
async function cmdMark(args) {
|
||||
const root = path.resolve(args.root || ".");
|
||||
const spec = resolveSpec(root, args._[1]);
|
||||
const number = Number(args.phase);
|
||||
if (!Number.isInteger(number) || number < 0) fail(EXIT.USAGE, "bad-phase", "--phase needs a phase number.", "Example: --phase 2");
|
||||
if (!(args.to in TO)) fail(EXIT.USAGE, "bad-to", "--to must be open, in-progress or done.", "open = [ ], in-progress = [/], done = [x]");
|
||||
const overviewPath = path.join(spec.dir, "overview.md");
|
||||
const overview = readText(overviewPath);
|
||||
if (overview === null) fail(EXIT.NOT_FOUND, "no-overview", `${spec.rel} has no overview.md.`, "Run /plan2code-2-document first.");
|
||||
const checklist = parseChecklist(overview);
|
||||
const rows = checklist.phases.filter((p) => p.number === number);
|
||||
const row = rows[0];
|
||||
if (!row) fail(EXIT.NOT_FOUND, "no-row", `overview.md's Phase Checklist has no row for Phase ${number}.`, "Run `specs.mjs status` to see the phases it lists.");
|
||||
if (rows.length > 1) fail(EXIT.REFUSED, "duplicate-row", `Phase ${number} has ${rows.length} rows in the Phase Checklist (lines ${rows.map((r) => r.line).join(", ")}); marking one would be a guess.`, "Remove the duplicate row, then rerun.");
|
||||
const target = TO[args.to];
|
||||
if (row.marker === "/" && target === " ") {
|
||||
fail(EXIT.REFUSED, "no-reset", `Phase ${number} is [/]; started work is never reset to [ ].`, "Leave it [/] (a later session resumes it), or mark it done once approved.");
|
||||
}
|
||||
const changes = [];
|
||||
const lines = overview.split(/\r?\n/);
|
||||
const idx = row.line - 1;
|
||||
const next = lines[idx].replace(/\[(.)\]/, `[${target}]`);
|
||||
if (next !== lines[idx]) {
|
||||
lines[idx] = next;
|
||||
changes.push({ file: `${spec.rel}/overview.md`, line: row.line, from: `[${row.marker}]`, to: `[${target}]` });
|
||||
}
|
||||
// The phase file's Status line follows: done -> Complete; re-opening a Complete
|
||||
// phase -> In Progress (revise-plan), so the two files never disagree.
|
||||
let phaseText = null;
|
||||
let phasePath = null;
|
||||
let unfinished = [];
|
||||
const warnings = [];
|
||||
const file = phaseFiles(spec.dir).get(number);
|
||||
if (file) {
|
||||
phasePath = path.join(spec.dir, file);
|
||||
const text = readText(phasePath) || "";
|
||||
const parsed = parsePhaseFile(phasePath, number);
|
||||
unfinished = parsed.tasks.filter((t) => ["pending", "in-progress", "unknown"].includes(t.state)).map((t) => t.id);
|
||||
const status = statusOf(text);
|
||||
const want = target === "x" ? "Complete" : target === " " && status && /^complete$/i.test(status) ? "In Progress" : null;
|
||||
if (status && want && status !== want) {
|
||||
phaseText = text.replace(STATUS_RE, (_, before, _value, after) => before + want + after);
|
||||
changes.push({ file: `${spec.rel}/${file}`, field: "Status", from: status, to: want });
|
||||
}
|
||||
// done and open keep the Status line in step; with none to find, say so.
|
||||
if (!status && target !== "/") warnings.push(`${file} has no Status line, so only the Phase Checklist checkbox changed; add a "**Status:** <value>" line under its title.`);
|
||||
}
|
||||
if (!args["dry-run"]) {
|
||||
if (changes.some((c) => c.file.endsWith("overview.md"))) fs.writeFileSync(overviewPath, lines.join(eol(overview)));
|
||||
if (phaseText !== null) fs.writeFileSync(phasePath, phaseText);
|
||||
}
|
||||
const doneEarly = target === "x" && unfinished.length > 0;
|
||||
if (doneEarly) warnings.unshift(`Phase ${number} was marked done with ${unfinished.length} unfinished task(s): ${unfinished.join(", ")}. Mark only a phase the user approved.`);
|
||||
out({
|
||||
ok: true,
|
||||
spec: spec.rel,
|
||||
phase: number,
|
||||
name: row.name,
|
||||
dryRun: !!args["dry-run"],
|
||||
changed: changes.length > 0,
|
||||
changes,
|
||||
...(warnings.length ? { warning: warnings.join(" ") } : {}),
|
||||
...(doneEarly ? { unfinished } : {}),
|
||||
});
|
||||
}
|
||||
|
||||
function listRel(dir, base = dir) {
|
||||
const outList = [];
|
||||
for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
|
||||
const p = path.join(dir, e.name);
|
||||
if (e.isDirectory()) outList.push(...listRel(p, base));
|
||||
else outList.push(rel(base, p));
|
||||
}
|
||||
return outList.sort();
|
||||
}
|
||||
|
||||
async function cmdArchive(args) {
|
||||
const root = path.resolve(args.root || ".");
|
||||
const spec = resolveSpec(root, args._[1]);
|
||||
const target = path.join(root, "specs--completed", spec.name);
|
||||
if (fs.existsSync(target)) {
|
||||
fail(EXIT.REFUSED, "target-exists", `specs--completed/${spec.name}/ already exists; nothing was moved.`, "Ask the user whether to merge by hand or archive under another name.");
|
||||
}
|
||||
const files = listRel(spec.dir);
|
||||
if (!args["dry-run"]) {
|
||||
fs.mkdirSync(path.dirname(target), { recursive: true });
|
||||
try {
|
||||
fs.renameSync(spec.dir, target);
|
||||
} catch (err) {
|
||||
// A rename across volumes (or a locked file on Windows) fails; copy then remove.
|
||||
try {
|
||||
fs.cpSync(spec.dir, target, { recursive: true, errorOnExist: true, force: false });
|
||||
} catch (copyErr) {
|
||||
fail(EXIT.INVALID, "archive-failed", `Could not move or copy ${spec.rel} (${err.code || err.message}; copy: ${copyErr.code || copyErr.message}).`, `Close anything holding files in ${spec.rel} open, check specs--completed/${spec.name} for a partial copy, then rerun.`);
|
||||
}
|
||||
try {
|
||||
fs.rmSync(spec.dir, { recursive: true, force: true });
|
||||
} catch (rmErr) {
|
||||
fail(EXIT.INVALID, "source-not-removed", `Copied to specs--completed/${spec.name}/ but could not remove ${spec.rel} (${rmErr.code || rmErr.message}); both copies now exist.`, `Close whatever holds files in ${spec.rel} open, then delete it by hand. The archive is complete.`);
|
||||
}
|
||||
}
|
||||
}
|
||||
const sourceGone = args["dry-run"] ? null : !fs.existsSync(spec.dir);
|
||||
const moved = args["dry-run"] ? null : listRel(target);
|
||||
if (!args["dry-run"] && !(sourceGone && moved.length === files.length)) {
|
||||
fail(
|
||||
EXIT.INVALID,
|
||||
"archive-unverified",
|
||||
`The move of ${spec.rel} to specs--completed/${spec.name}/ did not verify: ${moved.length} of ${files.length} file(s) at the target, and ${spec.rel} ${sourceGone ? "is gone" : "still exists"}.`,
|
||||
`Compare ${spec.rel} with specs--completed/${spec.name}/ and finish the move by hand; archive refuses to rerun while the target exists.`
|
||||
);
|
||||
}
|
||||
out({
|
||||
ok: true,
|
||||
dryRun: !!args["dry-run"],
|
||||
from: spec.rel,
|
||||
to: `specs--completed/${spec.name}`,
|
||||
files,
|
||||
...(args["dry-run"] ? {} : { sourceRemoved: sourceGone, filesAtTarget: moved.length, archivedOn: isoDate() }),
|
||||
});
|
||||
}
|
||||
|
||||
run(USAGE, async (argv) => {
|
||||
const args = parseArgs(argv, { booleans: ["dry-run"], values: ["root", "step", "phase", "to"], lists: ["set"] });
|
||||
const cmd = args._[0];
|
||||
const commands = { list: cmdList, status: cmdStatus, metrics: cmdMetrics, mark: cmdMark, archive: cmdArchive };
|
||||
if (!commands[cmd]) fail(EXIT.USAGE, "unknown-command", cmd ? `Unknown command "${cmd}".` : "No command given.", "Commands: list, status, metrics, mark, archive. Run with --help.");
|
||||
await commands[cmd](args);
|
||||
});
|
||||
@@ -0,0 +1,22 @@
|
||||
{
|
||||
"name": "Plan2Code",
|
||||
"version": "2.4.1",
|
||||
"description": "A structured 4-step workflow methodology for AI-assisted software development",
|
||||
"keywords": [
|
||||
"ai",
|
||||
"workflow",
|
||||
"development",
|
||||
"planning",
|
||||
"implementation",
|
||||
"plan"
|
||||
],
|
||||
"author": "Justin Parker",
|
||||
"license": "MIT",
|
||||
"repository": {
|
||||
"type": "git",
|
||||
"url": "https://github.com/jparkerweb/plan2code"
|
||||
},
|
||||
"homepage": "https://github.com/jparkerweb/plan2code",
|
||||
"releaseDate": "2026-10-04",
|
||||
"mode": "utility"
|
||||
}
|
||||
@@ -101,7 +101,7 @@ Only this prompt can obtain phase approval.
|
||||
When the user replies `approved` to the final sign-off:
|
||||
|
||||
1. Run Implementation Mode's `After Approval / Session End` actions.
|
||||
2. Mark overview.md `[/]` to `[x]` and set the phase status to `Complete`.
|
||||
2. Mark overview.md `[/]` to `[x]` and set the phase status to `Complete` (`specs.mjs mark --to done`, per Implementation Mode's Scripts; `<S>` is this skill's own `scripts/`).
|
||||
3. Provide the work summary, upcoming phases, commit command, and next pipeline step.
|
||||
4. Do not suggest `/plan2code-review`; this phase has already passed that gate.
|
||||
5. Mention `/plan2code-1b-revise-plan` only when it remains relevant.
|
||||
|
||||
@@ -10,6 +10,14 @@ Senior software engineer implementing solutions exactly as specified. Follow spe
|
||||
|
||||
The FIRST thing you do, before anything else in this file — before reading a spec, before Phase 1: ask **web console** (browser page, suggested) or **terminal**? Console → run `node "<D>/console.mjs" open --workflow implement` before reading (<D>: references/web-console/ beside this SKILL.md — ~/.agents/skills/plan2code-3-implement/references/web-console/ globally — or the dir in ~/.plan2code/console/console-dir), then <D>/console.md and <D>/building.md; progress, every question and the sign-off go through it. Switchable anytime. If the argument already says which — `--web` or `Use the web console for this session.` — take it and do not ask; drop the flag. Launched by the dashboard? Its session is already open — resume it (console.md → Launches), then the spec.
|
||||
|
||||
## Scripts
|
||||
|
||||
`<S>` is `scripts/` beside this SKILL.md (`~/.agents/skills/plan2code-3-implement/scripts/` globally; for Implement + Review, its own skill's `scripts/`). Run them from the project root. Each prints one JSON object; on a non-zero exit read `message` and do what `next` says.
|
||||
|
||||
- `node "<S>/specs.mjs" status <spec>`: the Phase Checklist, parallel groups, every phase's task counts by marker, goal, the phase-selection verdict (`next`) and consistency `checks`.
|
||||
- `node "<S>/specs.mjs" mark <spec> --phase <N> --to in-progress|done`: the overview checkbox (and on `done`, the phase file's Status line). It refuses to reset `[/]` to `[ ]`.
|
||||
- `node "<S>/commit-msg.mjs" --subject "<subject>" --add-all`: the commit command, ticket taken from the branch.
|
||||
|
||||
## Rules
|
||||
|
||||
- Follow `./AGENTS.md` if it exists
|
||||
@@ -25,28 +33,15 @@ The FIRST thing you do, before anything else in this file — before reading a s
|
||||
|
||||
## Required Context
|
||||
|
||||
⚠️ IMPORTANT: `specs/` is gitignored — NEVER use Glob (silently fails). Shell only: `ls specs/` (Bash) or `Get-ChildItem specs/` (PS).
|
||||
Need implementation spec files to proceed. `specs/` is gitignored, so never search it with Glob; the script reads the disk directly and never looks in `specs--completed/`.
|
||||
|
||||
Need implementation spec files to proceed.
|
||||
**Option 1: User provides an overview.md path** → `specs.mjs status <that path>`.
|
||||
|
||||
**IMPORTANT:** Never look in `specs--completed/` (archived only). Only check active spec folders under `specs/`.
|
||||
**Option 2: Auto-detect** → `specs.mjs list`. Exactly one spec with phases (`phaseFiles` > 0) → `status` it.
|
||||
|
||||
**Option 1: User provides overview.md path**
|
||||
1. Read the overview.md file
|
||||
2. Find "Phase Checklist" section
|
||||
3. Identify workable phases: `[ ]` (pending) or `[/]` (in-progress)
|
||||
4. Check for parallel execution options
|
||||
5. Apply phase selection logic
|
||||
6. Read corresponding `phase-X.md` from same directory
|
||||
7. Begin implementation
|
||||
**Option 3: Several specs or none** → ask: "Please provide the path to the overview.md file (e.g., `specs/user-authentication/overview.md`)"
|
||||
|
||||
**Option 2: Auto-detect from specs folder**
|
||||
If no file provided, look for single `specs/<feature-name>` folder. If found, read its `overview.md` and follow Option 1.
|
||||
|
||||
**Option 3: Multiple specs or nothing found**
|
||||
Ask user: "Please provide the path to the overview.md file (e.g., `specs/user-authentication/overview.md`)"
|
||||
|
||||
Do not proceed without successfully reading overview.md and determining the next phase.
|
||||
Then read overview.md and act on `next` (Parallel Phase Selection below). Any `error` in `checks` (a phase marked `[x]` with open tasks, a checklist row with no phase file) is worth one line to the user before you start. Do not proceed without a readable overview.md and a `next` verdict.
|
||||
|
||||
## Phase Status Tracking
|
||||
|
||||
@@ -70,16 +65,16 @@ Never reset `[/]` to `[ ]`. Started work stays marked for conscious resume decis
|
||||
|
||||
## Parallel Phase Selection
|
||||
|
||||
Check overview.md for "Parallel Execution Groups" section. Find workable phases (`[ ]` or `[/]`).
|
||||
`status` applies the selection rules (workable = `[ ]` or `[/]`; consecutive incomplete phases of one parallel group are offered together) and returns `next`:
|
||||
|
||||
| Condition | Action |
|
||||
| `next.action` | Action |
|
||||
|-----------|--------|
|
||||
| 2+ workable phases in same parallel group | Show selection prompt listing each with status. TIP: run another agent on a different phase simultaneously. If all are `[/]`, warn about duplication. |
|
||||
| Single `[/]` phase | Prompt: "Phase X is in progress. Resume? (yes/no)" |
|
||||
| Single `[ ]` phase | Auto-start: mark `[/]` and begin |
|
||||
| No parallel groups section | Sequential mode (single-phase rules above) |
|
||||
| `choose` | Show a selection prompt listing each of `options` with its status. TIP: run another agent on a different phase simultaneously. Relay `warning` (all already `[/]`: duplicated work) when present. |
|
||||
| `ask-resume` | Prompt: "Phase X is in progress. Resume? (yes/no)" Relay `warning` when present. |
|
||||
| `auto-start` | Mark it `[/]` and begin. Relay `warning` when present. |
|
||||
| `none` | Nothing to implement: say why (`reason`). Every phase complete → `/plan2code-4-finalize --web` |
|
||||
|
||||
Only show consecutive same-group incomplete phases. After selection, mark `[/]`, read `phase-X.md`, begin.
|
||||
After selection, `mark --to in-progress`, read `phase-X.md`, begin.
|
||||
|
||||
## Code Consistency Rules
|
||||
|
||||
@@ -103,11 +98,9 @@ Only show consecutive same-group incomplete phases. After selection, mark `[/]`,
|
||||
|
||||
### 1. Identify and Claim Phase
|
||||
|
||||
Review `overview.md`, find workable phases (`[ ]` or `[/]`). Apply parallel selection logic.
|
||||
Act on `status`'s `next` (Parallel Phase Selection above).
|
||||
|
||||
**Once selected:**
|
||||
- If `[ ]`: Update to `[/]` in overview.md
|
||||
- If `[/]`: No change needed
|
||||
**Once selected:** `specs.mjs mark <spec> --phase <N> --to in-progress` (a no-op when it is already `[/]`).
|
||||
|
||||
State: `⚡ [PHASE X: Phase Name] - Marking in-progress and starting`
|
||||
|
||||
@@ -168,7 +161,7 @@ See "After Approval / Session End" section below.
|
||||
| Minor spec gap | Proceed with interpretation, note decision | `> SPEC NOTE: [what was assumed]` |
|
||||
| Major spec conflict | STOP and ask user — do NOT guess on architecture | `SPEC CONFLICT: [details]. Please clarify.` |
|
||||
|
||||
Default: ONE phase per conversation. Small phase (<5 tasks): ask if should continue with next. Large (>40): warn at start.
|
||||
Default: ONE phase per conversation. Small phase (<5 tasks in `status`): ask if should continue with next. Large (>40): warn at start.
|
||||
|
||||
## Templates
|
||||
|
||||
@@ -205,18 +198,17 @@ Sections: Summary (2-3 sentences), Tasks Completed (Y/Z + blocked list), Test Re
|
||||
### After Approval / Session End
|
||||
|
||||
On user "approved":
|
||||
1. Mark `[/]` → `[x]` in overview.md, update phase-X.md status to "Complete"
|
||||
1. `specs.mjs mark <spec> --phase <N> --to done`: overview `[/]` → `[x]` and phase-X.md Status "Complete"
|
||||
2. Show Planny art with completion message
|
||||
3. Work summary — tell user: phase name, tasks completed, key files created/modified
|
||||
4. **Upcoming phases** — read overview.md Phase Checklist, find next 2-3 pending (`[ ]`) phases. For each, peek at its `phase-X.md` for task count and goal. Present a table so the user can assess stopping points and review gates:
|
||||
4. **Upcoming phases** — rerun `status`; its `pending` list carries each remaining phase's name, task count and goal. Present the next 2-3 as a table so the user can assess stopping points and review gates (tighten a goal to one sentence if it runs long):
|
||||
|
||||
| Phase | Tasks | Goal |
|
||||
|-------|-------|------|
|
||||
| Phase X: [Name] | Y | [One-sentence goal] |
|
||||
| Phase X+1: [Name] | Z | [One-sentence goal] |
|
||||
|
||||
5. Provide: `git add -A && git commit -m "<subject>" -m "<JIRA-Ticket-ID>" -m "AI Assisted"` (derive JIRA ticket ID from branch name)
|
||||
- **Subject ≤100 chars. EXACTLY THREE -m flags — no body. NEVER add bullet bodies, paragraph descriptions, or multi-line explanations.** If a phase spec file contains a longer commit-message template, use only its subject line. The diff is the body; the PR is the explanation.
|
||||
5. Write a one-line subject for the phase, then give the user the `command` from `commit-msg.mjs --subject "<subject>" --add-all`. It enforces the format: subject ≤100 chars and EXACTLY THREE -m flags (subject, ticket, `AI Assisted`), no body. If a phase spec file contains a longer commit-message template, use only its subject line. The diff is the body; the PR is the explanation. On Windows PowerShell 5.1 (no `&&`), give `add` and `commit` as two commands instead. Exit 4 `no-ticket`: ask the user for the ticket and rerun with `--ticket`, or show the command with `<JIRA-Ticket-ID>` for them to fill in.
|
||||
6. **If more phases:** "NEXT STEP: Start NEW conversation and run: `/plan2code-3-implement --web`"
|
||||
7. **If final phase:** "NEXT STEP: Start NEW conversation and run: `/plan2code-4-finalize --web`"
|
||||
8. Mention `/plan2code-1b-revise-plan --web` option
|
||||
|
||||
@@ -10,6 +10,14 @@ Critical review specialist -- experienced senior engineer providing independent
|
||||
|
||||
The FIRST thing you do, before anything else in this file — before the scope detection: ask **web console** (browser page, suggested) or **terminal**? Console → run `node "<D>/console.mjs" open --workflow review` before reading (<D>: references/web-console/ beside this SKILL.md — ~/.agents/skills/plan2code-review/references/web-console/ globally — or the dir in ~/.plan2code/console/console-dir), then read <D>/console.md. Scope questions, the findings report and the pick-what-gets-fixed menu all go through it; the report lands on the page as a doc. Switchable anytime. If the argument already says which — `--web` or `Use the web console for this session.` — take it and do not ask; drop the flag. Launched by the dashboard? Its session is already open — resume it (console.md → Launches), then Process. Read inside a build session for its review button? Skip this section — building.md's overrides govern, the session is already running. On the console, a `__stop` action is the person ending the session (console.md → Stop requests); at every session end post `finish` BEFORE `stop`; unless it is a pause, the finish carries `"dashboard": true` (the Back to the dashboard button) and you keep waiting for the press (console.md → Finishing).
|
||||
|
||||
## Scripts
|
||||
|
||||
`<S>` is `scripts/` beside the SKILL.md that loaded this file (`~/.agents/skills/<skill>/scripts/` globally; when this file is a reference inside implement, implement-review or quick-task, that skill's own `<skill>/scripts/`, never `references/scripts/`). Run from the project root. Each prints one JSON object; on a non-zero exit read `message` and do what `next` says.
|
||||
|
||||
- `node "<S>/review-scope.mjs" [--base <branch>]`: the branch-review scope from git (Step 1).
|
||||
- `node "<S>/specs.mjs" list` / `status <spec>`: spec state on disk (Step 2, Session End routing).
|
||||
- `node "<S>/commit-msg.mjs" --subject "<subject>" --files <path> [--files <path> ...]`: the commit command (one `--files` per path).
|
||||
|
||||
## Rules
|
||||
|
||||
- Follow `./AGENTS.md` if it exists -- use all rules and conventions. If missing, warn and proceed with caution.
|
||||
@@ -40,7 +48,7 @@ Three levels -- auto-detected, always respect explicit user override:
|
||||
|
||||
**User override:** If user specifies scope, use exactly that. Never silently narrow.
|
||||
|
||||
**Doc review:** >70% doc files = editorial critique. >70% code = also verify related docs match.
|
||||
**Doc review:** >70% doc files = editorial critique. >70% code = also verify related docs match. (`review-scope.mjs` reports this as `mix`: `docs`, `code` or `mixed`; for a Focused scope, count the named files the same way.)
|
||||
|
||||
## Process
|
||||
|
||||
@@ -54,7 +62,7 @@ Three levels -- auto-detected, always respect explicit user override:
|
||||
|
||||
1. **User prompt** — use it.
|
||||
2. **Conversation context** — recent work? Those artifacts. Scope: `focused`.
|
||||
3. **Git fallback** — `git status`, `git diff`, `git log main..HEAD --oneline`, `git diff --name-only main..HEAD`. Nothing? Ask user.
|
||||
3. **Git fallback** — run `review-scope.mjs`. It compares the branch with its base (`main`, else `master`; `--base` overrides; `base` says which it used) and adds staged, unstaged and untracked changes: `files` (status, lines), `counts`, `commits`, `mix`, `batchByRisk`. `empty: true`? Ask user. Exit 3 `no-base` (no `main` or `master`, or no such `--base`)? Rerun with `--base <trunk>`, asking the user which branch is the trunk if unclear. Exit 3 `not-a-repo`? Ask user which files to review.
|
||||
|
||||
**Classify review type** from context (auto-detect; use `ask_user_question` only if ambiguous):
|
||||
|
||||
@@ -69,13 +77,13 @@ Three levels -- auto-detected, always respect explicit user override:
|
||||
| >70% .md files | Docs | Accuracy, Completeness |
|
||||
| Default | General | All 11, risk-prioritized |
|
||||
|
||||
**50+ files:** batch by risk tier (security/auth/data first).
|
||||
**50+ files** (`batchByRisk`): batch by risk tier (security/auth/data first).
|
||||
|
||||
> 🔬 [Review Mode] [X] files, ~[Y] lines. Type: [type]. Focus: [prioritized dimensions].
|
||||
|
||||
### Step 2: Context
|
||||
|
||||
1. **Specs?** Read `overview.md` + recent `phase-X.md`.
|
||||
1. **Specs?** `specs.mjs list` (it reads gitignored `specs/`, which file search skips), then read `overview.md` + recent `phase-X.md`.
|
||||
2. **AGENTS.md** for conventions.
|
||||
3. **Tech stack** -- check for deprecations, CVEs, breaking changes.
|
||||
4. **Classify:** >70% docs = doc review. >70% code = verify docs match.
|
||||
@@ -167,9 +175,9 @@ Work summary — tell user: scope reviewed, findings count by severity (Critical
|
||||
|
||||
Read references/session-end.md
|
||||
|
||||
> Fallback: route plan2code artifacts (plan/spec docs/phases) on the reviewed feature's own `specs/<feature>/` state to the earliest unmet pipeline stage whose input exists — `PLAN-*` or `overview.md` without `phase-*.md` → `/plan2code-2-document`; unchecked `- [ ]` phase tasks → `/plan2code-3-implement`; all checked → `/plan2code-4-finalize`; archived → complete, summary only. Verify `specs/` on disk with a terminal `ls`/`Get-ChildItem` — it's gitignored, so search tools miss it and an empty result proves nothing. Non-pipeline artifacts (code/PRs/docs/logs) → summary only. Unresolved Criticals → fixing them (H/A/S) is the next step. Ambiguous or multiple candidate specs → ask one targeted question. Output: "Next (NEW conversation): `/plan2code-<step>` — [why + how you know]", appending ` --web` when the routed step offers the web console; else "Review complete -- [summary]."
|
||||
> Fallback: route plan2code artifacts (plan/spec docs/phases) on the reviewed feature's own `specs/<feature>/` state to the earliest unmet pipeline stage whose input exists — `PLAN-*` or `overview.md` without `phase-*.md` → `/plan2code-2-document`; unchecked `- [ ]` phase tasks → `/plan2code-3-implement`; all checked → `/plan2code-4-finalize`; archived → complete, summary only. Read the state with `specs.mjs status <spec>` (gitignored `specs/` defeats search tools). Non-pipeline artifacts (code/PRs/docs/logs) → summary only. Unresolved Criticals → fixing them (H/A/S) is the next step. Ambiguous or multiple candidate specs → ask one targeted question. Output: "Next (NEW conversation): `/plan2code-<step>` — [why + how you know]", appending ` --web` when the routed step offers the web console; else "Review complete -- [summary]."
|
||||
|
||||
- **Commit** (code changes): `git add [files] && git commit -m "fix: [desc]" -m "<JIRA>" -m "AI Assisted"` -- derive JIRA from branch.
|
||||
- **Commit** (code changes): the `command` from `commit-msg.mjs --subject "fix: [desc]" --files <file>` repeated once per fixed file (ticket from the branch; exit 4 `no-ticket`: show it with `<JIRA>` for the user to fill in). On Windows PowerShell 5.1 (no `&&`), give `add` and `commit` as two commands.
|
||||
|
||||
```
|
||||
⋅
|
||||
|
||||
@@ -5,7 +5,7 @@ Principles to reason from, not a lookup table — adapt; when a case doesn't fit
|
||||
cleanly, say what you verified and ask.
|
||||
|
||||
- **Plan2Code Workflow Pipeline:** `/plan2code-1-plan` → `PLAN-*` files · `/plan2code-2-document` → `overview.md` + `phase-*.md` (the "spec docs") in `specs/<feature>/` · `/plan2code-3-implement` → checks off phase tasks, one phase per run · `/plan2code-4-finalize` → archives to `specs--completed/`.
|
||||
- **Find specs (any OS/shell):** `specs/` is gitignored, and search tools (Glob/Grep/project search) skip gitignored paths on many platforms — an empty search result is not evidence either way. Check with a terminal listing: `ls specs/<feature>/` (bash/zsh) · `Get-ChildItem specs/<feature>` (PowerShell) · `dir specs\<feature>` (cmd). Feature dir unknown? List `specs/` first. Command errors? Try another shell's form, then read the expected files directly — file reads see gitignored paths. Conclude "no specs" only after a terminal listing or a failed direct read.
|
||||
- **Find specs (any OS/shell):** `specs/` is gitignored, and search tools (Glob/Grep/project search) skip gitignored paths on many platforms — an empty search result is not evidence either way. Use `node "<S>/specs.mjs" list` (`<S>`: see Review Mode → Scripts) (feature dir unknown, or to see what is archived in `completed`) and `node "<S>/specs.mjs" status <spec>`: they read the disk directly. Its fields map onto the routing below: `planDrafts` with no `overview` · `overview` with no phases · each phase's `tasks.open` · a name in `completed`. If the script cannot run, read the expected files directly — file reads see gitignored paths. Conclude "no specs" only after `list` or a failed direct read.
|
||||
- **Reconcile three signals:** session context (what this conversation was doing — a fresh session may have none), user intent (what they asked reviewed), the disk check above. Disk wins on state; context wins on intent and on disk silence; no context → intent + disk decide.
|
||||
- **plan2code artifact reviewed (a plan, the spec docs, phases) — route on the reviewed feature's own `specs/<feature>/` state (another feature's specs prove nothing here), to the earliest unmet stage, suggesting only a step whose input exists:**
|
||||
- `PLAN-*` without `overview.md` → `/plan2code-2-document`
|
||||
|
||||
@@ -556,8 +556,15 @@ enforces it, so never tell someone to keep asking past it.
|
||||
The person can add folders beside the one the session started in (a shared
|
||||
library, a design folder), from the footer's folder label. Together they are
|
||||
the session's **workspace**: context for every skill run in this console
|
||||
session, each folder addressed by a short `@name`. It outlives dashboard hops;
|
||||
a new console session starts with the original folder alone.
|
||||
session, each folder addressed by a short `@name`. It outlives dashboard hops,
|
||||
and it is remembered: every change is saved to `workspaces.json` beside
|
||||
`looks.json` (never into the project), keyed by the folder the session runs
|
||||
in and then by spec. A session with a spec opens on that spec's list, one with
|
||||
none on the project's; a spec with nothing saved starts as a copy of the
|
||||
project's list. The dashboard's picker swaps the list as the selection moves,
|
||||
and a `specDir` you post mid-run takes the current list with it. There is
|
||||
nothing for you to load: `open` prints the list, and a switch of spec on a
|
||||
resume reaches you as ordinary workspace changes on your next `wait`.
|
||||
|
||||
### What you are told
|
||||
|
||||
@@ -767,7 +774,7 @@ that is what the person is there to download. The finish carries no
|
||||
sees the Trail Footer, and without this their last screen promises a question
|
||||
that is never coming.
|
||||
- Post `run` `pathfinder-chart` (id `map`) when a new map is first written,
|
||||
and `pathfinder-research` (id = the question's file slug) as each research
|
||||
and `pathfinder-research` (id = the question's file slug; on `github`, `q<issue-number>`) as each research
|
||||
subagent reports back, or when you resolve a `research` question yourself
|
||||
(Posting an update → Session meter). Other questions score through their
|
||||
answers, so there is nothing to post for them.
|
||||
@@ -820,7 +827,7 @@ know:
|
||||
| 3, Implementation Summary | Written to `overview.md` as usual; mirror it as a doc (marked `saved`) so the page reader sees it land. |
|
||||
| 4, Documentation Review | The proposed-updates table as a doc, and a `multi` naming the documents to update — every option ticked is "approve", unticked ones are skipped. A `review` works instead when the set is all-or-nothing. |
|
||||
| 5, User Feedback | Optional items, `required: false`: the rating as a `choice` of 1 to 10 or a `text`, the three reasons as `text`. The submit-to-maintainer consent is a `confirm`. |
|
||||
| 6, Spec Cleanup | A `confirm` before moving anything, the archive paths in `consequences`. |
|
||||
| 6, Spec Cleanup | A `confirm` before moving anything, the archive paths in `consequences`, and a line that the spec's remembered workspace folders are forgotten too (`console.mjs forget --spec specs/<feature>` after the move). |
|
||||
|
||||
Pass `--spec specs/<feature>` to `open`, or post `specDir` once you know it.
|
||||
Stopping mid-finalize loses nothing
|
||||
|
||||
@@ -41,6 +41,7 @@ import {
|
||||
die,
|
||||
ensureDir,
|
||||
fileStamp,
|
||||
forgetWorkspace,
|
||||
handOff,
|
||||
handleFile,
|
||||
healthOk,
|
||||
@@ -65,6 +66,7 @@ import {
|
||||
readLedger,
|
||||
readWorkspace,
|
||||
reapHandles,
|
||||
rememberedWorkspace,
|
||||
remoteWarning,
|
||||
removeScratch,
|
||||
removeSessions,
|
||||
@@ -73,6 +75,7 @@ import {
|
||||
SESSION_MAX_AGE_MS,
|
||||
sessionDir,
|
||||
sleepSync,
|
||||
specKey,
|
||||
staleScratch,
|
||||
staleSessions,
|
||||
sweepUploads,
|
||||
@@ -317,7 +320,7 @@ async function cmdOpen() {
|
||||
if (launched) appendLedger(dir, { kind: "launch", id: nextLaunchId(readLedger(dir)), workflow: state.workflow });
|
||||
for (const line of ledgerFromPost(dir, openRun, openIssue, state.workflow)) appendLedger(dir, line);
|
||||
} catch {}
|
||||
const workspace = workspaceOnOpen(dir, worktree);
|
||||
const workspace = workspaceOnOpen(dir, worktree, state.specDir);
|
||||
|
||||
// Month-old sessions and scratch files: listed before the print so the
|
||||
// agent can see what went, removed after it so the page waits for nothing.
|
||||
@@ -403,10 +406,11 @@ async function cmdOpen() {
|
||||
* The workspace as `open` hands it to the agent, and the cursor seeded to
|
||||
* match: the agent now has the whole list, so no change up to here is owed.
|
||||
* Read-only on workspace.json, which only the server writes; on a fresh
|
||||
* session the server has not made it yet, so the original folder stands in.
|
||||
* session the server has not made it yet, so what was remembered for this
|
||||
* folder and spec stands in, the same list the server is about to make.
|
||||
*/
|
||||
function workspaceOnOpen(dir, worktree) {
|
||||
const ws = readWorkspace(dir) || initialWorkspace(worktree);
|
||||
function workspaceOnOpen(dir, worktree, specDir) {
|
||||
const ws = readWorkspace(dir) || initialWorkspace(worktree, rememberedWorkspace(worktree, specDir).entry);
|
||||
const missing = ws.folders.filter((f) => !isFolder(f.path)).map((f) => f.id);
|
||||
try {
|
||||
writeWorkspaceCursor(dir, ws.version || 0);
|
||||
@@ -946,6 +950,18 @@ function realNearest(p) {
|
||||
return path.join(fs.realpathSync(existing), path.relative(existing, p));
|
||||
}
|
||||
|
||||
/* --------------------------------------------------------------- forget */
|
||||
|
||||
// Drop the folder list remembered for one spec (Finalize, once the spec is
|
||||
// archived). The project's own list and every other spec's are untouched.
|
||||
function cmdForget() {
|
||||
if (typeof args.spec !== "string" || !args.spec.trim()) die("forget needs --spec specs/<idea>", 2);
|
||||
let spec = specKey(args.spec);
|
||||
if (/\.md$/i.test(spec)) spec = spec.slice(0, spec.lastIndexOf("/"));
|
||||
const worktree = repoRoots().worktree;
|
||||
print({ ok: true, spec, forgot: forgetWorkspace(worktree, spec) });
|
||||
}
|
||||
|
||||
/* ----------------------------------------------------------------- help */
|
||||
|
||||
function cmdHelp() {
|
||||
@@ -961,7 +977,8 @@ port, and the filesystem as transport; this CLI is the whole agent surface.
|
||||
first post. --file is optional, and --title defaults to the
|
||||
project's folder name. Also prints workspace: { folders: [{ name,
|
||||
path, description?, original? }], missing? }, the folders this
|
||||
console session reads as context, addressed as @name.
|
||||
console session reads as context, addressed as @name. The list is
|
||||
remembered per folder and spec in workspaces.json beside looks.json.
|
||||
post --session <sid> --file <patch.json>
|
||||
Merge a patch into the session. Prints terminalLine while the
|
||||
server is live. Exit 3 = rejected; stderr says why. A patch may
|
||||
@@ -988,6 +1005,10 @@ port, and the filesystem as transport; this CLI is the whole agent surface.
|
||||
Copy a cited note attachment into specs/<idea>/attachments/. Prints
|
||||
{ ok, path, link, image, reused }; exit 2 = bad usage, 3 = refused or
|
||||
missing. Paste link as it is.
|
||||
forget --spec specs/<idea>
|
||||
Drop the workspace folders remembered for that spec, in this
|
||||
folder (Finalize, after archiving it). Prints { ok, spec, forgot };
|
||||
forgot is false when nothing was saved. Exit 2 = bad usage.
|
||||
status [--session <sid>] [--all]
|
||||
One session, or every session belonging to this project.
|
||||
stop --session <sid> | --all
|
||||
@@ -1206,6 +1227,7 @@ const COMMANDS = {
|
||||
wait: cmdWait,
|
||||
chat: cmdChat,
|
||||
keep: cmdKeep,
|
||||
forget: cmdForget,
|
||||
status: cmdStatus,
|
||||
stop: cmdStop,
|
||||
help: cmdHelp,
|
||||
|
||||
@@ -178,8 +178,8 @@ function lockStale(lock) {
|
||||
// Run fn while holding the session's state lock, and release it however fn
|
||||
// ends. fn must not call process.exit(): the release would never run, and the
|
||||
// next writer would wait out the stale age.
|
||||
export function withStateLock(dir, fn) {
|
||||
const lock = path.join(dir, STATE_LOCK_FILE);
|
||||
export function withStateLock(dir, fn, lockName = STATE_LOCK_FILE) {
|
||||
const lock = path.join(dir, lockName);
|
||||
const deadline = Date.now() + LOCK_WAIT_MS;
|
||||
let fd = null;
|
||||
for (let attempt = 0; fd === null; attempt++) {
|
||||
@@ -188,7 +188,7 @@ export function withStateLock(dir, fn) {
|
||||
} catch (err) {
|
||||
// EPERM / EACCES: on Windows, a lock being deleted still blocks a create.
|
||||
if (!["EEXIST", "EPERM", "EACCES", "EBUSY"].includes(err.code)) throw err;
|
||||
if (Date.now() > deadline) throw new Error("state.json is busy with another writer; try again");
|
||||
if (Date.now() > deadline) throw new Error(`${lockName.replace(/.lock$/, "")} is busy with another writer; try again`);
|
||||
if (err.code === "EEXIST" && lockStale(lock)) {
|
||||
try {
|
||||
fs.rmSync(lock, { force: true });
|
||||
@@ -487,8 +487,9 @@ export async function removeSessions(sessionsDir, sids) {
|
||||
}
|
||||
|
||||
// The console folder's own files that no sweep may ever remove: the person's
|
||||
// looks and the pointer to this console's directory.
|
||||
export const PROTECTED_CONSOLE_FILES = new Set(["looks.json", "console-dir"]);
|
||||
// looks, the folders remembered per project and spec, and the pointer to
|
||||
// this console's directory.
|
||||
export const PROTECTED_CONSOLE_FILES = new Set(["looks.json", "workspaces.json", "console-dir"]);
|
||||
|
||||
function isScratchName(name) {
|
||||
return (
|
||||
@@ -1619,17 +1620,125 @@ export function readWorkspace(dir) {
|
||||
return readJson(path.join(dir, WORKSPACE_FILE), null);
|
||||
}
|
||||
|
||||
// A fresh workspace: just the original folder, named after itself.
|
||||
export function initialWorkspace(worktree) {
|
||||
// A fresh workspace: the original folder, named after itself, plus whatever
|
||||
// was remembered for this folder and spec (rememberedWorkspace() below).
|
||||
export function initialWorkspace(worktree, remembered = null) {
|
||||
const original = { id: "f0", path: worktree, name: defaultName(worktree), description: "", original: true };
|
||||
if (remembered && remembered.original) {
|
||||
if (remembered.original.name) original.name = remembered.original.name;
|
||||
if (remembered.original.description) original.description = remembered.original.description;
|
||||
}
|
||||
const added = ((remembered && remembered.folders) || []).map((f, i) => ({
|
||||
id: "f" + (i + 1),
|
||||
path: f.path,
|
||||
name: f.name,
|
||||
description: f.description || "",
|
||||
...(f.nested ? { nested: true } : {}),
|
||||
}));
|
||||
return { version: 0, folders: [original, ...added], missing: [], changes: [], remote: "" };
|
||||
}
|
||||
|
||||
/* ------------------------------------------------ remembered workspaces */
|
||||
|
||||
// The folder list outlives the console session: one file for the person,
|
||||
// beside looks.json, keyed by the folder a session runs in and then by spec.
|
||||
// Never under specs/: the paths are this machine's, and the server never
|
||||
// writes into a project.
|
||||
//
|
||||
// { "projects": { "<folded worktree>": {
|
||||
// "path": "<worktree>",
|
||||
// "project": { original, folders, at }, // no spec picked
|
||||
// "specs": { "specs/<name>": { original, folders, at } } } } }
|
||||
//
|
||||
// `original` holds the first folder's name and description only (its path is
|
||||
// always the session's own); `folders` the added ones as { path, name,
|
||||
// description, nested? }. Two writers, the server on every change and
|
||||
// `console.mjs forget`, each a read-modify-write of one key.
|
||||
export const WORKSPACES_FILE = path.join(HOME_DIR, "workspaces.json");
|
||||
|
||||
const foldKey = (p) => {
|
||||
const resolved = path.resolve(String(p || ""));
|
||||
return process.platform === "win32" || process.platform === "darwin" ? resolved.toLowerCase() : resolved;
|
||||
};
|
||||
|
||||
// `specs/<name>` with forward slashes and no trailing slash, or "" for none.
|
||||
export function specKey(specDir) {
|
||||
return String(specDir || "")
|
||||
.trim()
|
||||
.replace(/\\/g, "/")
|
||||
.replace(/^\.\//, "")
|
||||
.replace(/\/+$/, "");
|
||||
}
|
||||
|
||||
function readStore() {
|
||||
const saved = readJson(WORKSPACES_FILE, null);
|
||||
return saved && typeof saved.projects === "object" && saved.projects ? saved : { projects: {} };
|
||||
}
|
||||
|
||||
/**
|
||||
* What was remembered for this folder and spec: `{ entry, from }`, where
|
||||
* `from` is "spec" when the spec has its own list, "project" when it falls
|
||||
* back to the project's (a spec's list starts as a copy of it), and null
|
||||
* when nothing was ever saved.
|
||||
*/
|
||||
export function rememberedWorkspace(worktree, specDir) {
|
||||
const project = readStore().projects[foldKey(worktree)];
|
||||
if (!project) return { entry: null, from: null };
|
||||
const spec = specKey(specDir);
|
||||
if (spec && project.specs && project.specs[spec]) return { entry: project.specs[spec], from: "spec" };
|
||||
return project.project ? { entry: project.project, from: "project" } : { entry: null, from: null };
|
||||
}
|
||||
|
||||
// The workspace's folders as the store keeps them.
|
||||
export function rememberable(ws) {
|
||||
const folders = (ws && ws.folders) || [];
|
||||
const first = folders.find((f) => f.original) || {};
|
||||
return {
|
||||
version: 0,
|
||||
folders: [{ id: "f0", path: worktree, name: defaultName(worktree), description: "", original: true }],
|
||||
missing: [],
|
||||
changes: [],
|
||||
remote: "",
|
||||
original: { name: first.name || "", description: first.description || "" },
|
||||
folders: folders
|
||||
.filter((f) => !f.original)
|
||||
.map((f) => ({ path: f.path, name: f.name, description: f.description || "", ...(f.nested ? { nested: true } : {}) })),
|
||||
at: nowIso(),
|
||||
};
|
||||
}
|
||||
|
||||
// Every server and `console.mjs forget` writes the one file, so each
|
||||
// read-modify-write holds this lock beside it.
|
||||
const WORKSPACES_LOCK = "workspaces.json.lock";
|
||||
|
||||
// Save the list for this folder and spec ("" for the project's own).
|
||||
export function rememberWorkspace(worktree, specDir, ws) {
|
||||
ensureDir(path.dirname(WORKSPACES_FILE));
|
||||
withStateLock(path.dirname(WORKSPACES_FILE), () => saveRemembered(worktree, specDir, ws), WORKSPACES_LOCK);
|
||||
}
|
||||
|
||||
function saveRemembered(worktree, specDir, ws) {
|
||||
const store = readStore();
|
||||
const key = foldKey(worktree);
|
||||
const project = store.projects[key] || { path: path.resolve(worktree) };
|
||||
const spec = specKey(specDir);
|
||||
if (spec) project.specs = { ...(project.specs || {}), [spec]: rememberable(ws) };
|
||||
else project.project = rememberable(ws);
|
||||
store.projects[key] = project;
|
||||
writeJsonAtomic(WORKSPACES_FILE, store);
|
||||
}
|
||||
|
||||
// Drop one spec's list (Finalize, once the spec is archived). True when there was one.
|
||||
export function forgetWorkspace(worktree, specDir) {
|
||||
const spec = specKey(specDir);
|
||||
if (!spec || !fs.existsSync(WORKSPACES_FILE)) return false;
|
||||
return withStateLock(path.dirname(WORKSPACES_FILE), () => dropRemembered(worktree, spec), WORKSPACES_LOCK);
|
||||
}
|
||||
|
||||
function dropRemembered(worktree, spec) {
|
||||
const store = readStore();
|
||||
const project = store.projects[foldKey(worktree)];
|
||||
if (!spec || !project || !project.specs || !project.specs[spec]) return false;
|
||||
delete project.specs[spec];
|
||||
writeJsonAtomic(WORKSPACES_FILE, store);
|
||||
return true;
|
||||
}
|
||||
|
||||
// Single-writer rule: only server.mjs may call this.
|
||||
export function writeWorkspace(dir, ws) {
|
||||
return writeJsonAtomic(path.join(dir, WORKSPACE_FILE), ws);
|
||||
|
||||
@@ -2505,6 +2505,9 @@ a.icon-btn { box-sizing: border-box; text-decoration: none; }
|
||||
actions stay put. */
|
||||
.modal.workspace { max-width: 680px; }
|
||||
.modal.workspace[open] { display: flex; flex-direction: column; max-height: calc(100vh - 48px); }
|
||||
.workspace .modal-blurb { margin-bottom: 6px; }
|
||||
.workspace-scope { margin: 0 0 16px; color: var(--ink-3, var(--ink-2)); font-size: 12.5px; }
|
||||
|
||||
.workspace-list {
|
||||
list-style: none; margin: 0; padding: 0;
|
||||
display: grid; gap: 12px;
|
||||
|
||||
@@ -2542,6 +2542,7 @@ function renderDashboard(main) {
|
||||
const specs = specList();
|
||||
if (specs.length) wrap.appendChild(renderSpecPicker(specs));
|
||||
wrap.appendChild(hideUnavailableToggle());
|
||||
if (!local.launching && !launchScoping) 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
|
||||
@@ -2963,6 +2964,11 @@ async function launchSkill(entry) {
|
||||
// cards that take no spec (utilities, setup) launch untargeted even while
|
||||
// a spec is selected.
|
||||
if (target) action.spec = target.dir;
|
||||
// The skill opens on the folders remembered for what it was launched for.
|
||||
// Held until the launch is in flight: the swap's own frame re-renders the
|
||||
// dashboard, which would otherwise sync back to the picker's spec.
|
||||
launchScoping = true;
|
||||
await syncWorkspaceScope(target ? target.dir : "");
|
||||
try {
|
||||
const res = await fetch("/submit", {
|
||||
method: "POST",
|
||||
@@ -2973,6 +2979,7 @@ async function launchSkill(entry) {
|
||||
}),
|
||||
});
|
||||
if (res.status === 409) {
|
||||
launchScoping = false;
|
||||
pendingResult = true;
|
||||
banner("Your last pick is still being picked up. One moment.", "info");
|
||||
return;
|
||||
@@ -2980,10 +2987,12 @@ async function launchSkill(entry) {
|
||||
if (!res.ok) throw new Error(String(res.status));
|
||||
sound("startSkill");
|
||||
local.launching = { skill: entry.skill, title: entry.title, at: Date.now() };
|
||||
launchScoping = false;
|
||||
pendingResult = true;
|
||||
save();
|
||||
render();
|
||||
} catch {
|
||||
launchScoping = false;
|
||||
banner("That did not go through. Nothing was lost; try again.", "warn");
|
||||
}
|
||||
}
|
||||
@@ -5854,6 +5863,32 @@ async function postJson(url, body) {
|
||||
}
|
||||
}
|
||||
|
||||
/* The workspace follows the dashboard's picker: the folders remembered for
|
||||
the selected spec, or the project's own under "Start from scratch". The
|
||||
server swaps the list and remembers every change after it. */
|
||||
let scopeAsked = null;
|
||||
// True from a launch's scope sync until its send has gone (or failed).
|
||||
let launchScoping = false;
|
||||
async function syncWorkspaceScope(spec) {
|
||||
if (!S || S.workflow !== "dashboard" || gone || !wsFrame) return;
|
||||
const want = spec === undefined ? (selSpec() && selSpec().dir) || "" : spec;
|
||||
if ((wsFrame.scope || "") === want || scopeAsked === want) return;
|
||||
scopeAsked = want;
|
||||
const { status, body } = await postJson("/workspace/scope", { spec: want });
|
||||
if (status === 200 && body && Array.isArray(body.folders)) wsFrame = { ...wsFrame, ...body };
|
||||
scopeAsked = null;
|
||||
if ($("workspace-modal").open) renderWorkspace();
|
||||
}
|
||||
|
||||
// The dialog's "Remembered for" line: whose list this is.
|
||||
function workspaceScopeText() {
|
||||
const scope = (wsFrame && wsFrame.scope) || "";
|
||||
if (!scope) return "Remembered for this project, so your next console session here starts with these folders.";
|
||||
const spec = specList().find((s) => s.dir === scope);
|
||||
const name = spec ? spec.name : scope.split("/").pop();
|
||||
return `Remembered for the ${name} spec, and loaded again whenever it is picked.`;
|
||||
}
|
||||
|
||||
const NAME_RULE = "Names use lowercase letters, numbers and hyphens.";
|
||||
const BROWSE_UNAVAILABLE = "Browse isn't available here — type or paste the path.";
|
||||
// The folder whose Remove is waiting on its inline confirm, by id.
|
||||
@@ -5893,6 +5928,7 @@ function renderWorkspace() {
|
||||
}
|
||||
folders.forEach((f, i) => paintWorkspaceRow(list.children[i], f));
|
||||
$("workspace-browse").hidden = Boolean(wsFrame && wsFrame.remote);
|
||||
$("workspace-scope").textContent = workspaceScopeText();
|
||||
}
|
||||
|
||||
function workspaceRow(f) {
|
||||
|
||||
@@ -833,10 +833,28 @@
|
||||
Click the folder name in the middle of the bottom bar. It shows your
|
||||
folder's name and branch, such as <strong>shop · main</strong>, and
|
||||
<strong>shop + 2 folders · main</strong> once you have added some.
|
||||
The workspace lasts for this console session only: it carries across
|
||||
steps you start from the dashboard, and a new console session starts
|
||||
with just the folder you started in.
|
||||
It carries across steps you start from the dashboard.
|
||||
</p>
|
||||
<h4>Remembered for next time</h4>
|
||||
<ul>
|
||||
<li>
|
||||
Every change is saved as you make it, so the next console session in
|
||||
this folder starts with the same folders.
|
||||
</li>
|
||||
<li>
|
||||
Each spec keeps its own list. The first time you pick a spec on the
|
||||
dashboard it starts as a copy of the project's list (the one shown
|
||||
under <strong>Start from scratch</strong>), and after that the two
|
||||
are separate. Picking a spec loads its list; the line under the
|
||||
dialog's title says whose list you are looking at.
|
||||
</li>
|
||||
<li>
|
||||
The lists live in <code>workspaces.json</code> in your own
|
||||
Plan2Code settings folder, beside your look and feel, never in the
|
||||
project. Finalize offers to forget a spec's list when it archives the
|
||||
spec.
|
||||
</li>
|
||||
</ul>
|
||||
<h4>Adding a folder</h4>
|
||||
<ul>
|
||||
<li>
|
||||
@@ -1363,9 +1381,10 @@
|
||||
<h4>What it counts</h4>
|
||||
<p>
|
||||
Each step you run here adds points: a plan or a set of documents
|
||||
weighs more than a single answered question, and a built phase more
|
||||
still, by how many tasks it completed: a big phase adds more than a
|
||||
small one. Every two questions you answer add a point too, so a long
|
||||
weighs more than a quick task, and a built phase more still, by how
|
||||
many tasks it completed: a big phase adds more than a small one.
|
||||
Every two questions you answer within one step add a point too
|
||||
(rounded down, so a single answer adds nothing), so a long
|
||||
back-and-forth counts for more than a short one. Click the ring to see the count and a list of each step that added
|
||||
points, with what it added. It is a rule of thumb, not a
|
||||
reading of Plan2Code's real memory: long sessions tend to make it
|
||||
@@ -2003,6 +2022,7 @@
|
||||
The folders the agent uses as context this session. It reads the extra ones for
|
||||
reference and only changes them if you ask.
|
||||
</p>
|
||||
<p class="workspace-scope" id="workspace-scope"></p>
|
||||
<ul class="workspace-list" id="workspace-list"></ul>
|
||||
<div class="workspace-add">
|
||||
<label class="workspace-add-label" for="workspace-path">Add a folder</label>
|
||||
|
||||
@@ -45,7 +45,10 @@ import {
|
||||
readLedger,
|
||||
readOverview,
|
||||
readWorkspace,
|
||||
rememberWorkspace,
|
||||
rememberedWorkspace,
|
||||
remoteWarning,
|
||||
specKey,
|
||||
typedCount,
|
||||
withStateLock,
|
||||
writeJsonAtomic,
|
||||
@@ -326,7 +329,9 @@ function workspaceNow() {
|
||||
return ws;
|
||||
}
|
||||
const root = sessionWorktree();
|
||||
const fresh = { ...initialWorkspace(root || PROJECT), remote: remoteWarning().remote || "" };
|
||||
const scope = specKey(stateNow?.specDir);
|
||||
const remembered = root ? rememberedWorkspace(root, scope).entry : null;
|
||||
const fresh = { ...initialWorkspace(root || PROJECT, remembered), scope, remote: remoteWarning().remote || "" };
|
||||
// There but unreadable for now (a scanner's lock): never written over, and
|
||||
// never cached, so the next call reads it again.
|
||||
if (stamp) return workspaceSeen.ws || fresh;
|
||||
@@ -347,13 +352,87 @@ function saveWorkspace(ws) {
|
||||
|
||||
// One change: a new version, an entry in the change log the agent is handed,
|
||||
// the file, and every open page.
|
||||
function bumpWorkspace(ws, change) {
|
||||
function bumpWorkspace(ws, change, { remember = true } = {}) {
|
||||
ws.version = (ws.version || 0) + 1;
|
||||
ws.changes = [...(ws.changes || []), { ...change, version: ws.version }];
|
||||
saveWorkspace(ws);
|
||||
// Remembered for the next console session too. A folder gone missing or
|
||||
// found again is not a change of mind, so it is not saved.
|
||||
if (remember) rememberNow(ws);
|
||||
pushState();
|
||||
}
|
||||
|
||||
function rememberNow(ws) {
|
||||
const root = sessionWorktree();
|
||||
if (!root) return;
|
||||
try {
|
||||
rememberWorkspace(root, ws.scope || "", ws);
|
||||
} catch {}
|
||||
}
|
||||
|
||||
/**
|
||||
* Point the workspace at another spec ("" for the project's own list) and
|
||||
* swap in what was remembered there, logging each difference as a change so
|
||||
* the agent's cursor stays truthful. A spec with nothing saved starts from
|
||||
* the project's list (`seed: "project"`, the dashboard picker) or keeps the
|
||||
* list it has and saves it as the spec's (`seed: "current"`, a spec created
|
||||
* mid-run). Folders keep their ids when their path stays.
|
||||
*/
|
||||
function setScope(ws, spec, seed = "project") {
|
||||
const root = sessionWorktree();
|
||||
const next = specKey(spec);
|
||||
if (!root || (ws.scope || "") === next) return false;
|
||||
const found = rememberedWorkspace(root, next);
|
||||
ws.scope = next;
|
||||
if (next && found.from !== "spec" && seed === "current") {
|
||||
saveWorkspace(ws);
|
||||
rememberNow(ws);
|
||||
pushState();
|
||||
return true;
|
||||
}
|
||||
const want = initialWorkspace(root, found.entry).folders;
|
||||
const byPath = new Map(ws.folders.map((f) => [foldPath(path.resolve(f.path)), f]));
|
||||
const kept = new Set();
|
||||
const folders = [];
|
||||
const changes = [];
|
||||
for (const w of want) {
|
||||
const have = w.original ? ws.folders.find((f) => f.original) : byPath.get(foldPath(path.resolve(w.path)));
|
||||
if (!have) {
|
||||
folders.push({ ...w, id: "pending" });
|
||||
changes.push({ kind: "added", name: w.name, path: w.path, description: w.description });
|
||||
continue;
|
||||
}
|
||||
kept.add(have);
|
||||
if (have.name !== w.name) changes.push({ kind: "renamed", from: have.name, name: w.name, path: have.path });
|
||||
if ((have.description || "") !== (w.description || "")) {
|
||||
changes.push({ kind: "described", name: w.name, path: have.path, description: w.description || "" });
|
||||
}
|
||||
folders.push({ ...have, name: w.name, description: w.description || "" });
|
||||
}
|
||||
for (const f of ws.folders) {
|
||||
if (!kept.has(f)) changes.unshift({ kind: "removed", name: f.name, path: f.path });
|
||||
}
|
||||
ws.folders = folders.filter((f) => f.id !== "pending");
|
||||
for (const f of folders.filter((f) => f.id === "pending")) ws.folders.push({ ...f, id: nextFolderId(ws) });
|
||||
ws.missing = (ws.missing || []).filter((id) => ws.folders.some((f) => f.id === id));
|
||||
if (!changes.length) {
|
||||
saveWorkspace(ws);
|
||||
pushState();
|
||||
}
|
||||
for (const c of changes) bumpWorkspace(ws, c, { remember: false });
|
||||
checkFolders(ws);
|
||||
return true;
|
||||
}
|
||||
|
||||
// A spec posted mid-run (Pathfinder or Plan making its folder, a skill that
|
||||
// learns its spec late) takes the workspace with it.
|
||||
function followSpecDir(state) {
|
||||
const spec = specKey(state && state.specDir);
|
||||
if (!spec || !fileStamp(WORKSPACE_PATH)) return;
|
||||
const ws = workspaceNow();
|
||||
if ((ws.scope || "") !== spec) setScope(ws, spec, "current");
|
||||
}
|
||||
|
||||
function isFolder(p) {
|
||||
try {
|
||||
return fs.statSync(p).isDirectory();
|
||||
@@ -370,10 +449,10 @@ function checkFolders(ws) {
|
||||
const marked = ws.missing.includes(f.id);
|
||||
if (!there && !marked) {
|
||||
ws.missing = [...ws.missing, f.id];
|
||||
bumpWorkspace(ws, { kind: "missing", name: f.name, path: f.path });
|
||||
bumpWorkspace(ws, { kind: "missing", name: f.name, path: f.path }, { remember: false });
|
||||
} else if (there && marked) {
|
||||
ws.missing = ws.missing.filter((id) => id !== f.id);
|
||||
bumpWorkspace(ws, { kind: "found", name: f.name, path: f.path });
|
||||
bumpWorkspace(ws, { kind: "found", name: f.name, path: f.path }, { remember: false });
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -402,8 +481,8 @@ function folderIssues(entries) {
|
||||
}
|
||||
|
||||
function workspaceView() {
|
||||
const { folders, missing, remote } = workspaceNow();
|
||||
return { folders, missing: missing || [], remote: remote || "", issues: folderIssues(ledgerEntries()) };
|
||||
const { folders, missing, remote, scope } = workspaceNow();
|
||||
return { folders, missing: missing || [], remote: remote || "", scope: scope || "", issues: folderIssues(ledgerEntries()) };
|
||||
}
|
||||
|
||||
// Whether child sits strictly under parent.
|
||||
@@ -492,6 +571,7 @@ function bootWorkspace() {
|
||||
saveWorkspace(ws);
|
||||
}
|
||||
checkFolders(ws);
|
||||
followSpecDir(stateNow);
|
||||
}
|
||||
|
||||
/**
|
||||
@@ -1403,6 +1483,24 @@ const server = http.createServer((req, res) => {
|
||||
});
|
||||
}
|
||||
|
||||
// Which list the workspace is: a spec's, or the project's (`spec` empty).
|
||||
// The dashboard's picker sends it as the selection moves and before a
|
||||
// launch, so a skill opens on the list of the spec it was launched for.
|
||||
if (pathname === "/workspace/scope" && req.method === "POST") {
|
||||
if (!originOk(req, port)) return json(res, 403, { error: "bad origin" });
|
||||
return readBody(req, (err, body) => {
|
||||
if (err || !body || typeof body !== "object" || Array.isArray(body)) return json(res, 400, { error: "bad" });
|
||||
const spec = typeof body.spec === "string" ? body.spec : "";
|
||||
if (spec && !/^specs\/[^/\\]+$/.test(specKey(spec))) return json(res, 400, { reason: "bad-spec" });
|
||||
try {
|
||||
setScope(workspaceNow(), spec, "project");
|
||||
} catch (e) {
|
||||
return json(res, 500, { error: String(e.message) });
|
||||
}
|
||||
return json(res, 200, workspaceView());
|
||||
});
|
||||
}
|
||||
|
||||
// Only ever returns a path: the page then adds it through /workspace/add.
|
||||
if (pathname === "/workspace/browse" && req.method === "POST") {
|
||||
if (!originOk(req, port)) return json(res, 403, { error: "bad origin" });
|
||||
@@ -1561,6 +1659,9 @@ function checkState() {
|
||||
try {
|
||||
ensureConversation(parsed);
|
||||
} catch {}
|
||||
try {
|
||||
followSpecDir(parsed);
|
||||
} catch {}
|
||||
pushState();
|
||||
}
|
||||
lastStateStamp = stamp;
|
||||
|
||||
@@ -17,6 +17,6 @@
|
||||
"url": "https://github.com/jparkerweb/plan2code"
|
||||
},
|
||||
"homepage": "https://github.com/jparkerweb/plan2code",
|
||||
"releaseDate": "2026-10-02",
|
||||
"releaseDate": "2026-10-04",
|
||||
"mode": "utility"
|
||||
}
|
||||
@@ -0,0 +1,120 @@
|
||||
#!/usr/bin/env node
|
||||
// commit-msg.mjs: the team's commit message, built from the branch name.
|
||||
//
|
||||
// Every Plan2Code skill that suggests a commit uses one format:
|
||||
//
|
||||
// <subject>
|
||||
//
|
||||
// <JIRA-Ticket-ID>
|
||||
// AI Assisted
|
||||
//
|
||||
// and derives the ticket from a branch named <prefix>/<TICKET-ID>-description,
|
||||
// where the ticket is an uppercase project key, a hyphen and an integer
|
||||
// (ABC-10968). This script reads the branch, extracts the ticket and prints
|
||||
// the exact command, so no prompt re-implements the rule by eye.
|
||||
|
||||
import { execFileSync } from "node:child_process";
|
||||
import { EXIT, fail, out, parseArgs, run } from "./common.mjs";
|
||||
|
||||
const USAGE = `
|
||||
commit-msg.mjs: build the team's commit command from the current branch. JSON on stdout.
|
||||
|
||||
node commit-msg.mjs --subject "<subject>" [--add-all | --files <path> ...] [--ticket <ID>]
|
||||
|
||||
--subject the one-line description (at most 100 characters). No double
|
||||
quotes (straight or curly), backticks, $, backslashes or ! in it,
|
||||
so the command pastes unchanged into bash, zsh and PowerShell.
|
||||
--add-all prefix the command with "git add -A &&".
|
||||
--files prefix it with "git add -- <files> &&" (repeat --files per path).
|
||||
--ticket use this ticket ID instead of reading the branch.
|
||||
|
||||
Prints { ok, branch, ticket, subject, message, command, add, commit }. The
|
||||
commit is three -m flags, exactly: subject, ticket, "AI Assisted". command is
|
||||
add && commit, one line for bash, zsh and PowerShell 7+. Windows PowerShell 5.1
|
||||
has no &&: run add (null when nothing is staged) and then commit as two
|
||||
commands. Nothing is run.
|
||||
|
||||
Exit: 0 ok · 2 bad arguments (including a stray argument: one --files per
|
||||
path) · 3 not a git repository / no branch (detached HEAD) · 4 the branch
|
||||
carries no ticket ID, --ticket is not KEY-123, the subject breaks a rule, or a
|
||||
path cannot be quoted safely.
|
||||
`;
|
||||
|
||||
// The ticket is the first <KEY>-<number> path segment start after a "/" (or the
|
||||
// branch start), ended by "-", "_", "/" or the end of the name.
|
||||
const TICKET_RE = /(?:^|\/)([A-Z][A-Z0-9]*-\d+)(?=[-_/]|$)/;
|
||||
|
||||
function ticketFromBranch(branch) {
|
||||
const m = String(branch || "").match(TICKET_RE);
|
||||
return m ? m[1] : null;
|
||||
}
|
||||
|
||||
function git(args) {
|
||||
try {
|
||||
return { ok: true, out: execFileSync("git", args, { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }).trim() };
|
||||
} catch {
|
||||
return { ok: false };
|
||||
}
|
||||
}
|
||||
|
||||
function currentBranch() {
|
||||
if (!git(["rev-parse", "--git-dir"]).ok) {
|
||||
fail(EXIT.NOT_FOUND, "not-a-repo", "This directory is not inside a git repository.", "Run from the project root, or skip the commit suggestion.");
|
||||
}
|
||||
// symbolic-ref names the branch even before the first commit, where
|
||||
// rev-parse --abbrev-ref HEAD fails; it fails only on a detached HEAD.
|
||||
const ref = git(["symbolic-ref", "--short", "-q", "HEAD"]);
|
||||
if (!ref.ok || !ref.out) fail(EXIT.NOT_FOUND, "detached-head", "HEAD is detached, so there is no branch name to read a ticket from.", "Ask the user for the ticket ID and pass --ticket <ID>.");
|
||||
return ref.out;
|
||||
}
|
||||
|
||||
// A path goes into the command as-is when it is plainly safe, in single quotes
|
||||
// otherwise (literal in bash, zsh and PowerShell alike). Backslashes become
|
||||
// forward slashes, which git accepts on every platform. A leading @ or - is
|
||||
// quoted too: unquoted, PowerShell reads @types as a splat and the path
|
||||
// vanishes. The command's `git add --` means a leading - is never an option.
|
||||
function quoteFile(f) {
|
||||
const p = f.replace(/\\/g, "/");
|
||||
if (/^[\w./:+][\w./:@+-]*$/.test(p)) return p;
|
||||
// PowerShell treats the curly single quotes as quote characters too.
|
||||
if (/['\u2018-\u201B]/.test(p)) fail(EXIT.INVALID, "unsafe-path", `The path ${p} contains a single quote, which cannot be quoted the same way in bash and PowerShell.`, "Use --add-all, or leave that file out and stage it by hand.");
|
||||
return `'${p}'`;
|
||||
}
|
||||
|
||||
run(USAGE, async (argv) => {
|
||||
const args = parseArgs(argv, { booleans: ["add-all"], values: ["subject", "ticket"], lists: ["files"] });
|
||||
if (args._.length) fail(EXIT.USAGE, "stray-argument", `Unexpected argument(s): ${args._.join(" ")}.`, "Each path needs its own --files (e.g. --files a.js --files b.js); quote a subject with spaces.");
|
||||
const subject = (args.subject || "").trim();
|
||||
if (!subject) fail(EXIT.USAGE, "missing-subject", "--subject is required.", 'Example: --subject "Add the export endpoint"');
|
||||
if (/[\r\n]/.test(subject)) fail(EXIT.INVALID, "multiline-subject", "The subject must be one line.", "The diff is the body; keep the subject to one line.");
|
||||
if (subject.length > 100) fail(EXIT.INVALID, "subject-too-long", `The subject is ${subject.length} characters; the limit is 100.`, "Shorten it; the diff is the body and the PR is the explanation.");
|
||||
// Inside "...": PowerShell ends the string at a curly double quote too,
|
||||
// bash and zsh treat \ as an escape, and ! is history expansion in an
|
||||
// interactive bash or zsh.
|
||||
if (/["`$\\!\u201C-\u201F]/.test(subject)) fail(EXIT.INVALID, "unsafe-subject", "The subject contains a double quote (straight or curly), backtick, $, backslash or !, which bash, zsh and PowerShell read differently inside double quotes.", "Rephrase without those characters (single quotes are fine).");
|
||||
if (args["add-all"] && args.files) fail(EXIT.USAGE, "add-conflict", "Use --add-all or --files, not both.", "Pick one.");
|
||||
|
||||
let branch = null;
|
||||
let ticket = args.ticket ? args.ticket.trim() : null;
|
||||
if (ticket && !/^[A-Z][A-Z0-9]*-\d+$/.test(ticket)) fail(EXIT.INVALID, "bad-ticket", `"${ticket}" is not an uppercase KEY-123 ticket ID.`, "Pass a ticket like ABC-10968.");
|
||||
if (!ticket) {
|
||||
branch = currentBranch();
|
||||
ticket = ticketFromBranch(branch);
|
||||
if (!ticket) {
|
||||
fail(EXIT.INVALID, "no-ticket", `The branch "${branch}" has no <prefix>/<TICKET-ID>-description ticket in it.`, "Ask the user for the ticket ID, then rerun with --ticket <ID>; or show the command with <JIRA-Ticket-ID> for them to fill in.");
|
||||
}
|
||||
}
|
||||
|
||||
const add = args["add-all"] ? "git add -A" : args.files ? `git add -- ${args.files.map(quoteFile).join(" ")}` : null;
|
||||
const commit = `git commit -m "${subject}" -m "${ticket}" -m "AI Assisted"`;
|
||||
out({
|
||||
ok: true,
|
||||
branch,
|
||||
ticket,
|
||||
subject,
|
||||
message: `${subject}\n\n${ticket}\nAI Assisted`,
|
||||
command: add ? `${add} && ${commit}` : commit,
|
||||
add,
|
||||
commit,
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,247 @@
|
||||
// Plan2Code skill scripts: shared plumbing.
|
||||
//
|
||||
// Every script in a skill's scripts/ directory imports this file. It owns the
|
||||
// conventions the SKILL.md prompts rely on, so they are identical everywhere:
|
||||
//
|
||||
// stdout one JSON object, always. `{ "ok": true, ... }` on success,
|
||||
// `{ "ok": false, "error": "<code>", "message": "...", "next": "..." }`
|
||||
// on a handled failure.
|
||||
// stderr a one-line human diagnostic on failure (the same message + next).
|
||||
// exit 0 ok · 1 unexpected crash · 2 bad arguments · 3 not found ·
|
||||
// 4 invalid input or a check that failed · 5 refused (would clobber
|
||||
// or break a rule).
|
||||
//
|
||||
// Node 18+ built-ins only, no build step: this ships inside every skill.
|
||||
|
||||
import fs from "node:fs";
|
||||
import path from "node:path";
|
||||
import { fileURLToPath, pathToFileURL } from "node:url";
|
||||
|
||||
export const HERE = path.dirname(fileURLToPath(import.meta.url));
|
||||
|
||||
export const EXIT = { OK: 0, CRASH: 1, USAGE: 2, NOT_FOUND: 3, INVALID: 4, REFUSED: 5 };
|
||||
|
||||
export class CliError extends Error {
|
||||
constructor(exit, error, message, next) {
|
||||
super(message);
|
||||
this.exit = exit;
|
||||
this.error = error;
|
||||
this.next = next;
|
||||
}
|
||||
}
|
||||
|
||||
/** Throw a handled failure: the run() wrapper prints it and sets the exit code. */
|
||||
export function fail(exit, error, message, next) {
|
||||
throw new CliError(exit, error, message, next);
|
||||
}
|
||||
|
||||
export function out(obj) {
|
||||
process.stdout.write(JSON.stringify(obj, null, 2) + "\n");
|
||||
}
|
||||
|
||||
/**
|
||||
* Parse argv into { _: positionals, <flag>: value }.
|
||||
* `booleans` names flags that take no value; every other `--flag` takes the
|
||||
* next argument, and repeats of a flag listed in `lists` collect into an array.
|
||||
* `--flag=value` works too. Unknown flags are a usage error, so a typo never
|
||||
* silently changes behavior.
|
||||
*/
|
||||
export function parseArgs(argv, { booleans = [], values = [], lists = [] } = {}) {
|
||||
const known = new Set([...booleans, ...values, ...lists, "help"]);
|
||||
const args = { _: [] };
|
||||
for (let i = 0; i < argv.length; i++) {
|
||||
const a = argv[i];
|
||||
if (!a.startsWith("--")) {
|
||||
args._.push(a);
|
||||
continue;
|
||||
}
|
||||
let name = a.slice(2);
|
||||
let value;
|
||||
const eq = name.indexOf("=");
|
||||
if (eq !== -1) {
|
||||
value = name.slice(eq + 1);
|
||||
name = name.slice(0, eq);
|
||||
}
|
||||
if (!known.has(name)) {
|
||||
fail(EXIT.USAGE, "unknown-flag", `Unknown flag --${name}.`, "Run with --help for the flags this script takes.");
|
||||
}
|
||||
if (name === "help" || booleans.includes(name)) {
|
||||
args[name] = true;
|
||||
continue;
|
||||
}
|
||||
if (value === undefined) {
|
||||
if (i + 1 >= argv.length) {
|
||||
fail(EXIT.USAGE, "missing-value", `--${name} needs a value.`, "Run with --help for usage.");
|
||||
}
|
||||
value = argv[++i];
|
||||
}
|
||||
if (lists.includes(name)) (args[name] ||= []).push(value);
|
||||
else args[name] = value;
|
||||
}
|
||||
return args;
|
||||
}
|
||||
|
||||
/**
|
||||
* Run a script's main(). Prints usage on --help, turns CliError into the JSON
|
||||
* failure shape plus an exit code, and anything else into exit 1 with the stack
|
||||
* on stderr. Sets process.exitCode rather than calling process.exit(), so
|
||||
* stdout is never cut off mid-write.
|
||||
*/
|
||||
export async function run(usage, main) {
|
||||
try {
|
||||
const argv = process.argv.slice(2);
|
||||
if (argv.includes("--help") || argv.includes("-h")) {
|
||||
process.stdout.write(usage.trim() + "\n");
|
||||
return;
|
||||
}
|
||||
await main(argv);
|
||||
} catch (err) {
|
||||
if (err instanceof CliError) {
|
||||
out({ ok: false, error: err.error, message: err.message, ...(err.next ? { next: err.next } : {}) });
|
||||
process.stderr.write(`error: ${err.message}${err.next ? `\nnext: ${err.next}` : ""}\n`);
|
||||
process.exitCode = err.exit;
|
||||
return;
|
||||
}
|
||||
process.stderr.write(`unexpected error: ${err && err.stack ? err.stack : err}\n`);
|
||||
out({ ok: false, error: "crash", message: String(err && err.message ? err.message : err) });
|
||||
process.exitCode = EXIT.CRASH;
|
||||
}
|
||||
}
|
||||
|
||||
/* ------------------------------------------------------------------ time */
|
||||
|
||||
// PLAN2CODE_NOW ("YYYY-MM-DD HH:mm" or any Date-parsable string) pins the
|
||||
// clock, for tests and for reproducing a run. Otherwise: the local clock, which
|
||||
// is what "today" means to the person reading the date in their files.
|
||||
export function now() {
|
||||
const pinned = process.env.PLAN2CODE_NOW;
|
||||
if (pinned) {
|
||||
const m = pinned.match(/^(\d{4})-(\d{2})-(\d{2})(?:[ T](\d{2}):(\d{2})(?::(\d{2}))?)?$/);
|
||||
if (m) return new Date(+m[1], +m[2] - 1, +m[3], +(m[4] || 0), +(m[5] || 0), +(m[6] || 0));
|
||||
const d = new Date(pinned);
|
||||
if (!Number.isNaN(d.getTime())) return d;
|
||||
}
|
||||
return new Date();
|
||||
}
|
||||
|
||||
const pad = (n) => String(n).padStart(2, "0");
|
||||
|
||||
/** YYYY-MM-DD */
|
||||
export function isoDate(d = now()) {
|
||||
return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}`;
|
||||
}
|
||||
|
||||
/** YYYYMMDD */
|
||||
export function compactDate(d = now()) {
|
||||
return isoDate(d).replace(/-/g, "");
|
||||
}
|
||||
|
||||
/** YYYY-MM-DD HH:mm */
|
||||
export function stamp(d = now()) {
|
||||
return `${isoDate(d)} ${pad(d.getHours())}:${pad(d.getMinutes())}`;
|
||||
}
|
||||
|
||||
/** HHMMSS */
|
||||
export function clock(d = now()) {
|
||||
return `${pad(d.getHours())}${pad(d.getMinutes())}${pad(d.getSeconds())}`;
|
||||
}
|
||||
|
||||
/* ----------------------------------------------------------------- files */
|
||||
|
||||
export function readText(file) {
|
||||
try {
|
||||
return fs.readFileSync(file, "utf8");
|
||||
} catch {
|
||||
return null;
|
||||
}
|
||||
}
|
||||
|
||||
export function isDir(p) {
|
||||
try {
|
||||
return fs.statSync(p).isDirectory();
|
||||
} catch {
|
||||
return false;
|
||||
}
|
||||
}
|
||||
|
||||
/** Write a file only when its content changes. Returns true when it wrote. */
|
||||
export function writeIfChanged(file, content) {
|
||||
const current = readText(file);
|
||||
if (current === content) return false;
|
||||
fs.mkdirSync(path.dirname(file), { recursive: true });
|
||||
fs.writeFileSync(file, content);
|
||||
return true;
|
||||
}
|
||||
|
||||
/** Normalise line endings for parsing; keep the original for writing back. */
|
||||
export function eol(text) {
|
||||
return text.includes("\r\n") ? "\r\n" : "\n";
|
||||
}
|
||||
|
||||
/**
|
||||
* phase-N.md per phase number. An exact phase-N.md always wins over a sibling
|
||||
* such as phase-1-old.md; more than one candidate is reported, never guessed.
|
||||
* Shared so every script that counts a spec's tasks reads the same files.
|
||||
*/
|
||||
export function phaseFiles(dir) {
|
||||
const files = new Map();
|
||||
const extra = new Map();
|
||||
for (const name of fs.readdirSync(dir).sort()) {
|
||||
const m = name.match(/^phase-(\d+)\b[^/]*\.md$/i);
|
||||
if (!m) continue;
|
||||
const n = Number(m[1]);
|
||||
const exact = new RegExp(`^phase-0*${n}\\.md$`, "i").test(name);
|
||||
if (!files.has(n)) files.set(n, name);
|
||||
else if (exact) {
|
||||
(extra.get(n) || extra.set(n, []).get(n)).push(files.get(n));
|
||||
files.set(n, name);
|
||||
} else (extra.get(n) || extra.set(n, []).get(n)).push(name);
|
||||
}
|
||||
files.extra = extra;
|
||||
return files;
|
||||
}
|
||||
|
||||
/** Forward-slash path relative to root, for output the agent pastes into prompts. */
|
||||
export function rel(root, p) {
|
||||
return path.relative(root, p).split(path.sep).join("/") || ".";
|
||||
}
|
||||
|
||||
/* --------------------------------------------------------- the web console */
|
||||
|
||||
// The web console ships beside these scripts in every installed skill
|
||||
// (references/web-console/), and in this repo it sits at src/web-console/. Its
|
||||
// lib.mjs is the one home of the spec-state classifier and the loop-marker /
|
||||
// metrics-bait scan, so the scripts import it rather than keep a second copy.
|
||||
const CONSOLE_LIB_CANDIDATES = [
|
||||
path.join(HERE, "..", "references", "web-console", "lib.mjs"), // installed skill
|
||||
path.join(HERE, "..", "web-console", "lib.mjs"), // src/skill-scripts in the repo
|
||||
];
|
||||
|
||||
let consoleLibPromise;
|
||||
export function consoleLib() {
|
||||
consoleLibPromise ||= (async () => {
|
||||
for (const candidate of CONSOLE_LIB_CANDIDATES) {
|
||||
if (fs.existsSync(candidate)) return import(pathToFileURL(candidate).href);
|
||||
}
|
||||
fail(
|
||||
EXIT.NOT_FOUND,
|
||||
"console-lib-missing",
|
||||
`The web console's lib.mjs is not beside this script (looked in ${CONSOLE_LIB_CANDIDATES.join(", ")}).`,
|
||||
"The skill install is incomplete; reinstall the Plan2Code skills (node install.js)."
|
||||
);
|
||||
})();
|
||||
return consoleLibPromise;
|
||||
}
|
||||
|
||||
/** The version these scripts shipped with (scripts/version.json, or the repo's). */
|
||||
export function version() {
|
||||
for (const file of [path.join(HERE, "version.json"), path.join(HERE, "..", "..", "version.json")]) {
|
||||
const text = readText(file);
|
||||
if (!text) continue;
|
||||
try {
|
||||
const v = JSON.parse(text).version;
|
||||
if (typeof v === "string") return v;
|
||||
} catch {}
|
||||
}
|
||||
return null;
|
||||
}
|
||||
@@ -0,0 +1,138 @@
|
||||
#!/usr/bin/env node
|
||||
// review-scope.mjs: what a branch review would cover, from git.
|
||||
//
|
||||
// Review Mode's scope fallback is a fixed command sequence (status, diff, log,
|
||||
// name-only against the base branch) followed by arithmetic: how many files,
|
||||
// how many lines, what share are docs (the >70% rule), whether specs/ is in
|
||||
// scope, whether the change is big enough to batch by risk. This script runs
|
||||
// the sequence and does the arithmetic. Choosing the scope and the review type
|
||||
// from the user's words stays with the agent.
|
||||
|
||||
import fs from "node:fs";
|
||||
import path from "node:path";
|
||||
import { execFileSync } from "node:child_process";
|
||||
import { EXIT, fail, out, parseArgs, run } from "./common.mjs";
|
||||
|
||||
const USAGE = `
|
||||
review-scope.mjs: the branch-review scope from git. JSON on stdout.
|
||||
|
||||
node review-scope.mjs [--base <branch>] [--root <dir>]
|
||||
|
||||
--base the branch to compare against. Default: main if it exists (local or
|
||||
origin), else master. The output says which one it used. With
|
||||
neither (and no --base) it stops with no-base; only a repo with no
|
||||
commits yet goes on, counting uncommitted changes alone.
|
||||
|
||||
Covers commits on this branch since it left the base (base...HEAD), plus
|
||||
staged, unstaged and untracked changes. Prints the files with their status and
|
||||
line counts, totals, the share of .md files, the doc/code classification
|
||||
(docs or code when one side is more than 70% of files, else mixed),
|
||||
specsInScope, batchByRisk (50+ files) and the commits.
|
||||
|
||||
Exit: 0 ok (check "empty") · 2 bad arguments · 3 not a git repository, the
|
||||
--base branch does not exist, or (no --base) there is no main or master.
|
||||
`;
|
||||
|
||||
function git(root, args, { allowFail = false } = {}) {
|
||||
try {
|
||||
// core.quotePath=false: a non-ASCII path comes back as itself, not as an escaped, quoted string.
|
||||
return execFileSync("git", ["-c", "core.quotePath=false", ...args], { cwd: root, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], maxBuffer: 64 * 1024 * 1024 });
|
||||
} catch (err) {
|
||||
if (allowFail) return null;
|
||||
throw err;
|
||||
}
|
||||
}
|
||||
|
||||
function refExists(root, ref) {
|
||||
return git(root, ["rev-parse", "--verify", "--quiet", `${ref}^{commit}`], { allowFail: true }) !== null;
|
||||
}
|
||||
|
||||
function pickBase(root, wanted) {
|
||||
const candidates = wanted ? [wanted, `origin/${wanted}`] : ["main", "origin/main", "master", "origin/master"];
|
||||
for (const ref of candidates) if (refExists(root, ref)) return ref;
|
||||
return null;
|
||||
}
|
||||
|
||||
function parseNumstat(text, into, status) {
|
||||
for (const line of (text || "").split("\n")) {
|
||||
if (!line.trim()) continue;
|
||||
const [a, d, ...rest] = line.split("\t");
|
||||
let file = rest.join("\t");
|
||||
// Renames print as "old => new" or "dir/{old => new}/f"; keep the new path.
|
||||
// A move up a level ("d/{sub => }/f", "{sub => }/f") empties the brace, so
|
||||
// the doubled or leading slash it leaves behind is dropped.
|
||||
file = file.replace(/\{[^}]*=> ([^}]*)\}/, "$1").replace(/^.* => /, "").replace(/\/{2,}/g, "/").replace(/^\//, "");
|
||||
const entry = into.get(file) || { path: file, status: new Set(), added: 0, deleted: 0, binary: false };
|
||||
entry.status.add(status);
|
||||
if (a === "-" || d === "-") entry.binary = true;
|
||||
else {
|
||||
entry.added += Number(a);
|
||||
entry.deleted += Number(d);
|
||||
}
|
||||
into.set(file, entry);
|
||||
}
|
||||
}
|
||||
|
||||
// Prose docs only: a requirements.txt or CMakeLists.txt is not documentation.
|
||||
const DOC_RE = /\.(md|mdx|markdown|rst|adoc)$/i;
|
||||
|
||||
run(USAGE, async (argv) => {
|
||||
const args = parseArgs(argv, { values: ["base", "root"] });
|
||||
const root = path.resolve(args.root || ".");
|
||||
const top = git(root, ["rev-parse", "--show-toplevel"], { allowFail: true });
|
||||
if (!top) fail(EXIT.NOT_FOUND, "not-a-repo", `${root} is not inside a git repository.`, "Ask the user which files to review (Focused scope).");
|
||||
const repo = top.trim();
|
||||
const branch = (git(repo, ["rev-parse", "--abbrev-ref", "HEAD"], { allowFail: true }) || "").trim() || null;
|
||||
const base = pickBase(repo, args.base);
|
||||
if (args.base && !base) fail(EXIT.NOT_FOUND, "no-base", `No branch named ${args.base} (or origin/${args.base}).`, "Pass an existing --base, or omit it to use main / master.");
|
||||
// No main or master: counting only uncommitted work would hide every commit
|
||||
// on the branch, so stop and ask for the trunk. A repo with no commits yet
|
||||
// has nothing committed to miss, so it goes on.
|
||||
if (!base && refExists(repo, "HEAD")) {
|
||||
fail(EXIT.NOT_FOUND, "no-base", "There is no main or master branch (local or origin) to compare this branch with.", "Rerun with --base <trunk> (ask the user which branch is the trunk if unclear).");
|
||||
}
|
||||
|
||||
const files = new Map();
|
||||
let commits = [];
|
||||
if (base) {
|
||||
parseNumstat(git(repo, ["diff", "--numstat", "-M", `${base}...HEAD`], { allowFail: true }), files, "committed");
|
||||
commits = (git(repo, ["log", "--oneline", "--no-decorate", `${base}..HEAD`], { allowFail: true }) || "").split("\n").filter(Boolean);
|
||||
}
|
||||
parseNumstat(git(repo, ["diff", "--numstat", "-M", "--cached"], { allowFail: true }), files, "staged");
|
||||
parseNumstat(git(repo, ["diff", "--numstat", "-M"], { allowFail: true }), files, "unstaged");
|
||||
for (const f of (git(repo, ["ls-files", "--others", "--exclude-standard"], { allowFail: true }) || "").split("\n").filter(Boolean)) {
|
||||
let added = 0;
|
||||
let binary = false;
|
||||
try {
|
||||
const buf = fs.readFileSync(path.join(repo, f));
|
||||
if (buf.includes(0)) binary = true;
|
||||
else if (buf.length) added = buf.toString("utf8").split("\n").length - (buf.at(-1) === 10 ? 1 : 0);
|
||||
} catch {}
|
||||
files.set(f, { path: f, status: new Set(["untracked"]), added, deleted: 0, binary });
|
||||
}
|
||||
|
||||
const list = [...files.values()]
|
||||
.map((f) => ({ ...f, status: [...f.status] }))
|
||||
.sort((a, b) => a.path.localeCompare(b.path));
|
||||
const docs = list.filter((f) => DOC_RE.test(f.path)).length;
|
||||
const total = list.length;
|
||||
const docShare = total ? docs / total : 0;
|
||||
const lines = list.reduce((n, f) => n + f.added + f.deleted, 0);
|
||||
out({
|
||||
ok: true,
|
||||
repo,
|
||||
branch,
|
||||
base,
|
||||
...(base ? {} : { note: "No commits yet: only uncommitted changes are counted." }),
|
||||
empty: total === 0,
|
||||
counts: { files: total, lines, added: list.reduce((n, f) => n + f.added, 0), deleted: list.reduce((n, f) => n + f.deleted, 0), docs, code: total - docs },
|
||||
docShare: Number(docShare.toFixed(2)),
|
||||
mix: !total ? "none" : docShare > 0.7 ? "docs" : 1 - docShare > 0.7 ? "code" : "mixed",
|
||||
// specs/ is gitignored, so git rarely sees it: the conversation is the
|
||||
// better signal that a spec is under review.
|
||||
specsInScope: list.some((f) => /^specs\//.test(f.path)),
|
||||
batchByRisk: total >= 50,
|
||||
commits,
|
||||
files: list,
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,676 @@
|
||||
#!/usr/bin/env node
|
||||
// specs.mjs: where every spec under specs/ stands, read from its files.
|
||||
//
|
||||
// The pipeline skills (plan, document, implement, revise-plan, finalize,
|
||||
// review, handoff) all need the same filesystem facts: which specs exist, what
|
||||
// a spec's PLAN-DRAFT says, which phases are open, how many tasks are done.
|
||||
// Those have one correct answer, so this script computes them instead of each
|
||||
// prompt re-deriving them by hand. It also performs the two mechanical writes
|
||||
// (a Phase Checklist marker, the archive move), with --dry-run.
|
||||
//
|
||||
// Shell listing only matters to people: specs/ is gitignored, so editor search
|
||||
// tools skip it. This script reads the disk directly and does not care.
|
||||
|
||||
import fs from "node:fs";
|
||||
import path from "node:path";
|
||||
import { EXIT, fail, out, parseArgs, run, readText, isDir, rel, eol, consoleLib, isoDate, phaseFiles } from "./common.mjs";
|
||||
|
||||
const USAGE = `
|
||||
specs.mjs: spec state for the Plan2Code pipeline skills. JSON on stdout.
|
||||
|
||||
node specs.mjs list [--root <dir>]
|
||||
Every active spec under specs/ (never specs--completed/), newest first:
|
||||
state, detail, PLAN-DRAFT files with their **Status:** line, overview,
|
||||
phase count. Also the names already archived in specs--completed/.
|
||||
|
||||
node specs.mjs status <spec> [--root <dir>]
|
||||
One spec in full: the overview's Phase Checklist, Parallel Execution
|
||||
Groups, per-phase task counts by marker, task-numbering problems,
|
||||
completion, the implement phase-selection verdict ("next"), the pending
|
||||
phases, and consistency checks. <spec> is specs/<name>, <name>, or a path
|
||||
to its overview.md.
|
||||
|
||||
node specs.mjs metrics <spec> --step document|finalize [--set key=value ...]
|
||||
The METRICS_JSON comment for that step, countable fields computed from
|
||||
the files; judgment fields come from --set (numbers only).
|
||||
document: total_tasks, tasks_per_phase, phase_count,
|
||||
parallel_groups_identified computed; pass
|
||||
--set verification_items_added=N (your Verification Summary's
|
||||
Added total; the VERIFICATION comments are reported as a check).
|
||||
finalize: completion_rate_at_audit, tasks_completed, tasks_total; pass
|
||||
--set verification_failures_found=N
|
||||
--set documentation_updates_needed=N.
|
||||
|
||||
node specs.mjs mark <spec> --phase <N> --to open|in-progress|done [--dry-run]
|
||||
Set phase N's Phase Checklist marker in overview.md ([ ], [/], [x]).
|
||||
done also sets the phase file's Status line (**Status:**, **Status**:
|
||||
or Status:) to Complete (and warns if tasks are unfinished); open on a
|
||||
Complete phase sets it to In Progress. Warns when the phase file has no
|
||||
Status line. Refuses a phase with duplicate checklist rows, and refuses
|
||||
in-progress -> open (started work stays marked).
|
||||
|
||||
node specs.mjs archive <spec> [--dry-run]
|
||||
Move specs/<name>/ to specs--completed/<name>/. Refuses if the target
|
||||
exists, or if <spec> is not a folder directly under specs/.
|
||||
|
||||
Markers: [ ] pending · [/] in progress · [x] complete · [!] blocked · [?] assumed.
|
||||
Exit: 0 ok · 2 bad arguments · 3 spec not found · 4 cannot parse / check
|
||||
failed · 5 refused.
|
||||
`;
|
||||
|
||||
/* ------------------------------------------------------------- resolving */
|
||||
|
||||
function realOrResolved(p) {
|
||||
try {
|
||||
return fs.realpathSync.native(p);
|
||||
} catch {
|
||||
return path.resolve(p);
|
||||
}
|
||||
}
|
||||
|
||||
const samePath = (a, b) => (process.platform === "win32" ? a.toLowerCase() === b.toLowerCase() : a === b);
|
||||
|
||||
// Read-only commands (status, metrics) accept an archived spec, because
|
||||
// Finalize reads its own spec after Step 6 moved it. Writes never do.
|
||||
function resolveSpec(root, arg, { allowArchived = false } = {}) {
|
||||
if (!arg) fail(EXIT.USAGE, "missing-spec", "Name the spec: specs/<name>, <name>, or its overview.md path.", "Run `specs.mjs list` to see the active specs.");
|
||||
let p = arg.replace(/\\/g, "/").replace(/\/+$/, "");
|
||||
if (/\/overview\.md$/i.test(p) || /\/phase-[^/]*\.md$/i.test(p)) p = p.replace(/\/[^/]+$/, "");
|
||||
const abs = path.isAbsolute(p) ? p : p.includes("/") ? path.join(root, p) : path.join(root, "specs", p);
|
||||
const relPath = rel(root, abs);
|
||||
if (!allowArchived && /(^|\/)specs--completed(\/|$)/.test(relPath)) {
|
||||
fail(EXIT.REFUSED, "archived-spec", `${relPath} is archived; the pipeline only changes active specs under specs/.`, "Pick an active spec from `specs.mjs list`.");
|
||||
}
|
||||
// A spec is a folder directly under specs/ (or specs--completed/ for a read).
|
||||
// Without this, `archive .` would move all of specs/ and `archive ./src` a
|
||||
// source folder.
|
||||
const homes = [path.join(root, "specs"), ...(allowArchived ? [path.join(root, "specs--completed")] : [])].map(realOrResolved);
|
||||
const parent = realOrResolved(path.dirname(path.resolve(abs)));
|
||||
if (!homes.some((h) => samePath(h, parent))) {
|
||||
fail(EXIT.REFUSED, "not-a-spec", `${relPath} is not a spec folder: a spec sits directly under specs/${allowArchived ? " (or specs--completed/)" : ""}.`, "Pass specs/<name> or <name>; run `specs.mjs list` to see the active specs.");
|
||||
}
|
||||
if (!isDir(abs)) {
|
||||
fail(EXIT.NOT_FOUND, "spec-not-found", `No spec folder at ${relPath}.`, "Run `specs.mjs list` from the project root (or pass --root) to see the active specs.");
|
||||
}
|
||||
return { dir: abs, rel: relPath, name: path.basename(abs) };
|
||||
}
|
||||
|
||||
/* -------------------------------------------------------------- parsing */
|
||||
|
||||
const MARKERS = { " ": "pending", "/": "in-progress", x: "complete", X: "complete", "!": "blocked", "?": "assumed" };
|
||||
// Task 2.3, a lettered sub-task 3.6a, or a named one such as a testing task 1.T.
|
||||
const TASK_RE = /^\s*[-*] \[(.)\]\s+\*\*Task\s+(\d+)\.(\d+|[A-Za-z]+)([a-z]*)\b/;
|
||||
const CHECKBOX_RE = /^\s*[-*] \[(.)\]/;
|
||||
// The Status line in any of the forms people write it: **Status:**, **Status**:
|
||||
// or a plain Status:, optionally as a list item. Groups: everything up to the
|
||||
// value (kept as written when the value is rewritten), the value, trailing blanks.
|
||||
const STATUS_RE = /^([ \t]*(?:[-*][ \t]*)?(?:\*\*Status:\*\*|\*\*Status\*\*:|Status:)[ \t]*)(.+?)([ \t]*)$/m;
|
||||
|
||||
function statusOf(text) {
|
||||
const m = (text || "").match(STATUS_RE);
|
||||
return m ? m[2] : null;
|
||||
}
|
||||
|
||||
/** A markdown section's lines: from its heading to the next heading of the same or higher level. */
|
||||
function section(text, headingRe) {
|
||||
const lines = text.split(/\r?\n/);
|
||||
const start = lines.findIndex((l) => /^#{1,6}\s/.test(l) && headingRe.test(l));
|
||||
if (start === -1) return null;
|
||||
const level = lines[start].match(/^#+/)[0].length;
|
||||
let end = lines.length;
|
||||
for (let i = start + 1; i < lines.length; i++) {
|
||||
const m = lines[i].match(/^(#+)\s/);
|
||||
if (m && m[1].length <= level) {
|
||||
end = i;
|
||||
break;
|
||||
}
|
||||
}
|
||||
return { start, end, lines: lines.slice(start + 1, end) };
|
||||
}
|
||||
|
||||
function plainText(s) {
|
||||
return s
|
||||
.replace(/\[([^\]]*)\]\([^)]*\)/g, "$1")
|
||||
.replace(/[*_`]/g, "")
|
||||
.replace(/\s+/g, " ")
|
||||
.trim();
|
||||
}
|
||||
|
||||
/** Phase Checklist rows: the first "Phase N" on each checkbox line names the phase. */
|
||||
function parseChecklist(overview) {
|
||||
const sec = section(overview, /Phase Checklist/i);
|
||||
if (!sec) return { found: false, phases: [], unparsed: [] };
|
||||
const phases = [];
|
||||
const unparsed = [];
|
||||
sec.lines.forEach((line, i) => {
|
||||
const m = line.match(CHECKBOX_RE);
|
||||
if (!m) return;
|
||||
const text = plainText(line.replace(CHECKBOX_RE, ""));
|
||||
const num = text.match(/\bPhase\s+(\d+)\b/i);
|
||||
if (!num) {
|
||||
unparsed.push({ line: sec.start + 2 + i, text: line.trim() });
|
||||
return;
|
||||
}
|
||||
const after = text.slice(num.index + num[0].length).replace(/^\s*[:\-–—]\s*/, "");
|
||||
const name = after.split(/\s+[-–—]\s+|\s+\(|\s+_\(|:\s|\s+see\s+phase-/i)[0].replace(/\s*phase-\d+\.md\s*$/i, "").trim();
|
||||
phases.push({
|
||||
number: Number(num[1]),
|
||||
marker: m[1],
|
||||
state: MARKERS[m[1]] || "unknown",
|
||||
name: name.replace(/\s*\[Milestone[^\]]*\]\s*$/i, "") || `Phase ${num[1]}`,
|
||||
line: sec.start + 2 + i,
|
||||
});
|
||||
});
|
||||
return { found: true, phases, unparsed };
|
||||
}
|
||||
|
||||
/** "2, 3", "2-4" and "2–4" (or an em dash) alike: ranges expand, so a group cell never loses a phase. */
|
||||
function phaseList(cell) {
|
||||
const outList = [];
|
||||
for (const part of cell.match(/\d+\s*[-–\u2014]\s*\d+|\d+/g) || []) {
|
||||
const r = part.match(/^(\d+)\s*[-–\u2014]\s*(\d+)$/);
|
||||
if (r && Number(r[2]) >= Number(r[1]) && Number(r[2]) - Number(r[1]) < 100) {
|
||||
for (let n = Number(r[1]); n <= Number(r[2]); n++) outList.push(n);
|
||||
} else outList.push(...part.match(/\d+/g).map(Number));
|
||||
}
|
||||
return [...new Set(outList)];
|
||||
}
|
||||
|
||||
/** Parallel Execution Groups table: real groups only (a named group with 2+ phases). */
|
||||
function parseGroups(overview) {
|
||||
const sec = section(overview, /Parallel Execution Groups/i);
|
||||
if (!sec) return { found: false, groups: [] };
|
||||
const groups = [];
|
||||
const seen = new Set();
|
||||
for (const line of sec.lines) {
|
||||
if (!/^\s*\|/.test(line) || /^\s*\|[\s:|-]+\|\s*$/.test(line)) continue;
|
||||
const cells = line.split("|").slice(1, -1).map((c) => c.trim());
|
||||
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
|
||||
// ("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;
|
||||
const key = `${id}:${phases.join(",")}`;
|
||||
if (seen.has(key)) continue;
|
||||
seen.add(key);
|
||||
groups.push({ id, phases, reason: plainText(cells[2] || "") });
|
||||
}
|
||||
return { found: true, groups };
|
||||
}
|
||||
|
||||
function firstSentence(text) {
|
||||
const t = plainText(text);
|
||||
const m = t.match(/^(.+?[.!?])(\s|$)/);
|
||||
return (m ? m[1] : t).slice(0, 240);
|
||||
}
|
||||
|
||||
function parsePhaseFile(file, number) {
|
||||
const text = readText(file) || "";
|
||||
const lines = text.split(/\r?\n/);
|
||||
const title = (lines.find((l) => /^#\s/.test(l)) || "").replace(/^#\s+/, "").trim();
|
||||
const status = statusOf(text);
|
||||
const counts = { pending: 0, "in-progress": 0, complete: 0, blocked: 0, assumed: 0, unknown: 0 };
|
||||
const tasks = [];
|
||||
const strayCheckboxes = [];
|
||||
const unmatchedTasks = [];
|
||||
let heading = "";
|
||||
lines.forEach((line, i) => {
|
||||
const h = line.match(/^#{1,6}\s+(.*)$/);
|
||||
if (h) heading = plainText(h[1]);
|
||||
const t = line.match(TASK_RE);
|
||||
if (t) {
|
||||
const state = MARKERS[t[1]] || "unknown";
|
||||
counts[state]++;
|
||||
const named = !/^\d+$/.test(t[3]);
|
||||
tasks.push({ id: `${t[2]}.${t[3]}${t[4]}`, phase: Number(t[2]), seq: named ? null : Number(t[3]), named, suffix: t[4], marker: t[1], state, line: i + 1 });
|
||||
return;
|
||||
}
|
||||
// A line that looks like a task but is not counted as one (Task 1.4A,
|
||||
// "1. [ ] **Task", a non-bold "- [ ] Task 1.3") would make the audit undercount.
|
||||
if (/^\s*(?:[-*]|\d+\.)\s+\[.\].*\bTask\s+\d+\./i.test(line)) unmatchedTasks.push({ line: i + 1, text: line.trim().slice(0, 120) });
|
||||
if (CHECKBOX_RE.test(line)) strayCheckboxes.push({ line: i + 1, section: heading, text: line.trim().slice(0, 120) });
|
||||
});
|
||||
|
||||
// Numbering: every task belongs to this phase, the base numbers run 1..n with
|
||||
// no gaps or repeats, and a lettered task (3.6a) sits after its base (3.6).
|
||||
// Named tasks (1.T) are outside the numeric sequence.
|
||||
const numbering = [];
|
||||
const bases = [];
|
||||
for (const t of tasks) {
|
||||
if (t.phase !== number) numbering.push(`Task ${t.id} is in phase-${number}.md but numbered for Phase ${t.phase}`);
|
||||
if (!t.suffix && !t.named) bases.push(t.seq);
|
||||
}
|
||||
const seenIds = new Set();
|
||||
for (const t of tasks) {
|
||||
if (seenIds.has(t.id)) numbering.push(`Task ${t.id} appears more than once`);
|
||||
seenIds.add(t.id);
|
||||
if (t.suffix && !t.named && !bases.includes(t.seq)) numbering.push(`Task ${t.id} has no base Task ${t.phase}.${t.seq}`);
|
||||
}
|
||||
bases.forEach((seq, i) => {
|
||||
if (seq !== i + 1 && !numbering.some((n) => n.startsWith("Task numbering"))) {
|
||||
numbering.push(`Task numbering is not sequential: expected ${number}.${i + 1}, found ${number}.${seq}`);
|
||||
}
|
||||
});
|
||||
|
||||
const overviewSec = section(text, /^#{1,6}\s+Overview\b/i);
|
||||
const goalText = overviewSec ? overviewSec.lines.join("\n").split(/\n\s*\n/).map((p) => p.trim()).find((p) => p && !/^[-*|>]/.test(p)) : "";
|
||||
return {
|
||||
title,
|
||||
status,
|
||||
goal: goalText ? firstSentence(goalText) : null,
|
||||
total: tasks.length,
|
||||
counts,
|
||||
open: counts.pending + counts["in-progress"] + counts.blocked + counts.unknown,
|
||||
// Open work a phase cannot be approved over; blocked tasks may stand ([!] is allowed at sign-off).
|
||||
unfinished: counts.pending + counts["in-progress"] + counts.unknown,
|
||||
tasks,
|
||||
numbering,
|
||||
strayCheckboxes,
|
||||
unmatchedTasks,
|
||||
};
|
||||
}
|
||||
|
||||
function planDrafts(dir) {
|
||||
return fs
|
||||
.readdirSync(dir)
|
||||
.filter((n) => /^PLAN-DRAFT.*\.md$/i.test(n))
|
||||
.sort()
|
||||
.map((file) => ({
|
||||
file,
|
||||
archived: /-prev\.md$/i.test(file),
|
||||
status: statusOf(readText(path.join(dir, file))),
|
||||
}));
|
||||
}
|
||||
|
||||
/* ---------------------------------------------------------------- status */
|
||||
|
||||
function specStatus(spec) {
|
||||
const overviewPath = path.join(spec.dir, "overview.md");
|
||||
const overview = readText(overviewPath);
|
||||
const files = phaseFiles(spec.dir);
|
||||
// An empty overview.md still exists; only a missing one is "no overview".
|
||||
const hasOverview = overview !== null;
|
||||
const checklist = hasOverview ? parseChecklist(overview) : { found: false, phases: [], unparsed: [] };
|
||||
const groups = hasOverview ? parseGroups(overview) : { found: false, groups: [] };
|
||||
const checks = [];
|
||||
const check = (level, code, message) => checks.push({ level, code, message });
|
||||
for (const [n, names] of files.extra) {
|
||||
check("warn", "duplicate-phase-file", `Phase ${n} has more than one file: using ${files.get(n)}, ignoring ${names.join(", ")}`);
|
||||
}
|
||||
const rowsByNumber = new Map();
|
||||
for (const r of checklist.phases) rowsByNumber.set(r.number, [...(rowsByNumber.get(r.number) || []), r]);
|
||||
for (const [n, rows] of rowsByNumber) {
|
||||
if (rows.length > 1) check("error", "duplicate-checklist-row", `Phase ${n} has ${rows.length} rows in the Phase Checklist (overview.md lines ${rows.map((r) => r.line).join(", ")}); the first one is used`);
|
||||
}
|
||||
|
||||
const phases = [];
|
||||
const numbers = new Set([...checklist.phases.map((p) => p.number), ...files.keys()]);
|
||||
for (const number of [...numbers].sort((a, b) => a - b)) {
|
||||
const row = checklist.phases.find((p) => p.number === number) || null;
|
||||
const file = files.get(number) || null;
|
||||
const parsed = file ? parsePhaseFile(path.join(spec.dir, file), number) : null;
|
||||
phases.push({
|
||||
number,
|
||||
name: row ? row.name : parsed ? parsed.title.replace(/^Phase\s+\d+\s*[:\-–—]?\s*/i, "") : `Phase ${number}`,
|
||||
checklist: row ? row.state : null,
|
||||
marker: row ? row.marker : null,
|
||||
file,
|
||||
status: parsed ? parsed.status : null,
|
||||
goal: parsed ? parsed.goal : null,
|
||||
tasks: parsed ? { total: parsed.total, open: parsed.open, ...parsed.counts } : null,
|
||||
blockedTasks: parsed ? parsed.tasks.filter((t) => t.state === "blocked").map((t) => t.id) : [],
|
||||
assumedTasks: parsed ? parsed.tasks.filter((t) => t.state === "assumed").map((t) => t.id) : [],
|
||||
openTasks: parsed ? parsed.tasks.filter((t) => ["pending", "in-progress", "blocked", "unknown"].includes(t.state)).map((t) => t.id) : [],
|
||||
});
|
||||
if (!row && hasOverview) check("error", "missing-checklist-row", `phase-${number}.md has no row in overview.md's Phase Checklist`);
|
||||
if (row && !file) check("error", "missing-phase-file", `Phase Checklist lists Phase ${number} but there is no phase-${number}.md`);
|
||||
if (parsed) {
|
||||
for (const n of parsed.numbering) check("error", "task-numbering", `phase-${number}.md: ${n}`);
|
||||
// Prerequisites and criteria are plain bullets by rule; other checkbox
|
||||
// blocks (a Phase Testing list) are the template's own and are not tasks.
|
||||
for (const s of parsed.strayCheckboxes.filter((c) => /prerequisite|criteria/i.test(c.section))) {
|
||||
check("warn", "criteria-checkbox", `phase-${number}.md:${s.line} is a checkbox under "${s.section}"; prerequisites and criteria use plain bullets`);
|
||||
}
|
||||
if (parsed.total === 0) check("warn", "no-tasks", `phase-${number}.md has no **Task ${number}.N:** checkbox lines`);
|
||||
for (const u of parsed.unmatchedTasks) {
|
||||
check("warn", "uncounted-task", `phase-${number}.md:${u.line} looks like a task but is not counted (a task line is "- [ ] **Task ${number}.N:**"): ${u.text}`);
|
||||
}
|
||||
const done = parsed.counts.complete + parsed.counts.assumed;
|
||||
const rowDone = row && (row.state === "complete" || row.state === "assumed");
|
||||
// A phase may be approved with blocked [!] tasks left (Implementation
|
||||
// Mode's self-review allows "[x] or blocked [!]"); only unfinished work is an error.
|
||||
if (rowDone && parsed.unfinished > 0) {
|
||||
check("error", "checked-with-open-tasks", `Phase ${number} is [${row.marker}] in overview.md but ${parsed.unfinished} task(s) are not done (${phases.at(-1).openTasks.filter((id) => !phases.at(-1).blockedTasks.includes(id)).join(", ")})`);
|
||||
} else if (rowDone && parsed.counts.blocked > 0) {
|
||||
check("info", "approved-with-blocked", `Phase ${number} is [${row.marker}] with ${parsed.counts.blocked} blocked task(s) (${phases.at(-1).blockedTasks.join(", ")})`);
|
||||
}
|
||||
if (row && row.state === "pending" && parsed.total > 0 && done > 0) {
|
||||
// Done tasks under a [ ] phase with work still open is what a re-opened
|
||||
// phase looks like (revise-plan); with nothing open it is a missed mark.
|
||||
if (parsed.unfinished > 0) check("info", "partly-done-unchecked", `Phase ${number} is [ ] with ${done} task(s) done and ${parsed.unfinished} open (normal for a re-opened phase)`);
|
||||
else check("warn", "unchecked-with-done-tasks", `Phase ${number} is [ ] in overview.md but all ${done} unblocked task(s) are done`);
|
||||
}
|
||||
if (row && !rowDone && row.state !== "pending" && parsed.total > 0 && parsed.unfinished === 0) {
|
||||
check("info", "done-not-approved", `Phase ${number}: every task is done but overview.md still shows [${row.marker}] (normal until the user approves the phase)`);
|
||||
}
|
||||
}
|
||||
}
|
||||
if (!hasOverview) check("error", "no-overview", `${spec.rel} has no overview.md`);
|
||||
else if (!checklist.found) check("error", "no-checklist", "overview.md has no ## Phase Checklist section");
|
||||
for (const u of checklist.unparsed) check("warn", "unparsed-checklist-row", `overview.md:${u.line} is a checkbox in the Phase Checklist with no "Phase N" in it: ${u.text}`);
|
||||
for (const g of groups.groups) {
|
||||
for (const n of g.phases) if (!numbers.has(n)) check("error", "group-unknown-phase", `Parallel group ${g.id} names Phase ${n}, which does not exist`);
|
||||
}
|
||||
|
||||
// Totals. Completed = [x] plus [?] (assumed complete); [?] is reported on its own too.
|
||||
// Incomplete = [ ] + [/] (+ unreadable markers); Blocked is its own column.
|
||||
const totals = { total: 0, complete: 0, assumed: 0, pending: 0, "in-progress": 0, blocked: 0, unknown: 0 };
|
||||
for (const p of phases) if (p.tasks) for (const k of Object.keys(totals)) totals[k] += p.tasks[k] || 0;
|
||||
const completed = totals.complete + totals.assumed;
|
||||
const completion = totals.total ? completed / totals.total : null;
|
||||
|
||||
return {
|
||||
ok: true,
|
||||
spec: spec.rel,
|
||||
name: spec.name,
|
||||
overview: hasOverview ? "overview.md" : null,
|
||||
planDrafts: planDrafts(spec.dir),
|
||||
phases,
|
||||
parallelGroups: groups.groups,
|
||||
totals: { ...totals, completed, incomplete: totals.pending + totals["in-progress"] + totals.unknown },
|
||||
completion: completion === null ? null : Number(completion.toFixed(4)),
|
||||
completionPercent: completion === null ? null : Math.round(completion * 100),
|
||||
next: nextPhase(phases, groups.groups, checklist.found),
|
||||
pending: phases
|
||||
.filter((p) => p.checklist && p.checklist !== "complete" && p.checklist !== "assumed")
|
||||
.map((p) => ({ number: p.number, name: p.name, state: p.checklist, tasks: p.tasks ? p.tasks.total : null, open: p.tasks ? p.tasks.open : null, goal: p.goal })),
|
||||
checks,
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Implementation Mode's phase-selection table, applied mechanically.
|
||||
* 2+ workable phases in the same parallel group, consecutive -> choose (warn if all [/])
|
||||
* a single [/] -> ask-resume · a single [ ] -> auto-start · nothing workable -> none
|
||||
*/
|
||||
function nextPhase(phases, groups, haveChecklist) {
|
||||
if (!haveChecklist) return { action: "none", reason: "no Phase Checklist in overview.md" };
|
||||
const ordered = phases.filter((p) => p.checklist);
|
||||
const isDone = (p) => p.checklist === "complete" || p.checklist === "assumed";
|
||||
const workable = ordered.filter((p) => p.checklist === "pending" || p.checklist === "in-progress");
|
||||
if (!workable.length) {
|
||||
return { action: "none", reason: ordered.length && ordered.every(isDone) ? "every phase is complete" : "no [ ] or [/] phase in the Phase Checklist" };
|
||||
}
|
||||
const first = workable[0];
|
||||
const brief = (p) => ({ number: p.number, name: p.name, state: p.checklist, tasks: p.tasks ? p.tasks.total : null });
|
||||
// A blocked [!] phase ahead of the pick is skipped, but never silently.
|
||||
const skipped = ordered.slice(0, ordered.indexOf(first)).filter((p) => !isDone(p)).map(brief);
|
||||
const note = skipped.length ? { skipped, warning: `skipping ${skipped.map((p) => `Phase ${p.number} [${p.state}]`).join(", ")} ahead of it` } : {};
|
||||
const group = groups.find((g) => g.phases.includes(first.number));
|
||||
if (group) {
|
||||
// Consecutive same-group incomplete phases, in checklist order, starting at the first workable one.
|
||||
const run = [];
|
||||
for (const p of ordered.slice(ordered.indexOf(first))) {
|
||||
if (!group.phases.includes(p.number)) break;
|
||||
if (isDone(p)) continue;
|
||||
if (p.checklist === "pending" || p.checklist === "in-progress") run.push(p);
|
||||
else break;
|
||||
}
|
||||
if (run.length >= 2) {
|
||||
const allStarted = run.every((p) => p.checklist === "in-progress");
|
||||
const warnings = [
|
||||
...(allStarted ? ["every option is already [/]: another agent may be working on it, so picking one risks duplicated work"] : []),
|
||||
...(note.warning ? [note.warning] : []),
|
||||
];
|
||||
return {
|
||||
action: "choose",
|
||||
group: group.id,
|
||||
options: run.map(brief),
|
||||
...(note.skipped ? { skipped: note.skipped } : {}),
|
||||
...(warnings.length ? { warning: warnings.join("; ") } : {}),
|
||||
};
|
||||
}
|
||||
}
|
||||
return { action: first.checklist === "in-progress" ? "ask-resume" : "auto-start", phase: brief(first), ...note };
|
||||
}
|
||||
|
||||
/* --------------------------------------------------------------- commands */
|
||||
|
||||
async function cmdList(args) {
|
||||
const root = path.resolve(args.root || ".");
|
||||
const { scanProject } = await consoleLib();
|
||||
const scan = scanProject(root);
|
||||
const specs = scan.specs.map((s) => {
|
||||
const dir = path.join(root, s.dir);
|
||||
let names = [];
|
||||
try {
|
||||
names = fs.readdirSync(dir);
|
||||
} catch {}
|
||||
return {
|
||||
dir: s.dir,
|
||||
name: s.name,
|
||||
state: s.state,
|
||||
detail: s.detail,
|
||||
touched: s.touched ? new Date(s.touched).toISOString() : null,
|
||||
planDrafts: planDrafts(dir),
|
||||
overview: names.includes("overview.md"),
|
||||
phaseFiles: names.filter((n) => /^phase-\d+\b.*\.md$/i.test(n)).length,
|
||||
pathfinder: isDir(path.join(dir, "pathfinder")),
|
||||
};
|
||||
});
|
||||
let completed = [];
|
||||
try {
|
||||
completed = fs.readdirSync(path.join(root, "specs--completed")).filter((n) => isDir(path.join(root, "specs--completed", n))).sort();
|
||||
} catch {}
|
||||
out({
|
||||
ok: true,
|
||||
root,
|
||||
hasAgents: scan.hasAgents,
|
||||
specsDir: isDir(path.join(root, "specs")),
|
||||
specs,
|
||||
completed,
|
||||
...(specs.length ? {} : { note: "No active specs under specs/." }),
|
||||
});
|
||||
}
|
||||
|
||||
async function cmdStatus(args) {
|
||||
const root = path.resolve(args.root || ".");
|
||||
out(specStatus(resolveSpec(root, args._[1], { allowArchived: true })));
|
||||
}
|
||||
|
||||
function countVerificationAdded(dir) {
|
||||
let n = 0;
|
||||
for (const name of fs.readdirSync(dir)) {
|
||||
if (!/\.md$/i.test(name) || /^PLAN-/i.test(name)) continue;
|
||||
n += ((readText(path.join(dir, name)) || "").match(/<!--\s*VERIFICATION:\s*Added\b/gi) || []).length;
|
||||
}
|
||||
return n;
|
||||
}
|
||||
|
||||
async function cmdMetrics(args) {
|
||||
const root = path.resolve(args.root || ".");
|
||||
const spec = resolveSpec(root, args._[1], { allowArchived: true });
|
||||
const step = args.step;
|
||||
if (step !== "document" && step !== "finalize") fail(EXIT.USAGE, "bad-step", "--step must be document or finalize.", "Plan's METRICS_JSON is written by hand in its Phase 7.");
|
||||
const sets = {};
|
||||
for (const kv of args.set || []) {
|
||||
const m = kv.match(/^([a-z_]+)=(-?\d+(?:\.\d+)?)$/);
|
||||
if (!m) fail(EXIT.USAGE, "bad-set", `--set ${kv} is not key=number.`, "Example: --set verification_failures_found=1");
|
||||
sets[m[1]] = Number(m[2]);
|
||||
}
|
||||
// --set supplies the judgment fields only; the computed ones are never overridden.
|
||||
const SETTABLE = { document: ["verification_items_added"], finalize: ["verification_failures_found", "documentation_updates_needed"] };
|
||||
for (const k of Object.keys(sets)) {
|
||||
if (!SETTABLE[step].includes(k)) fail(EXIT.USAGE, "bad-set", `--set ${k} is not a field you supply for --step ${step}.`, `Only ${SETTABLE[step].join(", ")}; the rest is computed from the files.`);
|
||||
}
|
||||
const st = specStatus(spec);
|
||||
const withTasks = st.phases.filter((p) => p.tasks);
|
||||
let metrics;
|
||||
let hint;
|
||||
if (step === "document") {
|
||||
// verification_items_added is the Added total of the Verification Summary
|
||||
// you presented, not something the files record, so it comes from --set.
|
||||
// The <!-- VERIFICATION: Added --> comments are a cross-check only.
|
||||
if (!("verification_items_added" in sets)) fail(EXIT.USAGE, "missing-set", "document needs --set verification_items_added=N (the Added column total of your Verification Summary).", `The spec has ${countVerificationAdded(spec.dir)} <!-- VERIFICATION: Added --> comment(s), as a cross-check.`);
|
||||
metrics = {
|
||||
step: "document",
|
||||
total_tasks: st.totals.total,
|
||||
tasks_per_phase: withTasks.map((p) => p.tasks.total),
|
||||
phase_count: st.phases.length,
|
||||
parallel_groups_identified: st.parallelGroups.length,
|
||||
...sets,
|
||||
};
|
||||
hint = { verificationCommentsFound: countVerificationAdded(spec.dir) };
|
||||
} else {
|
||||
const missing = ["verification_failures_found", "documentation_updates_needed"].filter((k) => !(k in sets));
|
||||
if (missing.length) fail(EXIT.USAGE, "missing-set", `finalize needs ${missing.map((k) => `--set ${k}=N`).join(" and ")}.`, "Those two counts are your judgment from Steps 2 and 4.");
|
||||
metrics = {
|
||||
step: "finalize",
|
||||
completion_rate_at_audit: st.completion === null ? 0 : Number(st.completion.toFixed(2)),
|
||||
tasks_completed: st.totals.completed,
|
||||
tasks_total: st.totals.total,
|
||||
...sets,
|
||||
};
|
||||
}
|
||||
out({ ok: true, spec: spec.rel, metrics, comment: `<!-- METRICS_JSON ${spacedJson(metrics)} -->`, ...(hint || {}), checks: st.checks.filter((c) => c.level === "error") });
|
||||
}
|
||||
|
||||
// The house style of every METRICS_JSON comment: {"key": value, "list": [1, 2]}.
|
||||
function spacedJson(obj) {
|
||||
const v = (x) => (Array.isArray(x) ? `[${x.map(v).join(", ")}]` : x && typeof x === "object" ? spacedJson(x) : JSON.stringify(x));
|
||||
return `{${Object.entries(obj).map(([k, x]) => `${JSON.stringify(k)}: ${v(x)}`).join(", ")}}`;
|
||||
}
|
||||
|
||||
const TO = { open: " ", "in-progress": "/", done: "x" };
|
||||
|
||||
async function cmdMark(args) {
|
||||
const root = path.resolve(args.root || ".");
|
||||
const spec = resolveSpec(root, args._[1]);
|
||||
const number = Number(args.phase);
|
||||
if (!Number.isInteger(number) || number < 0) fail(EXIT.USAGE, "bad-phase", "--phase needs a phase number.", "Example: --phase 2");
|
||||
if (!(args.to in TO)) fail(EXIT.USAGE, "bad-to", "--to must be open, in-progress or done.", "open = [ ], in-progress = [/], done = [x]");
|
||||
const overviewPath = path.join(spec.dir, "overview.md");
|
||||
const overview = readText(overviewPath);
|
||||
if (overview === null) fail(EXIT.NOT_FOUND, "no-overview", `${spec.rel} has no overview.md.`, "Run /plan2code-2-document first.");
|
||||
const checklist = parseChecklist(overview);
|
||||
const rows = checklist.phases.filter((p) => p.number === number);
|
||||
const row = rows[0];
|
||||
if (!row) fail(EXIT.NOT_FOUND, "no-row", `overview.md's Phase Checklist has no row for Phase ${number}.`, "Run `specs.mjs status` to see the phases it lists.");
|
||||
if (rows.length > 1) fail(EXIT.REFUSED, "duplicate-row", `Phase ${number} has ${rows.length} rows in the Phase Checklist (lines ${rows.map((r) => r.line).join(", ")}); marking one would be a guess.`, "Remove the duplicate row, then rerun.");
|
||||
const target = TO[args.to];
|
||||
if (row.marker === "/" && target === " ") {
|
||||
fail(EXIT.REFUSED, "no-reset", `Phase ${number} is [/]; started work is never reset to [ ].`, "Leave it [/] (a later session resumes it), or mark it done once approved.");
|
||||
}
|
||||
const changes = [];
|
||||
const lines = overview.split(/\r?\n/);
|
||||
const idx = row.line - 1;
|
||||
const next = lines[idx].replace(/\[(.)\]/, `[${target}]`);
|
||||
if (next !== lines[idx]) {
|
||||
lines[idx] = next;
|
||||
changes.push({ file: `${spec.rel}/overview.md`, line: row.line, from: `[${row.marker}]`, to: `[${target}]` });
|
||||
}
|
||||
// The phase file's Status line follows: done -> Complete; re-opening a Complete
|
||||
// phase -> In Progress (revise-plan), so the two files never disagree.
|
||||
let phaseText = null;
|
||||
let phasePath = null;
|
||||
let unfinished = [];
|
||||
const warnings = [];
|
||||
const file = phaseFiles(spec.dir).get(number);
|
||||
if (file) {
|
||||
phasePath = path.join(spec.dir, file);
|
||||
const text = readText(phasePath) || "";
|
||||
const parsed = parsePhaseFile(phasePath, number);
|
||||
unfinished = parsed.tasks.filter((t) => ["pending", "in-progress", "unknown"].includes(t.state)).map((t) => t.id);
|
||||
const status = statusOf(text);
|
||||
const want = target === "x" ? "Complete" : target === " " && status && /^complete$/i.test(status) ? "In Progress" : null;
|
||||
if (status && want && status !== want) {
|
||||
phaseText = text.replace(STATUS_RE, (_, before, _value, after) => before + want + after);
|
||||
changes.push({ file: `${spec.rel}/${file}`, field: "Status", from: status, to: want });
|
||||
}
|
||||
// done and open keep the Status line in step; with none to find, say so.
|
||||
if (!status && target !== "/") warnings.push(`${file} has no Status line, so only the Phase Checklist checkbox changed; add a "**Status:** <value>" line under its title.`);
|
||||
}
|
||||
if (!args["dry-run"]) {
|
||||
if (changes.some((c) => c.file.endsWith("overview.md"))) fs.writeFileSync(overviewPath, lines.join(eol(overview)));
|
||||
if (phaseText !== null) fs.writeFileSync(phasePath, phaseText);
|
||||
}
|
||||
const doneEarly = target === "x" && unfinished.length > 0;
|
||||
if (doneEarly) warnings.unshift(`Phase ${number} was marked done with ${unfinished.length} unfinished task(s): ${unfinished.join(", ")}. Mark only a phase the user approved.`);
|
||||
out({
|
||||
ok: true,
|
||||
spec: spec.rel,
|
||||
phase: number,
|
||||
name: row.name,
|
||||
dryRun: !!args["dry-run"],
|
||||
changed: changes.length > 0,
|
||||
changes,
|
||||
...(warnings.length ? { warning: warnings.join(" ") } : {}),
|
||||
...(doneEarly ? { unfinished } : {}),
|
||||
});
|
||||
}
|
||||
|
||||
function listRel(dir, base = dir) {
|
||||
const outList = [];
|
||||
for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
|
||||
const p = path.join(dir, e.name);
|
||||
if (e.isDirectory()) outList.push(...listRel(p, base));
|
||||
else outList.push(rel(base, p));
|
||||
}
|
||||
return outList.sort();
|
||||
}
|
||||
|
||||
async function cmdArchive(args) {
|
||||
const root = path.resolve(args.root || ".");
|
||||
const spec = resolveSpec(root, args._[1]);
|
||||
const target = path.join(root, "specs--completed", spec.name);
|
||||
if (fs.existsSync(target)) {
|
||||
fail(EXIT.REFUSED, "target-exists", `specs--completed/${spec.name}/ already exists; nothing was moved.`, "Ask the user whether to merge by hand or archive under another name.");
|
||||
}
|
||||
const files = listRel(spec.dir);
|
||||
if (!args["dry-run"]) {
|
||||
fs.mkdirSync(path.dirname(target), { recursive: true });
|
||||
try {
|
||||
fs.renameSync(spec.dir, target);
|
||||
} catch (err) {
|
||||
// A rename across volumes (or a locked file on Windows) fails; copy then remove.
|
||||
try {
|
||||
fs.cpSync(spec.dir, target, { recursive: true, errorOnExist: true, force: false });
|
||||
} catch (copyErr) {
|
||||
fail(EXIT.INVALID, "archive-failed", `Could not move or copy ${spec.rel} (${err.code || err.message}; copy: ${copyErr.code || copyErr.message}).`, `Close anything holding files in ${spec.rel} open, check specs--completed/${spec.name} for a partial copy, then rerun.`);
|
||||
}
|
||||
try {
|
||||
fs.rmSync(spec.dir, { recursive: true, force: true });
|
||||
} catch (rmErr) {
|
||||
fail(EXIT.INVALID, "source-not-removed", `Copied to specs--completed/${spec.name}/ but could not remove ${spec.rel} (${rmErr.code || rmErr.message}); both copies now exist.`, `Close whatever holds files in ${spec.rel} open, then delete it by hand. The archive is complete.`);
|
||||
}
|
||||
}
|
||||
}
|
||||
const sourceGone = args["dry-run"] ? null : !fs.existsSync(spec.dir);
|
||||
const moved = args["dry-run"] ? null : listRel(target);
|
||||
if (!args["dry-run"] && !(sourceGone && moved.length === files.length)) {
|
||||
fail(
|
||||
EXIT.INVALID,
|
||||
"archive-unverified",
|
||||
`The move of ${spec.rel} to specs--completed/${spec.name}/ did not verify: ${moved.length} of ${files.length} file(s) at the target, and ${spec.rel} ${sourceGone ? "is gone" : "still exists"}.`,
|
||||
`Compare ${spec.rel} with specs--completed/${spec.name}/ and finish the move by hand; archive refuses to rerun while the target exists.`
|
||||
);
|
||||
}
|
||||
out({
|
||||
ok: true,
|
||||
dryRun: !!args["dry-run"],
|
||||
from: spec.rel,
|
||||
to: `specs--completed/${spec.name}`,
|
||||
files,
|
||||
...(args["dry-run"] ? {} : { sourceRemoved: sourceGone, filesAtTarget: moved.length, archivedOn: isoDate() }),
|
||||
});
|
||||
}
|
||||
|
||||
run(USAGE, async (argv) => {
|
||||
const args = parseArgs(argv, { booleans: ["dry-run"], values: ["root", "step", "phase", "to"], lists: ["set"] });
|
||||
const cmd = args._[0];
|
||||
const commands = { list: cmdList, status: cmdStatus, metrics: cmdMetrics, mark: cmdMark, archive: cmdArchive };
|
||||
if (!commands[cmd]) fail(EXIT.USAGE, "unknown-command", cmd ? `Unknown command "${cmd}".` : "No command given.", "Commands: list, status, metrics, mark, archive. Run with --help.");
|
||||
await commands[cmd](args);
|
||||
});
|
||||
@@ -0,0 +1,22 @@
|
||||
{
|
||||
"name": "Plan2Code",
|
||||
"version": "2.4.1",
|
||||
"description": "A structured 4-step workflow methodology for AI-assisted software development",
|
||||
"keywords": [
|
||||
"ai",
|
||||
"workflow",
|
||||
"development",
|
||||
"planning",
|
||||
"implementation",
|
||||
"plan"
|
||||
],
|
||||
"author": "Justin Parker",
|
||||
"license": "MIT",
|
||||
"repository": {
|
||||
"type": "git",
|
||||
"url": "https://github.com/jparkerweb/plan2code"
|
||||
},
|
||||
"homepage": "https://github.com/jparkerweb/plan2code",
|
||||
"releaseDate": "2026-10-04",
|
||||
"mode": "utility"
|
||||
}
|
||||
@@ -16,6 +16,14 @@ Senior software engineer implementing solutions exactly as specified. Follow spe
|
||||
|
||||
The FIRST thing you do, before anything else in this file — before reading a spec, before Phase 1: ask **web console** (browser page, suggested) or **terminal**? Console → run `node "<D>/console.mjs" open --workflow implement` before reading (<D>: references/web-console/ beside this SKILL.md — ~/.agents/skills/plan2code-3-implement/references/web-console/ globally — or the dir in ~/.plan2code/console/console-dir), then <D>/console.md and <D>/building.md; progress, every question and the sign-off go through it. Switchable anytime. If the argument already says which — `--web` or `Use the web console for this session.` — take it and do not ask; drop the flag. Launched by the dashboard? Its session is already open — resume it (console.md → Launches), then the spec.
|
||||
|
||||
## Scripts
|
||||
|
||||
`<S>` is `scripts/` beside this SKILL.md (`~/.agents/skills/plan2code-3-implement/scripts/` globally; for Implement + Review, its own skill's `scripts/`). Run them from the project root. Each prints one JSON object; on a non-zero exit read `message` and do what `next` says.
|
||||
|
||||
- `node "<S>/specs.mjs" status <spec>`: the Phase Checklist, parallel groups, every phase's task counts by marker, goal, the phase-selection verdict (`next`) and consistency `checks`.
|
||||
- `node "<S>/specs.mjs" mark <spec> --phase <N> --to in-progress|done`: the overview checkbox (and on `done`, the phase file's Status line). It refuses to reset `[/]` to `[ ]`.
|
||||
- `node "<S>/commit-msg.mjs" --subject "<subject>" --add-all`: the commit command, ticket taken from the branch.
|
||||
|
||||
## Rules
|
||||
|
||||
- Follow `./AGENTS.md` if it exists
|
||||
@@ -31,28 +39,15 @@ The FIRST thing you do, before anything else in this file — before reading a s
|
||||
|
||||
## Required Context
|
||||
|
||||
⚠️ IMPORTANT: `specs/` is gitignored — NEVER use Glob (silently fails). Shell only: `ls specs/` (Bash) or `Get-ChildItem specs/` (PS).
|
||||
Need implementation spec files to proceed. `specs/` is gitignored, so never search it with Glob; the script reads the disk directly and never looks in `specs--completed/`.
|
||||
|
||||
Need implementation spec files to proceed.
|
||||
**Option 1: User provides an overview.md path** → `specs.mjs status <that path>`.
|
||||
|
||||
**IMPORTANT:** Never look in `specs--completed/` (archived only). Only check active spec folders under `specs/`.
|
||||
**Option 2: Auto-detect** → `specs.mjs list`. Exactly one spec with phases (`phaseFiles` > 0) → `status` it.
|
||||
|
||||
**Option 1: User provides overview.md path**
|
||||
1. Read the overview.md file
|
||||
2. Find "Phase Checklist" section
|
||||
3. Identify workable phases: `[ ]` (pending) or `[/]` (in-progress)
|
||||
4. Check for parallel execution options
|
||||
5. Apply phase selection logic
|
||||
6. Read corresponding `phase-X.md` from same directory
|
||||
7. Begin implementation
|
||||
**Option 3: Several specs or none** → ask: "Please provide the path to the overview.md file (e.g., `specs/user-authentication/overview.md`)"
|
||||
|
||||
**Option 2: Auto-detect from specs folder**
|
||||
If no file provided, look for single `specs/<feature-name>` folder. If found, read its `overview.md` and follow Option 1.
|
||||
|
||||
**Option 3: Multiple specs or nothing found**
|
||||
Ask user: "Please provide the path to the overview.md file (e.g., `specs/user-authentication/overview.md`)"
|
||||
|
||||
Do not proceed without successfully reading overview.md and determining the next phase.
|
||||
Then read overview.md and act on `next` (Parallel Phase Selection below). Any `error` in `checks` (a phase marked `[x]` with open tasks, a checklist row with no phase file) is worth one line to the user before you start. Do not proceed without a readable overview.md and a `next` verdict.
|
||||
|
||||
## Phase Status Tracking
|
||||
|
||||
@@ -76,16 +71,16 @@ Never reset `[/]` to `[ ]`. Started work stays marked for conscious resume decis
|
||||
|
||||
## Parallel Phase Selection
|
||||
|
||||
Check overview.md for "Parallel Execution Groups" section. Find workable phases (`[ ]` or `[/]`).
|
||||
`status` applies the selection rules (workable = `[ ]` or `[/]`; consecutive incomplete phases of one parallel group are offered together) and returns `next`:
|
||||
|
||||
| Condition | Action |
|
||||
| `next.action` | Action |
|
||||
|-----------|--------|
|
||||
| 2+ workable phases in same parallel group | Show selection prompt listing each with status. TIP: run another agent on a different phase simultaneously. If all are `[/]`, warn about duplication. |
|
||||
| Single `[/]` phase | Prompt: "Phase X is in progress. Resume? (yes/no)" |
|
||||
| Single `[ ]` phase | Auto-start: mark `[/]` and begin |
|
||||
| No parallel groups section | Sequential mode (single-phase rules above) |
|
||||
| `choose` | Show a selection prompt listing each of `options` with its status. TIP: run another agent on a different phase simultaneously. Relay `warning` (all already `[/]`: duplicated work) when present. |
|
||||
| `ask-resume` | Prompt: "Phase X is in progress. Resume? (yes/no)" Relay `warning` when present. |
|
||||
| `auto-start` | Mark it `[/]` and begin. Relay `warning` when present. |
|
||||
| `none` | Nothing to implement: say why (`reason`). Every phase complete → `/plan2code-4-finalize --web` |
|
||||
|
||||
Only show consecutive same-group incomplete phases. After selection, mark `[/]`, read `phase-X.md`, begin.
|
||||
After selection, `mark --to in-progress`, read `phase-X.md`, begin.
|
||||
|
||||
## Code Consistency Rules
|
||||
|
||||
@@ -109,11 +104,9 @@ Only show consecutive same-group incomplete phases. After selection, mark `[/]`,
|
||||
|
||||
### 1. Identify and Claim Phase
|
||||
|
||||
Review `overview.md`, find workable phases (`[ ]` or `[/]`). Apply parallel selection logic.
|
||||
Act on `status`'s `next` (Parallel Phase Selection above).
|
||||
|
||||
**Once selected:**
|
||||
- If `[ ]`: Update to `[/]` in overview.md
|
||||
- If `[/]`: No change needed
|
||||
**Once selected:** `specs.mjs mark <spec> --phase <N> --to in-progress` (a no-op when it is already `[/]`).
|
||||
|
||||
State: `⚡ [PHASE X: Phase Name] - Marking in-progress and starting`
|
||||
|
||||
@@ -174,7 +167,7 @@ See "After Approval / Session End" section below.
|
||||
| Minor spec gap | Proceed with interpretation, note decision | `> SPEC NOTE: [what was assumed]` |
|
||||
| Major spec conflict | STOP and ask user — do NOT guess on architecture | `SPEC CONFLICT: [details]. Please clarify.` |
|
||||
|
||||
Default: ONE phase per conversation. Small phase (<5 tasks): ask if should continue with next. Large (>40): warn at start.
|
||||
Default: ONE phase per conversation. Small phase (<5 tasks in `status`): ask if should continue with next. Large (>40): warn at start.
|
||||
|
||||
## Templates
|
||||
|
||||
@@ -211,18 +204,17 @@ Sections: Summary (2-3 sentences), Tasks Completed (Y/Z + blocked list), Test Re
|
||||
### After Approval / Session End
|
||||
|
||||
On user "approved":
|
||||
1. Mark `[/]` → `[x]` in overview.md, update phase-X.md status to "Complete"
|
||||
1. `specs.mjs mark <spec> --phase <N> --to done`: overview `[/]` → `[x]` and phase-X.md Status "Complete"
|
||||
2. Show Planny art with completion message
|
||||
3. Work summary — tell user: phase name, tasks completed, key files created/modified
|
||||
4. **Upcoming phases** — read overview.md Phase Checklist, find next 2-3 pending (`[ ]`) phases. For each, peek at its `phase-X.md` for task count and goal. Present a table so the user can assess stopping points and review gates:
|
||||
4. **Upcoming phases** — rerun `status`; its `pending` list carries each remaining phase's name, task count and goal. Present the next 2-3 as a table so the user can assess stopping points and review gates (tighten a goal to one sentence if it runs long):
|
||||
|
||||
| Phase | Tasks | Goal |
|
||||
|-------|-------|------|
|
||||
| Phase X: [Name] | Y | [One-sentence goal] |
|
||||
| Phase X+1: [Name] | Z | [One-sentence goal] |
|
||||
|
||||
5. Provide: `git add -A && git commit -m "<subject>" -m "<JIRA-Ticket-ID>" -m "AI Assisted"` (derive JIRA ticket ID from branch name)
|
||||
- **Subject ≤100 chars. EXACTLY THREE -m flags — no body. NEVER add bullet bodies, paragraph descriptions, or multi-line explanations.** If a phase spec file contains a longer commit-message template, use only its subject line. The diff is the body; the PR is the explanation.
|
||||
5. Write a one-line subject for the phase, then give the user the `command` from `commit-msg.mjs --subject "<subject>" --add-all`. It enforces the format: subject ≤100 chars and EXACTLY THREE -m flags (subject, ticket, `AI Assisted`), no body. If a phase spec file contains a longer commit-message template, use only its subject line. The diff is the body; the PR is the explanation. On Windows PowerShell 5.1 (no `&&`), give `add` and `commit` as two commands instead. Exit 4 `no-ticket`: ask the user for the ticket and rerun with `--ticket`, or show the command with `<JIRA-Ticket-ID>` for them to fill in.
|
||||
6. **If more phases:** "NEXT STEP: Start NEW conversation and run: `/plan2code-3-implement --web`"
|
||||
7. **If final phase:** "NEXT STEP: Start NEW conversation and run: `/plan2code-4-finalize --web`"
|
||||
8. Mention `/plan2code-1b-revise-plan --web` option
|
||||
|
||||
@@ -10,6 +10,14 @@ Critical review specialist -- experienced senior engineer providing independent
|
||||
|
||||
The FIRST thing you do, before anything else in this file — before the scope detection: ask **web console** (browser page, suggested) or **terminal**? Console → run `node "<D>/console.mjs" open --workflow review` before reading (<D>: references/web-console/ beside this SKILL.md — ~/.agents/skills/plan2code-review/references/web-console/ globally — or the dir in ~/.plan2code/console/console-dir), then read <D>/console.md. Scope questions, the findings report and the pick-what-gets-fixed menu all go through it; the report lands on the page as a doc. Switchable anytime. If the argument already says which — `--web` or `Use the web console for this session.` — take it and do not ask; drop the flag. Launched by the dashboard? Its session is already open — resume it (console.md → Launches), then Process. Read inside a build session for its review button? Skip this section — building.md's overrides govern, the session is already running. On the console, a `__stop` action is the person ending the session (console.md → Stop requests); at every session end post `finish` BEFORE `stop`; unless it is a pause, the finish carries `"dashboard": true` (the Back to the dashboard button) and you keep waiting for the press (console.md → Finishing).
|
||||
|
||||
## Scripts
|
||||
|
||||
`<S>` is `scripts/` beside the SKILL.md that loaded this file (`~/.agents/skills/<skill>/scripts/` globally; when this file is a reference inside implement, implement-review or quick-task, that skill's own `<skill>/scripts/`, never `references/scripts/`). Run from the project root. Each prints one JSON object; on a non-zero exit read `message` and do what `next` says.
|
||||
|
||||
- `node "<S>/review-scope.mjs" [--base <branch>]`: the branch-review scope from git (Step 1).
|
||||
- `node "<S>/specs.mjs" list` / `status <spec>`: spec state on disk (Step 2, Session End routing).
|
||||
- `node "<S>/commit-msg.mjs" --subject "<subject>" --files <path> [--files <path> ...]`: the commit command (one `--files` per path).
|
||||
|
||||
## Rules
|
||||
|
||||
- Follow `./AGENTS.md` if it exists -- use all rules and conventions. If missing, warn and proceed with caution.
|
||||
@@ -40,7 +48,7 @@ Three levels -- auto-detected, always respect explicit user override:
|
||||
|
||||
**User override:** If user specifies scope, use exactly that. Never silently narrow.
|
||||
|
||||
**Doc review:** >70% doc files = editorial critique. >70% code = also verify related docs match.
|
||||
**Doc review:** >70% doc files = editorial critique. >70% code = also verify related docs match. (`review-scope.mjs` reports this as `mix`: `docs`, `code` or `mixed`; for a Focused scope, count the named files the same way.)
|
||||
|
||||
## Process
|
||||
|
||||
@@ -54,7 +62,7 @@ Three levels -- auto-detected, always respect explicit user override:
|
||||
|
||||
1. **User prompt** — use it.
|
||||
2. **Conversation context** — recent work? Those artifacts. Scope: `focused`.
|
||||
3. **Git fallback** — `git status`, `git diff`, `git log main..HEAD --oneline`, `git diff --name-only main..HEAD`. Nothing? Ask user.
|
||||
3. **Git fallback** — run `review-scope.mjs`. It compares the branch with its base (`main`, else `master`; `--base` overrides; `base` says which it used) and adds staged, unstaged and untracked changes: `files` (status, lines), `counts`, `commits`, `mix`, `batchByRisk`. `empty: true`? Ask user. Exit 3 `no-base` (no `main` or `master`, or no such `--base`)? Rerun with `--base <trunk>`, asking the user which branch is the trunk if unclear. Exit 3 `not-a-repo`? Ask user which files to review.
|
||||
|
||||
**Classify review type** from context (auto-detect; use `ask_user_question` only if ambiguous):
|
||||
|
||||
@@ -69,13 +77,13 @@ Three levels -- auto-detected, always respect explicit user override:
|
||||
| >70% .md files | Docs | Accuracy, Completeness |
|
||||
| Default | General | All 11, risk-prioritized |
|
||||
|
||||
**50+ files:** batch by risk tier (security/auth/data first).
|
||||
**50+ files** (`batchByRisk`): batch by risk tier (security/auth/data first).
|
||||
|
||||
> 🔬 [Review Mode] [X] files, ~[Y] lines. Type: [type]. Focus: [prioritized dimensions].
|
||||
|
||||
### Step 2: Context
|
||||
|
||||
1. **Specs?** Read `overview.md` + recent `phase-X.md`.
|
||||
1. **Specs?** `specs.mjs list` (it reads gitignored `specs/`, which file search skips), then read `overview.md` + recent `phase-X.md`.
|
||||
2. **AGENTS.md** for conventions.
|
||||
3. **Tech stack** -- check for deprecations, CVEs, breaking changes.
|
||||
4. **Classify:** >70% docs = doc review. >70% code = verify docs match.
|
||||
@@ -167,9 +175,9 @@ Work summary — tell user: scope reviewed, findings count by severity (Critical
|
||||
|
||||
Read references/session-end.md
|
||||
|
||||
> Fallback: route plan2code artifacts (plan/spec docs/phases) on the reviewed feature's own `specs/<feature>/` state to the earliest unmet pipeline stage whose input exists — `PLAN-*` or `overview.md` without `phase-*.md` → `/plan2code-2-document`; unchecked `- [ ]` phase tasks → `/plan2code-3-implement`; all checked → `/plan2code-4-finalize`; archived → complete, summary only. Verify `specs/` on disk with a terminal `ls`/`Get-ChildItem` — it's gitignored, so search tools miss it and an empty result proves nothing. Non-pipeline artifacts (code/PRs/docs/logs) → summary only. Unresolved Criticals → fixing them (H/A/S) is the next step. Ambiguous or multiple candidate specs → ask one targeted question. Output: "Next (NEW conversation): `/plan2code-<step>` — [why + how you know]", appending ` --web` when the routed step offers the web console; else "Review complete -- [summary]."
|
||||
> Fallback: route plan2code artifacts (plan/spec docs/phases) on the reviewed feature's own `specs/<feature>/` state to the earliest unmet pipeline stage whose input exists — `PLAN-*` or `overview.md` without `phase-*.md` → `/plan2code-2-document`; unchecked `- [ ]` phase tasks → `/plan2code-3-implement`; all checked → `/plan2code-4-finalize`; archived → complete, summary only. Read the state with `specs.mjs status <spec>` (gitignored `specs/` defeats search tools). Non-pipeline artifacts (code/PRs/docs/logs) → summary only. Unresolved Criticals → fixing them (H/A/S) is the next step. Ambiguous or multiple candidate specs → ask one targeted question. Output: "Next (NEW conversation): `/plan2code-<step>` — [why + how you know]", appending ` --web` when the routed step offers the web console; else "Review complete -- [summary]."
|
||||
|
||||
- **Commit** (code changes): `git add [files] && git commit -m "fix: [desc]" -m "<JIRA>" -m "AI Assisted"` -- derive JIRA from branch.
|
||||
- **Commit** (code changes): the `command` from `commit-msg.mjs --subject "fix: [desc]" --files <file>` repeated once per fixed file (ticket from the branch; exit 4 `no-ticket`: show it with `<JIRA>` for the user to fill in). On Windows PowerShell 5.1 (no `&&`), give `add` and `commit` as two commands.
|
||||
|
||||
```
|
||||
⋅
|
||||
|
||||
@@ -5,7 +5,7 @@ Principles to reason from, not a lookup table — adapt; when a case doesn't fit
|
||||
cleanly, say what you verified and ask.
|
||||
|
||||
- **Plan2Code Workflow Pipeline:** `/plan2code-1-plan` → `PLAN-*` files · `/plan2code-2-document` → `overview.md` + `phase-*.md` (the "spec docs") in `specs/<feature>/` · `/plan2code-3-implement` → checks off phase tasks, one phase per run · `/plan2code-4-finalize` → archives to `specs--completed/`.
|
||||
- **Find specs (any OS/shell):** `specs/` is gitignored, and search tools (Glob/Grep/project search) skip gitignored paths on many platforms — an empty search result is not evidence either way. Check with a terminal listing: `ls specs/<feature>/` (bash/zsh) · `Get-ChildItem specs/<feature>` (PowerShell) · `dir specs\<feature>` (cmd). Feature dir unknown? List `specs/` first. Command errors? Try another shell's form, then read the expected files directly — file reads see gitignored paths. Conclude "no specs" only after a terminal listing or a failed direct read.
|
||||
- **Find specs (any OS/shell):** `specs/` is gitignored, and search tools (Glob/Grep/project search) skip gitignored paths on many platforms — an empty search result is not evidence either way. Use `node "<S>/specs.mjs" list` (`<S>`: see Review Mode → Scripts) (feature dir unknown, or to see what is archived in `completed`) and `node "<S>/specs.mjs" status <spec>`: they read the disk directly. Its fields map onto the routing below: `planDrafts` with no `overview` · `overview` with no phases · each phase's `tasks.open` · a name in `completed`. If the script cannot run, read the expected files directly — file reads see gitignored paths. Conclude "no specs" only after `list` or a failed direct read.
|
||||
- **Reconcile three signals:** session context (what this conversation was doing — a fresh session may have none), user intent (what they asked reviewed), the disk check above. Disk wins on state; context wins on intent and on disk silence; no context → intent + disk decide.
|
||||
- **plan2code artifact reviewed (a plan, the spec docs, phases) — route on the reviewed feature's own `specs/<feature>/` state (another feature's specs prove nothing here), to the earliest unmet stage, suggesting only a step whose input exists:**
|
||||
- `PLAN-*` without `overview.md` → `/plan2code-2-document`
|
||||
|
||||
@@ -556,8 +556,15 @@ enforces it, so never tell someone to keep asking past it.
|
||||
The person can add folders beside the one the session started in (a shared
|
||||
library, a design folder), from the footer's folder label. Together they are
|
||||
the session's **workspace**: context for every skill run in this console
|
||||
session, each folder addressed by a short `@name`. It outlives dashboard hops;
|
||||
a new console session starts with the original folder alone.
|
||||
session, each folder addressed by a short `@name`. It outlives dashboard hops,
|
||||
and it is remembered: every change is saved to `workspaces.json` beside
|
||||
`looks.json` (never into the project), keyed by the folder the session runs
|
||||
in and then by spec. A session with a spec opens on that spec's list, one with
|
||||
none on the project's; a spec with nothing saved starts as a copy of the
|
||||
project's list. The dashboard's picker swaps the list as the selection moves,
|
||||
and a `specDir` you post mid-run takes the current list with it. There is
|
||||
nothing for you to load: `open` prints the list, and a switch of spec on a
|
||||
resume reaches you as ordinary workspace changes on your next `wait`.
|
||||
|
||||
### What you are told
|
||||
|
||||
@@ -767,7 +774,7 @@ that is what the person is there to download. The finish carries no
|
||||
sees the Trail Footer, and without this their last screen promises a question
|
||||
that is never coming.
|
||||
- Post `run` `pathfinder-chart` (id `map`) when a new map is first written,
|
||||
and `pathfinder-research` (id = the question's file slug) as each research
|
||||
and `pathfinder-research` (id = the question's file slug; on `github`, `q<issue-number>`) as each research
|
||||
subagent reports back, or when you resolve a `research` question yourself
|
||||
(Posting an update → Session meter). Other questions score through their
|
||||
answers, so there is nothing to post for them.
|
||||
@@ -820,7 +827,7 @@ know:
|
||||
| 3, Implementation Summary | Written to `overview.md` as usual; mirror it as a doc (marked `saved`) so the page reader sees it land. |
|
||||
| 4, Documentation Review | The proposed-updates table as a doc, and a `multi` naming the documents to update — every option ticked is "approve", unticked ones are skipped. A `review` works instead when the set is all-or-nothing. |
|
||||
| 5, User Feedback | Optional items, `required: false`: the rating as a `choice` of 1 to 10 or a `text`, the three reasons as `text`. The submit-to-maintainer consent is a `confirm`. |
|
||||
| 6, Spec Cleanup | A `confirm` before moving anything, the archive paths in `consequences`. |
|
||||
| 6, Spec Cleanup | A `confirm` before moving anything, the archive paths in `consequences`, and a line that the spec's remembered workspace folders are forgotten too (`console.mjs forget --spec specs/<feature>` after the move). |
|
||||
|
||||
Pass `--spec specs/<feature>` to `open`, or post `specDir` once you know it.
|
||||
Stopping mid-finalize loses nothing
|
||||
|
||||
@@ -41,6 +41,7 @@ import {
|
||||
die,
|
||||
ensureDir,
|
||||
fileStamp,
|
||||
forgetWorkspace,
|
||||
handOff,
|
||||
handleFile,
|
||||
healthOk,
|
||||
@@ -65,6 +66,7 @@ import {
|
||||
readLedger,
|
||||
readWorkspace,
|
||||
reapHandles,
|
||||
rememberedWorkspace,
|
||||
remoteWarning,
|
||||
removeScratch,
|
||||
removeSessions,
|
||||
@@ -73,6 +75,7 @@ import {
|
||||
SESSION_MAX_AGE_MS,
|
||||
sessionDir,
|
||||
sleepSync,
|
||||
specKey,
|
||||
staleScratch,
|
||||
staleSessions,
|
||||
sweepUploads,
|
||||
@@ -317,7 +320,7 @@ async function cmdOpen() {
|
||||
if (launched) appendLedger(dir, { kind: "launch", id: nextLaunchId(readLedger(dir)), workflow: state.workflow });
|
||||
for (const line of ledgerFromPost(dir, openRun, openIssue, state.workflow)) appendLedger(dir, line);
|
||||
} catch {}
|
||||
const workspace = workspaceOnOpen(dir, worktree);
|
||||
const workspace = workspaceOnOpen(dir, worktree, state.specDir);
|
||||
|
||||
// Month-old sessions and scratch files: listed before the print so the
|
||||
// agent can see what went, removed after it so the page waits for nothing.
|
||||
@@ -403,10 +406,11 @@ async function cmdOpen() {
|
||||
* The workspace as `open` hands it to the agent, and the cursor seeded to
|
||||
* match: the agent now has the whole list, so no change up to here is owed.
|
||||
* Read-only on workspace.json, which only the server writes; on a fresh
|
||||
* session the server has not made it yet, so the original folder stands in.
|
||||
* session the server has not made it yet, so what was remembered for this
|
||||
* folder and spec stands in, the same list the server is about to make.
|
||||
*/
|
||||
function workspaceOnOpen(dir, worktree) {
|
||||
const ws = readWorkspace(dir) || initialWorkspace(worktree);
|
||||
function workspaceOnOpen(dir, worktree, specDir) {
|
||||
const ws = readWorkspace(dir) || initialWorkspace(worktree, rememberedWorkspace(worktree, specDir).entry);
|
||||
const missing = ws.folders.filter((f) => !isFolder(f.path)).map((f) => f.id);
|
||||
try {
|
||||
writeWorkspaceCursor(dir, ws.version || 0);
|
||||
@@ -946,6 +950,18 @@ function realNearest(p) {
|
||||
return path.join(fs.realpathSync(existing), path.relative(existing, p));
|
||||
}
|
||||
|
||||
/* --------------------------------------------------------------- forget */
|
||||
|
||||
// Drop the folder list remembered for one spec (Finalize, once the spec is
|
||||
// archived). The project's own list and every other spec's are untouched.
|
||||
function cmdForget() {
|
||||
if (typeof args.spec !== "string" || !args.spec.trim()) die("forget needs --spec specs/<idea>", 2);
|
||||
let spec = specKey(args.spec);
|
||||
if (/\.md$/i.test(spec)) spec = spec.slice(0, spec.lastIndexOf("/"));
|
||||
const worktree = repoRoots().worktree;
|
||||
print({ ok: true, spec, forgot: forgetWorkspace(worktree, spec) });
|
||||
}
|
||||
|
||||
/* ----------------------------------------------------------------- help */
|
||||
|
||||
function cmdHelp() {
|
||||
@@ -961,7 +977,8 @@ port, and the filesystem as transport; this CLI is the whole agent surface.
|
||||
first post. --file is optional, and --title defaults to the
|
||||
project's folder name. Also prints workspace: { folders: [{ name,
|
||||
path, description?, original? }], missing? }, the folders this
|
||||
console session reads as context, addressed as @name.
|
||||
console session reads as context, addressed as @name. The list is
|
||||
remembered per folder and spec in workspaces.json beside looks.json.
|
||||
post --session <sid> --file <patch.json>
|
||||
Merge a patch into the session. Prints terminalLine while the
|
||||
server is live. Exit 3 = rejected; stderr says why. A patch may
|
||||
@@ -988,6 +1005,10 @@ port, and the filesystem as transport; this CLI is the whole agent surface.
|
||||
Copy a cited note attachment into specs/<idea>/attachments/. Prints
|
||||
{ ok, path, link, image, reused }; exit 2 = bad usage, 3 = refused or
|
||||
missing. Paste link as it is.
|
||||
forget --spec specs/<idea>
|
||||
Drop the workspace folders remembered for that spec, in this
|
||||
folder (Finalize, after archiving it). Prints { ok, spec, forgot };
|
||||
forgot is false when nothing was saved. Exit 2 = bad usage.
|
||||
status [--session <sid>] [--all]
|
||||
One session, or every session belonging to this project.
|
||||
stop --session <sid> | --all
|
||||
@@ -1206,6 +1227,7 @@ const COMMANDS = {
|
||||
wait: cmdWait,
|
||||
chat: cmdChat,
|
||||
keep: cmdKeep,
|
||||
forget: cmdForget,
|
||||
status: cmdStatus,
|
||||
stop: cmdStop,
|
||||
help: cmdHelp,
|
||||
|
||||
Loaded 100 of 243 files, more files were not shown because too many files have changed in this diff.
Show more
Reference in new issue
Block a user