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: require checked architecture rule coverage [H19]

Corey Olson9b2915f0dd46
diff --git a/src/blueprints.js b/src/blueprints.js
index 5763cfde..89337e44 100644
--- a/src/blueprints.js
+++ b/src/blueprints.js
@@ -26,7 +26,9 @@
* BLUEPRINT_ITEM_UNCHECKED when it is read or saved: a starter that cannot be verified cannot be
* accepted. Every rule of an architecture blueprint names its source, or the blueprint is refused
* with BLUEPRINT_NO_SOURCE when it is read or saved: an architecture rule paraphrases a known-good
- * reference, so the row it drafts must say which one. An item's route is light, mid or strong (strong when left out), as pullboard add takes
+ * reference, so the row it drafts must say which one. Every must rule is cited by a checked starter
+ * item, or an architecture blueprint is refused with BLUEPRINT_RULE_UNCHECKED; aim rules are optional.
+ * An item's route is light, mid or strong (strong when left out), as pullboard add takes
* it. Its brief and criterion pass through unchanged; bundled checks use the chosen lane folder. A light or mid item is filed when it
* carries what add requires for that route and refused with add's own refusal when it does not.
* A check is stored on the item and never run during add: no check baseline starts, so nothing a
@@ -233,6 +235,7 @@ export function validateBlueprint(value, source = 'blueprint') {
}
refuseUnsourcedRules(value.name, kind, rules);
refuseUncheckedItems(value.name, items);
+ refuseUncheckedArchitectureRules(value.name, kind, rules, items);
return {
...value,
...(kind === undefined ? {} : { kind }),
@@ -288,6 +291,27 @@ function refuseUncheckedItems(name, items) {
}
}
+/**
+ * Refuse an architecture blueprint whose must rule has no checked starter item citing it.
+ * Aim rules are optional; other blueprint kinds keep their existing meaning.
+ *
+ * @param {string} name - The blueprint's name, already checked.
+ * @param {string | undefined} kind - The blueprint's kind, with old names already mapped.
+ * @param {{ key: string, text: string, tier?: string }[]} rules
+ * @param {{ key: string, title: string, cites?: string[], check?: string }[]} items
+ * @returns {void}
+ */
+function refuseUncheckedArchitectureRules(name, kind, rules, items) {
+ if (kind !== 'architecture') return;
+ for (const rule of rules) {
+ if ((rule.tier ?? 'must') !== 'must') continue;
+ const covered = items.some((item) => (item.cites ?? []).includes(rule.key)
+ && typeof item.check === 'string' && item.check.trim());
+ if (covered) continue;
+ throw new Refused('BLUEPRINT_RULE_UNCHECKED', `architecture blueprint ${name} must rule ${rule.key} (${JSON.stringify(rule.text)}) has no checked starter item citing it; add a starter item with cites: [${JSON.stringify(rule.key)}] and a criterion and check command, then run pullboard blueprint add again`);
+ }
+}
+
/**
* The marker line a blueprint leaves after its rows once everything is added, so the same version
* adds nothing twice even after the person rewords or declines its rows.
diff --git a/src/next-step-defaults.js b/src/next-step-defaults.js
index e75f3dca..7ba3c004 100644
--- a/src/next-step-defaults.js
+++ b/src/next-step-defaults.js
@@ -86,6 +86,7 @@ export const DEFAULT_NEXT_STEPS = Object.freeze({
"BAD_SINCE": "pass a date: --since 2026-10-08",
"BLUEPRINT_EXISTS": "choose a file that does not exist: pullboard blueprint save <new-file>",
"BLUEPRINT_ITEM_UNCHECKED": "give the starter item named in the message a criterion and a check command, then run pullboard blueprint add <file> again",
+ "BLUEPRINT_RULE_UNCHECKED": "add a checked starter item that cites the must rule named in the message, then run pullboard blueprint add <file> again",
"BLUEPRINT_KIND_TAKEN": "keep at most one product and one architecture blueprint, then run the same command again",
"BLUEPRINT_NOT_ADDED": "add the blueprint to this board first: pullboard blueprint add <name or file>",
"BLUEPRINT_NO_SOURCE": "give the rule named in the message the reference it paraphrases as source { name, id, url }, then run pullboard blueprint add <file> again",
diff --git a/test/blueprint.test.js b/test/blueprint.test.js
index 281629ed..bca11b5e 100644
--- a/test/blueprint.test.js
+++ b/test/blueprint.test.js
@@ -369,12 +369,13 @@ test("an architecture blueprint's rows each arrive with a check that runs red be
`${item.item_title} check is green after its fixture is built`);
}
const uncovered = { ...blueprint, name: 'uncovered-edge-api', items: [blueprint.items[0]] };
- writeFileSync(join(box.repo, 'uncovered-edge-api.json'), `${JSON.stringify(uncovered)}\n`);
- const before = readFileSync(join(box.repo, 'SPEC.md'), 'utf8');
- const refused = box.run('blueprint', 'add', 'uncovered-edge-api.json', '--json');
+ const uncoveredBox = freshBoard({ gate: 'true' });
+ writeFileSync(join(uncoveredBox.repo, 'uncovered-edge-api.json'), `${JSON.stringify(uncovered)}\n`);
+ const before = readFileSync(join(uncoveredBox.repo, 'SPEC.md'), 'utf8');
+ const refused = uncoveredBox.run('blueprint', 'add', 'uncovered-edge-api.json', '--json');
assert.equal(refused.status, 1, refused.stdout + refused.stderr);
assert.equal(JSON.parse(refused.stdout).error.code, 'BLUEPRINT_RULE_UNCHECKED');
- assert.equal(readFileSync(join(box.repo, 'SPEC.md'), 'utf8'), before, 'a missing must-row check writes nothing');
+ assert.equal(readFileSync(join(uncoveredBox.repo, 'SPEC.md'), 'utf8'), before, 'a missing must-row check writes nothing');
});
test('an architecture must-row without a checked starter item is refused at add [S1,I1]', () => {
@@ -387,6 +388,10 @@ test('an architecture must-row without a checked starter item is refused at add
assert.equal(JSON.parse(refused.stdout).error.code, 'BLUEPRINT_RULE_UNCHECKED');
assert.equal(readFileSync(join(box.repo, 'SPEC.md'), 'utf8'), before, 'the blueprint is refused before writing rows');
assert.equal(json(box, 'list', '--all').items.length, 0, 'no starter item is filed');
+
+ const aimOnly = { ...SOURCED, name: 'optional-aim', rules: [SOURCED.rules[0], { ...SOURCED.rules[1], tier: 'aim' }], items: [SOURCED.items[0]] };
+ writeFileSync(join(box.repo, 'optional-aim.json'), `${JSON.stringify(aimOnly)}\n`);
+ assert.equal(json(box, 'blueprint', 'add', 'optional-aim.json').blueprint.name, 'optional-aim', 'an uncovered aim row is optional');
});
test('a drafted row records its rule source [S1,I1]', () => {