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.

7.9 KB
Raw Blame
/** A decision records where it came from, and pullboard why <file> names the decisions behind a file [N29,B29,P6]. */
import assert from 'node:assert/strict';
import { readFileSync, writeFileSync } from 'node:fs';
import { join } from 'node:path';
import { after, test } from 'node:test';
import * as store from '../src/board.js';
import { createE2eHelpers } from './e2e-helpers.js';
import { minimumMoveEngine } from '../src/move-registry.js';
import { DECISION_ORIGIN_ENGINE } from '../src/decision-origin-engine.js';
import { originOf } from '../src/decision-origin.js';
import { whyFile } from '../src/why-file.js';

const e2e = createE2eHelpers();
after(e2e.cleanup);

/** Real Git/SQLite items use public submit, verdict and native landing before file history is queried. */
function fixture() {
  const box = e2e.project('true');
  const config = JSON.parse(readFileSync(join(box.repo, 'pullboard.json'), 'utf8'));
  config.landing = { publish: 'separate' };
  writeFileSync(join(box.repo, 'pullboard.json'), JSON.stringify(config, null, 2));
  const seed = e2e.commitFile(box, box.repo, 'web/shared.txt', 'one\ntwo\nthree\n', 'chore: configure private why landing');
  assert.equal(seed.status, 0, seed.stderr);
  const other = e2e.commitFile(box, box.repo, 'web/other.txt', 'other\n', 'chore: seed other why history');
  assert.equal(other.status, 0, other.stderr);
  box.git(box.web, 'merge', '-q', '--ff-only', 'main');
  /** Return one public JSON result only after its native command succeeds. */
  function json(cwd, ...args) {
    const result = box.run(cwd, ...args, '--json');
    assert.equal(result.code, 0, `${args.join(' ')}: ${result.err}${result.out}`);
    return JSON.parse(result.out);
  }
  for (const [index, title] of ['First item', 'Second item'].entries()) {
    json(box.repo, 'add', 'web', title, '--specs', 'G1', '--criterion', `${title} exists`,
      '--check', `test -f web/built-${index + 1}`);
  }
  /** Land an actual submitted item, preserving its item trailer and durable merge receipt. */
  function landItem(id, file, text) {
    box.git(box.web, 'merge', '-q', '--ff-only', 'main');
    json(box.web, 'claim', String(id));
    const result = e2e.commitFile(box, box.web, file, text, `feat(web): build why item ${id} [G1]`);
    assert.equal(result.status, 0, result.stderr);
    const flag = e2e.commitFile(box, box.web, `web/built-${id}`, 'built\n', `feat(web): complete why item ${id} [G1]`);
    assert.equal(flag.status, 0, flag.stderr);
    const submitted = json(box.web, 'submit', String(id));
    box.git(box.repo, 'switch', '-q', '--detach', submitted.commit);
    try { json(box.repo, 'verify', String(id), 'accept', '--as', 'coordinator', '--note', 'The committed result exists.'); }
    finally { box.git(box.repo, 'switch', '-q', 'main'); }
    assert.deepEqual(json(box.repo, 'land').landed, [id]);
  }
  return { ...box, json, landItem };
}

