ct-adr-recorder

ADR Recorder

Overview

Drafts, persists, and lifecycles Architecture Decision Records (ADRs) derived from accepted consensus verdicts. The skill owns the proposed-then-accepted HITL gate, writes the canonical markdown artifact, inserts the record into the SQLite decisions table via Drizzle, and orchestrates downstream invalidation whenever an accepted ADR is later superseded.

Core Principle

ADRs capture decisions from consensus verdicts, never from the author's own judgment.

Immutable Constraints

Status Lifecycle

proposed  --HITL review-->  accepted  --supersession-->  superseded
                               |
                               +------deprecation------>  deprecated

The proposed -> accepted edge is the only HITL gate in the pipeline. A human reviewer MUST explicitly sign off; auto-promotion is forbidden.

ADR Document Structure

Every ADR markdown artifact MUST carry frontmatter plus six canonical sections. Keep sections 1-5 concise; prose belongs in the downstream spec, not the ADR.

---
id: ADR-0042
title: "Adopt Drizzle ORM v1 beta for all SQLite access"
status: proposed
date: 2026-04-06
consensus_manifest_id: CONS-2026-04-06-0017
supersedes: []
superseded_by: []
---

# ADR-0042: Adopt Drizzle ORM v1 beta for all SQLite access

## 1. Context and Problem Statement
Better-sqlite3 and raw drizzle 0.x diverge on schema introspection and block
forward migration of the `decisions` table.

## 2. Options Evaluated
* Option A: Stay on drizzle 0.29 and backport fixes.
* Option B: Move to drizzle 1.0.0-beta and accept API churn.
* Option C: Drop Drizzle, switch to Kysely.

## 3. Decision
Adopt [email protected] project-wide; pin to a single beta tag.

## 4. Rationale
Derived from CONS-2026-04-06-0017 (verdict PROVEN, 0.82 confidence).
Option B preserves relational queries and unblocks the migration epic.

## 5. Consequences
### Positive
* Single ORM path; no downgrades.
### Negative
* API churn in each beta; pin required per release.

## 6. Downstream Impact (Traceability)
Flags specs T4776, T4781; decomposition epic T4772; live impl T4790.

A longer, realistic example with all six sections filled out lives in references/examples.md.

Through SDK (preferred)

ADRs are first-class docs SSoT records — drafted via cleo docs add --type adr, attached to the originating consensus task, and numbered through the slug. This is the canonical write path; the legacy "write to docs/adr/ADR-NNNN.md and commit" pattern is deprecated below.

Draft the ADR attached to its consensus task

cleo docs add T4798 docs/adr/ADR-0042.md \
  --type adr \
  --slug adr-0042-drizzle-v1-beta \
  --desc "ADR-0042: Adopt Drizzle ORM v1 beta for all SQLite access (status: proposed)" \
  --labels "adr,proposed"

• --type adr is the canonical taxonomy value. The closed set is spec | adr | research | handoff | note | llm-readme.
• --slug MUST follow adr-<NNNN>-<short-topic>. The numeric segment is the canonical ADR id; the topic segment makes the slug human readable. Collisions return E_SLUG_RESERVED with 3 alternatives (legacy E_SLUG_TAKEN aliased under details.aliases for one release — T10386).
• Near-duplicate slugs trigger W_SLUG_SIMILAR (T10361). The CLI surfaces the top match and hints --allow-similar. Use --allow-similar only when the new ADR genuinely forks from the existing one (e.g. versioned re-issue); every bypass is audited to .cleo/audit/similar-bypass.jsonl.
• Unknown flags fail fast with E_UNKNOWN_FLAG + did-you-mean suggestions (T10359) — --lbls becomes "did you mean --labels?".
• TODO(T10360 · E3.2 pending): when shipped, ADR drafts will accept --title "<human title>" and CLEO will auto-allocate the next adr-NNN-<kebab-title> via the E1 slug allocator. Until then, you MUST hand-pick the next free NNNN by inspecting cleo docs list --type adr --project. Example future call:

  # FUTURE — DO NOT USE until T10360 ships:
  # cleo docs add T4798 docs/drafts/draft.md --type adr \
  #   --title "Adopt Drizzle ORM v1 beta"
  

• The owner ID is the consensus task whose verdict drives the ADR (T4798 above). This is how downstream supersession cascades find the chain — never attach an ADR to an arbitrary task.

Persist the decision row alongside the doc blob

cleo docs add --type adr writes the document and the docs-side manifest entry, but per Immutable Constraint ADR-006 the canonical decisions table MUST also be populated via Drizzle. The two writes are paired: doc blob first (SSoT-of-the-prose), then the relational row (SSoT-of-the-decision). Skipping either is a validation failure.

Publish the ADR to a git-tracked path

cleo docs publish --for T4798 --to docs/adr/ADR-0042.md

Atomic tmp-then-rename. The published file lands in the next commit; the SSoT blob remains the canonical version-history root.

Fetch the ADR back by slug (for HITL review + downstream supersession)

