Files
plan2code/skills/plan2code-init/references/web-console/public/meter.js
T

307 lines
12 KiB
JavaScript

// Plan2Code Web Console - the session meter's weights, count and wording.
//
// The source of truth for how much each piece of work weighs, how the count
// is folded out of ledger.ndjson, and what the pill says at each level. The
// count is never stored: it is always pointsFrom() over the ledger. No DOM
// access at module scope and no imports: the server, console.mjs, the page
// and `node --test` all import this file.
// The one place the weights live (FR-12). Tune here.
export const WEIGHTS = Object.freeze({
"pathfinder-chart": 2,
// 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,
"implement-phase": 2,
"implement-review-phase": 3,
review: 2,
"quick-task": 1,
init: 2,
"init-update": 2,
finalize: 1,
handoff: 0,
});
// Workflows whose launch itself scores WEIGHTS[workflow]. Pathfinder,
// implement and implement-review score only through the agent's `run`
// reports; dashboard and handoff never score.
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));
// 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 build scores while it runs, not only once it is approved: console.mjs
// writes a `progress` ledger entry whenever a build's `headline.cleared`
// rises, and the build's row scores those tasks at TASKS_PER_POINT with no
// bonus. The phase's `run` then takes the row over with its final score, so
// the total only ever climbs. Workflows whose headline counts tasks:
export const PROGRESS_WORKFLOWS = Object.freeze(new Set(["implement", "implement-review"]));
// Implement + Review reviews every phase as a stage of the build. A `review`
// run inside it is that stage, so it scores the phase's TASK_BONUS when it
// starts, and the phase's own run leaves the bonus out after it.
const BUILT_IN_REVIEW = Object.freeze({ "implement-review": "implement-review-phase" });
/**
* The ledger entry a build's progress post stands for, or null when it adds
* nothing: not a task-counting workflow, no whole `cleared`, or no more tasks
* than this build already has. `seg` is how many phases this skill run has
* finished, so a second phase in the same run starts its own count, but only
* once its headline is back at 0: until then a `cleared` is the finished
* phase's, posted again, and opening a build on it would count it twice.
*/
export function progressEntry(entries, launch, workflow, cleared) {
if (!PROGRESS_WORKFLOWS.has(workflow)) return null;
if (cleared !== 0 && !isTaskCount(cleared)) return null;
const list = Array.isArray(entries) ? entries : [];
const seg = list.filter((e) => e && e.kind === "run" && TASK_EVENTS.has(e.event) && launchOf(e.id) === launch).length;
const build = `${launch}:b${seg}`;
const mine = list.filter((e) => e && e.kind === "progress" && e.build === build);
const entry = (tasks) => ({ kind: "progress", id: `${build}:${tasks}`, build, workflow, tasks });
if (cleared === 0) return seg > 0 && !mine.length ? entry(0) : null;
if (seg > 0 && !mine.length) return null;
const most = mine.reduce((n, e) => Math.max(n, e.tasks), 0);
return cleared > most ? entry(cleared) : null;
}
/** 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.
* `bonus: false` leaves the review bonus out, for a phase whose review
* already scored.
*/
export function runPoints(event, tasks, { bonus = true } = {}) {
if (TASK_EVENTS.has(event) && isTaskCount(tasks)) {
return Math.ceil(tasks / TASKS_PER_POINT) + (bonus ? TASK_BONUS[event] : 0);
}
if (TASK_EVENTS.has(event) && !bonus) return weightOf(event) - 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({
plan: "Plan started",
"revise-plan": "Revise plan started",
document: "Document started",
review: "Review started",
"quick-task": "Quick task started",
init: "Init started",
"init-update": "Init update started",
finalize: "Finalize started",
});
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",
"implement-phase": "Implement phase built",
"implement-review-phase": "Implement + Review phase built",
review: "Code review run",
"quick-task": "Quick task built",
init: "Init run",
"init-update": "Init update run",
finalize: "Finalize run",
handoff: "Handoff written",
});
// The unit a run names, from its ledger id ("L3:phase-2" -> "phase-2").
const unitOf = (id) => (typeof id === "string" && id.includes(":") ? id.slice(id.indexOf(":") + 1) : "");
/**
* What the count is made of: one { label, points } per ledger entry that
* 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 }
const builds = new Map(); // launch id -> the row of the build in progress
const reviewed = new Set(); // launch ids whose built-in review has scored
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;
}
if (entry.kind === "progress") {
if (!isTaskCount(entry.tasks)) continue;
const launch = launchOf(entry.id);
let row = builds.get(launch);
if (!row || row.build !== entry.build) {
row = { label: "", points: 0, build: entry.build, tasks: 0 };
builds.set(launch, row);
rows.push(row);
}
if (entry.tasks > row.tasks) {
row.tasks = entry.tasks;
row.points = Math.ceil(entry.tasks / TASKS_PER_POINT);
const where = WORKFLOW_NAMES[entry.workflow] || "Build";
row.label = `${where}: ${entry.tasks} ${entry.tasks === 1 ? "task" : "tasks"} built so far`;
}
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") {
const launch = launchOf(entry.id);
const builtIn = BUILT_IN_REVIEW[entry.workflow];
if (entry.event === "review" && builtIn) {
// The review stage of Implement + Review: it scores the bonus its
// phase would otherwise carry, once per skill run.
if (reviewed.has(launch)) continue;
reviewed.add(launch);
points = TASK_BONUS[builtIn];
label = `${WORKFLOW_NAMES[entry.workflow]}: code review run`;
} else {
const bonus = !(TASK_EVENTS.has(entry.event) && reviewed.has(launch));
points = runPoints(entry.event, entry.tasks, { bonus });
const unit = unitOf(entry.id);
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 !== entry.event ? `: ${unit}` : "") + size;
}
// A finished phase takes over its build's progress row, in place.
if (TASK_EVENTS.has(entry.event) && builds.has(launch)) {
const row = builds.get(launch);
builds.delete(launch);
row.label = label;
row.points = Math.max(points, row.points);
continue;
}
}
if (points > 0) rows.push({ label, points });
}
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).map(({ label, points }) => ({ label, points }));
}
/** The session's points, folded from ledger entries in order. */
export function pointsFrom(entries) {
return breakdownFrom(entries).reduce((sum, row) => sum + row.points, 0);
}
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";
if (points < RED_AT) return "yellow";
return "red";
}
// How much of the ring is filled: full at RING_FULL, never below empty.
export function ringFraction(points) {
return Math.max(0, Math.min(points, RING_FULL)) / RING_FULL;
}
export const WORDS = Object.freeze({
green: "Session: fresh",
yellow: "Session: getting long",
red: "Session: time for a fresh start",
});
export function tooltipFor(points) {
const count = `${points} ${points === 1 ? "point" : "points"}`;
switch (levelFor(points)) {
case "green":
return `This session is fresh (${count}).`;
case "yellow":
return `This session is getting long (${count}). A fresh one will soon be sharper.`;
default:
return `This session has done a lot (${count}). The agent may start missing things.`;
}
}
export const RED_BANNER =
"This console session has done a lot. Starting a new console session will keep the agent sharp.";
// Everything the pill draws, from the ledger alone.
export function meterView(entries) {
const points = pointsFrom(entries);
const level = levelFor(points);
return {
points,
level,
fraction: ringFraction(points),
words: WORDS[level],
tooltip: tooltipFor(points),
items: breakdownFrom(entries),
};
}