Skip to content

core: the contract omits CLI shapes its own consumer parses, and four rows are too vague to freeze #345

Closed

Description

@schlessera

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 --json is { "issues": AuditIssue[], ... } (:46). The ...
    is not a shape, and AuditIssue is never spelled out.
  • brain index is a "stats object" (:49).
  • brain init --check is a "preflight object" (:51). Only its config block
    is specified.
  • The MCP tools' "input schemas are stable" (:201), but the schemas are not
    written down, and packages/core/tests/mcp-contract.test.ts pins names and
    annotations, not schemas. structuredContent is asserted for brain_search
    and brain_list only (:69-97), not for brain_context, brain_read or
    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 --json and the --version output, documenting what they emit
    today.
  • Spell out AuditIssue and the full audit --json envelope, the index
    stats object and the init --check preflight object.
  • Pin the eight MCP tools' input schemas with a checked-in snapshot that a
    change must update on purpose, and assert structuredContent for
    brain_context, brain_read and brain_graph.
  • Assert each new or clarified row, and the three graph envelopes, through
    the CLI in packages/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 for warnings, for example), file that as its own
    issue with the breaking label 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.md has 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 contract label, a CONTRACT: 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

  1. added
    area: corepackages/core: the brain CLI, indexer, hybrid search, config, taxonomy, skills.
    area: mcpThe stdio MCP server and its brain_* tools.
    agent-readyContext and acceptance criteria are complete enough for an agent to take this unattended.
    contractTouches the integration contract: CONTRACT: commit, contract doc updated in the same commit.
    on Sep 25, 2026
  2. added 2 commits that reference this issue on Sep 25, 2026
    9e7fa93
    718df85
  3. added this to the 0.38.0 milestone on Oct 9, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    agent-readyContext and acceptance criteria are complete enough for an agent to take this unattended.area: corepackages/core: the brain CLI, indexer, hybrid search, config, taxonomy, skills.area: mcpThe stdio MCP server and its brain_* tools.contractTouches the integration contract: CONTRACT: commit, contract doc updated in the same commit.type: docsDocumentation only.

    Projects

    No projects

      Milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions