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:
jparkerweb committed 2026-10-04 12:17:05 -07:00
1 parent c0ea70e838
commit 6a66440095
243 files changed
+23698 -1607

No files matched your search

+26 -28
View File
@@ -16,6 +16,16 @@ QA engineer and technical lead performing rigorous final validation. Verify spec
The FIRST thing you do, before anything else in this file — before the Required Context check, before Step 1: ask **web console** (browser page, suggested) or **terminal**? Console → run `node "<D>/console.mjs" open --workflow finalize` before reading (<D>: references/web-console/ beside this SKILL.md, or the dir in ~/.plan2code/console/console-dir; `--spec specs/<feature-name>` if known, else post `specDir` later), then <D>/console.md → Finalize; the audit options, the doc-update approval and every cleanup confirmation go through it. 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 the Required Context check.
## Scripts
`<S>` is `scripts/` beside this SKILL.md (`~/.agents/skills/plan2code-4-finalize/scripts/` globally). Run 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" list` / `status <spec>`: specs on disk; one spec's phases, task counts by marker, completion and `checks`. `status` also reads an archived spec.
- `node "<S>/specs.mjs" archive <spec> [--dry-run]`: the Step 6 move, verified.
- `node "<S>/specs.mjs" metrics <spec> --step finalize --set ...`: Step 7's METRICS_JSON line.
- `node "<S>/feedback-payload.mjs"`: Step 6.5 (see its reference).
- `node "<S>/commit-msg.mjs" --subject "<subject>"`: the commit command, ticket from the branch.
## Rules
- Follow `./AGENTS.md` if it exists
@@ -30,11 +40,7 @@ The FIRST thing you do, before anything else in this file — before the Require
### Required Context
⚠️ IMPORTANT: `specs/` is gitignored — NEVER use Glob (silently fails). Shell only: `ls specs/` (Bash) or `Get-ChildItem specs/` (PS).
Need all implementation spec files. Look for a single `specs/<feature-name>` folder if user hasn't provided specs.
**NEVER look in `specs--completed/`** - that contains archived specs only.
Need all implementation spec files. If the user hasn't named the spec, run `specs.mjs list` (it reads gitignored `specs/` directly, where Glob silently finds nothing, and never offers `specs--completed/`, which holds archives only). Exactly one active spec → use it.
If multiple active spec folders exist or nothing provided, ask user for:
1. The entire `specs/<feature-name>/` directory: `overview.md` and all `phase-X.md` files
@@ -57,17 +63,16 @@ Complete steps in order. Report progress after each.
**Objective:** Verify all tasks across all phases completed.
1. Open each `phase-X.md` file
2. Count only `**Task X.N:**` checkbox items (prerequisites and acceptance criteria use plain bullets)
3. Verify each task status:
1. Run `specs.mjs status <spec>`. It counts only `**Task X.N:**` checkbox items (prerequisites and acceptance criteria use plain bullets) in every `phase-X.md`, by marker:
| Status | Meaning | Action |
|--------|---------|--------|
| `[x]` | Completed | Verify implementation exists |
| `[ ]` | Not started | Flag INCOMPLETE |
| `[!]` | Blocked | Document blocker |
| Marker | Meaning | Counts as | Action |
|--------|---------|-----------|--------|
| `[x]` | Completed | Completed | Verify implementation exists |
| `[?]` | Assumed complete | Completed | List it: it was never verified |
| `[ ]` / `[/]` | Not started / started | Incomplete | Flag INCOMPLETE |
| `[!]` | Blocked | Incomplete | Document blocker |
3. Create audit table:
2. Build the audit table from each phase's `tasks` (Completed = `complete` + `assumed`; Incomplete = `pending` + `in-progress`; each phase's `openTasks`, `blockedTasks` and `assumedTasks` name them; the Total row is `totals`):
```markdown
## Task Completion Audit
@@ -77,7 +82,7 @@ Complete steps in order. Report progress after each.
| **Total** | **X** | **X** | **X** | **X** |
```
4. Calculate: `(Completed / Total) * 100`
3. Completion is `completionPercent` (Completed / Total). Report any `error` in `checks` too (e.g. a phase marked `[x]` in overview.md with open tasks).
#### If incomplete tasks exist:
@@ -245,13 +250,9 @@ Ask: "Submit this feedback + run metrics to the maintainer via GitHub? (optional
**Confirm with user before moving files.**
1. Create: `specs--completed/<feature-name>/`
2. Move all contents of `specs/<feature-name>/`:
- `overview.md` (with completion summary)
- All `phase-X.md` files
- `PLAN-DRAFT.md`, `PLAN-CONVERSATION-*.md`, `pathfinder/` (if present)
3. Remove temporary scratch files not part of the final spec record
4. Verify original directory empty and can be removed
1. Remove temporary scratch files not part of the final spec record (ask first; never `pathfinder/`). Everything left is the record: `overview.md` (with completion summary), every `phase-X.md`, `PLAN-DRAFT-*.md`, `PLAN-CONVERSATION-*.md`, `pathfinder/` (if present).
2. `specs.mjs archive <spec> --dry-run` and show the user its `files`; on their yes, `specs.mjs archive <spec>`. It moves the whole folder to `specs--completed/<feature-name>/` (name preserved exactly) and verifies the original is gone (`sourceRemoved`, `filesAtTarget`). Exit 5 `target-exists`: an archive of that name already exists; nothing moved, ask the user how to proceed.
3. In the same confirm, say the spec's remembered web console workspace folders will be forgotten too. After a successful move, on that yes: `node "<D>/console.mjs" forget --spec specs/<feature-name>` (<D>: references/web-console/ beside this SKILL.md). `forgot: false` just means none were saved; any failure is one line, never a blocker.
---
@@ -282,7 +283,7 @@ Read references/community-feedback-submission.md
<!-- METRICS_JSON {"step": "finalize", "completion_rate_at_audit": 0.95, "tasks_completed": 19, "tasks_total": 20, "verification_failures_found": 1, "documentation_updates_needed": 2} -->
Replace METRICS_JSON values with actuals. `completion_rate_at_audit` = Y/Z as decimal (e.g., 19/20 = 0.95).
Paste the `comment` from `specs.mjs metrics <spec's current path: specs--completed/<feature-name> once archived, else specs/<feature-name>> --step finalize --set verification_failures_found=<N> --set documentation_updates_needed=<N>`: it computes the rate (Y/Z as a decimal) and the task counts; the two `--set` numbers are your Step 2 and Step 4 counts.
### Finalization Steps Completed
- [x] Step 1: Task Completion Audit
@@ -322,7 +323,7 @@ Replace METRICS_JSON values with actuals. `completion_rate_at_audit` = Y/Z as de
| Completion | Action |
|-----------|--------|
| **>75%** | Finalize with notice. List incomplete items. Note remaining tasks for follow-up cycle. |
| **≥75%** | Finalize with notice. List incomplete items. Note remaining tasks for follow-up cycle. |
| **<75%** | Recommend returning to implementation. List incomplete phases with task counts. Options: 1) Return via `/plan2code-3-implement --web` 2) Proceed with partial finalization. |
## Abort Handling
@@ -348,10 +349,7 @@ If you discovered undocumented commands, dependency quirks, gotchas (>5min cost)
(Step 7 already delivered the completion summary — don't repeat it.)
Suggested commit (only if README, CHANGELOG, or other tracked docs were updated):
```
git commit -m "chore: finalize and archive <feature-name>" -m "<JIRA-Ticket-ID>" -m "AI Assisted"
```
Suggested commit (only if README, CHANGELOG, or other tracked docs were updated): the `command` from `commit-msg.mjs --subject "chore: finalize and archive <feature-name>"` (exit 4 `no-ticket`: show it with `<JIRA-Ticket-ID>` for the user to fill in).
Returning context: Feature complete. Specs archived to `specs--completed/<feature-name>/`.
@@ -2,52 +2,39 @@
> Loaded by `src/plan2code-4-finalize.md` STEP 6.5. This file has no character limit (see `AGENTS-architecture.md` Reference Files).
## 1. Generate a fresh `run_id`
Everything in the payload is read from files, so a script builds it: the metrics from the `METRICS_JSON` comments the pipeline already wrote, the task counts from the phase files, your Step 5 answers from overview.md's `## User Feedback` table, the installed version, and a sha256 prefix of each prompt. Your part is the two judgment counts, the preview, and the user's approval.
Compute your own current timestamp and a freshly generated random 4-character hex string — do not reuse the example value shown below or anywhere in this spec. Format: `run-<YYYYMMDD>-<HHMMSS>-<4-hex-chars>` (e.g. `run-20260715-143000-a1b2`).
## 1. Build the payload
## 2. Assemble the payload
Step 6 has already archived the spec, so point at the archive:
Read `PLAN-DRAFT-*.md`, `phase-*.md`, and `overview.md` in `specs--completed/<feature-name>/` (STEP 6 has already archived them there) and reason over their content to gather:
- `step1`: `final_confidence`, `confidence_breakdown` (`{requirements, feasibility, integration, risk}`), `clarification_rounds`, `tech_stack_revision_rounds`, `verification_gaps_found`, `functional_requirements_count`, `non_functional_requirements_count`, `risk_count`, `phase_count`
- `step2`: `total_tasks`, `phase_count`, `parallel_groups_identified`, `requirement_coverage_percent`, `verification_items_added`
- `step3`: `task_completion_rate`, `tasks_completed`, `tasks_total`, `blocker_count`
- `step4`: `completion_rate_at_audit`, `verification_failures_found`, `documentation_updates_needed`, `archival_succeeded` (safe to read now that Step 6 has run)
- `plan2code_version` — from `version.json`
- `prompt_versions_short` — first 12 characters of each of the 8 prompt file names' content (`plan`, `revise_plan`, `document`, `implement`, `finalize`, `init`, `init_update`, `quick_task`). You do not have `sha256File()` available — note these as best-effort/approximate if you cannot compute a real hash, or omit the field entirely if you cannot.
**Never include** `project.name` or any bulky arrays (e.g. `tasks_per_phase`).
Include the feedback collected at Step 5 as `user_feedback`: `overall_rating`, `rating_reason`, `what_went_well`, `what_went_poorly`.
Assemble the full nested JSON object matching this schema exactly:
```json
{
"schema_version": "1.0",
"run_id": "run-<YYYYMMDD>-<HHMMSS>-<4-hex>",
"plan2code_version": "<from version.json>",
"prompt_versions_short": { "plan": "...", "revise_plan": "...", "document": "...", "implement": "...", "finalize": "...", "init": "...", "init_update": "...", "quick_task": "..." },
"step1": { "final_confidence": 0, "confidence_breakdown": { "requirements": 0, "feasibility": 0, "integration": 0, "risk": 0 }, "clarification_rounds": 0, "tech_stack_revision_rounds": 0, "verification_gaps_found": 0, "functional_requirements_count": 0, "non_functional_requirements_count": 0, "risk_count": 0, "phase_count": 0 },
"step2": { "total_tasks": 0, "phase_count": 0, "parallel_groups_identified": 0, "requirement_coverage_percent": 0, "verification_items_added": 0 },
"step3": { "task_completion_rate": 0, "tasks_completed": 0, "tasks_total": 0, "blocker_count": 0 },
"step4": { "completion_rate_at_audit": 0, "verification_failures_found": 0, "documentation_updates_needed": 0, "archival_succeeded": true },
"user_feedback": { "overall_rating": 0, "rating_reason": "...", "what_went_well": "...", "what_went_poorly": "..." }
}
```
node "<S>/feedback-payload.mjs" build specs--completed/<feature-name> --set verification_failures_found=<N> --set documentation_updates_needed=<N>
```
## 3. Render the GitHub Issue
If Step 6 did not archive (the archive target already existed), the spec is still in `specs/`: pass `specs/<feature-name>` instead. A bare `<feature-name>` that exists in both folders stops with exit 5 `ambiguous-spec` rather than guessing, because `specs--completed/<feature-name>` would be the older run.
- **Title:** `` `[Feedback] v<plan2code_version> — rating <N>/10` `` (e.g. `[Feedback] v1.15.3 — rating 8/10`)
- **Body:** a short human-readable markdown summary (version, rating, headline numbers such as completion rate and confidence), followed by the full payload as `<!-- METRICS_JSON {...} -->` (same HTML-comment convention used in Step 7's own summary block)
- **Label:** `community-feedback`
The two counts are the ones Step 7's METRICS_JSON carries (your Step 2 and Step 4 findings). It prints:
Estimate the combined URL-encoded size of `title` + `body` + `labels`. If it exceeds roughly 8KB, warn the user and offer to truncate the longest free-text `user_feedback` field(s) — starting with `rating_reason`, then `what_went_well`/`what_went_poorly` — before proceeding. This size limit only affects the browser/print fallback tiers (below), not the `gh` CLI tier.
| Field | Use |
|---|---|
| `title`, `body`, `label` | The exact issue to preview. The body ends with the full payload as `<!-- METRICS_JSON {...} -->` |
| `payload` | The schema-1.0 object: a fresh `run_id`, `plan2code_version`, `prompt_versions_short` (12-character sha256 prefixes), `step1`-`step4`, `user_feedback`. It never includes `project.name` or bulky arrays |
| `notes` | Missing METRICS_JSON blocks (that step is `null`, which the ingest side reads as not present). Mention them in one line |
| `oversize`, `urlBytes`, `next` | The prefilled browser URL is over ~8 KB. Offer to shorten the free-text answers; on yes, rebuild with `--truncate` (trims `rating_reason` first, then `what_went_well` / `what_went_poorly`). Tier 1 (`gh`) has no limit, so declining is fine only when `gh` is installed and signed in (`gh auth status`): if `gh` fails, `submit` stops with exit 4 `oversize` instead of falling back to the browser |
| `dir` | Where `payload.json` and `body.md` were written; `submit` needs it |
## 4. Preview and approval gate
| Exit | Meaning | Do |
|---|---|---|
| 2 `missing-set` | A judgment count is missing | Pass both `--set` values |
| 3 `no-feedback` | overview.md has no `## User Feedback` table | Nothing to submit: skip to Step 7 |
| 3 `spec-not-found` | Wrong name or not archived | Check `specs--completed/` |
| 4 `bad-rating` | The Rating row is not 1-10 | Fix the row, rebuild |
| 5 `ambiguous-spec` | A bare name exists in both `specs/` and `specs--completed/` | Pass the exact path: `specs/<feature-name>` if Step 6 did not archive this run |
Display the exact rendered title, full body (including the `METRICS_JSON` block), and label(s) to the user, mirroring the Step 4 Documentation Review pattern:
## 2. Preview and approval gate
Display the exact `title`, the full `body` (including the `METRICS_JSON` block), and the label to the user, mirroring the Step 4 Documentation Review pattern:
```
⋅
@@ -61,12 +48,25 @@ Display the exact rendered title, full body (including the `METRICS_JSON` block)
Do NOT proceed to submission without an explicit "approve" reply. A "skip" or any non-approval reply cancels this sub-step entirely and proceeds to Step 7 with no submission.
## 5. Tiered submission
## 3. Submit
On approval, attempt each tier in order until one succeeds:
On approval only:
1. **Tier 1 (primary):** Attempt `gh issue create --repo jparkerweb/plan2code --title "<title>" --body "<body>" --label community-feedback` via your shell tool. If it succeeds, report the created issue URL to the user and stop.
2. **Tier 2 (secondary):** If `gh` is not installed or not authenticated (command fails), construct the URL `https://github.com/jparkerweb/plan2code/issues/new?title=<url-encoded title>&body=<url-encoded body>&labels=community-feedback` and attempt to open it in the user's default browser using the OS-appropriate command (`start "<url>"` on Windows, `open "<url>"` on macOS, `xdg-open "<url>"` on Linux). Tell the user they still need to click "Submit issue" themselves since they must be logged in.
3. **Tier 3 (tertiary):** If no browser can be opened (e.g. no shell tool access, headless/remote session), print the same URL from Tier 2 to the terminal/chat: "Please open this URL in your browser and click 'Submit issue' to share your feedback: `<url>`".
```
node "<S>/feedback-payload.mjs" submit --from <dir>
```
After any tier succeeds (or the user manually confirms Tier 3 submission), proceed to Step 7 as normal.
It tries each tier in order and reports the one that worked:
| `tier` | What happened | Tell the user |
|---|---|---|
| 1 | `gh issue create` succeeded | The issue URL (`issue`) |
| 2 | `gh` missing or not signed in (`ghError`); the system was asked to open the prefilled new-issue page | If it opened, they still need to click **Submit new issue**, signed in to GitHub. If nothing opened (a remote or headless session), give them `url` as in tier 3 |
| 3 | No browser could be opened (headless or remote session) | "Please open this URL in your browser and click 'Submit new issue' to share your feedback:" plus `url` |
| Exit | Meaning | Do |
|---|---|---|
| 3 `no-payload` | `--from` has no `payload.json` / `body.md` | Pass the `dir` that `build` printed |
| 4 `oversize` | `gh` failed (`message` says why) and the URL is over ~8 KB, too long for tiers 2 and 3, so neither ran | Offer to shorten the free-text answers: on yes, rebuild with `--truncate` and submit again. Or have the user install `gh` and run `gh auth login`, then submit again |
`--dry-run` shows the tiers without running them, plus `urlBytes` and `oversize` (when `oversize` is true, only tier 1 can submit). After any tier succeeds (or the user confirms a tier 3 submission), proceed to Step 7 as normal.
@@ -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
// (PCWEB-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 PCWEB-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,379 @@
#!/usr/bin/env node
// feedback-payload.mjs: Finalize STEP 6.5, the community feedback submission.
//
// The payload is fixed data: metrics read from the METRICS_JSON comments the
// pipeline already wrote, task counts read from the phase files, the user's
// Step 5 answers read from overview.md's ## User Feedback table, the installed
// version, and a sha256 prefix of each prompt. None of it needs judgment, and
// the hashes cannot be computed by reading. The submission is a fixed tier
// sequence (gh, then the browser, then a printed URL). Both live here; the
// agent previews and asks for approval in between.
import fs from "node:fs";
import os from "node:os";
import path from "node:path";
import crypto from "node:crypto";
import { execFileSync, spawn } from "node:child_process";
import { EXIT, HERE, fail, out, parseArgs, run, readText, isDir, rel, compactDate, clock, version, phaseFiles } from "./common.mjs";
const USAGE = `
feedback-payload.mjs: build and submit the community feedback payload. JSON on stdout.
node feedback-payload.mjs build <spec> --set verification_failures_found=N
--set documentation_updates_needed=N [--truncate] [--root <dir>] [--out <dir>]
<spec> is the archived spec (specs--completed/<name>, specs/<name> when
Step 6 did not archive, or <name>). Reads
its PLAN-DRAFT, overview.md and phase files, and the ## User Feedback
table Step 5 appended. Writes payload.json and body.md to --out (default:
a new folder in the OS temp dir) and prints the title, body, label, the
browser URL and its size. --truncate shortens the free-text answers
(rating_reason first, then what_went_well / what_went_poorly) until the
URL fits 8 KB.
node feedback-payload.mjs submit --from <dir> [--dry-run]
Only after the user approved the preview. Tier 1: gh issue create.
Tier 2: open the prefilled new-issue page in the browser (the user still
clicks Submit). Tier 3: print the URL. Reports the tier that worked.
Tiers 2 and 3 are skipped when the URL is over 8 KB (exit 4 oversize).
Exit: 0 ok · 2 bad arguments · 3 spec, feedback table or payload not found ·
4 the payload would be invalid (e.g. no rating), or gh failed and the URL is
too long for the other tiers · 5 a bare <name> exists in both specs/ and
specs--completed/ (pass the exact path).
`;
const REPO = "jparkerweb/plan2code";
const LABEL = "community-feedback";
const URL_LIMIT = 8192;
// Prompt keys the metrics pipeline cohorts on, and the skill each comes from.
const PROMPTS = {
plan: "plan2code-1-plan",
revise_plan: "plan2code-1b-revise-plan",
document: "plan2code-2-document",
implement: "plan2code-3-implement",
finalize: "plan2code-4-finalize",
init: "plan2code-init",
init_update: "plan2code-init-update",
quick_task: "plan2code-quick-task",
};
/**
* The prompt's source text: an installed skill's SKILL.md minus the generated
* frontmatter (the installer writes header + "\n\n" + source), or the repo's
* src/<name>.md. Hashing either gives the same sha256 the metrics collector
* computes from src/.
*/
function promptSource(name) {
const skillMd = path.join(HERE, "..", "..", name, "SKILL.md");
const text = readText(skillMd);
if (text !== null) {
const m = text.match(/^---\r?\n[\s\S]*?\r?\n---\r?\n\r?\n/);
return m ? text.slice(m[0].length) : text;
}
for (const candidate of [path.join(HERE, "..", "..", "..", "src", `${name}.md`), path.join(HERE, "..", "..", "src", `${name}.md`)]) {
const t = readText(candidate);
if (t !== null) return t;
}
return null;
}
function promptVersions() {
const outV = {};
for (const [key, name] of Object.entries(PROMPTS)) {
const src = promptSource(name);
outV[key] = src === null ? "sha256:missing" : crypto.createHash("sha256").update(src, "utf8").digest("hex").slice(0, 12);
}
return outV;
}
function metricsBlocks(text) {
const blocks = [];
for (const m of (text || "").matchAll(/<!--\s*METRICS_JSON\s+(\{[\s\S]*?\})\s*-->/g)) {
try {
blocks.push(JSON.parse(m[1]));
} catch {}
}
return blocks;
}
const num = (v) => (typeof v === "number" && Number.isFinite(v) ? v : null);
function parseFeedbackTable(overview) {
const sec = overview.match(/^## +User Feedback\s*$([\s\S]*?)(?=^## |(?![\s\S]))/m);
if (!sec) return null;
const fields = {};
for (const line of sec[1].split(/\r?\n/)) {
if (!/^\s*\|/.test(line) || /^\s*\|[\s:|-]+\|\s*$/.test(line)) continue;
// Split on pipes that are not escaped (values escape theirs as \|).
const cells = line.trim().replace(/^\||\|$/g, "").split(/(?<!\\)\|/).map((c) => c.trim().replace(/\\\|/g, "|"));
if (cells.length >= 2 && !/^field$/i.test(cells[0])) fields[cells[0].toLowerCase()] = cells.slice(1).join("|").trim();
}
return fields;
}
function phaseTasks(dir) {
const c = { total: 0, complete: 0, assumed: 0, blocked: 0 };
// The same files specs.mjs reads: a stale sibling like phase-1-old.md is not counted.
for (const n of phaseFiles(dir).values()) {
for (const line of (readText(path.join(dir, n)) || "").split(/\r?\n/)) {
// The same task line specs.mjs counts: 2.3, 3.6a, or a named 1.T.
const m = line.match(/^\s*[-*] \[(.)\]\s+\*\*Task\s+\d+\.(?:\d+|[A-Za-z]+)[a-z]*\b/);
if (!m) continue;
c.total++;
if (/[xX]/.test(m[1])) c.complete++;
else if (m[1] === "?") c.assumed++;
else if (m[1] === "!") c.blocked++;
}
}
return c;
}
function locateSpec(root, arg) {
if (!arg) fail(EXIT.USAGE, "missing-spec", "Name the archived spec.", "Example: build specs--completed/user-auth");
const p = arg.replace(/\\/g, "/").replace(/\/+$/, "");
const candidates = p.includes("/") ? [path.resolve(root, p)] : [path.join(root, "specs--completed", p), path.join(root, "specs", p)];
// A bare name in both places means Step 6 did not archive (the target
// existed): specs--completed/<name> is an older run, so guessing would read
// the wrong spec.
if (candidates.length > 1 && candidates.every(isDir)) fail(EXIT.REFUSED, "ambiguous-spec", `Both specs/${p} and specs--completed/${p} exist.`, `Pass the exact path: specs/${p} when Step 6 did not archive this run, specs--completed/${p} when it did.`);
const dir = candidates.find(isDir);
if (!dir) fail(EXIT.NOT_FOUND, "spec-not-found", `No spec folder at ${candidates.map((c) => rel(root, c)).join(" or ")}.`, "Step 6 archives to specs--completed/<name>/; check the name.");
return dir;
}
function urlFor(title, body) {
return `https://github.com/${REPO}/issues/new?title=${encodeURIComponent(title)}&body=${encodeURIComponent(body)}&labels=${LABEL}`;
}
function render(payload) {
const f = payload.user_feedback;
const title = `[Feedback] v${payload.plan2code_version} - rating ${f.overall_rating}/10`;
const pct = (v) => (v === null || v === undefined ? "n/a" : `${Math.round(v * 100)}%`);
// The person's words are shown as text, never markup: a "<!--" in them must
// not open a comment ahead of the payload's.
const shown = (s) => String(s).replace(/</g, "&lt;");
// Inside the comment, < and > are written as \u003c / \u003e: still valid JSON
// that parses back to the same text, but a "-->" in an answer can no longer
// end the comment (or the ingest regex) early.
const json = JSON.stringify(payload).replace(/</g, "\\u003c").replace(/>/g, "\\u003e");
const s1 = payload.step1 || {};
const s2 = payload.step2 || {};
const body = [
"## Plan2Code run feedback",
"",
`- **Version:** ${payload.plan2code_version}`,
`- **Rating:** ${f.overall_rating}/10`,
`- **Planning confidence:** ${s1.final_confidence ?? "n/a"}`,
`- **Tasks completed:** ${payload.step3.tasks_completed ?? "n/a"} of ${payload.step3.tasks_total ?? "n/a"} (${pct(payload.step3.task_completion_rate)})`,
`- **Phases:** ${s2.phase_count ?? s1.phase_count ?? "n/a"}`,
"",
`**Reason:** ${shown(f.rating_reason)}`,
"",
`**Went well:** ${shown(f.what_went_well)}`,
"",
`**Went poorly:** ${shown(f.what_went_poorly)}`,
"",
`<!-- METRICS_JSON ${json} -->`,
"",
].join("\n");
return { title, body };
}
function sizeOf(title, body) {
return Buffer.byteLength(urlFor(title, body), "utf8");
}
async function cmdBuild(args) {
const root = path.resolve(args.root || ".");
const dir = locateSpec(root, args._[1]);
const sets = {};
for (const kv of args.set || []) {
const m = kv.match(/^([a-z_]+)=(\d+)$/);
if (!m) fail(EXIT.USAGE, "bad-set", `--set ${kv} is not key=integer.`, "Example: --set verification_failures_found=1");
if (!["verification_failures_found", "documentation_updates_needed"].includes(m[1])) fail(EXIT.USAGE, "bad-set", `--set ${m[1]} is not a field you supply.`, "Only verification_failures_found and documentation_updates_needed; the rest is read from the files.");
sets[m[1]] = Number(m[2]);
}
const overview = readText(path.join(dir, "overview.md"));
if (overview === null) fail(EXIT.NOT_FOUND, "no-overview", `${rel(root, dir)} has no overview.md.`, "The payload reads overview.md; check the archive.");
const feedback = parseFeedbackTable(overview);
if (!feedback) fail(EXIT.NOT_FOUND, "no-feedback", "overview.md has no ## User Feedback table.", "Step 5 appends it; with no feedback there is nothing to submit, so skip Step 6.5.");
// As lenient as the metrics collector: field names any case, "8/10" reads as 8.
const rating = parseInt(feedback.rating, 10);
if (!Number.isInteger(rating) || rating < 1 || rating > 10) fail(EXIT.INVALID, "bad-rating", `The User Feedback Rating "${feedback.rating ?? ""}" is not a whole number from 1 to 10.`, "Fix the Rating row in overview.md, then rebuild.");
const drafts = fs.readdirSync(dir).filter((n) => /^PLAN-DRAFT-.*\.md$/i.test(n) && !/-prev\.md$/i.test(n)).sort();
const draft = drafts.length ? readText(path.join(dir, drafts.at(-1))) : null;
const plan = metricsBlocks(draft).find((b) => !b.step || b.step === "plan") || null;
const overviewBlocks = metricsBlocks(overview);
const doc = overviewBlocks.find((b) => b.step === "document") || null;
const fin = overviewBlocks.find((b) => b.step === "finalize") || null;
const tasks = phaseTasks(dir);
const done = tasks.complete + tasks.assumed;
const rate = tasks.total ? Number((done / tasks.total).toFixed(2)) : null;
const bd = plan && plan.confidence_breakdown && typeof plan.confidence_breakdown === "object" ? plan.confidence_breakdown : null;
const pick = (k) => (k in sets ? sets[k] : fin ? num(fin[k]) : null);
const missing = ["verification_failures_found", "documentation_updates_needed"].filter((k) => pick(k) === null);
if (missing.length) fail(EXIT.USAGE, "missing-set", `Pass ${missing.map((k) => `--set ${k}=N`).join(" and ")} (your Step 2 and Step 4 counts).`, "They are the same numbers Step 7's METRICS_JSON carries.");
const name = path.basename(dir);
const payload = {
schema_version: "1.0",
run_id: `run-${compactDate()}-${clock()}-${crypto.randomBytes(2).toString("hex")}`,
plan2code_version: version() || "unknown",
prompt_versions_short: promptVersions(),
// A step with no METRICS_JSON block is null, which the ingest side reads as
// "not present"; an object of nulls would be counted as present.
step1: plan
? {
final_confidence: num(plan.confidence ?? plan.final_confidence),
confidence_breakdown: bd ? { requirements: num(bd.requirements), feasibility: num(bd.feasibility), integration: num(bd.integration), risk: num(bd.risk) } : null,
clarification_rounds: num(plan.clarification_rounds),
tech_stack_revision_rounds: num(plan.tech_stack_revision_rounds),
verification_gaps_found: num(plan.verification_gaps_found),
functional_requirements_count: num(plan.functional_requirements_count),
non_functional_requirements_count: num(plan.non_functional_requirements_count),
risk_count: num(plan.risk_count),
phase_count: num(plan.phase_count),
}
: null,
step2: doc
? {
total_tasks: num(doc.total_tasks),
phase_count: num(doc.phase_count),
parallel_groups_identified: num(doc.parallel_groups_identified),
requirement_coverage_percent: num(doc.requirement_coverage_percent),
verification_items_added: num(doc.verification_items_added),
}
: null,
step3: { task_completion_rate: rate, tasks_completed: done, tasks_total: tasks.total, blocker_count: tasks.blocked },
step4: {
completion_rate_at_audit: fin ? num(fin.completion_rate_at_audit) ?? rate : rate,
verification_failures_found: pick("verification_failures_found"),
documentation_updates_needed: pick("documentation_updates_needed"),
archival_succeeded: /specs--completed$/.test(path.dirname(dir)) && !isDir(path.join(root, "specs", name)),
},
user_feedback: {
overall_rating: rating,
rating_reason: feedback.reason || "",
what_went_well: feedback["went well"] || "",
what_went_poorly: feedback["went poorly"] || "",
},
};
let { title, body } = render(payload);
const truncated = [];
if (args.truncate) {
// Each field keeps at least 40 characters of its own text. Every pass cuts
// from the field's ORIGINAL text, so the loop always shortens and ends.
for (const field of ["rating_reason", "what_went_well", "what_went_poorly"]) {
const original = payload.user_feedback[field];
let keep = original.length;
while (sizeOf(title, body) > URL_LIMIT && keep > 40) {
keep = Math.max(40, Math.floor(keep * 0.8));
// Never cut between the two halves of a surrogate pair (an emoji): a
// lone half makes encodeURIComponent throw.
let end = keep;
if (/[\uD800-\uDBFF]/.test(original[end - 1] || "")) end--;
payload.user_feedback[field] = original.slice(0, end).trimEnd() + "...";
({ title, body } = render(payload));
if (!truncated.includes(field)) truncated.push(field);
}
}
}
const outDir = path.resolve(args.out || fs.mkdtempSync(path.join(os.tmpdir(), "plan2code-feedback-")));
fs.mkdirSync(outDir, { recursive: true });
fs.writeFileSync(path.join(outDir, "payload.json"), JSON.stringify({ title, label: LABEL, payload }, null, 2));
fs.writeFileSync(path.join(outDir, "body.md"), body);
const url = urlFor(title, body);
const bytes = Buffer.byteLength(url, "utf8");
out({
ok: true,
dir: outDir,
title,
label: LABEL,
body,
payload,
url,
urlBytes: bytes,
oversize: bytes > URL_LIMIT,
...(truncated.length ? { truncated } : {}),
...(bytes > URL_LIMIT && !args.truncate ? { next: "The browser and print tiers cap URLs near 8 KB: offer to shorten the free-text answers, then rebuild with --truncate. gh (tier 1) has no limit, but if gh fails, submit stops with exit 4 oversize instead of opening a cut-off page." } : {}),
notes: [
...(plan ? [] : ["No plan METRICS_JSON in the PLAN-DRAFT: step1 is null (not present)."]),
...(doc ? [] : ["No document METRICS_JSON in overview.md: step2 is null (not present)."]),
],
});
}
function tryGh(dir, title) {
try {
const url = execFileSync("gh", ["issue", "create", "--repo", REPO, "--title", title, "--body-file", path.join(dir, "body.md"), "--label", LABEL], {
encoding: "utf8",
stdio: ["ignore", "pipe", "pipe"],
timeout: 60000,
}).trim();
return { ok: true, url: url.split(/\s+/).find((s) => s.startsWith("https://")) || url };
} catch (err) {
return { ok: false, why: String((err.stderr || err.message || "").toString().trim().split("\n")[0] || "gh failed") };
}
}
function openBrowser(url) {
// No shell in between: a URL full of & and % survives intact.
const [cmd, argv] =
process.platform === "win32" ? ["rundll32", ["url.dll,FileProtocolHandler", url]] :
process.platform === "darwin" ? ["open", [url]] :
["xdg-open", [url]];
return new Promise((resolve) => {
try {
const child = spawn(cmd, argv, { stdio: "ignore", detached: true });
child.on("error", () => resolve(false));
child.on("spawn", () => {
child.unref();
resolve(true);
});
} catch {
resolve(false);
}
});
}
async function cmdSubmit(args) {
if (!args.from) fail(EXIT.USAGE, "missing-from", "--from <dir> is required (the dir `build` printed).", "Run build first.");
const dir = path.resolve(args.from);
const saved = readText(path.join(dir, "payload.json"));
const body = readText(path.join(dir, "body.md"));
if (saved === null || body === null) fail(EXIT.NOT_FOUND, "no-payload", `${dir} has no payload.json / body.md.`, "Run build first and pass the dir it printed.");
const { title } = JSON.parse(saved);
const url = urlFor(title, body);
const urlBytes = Buffer.byteLength(url, "utf8");
const oversize = urlBytes > URL_LIMIT;
if (args["dry-run"]) {
out({ ok: true, dryRun: true, urlBytes, oversize, tiers: [`gh issue create --repo ${REPO} --title "${title}" --body-file ${path.join(dir, "body.md")} --label ${LABEL}`, `open in browser: ${url.slice(0, 120)}...`, "print the URL"], ...(oversize ? { note: "The URL is over 8 KB: only tier 1 (gh) can submit this payload; tiers 2 and 3 would be skipped." } : {}) });
return;
}
const gh = tryGh(dir, title);
if (gh.ok) {
out({ ok: true, tier: 1, issue: gh.url, message: `Feedback submitted: ${gh.url}` });
return;
}
// The browser and print tiers cap URLs near 8 KB: an oversize URL would open
// a page with the body cut off (or none at all), so do not offer it.
if (oversize) fail(EXIT.INVALID, "oversize", `gh failed (${gh.why}) and the prefilled URL is ${urlBytes} bytes, over the ${URL_LIMIT}-byte limit of the browser and print tiers.`, "Offer to shorten the free-text answers and rebuild with --truncate, then submit again; or install gh and sign in (gh auth login) so tier 1 can submit it as is.");
if (await openBrowser(url)) {
// A launched opener is not proof a browser appeared (a headless or remote
// session has none), so the URL always rides along.
out({ ok: true, tier: 2, ghError: gh.why, url, message: "Asked the system to open the prefilled issue in the browser. If a page opened, the user still has to click Submit new issue (signed in to GitHub). If nothing opened, give them the url to open by hand (tier 3)." });
return;
}
out({ ok: true, tier: 3, ghError: gh.why, url, message: "Please open this URL in your browser and click 'Submit new issue' to share your feedback." });
}
run(USAGE, async (argv) => {
const args = parseArgs(argv, { booleans: ["dry-run", "truncate"], values: ["root", "out", "from"], lists: ["set"] });
const cmd = args._[0];
if (cmd === "build") return cmdBuild(args);
if (cmd === "submit") return cmdSubmit(args);
fail(EXIT.USAGE, "unknown-command", cmd ? `Unknown command "${cmd}".` : "No command given.", "Commands: build, submit. Run with --help.");
});
@@ -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"
}