cleo docs fetch adr-0042-drizzle-v1-beta     # latest version
cleo docs versions --for T4798               # every SHA version

The HITL reviewer reads the proposed ADR via cleo docs fetch rather than the on-disk file so the review anchors on the canonical SSoT blob — drift between the published file and the blob is its own review finding.

List ADRs by type or status

cleo docs list --type adr --project          # every ADR in the project
cleo docs list --task T4798 --type adr       # ADRs attached to T4798

Deprecated: Direct filesystem write

The legacy "write to docs/adr/ADR-NNNN.md and commit" pattern is deprecated. The on-disk file drifts from the SSoT, the ADR has no slug for the supersession cascade to retrieve it by, and the consensus-task↔ADR linkage exists only as a frontmatter field (consensus_manifest_id) rather than a relational owner edge. Migrate to cleo docs add --type adr --slug adr-<NNNN>-<topic> for every new ADR — and use cleo docs sync --from docs/adr/ADR-NNNN.md --for <taskId> to back-fill existing on-disk ADRs into the SSoT.

HITL Approval Gate

When a draft reaches proposed, the skill MUST:

1. Write the markdown artifact to disk.
2. Record the manifest entry with status: proposed and agent_type: "decision".
3. Exit with code 65 (HANDOFF_REQUIRED).
4. Leave the pipeline paused until a human reviewer runs the approval path.

The agent MUST NOT:

• Promote a proposed ADR to accepted on its own.
• Retry the transition on a loop after exit 65.
• Edit the ADR body after exit 65 (any revision starts a new proposed cycle).

The human reviewer is expected to:

1. Read the markdown and the linked consensus manifest.
2. Confirm that every option from the consensus verdict appears in section 2.
3. Sign off by moving the status to accepted through the CLI and re-running validation with hitlReviewed: true.

Downstream Cascade (on supersession)

When an accepted ADR is later superseded, the skill MUST:

1. Query the decision_evidence relation for every specification, decomposition, and implementation that cited the old ADR.
2. Flag each linked artifact as needs-review.
3. Suspend any active implementation or contribution task tied to the old ADR.
4. Record the cascade in the new ADR's manifest entry.

A missing cascade fails validation with exit code 18 (CASCADE_FAILED). The full flow, including the decision_evidence query and the manifest fields to populate, is documented in references/cascade.md.

Integration

Validate every ADR manifest entry through cleo check protocol:

# Draft reaches proposed: runs inside the skill, before HITL hand-off.
cleo check protocol \
  --protocolType architecture-decision \
  --taskId T4798 \
  --status proposed \
  --persistedInDb true \
  --adrContent "$(cat docs/adr/ADR-0042.md)"

# HITL accepts the ADR: rerun with the review flag.
cleo check protocol \
  --protocolType architecture-decision \
  --taskId T4798 \
  --status accepted \
  --hitlReviewed true \
  --persistedInDb true

# Later supersession: include the cascade flag.
cleo check protocol \
  --protocolType architecture-decision \
  --taskId T4798 \
  --status superseded \
  --downstreamFlagged true

Exit code 0 = valid. Exit code 65 = HANDOFF_REQUIRED. Exit code 18 = CASCADE_FAILED. Exit code 84 = PROVENANCE_REQUIRED (attempted ADR without a linked consensus).

Anti-Patterns

Critical Rules Summary

1. ADRs MUST be drafted from an accepted consensus verdict, with consensus_manifest_id populated.
2. The proposed -> accepted transition MUST pass through a HITL review; agents stop at exit 65.
3. The ADR body MUST contain all five canonical sections (Context, Options, Decision, Rationale, Consequences).
4. The decision MUST be inserted into the canonical decisions SQLite table via Drizzle.
5. The manifest entry MUST set agent_type: "decision" and reference the output markdown file.
6. Superseding an accepted ADR MUST trigger the downstream cascade over linked specs, decomps, and impls.
7. Agents MUST NOT retry the HITL handoff on a loop; wait for the human reviewer.
8. Always validate via cleo check protocol --protocolType architecture-decision before exiting.

See also / References

This skill binds to the architecture_decision LOOM lifecycle stage (underscored canonical form — cleo lifecycle source of truth). Governing ADRs:

• ADR-053 — playbook runtime — defines the lifecycle state machine; the ADR stage is one of its 10 nodes.
• ADR-070 — three-tier orchestration — defines the Orchestrator HITL gate that owns the proposed → accepted ADR transition.

Naming Note (T9672)

The stage's canonical name is architecture_decision (underscored) because the cleo lifecycle CLI emits it that way. Historically packages/skills/skills/manifest.json dispatch_matrix.by_protocol used the dashed form architecture-decision — T9672 reconciled that key to the underscored form. The dashed form is retained only as a keyword alias under dispatch_matrix.by_keyword so legacy dispatch paths continue to resolve. Frontmatter on this skill (protocol: architecture_decision, loomStage: architecture_decision) uses the underscored form.

LOOM coverage matrix: docs/skills/loom-coverage-matrix.md.