mirror of
https://github.com/jparkerweb/plan2code.git
synced 2026-11-17 04:45:33 -08:00
Port upstream skill scripts into v2.4.1: deterministic workflow steps run as Node scripts beside each SKILL.md (specs, pathfinder, feedback payload, commit message, review scope, agent files, handoff path) with tests, the prompt limit rises to 20,000 chars, upstream review fixes are folded in (linked agent files never overwrite AGENTS.md, review stops with no base, paste-safe commit commands, Pathfinder number high-water mark and dry runs), and web console workspace folders are remembered per project and spec, with Finalize forgetting an archived spec's list
AI Assisted
This commit is contained in:
1 parent
c0ea70e838
commit
6a66440095
243 files changed
+23698
-1607
No files matched your search
@@ -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, "<");
|
||||
// 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.");
|
||||
});
|
||||
Reference in new issue
Block a user