Skip to content

Autonomous development for real products. Governed agents build from specs you approve, follow the rules you set, and nothing merges until another agent proves it. Your decisions, judgement and taste are the bar that work must clear. Declare your vision and let agents build it.

feat(core): derive badge endpoints from verified board records [B3,V1]

Corey Olson9f3c8e4412d9
diff --git a/src/badge.js b/src/badge.js
new file mode 100644
index 00000000..46bad51a
--- /dev/null
+++ b/src/badge.js
@@ -0,0 +1,41 @@
+/** Board-derived Shields endpoint documents, shared by the command and landing [B3,V1]. */
+import { existsSync } from 'node:fs';
+import { mkdirSync } from 'node:fs';
+import { readFileSync } from 'node:fs';
+import { writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { join } from 'node:path';
+
+/** Count finished records and their current non-self acceptance; absent legacy builder evidence proves nothing. */
+export function badgeCounts(board) {
+ const row = board.db.prepare(`SELECT COUNT(*) AS items,
+ COALESCE(SUM(CASE WHEN i.item_built_by IS NOT NULL AND i.item_built_by != ''
+ AND v.verdict_by != i.item_built_by THEN 1 ELSE 0 END), 0) AS checked
+ FROM item i LEFT JOIN verdict v ON v.verdict_id = (
+ SELECT MAX(a.verdict_id) FROM verdict a WHERE a.item_id=i.item_id
+ AND a.verdict_decision='ACCEPT' AND a.verdict_commit=i.item_commit)
+ WHERE i.item_status='verified'`).get();
+ return { items: row.items, checked: row.checked, percent: row.items ? Math.floor(row.checked * 100 / row.items) : null };
+}
+
+/** Serialize stable endpoint bytes; the zero-item board has no percentage to publish. */
+export function badgeDocuments(counts) {
+ if (!counts.items) return [];
+ return [
+ { path: 'docs/badges/items.json', value: { schemaVersion: 1, label: 'pullboard', message: `${counts.items} items`, color: '2f7d5b' } },
+ { path: 'docs/badges/checked.json', value: { schemaVersion: 1, label: 'agent-verified', message: `${counts.percent}%`, color: '6e7781' } },
+ ].map(document => ({ path: document.path, text: JSON.stringify(document.value, null, 2) + '\n' }));
+}
+
+/** Write changed endpoint documents only; an empty board leaves even existing files untouched. */
+export function writeBadges(root, counts) {
+ const changed = [];
+ for (const document of badgeDocuments(counts)) {
+ const file = join(root, document.path);
+ if (existsSync(file) && readFileSync(file, 'utf8') === document.text) continue;
+ mkdirSync(dirname(file), { recursive: true });
+ writeFileSync(file, document.text);
+ changed.push(document.path);
+ }
+ return changed;
+}
diff --git a/src/commands/badge.js b/src/commands/badge.js
new file mode 100644
index 00000000..be4cbb88
--- /dev/null
+++ b/src/commands/badge.js
@@ -0,0 +1,18 @@
+/** Publish board-derived badge endpoint documents in any Pullboard project [B3,V1]. */
+import { badgeCounts } from '../badge.js';
+import { writeBadges } from '../badge.js';
+import { context } from '../cli.js';
+import { withBoardRead } from '../cli.js';
+import { Refused } from '../refused.js';
+
+/** Run `pullboard badge` without modifying the board or contacting a badge service. */
+export function run(io, { first }) {
+ if (first) throw new Refused('USAGE', 'pullboard badge takes no arguments');
+ const ctx = context(io);
+ const counts = withBoardRead(ctx, badgeCounts);
+ const changed = writeBadges(ctx.info.root, counts);
+ io.result?.({ ...counts, changed });
+ if (!counts.items) io.say('No finished items yet; no badge files were written.');
+ else io.say(`${counts.items} items; ${counts.percent}% agent-verified. ${changed.length ? `Wrote ${changed.join(' and ')}.` : 'Badge files are unchanged.'}`);
+ return 0;
+}
diff --git a/src/help.js b/src/help.js
index 629142c7..53b79e78 100644
--- a/src/help.js
+++ b/src/help.js
@@ -58,6 +58,7 @@ Set up
pullboard relay recover --skip <sequence> person-only recovery of one blocked next relay position
pullboard resume where you are: your claim, branch, uncommitted work, what came back,
unread shouts, what to do next; run it to start any session
+ pullboard badge write board-derived Shields endpoint JSON to docs/badges/
pullboard hooks reinstall the git hooks (e.g. after a fresh clone)
Work
diff --git a/src/json.js b/src/json.js
index b3eb10d9..cc6e2d00 100644
--- a/src/json.js
+++ b/src/json.js
@@ -41,6 +41,7 @@ export const JSON_SHAPES = {
'milestone ship': shape({ milestone: 'object', into: 'string|null', moved: 'array', notMoved: 'array' }),
show: shape({ item_id: 'number', item_title: 'string', item_lane: 'string', item_status: 'string', verdicts: 'array', thread: 'array' }),
stats: shape({ stats: 'object', gateWaits: 'array' }),
+ badge: shape({ items: 'number', checked: 'number', percent: 'number|null', changed: 'array' }),
status: shape({ me: 'object', mine: 'array', stats: 'object', reviewQueue: 'object', unread: 'number', relay: 'object' }),
doctor: shape({ problems: 'array' }),
health: shape({ asOf: 'string', thresholds: 'object', stuck: 'array', waiting: 'array' }),
diff --git a/src/land.js b/src/land.js
index 4acc5f12..7380e61c 100644
--- a/src/land.js
+++ b/src/land.js
@@ -19,6 +19,8 @@ import {
relative,
} from 'node:path';
import * as store from './board.js';
+import { badgeCounts } from './badge.js';
+import { writeBadges } from './badge.js';
import {
git,
headCommit,
@@ -207,6 +209,13 @@ async function mergeGroup(state, items) {
.find((commit) => tryGit(batch.root, ['merge-base', '--is-ancestor', checked, commit]).status === 0);
merged.push({ id: item.item_id, commit: item.item_commit, ...(checked !== item.item_commit ? { reviewedCommit: checked } : {}), merge: first });
}
+ if (merged.length) {
+ const changed = writeBadges(batch.root, badgeCounts(state.board));
+ if (changed.length) {
+ git(batch.root, ['add', '--', ...changed]);
+ git(batch.root, ['commit', '-m', 'chore: refresh board badge counts']);
+ }
+ }
return { items: merged, conflicts, tip: headCommit(batch.root) };
}
diff --git a/test/api-catalog.test.js b/test/api-catalog.test.js
index a3646343..f05ddb55 100644
--- a/test/api-catalog.test.js
+++ b/test/api-catalog.test.js
@@ -277,6 +277,7 @@ catalogCase('[A1] command results match the catalog across roots and subcommands
await json(box, repo, 'resume');
await json(box, repo, 'status');
await json(box, repo, 'stats');
+ await json(box, repo, 'badge');
await json(box, repo, 'doctor');
assert.deepEqual((await json(box, repo, 'health')).stuck, [], 'a new board has nothing stuck [A6]');
await json(box, repo, 'skills', ['--update']);
diff --git a/test/badge-fixture.js b/test/badge-fixture.js
new file mode 100644
index 00000000..47cd9db2
--- /dev/null
+++ b/test/badge-fixture.js
@@ -0,0 +1,40 @@
+/** Real landing proof for board-derived badge endpoint commits [B3,V1,R3]. */
+import assert from 'node:assert/strict';
+import { readFileSync } from 'node:fs';
+import { writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+/** Require both documents in the exact landed, clean tip of a real private project's complete lifecycle. */
+export function assertBadgeLanding(e2e) {
+ const box = e2e.project('node --test web/badge.test.cjs');
+ const path = join(box.repo, 'pullboard.json');
+ const config = JSON.parse(readFileSync(path, 'utf8'));
+ writeFileSync(path, JSON.stringify({ ...config, landing: { publish: 'separate' } }, null, 2));
+ box.git(box.repo, 'add', 'pullboard.json');
+ box.git(box.repo, 'commit', '-q', '-m', 'chore: configure private badge landing');
+ box.git(box.web, 'merge', '-q', '--ff-only', 'main');
+ const added = box.run(box.repo, 'add', 'web', 'Badge landing', '--criterion', 'The native probe passes.', '--check', 'node --test web/badge.test.cjs', '--json');
+ assert.equal(added.code, 0, `${added.err}\n${added.out}`);
+ const id = JSON.parse(added.out).item.item_id;
+ const claimed = box.run(box.web, 'claim', String(id));
+ assert.equal(claimed.code, 0, claimed.err);
+ const committed = e2e.commitFile(box, box.web, 'web/badge.test.cjs', "const { test } = require('node:test'); test('the badge landing probe passes [G1]', () => {});\n", 'test(web): add private badge landing probe [G1]');
+ assert.equal(committed.status, 0, committed.stderr);
+ const commit = box.git(box.web, 'rev-parse', 'HEAD');
+ const submitted = box.run(box.web, 'submit', String(id));
+ assert.equal(submitted.code, 0, `${submitted.err}\n${submitted.out}`);
+ box.git(box.repo, 'switch', '-q', '--detach', commit);
+ try {
+ const accepted = box.run(box.repo, 'verify', String(id), 'accept', '--as', 'coordinator', '--note', 'The private native probe passed at the submitted commit.');
+ assert.equal(accepted.code, 0, `${accepted.err}\n${accepted.out}`);
+ } finally { box.git(box.repo, 'switch', '-q', 'main'); }
+ const result = box.run(box.repo, 'land', '--json');
+ assert.equal(result.code, 0, `${result.err}\n${result.out}`);
+ const landed = JSON.parse(result.out);
+ assert.deepEqual(landed.landed, [id]);
+ const documents = ['items', 'checked'].map(name => JSON.parse(box.git(box.repo, 'show', `${landed.batch.tip}:docs/badges/${name}.json`)));
+ assert.equal(documents[0].message, '1 items');
+ assert.equal(documents[1].message, '100%');
+ assert.equal(box.git(box.repo, 'rev-parse', 'HEAD'), landed.batch.tip);
+ assert.equal(box.git(box.repo, 'status', '--porcelain'), '', 'the endpoint refresh is committed with the landed tip');
+}
diff --git a/test/badge.test.js b/test/badge.test.js
new file mode 100644
index 00000000..bac32f05
--- /dev/null
+++ b/test/badge.test.js
@@ -0,0 +1,76 @@
+/** Board-record badge counts use actual private Git/SQLite projects [B3,V1]. */
+import assert from 'node:assert/strict';
+import { existsSync } from 'node:fs';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { after } from 'node:test';
+import { test } from 'node:test';
+import * as store from '../src/board.js';
+import { exportBoard } from '../src/exchange.js';
+import { importBoard } from '../src/exchange.js';
+import { createE2eHelpers } from './e2e-helpers.js';
+import { assertBadgeLanding } from './badge-fixture.js';
+import { submitFixture } from './board-submit-fixture.js';
+
+const e2e = createE2eHelpers();
+after(e2e.cleanup);
+
+/** Seed historical board records through normal lifecycle and native import, including a legacy self acceptance. */
+function badgeProject(total, outside) {
+ const box = e2e.sandbox();
+ box.git(box.dir, 'init', '-q', '-b', 'main');
+ const source = store.openBoard(':memory:');
+ let document;
+ try {
+ store.register(source, { lane: 'coordinator', path: box.dir });
+ const builder = store.register(source, { lane: 'web', path: join(box.dir, 'builder') });
+ const reviewer = store.register(source, { lane: 'web', path: join(box.dir, 'reviewer') });
+ for (let index = 0; index < total; index++) {
+ const id = store.addItem(source, { by: 'coordinator', lane: 'web', title: `Finished ${index}` });
+ store.claim(source, id, { agentId: builder, lane: 'web', leaseMs: 3_600_000,
+ freeze: () => ({ text: 'badge history fixture', digest: `badge-${id}` }) });
+ const commit = String(index + 1).padStart(40, '0');
+ submitFixture(source, id, { agentId: builder, commit, tree: commit });
+ store.verify(source, id, { agentId: reviewer, decision: 'ACCEPT', head: commit,
+ digest: `badge-${id}`, policy: 'any', note: 'Synthetic historical board-state acceptance; no runtime proof claimed.' });
+ }
+ document = exportBoard(source);
+ // Modern guards forbid self acceptance; native import preserves historical records without a guard bypass.
+ for (const item of document.tables.item.slice(outside)) {
+ item.item_verified_by = builder;
+ for (const verdict of document.tables.verdict.filter(row => row.item_id === item.item_id)) verdict.verdict_by = builder;
+ }
+ } finally { store.closeBoard(source); }
+ const target = store.openBoard(join(box.dir, '.git', 'pullboard', 'board.sqlite'));
+ try { importBoard(target, document); } finally { store.closeBoard(target); }
+ const initialized = box.run(box.dir, 'init');
+ assert.equal(initialized.code, 0, initialized.err);
+ return box;
+}
+
+/** Read the committed endpoint shape written by the real command. */
+function endpoints(box) {
+ return ['items', 'checked'].map(name => JSON.parse(readFileSync(join(box.dir, `docs/badges/${name}.json`), 'utf8')));
+}
+
+test('pullboard badge writes the verified counts from the board [B3,V1]', () => {
+ const five = badgeProject(5, 4);
+ const result = five.run(five.dir, 'badge', '--json');
+ assert.equal(result.code, 0, `${result.err}\n${result.out}`);
+ assert.deepEqual(endpoints(five), [
+ { schemaVersion: 1, label: 'pullboard', message: '5 items', color: '2f7d5b' },
+ { schemaVersion: 1, label: 'agent-verified', message: '80%', color: '6e7781' },
+ ]);
+ const repeated = five.run(five.dir, 'badge', '--json');
+ assert.equal(repeated.code, 0, repeated.err);
+ assert.deepEqual(JSON.parse(repeated.out).changed, [], 'unchanged counts do not rewrite the documents');
+ const thirds = badgeProject(3, 2);
+ assert.equal(thirds.run(thirds.dir, 'badge').code, 0);
+ assert.equal(endpoints(thirds)[1].message, '66%', 'the percentage is floored, never rounded');
+ const empty = badgeProject(0, 0);
+ const nothing = empty.run(empty.dir, 'badge');
+ assert.equal(nothing.code, 0, nothing.err);
+ assert.match(nothing.out, /No finished items.*no badge files/);
+ assert.equal(existsSync(join(empty.dir, 'docs/badges')), false, 'no files or directories are written for no finished work');
+ assertBadgeLanding(e2e);
+});