19. Optional Extensions

aDNA Specification v2.6 Section 19 of 20 Full text

Scan: Nine opt-in subsystems — machine registry, backlog, skill files, testing/CI awareness, reference code, ADRs, graph exchange, campaigns, memorialized data models. Adopt based on need.

The following patterns are available but not required. Projects adopt them based on need.

19.1 Machine Registry

Decision: D10

For projects running on multiple machines or sync environments where path patterns vary.

Location: what/hardware/machines/ or a similar what/ subfolder.

Per-machine file contents: hostname, user, OS, path patterns, installed tools, capabilities.

RECOMMENDED for sync-based environments (cloud storage, team sync tools) where file paths differ across machines. OPTIONAL for git repositories where environment variables handle path differences.

19.2 Backlog System

Decision: D13

Durable ideation and improvement tracking.

Location: how/backlog/

Lifecycle: idea → triage (priority/effort assessment) → graduation to how/missions/ or archive.

Frontmatter: type: idea, category, priority, effort, status, proposed_by.

Agents SHOULD scan how/backlog/ during session startup for ideas relevant to the current work. New ideas discovered during work SHOULD be captured as backlog files.

19.3 Skill Files

Decision: D15

Reusable agent procedures — step-by-step instructions agents can follow autonomously.

Location: how/skills/skill_{name}.md

Sections: purpose, prerequisites, steps, verification, rollback, notes.

Skills are distinct from processes: skills are agent-executable (precise steps, verification checks); processes are human-readable (guidelines, decision trees).

19.4 Testing/CI Awareness

Decision: D23

aDNA does not prescribe test frameworks or CI/CD configurations — these belong to the project content layer. However, agents SHOULD be aware of test status.

Awareness pattern:

CLAUDE.md includes an optional section on testing: where to check, how to run, what signals mean
AGENTS.md for code directories includes testing guidance as an enrichment layer
STATE.md reports test status when relevant (pass/fail, coverage, regressions)
CI/CD configuration lives in project content (.github/, Makefile, pyproject.toml, etc.)

19.5 Reference Code

Decision: C11

Bounded exception for code-adjacent reference material inside the aDNA structure.

Location: what/reference/

Rules:

Executable code MUST live in what/reference/ or in the project content layer — nowhere else in the triad
what/reference/ MUST be bounded — no unbounded growth
Entries SHOULD link to source implementations rather than duplicating code
Documentation-only projects skip this entirely

19.6 Architecture Decision Records (ADRs)

Decision: C12

Lightweight records of significant project decisions.

Location: what/decisions/

Template sections: context, decision, consequences.

Numbering (v2.6): an ADR number SHOULD be qualified by the vault that holds it wherever it is cited outside that vault (aDNA.aDNA ADR-066, not ADR-066). A campaign that numbers its own ADRs SHOULD prefix them with the campaign’s one-letter code (ADR-B08 is a campaign’s ADR 08, not the vault’s ADR-008).

ADRs are knowledge artifacts — decisions outlive the process that produced them. A 2-year-old ADR is reference knowledge, not an active operation. This is why they live in what/, not how/.

19.7 Graph Exchange

Decision: v2.6 (ARCADE G4)

A graph MAY be published, discovered and fetched as an artifact through an aDNA Exchange. The standard-side contract is aDNA.aDNA/what/specs/spec_graph_exchange.md; it cites the Exchange’s own specifications and copies none of them. A publishing graph places its consumer wrapper at how/federation/exchange/ (§5.3).

19.8 Campaigns

Decision: v2.6 (ARCADE G4)

A project MAY organise work above the mission (§9) as campaigns: Campaign → Mission → Objective, each level narrowing the context the next one needs.

Containment: a campaign lives at how/campaigns/campaign_<name>/ with its charter; its missions live at how/campaigns/campaign_<name>/missions/. Standalone missions stay in how/missions/.
Phases and gates: a campaign runs in phases, and the gate between two phases is a human gate. The ruling is recorded per §7.7; an agent SHOULD NOT advance a campaign across a gate without it.
After-action review: a mission SHOULD carry a short after-action review (what worked · what didn’t · the finding · the change · the follow-up) before it is set status: completed.
Archive-don’t-delete (§15.1): campaign, mission and session records are completed or abandoned, never removed.
OODA cascade (MAY): each level MAY run an observe–orient–decide–act loop; anomalies escalate upward (session → mission → campaign) and restructuring flows downward.

19.9 Memorialized Data Models

Decision: aDNA.aDNA ADR-067 (v2.6)

A data model qualifies when a graph other than its owner’s reads, validates against, or copies it; the owner judges. A conforming instance that owns a qualifying model:

SHOULD hold it as one master and generate its other surfaces from that master rather than write them by hand. The master SHOULD be LinkML (aDNA.aDNA ADR-062 clause 2); a master in another schema language is not nonconformant.
SHOULD stamp each generated face with the master’s path and the first 16 hex characters of its sync hash (sha256 over the master’s bytes, exactly as committed, with no normalization). The stamp is a pattern, not a literal: GENERATED — DO NOT EDIT. Master: <path …> <label>: <16 hex>, where <label> is sync_hash, or source_sha256 on a face whose own standard uses sync_hash for another value (a canvas). The path part MAY carry a parenthetical. A face whose format cannot hold a stamp MAY carry it in a sidecar file.
SHOULD record the full 64-hex sync hash on the master’s descriptor.
SHOULD keep one check that recomputes the sync hash, regenerates every face, and fails on any difference; the check trusts no value it finds recorded.
SHOULD treat a copy of the master held in another graph as a generated face: the copy carries the stamp, or, for a byte-for-byte copy, the copying graph keeps a pin file that records the master’s path and its full sha256; either way, the copying graph’s check compares the copy with the master’s hash. Item 4 binds the owner’s check; a pin is the copier’s record of what it copied, and the copier’s check recomputes the master’s hash wherever the master is present.
MAY apply all of the above to a model read only inside its owning graph.

Where the face is a canvas, the Canvas Standard’s own sync block governs: _reserved.sync.sync_hash is the canvas topology hash, and the master’s hash is carried as source_sha256. A validator that checks stamps reports a mismatch as a warning and a stamp whose master is absent as unverifiable, never as a failure. The qualifying models known at the cut are listed, informatively, in the roster that accompanies aDNA.aDNA ADR-067; the roster is held by its steward graph (LatticeProtocol.aDNA) and is not publicly readable, so a public reader learns that it exists and who holds it, not its rows. A sync hash identifies one master and a release manifest (§15.5) identifies a release’s files; neither stands in for the other.