kryptobaseddev/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

| 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 [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.

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

| Pattern | Problem | Solution | |---------|---------|----------| | Drafting an ADR without a consensus verdict | Violates ADR-001; decision lacks evidence base | Run the consensus skill first; copy the manifest id into the ADR frontmatter | | Auto-promoting proposed to accepted | Bypasses the HITL gate (ADR-003) | Stop at exit 65 and wait for the human reviewer | | Persisting only the markdown, skipping SQLite | Violates ADR-006; loses relational queries | Insert via the architectureDecisions Drizzle table before exiting the skill | | Omitting the Downstream Impact section | Future implementers can't find cascade targets (ADR-005) | Populate section 6 with every touched spec/epic/impl | | Using the ADR to list implementation requirements | Blurs the ADR/spec boundary | Keep the ADR decision-only; push requirements to the specification stage | | Superseding without running the cascade | Violates ADR-005; breaks the evidence chain | Query decision_evidence, flag artifacts, record the cascade in the new ADR | | Editing an accepted ADR in-place | Breaks immutability and audit trail | Create a new ADR that supersedes the old one |

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.