test('a decision records its origin and pullboard why names the decisions behind a file [N29,B29,P6]', () => {
  const box = fixture();
  const web = box.web;

  const ask = box.json(web, 'shout', 'coordinator', 'Keep line two upper case?', '--decision').id;
  const answer = box.json(box.repo, 'answer', String(ask), 'Keep it upper case', '--implies', '1',
    '--origin', 'person-relayed', '--rationale', 'the person wants it to read as a heading').id;
  const askOther = box.json(web, 'shout', 'coordinator', 'Change the other file?', '--decision').id;
  const answerOther = box.json(box.repo, 'answer', String(askOther), 'Change it', '--implies', '2').id;

  const inheritedAsk = box.json(web, 'shout', 'coordinator', 'Keep the inherited convention?', '--decision').id;
  const inherited = box.json(box.repo, 'answer', String(inheritedAsk), 'Keep the convention', '--implies', '2',
    '--origin', 'inherited', '--rationale', 'the earlier design supplies no named decider').id;
  const personAsk = box.json(box.repo, 'shout', 'person', 'Approve the other change?', '--decision').id;
  const person = box.json(box.repo, 'answer', String(personAsk), 'I approve this change', '--as', 'person', '--implies', '2').id;

  const third = box.json(web, 'shout', 'coordinator', 'One more?', '--decision').id;
  const forged = box.run(box.repo, 'answer', String(third), 'x', '--origin', 'person');
  assert.notEqual(forged.code, 0, 'an agent cannot name the person as the origin');
  assert.match(forged.err, /BAD_ORIGIN/u);

  box.landItem(1, 'web/shared.txt', 'one\nTWO\nthree\n');
  box.landItem(2, 'web/other.txt', 'other, changed\n');

  const file = box.json(box.repo, 'why', 'web/shared.txt');
  assert.equal(file.file, 'web/shared.txt');
  assert.deepEqual(file.items.map((item) => item.id), [1], 'only the item whose landed commit touched the file');
  assert.deepEqual(file.rows.map((row) => row.id), ['G1']);
  assert.equal(file.decisions.length, 1, 'only the decision implying that item');
  assert.deepEqual({ id: file.decisions[0].id, statement: file.decisions[0].statement, rationale: file.decisions[0].rationale,
    decidedBy: file.decisions[0].decidedBy, relayedBy: file.decisions[0].relayedBy, origin: file.decisions[0].origin },
  { id: answer, statement: 'Keep it upper case', rationale: 'the person wants it to read as a heading',
    decidedBy: 'unknown', relayedBy: 'coordinator', origin: 'person-relayed' });

  const text = box.run(box.repo, 'why', 'web/shared.txt');
  assert.equal(text.code, 0, text.err);
  assert.match(text.out, /person-relayed/u);
  assert.match(text.out, /Keep it upper case/u);

  assert.deepEqual(box.json(box.repo, 'why', 'web/shared.txt:2').items.map((item) => item.id), [1], 'the changed line');
  assert.deepEqual(box.json(box.repo, 'why', 'web/shared.txt:1').items, [], 'a line no landed commit touched');
  const other = box.json(box.repo, 'why', 'web/other.txt');
  assert.deepEqual(other.decisions.map((entry) => [entry.id, entry.origin, entry.decidedBy]),
    [[answerOther, 'agent', 'coordinator'], [inherited, 'inherited', 'unknown'], [person, 'person', 'person']],
    'actual person answers and agent answers retain their authority; an inherited decider stays unknown');

  const board = store.openBoard(join(box.repo, '.git', 'pullboard', 'board.sqlite'));
  try {
    let queries = 0;
    const db = { prepare(sql) { queries += 1; return board.db.prepare(sql); } };
    assert.deepEqual(whyFile({ ...board, db }, box.repo, 'web/shared.txt').items.map(item => item.id), [1]);
    assert.equal(queries, 1, 'items, rows and answers resolve in one board query');
  } finally { store.closeBoard(board); }

  assert.equal(originOf({}), 'unknown', 'a decision with no recorded origin is unknown');
  assert.equal(originOf({ provenance: { origin: 'inherited' } }), 'inherited');
  assert.equal(box.json(box.repo, 'why', 'web/missing.txt').items.length, 0, 'a file no commit touched has nothing behind it');
  const pending = box.json(box.repo, 'add', 'web', 'Not landed', '--specs', 'G1', '--criterion', 'Pending exists', '--check', 'test -f web/not-landed').item.item_id;
  box.git(web, 'merge', '-q', '--ff-only', 'main');
  box.json(web, 'claim', String(pending));
  const unlanded = e2e.commitFile(box, web, 'web/shared.txt', 'one\nUNLANDED\nthree\n',
    `feat(web): pending change [G1]\n\nPullboard-Item: #${pending}`);
  assert.equal(unlanded.status, 0, unlanded.stderr);
  assert.deepEqual(box.json(web, 'why', 'web/shared.txt').items.map(item => item.id), [1],
    'a builder checkout cannot present its unlanded history as the primary branch');

});


test('decision origin and rationale retain their floor when an answer implies an item [H16,N29]', () => {
  for (const detail of [{ origin: 'agent' }, { rationale: 'the recorded reason' }]) {
    for (const options of [{ implies: [1] }, { cause: 'conflict:src/fixture.js' }, { cause: 'sentinel:fixture' }]) {
      const args = [1, { agentId: 'coordinator', text: 'Keep the change', ...options, ...detail }];
      assert.ok(minimumMoveEngine('answerDecision', args) >= DECISION_ORIGIN_ENGINE,
        `every mixed answer retains its recorded origin meaning: ${JSON.stringify(args)}`);
    }
  }
});