Repository navigation
Description
Follow-up carved from Discussion #1360 Phase B (fleet-wide half), raised by a source-material audit run on 2026-09-01 while planning epic #1627. Recorded now so the finding is not lost; not ready to plan until #1628 lands (see Dependency).
The finding
Three product repos already carry substantial Winston (BMAD Solution Architect) architecture output. It is real, detailed, and currently unreachable by any agent — because it is not in a form anything can cite.
| Repo | Artifact | Size | Last touched | Age |
|---|---|---|---|---|
| TalkTerm | _bmad-output/planning-artifacts/architecture.md |
48 KB | 2026-03-24 | 160d |
| markets | _bmad-output/planning-artifacts/architecture.md |
54 KB | 2026-03-28 | 156d |
| broodly | _bmad-output/planning-artifacts/architecture.md |
38 KB | 2026-03-21 | 163d |
Plus a fourth, in better shape and not BMAD-generated — see "Correction to #1360" below.
Why these are not ADRs today
Each is a single monolithic "Architecture Decision Document". Against the #1360 decision model (ADRs are normative, append-only, immutable once accepted), they fail three of four properties:
- Not individually citable. The
solution-architectpersona's load-bearing rule ([Phase 2] Create thesolution-architectadvisory persona (manifest + advisory prompt + interaction contract + eval seed) #1629 AC feat: feature ideation framework — adversarial proposer/challenger/synthesizer #6) is that it must cite the ADR it measures a change against, by number. You cannot cite "the third bullet under Data Architecture." - No status, no supersession. There is no
statusfield and no mechanism to supersede a decision — a changed mind would be an in-place edit, which the decision model forbids. - Not immutable. One 38–54 KB mutable file per repo; the unit of change is the whole document.
- (Passes) the content itself is genuinely decision-shaped.
Why it is worth doing anyway — the material is good
broodly §"Architectural Boundaries" is already in the checkable-invariant form the ADR convention wants:
apps/apiis the only client-facing GraphQL API surface.- Mobile and web clients never access DB directly.
- Domain modules communicate via explicit interfaces/events only.
markets goes further — its boundaries are tables with an Enforced By column (Client → API / GraphQL over HTTPS / Cloud Run ingress, TLS). That column is precisely what a later Phase D/F check would assert against. This is ADR-ready content trapped in a non-ADR container.
Sizing — and the reason it is not mechanical
All three share the same BMAD skeleton (## Core Architectural Decisions → ### Decision Priority Analysis + ### Decision Impact Analysis; ## Project Structure & Boundaries → ### Architectural Boundaries). That invites the assumption that extraction is a deterministic parse. It is not, and this is the main sizing risk to flag:
| Repo | Decisions | Encoded as | Boundaries | Encoded as |
|---|---|---|---|---|
| TalkTerm | 13 | numbered lists | 13 | bullets |
| markets | 14 | bullets | 7+ | tables |
| broodly | 18 | bullets | 4 | bullets |
~45 candidate decisions total, in three different markup shapes under identical headings. A single regex/parser will be brittle; this needs a structure-aware pass per repo. Deterministic-first is still right for locating candidates (#1360's Phase B correction), but the split-and-rewrite is editorial and needs review per ADR.
Correction to #1360
The body of #1360 §3 states "google-app-scripts has a PRD and no architecture." That is wrong. petry-projects/google-app-scripts/docs/architecture.md exists (14 KB, 2026-03-28) — and it is the best-shaped architecture doc in the org:
- It is already at
docs/architecture.md, i.e. already on the Q0-decided path prefix. - Its §"Key Architecture Decisions" entries already use Decision / Rationale / Trade-off — Nygard's Decision / Context / Consequences under different names.
- Each entry names a real trade-off, not only an upside (e.g. the dual-file pattern's "logic must be kept in sync between
code.gsandsrc/index.js").
It is the closest to passable in the org and should be the first repo converted, not the last — it is the cheapest proof that the convention works, and it doubles as the in-org style exemplar. (It was also not generated by Winston, which is itself worth noting: the hand-written doc is in better ADR shape than the agent-generated ones.)
Proposed scope (when planned)
- Convert
google-app-scriptsfirst — smallest, best-shaped, proves the convention end to end. - Then
broodly,markets,TalkTerm— one repo per story; each emitsdocs/architecture/adr/NNNN-*.mdusing the convention established by [Phase 1] Seed the architecture-of-record (ADR convention + 4–6 lifted ADRs) for .github-private #1628, withstatus: acceptedand a provenance line citing the source section of the originalarchitecture.md. - Leave the original
architecture.mdin place, marked as superseded-by-the-ADR-tree rather than deleted — it holds narrative context (cost analysis, starter-template evaluation) that is not decision-shaped and does not belong in ADRs. - Do not attempt to make the ADRs current. They record what was decided in March 2026. If a decision has since drifted, that is a finding for the
solution-architectpersona to surface — not something to silently rewrite. Backfilling an ADR to match today's code is the exact ratchet Architectural integrity in the agentic delivery model — what enforces our standards, and where does the Solution Architect fit? #1360 §2 describes.
Dependency
Blocked by #1628 (the repo-local ADR convention, docs/architecture/adr/0000-adr-process.md). This work must reuse that convention rather than invent a second one — otherwise the fleet ends up with two ADR dialects, which is the drift the persona manifest pattern exists to prevent.
Explicitly not in scope
docs/architecture/views/ and deterministic view generation (the other half of Phase B), the org-level architecture standard (Phase A), and anything in Phases C/F/G. Those stay in #1360.
Parent: Discussion #1360 (Phase B, fleet-wide half) · Sibling cut: epic #1627 (Phase E, repo-local) · Source audit: 2026-09-01
Activity