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.

fix(map): publish and exercise its JSON contract [A1,C7]

Corey Olson4f965441e4ed
diff --git a/docs/api.md b/docs/api.md
index 65ec82d6..4223af7d 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -75,6 +75,8 @@ For example: `flow: review wait average 61 min (1 measured; > 60 min); bottlenec
`merged <id> <commit>` records only a commit reachable from the primary checkout's branch that contains the item's submitted commit or has the same stable patch id as the item's change from its claim base. Other commits are refused with `NOT_MERGED`; `--note "why"` records an exceptional receipt and keeps the note in that item's `merged` event.
+`map --json`, `map <module or function> --json`, and `map --for <item> --json` return the same envelope: `main` is the scanned primary-main commit and `map` is the rendered overview, card, or bounded item slice. Ordinary text output is that same map text. The scanner reports unobserved effects as `not detected`; the map is source context, not proof that an effect cannot occur.
+
<!-- api-command-shapes:start -->
`status --json` and local API state carry `ruleCounts`: `approved`, `gated` (approved rows naming a gate), `ungated`, `proven`, `unproven`, and `contradicted`. Proof requires a green configured full-gate receipt on the current trunk whose supported test selection includes the row's test files. Opaque or unsupported coverage remains unproven. Contradicted counts approved rows whose gate files failed on the trunk in the last seven days; it is independent of proven, so a row can count in both after a later green. The API refreshes this window when evidence ages out, even without a board move.
@@ -99,6 +101,7 @@ For example: `flow: review wait average 61 min (1 measured; > 60 min); bottlenec
| `sync` | `version:number`, `ref:string`, `sequence:number`, `pending:string|null` |
| `list` | `version:number`, `items:array` |
| `queue` | `version:number`, `releases:array`, `unreleased:array`, `first:object` |
+| `map` | `version:number`, `main:string`, `map:string` |
| `roadmap` | `version:number`, `milestones:array` |
| `milestone add` | `version:number`, `milestone:object` |
| `milestone items` | `version:number`, `milestone:object` |
diff --git a/src/commands/map.js b/src/commands/map.js
index f463518e..b6968fd0 100644
--- a/src/commands/map.js
+++ b/src/commands/map.js
@@ -35,6 +35,11 @@ export async function run(io, { first, values }) {
throw new Refused('NO_TRUNK', 'pullboard map could not read a clean main source at '
+ trunk.commit.slice(0, 12) + ': ' + error.message + '; restore main/src and bin, then retry');
}
+ /** Keep every map view's JSON envelope explicit while preserving its ordinary text exactly. */
+ function printMap(text) {
+ io.result?.({ main: map.mainCommit, map: text });
+ io.say(text);
+ }
if (values.for !== undefined) {
const id = idArg(values.for, 'an item id after --for');
const item = await withBoardRead(ctx, board => store.getItem(board, id));
@@ -43,7 +48,7 @@ export async function run(io, { first, values }) {
throw new Refused('USAGE', '--budget for an item slice must be a whole number from 1 to 8000 tokens');
}
try {
- io.say(renderItemSlice(map, item, { budget }));
+ printMap(renderItemSlice(map, item, { budget }));
} catch (error) {
if (error instanceof RangeError && error.message.startsWith('item slice budget too small')) {
throw new Refused('USAGE', error.message);
@@ -56,9 +61,9 @@ export async function run(io, { first, values }) {
const card = renderMapCard(map, first);
if (card === null) throw new Refused('USAGE', 'no module or unique function "' + first
+ '" appears in the current map; use pullboard map for the overview');
- io.say(card);
+ printMap(card);
return 0;
}
- io.say(renderCodeMapOverview(map));
+ printMap(renderCodeMapOverview(map));
return 0;
}
diff --git a/src/json.js b/src/json.js
index ceadc671..641ec5b2 100644
--- a/src/json.js
+++ b/src/json.js
@@ -33,6 +33,7 @@ export const JSON_SHAPES = {
sync: shape({ ref: 'string', sequence: 'number', pending: 'string|null' }),
list: shape({ items: 'array' }),
queue: shape({ releases: 'array', unreleased: 'array', first: 'object' }),
+ map: shape({ main: 'string', map: 'string' }),
roadmap: shape({ milestones: 'array' }),
'milestone add': shape({ milestone: 'object' }),
'milestone items': shape({ milestone: 'object' }),
diff --git a/test/api-catalog.test.js b/test/api-catalog.test.js
index fa7533a1..9a4af3d4 100644
--- a/test/api-catalog.test.js
+++ b/test/api-catalog.test.js
@@ -797,6 +797,29 @@ catalogCase('[A1] catalog commands keep their real repository exercises', async
assert.equal(handoff.resume.agent, joined.agent);
});
+catalogCase('[A1,C7] map exposes its main stamp and every rendered view through real CLI JSON', async () => {
+ const box = await project();
+ mkdirSync(join(box.repo, 'src'), { recursive: true });
+ writeFileSync(join(box.repo, 'src/map-fixture.js'), '/** Return a fixture value. */\nexport function mapFixture() { return 1; }\n');
+ await box.git(box.repo, 'add', 'src/map-fixture.js');
+ await box.git(box.repo, 'commit', '-q', '-m', 'test: add the catalog map source');
+ const main = (await box.git(box.repo, 'rev-parse', 'main')).trim();
+ const overview = await json(box, box.repo, 'map');
+ assert.equal(overview.main, main);
+ assert.match(overview.map, /Pullboard code map/u);
+ const card = await json(box, box.repo, 'map', ['mapFixture']);
+ assert.equal(card.main, main);
+ assert.match(card.map, /src\/map-fixture\.js#mapFixture/u);
+ const item = await json(box, box.repo, 'add', ['coordinator', 'Map source', '--specs', 'G1',
+ '--criterion', 'src/map-fixture.js defines mapFixture', '--check', 'true']);
+ const slice = await json(box, box.repo, 'map', ['--for', String(item.item.item_id)]);
+ assert.equal(slice.main, main);
+ assert.match(slice.map, /src\/map-fixture\.js/u);
+ const plain = await box.run(box.repo, 'map', 'mapFixture');
+ assert.equal(plain.status, 0, plain.stderr);
+ assert.equal(plain.stdout, `${card.map}\n`, 'JSON carries exactly the ordinary rendered card');
+});
+
catalogCase('[A1] intake records a real outside pull request through the CLI', async (t) => {
const box = intakeFixture(t);
const document = intakeFixtureJSON(box, box.repo, 'intake', box.pull.html_url,