Skip to content

I1026 — The architecture explains itself, from inside itself

Document the graph, its sources, its relation model, its two projections and the contributor workflow, and let the interface say how it was generated and from what.

BLOCKED wave 4 · p1 · implementation profile · parallel safe

Part of capability-graph — One capability graph, two projections, and no second inventory of what this repository can do.

Blocked. This issue cannot start until I1012 is done. The status is derived from that, not declared.

Objective

Document the graph, its sources, its relation model, its two projections and the contributor workflow, and let the interface say how it was generated and from what.

Why

The whole promise is that a contributor registers a capability in one place and everything follows. That promise is only usable if the one place is written down, and the interface itself is the most reliable location for its own provenance.

Current state

The Cockpit has a document. The composed graph, the relation model and the contributor workflow have none.

Desired state

One architecture document, reachable from the places a reader starts, and an interface that states its own mode, sources and revision.

Scope

  • docs/COCKPIT.md

Out of scope

  • Duplicating the ADR's reasoning in prose
  • Repeating full instructions in every directory document instead of composing them

Dependencies

What waits on this

Acceptance criteria

  • The document explains the sources, the relation model, both projections, the conditional exposure of runtime surfaces, how a new capability appears without an edit, the rules, the skill and how to debug a missing node
  • The interface states its own mode, its sources, its schema version and its build revision from safe metadata
  • It is reachable from the root document, the architecture documents and the interface itself, through existing cross-linking rather than a hand-written list
  • Any new directory this milestone creates carries its context document per the directory contract

Validation

  • bash test/run.sh
  • bin/majordomus doctor

Evidence required

  • architecture_documented
  • self_documenting

Evidence

None recorded. Every token above needs a command or an artifact behind it before this issue can be completed; narrative is refused.

Risk

A document explaining a derivation goes stale faster than the derivation. Every value it states about the current repository is generated rather than typed.

Timeline

started
—
verified
—
completed
—

Those three fields, the evidence above and the state of the dependencies are all the status is made of. There is no status field to disagree with them.

Canonical record: .ai/repo/project/issues/I1026.yaml. Read it back with majordomus plan show I1026.