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.
JavaScript agentic-codingai-agentsai-governanceautonomous-agentsclaude-codeclicode-reviewcodexcoding-agentsdeveloper-toolsgit-hooksllmlocal-firstmulti-agentsoftware-factoryspec-driven-developmentverificationvibe-coding
feat(rigor): a repeated cause can be drafted as a sentinel [D1,D3,A6]
Corey Olson03ae8f134c12
diff --git a/src/cli.js b/src/cli.jsindex 5799fdb9..7c03f398 100644--- a/src/cli.js+++ b/src/cli.js@@ -2649,7 +2649,7 @@ function readCommands(io, { first, second, rest, values }) {return 0;},rigor: () => {- if (first === 'draft') { const ctx = context(io); return rigorDraftCommand(io, { second, rest, values }, { root: ctx.info.root, config: ctx.config, read: () => withBoard(ctx, (board) => ({ events: store.events(board), actor: whoAmI(ctx, board).id })), reserve: (row) => reserveRow(ctx, row, true) }); }+ if (first === 'draft') { const ctx = context(io); return rigorDraftCommand(io, { second, rest, values }, { root: ctx.info.root, config: ctx.config, read: () => withBoard(ctx, (board) => ({ events: store.events(board), actor: whoAmI(ctx, board).id })), reserve: (row) => reserveRow(ctx, row, true), propose: (row, evidence) => withBoard(ctx, async (board) => ordered(ctx, board, 'proposeSentinel', [{ agentId: whoAmI(ctx, board).id, row, evidence }])) }); }if (first || second || rest.length) throw new Refused('USAGE', 'pullboard rigor takes no arguments; to draft a rule: pullboard rigor draft <key> "<rule>" --check "<command>" --red <commit> --green <commit>');const ctx = context(io);const report = withBoard(ctx, (board) => rigorReport(store.events(board), { person: store.PERSON }));diff --git a/src/needs-state.js b/src/needs-state.jsindex 452d9b3e..00bd29ec 100644--- a/src/needs-state.js+++ b/src/needs-state.js@@ -16,6 +16,10 @@ import {undraftedRigor,} from './rigor-notices.js';import { personNeeds } from './needs.js';+import {+ sentinelDraftNeeds,+ sentinels,+} from './sentinels.js';/** Borrow an existing connection or open a read-only one; retain exact row-decision matching. */export function personNeedsState(root, { board: providedBoard = null, includeRigorUndrafted = false } = {}) {@@ -27,7 +31,7 @@ export function personNeedsState(root, { board: providedBoard = null, includeRigconst config = loadConfig(root);const rows = projectRowDecisions(decisions, { root, spec: loadSpec(root, config).rows, practice: loadDoctrine(root, config).rows });const rigorDrafts = rigorDraftNeeds(rows);- const projected = { ...state, rigorDrafts, ...(includeRigorUndrafted+ const projected = { ...state, rigorDrafts, sentinelDrafts: sentinelDraftNeeds(sentinels(board)), ...(includeRigorUndrafted? { rigorUndrafted: undraftedRigor(store.events(board), rows, { person: store.PERSON }) } : {}) };return { ...projected, needs: personNeeds(projected) };} finally {diff --git a/src/needs.js b/src/needs.jsindex 5e668120..93eafde1 100644--- a/src/needs.js+++ b/src/needs.js@@ -16,6 +16,7 @@ export function personNeeds(state) {...(state.holds ?? []).map(hold => ({ kind: 'hold', id: hold.hold_lane,ref: hold.hold_lane, text: hold.hold_reason, what: 'lane held by ' + name(hold.hold_by) })),...rigorDrafts,+ ...(state.sentinelDrafts ?? []),...(drafts ? [{ kind: 'draft', id: 'drafts', count: drafts, ref: String(drafts),text: 'draft spec rows to approve or drop' + rows.filter(row => row.staleDecision).map(row => `; ${row.stage}`).join(''), what: 'review in SPEC.md', target: 'tab:spec' }] : []),];diff --git a/src/rigor-draft.js b/src/rigor-draft.jsindex 35ac11a1..6cd274be 100644--- a/src/rigor-draft.js+++ b/src/rigor-draft.js@@ -14,6 +14,7 @@ import {import { draftRow } from './spec-draft.js';import { proveCauseCheck } from './rigor-proof.js';import { rigorSource } from './rigor-source.js';+import { rigorSentinelName } from './sentinels.js';/*** Draft the rows for a repeated cause, after proving its check. Refused when the key is malformed,@@ -27,14 +28,24 @@ import { rigorSource } from './rigor-source.js';* @param {{ key: string, text: string, check?: string, red?: string, green?: string, section?: string }} request* @returns {Promise<{ key: string, reads: string, evidence: { items: { id: number, commits: string[] }[], occurrences: number, neverAgain: boolean }, proof: object, drafts: object[] }>}*/-export async function rigorDraft({ root, config, events, person, agent, reserve = async (row) => row }, { key, text, check, red, green, section }) {+export async function rigorDraft({ root, config, events, person, agent, reserve = async (row) => row, propose = null }, { key, text, check, red, green, section, sentinel = null }) {const malformed = causeProblem(key ?? '');if (malformed) throw malformed;const cause = rigorReport(events, { person }).causes.find((entry) => entry.key === key);if (!cause) throw new Refused('RIGOR_UNNOTICED', `${key} has not repeated, so there is nothing to draft yet; pullboard rigor lists the causes that can become rules`);- if (!text?.trim() || /[\r\n|]/u.test(text)) throw new Refused('USAGE', 'give the rule as one nonempty line without a field separator: pullboard rigor draft <key> "<rule>" --check "<command>" --red <commit> --green <commit>');+ if (sentinel && (text !== undefined && (!text.trim() || /[\r\n]/u.test(text)))) throw new Refused('USAGE', 'give the watch\'s next step as one line, or leave it out: pullboard rigor draft <key> --sentinel --check "<command>" --red <commit> --green <commit>');+ if (!sentinel && (!text?.trim() || /[\r\n|]/u.test(text))) throw new Refused('USAGE', 'give the rule as one nonempty line without a field separator: pullboard rigor draft <key> "<rule>" --check "<command>" --red <commit> --green <commit>');if (cause.reads !== 'work' && / \| /u.test(check ?? '')) throw new Refused('USAGE', 'a spec row gate cannot hold " | "; put the pipeline in a script and name the script in --check');const proof = await proveCauseCheck(root, cause, { check, red, green }, { agent });+ const evidence = { items: cause.items, occurrences: cause.occurrences, neverAgain: cause.neverAgain };+ if (sentinel) {+ // A cause a command can watch becomes a pending watch instead of a rule; it cites the repeats and its proof (#776).+ const row = { name: rigorSentinelName(key), check: proof.check, every: sentinel.every ?? 'hourly', owner: sentinel.owner ?? 'coordinator',+ next: text?.trim() || `find why ${key} went red again and repair it` };+ const proposed = await propose(row, { key, items: cause.items, occurrences: cause.occurrences,+ proof: { check: proof.check, red: { commit: proof.red.commit, exit: proof.red.exit }, green: { commit: proof.green.commit, exit: proof.green.exit } } });+ return { key, reads: cause.reads, evidence, proof: { check: proof.check, red: proof.red, green: proof.green }, drafts: [], sentinel: proposed };+ }const items = cause.items.map((item) => `#${item.id}`).join(', ');const why = `Why: rigor ${key.replaceAll('|', '/')} ${cause.neverAgain ? 'was marked never again by the person' : `failed on ${items}`}; red at ${proof.red.commit}, green at ${proof.green.commit}.`;const rowText = `${text.trim()} ${why}`;@@ -47,8 +58,7 @@ export async function rigorDraft({ root, config, events, person, agent, reserveconst drafts = [];if (cause.reads !== 'product') drafts.push(await write({ target: 'doctrine', text: rowText, gate: `check ${proof.countCheck}`, fields: ['count: 0', `source: ${source}`], section }));if (cause.reads !== 'work') drafts.push(await write({ target: 'spec', text: rowText, gate: proof.check, fields: [`source: ${source}`], section }));- return { key, reads: cause.reads, evidence: { items: cause.items, occurrences: cause.occurrences, neverAgain: cause.neverAgain },- proof: { check: proof.check, red: proof.red, green: proof.green }, drafts };+ return { key, reads: cause.reads, evidence, proof: { check: proof.check, red: proof.red, green: proof.green }, drafts };}/**@@ -58,17 +68,24 @@ export async function rigorDraft({ root, config, events, person, agent, reserve** @param {any} io* @param {{ second?: string, rest: string[], values: any }} args- * @param {{ root: string, config: any, read: () => { events: any[], actor: string }, reserve: (row: any) => Promise<{ id: string }> }} deps- * read: the board's events and the asking agent; reserve: the CLI's board reservation.+ * @param {{ root: string, config: any, read: () => { events: any[], actor: string }, reserve: (row: any) => Promise<{ id: string }>, propose?: (row: any, evidence: any) => Promise<any> }} deps+ * read: the board's events and the asking agent; reserve: the CLI's board reservation; propose: records a+ * pending watch with its evidence, for --sentinel (#776).* @returns {Promise<number>}*/-export async function rigorDraftCommand(io, { second, rest, values }, { root, config, read, reserve }) {- if (rest.length > 1) throw new Refused('USAGE', 'pullboard rigor draft <key> "<rule>" --check "<command>" --red <commit> --green <commit> [--section <letter>]');+export async function rigorDraftCommand(io, { second, rest, values }, { root, config, read, reserve, propose }) {+ if (rest.length > 1) throw new Refused('USAGE', 'pullboard rigor draft <key> "<rule>" --check "<command>" --red <commit> --green <commit> [--section <letter>], or <key> --sentinel [--every hourly] [--owner <seat or lane>]');const { events, actor } = read();- const result = await rigorDraft({ root, config, events, person: PERSON, agent: actor, reserve },- { key: second, text: rest[0], check: values.check, red: values.red, green: values.green, section: values.section });+ const sentinel = values.sentinel ? { every: values.every, owner: values.owner } : null;+ const result = await rigorDraft({ root, config, events, person: PERSON, agent: actor, reserve, propose },+ { key: second, text: rest[0], check: values.check, red: values.red, green: values.green, section: values.section, sentinel });io.result?.(result);io.say(`proved ${result.key}: red at ${result.proof.red.commit.slice(0, 12)} (${result.proof.red.problems} problem lines, exit ${result.proof.red.exit}), green at ${result.proof.green.commit.slice(0, 12)} (exit ${result.proof.green.exit})`);+ if (result.sentinel) {+ io.say(`sentinel ${result.sentinel.name}: pending; ${result.sentinel.every}; owner ${result.sentinel.owner}\n ${result.sentinel.check}`);+ io.say(`next: the person approves it with pullboard sentinel approve ${result.sentinel.name} or in Pullboard View, or declines it with --reason`);+ return 0;+ }for (const draft of result.drafts) io.say(`${draft.file}: ${draft.line}`);io.say(`next: the person approves ${result.drafts.map((draft) => draft.id).join(' or ')} in pullboard view or with pullboard spec approve; commit ${[...new Set(result.drafts.map((draft) => draft.file))].join(' and ')}`);return 0;diff --git a/src/sentinel-command.js b/src/sentinel-command.jsindex 5d9f3896..e376e9f0 100644--- a/src/sentinel-command.js+++ b/src/sentinel-command.js@@ -13,6 +13,7 @@ export const SENTINEL_OPTIONS = {directory: { type: 'string' },timeout: { type: 'string' },next: { type: 'string' },+ sentinel: { type: 'boolean' },};/** Run due approved watches from ordinary resume, respecting the health switches. */diff --git a/src/sentinels.js b/src/sentinels.jsindex 05280106..80e14f57 100644--- a/src/sentinels.js+++ b/src/sentinels.js@@ -38,6 +38,41 @@ export function sentinelDefinition(value) {timeoutMs, next: next.trim() };}+/**+ * The evidence a proposal cites, kept beside the row and outside its digest: the person approves the watch,+ * and the evidence says why it was proposed (#776). A Rigor draft cites its repeated cause, the items it+ * failed on and the red and green commits that prove its check; an agent's own proposal cites none.+ */+export function sentinelEvidence(value) {+ if (value === undefined || value === null) return null;+ const commit = (side) => side && typeof side.commit === 'string' && /^[0-9a-f]{7,64}$/u.test(side.commit) && Number.isSafeInteger(side.exit);+ if (typeof value !== 'object' || typeof value.key !== 'string' || !value.key.trim() || value.key.length > 512+ || !Array.isArray(value.items) || value.items.length > 100 || value.items.some(item => !Number.isSafeInteger(item?.id))+ || !Number.isSafeInteger(value.occurrences) || value.occurrences < 0+ || value.proof !== undefined && !(value.proof && typeof value.proof.check === 'string' && commit(value.proof.red) && commit(value.proof.green))) {+ throw new Refused('BAD_SENTINEL', 'a sentinel cites its evidence as a repeated cause, its items and a proven check; draft it with pullboard rigor draft <key> --sentinel');+ }+ return { key: value.key, items: value.items.map(item => ({ id: item.id, commits: Array.isArray(item.commits) ? item.commits.filter(commit => typeof commit === 'string').slice(0, 20) : [] })),+ occurrences: value.occurrences, ...(value.proof ? { proof: { check: value.proof.check,+ red: { commit: value.proof.red.commit, exit: value.proof.red.exit }, green: { commit: value.proof.green.commit, exit: value.proof.green.exit } } } : {}) };+}++/** A watch name for a repeated cause: lower case, safe characters, at most 64 long. */+export function rigorSentinelName(key) {+ const slug = String(key).toLowerCase().replace(/[^a-z0-9._-]+/gu, '-').replace(/^[^a-z0-9]+|-+$/gu, '');+ return ('rigor-' + slug).slice(0, 64).replace(/[-._]+$/u, '');+}++/** Pending watches are the person's calls: one Needs-you entry each, with the evidence that proposed it. */+export function sentinelDraftNeeds(rows) {+ return rows.filter(row => row.status === 'pending').map(row => ({+ kind: 'sentinel-draft', id: `sentinel:${row.name}`, ref: row.name,+ text: `Sentinel draft: ${row.name} runs ${row.check} ${row.every === 'daily' || row.every === 'hourly' ? row.every : 'every ' + row.every}, reporting to ${row.owner}`,+ what: `pullboard sentinel approve ${row.name}, or decline it with --reason`, target: `sentinel:${row.name}`,+ ...(row.evidence ? { cause: row.evidence.key, evidence: row.evidence } : {}),+ }));+}+/** Bind approval to every execution and notification field, including schedule and timeout. */export function sentinelDigest(value) {return createHash('sha256').update(JSON.stringify(sentinelDefinition(value))).digest('hex');@@ -52,7 +87,7 @@ export function sentinels(board) {if (detail.engine !== BOARD_SENTINEL_ENGINE) continue;if (event.event_kind === 'sentinel-proposal') {rows.set(detail.row.name, { ...detail.row, digest: detail.digest, status: 'pending', proposedBy: event.event_by,- proposedAt: event.event_at, lastRun: null, activeRun: null, history: [] });+ proposedAt: event.event_at, evidence: detail.evidence ?? null, lastRun: null, activeRun: null, history: [] });continue;}const row = rows.get(detail.name);@@ -90,16 +125,17 @@ function currentSentinel(board, name, digest) {}/** Propose or replace a watch; every replacement becomes pending and loses all prior approval. */-export function proposeSentinel(board, { agentId, row: value }) {+export function proposeSentinel(board, { agentId, row: value, evidence: cited }) {return atomic(board, () => {requireSentinelActor(board, agentId);const row = sentinelDefinition(value);+ const evidence = sentinelEvidence(cited);const agents = listAgents(board);if (row.owner !== 'coordinator' && !agents.some(agent => [agent.agent_id, agent.agent_lane].includes(row.owner))) {throw new Refused('BAD_SENTINEL', 'choose the coordinator, a registered seat or a lane as the sentinel owner');}const digest = sentinelDigest(row);- logEvent(board, agentId, 'sentinel-proposal', null, { row, digest, engine: BOARD_SENTINEL_ENGINE });+ logEvent(board, agentId, 'sentinel-proposal', null, { row, digest, engine: BOARD_SENTINEL_ENGINE, ...(evidence ? { evidence } : {}) });return sentinels(board).find(entry => entry.name === row.name);});}diff --git a/test/sentinels.test.js b/test/sentinels.test.jsindex 98dfe682..08d1827c 100644--- a/test/sentinels.test.js+++ b/test/sentinels.test.js@@ -32,6 +32,11 @@ import { sentinels } from '../src/sentinels.js';import { machineSettingsFile } from '../src/settings.js';import { runFixtureChild } from './fixture-child.js';import { runFixtureGit } from './fixture-child.js';+import { submitFixture } from './board-submit-fixture.js';+import { loadConfig } from '../src/config.js';+import { loadDoctrine } from '../src/doctrine.js';+import { frozenCriterion } from '../src/spec.js';+import { loadSpec } from '../src/spec.js';import { parseProcessCensus } from '../src/process-census.js';import { requireSupportedEngine as requirePublished55Engine } from './fixtures/engine-55-reader.js';@@ -74,7 +79,7 @@ function fixture(t) {store.closeBoard(board); rmSync(directory, { recursive: true, force: true });for (const [key, value] of Object.entries(original)) { if (value === undefined) delete process.env[key]; else process.env[key] = value; }});- return { root, directory, board, agent, clock, ordered, cli,+ return { root, directory, board, agent, clock, ordered, cli, env,run: () => runDueSentinels({ root, board, agentId: 'coordinator', ordered }) };}@@ -87,6 +92,78 @@ function checker(box, source, name = 'check.mjs') {return `${quote(process.execPath)} ${quote(path)}`;}+/**+ * A cause that repeated on two real items, and two real commits that prove a check for it: the check is red where+ * the items failed and green once the fix exists (#776).+ */+function repeatedCause(box) {+ const git = (...args) => runFixtureGit(args, { cwd: box.root, env: box.env, encoding: 'utf8' });+ writeFileSync(join(box.root, 'site.txt'), 'staging is down\n');+ git('add', 'site.txt'); git('commit', '-q', '-m', 'chore: staging down [A6]');+ const red = git('rev-parse', 'HEAD').trim();+ writeFileSync(join(box.root, 'up.txt'), 'staging is up\n');+ git('add', 'up.txt'); git('commit', '-q', '-m', 'chore: staging up [A6]');+ const green = git('rev-parse', 'HEAD').trim();+ const reviewer = store.register(box.board, { lane: 'core', path: join(box.directory, 'reviewer') });+ const config = loadConfig(box.root);+ const freeze = (item) => frozenCriterion(loadSpec(box.root, config), item, loadDoctrine(box.root, config));+ const items = [];+ for (const title of ['Staging first', 'Staging second']) {+ const id = store.addItem(box.board, { by: 'coordinator', lane: 'core', title });+ store.claim(box.board, id, { agentId: box.agent, lane: 'core', leaseMs: 3_600_000, freeze });+ submitFixture(box.board, id, { agentId: box.agent, commit: red, tree: `tree-${red}` });+ store.verify(box.board, id, { agentId: reviewer, decision: 'REJECT', reason: 'TEST_FAILURE', note: 'staging check failed', cause: 'row:A6',+ head: store.getItem(box.board, id).item_commit, digest: store.getItem(box.board, id).item_frozen_digest, policy: 'any' });+ items.push(id);+ }+ return { red, green, items, check: 'test -f up.txt' };+}++test('a repeated cause can be drafted as a sentinel [A6,D1,D3]', async t => {+ const box = fixture(t);+ const cause = repeatedCause(box);+ const spec = readFileSync(join(box.root, 'SPEC.md'), 'utf8');+ const drafted = await box.cli(['rigor', 'draft', 'row:A6', '--sentinel', '--check', cause.check, '--red', cause.red, '--green', cause.green,+ '--every', 'daily', '--owner', 'core']);+ assert.equal(drafted.code, 0, drafted.error);+ const sentinel = drafted.document.sentinel;+ assert.deepEqual([sentinel.name, sentinel.status, sentinel.check, sentinel.every, sentinel.owner], ['rigor-row-a6', 'pending', cause.check, 'daily', 'core'],+ 'the draft is a pending watch with its command, cadence and owner');+ assert.equal(sentinel.evidence.key, 'row:A6');+ assert.deepEqual(sentinel.evidence.items.map(item => item.id), cause.items, 'it cites both repeats');+ assert.equal(sentinel.evidence.occurrences, 2);+ assert.deepEqual([sentinel.evidence.proof.red.commit, sentinel.evidence.proof.green.commit], [cause.red, cause.green], 'and the commits that prove its check');+ assert.deepEqual(drafted.document.drafts, [], 'a sentinel draft writes no spec or doctrine row');+ assert.equal(readFileSync(join(box.root, 'SPEC.md'), 'utf8'), spec);+ const listed = await box.cli(['sentinels']);+ assert.equal(listed.document.sentinels[0].status, 'pending');+ assert.equal(listed.document.sentinels[0].evidence.key, 'row:A6');+ await box.run(); assert.equal(sentinels(box.board)[0].lastRun, null, 'a drafted watch never runs before the person approves it');+});++test('a sentinel draft waits in Needs-you with its evidence [A6,D1,D3]', async t => {+ const box = fixture(t);+ const cause = repeatedCause(box);+ assert.equal((await box.cli(['rigor', 'draft', 'row:A6', '--sentinel', '--check', cause.check, '--red', cause.red, '--green', cause.green])).code, 0);+ // Asking an agent to watch something drafts the same kind of row, with no repeat to cite.+ assert.equal((await box.cli(['sentinel', 'propose', 'staging-site', '--check', 'true', '--every', 'hourly', '--owner', 'core'])).code, 0);+ const pending = (await box.cli(['resume'])).document.needsYou.filter(entry => entry.kind === 'sentinel-draft');+ assert.deepEqual(pending.map(entry => entry.ref).sort(), ['rigor-row-a6', 'staging-site'], 'each pending watch is one Needs-you call');+ const drafted = pending.find(entry => entry.ref === 'rigor-row-a6');+ assert.equal(drafted.cause, 'row:A6');+ assert.deepEqual(drafted.evidence.items.map(item => item.id), cause.items, 'the call carries the repeats it cites');+ assert.equal(drafted.evidence.proof.green.commit, cause.green);+ assert.match(drafted.text, /^Sentinel draft: rigor-row-a6 runs test -f up\.txt hourly, reporting to coordinator$/u);+ assert.match(drafted.what, /pullboard sentinel approve rigor-row-a6/u);+ const approved = await box.cli(['sentinel', 'approve', 'rigor-row-a6'], 'view');+ assert.equal(approved.code, 0, approved.error);+ const after = (await box.cli(['resume'])).document.needsYou.filter(entry => entry.kind === 'sentinel-draft').map(entry => entry.ref);+ assert.deepEqual(after, ['staging-site'], 'the person’s approval closes the call');+ const watched = sentinels(box.board).find(row => row.name === 'rigor-row-a6');+ assert.equal(watched.status, 'approved');+ assert.equal(watched.lastRun?.green, true, 'approving it starts it: the next resume runs the watch, now green');+});+test('an approved sentinel runs by itself and reports to its owner once [A6,D1,D3]', async t => {const box = fixture(t);mkdirSync(join(box.root, 'watch'));