mirror of
https://github.com/jparkerweb/plan2code.git
synced 2026-11-16 04:45:33 -08:00
Compare commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
7e2c824d4f | ||
|
|
8890c3ad13 |
No files matched your search
@@ -2,6 +2,12 @@
|
||||
|
||||
All notable changes to Plan2Code will be documented in this file.
|
||||
|
||||
## v2.7.1
|
||||
|
||||
### 🐛 Fixed
|
||||
|
||||
- **implement**: Implement no longer says there is nothing left to do while the dashboard keeps Finalize greyed out. When every phase is approved but tasks under them are still open (usually manual steps an agent could not do, left blocked `[!]` with a "User action"), `specs.mjs status` now returns a `checkoff` verdict listing them, and Implement asks about each one in turn: "Is this done?" in the terminal, or a **Done, check it off** / **Not yet** card in the web console. A yes runs the new `specs.mjs tick <spec> --task <id>`, which marks the task `[x]` and adds a "Confirmed done by the user on <date>" line under it. Once nothing is left open, Implement points to `/plan2code-4-finalize` and the dashboard shows the spec as ready to finalize.
|
||||
|
||||
## v2.7.0
|
||||
|
||||
### ✨ Added
|
||||
|
||||
+1
-1
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "plan2code",
|
||||
"version": "2.7.0",
|
||||
"version": "2.7.1",
|
||||
"private": true,
|
||||
"bin": {
|
||||
"plan2code-install": "./install.js"
|
||||
|
||||
@@ -152,8 +152,46 @@ test("specs status: the implement selection table", () => {
|
||||
assert.ok(next("x", "x", "/", "/").warning, "all options already [/] warns about duplicated work");
|
||||
assert.equal(next("x", " ", " ", " ").action, "auto-start");
|
||||
assert.equal(next("x", "x", "x", " ").action, "auto-start");
|
||||
assert.equal(next("x", "x", "x", "x").action, "none");
|
||||
assert.equal(next("x", "x", "x", "x").reason, "every phase is complete");
|
||||
assert.equal(next("x", "x", "x", "x").action, "checkoff", "approved phases with open tasks are not finished");
|
||||
assert.deepEqual(next("x", "x", "x", "x").tasks.map((t) => t.id), ["2.2", "3.1", "3.2", "3.2a", "3.4", "4.1"]);
|
||||
});
|
||||
|
||||
test("specs: open tasks under approved phases are a checkoff, and tick checks them off one at a time", () => {
|
||||
const root = specFixture();
|
||||
write(root, "specs/lunch-vote/overview.md", OVERVIEW.replace(/- \[[ /]\] /g, "- [x] "));
|
||||
write(root, "specs/lunch-vote/phase-2.md", phase(2, "Complete", [["x", "2.1"], ["x", "2.2"]]));
|
||||
write(root, "specs/lunch-vote/phase-3.md", phase(3, "Complete", [["x", "3.1"], ["x", "3.2"], ["x", "3.3"]]));
|
||||
write(
|
||||
root,
|
||||
"specs/lunch-vote/phase-4.md",
|
||||
phase(4, "Complete", [["!", "4.1"], [" ", "4.2"], ["x", "4.3"]]).replace("**Task 4.1:** Do 4.1", "**Task 4.1:** Create the Okta app\n > BLOCKED: needs admin. User action: create it.\n")
|
||||
);
|
||||
const S = (...a) => runScript("plan2code-3-implement", "specs.mjs", [...a, "--root", root]);
|
||||
const j = S("status", "lunch-vote").json;
|
||||
assert.equal(j.next.action, "checkoff");
|
||||
assert.match(j.next.reason, /2 tasks are still open/);
|
||||
assert.deepEqual(j.next.tasks.map((t) => [t.id, t.marker]), [["4.1", "[!]"], ["4.2", "[ ]"]]);
|
||||
assert.equal(j.next.tasks[0].text, "Create the Okta app");
|
||||
assert.match(j.next.tasks[0].detail, /User action: create it/);
|
||||
assert.equal(S("list").json.specs.find((s) => s.name === "lunch-vote").state, "building", "the dashboard agrees: not built yet");
|
||||
|
||||
assert.equal(S("tick", "lunch-vote", "--task", "4.1", "--dry-run").json.changed, true);
|
||||
assert.match(read(root, "specs/lunch-vote/phase-4.md"), /- \[!\] \*\*Task 4\.1/, "dry-run writes nothing");
|
||||
const one = S("tick", "lunch-vote", "--task", "4.1");
|
||||
assert.equal(one.code, 0, one.stderr);
|
||||
assert.deepEqual(one.json.remaining, ["4.2"]);
|
||||
assert.equal(one.json.next, "checkoff");
|
||||
const text = read(root, "specs/lunch-vote/phase-4.md");
|
||||
assert.match(text, /- \[x\] \*\*Task 4\.1:\*\* Create the Okta app\n > BLOCKED: needs admin\. User action: create it\.\n > Confirmed done by the user on \d{4}-\d{2}-\d{2}\.\n/);
|
||||
assert.equal(S("tick", "lunch-vote", "--task", "4.1").json.changed, false, "ticking a done task is a no-op");
|
||||
const last = S("tick", "lunch-vote", "--task", "4.2");
|
||||
assert.deepEqual(last.json.remaining, []);
|
||||
assert.equal(last.json.next, "none");
|
||||
assert.equal(S("status", "lunch-vote").json.next.reason, "every phase is complete");
|
||||
assert.equal(S("list").json.specs.find((s) => s.name === "lunch-vote").state, "built", "Finalize lights up on the dashboard");
|
||||
|
||||
assert.equal(S("tick", "lunch-vote", "--task", "4.9").code, 3);
|
||||
assert.equal(S("tick", "lunch-vote", "--task", "nope").code, 2);
|
||||
});
|
||||
|
||||
test("specs status: drift between the checklist and the phase files is an error", () => {
|
||||
@@ -397,7 +435,7 @@ test("specs: group ranges expand, chains are not parallel, [?] phases count as d
|
||||
assert.deepEqual(runScript("plan2code-3-implement", "specs.mjs", ["status", "lunch-vote", "--root", root]).json.parallelGroups, []);
|
||||
write(root, "specs/lunch-vote/overview.md", OVERVIEW.replace("- [/] [Phase 2", "- [?] [Phase 2").replace("- [ ] **Phase 3", "- [?] **Phase 3").replace("- [ ] [Phase 4", "- [?] [Phase 4"));
|
||||
const done = runScript("plan2code-3-implement", "specs.mjs", ["status", "lunch-vote", "--root", root]).json;
|
||||
assert.equal(done.next.reason, "every phase is complete");
|
||||
assert.equal(done.next.action, "checkoff", "[?] phases count as done; their open tasks still need checking off");
|
||||
assert.deepEqual(done.pending, []);
|
||||
write(root, "specs/lunch-vote/overview.md", OVERVIEW.replace("- [/] [Phase 2", "- [!] [Phase 2"));
|
||||
const skip = runScript("plan2code-3-implement", "specs.mjs", ["status", "lunch-vote", "--root", root]).json.next;
|
||||
|
||||
@@ -72,10 +72,22 @@ Never reset `[/]` to `[ ]`. Started work stays marked for conscious resume decis
|
||||
| `choose` | Show a selection prompt listing each of `options` with its status. TIP: run another agent on a different phase simultaneously. Relay `warning` (all already `[/]`: duplicated work) when present. |
|
||||
| `ask-resume` | Prompt: "Phase X is in progress. Resume? (yes/no)" Relay `warning` when present. |
|
||||
| `auto-start` | Mark it `[/]` and begin. Relay `warning` when present. |
|
||||
| `checkoff` | Every phase is approved but tasks in them are still open (manual steps, blockers). Never say "nothing left to do": run Manual Check-Off below. |
|
||||
| `none` | Nothing to implement: say why (`reason`). Every phase complete → `/plan2code-4-finalize --web` |
|
||||
|
||||
After selection, `mark --to in-progress`, read `phase-X.md`, begin.
|
||||
|
||||
### Manual Check-Off
|
||||
|
||||
`next.tasks` lists each open task (`id`, `marker`, `text`, `detail` with any BLOCKED / User action note). The spec is not built, and Finalize stays unavailable on the dashboard, until each is `[x]`. Say so in one line, then ask about them **one at a time**, in order:
|
||||
|
||||
1. Show the task: id, `text`, and what `detail` says the person must do or check.
|
||||
2. Ask: "Is this done? (yes / not yet)". Console: a `confirm` item (`yesLabel` "Done, check it off", `noLabel` "Not yet"), posted with `--wait`, a new id per task.
|
||||
3. Yes → `node "<S>/specs.mjs" tick <spec> --task <id>` (writes `[x]` and a "Confirmed done by the user" line). Not yet → leave it as it stands. A note asking for help: help, then ask again.
|
||||
4. Next task.
|
||||
|
||||
After the last one: `tick`'s `remaining` empty (`next` is `none`) → "NEXT STEP: Start NEW conversation and run: `/plan2code-4-finalize --web`". Otherwise list what is still open, say Finalize opens once they are checked off, and that rerunning Implement asks again. Never tick a task the person did not confirm.
|
||||
|
||||
## Code Consistency Rules
|
||||
|
||||
| Rule | Description |
|
||||
|
||||
@@ -6,7 +6,8 @@
|
||||
// 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.
|
||||
// (a Phase Checklist marker, a task the user confirmed, 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.
|
||||
@@ -26,7 +27,8 @@ specs.mjs: spec state for the Plan2Code pipeline skills. JSON on stdout.
|
||||
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
|
||||
completion, the implement phase-selection verdict ("next": choose,
|
||||
ask-resume, auto-start, checkoff or none), the pending
|
||||
phases, and consistency checks. <spec> is specs/<name>, <name>, or a path
|
||||
to its overview.md.
|
||||
|
||||
@@ -49,6 +51,13 @@ specs.mjs: spec state for the Plan2Code pipeline skills. JSON on stdout.
|
||||
Status line. Refuses a phase with duplicate checklist rows, and refuses
|
||||
in-progress -> open (started work stays marked).
|
||||
|
||||
node specs.mjs tick <spec> --task <N.M> [--dry-run]
|
||||
Check off one task the user confirmed is done: its marker becomes [x]
|
||||
and a "> Confirmed done by the user on <date>." line goes under it.
|
||||
Prints the tasks still open under approved phases ("remaining") and the
|
||||
new phase-selection verdict ("next"). For the manual steps that
|
||||
status's "checkoff" verdict lists.
|
||||
|
||||
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/.
|
||||
@@ -206,6 +215,21 @@ function firstSentence(text) {
|
||||
return (m ? m[1] : t).slice(0, 240);
|
||||
}
|
||||
|
||||
// The lines under a task (its file path, notes, a BLOCKED / User action
|
||||
// blockquote), up to the next heading or checkbox: what a person needs to
|
||||
// judge whether a task they are asked about is done. taskBody is the index
|
||||
// just past its last non-blank line.
|
||||
function taskBody(lines, i) {
|
||||
let end = i + 1;
|
||||
while (end < lines.length && !/^#{1,6}\s/.test(lines[end]) && !CHECKBOX_RE.test(lines[end])) end++;
|
||||
while (end > i + 1 && !lines[end - 1].trim()) end--;
|
||||
return end;
|
||||
}
|
||||
|
||||
function taskDetail(lines, i) {
|
||||
return lines.slice(i + 1, taskBody(lines, i)).map((l) => l.trim()).filter(Boolean).join("\n").slice(0, 800);
|
||||
}
|
||||
|
||||
function parsePhaseFile(file, number) {
|
||||
const text = readText(file) || "";
|
||||
const lines = text.split(/\r?\n/);
|
||||
@@ -224,7 +248,8 @@ function parsePhaseFile(file, number) {
|
||||
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 });
|
||||
const said = plainText(line.slice(t[0].length)).replace(/^:\s*/, "").slice(0, 240);
|
||||
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, text: said, detail: taskDetail(lines, i) });
|
||||
return;
|
||||
}
|
||||
// A line that looks like a task but is not counted as one (Task 1.4A,
|
||||
@@ -306,6 +331,10 @@ function specStatus(spec) {
|
||||
}
|
||||
|
||||
const phases = [];
|
||||
// Tasks still open under a phase the user already approved: the manual
|
||||
// steps an agent could not do (blocked [!]) or left unticked. Nothing is left
|
||||
// to build, but the spec is not built until someone checks them off.
|
||||
const leftovers = [];
|
||||
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;
|
||||
@@ -339,6 +368,11 @@ function specStatus(spec) {
|
||||
}
|
||||
const done = parsed.counts.complete + parsed.counts.assumed;
|
||||
const rowDone = row && (row.state === "complete" || row.state === "assumed");
|
||||
if (rowDone) {
|
||||
for (const t of parsed.tasks.filter((t) => ["pending", "in-progress", "blocked", "unknown"].includes(t.state))) {
|
||||
leftovers.push({ phase: number, id: t.id, marker: `[${t.marker}]`, state: t.state, file: `${spec.rel}/${file}`, line: t.line, text: t.text, detail: t.detail });
|
||||
}
|
||||
}
|
||||
// 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) {
|
||||
@@ -382,7 +416,7 @@ function specStatus(spec) {
|
||||
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),
|
||||
next: nextPhase(phases, groups.groups, checklist.found, leftovers),
|
||||
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 })),
|
||||
@@ -393,14 +427,24 @@ function specStatus(spec) {
|
||||
/**
|
||||
* 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
|
||||
* a single [/] -> ask-resume · a single [ ] -> auto-start
|
||||
* nothing workable, every phase approved, tasks still open in them -> checkoff
|
||||
* nothing workable otherwise -> none
|
||||
*/
|
||||
function nextPhase(phases, groups, haveChecklist) {
|
||||
function nextPhase(phases, groups, haveChecklist, leftovers = []) {
|
||||
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) {
|
||||
if (ordered.length && ordered.every(isDone) && leftovers.length) {
|
||||
const n = leftovers.length;
|
||||
return {
|
||||
action: "checkoff",
|
||||
reason: `every phase is approved, but ${n} task${n === 1 ? " is" : "s are"} still open in them (${leftovers.map((t) => t.id).join(", ")}); the spec is not built until ${n === 1 ? "it is" : "they are"} checked off`,
|
||||
tasks: leftovers,
|
||||
};
|
||||
}
|
||||
return { action: "none", reason: ordered.length && ordered.every(isDone) ? "every phase is complete" : "no [ ] or [/] phase in the Phase Checklist" };
|
||||
}
|
||||
const first = workable[0];
|
||||
@@ -611,6 +655,47 @@ async function cmdMark(args) {
|
||||
});
|
||||
}
|
||||
|
||||
// Check off one task the user confirmed is done (a manual step left open under
|
||||
// an approved phase). The marker changes, and one line under the task says who
|
||||
// confirmed it, so the file never claims the agent verified it.
|
||||
async function cmdTick(args) {
|
||||
const root = path.resolve(args.root || ".");
|
||||
const spec = resolveSpec(root, args._[1]);
|
||||
const id = String(args.task || "");
|
||||
const m = id.match(/^(\d+)\.(\d+|[A-Za-z]+)([a-z]*)$/);
|
||||
if (!m) fail(EXIT.USAGE, "bad-task", "--task needs a task id.", "Example: --task 2.3");
|
||||
const number = Number(m[1]);
|
||||
const file = phaseFiles(spec.dir).get(number);
|
||||
if (!file) fail(EXIT.NOT_FOUND, "no-phase-file", `${spec.rel} has no phase-${number}.md.`, "Run `specs.mjs status` to see the phases.");
|
||||
const phasePath = path.join(spec.dir, file);
|
||||
const text = readText(phasePath) || "";
|
||||
const hits = parsePhaseFile(phasePath, number).tasks.filter((t) => t.id === id);
|
||||
if (!hits.length) fail(EXIT.NOT_FOUND, "no-task", `${file} has no Task ${id}.`, "Use an id from `specs.mjs status` (next.tasks).");
|
||||
if (hits.length > 1) fail(EXIT.REFUSED, "duplicate-task", `Task ${id} appears ${hits.length} times in ${file} (lines ${hits.map((t) => t.line).join(", ")}); ticking one would be a guess.`, "Renumber the duplicate, then rerun.");
|
||||
const task = hits[0];
|
||||
const changes = [];
|
||||
if (task.state !== "complete") {
|
||||
const lines = text.split(/\r?\n/);
|
||||
const idx = task.line - 1;
|
||||
lines[idx] = lines[idx].replace(/\[(.)\]/, "[x]");
|
||||
const indent = `${(lines[idx].match(/^\s*/) || [""])[0]} `;
|
||||
lines.splice(taskBody(lines, idx), 0, `${indent}> Confirmed done by the user on ${isoDate()}.`);
|
||||
changes.push({ file: `${spec.rel}/${file}`, line: task.line, from: `[${task.marker}]`, to: "[x]" });
|
||||
if (!args["dry-run"]) fs.writeFileSync(phasePath, lines.join(eol(text)));
|
||||
}
|
||||
const after = args["dry-run"] ? null : specStatus(spec);
|
||||
out({
|
||||
ok: true,
|
||||
spec: spec.rel,
|
||||
task: id,
|
||||
phase: number,
|
||||
dryRun: !!args["dry-run"],
|
||||
changed: changes.length > 0,
|
||||
changes,
|
||||
...(after ? { remaining: after.next.action === "checkoff" ? after.next.tasks.map((t) => t.id) : [], next: after.next.action } : {}),
|
||||
});
|
||||
}
|
||||
|
||||
function listRel(dir, base = dir) {
|
||||
const outList = [];
|
||||
for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
|
||||
@@ -668,9 +753,9 @@ async function cmdArchive(args) {
|
||||
}
|
||||
|
||||
run(USAGE, async (argv) => {
|
||||
const args = parseArgs(argv, { booleans: ["dry-run"], values: ["root", "step", "phase", "to"], lists: ["set"] });
|
||||
const args = parseArgs(argv, { booleans: ["dry-run"], values: ["root", "step", "phase", "to", "task"], 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.");
|
||||
const commands = { list: cmdList, status: cmdStatus, metrics: cmdMetrics, mark: cmdMark, tick: cmdTick, archive: cmdArchive };
|
||||
if (!commands[cmd]) fail(EXIT.USAGE, "unknown-command", cmd ? `Unknown command "${cmd}".` : "No command given.", "Commands: list, status, metrics, mark, tick, archive. Run with --help.");
|
||||
await commands[cmd](args);
|
||||
});
|
||||
@@ -139,6 +139,31 @@ own (`building-review.md`).
|
||||
|
||||
---
|
||||
|
||||
## Manual check-off (`next.action` is `checkoff`)
|
||||
|
||||
No phase to build: the open tasks under approved phases are asked about one
|
||||
at a time, one `confirm` item each, posted with `--wait`:
|
||||
|
||||
```jsonc
|
||||
{
|
||||
"headline": { "stage": "Manual check-off", "cleared": 0, "total": 2 },
|
||||
"items": [{
|
||||
"id": "checkoff-3.4", "kind": "confirm", "title": "Task 3.4",
|
||||
"body": "**Configure the SSO app in Okta**\n\nBLOCKED: needs admin access. User action: create the app and paste its client id into `.env`.\n\nIs this done?",
|
||||
"yesLabel": "Done, check it off", "noLabel": "Not yet"
|
||||
}]
|
||||
}
|
||||
```
|
||||
|
||||
`yes` → `specs.mjs tick`, then `"headline": { "cleared": N }` with the next
|
||||
item. When the last one is answered, post the finish: `command` is
|
||||
`/plan2code-4-finalize specs/<feature>/overview.md` when `tick` said
|
||||
`remaining` is empty, otherwise the same `/plan2code-3-implement` command,
|
||||
and `body` lists what is still open. No `run` (nothing was built), no
|
||||
`commit` unless a body prints one.
|
||||
|
||||
---
|
||||
|
||||
## Implement + Review (`implement-review`)
|
||||
|
||||
The same build, then Stage 2 publishes the findings exactly as
|
||||
|
||||
+2
-2
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "Plan2Code",
|
||||
"version": "2.7.0",
|
||||
"version": "2.7.1",
|
||||
"description": "A structured 4-step workflow methodology for AI-assisted software development",
|
||||
"keywords": [
|
||||
"ai",
|
||||
@@ -17,6 +17,6 @@
|
||||
"url": "https://github.com/jparkerweb/plan2code"
|
||||
},
|
||||
"homepage": "https://github.com/jparkerweb/plan2code",
|
||||
"releaseDate": "2026-10-11",
|
||||
"releaseDate": "2026-10-12",
|
||||
"mode": "utility"
|
||||
}
|
||||
Reference in new issue
Block a user