Scale the web console session meter with the work done: built phases score one point per 3 completed tasks (reported as run.tasks), every 2 answered questions add a point to their skill run, each Pathfinder research question adds 1 via the new pathfinder-research event, and thresholds move to yellow at 5, red at 10, ring full at 15

This commit is contained in:
jparkerweb committed 2026-10-03 22:31:14 -07:00
1 parent d49f2d5792
commit 6b93bcb4c5
72 files changed
+2121 -346

No files matched your search

+7 -3
View File
@@ -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.
+84 -7
View File
@@ -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/<idea>/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);
@@ -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.
---
@@ -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).
@@ -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/<idea>/attachments/, so
@@ -942,7 +965,7 @@ port, and the filesystem as transport; this CLI is the whole agent surface.
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
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 <sid> [--seconds <N>]
@@ -66,7 +66,7 @@
<span class="badge" id="badge">Pathfinder</span>
<h1 id="title">Plan2Code Console</h1>
<!-- The session meter: how much this console session has done. The
ring fills with the points (full at 8); the colour is the
ring fills with the points (full at 15); the colour is the
level. Hidden until a frame carries `meter`. -->
<span class="meter-slot">
<button
@@ -1347,16 +1347,16 @@
<ul>
<li>
<strong>Green, "Session: fresh".</strong> Under
<span data-fact="meterYellow">4</span> points. Carry on.
<span data-fact="meterYellow">5</span> points. Carry on.
</li>
<li>
<strong>Yellow, "Session: getting long".</strong> From
<span data-fact="meterYellow">4</span> points. Fine for now; think
<span data-fact="meterYellow">5</span> points. Fine for now; think
about a fresh start after this step.
</li>
<li>
<strong>Red, "Session: time for a fresh start".</strong> From
<span data-fact="meterRed">6</span> points. The dashboard also says so
<span data-fact="meterRed">10</span> points. The dashboard also says so
in a banner.
</li>
</ul>
@@ -1364,7 +1364,9 @@
<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. Click the ring to see the count and a list of each step that added
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
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
miss things, and the ring is there to remind you.
@@ -9,7 +9,11 @@
// The one place the weights live (FR-12). Tune here.
export const WEIGHTS = Object.freeze({
"pathfinder-chart": 2,
"pathfinder-question": 1,
// Scores 0: a Pathfinder question now counts through its answers (below).
"pathfinder-question": 0,
// Research reads sources and hands its findings back into the context, with
// nobody answering anything, so each research question scores on its own.
"pathfinder-research": 1,
plan: 2,
"revise-plan": 1,
document: 2,
@@ -30,10 +34,63 @@ export const LAUNCH_COUNTED = Object.freeze(
new Set(["plan", "revise-plan", "document", "review", "quick-task", "init", "init-update", "finalize"])
);
const weightOf = (key) => (Object.prototype.hasOwnProperty.call(WEIGHTS, key) ? WEIGHTS[key] : 0);
// The event names an agent may report in `run`.
export const RUN_EVENTS = new Set(Object.keys(WEIGHTS));
const weightOf = (key) => (Object.prototype.hasOwnProperty.call(WEIGHTS, key) ? WEIGHTS[key] : 0);
// Built phases weigh what they did: a `run` for one of these may carry
// `tasks`, the tasks the phase completed, and then scores one point per
// TASKS_PER_POINT tasks (rounded up, at least 1), plus the event's
// TASK_BONUS for work every phase does whatever its size (the review). A
// run without `tasks` falls back to WEIGHTS. Tune here.
export const TASKS_PER_POINT = 3;
export const TASK_BONUS = Object.freeze({
"implement-phase": 0,
"implement-review-phase": 1,
});
export const TASK_EVENTS = Object.freeze(new Set(Object.keys(TASK_BONUS)));
// The most tasks one run may report: past this it is a typo, not a phase.
export const MAX_TASKS = 999;
/** A valid `run.tasks`: a whole number from 1 to MAX_TASKS. */
export function isTaskCount(tasks) {
return Number.isInteger(tasks) && tasks >= 1 && tasks <= MAX_TASKS;
}
/** What one `run` scores, from its event and (for a built phase) its tasks. */
export function runPoints(event, tasks) {
if (TASK_EVENTS.has(event) && isTaskCount(tasks)) {
return Math.ceil(tasks / TASKS_PER_POINT) + TASK_BONUS[event];
}
return weightOf(event);
}
// Back-and-forth weighs what it took: every answer the person sends from a
// card is an `answer` ledger entry (console.mjs writes one per answered item
// when the agent collects a send), and each skill run scores one point per
// ANSWERS_PER_POINT answers, rounded down. Tune here.
export const ANSWERS_PER_POINT = 2;
// The skill names the answers row uses ("7 answers in Plan").
const WORKFLOW_NAMES = Object.freeze({
dashboard: "the dashboard",
pathfinder: "Pathfinder",
plan: "Plan",
"revise-plan": "Revise plan",
document: "Document",
implement: "Implement",
"implement-review": "Implement + Review",
review: "Review",
"quick-task": "Quick task",
init: "Init",
"init-update": "Init update",
finalize: "Finalize",
handoff: "Handoff",
});
// The skill run an entry belongs to, from its ledger id ("L3:..." -> "L3").
const launchOf = (id) => (typeof id === "string" && id.includes(":") ? id.slice(0, id.indexOf(":")) : "L0");
// What each scoring event is called in the meter's list of contributions.
const LAUNCH_LABELS = Object.freeze({
@@ -49,6 +106,7 @@ const LAUNCH_LABELS = Object.freeze({
const RUN_LABELS = Object.freeze({
"pathfinder-chart": "Pathfinder map written",
"pathfinder-question": "Pathfinder question settled",
"pathfinder-research": "Pathfinder research done",
plan: "Plan drafted",
"revise-plan": "Plan revised",
document: "Spec documented",
@@ -67,31 +125,51 @@ const unitOf = (id) => (typeof id === "string" && id.includes(":") ? id.slice(id
/**
* What the count is made of: one { label, points } per ledger entry that
* scored, in order. An id seen before is skipped, so a repeated `post` never
* scored, in order, and one row per skill run for its answers, where its
* first answer came. An id seen before is skipped, so a repeated `post` never
* counts twice. Entries that weigh nothing are left out.
*/
export function breakdownFrom(entries) {
const seen = new Set();
const rows = [];
const answers = new Map(); // launch id -> { row, count, workflow }
for (const entry of Array.isArray(entries) ? entries : []) {
if (!entry || typeof entry !== "object") continue;
if (entry.id !== undefined) {
if (seen.has(entry.id)) continue;
seen.add(entry.id);
}
if (entry.kind === "answer") {
const launch = launchOf(entry.id);
let tally = answers.get(launch);
if (!tally) {
tally = { row: { label: "", points: 0 }, count: 0, workflow: entry.workflow };
answers.set(launch, tally);
rows.push(tally.row);
}
tally.count += 1;
continue;
}
let points = 0;
let label = "";
if (entry.kind === "launch" && LAUNCH_COUNTED.has(entry.workflow)) {
points = weightOf(entry.workflow);
label = LAUNCH_LABELS[entry.workflow] || entry.workflow;
} else if (entry.kind === "run") {
points = weightOf(entry.event);
points = runPoints(entry.event, entry.tasks);
const unit = unitOf(entry.id);
label = (RUN_LABELS[entry.event] || entry.event) + (unit ? `: ${unit}` : "");
const counted = TASK_EVENTS.has(entry.event) && isTaskCount(entry.tasks);
const size = counted ? ` (${entry.tasks} ${entry.tasks === 1 ? "task" : "tasks"})` : "";
label = (RUN_LABELS[entry.event] || entry.event) + (unit ? `: ${unit}` : "") + size;
}
if (points > 0) rows.push({ label, points });
}
return rows;
for (const { row, count, workflow } of answers.values()) {
row.points = Math.floor(count / ANSWERS_PER_POINT);
const where = WORKFLOW_NAMES[workflow] ? ` in ${WORKFLOW_NAMES[workflow]}` : "";
row.label = `${count} ${count === 1 ? "answer" : "answers"}${where}`;
}
return rows.filter((row) => row.points > 0);
}
/** The session's points, folded from ledger entries in order. */
@@ -99,9 +177,9 @@ export function pointsFrom(entries) {
return breakdownFrom(entries).reduce((sum, row) => sum + row.points, 0);
}
export const YELLOW_AT = 4;
export const RED_AT = 6;
export const RING_FULL = 8;
export const YELLOW_AT = 5;
export const RED_AT = 10;
export const RING_FULL = 15;
export function levelFor(points) {
if (points < YELLOW_AT) return "green";
@@ -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.
---
@@ -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).
@@ -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/<idea>/attachments/, so
@@ -942,7 +965,7 @@ port, and the filesystem as transport; this CLI is the whole agent surface.
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
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 <sid> [--seconds <N>]
@@ -66,7 +66,7 @@
<span class="badge" id="badge">Pathfinder</span>
<h1 id="title">Plan2Code Console</h1>
<!-- The session meter: how much this console session has done. The
ring fills with the points (full at 8); the colour is the
ring fills with the points (full at 15); the colour is the
level. Hidden until a frame carries `meter`. -->
<span class="meter-slot">
<button
@@ -1347,16 +1347,16 @@
<ul>
<li>
<strong>Green, "Session: fresh".</strong> Under
<span data-fact="meterYellow">4</span> points. Carry on.
<span data-fact="meterYellow">5</span> points. Carry on.
</li>
<li>
<strong>Yellow, "Session: getting long".</strong> From
<span data-fact="meterYellow">4</span> points. Fine for now; think
<span data-fact="meterYellow">5</span> points. Fine for now; think
about a fresh start after this step.
</li>
<li>
<strong>Red, "Session: time for a fresh start".</strong> From
<span data-fact="meterRed">6</span> points. The dashboard also says so
<span data-fact="meterRed">10</span> points. The dashboard also says so
in a banner.
</li>
</ul>
@@ -1364,7 +1364,9 @@
<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. Click the ring to see the count and a list of each step that added
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
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
miss things, and the ring is there to remind you.
@@ -9,7 +9,11 @@
// The one place the weights live (FR-12). Tune here.
export const WEIGHTS = Object.freeze({
"pathfinder-chart": 2,
"pathfinder-question": 1,
// Scores 0: a Pathfinder question now counts through its answers (below).
"pathfinder-question": 0,
// Research reads sources and hands its findings back into the context, with
// nobody answering anything, so each research question scores on its own.
"pathfinder-research": 1,
plan: 2,
"revise-plan": 1,
document: 2,
@@ -30,10 +34,63 @@ export const LAUNCH_COUNTED = Object.freeze(
new Set(["plan", "revise-plan", "document", "review", "quick-task", "init", "init-update", "finalize"])
);
const weightOf = (key) => (Object.prototype.hasOwnProperty.call(WEIGHTS, key) ? WEIGHTS[key] : 0);
// The event names an agent may report in `run`.
export const RUN_EVENTS = new Set(Object.keys(WEIGHTS));
const weightOf = (key) => (Object.prototype.hasOwnProperty.call(WEIGHTS, key) ? WEIGHTS[key] : 0);
// Built phases weigh what they did: a `run` for one of these may carry
// `tasks`, the tasks the phase completed, and then scores one point per
// TASKS_PER_POINT tasks (rounded up, at least 1), plus the event's
// TASK_BONUS for work every phase does whatever its size (the review). A
// run without `tasks` falls back to WEIGHTS. Tune here.
export const TASKS_PER_POINT = 3;
export const TASK_BONUS = Object.freeze({
"implement-phase": 0,
"implement-review-phase": 1,
});
export const TASK_EVENTS = Object.freeze(new Set(Object.keys(TASK_BONUS)));
// The most tasks one run may report: past this it is a typo, not a phase.
export const MAX_TASKS = 999;
/** A valid `run.tasks`: a whole number from 1 to MAX_TASKS. */
export function isTaskCount(tasks) {
return Number.isInteger(tasks) && tasks >= 1 && tasks <= MAX_TASKS;
}
/** What one `run` scores, from its event and (for a built phase) its tasks. */
export function runPoints(event, tasks) {
if (TASK_EVENTS.has(event) && isTaskCount(tasks)) {
return Math.ceil(tasks / TASKS_PER_POINT) + TASK_BONUS[event];
}
return weightOf(event);
}
// Back-and-forth weighs what it took: every answer the person sends from a
// card is an `answer` ledger entry (console.mjs writes one per answered item
// when the agent collects a send), and each skill run scores one point per
// ANSWERS_PER_POINT answers, rounded down. Tune here.
export const ANSWERS_PER_POINT = 2;
// The skill names the answers row uses ("7 answers in Plan").
const WORKFLOW_NAMES = Object.freeze({
dashboard: "the dashboard",
pathfinder: "Pathfinder",
plan: "Plan",
"revise-plan": "Revise plan",
document: "Document",
implement: "Implement",
"implement-review": "Implement + Review",
review: "Review",
"quick-task": "Quick task",
init: "Init",
"init-update": "Init update",
finalize: "Finalize",
handoff: "Handoff",
});
// The skill run an entry belongs to, from its ledger id ("L3:..." -> "L3").
const launchOf = (id) => (typeof id === "string" && id.includes(":") ? id.slice(0, id.indexOf(":")) : "L0");
// What each scoring event is called in the meter's list of contributions.
const LAUNCH_LABELS = Object.freeze({
@@ -49,6 +106,7 @@ const LAUNCH_LABELS = Object.freeze({
const RUN_LABELS = Object.freeze({
"pathfinder-chart": "Pathfinder map written",
"pathfinder-question": "Pathfinder question settled",
"pathfinder-research": "Pathfinder research done",
plan: "Plan drafted",
"revise-plan": "Plan revised",
document: "Spec documented",
@@ -67,31 +125,51 @@ const unitOf = (id) => (typeof id === "string" && id.includes(":") ? id.slice(id
/**
* What the count is made of: one { label, points } per ledger entry that
* scored, in order. An id seen before is skipped, so a repeated `post` never
* scored, in order, and one row per skill run for its answers, where its
* first answer came. An id seen before is skipped, so a repeated `post` never
* counts twice. Entries that weigh nothing are left out.
*/
export function breakdownFrom(entries) {
const seen = new Set();
const rows = [];
const answers = new Map(); // launch id -> { row, count, workflow }
for (const entry of Array.isArray(entries) ? entries : []) {
if (!entry || typeof entry !== "object") continue;
if (entry.id !== undefined) {
if (seen.has(entry.id)) continue;
seen.add(entry.id);
}
if (entry.kind === "answer") {
const launch = launchOf(entry.id);
let tally = answers.get(launch);
if (!tally) {
tally = { row: { label: "", points: 0 }, count: 0, workflow: entry.workflow };
answers.set(launch, tally);
rows.push(tally.row);
}
tally.count += 1;
continue;
}
let points = 0;
let label = "";
if (entry.kind === "launch" && LAUNCH_COUNTED.has(entry.workflow)) {
points = weightOf(entry.workflow);
label = LAUNCH_LABELS[entry.workflow] || entry.workflow;
} else if (entry.kind === "run") {
points = weightOf(entry.event);
points = runPoints(entry.event, entry.tasks);
const unit = unitOf(entry.id);
label = (RUN_LABELS[entry.event] || entry.event) + (unit ? `: ${unit}` : "");
const counted = TASK_EVENTS.has(entry.event) && isTaskCount(entry.tasks);
const size = counted ? ` (${entry.tasks} ${entry.tasks === 1 ? "task" : "tasks"})` : "";
label = (RUN_LABELS[entry.event] || entry.event) + (unit ? `: ${unit}` : "") + size;
}
if (points > 0) rows.push({ label, points });
}
return rows;
for (const { row, count, workflow } of answers.values()) {
row.points = Math.floor(count / ANSWERS_PER_POINT);
const where = WORKFLOW_NAMES[workflow] ? ` in ${WORKFLOW_NAMES[workflow]}` : "";
row.label = `${count} ${count === 1 ? "answer" : "answers"}${where}`;
}
return rows.filter((row) => row.points > 0);
}
/** The session's points, folded from ledger entries in order. */
@@ -99,9 +177,9 @@ export function pointsFrom(entries) {
return breakdownFrom(entries).reduce((sum, row) => sum + row.points, 0);
}
export const YELLOW_AT = 4;
export const RED_AT = 6;
export const RING_FULL = 8;
export const YELLOW_AT = 5;
export const RED_AT = 10;
export const RING_FULL = 15;
export function levelFor(points) {
if (points < YELLOW_AT) return "green";
@@ -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.
---
@@ -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).
@@ -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/<idea>/attachments/, so
@@ -942,7 +965,7 @@ port, and the filesystem as transport; this CLI is the whole agent surface.
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
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 <sid> [--seconds <N>]
@@ -66,7 +66,7 @@
<span class="badge" id="badge">Pathfinder</span>
<h1 id="title">Plan2Code Console</h1>
<!-- The session meter: how much this console session has done. The
ring fills with the points (full at 8); the colour is the
ring fills with the points (full at 15); the colour is the
level. Hidden until a frame carries `meter`. -->
<span class="meter-slot">
<button
@@ -1347,16 +1347,16 @@
<ul>
<li>
<strong>Green, "Session: fresh".</strong> Under
<span data-fact="meterYellow">4</span> points. Carry on.
<span data-fact="meterYellow">5</span> points. Carry on.
</li>
<li>
<strong>Yellow, "Session: getting long".</strong> From
<span data-fact="meterYellow">4</span> points. Fine for now; think
<span data-fact="meterYellow">5</span> points. Fine for now; think
about a fresh start after this step.
</li>
<li>
<strong>Red, "Session: time for a fresh start".</strong> From
<span data-fact="meterRed">6</span> points. The dashboard also says so
<span data-fact="meterRed">10</span> points. The dashboard also says so
in a banner.
</li>
</ul>
@@ -1364,7 +1364,9 @@
<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. Click the ring to see the count and a list of each step that added
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
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
miss things, and the ring is there to remind you.
@@ -9,7 +9,11 @@
// The one place the weights live (FR-12). Tune here.
export const WEIGHTS = Object.freeze({
"pathfinder-chart": 2,
"pathfinder-question": 1,
// Scores 0: a Pathfinder question now counts through its answers (below).
"pathfinder-question": 0,
// Research reads sources and hands its findings back into the context, with
// nobody answering anything, so each research question scores on its own.
"pathfinder-research": 1,
plan: 2,
"revise-plan": 1,
document: 2,
@@ -30,10 +34,63 @@ export const LAUNCH_COUNTED = Object.freeze(
new Set(["plan", "revise-plan", "document", "review", "quick-task", "init", "init-update", "finalize"])
);
const weightOf = (key) => (Object.prototype.hasOwnProperty.call(WEIGHTS, key) ? WEIGHTS[key] : 0);
// The event names an agent may report in `run`.
export const RUN_EVENTS = new Set(Object.keys(WEIGHTS));
const weightOf = (key) => (Object.prototype.hasOwnProperty.call(WEIGHTS, key) ? WEIGHTS[key] : 0);
// Built phases weigh what they did: a `run` for one of these may carry
// `tasks`, the tasks the phase completed, and then scores one point per
// TASKS_PER_POINT tasks (rounded up, at least 1), plus the event's
// TASK_BONUS for work every phase does whatever its size (the review). A
// run without `tasks` falls back to WEIGHTS. Tune here.
export const TASKS_PER_POINT = 3;
export const TASK_BONUS = Object.freeze({
"implement-phase": 0,
"implement-review-phase": 1,
});
export const TASK_EVENTS = Object.freeze(new Set(Object.keys(TASK_BONUS)));
// The most tasks one run may report: past this it is a typo, not a phase.
export const MAX_TASKS = 999;
/** A valid `run.tasks`: a whole number from 1 to MAX_TASKS. */
export function isTaskCount(tasks) {
return Number.isInteger(tasks) && tasks >= 1 && tasks <= MAX_TASKS;
}
/** What one `run` scores, from its event and (for a built phase) its tasks. */
export function runPoints(event, tasks) {
if (TASK_EVENTS.has(event) && isTaskCount(tasks)) {
return Math.ceil(tasks / TASKS_PER_POINT) + TASK_BONUS[event];
}
return weightOf(event);
}
// Back-and-forth weighs what it took: every answer the person sends from a
// card is an `answer` ledger entry (console.mjs writes one per answered item
// when the agent collects a send), and each skill run scores one point per
// ANSWERS_PER_POINT answers, rounded down. Tune here.
export const ANSWERS_PER_POINT = 2;
// The skill names the answers row uses ("7 answers in Plan").
const WORKFLOW_NAMES = Object.freeze({
dashboard: "the dashboard",
pathfinder: "Pathfinder",
plan: "Plan",
"revise-plan": "Revise plan",
document: "Document",
implement: "Implement",
"implement-review": "Implement + Review",
review: "Review",
"quick-task": "Quick task",
init: "Init",
"init-update": "Init update",
finalize: "Finalize",
handoff: "Handoff",
});
// The skill run an entry belongs to, from its ledger id ("L3:..." -> "L3").
const launchOf = (id) => (typeof id === "string" && id.includes(":") ? id.slice(0, id.indexOf(":")) : "L0");
// What each scoring event is called in the meter's list of contributions.
const LAUNCH_LABELS = Object.freeze({
@@ -49,6 +106,7 @@ const LAUNCH_LABELS = Object.freeze({
const RUN_LABELS = Object.freeze({
"pathfinder-chart": "Pathfinder map written",
"pathfinder-question": "Pathfinder question settled",
"pathfinder-research": "Pathfinder research done",
plan: "Plan drafted",
"revise-plan": "Plan revised",
document: "Spec documented",
@@ -67,31 +125,51 @@ const unitOf = (id) => (typeof id === "string" && id.includes(":") ? id.slice(id
/**
* What the count is made of: one { label, points } per ledger entry that
* scored, in order. An id seen before is skipped, so a repeated `post` never
* scored, in order, and one row per skill run for its answers, where its
* first answer came. An id seen before is skipped, so a repeated `post` never
* counts twice. Entries that weigh nothing are left out.
*/
export function breakdownFrom(entries) {
const seen = new Set();
const rows = [];
const answers = new Map(); // launch id -> { row, count, workflow }
for (const entry of Array.isArray(entries) ? entries : []) {
if (!entry || typeof entry !== "object") continue;
if (entry.id !== undefined) {
if (seen.has(entry.id)) continue;
seen.add(entry.id);
}
if (entry.kind === "answer") {
const launch = launchOf(entry.id);
let tally = answers.get(launch);
if (!tally) {
tally = { row: { label: "", points: 0 }, count: 0, workflow: entry.workflow };
answers.set(launch, tally);
rows.push(tally.row);
}
tally.count += 1;
continue;
}
let points = 0;
let label = "";
if (entry.kind === "launch" && LAUNCH_COUNTED.has(entry.workflow)) {
points = weightOf(entry.workflow);
label = LAUNCH_LABELS[entry.workflow] || entry.workflow;
} else if (entry.kind === "run") {
points = weightOf(entry.event);
points = runPoints(entry.event, entry.tasks);
const unit = unitOf(entry.id);
label = (RUN_LABELS[entry.event] || entry.event) + (unit ? `: ${unit}` : "");
const counted = TASK_EVENTS.has(entry.event) && isTaskCount(entry.tasks);
const size = counted ? ` (${entry.tasks} ${entry.tasks === 1 ? "task" : "tasks"})` : "";
label = (RUN_LABELS[entry.event] || entry.event) + (unit ? `: ${unit}` : "") + size;
}
if (points > 0) rows.push({ label, points });
}
return rows;
for (const { row, count, workflow } of answers.values()) {
row.points = Math.floor(count / ANSWERS_PER_POINT);
const where = WORKFLOW_NAMES[workflow] ? ` in ${WORKFLOW_NAMES[workflow]}` : "";
row.label = `${count} ${count === 1 ? "answer" : "answers"}${where}`;
}
return rows.filter((row) => row.points > 0);
}
/** The session's points, folded from ledger entries in order. */
@@ -99,9 +177,9 @@ export function pointsFrom(entries) {
return breakdownFrom(entries).reduce((sum, row) => sum + row.points, 0);
}
export const YELLOW_AT = 4;
export const RED_AT = 6;
export const RING_FULL = 8;
export const YELLOW_AT = 5;
export const RED_AT = 10;
export const RING_FULL = 15;
export function levelFor(points) {
if (points < YELLOW_AT) return "green";
@@ -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.
---
@@ -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).
@@ -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/<idea>/attachments/, so
@@ -942,7 +965,7 @@ port, and the filesystem as transport; this CLI is the whole agent surface.
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
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 <sid> [--seconds <N>]
@@ -66,7 +66,7 @@
<span class="badge" id="badge">Pathfinder</span>
<h1 id="title">Plan2Code Console</h1>
<!-- The session meter: how much this console session has done. The
ring fills with the points (full at 8); the colour is the
ring fills with the points (full at 15); the colour is the
level. Hidden until a frame carries `meter`. -->
<span class="meter-slot">
<button
@@ -1347,16 +1347,16 @@
<ul>
<li>
<strong>Green, "Session: fresh".</strong> Under
<span data-fact="meterYellow">4</span> points. Carry on.
<span data-fact="meterYellow">5</span> points. Carry on.
</li>
<li>
<strong>Yellow, "Session: getting long".</strong> From
<span data-fact="meterYellow">4</span> points. Fine for now; think
<span data-fact="meterYellow">5</span> points. Fine for now; think
about a fresh start after this step.
</li>
<li>
<strong>Red, "Session: time for a fresh start".</strong> From
<span data-fact="meterRed">6</span> points. The dashboard also says so
<span data-fact="meterRed">10</span> points. The dashboard also says so
in a banner.
</li>
</ul>
@@ -1364,7 +1364,9 @@
<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. Click the ring to see the count and a list of each step that added
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
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
miss things, and the ring is there to remind you.
@@ -9,7 +9,11 @@
// The one place the weights live (FR-12). Tune here.
export const WEIGHTS = Object.freeze({
"pathfinder-chart": 2,
"pathfinder-question": 1,
// Scores 0: a Pathfinder question now counts through its answers (below).
"pathfinder-question": 0,
// Research reads sources and hands its findings back into the context, with
// nobody answering anything, so each research question scores on its own.
"pathfinder-research": 1,
plan: 2,
"revise-plan": 1,
document: 2,
@@ -30,10 +34,63 @@ export const LAUNCH_COUNTED = Object.freeze(
new Set(["plan", "revise-plan", "document", "review", "quick-task", "init", "init-update", "finalize"])
);
const weightOf = (key) => (Object.prototype.hasOwnProperty.call(WEIGHTS, key) ? WEIGHTS[key] : 0);
// The event names an agent may report in `run`.
export const RUN_EVENTS = new Set(Object.keys(WEIGHTS));
const weightOf = (key) => (Object.prototype.hasOwnProperty.call(WEIGHTS, key) ? WEIGHTS[key] : 0);
// Built phases weigh what they did: a `run` for one of these may carry
// `tasks`, the tasks the phase completed, and then scores one point per
// TASKS_PER_POINT tasks (rounded up, at least 1), plus the event's
// TASK_BONUS for work every phase does whatever its size (the review). A
// run without `tasks` falls back to WEIGHTS. Tune here.
export const TASKS_PER_POINT = 3;
export const TASK_BONUS = Object.freeze({
"implement-phase": 0,
"implement-review-phase": 1,
});
export const TASK_EVENTS = Object.freeze(new Set(Object.keys(TASK_BONUS)));
// The most tasks one run may report: past this it is a typo, not a phase.
export const MAX_TASKS = 999;
/** A valid `run.tasks`: a whole number from 1 to MAX_TASKS. */
export function isTaskCount(tasks) {
return Number.isInteger(tasks) && tasks >= 1 && tasks <= MAX_TASKS;
}
/** What one `run` scores, from its event and (for a built phase) its tasks. */
export function runPoints(event, tasks) {
if (TASK_EVENTS.has(event) && isTaskCount(tasks)) {
return Math.ceil(tasks / TASKS_PER_POINT) + TASK_BONUS[event];
}
return weightOf(event);
}
// Back-and-forth weighs what it took: every answer the person sends from a
// card is an `answer` ledger entry (console.mjs writes one per answered item
// when the agent collects a send), and each skill run scores one point per
// ANSWERS_PER_POINT answers, rounded down. Tune here.
export const ANSWERS_PER_POINT = 2;
// The skill names the answers row uses ("7 answers in Plan").
const WORKFLOW_NAMES = Object.freeze({
dashboard: "the dashboard",
pathfinder: "Pathfinder",
plan: "Plan",
"revise-plan": "Revise plan",
document: "Document",
implement: "Implement",
"implement-review": "Implement + Review",
review: "Review",
"quick-task": "Quick task",
init: "Init",
"init-update": "Init update",
finalize: "Finalize",
handoff: "Handoff",
});
// The skill run an entry belongs to, from its ledger id ("L3:..." -> "L3").
const launchOf = (id) => (typeof id === "string" && id.includes(":") ? id.slice(0, id.indexOf(":")) : "L0");
// What each scoring event is called in the meter's list of contributions.
const LAUNCH_LABELS = Object.freeze({
@@ -49,6 +106,7 @@ const LAUNCH_LABELS = Object.freeze({
const RUN_LABELS = Object.freeze({
"pathfinder-chart": "Pathfinder map written",
"pathfinder-question": "Pathfinder question settled",
"pathfinder-research": "Pathfinder research done",
plan: "Plan drafted",
"revise-plan": "Plan revised",
document: "Spec documented",
@@ -67,31 +125,51 @@ const unitOf = (id) => (typeof id === "string" && id.includes(":") ? id.slice(id
/**
* What the count is made of: one { label, points } per ledger entry that
* scored, in order. An id seen before is skipped, so a repeated `post` never
* scored, in order, and one row per skill run for its answers, where its
* first answer came. An id seen before is skipped, so a repeated `post` never
* counts twice. Entries that weigh nothing are left out.
*/
export function breakdownFrom(entries) {
const seen = new Set();
const rows = [];
const answers = new Map(); // launch id -> { row, count, workflow }
for (const entry of Array.isArray(entries) ? entries : []) {
if (!entry || typeof entry !== "object") continue;
if (entry.id !== undefined) {
if (seen.has(entry.id)) continue;
seen.add(entry.id);
}
if (entry.kind === "answer") {
const launch = launchOf(entry.id);
let tally = answers.get(launch);
if (!tally) {
tally = { row: { label: "", points: 0 }, count: 0, workflow: entry.workflow };
answers.set(launch, tally);
rows.push(tally.row);
}
tally.count += 1;
continue;
}
let points = 0;
let label = "";
if (entry.kind === "launch" && LAUNCH_COUNTED.has(entry.workflow)) {
points = weightOf(entry.workflow);
label = LAUNCH_LABELS[entry.workflow] || entry.workflow;
} else if (entry.kind === "run") {
points = weightOf(entry.event);
points = runPoints(entry.event, entry.tasks);
const unit = unitOf(entry.id);
label = (RUN_LABELS[entry.event] || entry.event) + (unit ? `: ${unit}` : "");
const counted = TASK_EVENTS.has(entry.event) && isTaskCount(entry.tasks);
const size = counted ? ` (${entry.tasks} ${entry.tasks === 1 ? "task" : "tasks"})` : "";
label = (RUN_LABELS[entry.event] || entry.event) + (unit ? `: ${unit}` : "") + size;
}
if (points > 0) rows.push({ label, points });
}
return rows;
for (const { row, count, workflow } of answers.values()) {
row.points = Math.floor(count / ANSWERS_PER_POINT);
const where = WORKFLOW_NAMES[workflow] ? ` in ${WORKFLOW_NAMES[workflow]}` : "";
row.label = `${count} ${count === 1 ? "answer" : "answers"}${where}`;
}
return rows.filter((row) => row.points > 0);
}
/** The session's points, folded from ledger entries in order. */
@@ -99,9 +177,9 @@ export function pointsFrom(entries) {
return breakdownFrom(entries).reduce((sum, row) => sum + row.points, 0);
}
export const YELLOW_AT = 4;
export const RED_AT = 6;
export const RING_FULL = 8;
export const YELLOW_AT = 5;
export const RED_AT = 10;
export const RING_FULL = 15;
export function levelFor(points) {
if (points < YELLOW_AT) return "green";
@@ -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.
---
@@ -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).
@@ -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/<idea>/attachments/, so
@@ -942,7 +965,7 @@ port, and the filesystem as transport; this CLI is the whole agent surface.
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
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 <sid> [--seconds <N>]
@@ -66,7 +66,7 @@
<span class="badge" id="badge">Pathfinder</span>
<h1 id="title">Plan2Code Console</h1>
<!-- The session meter: how much this console session has done. The
ring fills with the points (full at 8); the colour is the
ring fills with the points (full at 15); the colour is the
level. Hidden until a frame carries `meter`. -->
<span class="meter-slot">
<button
@@ -1347,16 +1347,16 @@
<ul>
<li>
<strong>Green, "Session: fresh".</strong> Under
<span data-fact="meterYellow">4</span> points. Carry on.
<span data-fact="meterYellow">5</span> points. Carry on.
</li>
<li>
<strong>Yellow, "Session: getting long".</strong> From
<span data-fact="meterYellow">4</span> points. Fine for now; think
<span data-fact="meterYellow">5</span> points. Fine for now; think
about a fresh start after this step.
</li>
<li>
<strong>Red, "Session: time for a fresh start".</strong> From
<span data-fact="meterRed">6</span> points. The dashboard also says so
<span data-fact="meterRed">10</span> points. The dashboard also says so
in a banner.
</li>
</ul>
@@ -1364,7 +1364,9 @@
<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. Click the ring to see the count and a list of each step that added
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
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
miss things, and the ring is there to remind you.
@@ -9,7 +9,11 @@
// The one place the weights live (FR-12). Tune here.
export const WEIGHTS = Object.freeze({
"pathfinder-chart": 2,
"pathfinder-question": 1,
// Scores 0: a Pathfinder question now counts through its answers (below).
"pathfinder-question": 0,
// Research reads sources and hands its findings back into the context, with
// nobody answering anything, so each research question scores on its own.
"pathfinder-research": 1,
plan: 2,
"revise-plan": 1,
document: 2,
@@ -30,10 +34,63 @@ export const LAUNCH_COUNTED = Object.freeze(
new Set(["plan", "revise-plan", "document", "review", "quick-task", "init", "init-update", "finalize"])
);
const weightOf = (key) => (Object.prototype.hasOwnProperty.call(WEIGHTS, key) ? WEIGHTS[key] : 0);
// The event names an agent may report in `run`.
export const RUN_EVENTS = new Set(Object.keys(WEIGHTS));
const weightOf = (key) => (Object.prototype.hasOwnProperty.call(WEIGHTS, key) ? WEIGHTS[key] : 0);
// Built phases weigh what they did: a `run` for one of these may carry
// `tasks`, the tasks the phase completed, and then scores one point per
// TASKS_PER_POINT tasks (rounded up, at least 1), plus the event's
// TASK_BONUS for work every phase does whatever its size (the review). A
// run without `tasks` falls back to WEIGHTS. Tune here.
export const TASKS_PER_POINT = 3;
export const TASK_BONUS = Object.freeze({
"implement-phase": 0,
"implement-review-phase": 1,
});
export const TASK_EVENTS = Object.freeze(new Set(Object.keys(TASK_BONUS)));
// The most tasks one run may report: past this it is a typo, not a phase.
export const MAX_TASKS = 999;
/** A valid `run.tasks`: a whole number from 1 to MAX_TASKS. */
export function isTaskCount(tasks) {
return Number.isInteger(tasks) && tasks >= 1 && tasks <= MAX_TASKS;
}
/** What one `run` scores, from its event and (for a built phase) its tasks. */
export function runPoints(event, tasks) {
if (TASK_EVENTS.has(event) && isTaskCount(tasks)) {
return Math.ceil(tasks / TASKS_PER_POINT) + TASK_BONUS[event];
}
return weightOf(event);
}
// Back-and-forth weighs what it took: every answer the person sends from a
// card is an `answer` ledger entry (console.mjs writes one per answered item
// when the agent collects a send), and each skill run scores one point per
// ANSWERS_PER_POINT answers, rounded down. Tune here.
export const ANSWERS_PER_POINT = 2;
// The skill names the answers row uses ("7 answers in Plan").
const WORKFLOW_NAMES = Object.freeze({
dashboard: "the dashboard",
pathfinder: "Pathfinder",
plan: "Plan",
"revise-plan": "Revise plan",
document: "Document",
implement: "Implement",
"implement-review": "Implement + Review",
review: "Review",
"quick-task": "Quick task",
init: "Init",
"init-update": "Init update",
finalize: "Finalize",
handoff: "Handoff",
});
// The skill run an entry belongs to, from its ledger id ("L3:..." -> "L3").
const launchOf = (id) => (typeof id === "string" && id.includes(":") ? id.slice(0, id.indexOf(":")) : "L0");
// What each scoring event is called in the meter's list of contributions.
const LAUNCH_LABELS = Object.freeze({
@@ -49,6 +106,7 @@ const LAUNCH_LABELS = Object.freeze({
const RUN_LABELS = Object.freeze({
"pathfinder-chart": "Pathfinder map written",
"pathfinder-question": "Pathfinder question settled",
"pathfinder-research": "Pathfinder research done",
plan: "Plan drafted",
"revise-plan": "Plan revised",
document: "Spec documented",
@@ -67,31 +125,51 @@ const unitOf = (id) => (typeof id === "string" && id.includes(":") ? id.slice(id
/**
* What the count is made of: one { label, points } per ledger entry that
* scored, in order. An id seen before is skipped, so a repeated `post` never
* scored, in order, and one row per skill run for its answers, where its
* first answer came. An id seen before is skipped, so a repeated `post` never
* counts twice. Entries that weigh nothing are left out.
*/
export function breakdownFrom(entries) {
const seen = new Set();
const rows = [];
const answers = new Map(); // launch id -> { row, count, workflow }
for (const entry of Array.isArray(entries) ? entries : []) {
if (!entry || typeof entry !== "object") continue;
if (entry.id !== undefined) {
if (seen.has(entry.id)) continue;
seen.add(entry.id);
}
if (entry.kind === "answer") {
const launch = launchOf(entry.id);
let tally = answers.get(launch);
if (!tally) {
tally = { row: { label: "", points: 0 }, count: 0, workflow: entry.workflow };
answers.set(launch, tally);
rows.push(tally.row);
}
tally.count += 1;
continue;
}
let points = 0;
let label = "";
if (entry.kind === "launch" && LAUNCH_COUNTED.has(entry.workflow)) {
points = weightOf(entry.workflow);
label = LAUNCH_LABELS[entry.workflow] || entry.workflow;
} else if (entry.kind === "run") {
points = weightOf(entry.event);
points = runPoints(entry.event, entry.tasks);
const unit = unitOf(entry.id);
label = (RUN_LABELS[entry.event] || entry.event) + (unit ? `: ${unit}` : "");
const counted = TASK_EVENTS.has(entry.event) && isTaskCount(entry.tasks);
const size = counted ? ` (${entry.tasks} ${entry.tasks === 1 ? "task" : "tasks"})` : "";
label = (RUN_LABELS[entry.event] || entry.event) + (unit ? `: ${unit}` : "") + size;
}
if (points > 0) rows.push({ label, points });
}
return rows;
for (const { row, count, workflow } of answers.values()) {
row.points = Math.floor(count / ANSWERS_PER_POINT);
const where = WORKFLOW_NAMES[workflow] ? ` in ${WORKFLOW_NAMES[workflow]}` : "";
row.label = `${count} ${count === 1 ? "answer" : "answers"}${where}`;
}
return rows.filter((row) => row.points > 0);
}
/** The session's points, folded from ledger entries in order. */
@@ -99,9 +177,9 @@ export function pointsFrom(entries) {
return breakdownFrom(entries).reduce((sum, row) => sum + row.points, 0);
}
export const YELLOW_AT = 4;
export const RED_AT = 6;
export const RING_FULL = 8;
export const YELLOW_AT = 5;
export const RED_AT = 10;
export const RING_FULL = 15;
export function levelFor(points) {
if (points < YELLOW_AT) return "green";
@@ -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.
---
@@ -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).
@@ -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/<idea>/attachments/, so
@@ -942,7 +965,7 @@ port, and the filesystem as transport; this CLI is the whole agent surface.
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
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 <sid> [--seconds <N>]
@@ -66,7 +66,7 @@
<span class="badge" id="badge">Pathfinder</span>
<h1 id="title">Plan2Code Console</h1>
<!-- The session meter: how much this console session has done. The
ring fills with the points (full at 8); the colour is the
ring fills with the points (full at 15); the colour is the
level. Hidden until a frame carries `meter`. -->
<span class="meter-slot">
<button
@@ -1347,16 +1347,16 @@
<ul>
<li>
<strong>Green, "Session: fresh".</strong> Under
<span data-fact="meterYellow">4</span> points. Carry on.
<span data-fact="meterYellow">5</span> points. Carry on.
</li>
<li>
<strong>Yellow, "Session: getting long".</strong> From
<span data-fact="meterYellow">4</span> points. Fine for now; think
<span data-fact="meterYellow">5</span> points. Fine for now; think
about a fresh start after this step.
</li>
<li>
<strong>Red, "Session: time for a fresh start".</strong> From
<span data-fact="meterRed">6</span> points. The dashboard also says so
<span data-fact="meterRed">10</span> points. The dashboard also says so
in a banner.
</li>
</ul>
@@ -1364,7 +1364,9 @@
<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. Click the ring to see the count and a list of each step that added
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
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
miss things, and the ring is there to remind you.
@@ -9,7 +9,11 @@
// The one place the weights live (FR-12). Tune here.
export const WEIGHTS = Object.freeze({
"pathfinder-chart": 2,
"pathfinder-question": 1,
// Scores 0: a Pathfinder question now counts through its answers (below).
"pathfinder-question": 0,
// Research reads sources and hands its findings back into the context, with
// nobody answering anything, so each research question scores on its own.
"pathfinder-research": 1,
plan: 2,
"revise-plan": 1,
document: 2,
@@ -30,10 +34,63 @@ export const LAUNCH_COUNTED = Object.freeze(
new Set(["plan", "revise-plan", "document", "review", "quick-task", "init", "init-update", "finalize"])
);
const weightOf = (key) => (Object.prototype.hasOwnProperty.call(WEIGHTS, key) ? WEIGHTS[key] : 0);
// The event names an agent may report in `run`.
export const RUN_EVENTS = new Set(Object.keys(WEIGHTS));
const weightOf = (key) => (Object.prototype.hasOwnProperty.call(WEIGHTS, key) ? WEIGHTS[key] : 0);
// Built phases weigh what they did: a `run` for one of these may carry
// `tasks`, the tasks the phase completed, and then scores one point per
// TASKS_PER_POINT tasks (rounded up, at least 1), plus the event's
// TASK_BONUS for work every phase does whatever its size (the review). A
// run without `tasks` falls back to WEIGHTS. Tune here.
export const TASKS_PER_POINT = 3;
export const TASK_BONUS = Object.freeze({
"implement-phase": 0,
"implement-review-phase": 1,
});
export const TASK_EVENTS = Object.freeze(new Set(Object.keys(TASK_BONUS)));
// The most tasks one run may report: past this it is a typo, not a phase.
export const MAX_TASKS = 999;
/** A valid `run.tasks`: a whole number from 1 to MAX_TASKS. */
export function isTaskCount(tasks) {
return Number.isInteger(tasks) && tasks >= 1 && tasks <= MAX_TASKS;
}
/** What one `run` scores, from its event and (for a built phase) its tasks. */
export function runPoints(event, tasks) {
if (TASK_EVENTS.has(event) && isTaskCount(tasks)) {
return Math.ceil(tasks / TASKS_PER_POINT) + TASK_BONUS[event];
}
return weightOf(event);
}
// Back-and-forth weighs what it took: every answer the person sends from a
// card is an `answer` ledger entry (console.mjs writes one per answered item
// when the agent collects a send), and each skill run scores one point per
// ANSWERS_PER_POINT answers, rounded down. Tune here.
export const ANSWERS_PER_POINT = 2;
// The skill names the answers row uses ("7 answers in Plan").
const WORKFLOW_NAMES = Object.freeze({
dashboard: "the dashboard",
pathfinder: "Pathfinder",
plan: "Plan",
"revise-plan": "Revise plan",
document: "Document",
implement: "Implement",
"implement-review": "Implement + Review",
review: "Review",
"quick-task": "Quick task",
init: "Init",
"init-update": "Init update",
finalize: "Finalize",
handoff: "Handoff",
});
// The skill run an entry belongs to, from its ledger id ("L3:..." -> "L3").
const launchOf = (id) => (typeof id === "string" && id.includes(":") ? id.slice(0, id.indexOf(":")) : "L0");
// What each scoring event is called in the meter's list of contributions.
const LAUNCH_LABELS = Object.freeze({
@@ -49,6 +106,7 @@ const LAUNCH_LABELS = Object.freeze({
const RUN_LABELS = Object.freeze({
"pathfinder-chart": "Pathfinder map written",
"pathfinder-question": "Pathfinder question settled",
"pathfinder-research": "Pathfinder research done",
plan: "Plan drafted",
"revise-plan": "Plan revised",
document: "Spec documented",
@@ -67,31 +125,51 @@ const unitOf = (id) => (typeof id === "string" && id.includes(":") ? id.slice(id
/**
* What the count is made of: one { label, points } per ledger entry that
* scored, in order. An id seen before is skipped, so a repeated `post` never
* scored, in order, and one row per skill run for its answers, where its
* first answer came. An id seen before is skipped, so a repeated `post` never
* counts twice. Entries that weigh nothing are left out.
*/
export function breakdownFrom(entries) {
const seen = new Set();
const rows = [];
const answers = new Map(); // launch id -> { row, count, workflow }
for (const entry of Array.isArray(entries) ? entries : []) {
if (!entry || typeof entry !== "object") continue;
if (entry.id !== undefined) {
if (seen.has(entry.id)) continue;
seen.add(entry.id);
}
if (entry.kind === "answer") {
const launch = launchOf(entry.id);
let tally = answers.get(launch);
if (!tally) {
tally = { row: { label: "", points: 0 }, count: 0, workflow: entry.workflow };
answers.set(launch, tally);
rows.push(tally.row);
}
tally.count += 1;
continue;
}
let points = 0;
let label = "";
if (entry.kind === "launch" && LAUNCH_COUNTED.has(entry.workflow)) {
points = weightOf(entry.workflow);
label = LAUNCH_LABELS[entry.workflow] || entry.workflow;
} else if (entry.kind === "run") {
points = weightOf(entry.event);
points = runPoints(entry.event, entry.tasks);
const unit = unitOf(entry.id);
label = (RUN_LABELS[entry.event] || entry.event) + (unit ? `: ${unit}` : "");
const counted = TASK_EVENTS.has(entry.event) && isTaskCount(entry.tasks);
const size = counted ? ` (${entry.tasks} ${entry.tasks === 1 ? "task" : "tasks"})` : "";
label = (RUN_LABELS[entry.event] || entry.event) + (unit ? `: ${unit}` : "") + size;
}
if (points > 0) rows.push({ label, points });
}
return rows;
for (const { row, count, workflow } of answers.values()) {
row.points = Math.floor(count / ANSWERS_PER_POINT);
const where = WORKFLOW_NAMES[workflow] ? ` in ${WORKFLOW_NAMES[workflow]}` : "";
row.label = `${count} ${count === 1 ? "answer" : "answers"}${where}`;
}
return rows.filter((row) => row.points > 0);
}
/** The session's points, folded from ledger entries in order. */
@@ -99,9 +177,9 @@ export function pointsFrom(entries) {
return breakdownFrom(entries).reduce((sum, row) => sum + row.points, 0);
}
export const YELLOW_AT = 4;
export const RED_AT = 6;
export const RING_FULL = 8;
export const YELLOW_AT = 5;
export const RED_AT = 10;
export const RING_FULL = 15;
export function levelFor(points) {
if (points < YELLOW_AT) return "green";
@@ -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.
---
@@ -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).
@@ -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/<idea>/attachments/, so
@@ -942,7 +965,7 @@ port, and the filesystem as transport; this CLI is the whole agent surface.
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
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 <sid> [--seconds <N>]
@@ -66,7 +66,7 @@
<span class="badge" id="badge">Pathfinder</span>
<h1 id="title">Plan2Code Console</h1>
<!-- The session meter: how much this console session has done. The
ring fills with the points (full at 8); the colour is the
ring fills with the points (full at 15); the colour is the
level. Hidden until a frame carries `meter`. -->
<span class="meter-slot">
<button
@@ -1347,16 +1347,16 @@
<ul>
<li>
<strong>Green, "Session: fresh".</strong> Under
<span data-fact="meterYellow">4</span> points. Carry on.
<span data-fact="meterYellow">5</span> points. Carry on.
</li>
<li>
<strong>Yellow, "Session: getting long".</strong> From
<span data-fact="meterYellow">4</span> points. Fine for now; think
<span data-fact="meterYellow">5</span> points. Fine for now; think
about a fresh start after this step.
</li>
<li>
<strong>Red, "Session: time for a fresh start".</strong> From
<span data-fact="meterRed">6</span> points. The dashboard also says so
<span data-fact="meterRed">10</span> points. The dashboard also says so
in a banner.
</li>
</ul>
@@ -1364,7 +1364,9 @@
<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. Click the ring to see the count and a list of each step that added
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
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
miss things, and the ring is there to remind you.
@@ -9,7 +9,11 @@
// The one place the weights live (FR-12). Tune here.
export const WEIGHTS = Object.freeze({
"pathfinder-chart": 2,
"pathfinder-question": 1,
// Scores 0: a Pathfinder question now counts through its answers (below).
"pathfinder-question": 0,
// Research reads sources and hands its findings back into the context, with
// nobody answering anything, so each research question scores on its own.
"pathfinder-research": 1,
plan: 2,
"revise-plan": 1,
document: 2,
@@ -30,10 +34,63 @@ export const LAUNCH_COUNTED = Object.freeze(
new Set(["plan", "revise-plan", "document", "review", "quick-task", "init", "init-update", "finalize"])
);
const weightOf = (key) => (Object.prototype.hasOwnProperty.call(WEIGHTS, key) ? WEIGHTS[key] : 0);
// The event names an agent may report in `run`.
export const RUN_EVENTS = new Set(Object.keys(WEIGHTS));
const weightOf = (key) => (Object.prototype.hasOwnProperty.call(WEIGHTS, key) ? WEIGHTS[key] : 0);
// Built phases weigh what they did: a `run` for one of these may carry
// `tasks`, the tasks the phase completed, and then scores one point per
// TASKS_PER_POINT tasks (rounded up, at least 1), plus the event's
// TASK_BONUS for work every phase does whatever its size (the review). A
// run without `tasks` falls back to WEIGHTS. Tune here.
export const TASKS_PER_POINT = 3;
export const TASK_BONUS = Object.freeze({
"implement-phase": 0,
"implement-review-phase": 1,
});
export const TASK_EVENTS = Object.freeze(new Set(Object.keys(TASK_BONUS)));
// The most tasks one run may report: past this it is a typo, not a phase.
export const MAX_TASKS = 999;
/** A valid `run.tasks`: a whole number from 1 to MAX_TASKS. */
export function isTaskCount(tasks) {
return Number.isInteger(tasks) && tasks >= 1 && tasks <= MAX_TASKS;
}
/** What one `run` scores, from its event and (for a built phase) its tasks. */
export function runPoints(event, tasks) {
if (TASK_EVENTS.has(event) && isTaskCount(tasks)) {
return Math.ceil(tasks / TASKS_PER_POINT) + TASK_BONUS[event];
}
return weightOf(event);
}
// Back-and-forth weighs what it took: every answer the person sends from a
// card is an `answer` ledger entry (console.mjs writes one per answered item
// when the agent collects a send), and each skill run scores one point per
// ANSWERS_PER_POINT answers, rounded down. Tune here.
export const ANSWERS_PER_POINT = 2;
// The skill names the answers row uses ("7 answers in Plan").
const WORKFLOW_NAMES = Object.freeze({
dashboard: "the dashboard",
pathfinder: "Pathfinder",
plan: "Plan",
"revise-plan": "Revise plan",
document: "Document",
implement: "Implement",
"implement-review": "Implement + Review",
review: "Review",
"quick-task": "Quick task",
init: "Init",
"init-update": "Init update",
finalize: "Finalize",
handoff: "Handoff",
});
// The skill run an entry belongs to, from its ledger id ("L3:..." -> "L3").
const launchOf = (id) => (typeof id === "string" && id.includes(":") ? id.slice(0, id.indexOf(":")) : "L0");
// What each scoring event is called in the meter's list of contributions.
const LAUNCH_LABELS = Object.freeze({
@@ -49,6 +106,7 @@ const LAUNCH_LABELS = Object.freeze({
const RUN_LABELS = Object.freeze({
"pathfinder-chart": "Pathfinder map written",
"pathfinder-question": "Pathfinder question settled",
"pathfinder-research": "Pathfinder research done",
plan: "Plan drafted",
"revise-plan": "Plan revised",
document: "Spec documented",
@@ -67,31 +125,51 @@ const unitOf = (id) => (typeof id === "string" && id.includes(":") ? id.slice(id
/**
* What the count is made of: one { label, points } per ledger entry that
* scored, in order. An id seen before is skipped, so a repeated `post` never
* scored, in order, and one row per skill run for its answers, where its
* first answer came. An id seen before is skipped, so a repeated `post` never
* counts twice. Entries that weigh nothing are left out.
*/
export function breakdownFrom(entries) {
const seen = new Set();
const rows = [];
const answers = new Map(); // launch id -> { row, count, workflow }
for (const entry of Array.isArray(entries) ? entries : []) {
if (!entry || typeof entry !== "object") continue;
if (entry.id !== undefined) {
if (seen.has(entry.id)) continue;
seen.add(entry.id);
}
if (entry.kind === "answer") {
const launch = launchOf(entry.id);
let tally = answers.get(launch);
if (!tally) {
tally = { row: { label: "", points: 0 }, count: 0, workflow: entry.workflow };
answers.set(launch, tally);
rows.push(tally.row);
}
tally.count += 1;
continue;
}
let points = 0;
let label = "";
if (entry.kind === "launch" && LAUNCH_COUNTED.has(entry.workflow)) {
points = weightOf(entry.workflow);
label = LAUNCH_LABELS[entry.workflow] || entry.workflow;
} else if (entry.kind === "run") {
points = weightOf(entry.event);
points = runPoints(entry.event, entry.tasks);
const unit = unitOf(entry.id);
label = (RUN_LABELS[entry.event] || entry.event) + (unit ? `: ${unit}` : "");
const counted = TASK_EVENTS.has(entry.event) && isTaskCount(entry.tasks);
const size = counted ? ` (${entry.tasks} ${entry.tasks === 1 ? "task" : "tasks"})` : "";
label = (RUN_LABELS[entry.event] || entry.event) + (unit ? `: ${unit}` : "") + size;
}
if (points > 0) rows.push({ label, points });
}
return rows;
for (const { row, count, workflow } of answers.values()) {
row.points = Math.floor(count / ANSWERS_PER_POINT);
const where = WORKFLOW_NAMES[workflow] ? ` in ${WORKFLOW_NAMES[workflow]}` : "";
row.label = `${count} ${count === 1 ? "answer" : "answers"}${where}`;
}
return rows.filter((row) => row.points > 0);
}
/** The session's points, folded from ledger entries in order. */
@@ -99,9 +177,9 @@ export function pointsFrom(entries) {
return breakdownFrom(entries).reduce((sum, row) => sum + row.points, 0);
}
export const YELLOW_AT = 4;
export const RED_AT = 6;
export const RING_FULL = 8;
export const YELLOW_AT = 5;
export const RED_AT = 10;
export const RING_FULL = 15;
export function levelFor(points) {
if (points < YELLOW_AT) return "green";
@@ -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.
---
@@ -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).
@@ -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/<idea>/attachments/, so
@@ -942,7 +965,7 @@ port, and the filesystem as transport; this CLI is the whole agent surface.
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
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 <sid> [--seconds <N>]
@@ -66,7 +66,7 @@
<span class="badge" id="badge">Pathfinder</span>
<h1 id="title">Plan2Code Console</h1>
<!-- The session meter: how much this console session has done. The
ring fills with the points (full at 8); the colour is the
ring fills with the points (full at 15); the colour is the
level. Hidden until a frame carries `meter`. -->
<span class="meter-slot">
<button
@@ -1347,16 +1347,16 @@
<ul>
<li>
<strong>Green, "Session: fresh".</strong> Under
<span data-fact="meterYellow">4</span> points. Carry on.
<span data-fact="meterYellow">5</span> points. Carry on.
</li>
<li>
<strong>Yellow, "Session: getting long".</strong> From
<span data-fact="meterYellow">4</span> points. Fine for now; think
<span data-fact="meterYellow">5</span> points. Fine for now; think
about a fresh start after this step.
</li>
<li>
<strong>Red, "Session: time for a fresh start".</strong> From
<span data-fact="meterRed">6</span> points. The dashboard also says so
<span data-fact="meterRed">10</span> points. The dashboard also says so
in a banner.
</li>
</ul>
@@ -1364,7 +1364,9 @@
<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. Click the ring to see the count and a list of each step that added
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
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
miss things, and the ring is there to remind you.
@@ -9,7 +9,11 @@
// The one place the weights live (FR-12). Tune here.
export const WEIGHTS = Object.freeze({
"pathfinder-chart": 2,
"pathfinder-question": 1,
// Scores 0: a Pathfinder question now counts through its answers (below).
"pathfinder-question": 0,
// Research reads sources and hands its findings back into the context, with
// nobody answering anything, so each research question scores on its own.
"pathfinder-research": 1,
plan: 2,
"revise-plan": 1,
document: 2,
@@ -30,10 +34,63 @@ export const LAUNCH_COUNTED = Object.freeze(
new Set(["plan", "revise-plan", "document", "review", "quick-task", "init", "init-update", "finalize"])
);
const weightOf = (key) => (Object.prototype.hasOwnProperty.call(WEIGHTS, key) ? WEIGHTS[key] : 0);
// The event names an agent may report in `run`.
export const RUN_EVENTS = new Set(Object.keys(WEIGHTS));
const weightOf = (key) => (Object.prototype.hasOwnProperty.call(WEIGHTS, key) ? WEIGHTS[key] : 0);
// Built phases weigh what they did: a `run` for one of these may carry
// `tasks`, the tasks the phase completed, and then scores one point per
// TASKS_PER_POINT tasks (rounded up, at least 1), plus the event's
// TASK_BONUS for work every phase does whatever its size (the review). A
// run without `tasks` falls back to WEIGHTS. Tune here.
export const TASKS_PER_POINT = 3;
export const TASK_BONUS = Object.freeze({
"implement-phase": 0,
"implement-review-phase": 1,
});
export const TASK_EVENTS = Object.freeze(new Set(Object.keys(TASK_BONUS)));
// The most tasks one run may report: past this it is a typo, not a phase.
export const MAX_TASKS = 999;
/** A valid `run.tasks`: a whole number from 1 to MAX_TASKS. */
export function isTaskCount(tasks) {
return Number.isInteger(tasks) && tasks >= 1 && tasks <= MAX_TASKS;
}
/** What one `run` scores, from its event and (for a built phase) its tasks. */
export function runPoints(event, tasks) {
if (TASK_EVENTS.has(event) && isTaskCount(tasks)) {
return Math.ceil(tasks / TASKS_PER_POINT) + TASK_BONUS[event];
}
return weightOf(event);
}
// Back-and-forth weighs what it took: every answer the person sends from a
// card is an `answer` ledger entry (console.mjs writes one per answered item
// when the agent collects a send), and each skill run scores one point per
// ANSWERS_PER_POINT answers, rounded down. Tune here.
export const ANSWERS_PER_POINT = 2;
// The skill names the answers row uses ("7 answers in Plan").
const WORKFLOW_NAMES = Object.freeze({
dashboard: "the dashboard",
pathfinder: "Pathfinder",
plan: "Plan",
"revise-plan": "Revise plan",
document: "Document",
implement: "Implement",
"implement-review": "Implement + Review",
review: "Review",
"quick-task": "Quick task",
init: "Init",
"init-update": "Init update",
finalize: "Finalize",
handoff: "Handoff",
});
// The skill run an entry belongs to, from its ledger id ("L3:..." -> "L3").
const launchOf = (id) => (typeof id === "string" && id.includes(":") ? id.slice(0, id.indexOf(":")) : "L0");
// What each scoring event is called in the meter's list of contributions.
const LAUNCH_LABELS = Object.freeze({
@@ -49,6 +106,7 @@ const LAUNCH_LABELS = Object.freeze({
const RUN_LABELS = Object.freeze({
"pathfinder-chart": "Pathfinder map written",
"pathfinder-question": "Pathfinder question settled",
"pathfinder-research": "Pathfinder research done",
plan: "Plan drafted",
"revise-plan": "Plan revised",
document: "Spec documented",
@@ -67,31 +125,51 @@ const unitOf = (id) => (typeof id === "string" && id.includes(":") ? id.slice(id
/**
* What the count is made of: one { label, points } per ledger entry that
* scored, in order. An id seen before is skipped, so a repeated `post` never
* scored, in order, and one row per skill run for its answers, where its
* first answer came. An id seen before is skipped, so a repeated `post` never
* counts twice. Entries that weigh nothing are left out.
*/
export function breakdownFrom(entries) {
const seen = new Set();
const rows = [];
const answers = new Map(); // launch id -> { row, count, workflow }
for (const entry of Array.isArray(entries) ? entries : []) {
if (!entry || typeof entry !== "object") continue;
if (entry.id !== undefined) {
if (seen.has(entry.id)) continue;
seen.add(entry.id);
}
if (entry.kind === "answer") {
const launch = launchOf(entry.id);
let tally = answers.get(launch);
if (!tally) {
tally = { row: { label: "", points: 0 }, count: 0, workflow: entry.workflow };
answers.set(launch, tally);
rows.push(tally.row);
}
tally.count += 1;
continue;
}
let points = 0;
let label = "";
if (entry.kind === "launch" && LAUNCH_COUNTED.has(entry.workflow)) {
points = weightOf(entry.workflow);
label = LAUNCH_LABELS[entry.workflow] || entry.workflow;
} else if (entry.kind === "run") {
points = weightOf(entry.event);
points = runPoints(entry.event, entry.tasks);
const unit = unitOf(entry.id);
label = (RUN_LABELS[entry.event] || entry.event) + (unit ? `: ${unit}` : "");
const counted = TASK_EVENTS.has(entry.event) && isTaskCount(entry.tasks);
const size = counted ? ` (${entry.tasks} ${entry.tasks === 1 ? "task" : "tasks"})` : "";
label = (RUN_LABELS[entry.event] || entry.event) + (unit ? `: ${unit}` : "") + size;
}
if (points > 0) rows.push({ label, points });
}
return rows;
for (const { row, count, workflow } of answers.values()) {
row.points = Math.floor(count / ANSWERS_PER_POINT);
const where = WORKFLOW_NAMES[workflow] ? ` in ${WORKFLOW_NAMES[workflow]}` : "";
row.label = `${count} ${count === 1 ? "answer" : "answers"}${where}`;
}
return rows.filter((row) => row.points > 0);
}
/** The session's points, folded from ledger entries in order. */
@@ -99,9 +177,9 @@ export function pointsFrom(entries) {
return breakdownFrom(entries).reduce((sum, row) => sum + row.points, 0);
}
export const YELLOW_AT = 4;
export const RED_AT = 6;
export const RING_FULL = 8;
export const YELLOW_AT = 5;
export const RED_AT = 10;
export const RING_FULL = 15;
export function levelFor(points) {
if (points < YELLOW_AT) return "green";
@@ -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.
---
@@ -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).
@@ -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/<idea>/attachments/, so
@@ -942,7 +965,7 @@ port, and the filesystem as transport; this CLI is the whole agent surface.
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
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 <sid> [--seconds <N>]
@@ -66,7 +66,7 @@
<span class="badge" id="badge">Pathfinder</span>
<h1 id="title">Plan2Code Console</h1>
<!-- The session meter: how much this console session has done. The
ring fills with the points (full at 8); the colour is the
ring fills with the points (full at 15); the colour is the
level. Hidden until a frame carries `meter`. -->
<span class="meter-slot">
<button
@@ -1347,16 +1347,16 @@
<ul>
<li>
<strong>Green, "Session: fresh".</strong> Under
<span data-fact="meterYellow">4</span> points. Carry on.
<span data-fact="meterYellow">5</span> points. Carry on.
</li>
<li>
<strong>Yellow, "Session: getting long".</strong> From
<span data-fact="meterYellow">4</span> points. Fine for now; think
<span data-fact="meterYellow">5</span> points. Fine for now; think
about a fresh start after this step.
</li>
<li>
<strong>Red, "Session: time for a fresh start".</strong> From
<span data-fact="meterRed">6</span> points. The dashboard also says so
<span data-fact="meterRed">10</span> points. The dashboard also says so
in a banner.
</li>
</ul>
@@ -1364,7 +1364,9 @@
<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. Click the ring to see the count and a list of each step that added
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
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
miss things, and the ring is there to remind you.
@@ -9,7 +9,11 @@
// The one place the weights live (FR-12). Tune here.
export const WEIGHTS = Object.freeze({
"pathfinder-chart": 2,
"pathfinder-question": 1,
// Scores 0: a Pathfinder question now counts through its answers (below).
"pathfinder-question": 0,
// Research reads sources and hands its findings back into the context, with
// nobody answering anything, so each research question scores on its own.
"pathfinder-research": 1,
plan: 2,
"revise-plan": 1,
document: 2,
@@ -30,10 +34,63 @@ export const LAUNCH_COUNTED = Object.freeze(
new Set(["plan", "revise-plan", "document", "review", "quick-task", "init", "init-update", "finalize"])
);
const weightOf = (key) => (Object.prototype.hasOwnProperty.call(WEIGHTS, key) ? WEIGHTS[key] : 0);
// The event names an agent may report in `run`.
export const RUN_EVENTS = new Set(Object.keys(WEIGHTS));
const weightOf = (key) => (Object.prototype.hasOwnProperty.call(WEIGHTS, key) ? WEIGHTS[key] : 0);
// Built phases weigh what they did: a `run` for one of these may carry
// `tasks`, the tasks the phase completed, and then scores one point per
// TASKS_PER_POINT tasks (rounded up, at least 1), plus the event's
// TASK_BONUS for work every phase does whatever its size (the review). A
// run without `tasks` falls back to WEIGHTS. Tune here.
export const TASKS_PER_POINT = 3;
export const TASK_BONUS = Object.freeze({
"implement-phase": 0,
"implement-review-phase": 1,
});
export const TASK_EVENTS = Object.freeze(new Set(Object.keys(TASK_BONUS)));
// The most tasks one run may report: past this it is a typo, not a phase.
export const MAX_TASKS = 999;
/** A valid `run.tasks`: a whole number from 1 to MAX_TASKS. */
export function isTaskCount(tasks) {
return Number.isInteger(tasks) && tasks >= 1 && tasks <= MAX_TASKS;
}
/** What one `run` scores, from its event and (for a built phase) its tasks. */
export function runPoints(event, tasks) {
if (TASK_EVENTS.has(event) && isTaskCount(tasks)) {
return Math.ceil(tasks / TASKS_PER_POINT) + TASK_BONUS[event];
}
return weightOf(event);
}
// Back-and-forth weighs what it took: every answer the person sends from a
// card is an `answer` ledger entry (console.mjs writes one per answered item
// when the agent collects a send), and each skill run scores one point per
// ANSWERS_PER_POINT answers, rounded down. Tune here.
export const ANSWERS_PER_POINT = 2;
// The skill names the answers row uses ("7 answers in Plan").
const WORKFLOW_NAMES = Object.freeze({
dashboard: "the dashboard",
pathfinder: "Pathfinder",
plan: "Plan",
"revise-plan": "Revise plan",
document: "Document",
implement: "Implement",
"implement-review": "Implement + Review",
review: "Review",
"quick-task": "Quick task",
init: "Init",
"init-update": "Init update",
finalize: "Finalize",
handoff: "Handoff",
});
// The skill run an entry belongs to, from its ledger id ("L3:..." -> "L3").
const launchOf = (id) => (typeof id === "string" && id.includes(":") ? id.slice(0, id.indexOf(":")) : "L0");
// What each scoring event is called in the meter's list of contributions.
const LAUNCH_LABELS = Object.freeze({
@@ -49,6 +106,7 @@ const LAUNCH_LABELS = Object.freeze({
const RUN_LABELS = Object.freeze({
"pathfinder-chart": "Pathfinder map written",
"pathfinder-question": "Pathfinder question settled",
"pathfinder-research": "Pathfinder research done",
plan: "Plan drafted",
"revise-plan": "Plan revised",
document: "Spec documented",
@@ -67,31 +125,51 @@ const unitOf = (id) => (typeof id === "string" && id.includes(":") ? id.slice(id
/**
* What the count is made of: one { label, points } per ledger entry that
* scored, in order. An id seen before is skipped, so a repeated `post` never
* scored, in order, and one row per skill run for its answers, where its
* first answer came. An id seen before is skipped, so a repeated `post` never
* counts twice. Entries that weigh nothing are left out.
*/
export function breakdownFrom(entries) {
const seen = new Set();
const rows = [];
const answers = new Map(); // launch id -> { row, count, workflow }
for (const entry of Array.isArray(entries) ? entries : []) {
if (!entry || typeof entry !== "object") continue;
if (entry.id !== undefined) {
if (seen.has(entry.id)) continue;
seen.add(entry.id);
}
if (entry.kind === "answer") {
const launch = launchOf(entry.id);
let tally = answers.get(launch);
if (!tally) {
tally = { row: { label: "", points: 0 }, count: 0, workflow: entry.workflow };
answers.set(launch, tally);
rows.push(tally.row);
}
tally.count += 1;
continue;
}
let points = 0;
let label = "";
if (entry.kind === "launch" && LAUNCH_COUNTED.has(entry.workflow)) {
points = weightOf(entry.workflow);
label = LAUNCH_LABELS[entry.workflow] || entry.workflow;
} else if (entry.kind === "run") {
points = weightOf(entry.event);
points = runPoints(entry.event, entry.tasks);
const unit = unitOf(entry.id);
label = (RUN_LABELS[entry.event] || entry.event) + (unit ? `: ${unit}` : "");
const counted = TASK_EVENTS.has(entry.event) && isTaskCount(entry.tasks);
const size = counted ? ` (${entry.tasks} ${entry.tasks === 1 ? "task" : "tasks"})` : "";
label = (RUN_LABELS[entry.event] || entry.event) + (unit ? `: ${unit}` : "") + size;
}
if (points > 0) rows.push({ label, points });
}
return rows;
for (const { row, count, workflow } of answers.values()) {
row.points = Math.floor(count / ANSWERS_PER_POINT);
const where = WORKFLOW_NAMES[workflow] ? ` in ${WORKFLOW_NAMES[workflow]}` : "";
row.label = `${count} ${count === 1 ? "answer" : "answers"}${where}`;
}
return rows.filter((row) => row.points > 0);
}
/** The session's points, folded from ledger entries in order. */
@@ -99,9 +177,9 @@ export function pointsFrom(entries) {
return breakdownFrom(entries).reduce((sum, row) => sum + row.points, 0);
}
export const YELLOW_AT = 4;
export const RED_AT = 6;
export const RING_FULL = 8;
export const YELLOW_AT = 5;
export const RED_AT = 10;
export const RING_FULL = 15;
export function levelFor(points) {
if (points < YELLOW_AT) return "green";
@@ -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.
---
@@ -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).
@@ -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/<idea>/attachments/, so
@@ -942,7 +965,7 @@ port, and the filesystem as transport; this CLI is the whole agent surface.
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
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 <sid> [--seconds <N>]
@@ -66,7 +66,7 @@
<span class="badge" id="badge">Pathfinder</span>
<h1 id="title">Plan2Code Console</h1>
<!-- The session meter: how much this console session has done. The
ring fills with the points (full at 8); the colour is the
ring fills with the points (full at 15); the colour is the
level. Hidden until a frame carries `meter`. -->
<span class="meter-slot">
<button
@@ -1347,16 +1347,16 @@
<ul>
<li>
<strong>Green, "Session: fresh".</strong> Under
<span data-fact="meterYellow">4</span> points. Carry on.
<span data-fact="meterYellow">5</span> points. Carry on.
</li>
<li>
<strong>Yellow, "Session: getting long".</strong> From
<span data-fact="meterYellow">4</span> points. Fine for now; think
<span data-fact="meterYellow">5</span> points. Fine for now; think
about a fresh start after this step.
</li>
<li>
<strong>Red, "Session: time for a fresh start".</strong> From
<span data-fact="meterRed">6</span> points. The dashboard also says so
<span data-fact="meterRed">10</span> points. The dashboard also says so
in a banner.
</li>
</ul>
@@ -1364,7 +1364,9 @@
<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. Click the ring to see the count and a list of each step that added
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
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
miss things, and the ring is there to remind you.
@@ -9,7 +9,11 @@
// The one place the weights live (FR-12). Tune here.
export const WEIGHTS = Object.freeze({
"pathfinder-chart": 2,
"pathfinder-question": 1,
// Scores 0: a Pathfinder question now counts through its answers (below).
"pathfinder-question": 0,
// Research reads sources and hands its findings back into the context, with
// nobody answering anything, so each research question scores on its own.
"pathfinder-research": 1,
plan: 2,
"revise-plan": 1,
document: 2,
@@ -30,10 +34,63 @@ export const LAUNCH_COUNTED = Object.freeze(
new Set(["plan", "revise-plan", "document", "review", "quick-task", "init", "init-update", "finalize"])
);
const weightOf = (key) => (Object.prototype.hasOwnProperty.call(WEIGHTS, key) ? WEIGHTS[key] : 0);
// The event names an agent may report in `run`.
export const RUN_EVENTS = new Set(Object.keys(WEIGHTS));
const weightOf = (key) => (Object.prototype.hasOwnProperty.call(WEIGHTS, key) ? WEIGHTS[key] : 0);
// Built phases weigh what they did: a `run` for one of these may carry
// `tasks`, the tasks the phase completed, and then scores one point per
// TASKS_PER_POINT tasks (rounded up, at least 1), plus the event's
// TASK_BONUS for work every phase does whatever its size (the review). A
// run without `tasks` falls back to WEIGHTS. Tune here.
export const TASKS_PER_POINT = 3;
export const TASK_BONUS = Object.freeze({
"implement-phase": 0,
"implement-review-phase": 1,
});
export const TASK_EVENTS = Object.freeze(new Set(Object.keys(TASK_BONUS)));
// The most tasks one run may report: past this it is a typo, not a phase.
export const MAX_TASKS = 999;
/** A valid `run.tasks`: a whole number from 1 to MAX_TASKS. */
export function isTaskCount(tasks) {
return Number.isInteger(tasks) && tasks >= 1 && tasks <= MAX_TASKS;
}
/** What one `run` scores, from its event and (for a built phase) its tasks. */
export function runPoints(event, tasks) {
if (TASK_EVENTS.has(event) && isTaskCount(tasks)) {
return Math.ceil(tasks / TASKS_PER_POINT) + TASK_BONUS[event];
}
return weightOf(event);
}
// Back-and-forth weighs what it took: every answer the person sends from a
// card is an `answer` ledger entry (console.mjs writes one per answered item
// when the agent collects a send), and each skill run scores one point per
// ANSWERS_PER_POINT answers, rounded down. Tune here.
export const ANSWERS_PER_POINT = 2;
// The skill names the answers row uses ("7 answers in Plan").
const WORKFLOW_NAMES = Object.freeze({
dashboard: "the dashboard",
pathfinder: "Pathfinder",
plan: "Plan",
"revise-plan": "Revise plan",
document: "Document",
implement: "Implement",
"implement-review": "Implement + Review",
review: "Review",
"quick-task": "Quick task",
init: "Init",
"init-update": "Init update",
finalize: "Finalize",
handoff: "Handoff",
});
// The skill run an entry belongs to, from its ledger id ("L3:..." -> "L3").
const launchOf = (id) => (typeof id === "string" && id.includes(":") ? id.slice(0, id.indexOf(":")) : "L0");
// What each scoring event is called in the meter's list of contributions.
const LAUNCH_LABELS = Object.freeze({
@@ -49,6 +106,7 @@ const LAUNCH_LABELS = Object.freeze({
const RUN_LABELS = Object.freeze({
"pathfinder-chart": "Pathfinder map written",
"pathfinder-question": "Pathfinder question settled",
"pathfinder-research": "Pathfinder research done",
plan: "Plan drafted",
"revise-plan": "Plan revised",
document: "Spec documented",
@@ -67,31 +125,51 @@ const unitOf = (id) => (typeof id === "string" && id.includes(":") ? id.slice(id
/**
* What the count is made of: one { label, points } per ledger entry that
* scored, in order. An id seen before is skipped, so a repeated `post` never
* scored, in order, and one row per skill run for its answers, where its
* first answer came. An id seen before is skipped, so a repeated `post` never
* counts twice. Entries that weigh nothing are left out.
*/
export function breakdownFrom(entries) {
const seen = new Set();
const rows = [];
const answers = new Map(); // launch id -> { row, count, workflow }
for (const entry of Array.isArray(entries) ? entries : []) {
if (!entry || typeof entry !== "object") continue;
if (entry.id !== undefined) {
if (seen.has(entry.id)) continue;
seen.add(entry.id);
}
if (entry.kind === "answer") {
const launch = launchOf(entry.id);
let tally = answers.get(launch);
if (!tally) {
tally = { row: { label: "", points: 0 }, count: 0, workflow: entry.workflow };
answers.set(launch, tally);
rows.push(tally.row);
}
tally.count += 1;
continue;
}
let points = 0;
let label = "";
if (entry.kind === "launch" && LAUNCH_COUNTED.has(entry.workflow)) {
points = weightOf(entry.workflow);
label = LAUNCH_LABELS[entry.workflow] || entry.workflow;
} else if (entry.kind === "run") {
points = weightOf(entry.event);
points = runPoints(entry.event, entry.tasks);
const unit = unitOf(entry.id);
label = (RUN_LABELS[entry.event] || entry.event) + (unit ? `: ${unit}` : "");
const counted = TASK_EVENTS.has(entry.event) && isTaskCount(entry.tasks);
const size = counted ? ` (${entry.tasks} ${entry.tasks === 1 ? "task" : "tasks"})` : "";
label = (RUN_LABELS[entry.event] || entry.event) + (unit ? `: ${unit}` : "") + size;
}
if (points > 0) rows.push({ label, points });
}
return rows;
for (const { row, count, workflow } of answers.values()) {
row.points = Math.floor(count / ANSWERS_PER_POINT);
const where = WORKFLOW_NAMES[workflow] ? ` in ${WORKFLOW_NAMES[workflow]}` : "";
row.label = `${count} ${count === 1 ? "answer" : "answers"}${where}`;
}
return rows.filter((row) => row.points > 0);
}
/** The session's points, folded from ledger entries in order. */
@@ -99,9 +177,9 @@ export function pointsFrom(entries) {
return breakdownFrom(entries).reduce((sum, row) => sum + row.points, 0);
}
export const YELLOW_AT = 4;
export const RED_AT = 6;
export const RING_FULL = 8;
export const YELLOW_AT = 5;
export const RED_AT = 10;
export const RING_FULL = 15;
export function levelFor(points) {
if (points < YELLOW_AT) return "green";
@@ -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.
---
@@ -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).
@@ -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/<idea>/attachments/, so
@@ -942,7 +965,7 @@ port, and the filesystem as transport; this CLI is the whole agent surface.
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
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 <sid> [--seconds <N>]
@@ -66,7 +66,7 @@
<span class="badge" id="badge">Pathfinder</span>
<h1 id="title">Plan2Code Console</h1>
<!-- The session meter: how much this console session has done. The
ring fills with the points (full at 8); the colour is the
ring fills with the points (full at 15); the colour is the
level. Hidden until a frame carries `meter`. -->
<span class="meter-slot">
<button
@@ -1347,16 +1347,16 @@
<ul>
<li>
<strong>Green, "Session: fresh".</strong> Under
<span data-fact="meterYellow">4</span> points. Carry on.
<span data-fact="meterYellow">5</span> points. Carry on.
</li>
<li>
<strong>Yellow, "Session: getting long".</strong> From
<span data-fact="meterYellow">4</span> points. Fine for now; think
<span data-fact="meterYellow">5</span> points. Fine for now; think
about a fresh start after this step.
</li>
<li>
<strong>Red, "Session: time for a fresh start".</strong> From
<span data-fact="meterRed">6</span> points. The dashboard also says so
<span data-fact="meterRed">10</span> points. The dashboard also says so
in a banner.
</li>
</ul>
@@ -1364,7 +1364,9 @@
<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. Click the ring to see the count and a list of each step that added
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
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
miss things, and the ring is there to remind you.
@@ -9,7 +9,11 @@
// The one place the weights live (FR-12). Tune here.
export const WEIGHTS = Object.freeze({
"pathfinder-chart": 2,
"pathfinder-question": 1,
// Scores 0: a Pathfinder question now counts through its answers (below).
"pathfinder-question": 0,
// Research reads sources and hands its findings back into the context, with
// nobody answering anything, so each research question scores on its own.
"pathfinder-research": 1,
plan: 2,
"revise-plan": 1,
document: 2,
@@ -30,10 +34,63 @@ export const LAUNCH_COUNTED = Object.freeze(
new Set(["plan", "revise-plan", "document", "review", "quick-task", "init", "init-update", "finalize"])
);
const weightOf = (key) => (Object.prototype.hasOwnProperty.call(WEIGHTS, key) ? WEIGHTS[key] : 0);
// The event names an agent may report in `run`.
export const RUN_EVENTS = new Set(Object.keys(WEIGHTS));
const weightOf = (key) => (Object.prototype.hasOwnProperty.call(WEIGHTS, key) ? WEIGHTS[key] : 0);
// Built phases weigh what they did: a `run` for one of these may carry
// `tasks`, the tasks the phase completed, and then scores one point per
// TASKS_PER_POINT tasks (rounded up, at least 1), plus the event's
// TASK_BONUS for work every phase does whatever its size (the review). A
// run without `tasks` falls back to WEIGHTS. Tune here.
export const TASKS_PER_POINT = 3;
export const TASK_BONUS = Object.freeze({
"implement-phase": 0,
"implement-review-phase": 1,
});
export const TASK_EVENTS = Object.freeze(new Set(Object.keys(TASK_BONUS)));
// The most tasks one run may report: past this it is a typo, not a phase.
export const MAX_TASKS = 999;
/** A valid `run.tasks`: a whole number from 1 to MAX_TASKS. */
export function isTaskCount(tasks) {
return Number.isInteger(tasks) && tasks >= 1 && tasks <= MAX_TASKS;
}
/** What one `run` scores, from its event and (for a built phase) its tasks. */
export function runPoints(event, tasks) {
if (TASK_EVENTS.has(event) && isTaskCount(tasks)) {
return Math.ceil(tasks / TASKS_PER_POINT) + TASK_BONUS[event];
}
return weightOf(event);
}
// Back-and-forth weighs what it took: every answer the person sends from a
// card is an `answer` ledger entry (console.mjs writes one per answered item
// when the agent collects a send), and each skill run scores one point per
// ANSWERS_PER_POINT answers, rounded down. Tune here.
export const ANSWERS_PER_POINT = 2;
// The skill names the answers row uses ("7 answers in Plan").
const WORKFLOW_NAMES = Object.freeze({
dashboard: "the dashboard",
pathfinder: "Pathfinder",
plan: "Plan",
"revise-plan": "Revise plan",
document: "Document",
implement: "Implement",
"implement-review": "Implement + Review",
review: "Review",
"quick-task": "Quick task",
init: "Init",
"init-update": "Init update",
finalize: "Finalize",
handoff: "Handoff",
});
// The skill run an entry belongs to, from its ledger id ("L3:..." -> "L3").
const launchOf = (id) => (typeof id === "string" && id.includes(":") ? id.slice(0, id.indexOf(":")) : "L0");
// What each scoring event is called in the meter's list of contributions.
const LAUNCH_LABELS = Object.freeze({
@@ -49,6 +106,7 @@ const LAUNCH_LABELS = Object.freeze({
const RUN_LABELS = Object.freeze({
"pathfinder-chart": "Pathfinder map written",
"pathfinder-question": "Pathfinder question settled",
"pathfinder-research": "Pathfinder research done",
plan: "Plan drafted",
"revise-plan": "Plan revised",
document: "Spec documented",
@@ -67,31 +125,51 @@ const unitOf = (id) => (typeof id === "string" && id.includes(":") ? id.slice(id
/**
* What the count is made of: one { label, points } per ledger entry that
* scored, in order. An id seen before is skipped, so a repeated `post` never
* scored, in order, and one row per skill run for its answers, where its
* first answer came. An id seen before is skipped, so a repeated `post` never
* counts twice. Entries that weigh nothing are left out.
*/
export function breakdownFrom(entries) {
const seen = new Set();
const rows = [];
const answers = new Map(); // launch id -> { row, count, workflow }
for (const entry of Array.isArray(entries) ? entries : []) {
if (!entry || typeof entry !== "object") continue;
if (entry.id !== undefined) {
if (seen.has(entry.id)) continue;
seen.add(entry.id);
}
if (entry.kind === "answer") {
const launch = launchOf(entry.id);
let tally = answers.get(launch);
if (!tally) {
tally = { row: { label: "", points: 0 }, count: 0, workflow: entry.workflow };
answers.set(launch, tally);
rows.push(tally.row);
}
tally.count += 1;
continue;
}
let points = 0;
let label = "";
if (entry.kind === "launch" && LAUNCH_COUNTED.has(entry.workflow)) {
points = weightOf(entry.workflow);
label = LAUNCH_LABELS[entry.workflow] || entry.workflow;
} else if (entry.kind === "run") {
points = weightOf(entry.event);
points = runPoints(entry.event, entry.tasks);
const unit = unitOf(entry.id);
label = (RUN_LABELS[entry.event] || entry.event) + (unit ? `: ${unit}` : "");
const counted = TASK_EVENTS.has(entry.event) && isTaskCount(entry.tasks);
const size = counted ? ` (${entry.tasks} ${entry.tasks === 1 ? "task" : "tasks"})` : "";
label = (RUN_LABELS[entry.event] || entry.event) + (unit ? `: ${unit}` : "") + size;
}
if (points > 0) rows.push({ label, points });
}
return rows;
for (const { row, count, workflow } of answers.values()) {
row.points = Math.floor(count / ANSWERS_PER_POINT);
const where = WORKFLOW_NAMES[workflow] ? ` in ${WORKFLOW_NAMES[workflow]}` : "";
row.label = `${count} ${count === 1 ? "answer" : "answers"}${where}`;
}
return rows.filter((row) => row.points > 0);
}
/** The session's points, folded from ledger entries in order. */
@@ -99,9 +177,9 @@ export function pointsFrom(entries) {
return breakdownFrom(entries).reduce((sum, row) => sum + row.points, 0);
}
export const YELLOW_AT = 4;
export const RED_AT = 6;
export const RING_FULL = 8;
export const YELLOW_AT = 5;
export const RED_AT = 10;
export const RING_FULL = 15;
export function levelFor(points) {
if (points < YELLOW_AT) return "green";
@@ -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.
---
@@ -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).
@@ -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/<idea>/attachments/, so
@@ -942,7 +965,7 @@ port, and the filesystem as transport; this CLI is the whole agent surface.
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
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 <sid> [--seconds <N>]
@@ -66,7 +66,7 @@
<span class="badge" id="badge">Pathfinder</span>
<h1 id="title">Plan2Code Console</h1>
<!-- The session meter: how much this console session has done. The
ring fills with the points (full at 8); the colour is the
ring fills with the points (full at 15); the colour is the
level. Hidden until a frame carries `meter`. -->
<span class="meter-slot">
<button
@@ -1347,16 +1347,16 @@
<ul>
<li>
<strong>Green, "Session: fresh".</strong> Under
<span data-fact="meterYellow">4</span> points. Carry on.
<span data-fact="meterYellow">5</span> points. Carry on.
</li>
<li>
<strong>Yellow, "Session: getting long".</strong> From
<span data-fact="meterYellow">4</span> points. Fine for now; think
<span data-fact="meterYellow">5</span> points. Fine for now; think
about a fresh start after this step.
</li>
<li>
<strong>Red, "Session: time for a fresh start".</strong> From
<span data-fact="meterRed">6</span> points. The dashboard also says so
<span data-fact="meterRed">10</span> points. The dashboard also says so
in a banner.
</li>
</ul>
@@ -1364,7 +1364,9 @@
<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. Click the ring to see the count and a list of each step that added
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
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
miss things, and the ring is there to remind you.
@@ -9,7 +9,11 @@
// The one place the weights live (FR-12). Tune here.
export const WEIGHTS = Object.freeze({
"pathfinder-chart": 2,
"pathfinder-question": 1,
// Scores 0: a Pathfinder question now counts through its answers (below).
"pathfinder-question": 0,
// Research reads sources and hands its findings back into the context, with
// nobody answering anything, so each research question scores on its own.
"pathfinder-research": 1,
plan: 2,
"revise-plan": 1,
document: 2,
@@ -30,10 +34,63 @@ export const LAUNCH_COUNTED = Object.freeze(
new Set(["plan", "revise-plan", "document", "review", "quick-task", "init", "init-update", "finalize"])
);
const weightOf = (key) => (Object.prototype.hasOwnProperty.call(WEIGHTS, key) ? WEIGHTS[key] : 0);
// The event names an agent may report in `run`.
export const RUN_EVENTS = new Set(Object.keys(WEIGHTS));
const weightOf = (key) => (Object.prototype.hasOwnProperty.call(WEIGHTS, key) ? WEIGHTS[key] : 0);
// Built phases weigh what they did: a `run` for one of these may carry
// `tasks`, the tasks the phase completed, and then scores one point per
// TASKS_PER_POINT tasks (rounded up, at least 1), plus the event's
// TASK_BONUS for work every phase does whatever its size (the review). A
// run without `tasks` falls back to WEIGHTS. Tune here.
export const TASKS_PER_POINT = 3;
export const TASK_BONUS = Object.freeze({
"implement-phase": 0,
"implement-review-phase": 1,
});
export const TASK_EVENTS = Object.freeze(new Set(Object.keys(TASK_BONUS)));
// The most tasks one run may report: past this it is a typo, not a phase.
export const MAX_TASKS = 999;
/** A valid `run.tasks`: a whole number from 1 to MAX_TASKS. */
export function isTaskCount(tasks) {
return Number.isInteger(tasks) && tasks >= 1 && tasks <= MAX_TASKS;
}
/** What one `run` scores, from its event and (for a built phase) its tasks. */
export function runPoints(event, tasks) {
if (TASK_EVENTS.has(event) && isTaskCount(tasks)) {
return Math.ceil(tasks / TASKS_PER_POINT) + TASK_BONUS[event];
}
return weightOf(event);
}
// Back-and-forth weighs what it took: every answer the person sends from a
// card is an `answer` ledger entry (console.mjs writes one per answered item
// when the agent collects a send), and each skill run scores one point per
// ANSWERS_PER_POINT answers, rounded down. Tune here.
export const ANSWERS_PER_POINT = 2;
// The skill names the answers row uses ("7 answers in Plan").
const WORKFLOW_NAMES = Object.freeze({
dashboard: "the dashboard",
pathfinder: "Pathfinder",
plan: "Plan",
"revise-plan": "Revise plan",
document: "Document",
implement: "Implement",
"implement-review": "Implement + Review",
review: "Review",
"quick-task": "Quick task",
init: "Init",
"init-update": "Init update",
finalize: "Finalize",
handoff: "Handoff",
});
// The skill run an entry belongs to, from its ledger id ("L3:..." -> "L3").
const launchOf = (id) => (typeof id === "string" && id.includes(":") ? id.slice(0, id.indexOf(":")) : "L0");
// What each scoring event is called in the meter's list of contributions.
const LAUNCH_LABELS = Object.freeze({
@@ -49,6 +106,7 @@ const LAUNCH_LABELS = Object.freeze({
const RUN_LABELS = Object.freeze({
"pathfinder-chart": "Pathfinder map written",
"pathfinder-question": "Pathfinder question settled",
"pathfinder-research": "Pathfinder research done",
plan: "Plan drafted",
"revise-plan": "Plan revised",
document: "Spec documented",
@@ -67,31 +125,51 @@ const unitOf = (id) => (typeof id === "string" && id.includes(":") ? id.slice(id
/**
* What the count is made of: one { label, points } per ledger entry that
* scored, in order. An id seen before is skipped, so a repeated `post` never
* scored, in order, and one row per skill run for its answers, where its
* first answer came. An id seen before is skipped, so a repeated `post` never
* counts twice. Entries that weigh nothing are left out.
*/
export function breakdownFrom(entries) {
const seen = new Set();
const rows = [];
const answers = new Map(); // launch id -> { row, count, workflow }
for (const entry of Array.isArray(entries) ? entries : []) {
if (!entry || typeof entry !== "object") continue;
if (entry.id !== undefined) {
if (seen.has(entry.id)) continue;
seen.add(entry.id);
}
if (entry.kind === "answer") {
const launch = launchOf(entry.id);
let tally = answers.get(launch);
if (!tally) {
tally = { row: { label: "", points: 0 }, count: 0, workflow: entry.workflow };
answers.set(launch, tally);
rows.push(tally.row);
}
tally.count += 1;
continue;
}
let points = 0;
let label = "";
if (entry.kind === "launch" && LAUNCH_COUNTED.has(entry.workflow)) {
points = weightOf(entry.workflow);
label = LAUNCH_LABELS[entry.workflow] || entry.workflow;
} else if (entry.kind === "run") {
points = weightOf(entry.event);
points = runPoints(entry.event, entry.tasks);
const unit = unitOf(entry.id);
label = (RUN_LABELS[entry.event] || entry.event) + (unit ? `: ${unit}` : "");
const counted = TASK_EVENTS.has(entry.event) && isTaskCount(entry.tasks);
const size = counted ? ` (${entry.tasks} ${entry.tasks === 1 ? "task" : "tasks"})` : "";
label = (RUN_LABELS[entry.event] || entry.event) + (unit ? `: ${unit}` : "") + size;
}
if (points > 0) rows.push({ label, points });
}
return rows;
for (const { row, count, workflow } of answers.values()) {
row.points = Math.floor(count / ANSWERS_PER_POINT);
const where = WORKFLOW_NAMES[workflow] ? ` in ${WORKFLOW_NAMES[workflow]}` : "";
row.label = `${count} ${count === 1 ? "answer" : "answers"}${where}`;
}
return rows.filter((row) => row.points > 0);
}
/** The session's points, folded from ledger entries in order. */
@@ -99,9 +177,9 @@ export function pointsFrom(entries) {
return breakdownFrom(entries).reduce((sum, row) => sum + row.points, 0);
}
export const YELLOW_AT = 4;
export const RED_AT = 6;
export const RING_FULL = 8;
export const YELLOW_AT = 5;
export const RED_AT = 10;
export const RING_FULL = 15;
export function levelFor(points) {
if (points < YELLOW_AT) return "green";
@@ -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.
---
@@ -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).
@@ -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/<idea>/attachments/, so
@@ -942,7 +965,7 @@ port, and the filesystem as transport; this CLI is the whole agent surface.
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
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 <sid> [--seconds <N>]
@@ -66,7 +66,7 @@
<span class="badge" id="badge">Pathfinder</span>
<h1 id="title">Plan2Code Console</h1>
<!-- The session meter: how much this console session has done. The
ring fills with the points (full at 8); the colour is the
ring fills with the points (full at 15); the colour is the
level. Hidden until a frame carries `meter`. -->
<span class="meter-slot">
<button
@@ -1347,16 +1347,16 @@
<ul>
<li>
<strong>Green, "Session: fresh".</strong> Under
<span data-fact="meterYellow">4</span> points. Carry on.
<span data-fact="meterYellow">5</span> points. Carry on.
</li>
<li>
<strong>Yellow, "Session: getting long".</strong> From
<span data-fact="meterYellow">4</span> points. Fine for now; think
<span data-fact="meterYellow">5</span> points. Fine for now; think
about a fresh start after this step.
</li>
<li>
<strong>Red, "Session: time for a fresh start".</strong> From
<span data-fact="meterRed">6</span> points. The dashboard also says so
<span data-fact="meterRed">10</span> points. The dashboard also says so
in a banner.
</li>
</ul>
@@ -1364,7 +1364,9 @@
<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. Click the ring to see the count and a list of each step that added
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
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
miss things, and the ring is there to remind you.
@@ -9,7 +9,11 @@
// The one place the weights live (FR-12). Tune here.
export const WEIGHTS = Object.freeze({
"pathfinder-chart": 2,
"pathfinder-question": 1,
// Scores 0: a Pathfinder question now counts through its answers (below).
"pathfinder-question": 0,
// Research reads sources and hands its findings back into the context, with
// nobody answering anything, so each research question scores on its own.
"pathfinder-research": 1,
plan: 2,
"revise-plan": 1,
document: 2,
@@ -30,10 +34,63 @@ export const LAUNCH_COUNTED = Object.freeze(
new Set(["plan", "revise-plan", "document", "review", "quick-task", "init", "init-update", "finalize"])
);
const weightOf = (key) => (Object.prototype.hasOwnProperty.call(WEIGHTS, key) ? WEIGHTS[key] : 0);
// The event names an agent may report in `run`.
export const RUN_EVENTS = new Set(Object.keys(WEIGHTS));
const weightOf = (key) => (Object.prototype.hasOwnProperty.call(WEIGHTS, key) ? WEIGHTS[key] : 0);
// Built phases weigh what they did: a `run` for one of these may carry
// `tasks`, the tasks the phase completed, and then scores one point per
// TASKS_PER_POINT tasks (rounded up, at least 1), plus the event's
// TASK_BONUS for work every phase does whatever its size (the review). A
// run without `tasks` falls back to WEIGHTS. Tune here.
export const TASKS_PER_POINT = 3;
export const TASK_BONUS = Object.freeze({
"implement-phase": 0,
"implement-review-phase": 1,
});
export const TASK_EVENTS = Object.freeze(new Set(Object.keys(TASK_BONUS)));
// The most tasks one run may report: past this it is a typo, not a phase.
export const MAX_TASKS = 999;
/** A valid `run.tasks`: a whole number from 1 to MAX_TASKS. */
export function isTaskCount(tasks) {
return Number.isInteger(tasks) && tasks >= 1 && tasks <= MAX_TASKS;
}
/** What one `run` scores, from its event and (for a built phase) its tasks. */
export function runPoints(event, tasks) {
if (TASK_EVENTS.has(event) && isTaskCount(tasks)) {
return Math.ceil(tasks / TASKS_PER_POINT) + TASK_BONUS[event];
}
return weightOf(event);
}
// Back-and-forth weighs what it took: every answer the person sends from a
// card is an `answer` ledger entry (console.mjs writes one per answered item
// when the agent collects a send), and each skill run scores one point per
// ANSWERS_PER_POINT answers, rounded down. Tune here.
export const ANSWERS_PER_POINT = 2;
// The skill names the answers row uses ("7 answers in Plan").
const WORKFLOW_NAMES = Object.freeze({
dashboard: "the dashboard",
pathfinder: "Pathfinder",
plan: "Plan",
"revise-plan": "Revise plan",
document: "Document",
implement: "Implement",
"implement-review": "Implement + Review",
review: "Review",
"quick-task": "Quick task",
init: "Init",
"init-update": "Init update",
finalize: "Finalize",
handoff: "Handoff",
});
// The skill run an entry belongs to, from its ledger id ("L3:..." -> "L3").
const launchOf = (id) => (typeof id === "string" && id.includes(":") ? id.slice(0, id.indexOf(":")) : "L0");
// What each scoring event is called in the meter's list of contributions.
const LAUNCH_LABELS = Object.freeze({
@@ -49,6 +106,7 @@ const LAUNCH_LABELS = Object.freeze({
const RUN_LABELS = Object.freeze({
"pathfinder-chart": "Pathfinder map written",
"pathfinder-question": "Pathfinder question settled",
"pathfinder-research": "Pathfinder research done",
plan: "Plan drafted",
"revise-plan": "Plan revised",
document: "Spec documented",
@@ -67,31 +125,51 @@ const unitOf = (id) => (typeof id === "string" && id.includes(":") ? id.slice(id
/**
* What the count is made of: one { label, points } per ledger entry that
* scored, in order. An id seen before is skipped, so a repeated `post` never
* scored, in order, and one row per skill run for its answers, where its
* first answer came. An id seen before is skipped, so a repeated `post` never
* counts twice. Entries that weigh nothing are left out.
*/
export function breakdownFrom(entries) {
const seen = new Set();
const rows = [];
const answers = new Map(); // launch id -> { row, count, workflow }
for (const entry of Array.isArray(entries) ? entries : []) {
if (!entry || typeof entry !== "object") continue;
if (entry.id !== undefined) {
if (seen.has(entry.id)) continue;
seen.add(entry.id);
}
if (entry.kind === "answer") {
const launch = launchOf(entry.id);
let tally = answers.get(launch);
if (!tally) {
tally = { row: { label: "", points: 0 }, count: 0, workflow: entry.workflow };
answers.set(launch, tally);
rows.push(tally.row);
}
tally.count += 1;
continue;
}
let points = 0;
let label = "";
if (entry.kind === "launch" && LAUNCH_COUNTED.has(entry.workflow)) {
points = weightOf(entry.workflow);
label = LAUNCH_LABELS[entry.workflow] || entry.workflow;
} else if (entry.kind === "run") {
points = weightOf(entry.event);
points = runPoints(entry.event, entry.tasks);
const unit = unitOf(entry.id);
label = (RUN_LABELS[entry.event] || entry.event) + (unit ? `: ${unit}` : "");
const counted = TASK_EVENTS.has(entry.event) && isTaskCount(entry.tasks);
const size = counted ? ` (${entry.tasks} ${entry.tasks === 1 ? "task" : "tasks"})` : "";
label = (RUN_LABELS[entry.event] || entry.event) + (unit ? `: ${unit}` : "") + size;
}
if (points > 0) rows.push({ label, points });
}
return rows;
for (const { row, count, workflow } of answers.values()) {
row.points = Math.floor(count / ANSWERS_PER_POINT);
const where = WORKFLOW_NAMES[workflow] ? ` in ${WORKFLOW_NAMES[workflow]}` : "";
row.label = `${count} ${count === 1 ? "answer" : "answers"}${where}`;
}
return rows.filter((row) => row.points > 0);
}
/** The session's points, folded from ledger entries in order. */
@@ -99,9 +177,9 @@ export function pointsFrom(entries) {
return breakdownFrom(entries).reduce((sum, row) => sum + row.points, 0);
}
export const YELLOW_AT = 4;
export const RED_AT = 6;
export const RING_FULL = 8;
export const YELLOW_AT = 5;
export const RED_AT = 10;
export const RING_FULL = 15;
export function levelFor(points) {
if (points < YELLOW_AT) return "green";
+7 -3
View File
@@ -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.
---
+18 -4
View File
@@ -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).
+26 -3
View File
@@ -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/<idea>/attachments/, so
@@ -942,7 +965,7 @@ port, and the filesystem as transport; this CLI is the whole agent surface.
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
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 <sid> [--seconds <N>]
+7 -5
View File
@@ -66,7 +66,7 @@
<span class="badge" id="badge">Pathfinder</span>
<h1 id="title">Plan2Code Console</h1>
<!-- The session meter: how much this console session has done. The
ring fills with the points (full at 8); the colour is the
ring fills with the points (full at 15); the colour is the
level. Hidden until a frame carries `meter`. -->
<span class="meter-slot">
<button
@@ -1347,16 +1347,16 @@
<ul>
<li>
<strong>Green, "Session: fresh".</strong> Under
<span data-fact="meterYellow">4</span> points. Carry on.
<span data-fact="meterYellow">5</span> points. Carry on.
</li>
<li>
<strong>Yellow, "Session: getting long".</strong> From
<span data-fact="meterYellow">4</span> points. Fine for now; think
<span data-fact="meterYellow">5</span> points. Fine for now; think
about a fresh start after this step.
</li>
<li>
<strong>Red, "Session: time for a fresh start".</strong> From
<span data-fact="meterRed">6</span> points. The dashboard also says so
<span data-fact="meterRed">10</span> points. The dashboard also says so
in a banner.
</li>
</ul>
@@ -1364,7 +1364,9 @@
<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. Click the ring to see the count and a list of each step that added
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
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
miss things, and the ring is there to remind you.
+87 -9
View File
@@ -9,7 +9,11 @@
// The one place the weights live (FR-12). Tune here.
export const WEIGHTS = Object.freeze({
"pathfinder-chart": 2,
"pathfinder-question": 1,
// Scores 0: a Pathfinder question now counts through its answers (below).
"pathfinder-question": 0,
// Research reads sources and hands its findings back into the context, with
// nobody answering anything, so each research question scores on its own.
"pathfinder-research": 1,
plan: 2,
"revise-plan": 1,
document: 2,
@@ -30,10 +34,63 @@ export const LAUNCH_COUNTED = Object.freeze(
new Set(["plan", "revise-plan", "document", "review", "quick-task", "init", "init-update", "finalize"])
);
const weightOf = (key) => (Object.prototype.hasOwnProperty.call(WEIGHTS, key) ? WEIGHTS[key] : 0);
// The event names an agent may report in `run`.
export const RUN_EVENTS = new Set(Object.keys(WEIGHTS));
const weightOf = (key) => (Object.prototype.hasOwnProperty.call(WEIGHTS, key) ? WEIGHTS[key] : 0);
// Built phases weigh what they did: a `run` for one of these may carry
// `tasks`, the tasks the phase completed, and then scores one point per
// TASKS_PER_POINT tasks (rounded up, at least 1), plus the event's
// TASK_BONUS for work every phase does whatever its size (the review). A
// run without `tasks` falls back to WEIGHTS. Tune here.
export const TASKS_PER_POINT = 3;
export const TASK_BONUS = Object.freeze({
"implement-phase": 0,
"implement-review-phase": 1,
});
export const TASK_EVENTS = Object.freeze(new Set(Object.keys(TASK_BONUS)));
// The most tasks one run may report: past this it is a typo, not a phase.
export const MAX_TASKS = 999;
/** A valid `run.tasks`: a whole number from 1 to MAX_TASKS. */
export function isTaskCount(tasks) {
return Number.isInteger(tasks) && tasks >= 1 && tasks <= MAX_TASKS;
}
/** What one `run` scores, from its event and (for a built phase) its tasks. */
export function runPoints(event, tasks) {
if (TASK_EVENTS.has(event) && isTaskCount(tasks)) {
return Math.ceil(tasks / TASKS_PER_POINT) + TASK_BONUS[event];
}
return weightOf(event);
}
// Back-and-forth weighs what it took: every answer the person sends from a
// card is an `answer` ledger entry (console.mjs writes one per answered item
// when the agent collects a send), and each skill run scores one point per
// ANSWERS_PER_POINT answers, rounded down. Tune here.
export const ANSWERS_PER_POINT = 2;
// The skill names the answers row uses ("7 answers in Plan").
const WORKFLOW_NAMES = Object.freeze({
dashboard: "the dashboard",
pathfinder: "Pathfinder",
plan: "Plan",
"revise-plan": "Revise plan",
document: "Document",
implement: "Implement",
"implement-review": "Implement + Review",
review: "Review",
"quick-task": "Quick task",
init: "Init",
"init-update": "Init update",
finalize: "Finalize",
handoff: "Handoff",
});
// The skill run an entry belongs to, from its ledger id ("L3:..." -> "L3").
const launchOf = (id) => (typeof id === "string" && id.includes(":") ? id.slice(0, id.indexOf(":")) : "L0");
// What each scoring event is called in the meter's list of contributions.
const LAUNCH_LABELS = Object.freeze({
@@ -49,6 +106,7 @@ const LAUNCH_LABELS = Object.freeze({
const RUN_LABELS = Object.freeze({
"pathfinder-chart": "Pathfinder map written",
"pathfinder-question": "Pathfinder question settled",
"pathfinder-research": "Pathfinder research done",
plan: "Plan drafted",
"revise-plan": "Plan revised",
document: "Spec documented",
@@ -67,31 +125,51 @@ const unitOf = (id) => (typeof id === "string" && id.includes(":") ? id.slice(id
/**
* What the count is made of: one { label, points } per ledger entry that
* scored, in order. An id seen before is skipped, so a repeated `post` never
* scored, in order, and one row per skill run for its answers, where its
* first answer came. An id seen before is skipped, so a repeated `post` never
* counts twice. Entries that weigh nothing are left out.
*/
export function breakdownFrom(entries) {
const seen = new Set();
const rows = [];
const answers = new Map(); // launch id -> { row, count, workflow }
for (const entry of Array.isArray(entries) ? entries : []) {
if (!entry || typeof entry !== "object") continue;
if (entry.id !== undefined) {
if (seen.has(entry.id)) continue;
seen.add(entry.id);
}
if (entry.kind === "answer") {
const launch = launchOf(entry.id);
let tally = answers.get(launch);
if (!tally) {
tally = { row: { label: "", points: 0 }, count: 0, workflow: entry.workflow };
answers.set(launch, tally);
rows.push(tally.row);
}
tally.count += 1;
continue;
}
let points = 0;
let label = "";
if (entry.kind === "launch" && LAUNCH_COUNTED.has(entry.workflow)) {
points = weightOf(entry.workflow);
label = LAUNCH_LABELS[entry.workflow] || entry.workflow;
} else if (entry.kind === "run") {
points = weightOf(entry.event);
points = runPoints(entry.event, entry.tasks);
const unit = unitOf(entry.id);
label = (RUN_LABELS[entry.event] || entry.event) + (unit ? `: ${unit}` : "");
const counted = TASK_EVENTS.has(entry.event) && isTaskCount(entry.tasks);
const size = counted ? ` (${entry.tasks} ${entry.tasks === 1 ? "task" : "tasks"})` : "";
label = (RUN_LABELS[entry.event] || entry.event) + (unit ? `: ${unit}` : "") + size;
}
if (points > 0) rows.push({ label, points });
}
return rows;
for (const { row, count, workflow } of answers.values()) {
row.points = Math.floor(count / ANSWERS_PER_POINT);
const where = WORKFLOW_NAMES[workflow] ? ` in ${WORKFLOW_NAMES[workflow]}` : "";
row.label = `${count} ${count === 1 ? "answer" : "answers"}${where}`;
}
return rows.filter((row) => row.points > 0);
}
/** The session's points, folded from ledger entries in order. */
@@ -99,9 +177,9 @@ export function pointsFrom(entries) {
return breakdownFrom(entries).reduce((sum, row) => sum + row.points, 0);
}
export const YELLOW_AT = 4;
export const RED_AT = 6;
export const RING_FULL = 8;
export const YELLOW_AT = 5;
export const RED_AT = 10;
export const RING_FULL = 15;
export function levelFor(points) {
if (points < YELLOW_AT) return "green";