Be Civic — Closed Corpus Internals
Internal structure of the closed knowledge graph — skills, paths, specs, the lifecycle state machine, and the D1 catalogue.
Closed Corpus Internals
Intent
This diagram maps the interior of the closed corpus — the knowledge graph that the harness reads. It answers the question: what is the corpus made of, how are its parts related, and how does content move from submission to canonical status? The diagram is the primary reference for corpus authors, for anyone writing tools that interact with the corpus programmatically, and for reasoning about the promotion pipeline that keeps the corpus accurate over time.
Entities
- Closed knowledge graph — the top-level container for all corpus content; private by design post-pivot (depth is not public).
- Skills — per-procedure markdown files stored at
skills/SLUG/canonical.md. Each skill carries frontmatter with DSL tags (<span class="dsl dsl-skill">Skill</span>,<span class="dsl dsl-ref">Ref: Ref</span>,<span class="dsl dsl-risk">Risk</span>), astatus:field, andrequires:/requires_paths:declarations that compose skills into a DAG. - Paths — procedural workflows stored at
paths/index.jsonkeyed bypth-NNNNN. A path declares the skills it references and the external resources (documents, commune links, calculators) a procedure requires. Paths are the harness's primary traversal unit. - Specs — the architecture, schemas, protocol, lifecycle, privacy, skills, website, cowork-plugin, and build-tools canonical documents. The authoritative reference layer.
- State machine (draft → alpha → beta → stable) — the skill-promotion lifecycle. Each state represents a consensus threshold reached via accumulated validations in D1:
- draft — initial submitted artefact; maintainer review required before alpha.
- alpha — merged to main; open for consumer-AI validation.
- beta — promotion threshold of validations reached; higher confidence.
- stable — high-confidence, actively used. Rollback triggers if rejects exceed confirms by ≥2.
- invalidated — found to be factually wrong; removed from normal serving (faded in diagram).
- superseded — replaced by a later skill version; retained for audit (faded in diagram).
- Path → Skills composition — the structural relationship between paths and skills; a path references skills by
<span class="dsl dsl-skill"><a href="https://becivic.be/skills/.../canonical" target="_blank" rel="noopener">Skill: ...</a></span>tags embedded in its rendered narrative. The composition graph is the primary validation target of thevalidate-cross-refs.tsscript. - D1 catalogue — Cloudflare D1 stores the runtime indexes:
skills_index,paths_index,submissions,validations,observations. The catalogue drives both fast lookup and the state-machine promotion arithmetic. - Observation submission — operational feedback from a real session; light review; routed to D1 staging.
- Amendment submission — a proposed field-level change to an existing skill or path; auto-merges on green CI after the 24-hour staging window.
- Draft submission — a new skill or path proposal (
status: alphaon merge); requires maintainer review before entering the corpus. - Validation submission — a consumer AI confirming that a skill ran correctly against a real case; feeds the state-machine promotion arithmetic.
Relationships
- Corpus → skills / paths / specs — the corpus is composed of exactly these three stores; there is no other category of corpus content.
- Skills carry a lifecycle — every skill exists at one of the six state-machine positions; the state transitions are driven by validation consensus in D1, not by manual editorial decisions for normal corpus content.
- Path composition references skills — paths are not self-contained; they declare dependencies on skills and compose them into a narrative workflow. A path with a broken skill reference fails the
validate-cross-refs.tscheck. - Skills and paths are indexed in D1 — the D1 catalogue is the runtime's lookup surface; the on-disk canonical files are the source of truth; D1 is a derived index that must stay consistent with the files.
- Submission types route to D1 staging (24h) — all four submission types enter the same 24-hour staging window in D1 before the cron tick routes them onward.
Design notes
The state machine is the corpus's quality ratchet. Content cannot advance from alpha to beta to stable without accumulated validations from independent consumer-AI sessions. The promotion thresholds are defined in lifecycle.md §9.2 and are designed to require consensus across distinct IPs (per-artefact salt prevents self-validation). This means the corpus's quality is a function of actual usage rather than maintainer judgment alone — the maintainer is constitutional-court only, not content editor.
The distinction between skills and paths is architecturally important. Skills are atomic procedures: one administrative task, self-contained, citable by article of the Code. Paths compose skills into the workflow a specific user journey requires, and additionally surface the external documents and commune-specific handoffs that no skill alone can provide. The harness traverses paths; skills are what get loaded and validated. A common authoring mistake is conflating the two — drafting a path-shaped skill or a skill-shaped path.
D1 is the runtime layer, not the truth layer. The canonical truth for skill and path content is always the file on bc-docs main. D1 holds volatile values (promotion counts, reference row status) and derived indexes (fast lookup). If D1 and the file disagree on a skill's status, the file wins; a D1 inconsistency is a bug to fix, not a policy to override. (Open question: what is the recovery procedure when D1 state diverges from the committed file state — is there an authoritative reconciliation script, and is it documented in a spec section?)
Related
- Spec: lifecycle.md — full state-machine diagram and promotion thresholds (§9), branch and CI policy (§10)
- Spec: schemas.md — skill frontmatter schema, submission schemas, MDX tags (§6)
- Spec: skills.md — skill-drafting protocol and path composition rules (§15)
- Related diagrams: overview · submission-flow