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 42d220ce4c
commit 61f927466e
72 files changed
+2121 -346

No files matched your search

@@ -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";