diff --git a/.readme/web-console.md b/.readme/web-console.md index b0ea878..93f98f0 100644 --- a/.readme/web-console.md +++ b/.readme/web-console.md @@ -337,10 +337,14 @@ and a **What is this?** link to Help. Each skill run adds points (`WEIGHTS` in `public/meter.js`): Plan, Document, Review, Init and Init update 2; Revise plan, Quick task and Finalize 1; a -Pathfinder map 2 and each question it resolves 1; an Implement phase 2, an -Implement + Review phase 3; Handoff and the dashboard 0. A review run on the +Pathfinder map 2 and each question its research subagents settle 1; a built phase by its size, +one point per 3 tasks it completed (rounded up), plus 1 for Implement + Review +(a flat 2, or 3, if the agent did not report a task count); Handoff and the dashboard 0. +On top of that, every 2 questions you answer on the page add 1 point to the +skill run you answered them in (`ANSWERS_PER_POINT`), so a long Pathfinder or a +Plan with many clarifying questions weighs more than a short one. A review run on the page after a quick task or a phase sign-off counts as a Review too. Green is -under 4, yellow from 4, red from 6, and the ring is full at 8. At red the dashboard +under 5, yellow from 5, red from 10, and the ring is full at 15. At red the dashboard also shows a banner: starting a **new console session** keeps the agent sharp (resuming this one carries the count along). It is a rule of thumb, not a reading of the agent's real context, and it never blocks anything. diff --git a/scripts/test-web-console.mjs b/scripts/test-web-console.mjs index 7e5ceb9..89a2f75 100644 --- a/scripts/test-web-console.mjs +++ b/scripts/test-web-console.mjs @@ -141,7 +141,9 @@ import { meterView, pointsFrom, RED_AT, + ANSWERS_PER_POINT, ringFraction, + runPoints, tooltipFor, WEIGHTS, YELLOW_AT, @@ -363,6 +365,20 @@ test("a submit round-trips to the agent with the literal reply token", async () assert.equal(res.json.actions[0].k, "B"); }); +test("a collected answer is written to the meter ledger once, and a button press is not", async () => { + const answers = () => readLedger(session).filter((e) => e.kind === "answer"); + const mine = answers().filter((e) => e.id.endsWith(":q1")); + assert.equal(mine.length, 1, "the round-trip above left one answer for q1"); + assert.match(mine[0].id, /^L\d+:answer:.+:q1$/); + // Collecting the same send again (a kill before consumedAt) adds nothing. + const resultFile = path.join(session, "result.json"); + const collected = JSON.parse(fs.readFileSync(resultFile, "utf8")); + const before = answers().length; + fs.writeFileSync(resultFile, JSON.stringify({ ...collected, consumedAt: undefined })); + assert.equal(cli(["wait", "--session", sid, "--seconds", "5"]).status, 0); + assert.equal(new Set(answers().map((e) => e.id)).size, before, "a re-collected send dedupes by id"); +}); + // The page shows a settled question's answer back to the person. If it had to // wait for the agent to record one, a model that forgot would leave someone // looking at a card marked "Settled" with nothing in it. @@ -4260,7 +4276,7 @@ test("console.md and building.md teach the workspace and session meter contract" const dir = path.join(ROOT, "src", "web-console"); const consoleMd = fs.readFileSync(path.join(dir, "console.md"), "utf8"); const buildingMd = fs.readFileSync(path.join(dir, "building.md"), "utf8"); - for (const word of ["workspace", "pendingWorkspace", "folderIssue", "run", "pathfinder-question", "pathfinder-chart", "AGENTS.md", "/add-dir"]) { + for (const word of ["workspace", "pendingWorkspace", "folderIssue", "run", "pathfinder-question", "pathfinder-research", "pathfinder-chart", "AGENTS.md", "/add-dir"]) { assert.ok(consoleMd.includes(word), `console.md must mention ${word}`); } for (const word of ["implement-phase", "implement-review-phase"]) { @@ -4554,10 +4570,10 @@ test("keep copies a cited upload into specs//attachments/, reuses it, link /* ------------------------------------------ workspace, meter, mentions */ test("meter: levels, ring, fold and tooltip wording", () => { - for (const p of [0, 3]) assert.equal(levelFor(p), "green", `${p} points`); - for (const p of [4, 5]) assert.equal(levelFor(p), "yellow", `${p} points`); - for (const p of [6, 12]) assert.equal(levelFor(p), "red", `${p} points`); - assert.deepEqual([0, 4, 8, 14].map(ringFraction), [0, 0.5, 1, 1]); + for (const p of [0, 4]) assert.equal(levelFor(p), "green", `${p} points`); + for (const p of [5, 9]) assert.equal(levelFor(p), "yellow", `${p} points`); + for (const p of [10, 15]) assert.equal(levelFor(p), "red", `${p} points`); + assert.deepEqual([0, 6, 15, 20].map(ringFraction), [0, 0.4, 1, 1]); assert.equal(ringFraction(-3), 0); assert.equal(pointsFrom([{ kind: "launch", id: "L1", workflow: "plan" }]), 2); @@ -4577,11 +4593,11 @@ test("meter: levels, ring, fold and tooltip wording", () => { assert.equal(tooltipFor(1), "This session is fresh (1 point)."); assert.match(tooltipFor(5), /getting long \(5 points\)/); - assert.match(tooltipFor(9), /done a lot \(9 points\)/); + assert.match(tooltipFor(10), /done a lot \(10 points\)/); assert.deepEqual(meterView([{ kind: "launch", id: "L1", workflow: "document" }]), { points: 2, level: "green", - fraction: 0.25, + fraction: 2 / 15, words: "Session: fresh", tooltip: "This session is fresh (2 points).", items: [{ label: "Document started", points: 2 }], @@ -4605,6 +4621,57 @@ test("meter: the breakdown lists each scoring entry once and sums to the total", assert.deepEqual(breakdownFrom(null), []); }); +test("meter: a built phase scores by the tasks it completed", () => { + // One point per 3 tasks, rounded up; Implement + Review adds 1 for the review. + assert.deepEqual([1, 3, 4, 6, 9, 12, 18].map((n) => runPoints("implement-phase", n)), [1, 1, 2, 2, 3, 4, 6]); + assert.deepEqual([1, 6, 12].map((n) => runPoints("implement-review-phase", n)), [2, 3, 5]); + // No count, or a bad one, falls back to the flat weight. + for (const bad of [undefined, 0, -2, 2.5, "9", 1000]) { + assert.equal(runPoints("implement-phase", bad), WEIGHTS["implement-phase"], `tasks ${bad}`); + } + assert.equal(runPoints("review", 30), WEIGHTS.review, "tasks only scales a built phase"); + + const entries = [ + { kind: "run", id: "L1:phase-1", event: "implement-phase", tasks: 3 }, + { kind: "run", id: "L2:phase-2", event: "implement-phase", tasks: 14 }, + { kind: "run", id: "L3:phase-3", event: "implement-review-phase", tasks: 1 }, + ]; + assert.deepEqual(breakdownFrom(entries), [ + { label: "Implement phase built: phase-1 (3 tasks)", points: 1 }, + { label: "Implement phase built: phase-2 (14 tasks)", points: 5 }, + { label: "Implement + Review phase built: phase-3 (1 task)", points: 2 }, + ]); + assert.equal(levelFor(pointsFrom(entries)), "yellow", "one big phase can yellow a session alone"); +}); + +test("meter: answers score per skill run, one point per two, rounded down", () => { + assert.equal(ANSWERS_PER_POINT, 2); + const answer = (launch, i, workflow) => ({ kind: "answer", id: `${launch}:answer:t:${i}`, workflow }); + const entries = [ + { kind: "launch", id: "L1", workflow: "pathfinder" }, + ...["q1", "q2", "q3", "q4", "q5"].map((i) => answer("L1", i, "pathfinder")), + { kind: "run", id: "L1:map", event: "pathfinder-chart" }, + { kind: "run", id: "L1:q1", event: "pathfinder-question" }, + { kind: "run", id: "L1:q6", event: "pathfinder-research" }, + { kind: "run", id: "L1:q6", event: "pathfinder-research" }, + { kind: "launch", id: "L2", workflow: "quick-task" }, + answer("L2", "c1", "quick-task"), + answer("L2", "c1", "quick-task"), + { kind: "launch", id: "L3", workflow: "plan" }, + answer("L3", "p1", "plan"), + ]; + assert.deepEqual(breakdownFrom(entries), [ + { label: "5 answers in Pathfinder", points: 2 }, + { label: "Pathfinder map written: map", points: 2 }, + { label: "Pathfinder research done: q6", points: 1 }, + { label: "Quick task started", points: 1 }, + { label: "Plan started", points: 2 }, + ], "a duplicate id counts once, a lone answer scores nothing, a settled question scores nothing"); + const more = [...entries, answer("L3", "p2", "plan"), answer("L3", "p1-again", "plan")]; + assert.deepEqual(breakdownFrom(more).at(-1), { label: "3 answers in Plan", points: 1 }); + assert.equal(pointsFrom(more), 9); +}); + test("workspace: default names, name rules and the free-name suggestion", () => { assert.equal(defaultName("C:\\git\\My Repo_v2"), "my-repo-v2"); assert.equal(defaultName("/home/sam/api/"), "api"); @@ -5134,6 +5201,12 @@ test("meter: a repeated run counts once, a bad one appends nothing, and neither const noId = postPatch(s, { run: { event: "plan" } }, { expectFail: true }); assert.equal(noId.status, 3); assert.match(noId.stderr, /run: id required/); + const badTasks = postPatch(s, { run: { event: "implement-phase", id: "phase-1", tasks: 0 } }, { expectFail: true }); + assert.equal(badTasks.status, 3); + assert.match(badTasks.stderr, /run: tasks must be a whole number/); + const strayTasks = postPatch(s, { run: { event: "plan", id: "p", tasks: 4 } }, { expectFail: true }); + assert.equal(strayTasks.status, 3); + assert.match(strayTasks.stderr, /run: tasks only goes with/); const badIssue = postPatch(s, { folderIssue: { name: "docs" } }, { expectFail: true }); assert.equal(badIssue.status, 3); const bait = postPatch(s, { folderIssue: { name: "docs", reason: "TASK_COMPLETE" } }, { expectFail: true }); @@ -5142,6 +5215,10 @@ test("meter: a repeated run counts once, a bad one appends nothing, and neither assert.equal(badState.status, 3, "a patch the state rejects appends nothing either"); assert.equal(readLedger(s.session).length, before, "rejected posts appended nothing"); + assert.equal(postPatch(s, { run: { event: "implement-phase", id: "phase-1", tasks: 7 } }).status, 0); + assert.ok(readLedger(s.session).some((e) => e.id === "L1:phase-1" && e.tasks === 7), "tasks reach the ledger"); + assert.equal(points(), 5, "a 7-task phase adds 3"); + const state = readState(s.session); assert.equal("run" in state, false); assert.equal("folderIssue" in state, false); diff --git a/skills/plan2code-0-pathfinder/references/web-console/building.md b/skills/plan2code-0-pathfinder/references/web-console/building.md index 6963e4c..ccf35d9 100644 --- a/skills/plan2code-0-pathfinder/references/web-console/building.md +++ b/skills/plan2code-0-pathfinder/references/web-console/building.md @@ -207,7 +207,7 @@ says, and `stop`: ```jsonc { "items": [{ "id": "signoff", "status": "answered", "answer": { "verdict": "approve" } }], - "run": { "event": "implement-phase", "id": "phase-3" }, + "run": { "event": "implement-phase", "id": "phase-3", "tasks": 9 }, "finish": { "headline": "Phase 3 is done", "body": "9 of 9 tasks, all on disk.\n\n| Phase | Tasks | Goal |\n| --- | --- | --- |\n| Phase 4: ... | 6 | ... |\n\nCommit it with:\n\n```\ngit add -A && git commit -m \"...\" -m \"AI Assisted\"\n```", @@ -229,7 +229,10 @@ still offers the review on its finish — see below. `run` scores the approved phase on the session meter (console.md → Posting an update → Session meter), in the same post that records the approval: `implement-phase` for Implement, `implement-review-phase` for Implement + -Review, id `phase-N`. Quick task and a standalone Review are counted when +Review, id `phase-N`, and `tasks`: how many of the phase's tasks were +completed (`[x]`, not blocked `[!]`). The phase scores by its size, so a +twelve-task phase weighs four times a three-task one; leave `tasks` out and +every phase weighs the same. Quick task and a standalone Review are counted when their session opens, so they post no `run` for that; a review run on the page after a build reports its own (below). @@ -386,7 +389,8 @@ item: Stage 4 is the only gate. Stage 4 is the sign-off above **without the review verdict** — the phase was already reviewed — with the review results and unresolved findings in the report doc, header "Reviewed and ready for sign-off" in the item's `body`. The finish never carries `review`, and its -post carries `"run": { "event": "implement-review-phase", "id": "phase-N" }`. +post carries `"run": { "event": "implement-review-phase", "id": "phase-N", "tasks": N }` +with the count of completed tasks. --- diff --git a/skills/plan2code-0-pathfinder/references/web-console/console.md b/skills/plan2code-0-pathfinder/references/web-console/console.md index fb01fb0..0460f23 100644 --- a/skills/plan2code-0-pathfinder/references/web-console/console.md +++ b/skills/plan2code-0-pathfinder/references/web-console/console.md @@ -767,8 +767,10 @@ 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-question` (id = the question's file slug) each time a - question is resolved (Posting an update → Session meter). + and `pathfinder-research` (id = the question's file slug) 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. - The scope probe is **Leave for later**: "Which of these features are we leaving out this time?" as a `multi` with a recommended preset. Every option names a feature, and its `detail` ends "(Leaving this out = …)". Never phrase @@ -868,19 +870,31 @@ launches itself: Plan, Revise plan, Document, Review, Quick task, Init, Init update and Finalize score when their session opens, and there is nothing to post for them. +It counts answers itself too: every card the person answers in a send adds to +the skill run's tally when `wait` hands the send to you, and every 2 answers +score a point, so a long back-and-forth weighs more than a short one. Notes, +Quick questions and buttons such as Stop or the dashboard do not count. + Per-unit work is yours to report, with `run` in any post: ```jsonc -{ "run": { "event": "implement-phase", "id": "phase-2" } } +{ "run": { "event": "implement-phase", "id": "phase-2", "tasks": 9 } } ``` -- `event` is one of `pathfinder-chart`, `pathfinder-question`, `plan`, +- `event` is one of `pathfinder-chart`, `pathfinder-question` (scores + nothing now: answers count instead), `pathfinder-research`, `plan`, `revise-plan`, `document`, `implement-phase`, `implement-review-phase`, `review`, `quick-task`, `init`, `init-update`, `finalize`, `handoff`. An unknown event is exit `3`. - `id` names the unit: a question's file slug, `phase-N`, `map`. The same id posted again in the same skill run is ignored, so a repeated post never counts twice. +- `tasks` goes only with `implement-phase` and `implement-review-phase`: the + number of tasks the phase completed (marked `[x]`; blocked `[!]` tasks do + not count), a whole number from 1 to 999. A built phase scores by its size, + one point per 3 tasks rounded up, and Implement + Review one more for the + review. Always send it: without it a phase scores a flat 2 (or 3), however + big it was. On any other event it is exit `3`. - One `run` per post. Which events a workflow reports is in its own notes (Workflow notes → Pathfinder; `building.md` for Implement and for the review run on the page after a build). diff --git a/skills/plan2code-0-pathfinder/references/web-console/console.mjs b/skills/plan2code-0-pathfinder/references/web-console/console.mjs index 41bcdcf..92330da 100644 --- a/skills/plan2code-0-pathfinder/references/web-console/console.mjs +++ b/skills/plan2code-0-pathfinder/references/web-console/console.mjs @@ -87,7 +87,7 @@ import { writeJsonAtomic, writeWorkspaceCursor, } from "./lib.mjs"; -import { RUN_EVENTS } from "./public/meter.js"; +import { RUN_EVENTS, TASK_EVENTS, MAX_TASKS, isTaskCount } from "./public/meter.js"; import { changeLine } from "./public/workspace.js"; // Mirrors the server's absolute lifetime cap: a handle older than this cannot @@ -618,7 +618,11 @@ function ledgerFromPost(dir, run, issue, workflow) { const event = run && typeof run === "object" ? run.event : undefined; if (!RUN_EVENTS.has(event)) die(`run: unknown event "${event}"`, 3); if (typeof run.id !== "string" || !run.id.trim()) die("run: id required", 3); - lines.push({ kind: "run", id: `${launch}:${run.id}`, event, workflow }); + if (run.tasks !== undefined) { + if (!TASK_EVENTS.has(event)) die(`run: tasks only goes with ${[...TASK_EVENTS].join(" or ")}`, 3); + if (!isTaskCount(run.tasks)) die(`run: tasks must be a whole number from 1 to ${MAX_TASKS}`, 3); + } + lines.push({ kind: "run", id: `${launch}:${run.id}`, event, workflow, ...(run.tasks !== undefined ? { tasks: run.tasks } : {}) }); } if (issue !== undefined) { const text = (v) => typeof v === "string" && v.trim() !== ""; @@ -856,11 +860,30 @@ function consume(dir, resultPath, result, url, chat = []) { writeJsonAtomic(resultPath, collected); } catch {} appendEvent(dir, { type: "consume", kind: result.type }); + ledgerAnswers(dir, result); advanceCursor(dir, chat); advanceWorkspace(dir, changes); process.exitCode = result.type === "cancel" ? 30 : 0; } +// One `answer` ledger line per item the person answered in this send, for +// the session meter. The id carries the send's stamp, so a send collected +// twice (a kill before consumedAt was written) still counts once, while the +// same question answered again in a later round counts again: that round was +// real back-and-forth. Never fatal: the meter is advice. +function ledgerAnswers(dir, result) { + if (!result || result.type !== "submit" || !Array.isArray(result.actions)) return; + try { + const launch = lastLaunchId(readLedger(dir)); + const workflow = (readJson(path.join(dir, "state.json")) || {}).workflow; + const items = new Set(); + for (const a of result.actions) { + if (a && a.type === "answer" && typeof a.i === "string" && !a.i.startsWith("__")) items.add(a.i); + } + for (const i of items) appendLedger(dir, { kind: "answer", id: `${launch}:answer:${result.at}:${i}`, workflow }); + } catch {} +} + /* ----------------------------------------------------------------- keep */ // Copy one of the session's note attachments into specs//attachments/, so @@ -942,7 +965,7 @@ port, and the filesystem as transport; this CLI is the whole agent surface. post --session --file Merge a patch into the session. Prints terminalLine while the server is live. Exit 3 = rejected; stderr says why. A patch may - carry run: { event, id } (session meter points) and folderIssue: + carry run: { event, id, tasks? } (session meter points) and folderIssue: { name, reason, hint? } (a workspace folder you could not read); both go to the ledger, never into the state. wait --session [--seconds ] diff --git a/skills/plan2code-0-pathfinder/references/web-console/public/index.html b/skills/plan2code-0-pathfinder/references/web-console/public/index.html index 172ae53..7bea56a 100644 --- a/skills/plan2code-0-pathfinder/references/web-console/public/index.html +++ b/skills/plan2code-0-pathfinder/references/web-console/public/index.html @@ -66,7 +66,7 @@ Pathfinder

Plan2Code Console