Skip to content

[Phase 1] Seed the architecture-of-record (ADR convention + 4–6 lifted ADRs) for .github-private #1628

Closed

Description

@github-actions

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

  1. docs/architecture/adr/0000-adr-process.md exists and records the convention itself: sequential NNNN-title.md filenames; a status field with values proposed | 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.
  2. Between 4 and 6 additional ADRs (0001–000N) are authored by LIFTING structural doctrine that already exists in AGENTS.md/org doctrine — not by inventing new rules. Each is committed with status: accepted.
  3. 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.
  4. Each lifted ADR cites the exact AGENTS.md section (or org-doctrine location) it was lifted from, so the ADR is traceable to existing doctrine rather than new invention.
  5. Scope is honored: no org-level standard, no docs/architecture/views/, no generation script, and no other repo are created or touched.

Tasks / Subtasks

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 → the scripts/*.sh + tests/*.bats convention (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.yml triggers.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/*.yml caller stub must only forward to a pinned petry-projects/* reusable and must not interpolate secrets into run:). 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. markdownlint runs in lint.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

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

  1. don-petry commented on Sep 1, 2026

    @don-petry
    Collaborator

    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-lead label to retry now.

    Last 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
      }
    }
    
    
  2. don-petry commented on Sep 1, 2026

    @don-petry
    Collaborator

    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 in AGENTS.md (no invented rules, no views/, no generator, no org-standard or cross-repo edits).

    Implementation Checklist

    • docs/architecture/adr/0000-adr-process.md — convention: sequential NNNN-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/*.yml caller stub only forwards to a pinned first-party petry-projects/* reusable and must not interpolate secrets into run:.
    • 0002-channel-tag-release-and-rings.md — lifts AGENTS.md §"Release channel tags & the mutable-ref exception". Checkable: immutable <name>/vX.Y.Z never 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 new artifact_type by adding a review-registry.tsv manifest row; do not fork the reviewer; the registry must not change engine/model routing.
    • 0004-pure-logic-plus-bats.md — lifts AGENTS.md §"Scripts" + the scripts/*.sh + tests/*.bats convention (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.yml triggers.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

    • None. Pure-documentation change — Phase 2 (TDD) exception applies. Enforcement is markdownlint-cli2 (already runs in lint.yml) keeping the ADRs lint-clean; no bespoke ADR validator (out of scope per Dev Notes).

    Test Command

    markdownlint-cli2 "docs/architecture/adr/**/*.md" (plus bash .dev-lead/scripts/dev-lead-lint.sh for the repo gate)

  3. don-petry commented on Sep 1, 2026

    @don-petry
    Collaborator

    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.

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

  4. added a commit that references this issue on Sep 1, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    dev-leadFor dev-lead agent pickupinitiativeEpic / initiative tracking issue

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions