Skip to content

0042. cordana: integrate the P1 knowledge and execution spine

  • Status: accepted
  • Date: 2026-07-17
  • Deciders: lusoris
  • Related: PR #2620, PR #2619

Context

The Cluster 2.0 / cordana program had accumulated its P1 foundation across many separately validated work units: the planning authority and capability/authority map, repository lifecycle and routing cleanup, typed knowledge-registry admission, canonical-JSON conformance, evidence delivery, and the P1-SRC-02 reviewed Argo source acceptance. These existed as reviewed units but were not integrated into the repository, so none of their guarantees were enforced by the repo's own gate.

The program's own traceability register (.workingdir2/cluster-2/12-adr-traceability.md) is explicit that it does not want per-decision ADRs yet: every design area is listed as Proposed, and the rule is that "no placeholder ADR is created until its decision is stable enough to be durable". This ADR therefore does not attempt to record the individual design decisions in that register. It records the one decision that is durable and already in force: how the P1 spine lands in this repository, and what authority it does and does not carry.

That distinction was the load-bearing concern. A knowledge registry that can silently promote its own outputs is an authority-laundering machine — generated candidates become cited fact without a review step. The integration had to make "has zero authority" the enforced default rather than a documented intention.

Decision

Land the validated P1 foundation as one reviewable branch, structured around four in-tree artifacts, each backed by a repo gate.

Knowledge registry (knowledge/, tools/knowledge-registry/). Versioned schemas and reviewed records are tracked in-tree; generated candidates, captures, indexes and caches are not, and must be written below a declared ignored run root until a separate reviewed change admits them. The discovery tooling is observation-only and forces every output to candidate / unreviewed and ineligible for compilation or promotion. It cannot acquire or admit source material, publish a retrieval release, sign a candidate, move a current/previous pointer, or change a cluster. Outputs are created exclusively and never overwritten. The JSON Schema Draft 2020-12 validator is pinned to an exact reviewed transitive closure (jsonschema==4.26.0) rather than an ambient version, so validation is deterministic.

Acceptance as content-addressed evidence, not as pointers. registry/acceptance/ retains offline review/acceptance bundles separately from the active registry/records/ and registry/record-sets/ inputs. An accepted-record-artifact-bundle maps a successor set's logical record paths to exact typed artifacts without copying them into a fake record directory — deliberately evidence, not admission, release or authority transition.

Documentation authority (docs/authority-manifest.json, tools/repository-docs/). Every tracked path under docs/ must carry exactly one authority class, which keeps docs/ from becoming a second, competing knowledge store. Deletion is blocked unless a gate proves either byte-identical replacement content or a reviewed, commit-bound retirement.

Repository map (repository-map.json, tools/repository-map/, .rgignore). A compact machine authority for stable repository roots: where a change belongs, what to read first, who maintains it, and which validation applies. Historical, vendored, generated and local-runtime surfaces stay reachable but are excluded from default searches.

All four are enforced by new pre-commit hooks (repository-doc-authority, repository-map, and the task-evidence suites), so the invariants are checked by the same gate as everything else rather than by convention.

P1-SRC-02 boundary. The accepted Workflows/Rollouts bundle and its explicit plan were landed as non-authoritative. This integration added no network acquisition, source admission, registry-pointer change, retrieval release, signing, GitOps mutation or live-cluster mutation.

Alternatives considered

None are recorded. The PR presents the integration as a scope-and-boundary decision — which validated units land together, and what authority they are denied — rather than as a choice between competing designs, and neither the PR discussion nor the .workingdir2/cluster-2/ audits record a rejected alternative for the spine's shape. The rationale for integrating as one branch rather than as a sequence of smaller PRs was not recorded beyond the PR's own framing of it as "one reviewable branch".

Consequences

  • Knowledge-plane invariants are now enforced by pre-commit, not by convention. A change that adds an unclassified file under docs/, or that breaks the repository map, fails the local gate.
  • Validation was extensive at merge: the complete committed knowledge-registry suite at 199/199, the focused output-writer and canonical-cascade suite at 124/124, an independent adversarial publication matrix, byte-identical bundle and two-plan replay with generator verification, and signed writer-commit and final-merge ancestry.
  • The pinned validator closure is a real operating constraint: the registry asserts jsonschema==4.26.0 and its suite fails against an ambient install. Running the tests requires the reviewed closure, not the default interpreter environment.
  • The P1-SRC-02 non-authoritative boundary was a stage gate, not a permanent property, and it has since been opened deliberately. P1-SRC-03 landed authority-local admission (merge c288ff92, PR #2613) and later promoted 117 turbo-ingest authorities into the admission tree (PR #2669); knowledge/registry/acceptance/ now holds both p1-src-02 and p1-src-03, and registry/records/ carries admitted records. The spine described here is in force and has been built on — this ADR is not superseded, but its "non-authoritative" language describes the state at merge, not today.
  • Because the branch also carried unrelated infrastructure work (chrony/PTB NTS, static-pod transaction recovery, audit-policy capture, Cilium docs), the merge is not a clean rollback unit for the spine alone. The PR names the separately reviewed Go Git-object runner as the next rollback unit, acknowledging this.

References

  • PR #2620 — feat(cordana): integrate P1 knowledge and execution spine
  • .workingdir2/cluster-2/12-adr-traceability.md — the promotion queue and the rule that no placeholder ADR is created before a decision is durable
  • .workingdir2/cluster-2/05-interface-data-contracts.md, .workingdir2/cluster-2/04-capability-authority-map.md
  • knowledge/README.md, tools/knowledge-registry/README.md, tools/repository-docs/README.md, tools/repository-map/README.md
  • PR #2613 (merge c288ff92), PR #2669 — the subsequent P1-SRC-03 admission work that built on this spine