docs(governance): refine ADR-012 to many-to-many ADR↔Persona↔Skill graph with bidirectional backlinks + parity linter

[scottschreckengaust]

Summary

Refine ADR-012's operational-knowledge model from a strict upward tree (Skill → Guide → ADR) into a many-to-many graph with Persona as a first-class node, enforced by bidirectional frontmatter backlinks and a parity linter in CI. This makes downstream artifacts (personas, skills) detectably-in-sync with their parent ADRs without a full-repository semantic read — directly mitigating the staleness risk ADR-012 itself flags but does not solve.

Refinement, not reversal (per #380 boundary test): the three-layer ADR→Guide→Skill decision stands; we are extending the "Reference direction" section. This is intended as the first real exercise of the in-place refinement path introduced by #380 — ADR-012 is edited in place with a ## Changelog entry, not superseded.

Motivation

ADR-012 §"Reference direction" asserts references point upward only in a tree. Real usage breaks the tree:

1. One ADR → many personas — ADR-003 shapes Planner, Implementor, Reviewer, and Administrator.
2. One persona → many ADRs — Administrator is shaped by ADR-003, ADR-009, and the security-triage ADR (governance: define security & quality finding triage process (candidate ADR-016); #276 = first CodeQL instance #277/ADR-016).
3. One skill → many personas — shared skills (e.g. validate-dependencies) serve Implementor and Planner.

ADR-012 lists this as an unmitigated risk: "(!) Reference chain integrity must be maintained — a broken link between layers means drift goes undetected." This issue mitigates it mechanically.

Decision to encode (graph + invariant)

   ADR (decision)  ──affects──▶  Persona  ──exercises──▶  Skill
        ▲   many-to-many ▲          │ many-to-many │         │
        └────────────────┴──────────┴──────────────┴─ optional direct Skill→ADR

• Persona becomes a first-class node (e.g. Administrator, PR Reviewer, Issue Triager, Implementor, Planner), living under a documented home (docs/personas/ and/or the plugin agents/ dir — to be decided in design).
• Edges are declared in frontmatter on both endpoints, e.g.:
  • ADR: personas: [planner, implementor, reviewer, administrator]
  • Persona: adrs: [ADR-003, ADR-008], skills: [pickup-issue, validate-dependencies]
  • Skill: adrs: [ADR-003] (or explicit adrs: [] for intentionally standalone), personas: [implementor], guide: CONTRIBUTOR_WORKFLOW.md
• Invariant (parity linter): every declared edge MUST be reciprocated on the other endpoint. A one-directional edge fails CI. A skill with no ADR parent MUST declare adrs: [] explicitly (deliberate, not an oversight).
• Maturity is derived, not stored: do NOT add "operationalized / enforced / validated" status fields to ADRs (they rot — cf. ADR-003's Implemented/Planned enforcement column). Compute maturity by walking the graph: operationalized iff ≥1 persona references it; enforced iff a skill/hook implements it.

Honest boundary (tabula-rasa / ADR-010)

The parity linter verifies structural consistency (links resolve and reciprocate; supersede flags surface dependents for review) — not semantic freshness (that the skill still reflects the ADR's intent). State this limit explicitly in the ADR so the standard doesn't over-promise. Semantic freshness remains a human/agent judgment.

Deliverables

• Amend ADR-012 §"Reference direction" in place: many-to-many graph, Persona as first-class node, bidirectional edges; add a ## Changelog entry + bump Last-updated (uses docs(governance): allow in-place refinement of accepted ADRs (refine vs. supersede + Last-updated + Changelog) #380 mechanics).
• Define the frontmatter edge schema for ADR / Persona / Skill (and where personas live).
• Specify the parity-linter contract (inputs, the reciprocity invariant, failure output) — implementation may be a follow-up.
• Document the supersede interaction: when an ADR goes superseded, the linter flags all referencing personas/skills for review.
• Sync Starlight mirror for ADR-012; commit alongside source.

Acceptance criteria

• ADR-012 expresses ADR↔Persona↔Skill as a many-to-many graph with reciprocal edges; the old "upward tree only" wording is replaced and a changelog entry records the refinement.
• The frontmatter schema is precise enough that a linter can be written from the ADR alone.
• The structural-vs-semantic limit is stated explicitly.
• No implementation-maturity status fields are added to any ADR.

Dependencies

• Blocked by docs(governance): allow in-place refinement of accepted ADRs (refine vs. supersede + Last-updated + Changelog) #380 (in-place refinement must be a sanctioned operation before ADR-012 can be edited in place rather than superseded).
• Related: feat(governance): implement ADR-003 enforcement hooks (commit-msg, branch naming, pickup-issue skill) #186 (ADR-003 decomposition produces the first personas/skills this graph will bind); feat(ci): mechanical module-boundary enforcement (eslint-plugin-boundaries/dependency-cruiser + madge) (CA-03) #254 (mechanical module-boundary enforcement — same "graph integrity as CI gate" technique, prior art); feat(registry): central agent asset registry for capabilities, skills, plugins, and MCP servers #246 (agent asset registry — overlaps on skill/capability cataloguing; reconcile).

References

• ADR-012 §"Reference direction", §Consequences (the (!) integrity risk this resolves)
• docs(governance): allow in-place refinement of accepted ADRs (refine vs. supersede + Last-updated + Changelog) #380 — refine-in-place standard (prerequisite)
• feat(registry): central agent asset registry for capabilities, skills, plugins, and MCP servers #246, feat(ci): mechanical module-boundary enforcement (eslint-plugin-boundaries/dependency-cruiser + madge) (CA-03) #254 — related registry / boundary-enforcement work

---

Filed under contribution governance (ADR-003). No implementation/file edits until approved + assigned.

[scottschreckengaust]

Gate note (do not start yet): Before implementation of this issue begins, it must be reconciled with #246 (central agent asset registry for capabilities/skills/plugins/MCP). Both define how skills are catalogued and referenced; the persona↔skill graph here must not duplicate or conflict with the registry model in #246. Reconciliation is a prerequisite to approval/assignment.

Also still blocked by #380 (in-place refinement must be a sanctioned operation before ADR-012 can be edited in place rather than superseded).

[scottschreckengaust]

Design rationale (to be refined by decisions as implemented). Captured here so the reasoning that motivated this issue survives. Three threads:

1. Separate decision lifecycle from implementation maturity

"Further states after accepted" (operationalized / enforced / validated / has-a-skill) do not belong in the ADR. An ADR has one axis of state — is this decision live? (proposed → accepted → superseded/deprecated), about the idea. Maturity describes the artifacts the decision spawned — a different axis.

In-tree cautionary example: ADR-003's enforcement table has a Status: Implemented/Planned column — maturity living inside an ADR, which goes stale (still "Planned" for the commit-msg hook though #186 may move it). ADR-012's own rule forbids ADRs containing checklists with >3 items.

Position: don't store maturity — derive it from this graph. Operationalized iff ≥1 persona references the ADR; enforced iff a skill/hook implements it; validated iff that skill has tests. Computed by walking edges, not hand-edited fields. This is what makes the many-to-many graph worth building — it replaces a rot-prone status field with a computed property.

2. Many-to-many is a refinement of ADR-012, not a reversal

ADR-012 says references point upward only (Skill → Guide → ADR, a tree). Personas break the tree: one ADR → many personas; one persona → many ADRs; one skill → many personas (shared skills). The "Reference direction" section gets extended, not reversed — so per #380's boundary test this is an in-place refinement of ADR-012 (the three-layer decision stands). It's the first real exercise of #380's refine-in-place path.

3. Bidirectional backlinks + parity linter

Edges declared in frontmatter on both endpoints; a linter builds the graph and fails CI on any one-directional edge (O(edges), mechanical, no semantic reading). Resolves ADR-012's open risk "(!) a broken link means drift goes undetected."

# ADR-003                        # persona: implementor          # skill: pickup-issue
personas: [planner,             adrs:   [ADR-003, ADR-008]      adrs:     [ADR-003]   # or [] = deliberately standalone
  implementor, reviewer,        skills: [pickup-issue,          personas: [implementor]
  administrator]                  validate-dependencies]        guide:    CONTRIBUTOR_WORKFLOW.md

Honest limit: verifies structural consistency (links resolve + reciprocate; supersede flags surface dependents), not semantic freshness (skill still reflects ADR intent) — that stays human/agent judgment. State this in the ADR so it doesn't over-promise.

---

Sequencing reminder: blocked by #380 (refine-in-place must be sanctioned first); must be reconciled with #246 (agent asset registry — overlapping skill/capability catalogue) before implementation begins. Full version also preserved in PR #382's body.