Repository navigation
Description
Story
As a solution-architect persona (and the humans it advises),
I want a repo-local docs/architecture/adr/ tree that records the ADR convention and 4–6 accepted ADRs lifting structural doctrine already written in AGENTS.md,
so that the persona has a normative intent-of-record to cite by number instead of reverse-engineering intent from drifted code (the ratchet in §2).
Acceptance Criteria
docs/architecture/adr/0000-adr-process.mdexists and records the convention itself: sequentialNNNN-title.mdfilenames; astatusfield with valuesproposed | accepted | superseded-by-NNNN; and the idempotency rule — an accepted ADR is immutable, a reversal is a NEW ADR that supersedes it, never an in-place edit.- Between 4 and 6 additional ADRs (
0001–000N) are authored by LIFTING structural doctrine that already exists inAGENTS.md/org doctrine — not by inventing new rules. Each is committed withstatus: accepted. - Every non-process ADR states its declared boundary or invariant in a form something could later check (e.g. a named module/tier boundary, a dependency-direction rule, or a reviewable rule-of-three claim) — this is what makes later Phases B/D/F possible without a rewrite.
- Each lifted ADR cites the exact
AGENTS.mdsection (or org-doctrine location) it was lifted from, so the ADR is traceable to existing doctrine rather than new invention. - Scope is honored: no org-level standard, no
docs/architecture/views/, no generation script, and no other repo are created or touched.
Tasks / Subtasks
- Create
docs/architecture/adr/0000-adr-process.mddocumenting the convention (sequential ids, status lifecycle, immutable-once-accepted / supersede-not-edit). (AC: test issue from agent #1) - Select 4–6 doctrine items already written in AGENTS.md and author one ADR each by lifting the existing text. Candidates (all pre-existing): the thin-caller/reusable two-tier model; the channel-tag release + ring model; the rubric-registry contract ("add a manifest row; do not fork the reviewer"); the pure-logic-plus-bats discipline (LLM only where it must be); advisory-by-default for personas. (AC: Go-live improvements for PR review agent #2, Optimize review: small-PR and incremental fast paths #4)
- For each ADR, phrase its boundary/invariant in a checkable form and record the source
AGENTS.mdsection it derives from. (AC: Add @claude delegation, auto-merge, and rebase handling #3, Optimize review: small-PR and incremental fast paths #4) - Verify no out-of-scope artifacts are introduced (no
views/, no generator, no org standard, no cross-repo edits). (AC: feat: add Copilot engine support via REVIEW_ENGINE toggle #5)
Dev Notes
- This is the normative substrate the whole epic rests on. Do NOT invent architecture rules — every ADR must be a lift of doctrine already present in
AGENTS.md. Inventing rules here would itself be the ratchet the initiative is trying to break. - Source doctrine to lift, with concrete AGENTS.md anchors: thin-caller/reusable two-tier model →
AGENTS.md§Workflow Files (dev-lead.yml stub → dev-lead-reusable.yml) and §Reusable caller-input contract; channel-tag release + ring model →AGENTS.md§'Release channel tags & the mutable-ref exception'; rubric-registry contract →AGENTS.md§'Review artifact contract & rubric registry' ("Register a new artifact_type by adding a manifest row; do not fork the reviewer"); pure-logic-plus-bats discipline → thescripts/*.sh+tests/*.batsconvention (e.g.spec-drift.sh,fleet_stub_drift.sh— main() does I/O, pure classifiers unit-tested); advisory-by-default → the persona pattern (personas/security-lead/persona.ymltriggers.default_mode: advisory). - Ground the ADR shape on standard ADR practice (Nygard-style: Context / Decision / Consequences / Status). Keep each ADR short and citable — the point is a stable, numbered, quotable record, not an essay.
- 'Checkable form' means: an ADR about the thin-caller tier should name the boundary a check could later assert (a
.github/workflows/*.ymlcaller stub must only forward to a pinnedpetry-projects/*reusable and must not interpolate secrets intorun:). An ADR lifting the rule-of-three should state it as a reviewable claim ('no abstraction until a third concrete instance exists'). - No test surface beyond markdown existence/lint.
markdownlintruns inlint.yml; keep the ADRs lint-clean. Do not add a bespoke ADR validator in this story — the convention is human-reviewed here; machine enforcement of ADR structure is out of scope (later cuts).
Project Structure Notes
New top-level docs/architecture/adr/ under the existing docs/ tree (which already holds agentic-interaction-model.md, adding-an-agentic-role.md, initiatives/). Matches Q0's docs/architecture/ decision. Only the adr/ subtree is created in this cut; views/ is deliberately absent (Phase B fleet-wide half, out of scope).
References
- AGENTS.md#workflow-files (thin-caller/reusable two-tier model)
- AGENTS.md#release-channel-tags--the-mutable-ref-exception (channel-tag + ring model)
- AGENTS.md#review-artifact-contract--rubric-registry (rubric-registry contract)
- scripts/spec-drift.sh, tests/ (pure-logic-plus-bats discipline)
- personas/security-lead/persona.yml#triggers (advisory-by-default)
- Discussion Architectural integrity in the agentic delivery model — what enforces our standards, and where does the Solution Architect fit? #1360 §7 S1 and §6 (architecture doctrine is not portable)
Story prepared by the BMAD Scrum Master (Bob) for epic #1627. Status: ready-for-dev.
ADR template + exemplars (maintainer addendum, 2026-09-01)
Use the Nygard 5-section template: Title / Status / Context / Decision / Consequences. Not MADR (its decision-drivers + considered-options-with-pros-and-cons sections are overhead for lifted doctrine, where the alternatives were never actually weighed here), and not Backstage's 3-section variant — Backstage omits Status, and Status is load-bearing for us: AC #1's immutability/supersession rule is unimplementable without it.
Write Decision in the active voice, starting "We will…" — that phrasing is what makes an invariant checkable, and it is the difference between a rule and a description.
Genre exemplar — Backstage's ADR log (16 ADRs, docs/architecture-decisions/adrNNN-title.md). This is the closest reputable match to our situation: a platform/tooling repo whose ADRs are about code and module conventions, not product/system design. Note the genre of its titles — "Avoid default exports", "Module export structure", "Plugin package structure". Those are the same shape as this story's targets (thin-caller tier, rubric-registry contract, pure-logic-plus-bats). ADR003 is a good length reference: ~30 lines, one decision, checkable, with the escape hatch named explicitly.
In-org precedent worth matching — petry-projects/google-app-scripts/docs/architecture.md §"Key Architecture Decisions". Its five entries already use Decision / Rationale / Trade-off, which is Nygard's Decision / Context / Consequences under different names, and each names a concrete trade-off rather than only an upside. Match that candor: a Consequences section that lists only benefits is a marketing document, not an ADR.
Do NOT import architecture content from the other org repos. TalkTerm, markets, and broodly each carry a large BMAD architecture.md (38–54KB), but those are Expo/Go/GCP product architectures — wrong domain for a shell + reusable-workflow repo, and lifting them here would seed invented doctrine, which is precisely the failure mode this epic exists to prevent. This repo's source material is AGENTS.md, per AC #2 and #4. (Decomposing those product artifacts into per-repo ADRs is real work, but it is Phase B fleet-wide — a separate cut, not this story.)
Canonical references: adr.github.io (index + template catalogue), joelparkerhenderson/architecture-decision-record (template library).
Activity
solution-architectas an addressable advisory persona (repo-local first cut) #1627solution-architectadvisory persona (manifest + advisory prompt + interaction contract + eval seed) #1629don-petry commentedon Sep 1, 2026
Dev-Lead: issue #1628 implementation failed — will retry
All engines were rate-limited. This was attempt 1 of 3; dev-lead will retry automatically. You can also re-apply the
dev-leadlabel to retry now.rate-limitedLast 40 lines of engine output (redacted)
at throwErrorIfNotOK (file:///home/runner/.npm-global/lib/node_modules/@google/gemini-cli/bundle/chunk-7HKQGPWB.js:267240:24) at process.processTicksAndRejections (node:internal/process/task_queues:103:5) at async file:///home/runner/.npm-global/lib/node_modules/@google/gemini-cli/bundle/chunk-7HKQGPWB.js:267003:7 at async Models.generateContentStream (file:///home/runner/.npm-global/lib/node_modules/@google/gemini-cli/bundle/chunk-7HKQGPWB.js:268099:16) at async file:///home/runner/.npm-global/lib/node_modules/@google/gemini-cli/bundle/chunk-7HKQGPWB.js:310468:19 at async file:///home/runner/.npm-global/lib/node_modules/@google/gemini-cli/bundle/chunk-7HKQGPWB.js:287277:23 at async retryWithBackoff (file:///home/runner/.npm-global/lib/node_modules/@google/gemini-cli/bundle/chunk-7HKQGPWB.js:307305:23) at async GeminiChat.makeApiCallAndProcessStream (file:///home/runner/.npm-global/lib/node_modules/@google/gemini-cli/bundle/chunk-7HKQGPWB.js:331095:28) at async GeminiChat.streamWithRetries (file:///home/runner/.npm-global/lib/node_modules/@google/gemini-cli/bundle/chunk-7HKQGPWB.js:330848:29) at async Turn.run (file:///home/runner/.npm-global/lib/node_modules/@google/gemini-cli/bundle/chunk-7HKQGPWB.js:331770:24) { status: 429 } Attempt 10 failed: Your prepayment credits are depleted. Please go to AI Studio at https://ai.studio/projects to manage your project and billing. Learn more at https://ai.google.dev/gemini-api/docs/billing#prepay. . Max attempts reached Error when talking to Gemini API Full report available at: /tmp/gemini-client-error-Turn.run-sendMessageStream-2026-09-01T02-33-03-166Z.json RetryableQuotaError: Your prepayment credits are depleted. Please go to AI Studio at https://ai.studio/projects to manage your project and billing. Learn more at https://ai.google.dev/gemini-api/docs/billing#prepay. at classifyGoogleError (file:///home/runner/.npm-global/lib/node_modules/@google/gemini-cli/bundle/chunk-7HKQGPWB.js:306592:14) at retryWithBackoff (file:///home/runner/.npm-global/lib/node_modules/@google/gemini-cli/bundle/chunk-7HKQGPWB.js:307328:29) at process.processTicksAndRejections (node:internal/process/task_queues:103:5) at async GeminiChat.makeApiCallAndProcessStream (file:///home/runner/.npm-global/lib/node_modules/@google/gemini-cli/bundle/chunk-7HKQGPWB.js:331095:28) at async GeminiChat.streamWithRetries (file:///home/runner/.npm-global/lib/node_modules/@google/gemini-cli/bundle/chunk-7HKQGPWB.js:330848:29) at async Turn.run (file:///home/runner/.npm-global/lib/node_modules/@google/gemini-cli/bundle/chunk-7HKQGPWB.js:331770:24) at async GeminiClient.processTurn (file:///home/runner/.npm-global/lib/node_modules/@google/gemini-cli/bundle/chunk-7HKQGPWB.js:345315:22) at async GeminiClient.sendMessageStream (file:///home/runner/.npm-global/lib/node_modules/@google/gemini-cli/bundle/chunk-7HKQGPWB.js:345412:14) at async file:///home/runner/.npm-global/lib/node_modules/@google/gemini-cli/bundle/gemini-OYYGXMHL.js:11527:26 at async main (file:///home/runner/.npm-global/lib/node_modules/@google/gemini-cli/bundle/gemini-OYYGXMHL.js:16954:5) { cause: { code: 429, message: 'Your prepayment credits are depleted. Please go to AI Studio at https://ai.studio/projects to manage your project and billing. Learn more at https://ai.google.dev/gemini-api/docs/billing#prepay. ', details: [] }, retryDelayMs: undefined, status: 429 } { "session_id": "f23949e9-bde4-4333-b77f-9e591a81f002", "error": { "type": "Error", "message": "Your prepayment credits are depleted. Please go to AI Studio at https://ai.studio/projects to manage your project and billing. Learn more at https://ai.google.dev/gemini-api/docs/billing#prepay. ", "code": 429 } }don-petry commentedon Sep 1, 2026
Dev-Lead Implementation Plan
Issue: #1628 — [Phase 1] Seed the architecture-of-record (ADR convention + 4–6 lifted ADRs) for .github-private
Scope
Create a repo-local
docs/architecture/adr/tree: an ADR-process record plus 5 accepted ADRs, each lifting structural doctrine already written inAGENTS.md(no invented rules, noviews/, no generator, no org-standard or cross-repo edits).Implementation Checklist
docs/architecture/adr/0000-adr-process.md— convention: sequentialNNNN-title.md;status: proposed | accepted | superseded-by-NNNN; immutability rule (accepted ADR is immutable; a reversal is a NEW superseding ADR, never an in-place edit); Nygard 5-section template (Title / Status / Context / Decision / Consequences).0001-thin-caller-reusable-two-tier.md— lifts AGENTS.md §"Workflow Files" + "Reusable caller-input contract". Checkable boundary: a.github/workflows/*.ymlcaller stub only forwards to a pinned first-partypetry-projects/*reusable and must not interpolate secrets intorun:.0002-channel-tag-release-and-rings.md— lifts AGENTS.md §"Release channel tags & the mutable-ref exception". Checkable: immutable<name>/vX.Y.Znever moves; moving channel tags<name>/v<MAJOR>-<tier>are the only sanctioned mutable-ref exception; caller-stub input forwarding follows the 3-step sequence.0003-rubric-registry-contract.md— lifts AGENTS.md §"Review artifact contract & rubric registry". Checkable: register a newartifact_typeby adding areview-registry.tsvmanifest row; do not fork the reviewer; the registry must not change engine/model routing.0004-pure-logic-plus-bats.md— lifts AGENTS.md §"Scripts" + thescripts/*.sh+tests/*.batsconvention (spec-drift.sh,fleet_stub_drift.sh). Checkable:main()does I/O; pure classifiers are unit-tested in bats; LLM used only where it must be.0005-advisory-by-default-personas.md— lifts the persona pattern (personas/security-lead/persona.ymltriggers.default_mode: advisory). Checkable: a persona is advisory on every surface unless a write mode is opted in with its own gate label.Tests to Write
markdownlint-cli2(already runs inlint.yml) keeping the ADRs lint-clean; no bespoke ADR validator (out of scope per Dev Notes).Test Command
markdownlint-cli2 "docs/architecture/adr/**/*.md"(plusbash .dev-lead/scripts/dev-lead-lint.shfor the repo gate)don-petry commentedon Sep 1, 2026
Dev-Lead: Implementation Complete — PR #1638
The implementation for issue #1628 is durable: commits are pushed and a pull request is open. This record is backed by verifiable artifacts you can confirm in one click.
624122af59ff66714f228b60f6ee8fa85c99f1caReview happens on the PR. Acceptance criteria and test results are evidenced by the PR's diff and CI checks — not asserted here. If a later stage fails, this claim is retracted in place.
feat: implement issue #1628 — [Phase 1] Seed the architecture-of-reco…