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(gate): a gate that refuses every run is an alarm [C7,D1]
Corey Olsonec5c235b5fd1
diff --git a/docs/api.md b/docs/api.mdindex 92ecace8..a4e092f7 100644--- a/docs/api.md+++ b/docs/api.md@@ -198,6 +198,8 @@ For HTTP `next`, a review offer returns success with `event: null`, `offer` and- `key` names the cause and what is stuck, like `CLAIM_LAPSED:item:12`, `HOLD_STALE:lane:docs`, `DECISION_UNANSWERED:shout:40` or `RELEASE_OVERDUE:release:v0.9.0`; it stays the same while the finding persists, so a watcher can post it once and notice when it clears.- `item` is the item id, or `null` for a lane hold, a decision or a release; `subject` is the same thing as text (`#12`, `lane docs`, `decision #40`, `release v0.9.0`).- `since` is when the wait began, in ISO time; `ageMinutes` counts whole minutes from it to `asOf`.++A gate has its own two alarms, which need no board. Each real `pullboard gate` run appends a line to `pullboard-gate-runs.jsonl` in the git directory, with its result and, when `pullboard.json` declares `positiveControl`, that known-good command's result. `GATE_CONTROL_FAILED:gate` is stuck when the last run's positive control failed. `GATE_REFUSED_EVERY_RUN:gate` is stuck when the runs in the last day were all refused, and there are at least three of them. Each carries the gate, its control and its last five runs in `detail`; its `command` is `pullboard gate` for the refusal alarm.- `why` and `next` are plain sentences; `command` is the exact command for the next step, or `null` when the step has none.- `owner.role` is `builder`, `reviewer`, `coordinator` or `person`; `owner.who` is the agent, lane, `coordinator` or `person`, and `null` when any reviewer may take it.- `detail` holds the cause's facts: `holder`, `reviewer`, `builder`, `commit`, `files` and `trunk` for a conflict, `parent` for a stacked item, `reason` and `by` for a hold, `withdrawn`, `after`, `move` and `milestone`, `shout`, `from` and `to`, or `release` and `landed`.diff --git a/src/config.js b/src/config.jsindex fb74f5ba..81779c58 100644--- a/src/config.js+++ b/src/config.js@@ -172,6 +172,9 @@ export function configProblems(config) {problems.push('"landingShards" is a whole number from 1 to 64: how many shards the landing gate splits its test files into');}if (typeof config.staticChecks !== 'string') problems.push('"staticChecks" is an optional project static-check command');+ if (config.positiveControl !== undefined && (typeof config.positiveControl !== 'string' || !config.positiveControl.trim())) {+ problems.push('"positiveControl" is a nonempty command for a known-good case the gate must pass, like "node --test test/known-good.test.js"');+ }if (config.affectedTests !== undefined && (typeof config.affectedTests !== 'string' || !config.affectedTests.trim())) {problems.push('"affectedTests" is a nonempty command prefix used to run selected test files');}diff --git a/src/gate-control.js b/src/gate-control.jsnew file mode 100644index 00000000..ebb8c59d--- /dev/null+++ b/src/gate-control.js@@ -0,0 +1,91 @@+/**+ * Gate runs and their positive controls [C7,D1]. Every real gate run appends one line to the checkout's git+ * directory; health reads those lines. A gate that refuses every run in its window, or whose known-good case+ * (the project's positiveControl) fails, is an alarm: it can no longer prove that it can pass.+ */+import {+ appendFileSync,+ existsSync,+ readFileSync,+} from 'node:fs';+import { gitPath } from './git.js';++/** The append-only record of real gate runs, kept in the git directory so it never enters a commit. */+export const GATE_RUNS_FILE = 'pullboard-gate-runs.jsonl';+/** How far back a run counts toward "refused every run": one day. */+export const GATE_WINDOW_MS = 86_400_000;+/** The fewest refused runs in the window that make a refusal an alarm, so one bad run is not news. */+export const GATE_MIN_RUNS = 3;+/** How many of the last runs an alarm carries, so its reader sees the pattern without opening the log. */+const LAST_RUNS = 5;++/**+ * Append one real gate run to the record. A run that the environment refused is not a gate result, so the+ * caller leaves it out.+ *+ * @param {string} root the checkout whose gate ran+ * @param {{ at: string, green: boolean, control: boolean | null, gate: string, positiveControl: string | null }} run+ */+export function recordGateRun(root, run) {+ appendFileSync(gitPath(root, GATE_RUNS_FILE), `${JSON.stringify(run)}\n`);+}++/**+ * Read every recorded gate run, oldest first. A missing file is no runs yet; a torn or foreign line is skipped,+ * since one bad line must not hide the rest of the record.+ *+ * @param {string} root+ * @returns {Array<{ at: string, green: boolean, control: boolean | null, gate: string, positiveControl: string | null }>}+ */+export function gateRuns(root) {+ const file = gitPath(root, GATE_RUNS_FILE);+ if (!existsSync(file)) return [];+ return readFileSync(file, 'utf8').split('\n').flatMap((line) => {+ try {+ const run = JSON.parse(line);+ return run && typeof run.at === 'string' && typeof run.green === 'boolean' ? [run] : [];+ } catch {+ return [];+ }+ });+}++/**+ * The gate alarms health reports: the last gate run's positive control failed, or every run in the window was+ * refused (at least GATE_MIN_RUNS of them). Each carries the gate, its control and its last runs; neither ever+ * reads as green.+ *+ * @param {string} root+ * @param {{ gate?: string, positiveControl?: string }} config+ * @param {Date} now+ * @returns {Array<object>} findings in the shape health reports+ */+export function gateControlFindings(root, config, now) {+ const runs = gateRuns(root);+ if (!runs.length) return [];+ const lastRuns = runs.slice(-LAST_RUNS);+ const detail = { gate: config.gate ?? '', positiveControl: config.positiveControl ?? null, runs: lastRuns };+ const alarms = [];+ const last = runs.at(-1);+ if (last.control === false) {+ alarms.push({+ key: 'GATE_CONTROL_FAILED:gate', cause: 'GATE_CONTROL_FAILED', item: null, subject: 'gate',+ title: 'gate positive control failed', since: last.at,+ why: `the gate's positive control "${config.positiveControl}" failed on its last run, so the gate can no longer be trusted to pass a good change`,+ next: 'fix the known-good case named by positiveControl in pullboard.json, or the gate it proves',+ command: null, owner: { role: 'coordinator', who: 'coordinator' }, detail,+ });+ }+ const windowStart = now.getTime() - GATE_WINDOW_MS;+ const recent = runs.filter((run) => Date.parse(run.at) >= windowStart);+ if (recent.length >= GATE_MIN_RUNS && recent.every((run) => !run.green)) {+ alarms.push({+ key: 'GATE_REFUSED_EVERY_RUN:gate', cause: 'GATE_REFUSED_EVERY_RUN', item: null, subject: 'gate',+ title: 'gate refused every run', since: recent[0].at,+ why: `the gate refused all ${recent.length} runs in the last day, so it refuses everything and proves nothing`,+ next: 'run pullboard gate and fix the failure it names, or check the gate command in pullboard.json',+ command: 'pullboard gate', owner: { role: 'coordinator', who: 'coordinator' }, detail,+ });+ }+ return alarms.map((alarm) => ({ ...alarm, ageMinutes: Math.max(0, Math.floor((now.getTime() - Date.parse(alarm.since)) / 60_000)) }));+}diff --git a/src/gate.js b/src/gate.jsindex e44d7670..8920f7cf 100644--- a/src/gate.js+++ b/src/gate.js@@ -40,6 +40,7 @@ import {isClean,untracked,} from './git.js';+import { recordGateRun } from './gate-control.js';import { secretsIn } from './hooks.js';import { Refused } from './refused.js';import { missingGate } from './gate-config.js';@@ -560,11 +561,28 @@ function fullGateRun(root, config, trustStamp = false, { waitMs = 0, log = gitPaconst run = runProfiledShell(root, config.gate, { waitMs, pipefail: true, profileFile: `${log}.profile.json`, gateLease, landing, stages, waivers });const { isGreen, output, seconds, profile, profilePath } = run;writeFileSync(log, output);+ // The environment refusing a run says nothing about the gate, so only a real result is recorded (U41).+ if (!run.sandboxBlocked) recordGateRun(root, gateRunRecord(root, config, isGreen));refuseSandboxBlocked(run);if (isGreen && before !== null && committedTree(root) === before) writeFileSync(gitPath(root, STAMP), `${before}\n`);return { isGreen, isCached: false, output, seconds, log, profile, profilePath, ...(run.executionRoot ? { executionRoot: run.executionRoot } : {}), ...(stages ? { stages: run.stages } : {}) };}+/**+ * The record one real gate run leaves for health: its result, and the positive control's result when the project+ * declares one, so a gate that stops passing its known-good case shows up without a person reading the log.+ *+ * @param {string} root+ * @param {{ gate: string, positiveControl?: string }} config+ * @param {boolean} isGreen whether the gate itself passed+ * @returns {{ at: string, green: boolean, control: boolean | null, gate: string, positiveControl: string | null }}+ */+function gateRunRecord(root, config, isGreen) {+ const positiveControl = config.positiveControl?.trim() ? config.positiveControl : null;+ const control = positiveControl ? runShell(root, positiveControl).isGreen : null;+ return { at: new Date().toISOString(), green: isGreen, control, gate: config.gate, positiveControl };+}+/** Quote a fixed executable or selected path without permitting shell expansion. */function commandWord(value) {return `'${String(value).replaceAll("'", "'\\''")}'`;diff --git a/src/health.js b/src/health.jsindex fbdb2c7c..77ed784a 100644--- a/src/health.js+++ b/src/health.js@@ -15,6 +15,7 @@ import {mainCheckout,tryGit,} from './git.js';+import { gateControlFindings } from './gate-control.js';import {boardBusyError,openBoardReadOnly,@@ -77,6 +78,8 @@ export function healthReport({ db, root, config, now }) {const limits = healthThresholds(config);const asOf = now.toISOString();const report = { asOf, thresholds: { stuck: limits.stuck, holds: limits.holds, release: limits.release }, stuck: [], waiting: [] };+ // Gate alarms read the git directory, so they report even before a board exists (U41).+ report.stuck.push(...gateControlFindings(root, config ?? {}, now));if (!db) return report;const at = now.getTime();const age = (iso) => at - Date.parse(iso);diff --git a/test/health.test.js b/test/health.test.jsindex 8ddaa685..036ee252 100644--- a/test/health.test.js+++ b/test/health.test.js@@ -299,3 +299,48 @@ test('item history survives garbage collection mid-read [A6]', () => {assert.equal(child.status, 0, `reading item history must not lose its statement to garbage collection: ${child.stderr}`);assert.equal(child.stdout, '50', 'every item with events has a history entry');});++/** Commit a pullboard.json whose gate, and optional positive control, the next gate run reads. */+function commitPolicy(box, policy) {+ writeFileSync(join(box.root, 'pullboard.json'), `${JSON.stringify({ gate: 'true', lanes: { core: { owns: ['src/'] }, docs: { owns: ['docs/'] }, review: { owns: [] } }, ...policy }, null, 2)}\n`);+ box.git(['add', 'pullboard.json']);+ box.git(['commit', '-q', '-m', 'chore: gate policy']);+}++/** Health at the real clock, since a gate run records the moment it actually ran. */+async function healthNow(cwd) {+ let stdout = '';+ const code = await main(['health', '--json'], {+ cwd, stdout: { isTTY: false, write: (text) => { stdout += text; } }, stderr: { write: () => {} },+ });+ return { code, report: JSON.parse(stdout) };+}++test('health reports a gate whose positive control fails [C7,D1]', async (t) => {+ const box = repo(t);+ commitPolicy(box, { gate: 'true', positiveControl: 'false' });+ const ran = await cli(box.root, ['gate']);+ assert.equal(ran.code, 0, 'the gate itself is green, so only its known-good case betrays it');+ const { code, report } = await healthNow(box.root);+ assert.equal(code, 1, 'a failing positive control is stuck work, not green');+ const alarm = report.stuck.find((entry) => entry.cause === 'GATE_CONTROL_FAILED');+ assert.ok(alarm, 'health names the gate whose positive control failed');+ assert.equal(alarm.subject, 'gate');+ assert.match(alarm.why, /positive control/u);+ assert.equal(alarm.detail.positiveControl, 'false');+ assert.equal(alarm.detail.runs.at(-1).control, false, 'the finding carries the last run and its control result');+});++test('health reports a gate that refused every run [C7,D1]', async (t) => {+ const box = repo(t);+ commitPolicy(box, { gate: 'false' });+ for (let run = 1; run <= 2; run += 1) assert.equal((await cli(box.root, ['gate'])).code, 1, `run ${run} is refused`);+ assert.equal((await healthNow(box.root)).report.stuck.some((entry) => entry.cause === 'GATE_REFUSED_EVERY_RUN'), false, 'two refusals are not yet an alarm');+ assert.equal((await cli(box.root, ['gate'])).code, 1, 'run 3 is refused');+ const { code, report } = await healthNow(box.root);+ assert.equal(code, 1);+ const alarm = report.stuck.find((entry) => entry.cause === 'GATE_REFUSED_EVERY_RUN');+ assert.ok(alarm, 'health names a gate that refused every run in its window');+ assert.equal(alarm.subject, 'gate');+ assert.deepEqual(alarm.detail.runs.map((run) => run.green), [false, false, false], 'the finding lists the last runs, all refused');+});