/ct-adr-recorder

name: ct-adr-recorder
description: "Records Architecture Decision Records from accepted consensus verdicts. Use when promoting a consensus outcome to a formal ADR: drafts the document in the proposed-then-accepted HITL lifecycle, links to the originating consensus manifest, persists the decision to the canonical SQLite decisions table, and triggers downstream invalidation when an accepted ADR is later superseded. Triggers on phrases like 'write ADR', 'record architecture decision', 'formalize this decision', 'lock in the choice', 'create ADR-XXX', or when a consensus task reaches completed status and needs formalization."
protocol: architecture_decision
adrRefs:
  - ADR-053
  - ADR-070
metadata:
  version: 1.0.2
  tier: on-demand
  install: harness
  covers:
    - packages/core/src/validation/protocols/cant/architecture-decision.cant
    - packages/core/src/validation/protocols/protocols-markdown/architecture-decision.md
  loomStage: architecture_decision
  lastReviewed: 2026-09-28
  stability: stable

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

| ID | Rule | Enforcement | |----|------|-------------| | ADR-001 | ADR MUST be generated from an accepted consensus report verdict. | `validateArchitectureDecisionProtocol` rejects entries without `consensus_manifest_id`; missing link deducts 25 from score. | | ADR-002 | ADR MUST include a `consensus_manifest_id` field linking to the originating consensus. | Manifest entry field is required. | | ADR-003 | ADR MUST require explicit HITL approval to transition from `proposed` to `accepted`. | `hitlReviewed: false` with `status: accepted` is rejected; exit code 65 (HANDOFF_REQUIRED). | | ADR-004 | ADR MUST include Context, Options Evaluated, Decision, Rationale, and Consequences sections. | Regex check on the ADR body; missing section deducts 20 from score. | | ADR-005 | Superseded ADRs MUST trigger downstream invalidation of linked Specifications, Decompositions, and Implementations. | `downstreamFlagged: false` on `status: superseded` fails validation; exit code 18 (CASCADE_FAILED). | | ADR-006 | ADR MUST be persisted in the canonical `decisions` SQLite table via Drizzle ORM. | `persistedInDb: false` rejects the manifest entry. | | ADR-007 | Manifest entry MUST set `agent_type: "decision"`. | Validator rejects any other value. | | ADR-008 | ADR MUST block the Specification stage until status is `accepted`. | Lifecycle state machine refuses to advance past the ADR stage while status is `proposed`. |

Status Lifecycle

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

| Status | Transition From | Required Input | Effect | |--------|-----------------|----------------|--------| | `proposed` | (initial draft) | Consensus manifest id | Pipeline pauses; exit 65 HANDOFF_REQUIRED | | `accepted` | `proposed` | Human review signal | Unblocks Specification stage | | `superseded` | `accepted` | New ADR id | Fires downstream cascade (see references/cascade.md) | | `deprecated` | `accepted` | Deprecation reason | Removed from canon without replacement |

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 drizzle-orm@1.0.0-beta 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](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 to