Rag Architecture Decisions: Architecture Decision Retrieval for Coding Agents

# ADR-0142: Payments ledger writes go through DynamoDB transactional outbox

- Status: Accepted
- Date: 2026-03-12
- Bounded context: payments
- Supersedes: ADR-0098
- Deciders: @payments-arch

## Decision
All ledger mutations emit domain events via a DynamoDB transactional outbox.
Direct dual-writes to EventBridge from application code are forbidden.

## Consequences
- Agents must not introduce `eventBridge.putEvents` beside a ledger put
- New consumers read from the outbox stream mapping

{
  "docType": "adr",
  "adrId": "ADR-0142",
  "status": "accepted",
  "boundedContext": "payments",
  "supersedes": ["ADR-0098"],
  "path": "docs/adr/0142-ledger-outbox.md"
}

export async function planWithArchitecture(opts: {
  ticket: string;
  boundedContext: string;
  retrieve: (q: string, filter: object) => Promise<{ path: string; text: string }[]>;
}) {
  const adrs = await opts.retrieve(opts.ticket, {
    andAll: [
      { equals: { key: "docType", value: "adr" } },
      { equals: { key: "status", value: "accepted" } },
      { equals: { key: "boundedContext", value: opts.boundedContext } },
    ],
  });

  // ✅ Accepted ADRs in system context — not optional "if relevant"
  const system = [
    "You are a senior engineer. Architecture changes must cite ADR IDs.",
    "If a proposal conflicts with an Accepted ADR, stop and propose an ADR amendment instead.",
    "ADRS:\n" + adrs.map((a) => `### ${a.path}\n${a.text}`).join("\n\n"),
  ].join("\n");

  return system;
}

const ARCH_SMELLS = [
  /new\s+(kafka|kinesis|eventbridge|graphql|grpc)\s+topic/i,
  /introduce\s+shared\s+database/i,
  /cross-context\s+import/i,
];

export function requiresAdrCitation(prBody: string, diff: string): boolean {
  return ARCH_SMELLS.some((re) => re.test(prBody) || re.test(diff));
}

export function assertAdrCitation(prBody: string) {
  if (!/ADR-\d{3,}/.test(prBody)) {
    throw new Error("architecture_change_missing_adr_citation");
  }
}