Repository navigation
Description
Context
Part of #56. Found by the 1.0 surface audit (#319), against main @ 550a41ef.
#56 says: "If something should be stable, it goes in the document before the
version moves." The contract names one consumer of its CLI shapes, the chat
server's CLI client (docs/integration-contract.md:25,
packages/ui-server/src/brain/client.ts). That client and the cron emitter
parse output the contract does not list:
| Command | Parsed where | In the contract? |
|---|---|---|
brain list --json |
client.ts:297, as JSON |
no. Asserted in packages/core/tests/cli-contract.test.ts:77 as "a plain array of documents" |
brain add --json |
client.ts:341; path, indexed, title, type, indexError?, action: created|appended are checked at :352-355 |
no |
brain sync --json |
client.ts:319, as JSON |
no |
brain module list --json |
packages/ui-server/src/cron/emit.ts:31, which feeds a root crontab |
only as a guarantee about cron entries (docs/integration-contract.md:599-604); the payload is not a row |
brain --version |
client.ts:126, parsed as SemVer; the server refuses to boot below a minimum |
no |
Four listed rows are too vague to freeze:
brain audit --jsonis{ "issues": AuditIssue[], ... }(:46). The...
is not a shape, andAuditIssueis never spelled out.brain indexis a "stats object" (:49).brain init --checkis a "preflight object" (:51). Only itsconfigblock
is specified.- The MCP tools' "input schemas are stable" (
:201), but the schemas are not
written down, andpackages/core/tests/mcp-contract.test.tspins names and
annotations, not schemas.structuredContentis asserted forbrain_search
andbrain_listonly (:69-97), not forbrain_context,brain_reador
brain_graph.
Three listed rows are specified but asserted only below the CLI:
brain graph stats|compute|export --json (:55-57). packages/core/tests/graph.test.ts
checks getGraphStats() and getMaintenanceFindings(). The CLI envelopes the
contract describes are not checked.
Scope
- Add contract rows for
list --json,add --json,sync --json,
module list --jsonand the--versionoutput, documenting what they emit
today. - Spell out
AuditIssueand the fullaudit --jsonenvelope, theindex
stats object and theinit --checkpreflight object. - Pin the eight MCP tools' input schemas with a checked-in snapshot that a
change must update on purpose, and assertstructuredContentfor
brain_context,brain_readandbrain_graph. - Assert each new or clarified row, and the three
graphenvelopes, through
the CLI inpackages/core/tests/cli-contract.test.ts.
Out of scope
- Changing any shape. If documenting a shape shows it should change before 1.0
(a bare array with no room forwarnings, for example), file that as its own
issue with thebreakinglabel for a maintainer ruling. - HTTP routes, config and environment variables. Whether they are contract
surface is docs: decide what 1.0 freezes where the contract document does not say #343's question. - Commands the named consumer does not parse.
Acceptance criteria
-
docs/integration-contract.mdhas a row for each command in the first
table, and the four vague rows are spelled out field by field. - The MCP input schema snapshot is checked in, and the test fails when one
tool's schema changes without the snapshot being updated. The mutation is
recorded in the PR. - Each new CLI assertion fails when its field is removed from the command's
output. One mutation per row, with the failing assertion, is recorded in
the PR.
Verification
bun run test; the mutation receipts in the PR.
Contract impact
- This touches the integration contract, so it needs the
contractlabel, aCONTRACT:commit prefix, and the doc updated in the same commit. - This changes a published package's behaviour, so it needs a changeset.
Additive: it documents shapes that already ship.
Activity
CONTRACT: docs: list the CLI shapes brain-ui parses, and spell out th…
CONTRACT: docs: list the CLI shapes brain-ui parses, and spell out th…