// 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 its one import is the data-only skills.js: the // server, console.mjs, the page and `node --test` all import this file. import { FLOW_SKILLS, isMetered, isPhased } from "./skills.js"; // The weights (FR-12): the events that are not a skill's own launch live // here, and each skill's weight is its `weight` in skills.js. Tune there or here. const EVENT_WEIGHTS = { "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, "implement-phase": 2, "implement-review-phase": 3, // Scores 0 itself: Git's commits are tallied per run (COMMITS_PER_POINT). "git-commits": 0, "git-conflict": 1, // UI Prototype scores per round drawn, not per launch: one point a round, // wherever the round runs (its own skill or a host skill that offers it). "ui-prototype-round": 1, }; // A skill's fields as a table by workflow, leaving out the entries without one. const bySkill = (field) => Object.fromEntries(FLOW_SKILLS.filter((s) => s[field] !== null).map((s) => [s.workflow, s[field]])); export const WEIGHTS = Object.freeze({ ...EVENT_WEIGHTS, ...bySkill("weight") }); // 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; git, changelog, xray and diagnose score 1 on // launch (Git then adds its commit tally and conflict help). Derived from // skills.js (`metered`). export const LAUNCH_COUNTED = Object.freeze(new Set(FLOW_SKILLS.filter((s) => isMetered(s.workflow)).map((s) => s.workflow))); // Git's commits weigh what they add up to: each `git-commits` run carries // `commits`, and a skill run scores one point per COMMITS_PER_POINT commits, // rounded down. MAX_COMMITS is the most one run may report. Tune here. export const COMMITS_PER_POINT = 2; export const MAX_COMMITS = 999; 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, derived // from skills.js (`phased`): export const PROGRESS_WORKFLOWS = Object.freeze(new Set(FLOW_SKILLS.filter((s) => isPhased(s.workflow)).map((s) => s.workflow))); // 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"), derived from // skills.js (`name`). const WORKFLOW_NAMES = Object.freeze(Object.fromEntries(FLOW_SKILLS.map((s) => [s.workflow, s.name]))); // 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: a // skill's launch and run labels are its `started` and `ran` in skills.js, and // the events that are not a skill's own are named here. export const LAUNCH_LABELS = Object.freeze(bySkill("started")); export const RUN_LABELS = Object.freeze({ "pathfinder-chart": "Pathfinder map written", "pathfinder-question": "Pathfinder question settled", "pathfinder-research": "Pathfinder research done", "implement-phase": "Implement phase built", "implement-review-phase": "Implement + Review phase built", "git-commits": "Commits in Git", "git-conflict": "Git conflict help", "ui-prototype-round": "Prototype round drawn", ...bySkill("ran"), }); // 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 commits = new Map(); // launch id -> { row, count } 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); } // A click on the git board is not back-and-forth: Git's answers score nothing. if (entry.kind === "answer" && entry.workflow === "git") continue; if (entry.kind === "run" && entry.event === "git-commits") { if (!Number.isInteger(entry.commits) || entry.commits < 1) continue; const launch = launchOf(entry.id); let tally = commits.get(launch); if (!tally) { tally = { row: { label: "", points: 0 }, count: 0 }; commits.set(launch, tally); rows.push(tally.row); } tally.count += entry.commits; continue; } 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}`; } for (const { row, count } of commits.values()) { row.points = Math.floor(count / COMMITS_PER_POINT); row.label = `${count} ${count === 1 ? "commit" : "commits"} in Git`; } 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."; // The same advice, worded for the desktop app: there the app's own New // Session button already replaces the agent on a fresh context in one click, // so this never tells anyone to copy a command into a new conversation. export const RED_BANNER_IN_APP = "This console session has done a lot. Press New Session at the top of the window to start the agent fresh."; // 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), }; }