docs/architecture.md - 30k-ft architectural guide (gc-toolkit) (tk-d6imi)

[zook-bot]

Summary

Brief — write docs/architecture.md (gc-toolkit)

Goal

Write a new central docs/architecture.md: a concise, 30,000-ft architectural
guide to how gc-toolkit's concepts are implemented. It names the core
features the pack delivers, the architectural pattern behind each, how they
play together, and where each is defined — so the repo reads as one coherent
system and both what's built and what's built next can be checked for
consistency against it.

Audience & altitude

• Primary reader: operator strategic reference — wants the mental model of
  what the pack is and how it's implemented. NOT a contributor how-to.
• Altitude: 30,000 ft. Broad architectural terms. Name the pattern; don't
  tutorialize. No code, no config syntax, no CLI-flag references, no
  file-line detail in prose.
• NOT a decision-tree. It explains how we implement the concepts
  architecturally, not "where to put your change."
• Concise & scannable. Target ~1–2 pages, consistent per-capability
  micro-structure. Each pattern is a phrase; interplay is a line; resist
  expanding into how-to.

Distinctness (one doc per subject — link, don't duplicate)

• foundation.md = the why (beliefs/goals) → link.
• roadmap.md = the where-to (direction/primitives) → link.
• README.md = pitch/install; file-structure.md = filing conventions → link.
• architecture.md = how it's built & how it coheres (patterns + interplay
  • definition-sites). This is its distinct subject.

Organizing spine: two flows + support, on one composition substrate

The pack exists to run two flows; everything else supports them, all wired
by one substrate.

Flow 1 — Attention (the Bead-Universe Operating Model; epic tk-q4xaj)

Pre-advance work before it claims human attention.

• Pattern: ephemeral one-shot first-reaction worker → board-surfaced
  hand-off → resident single-bead host.
• Pieces: proactive pool running mol-first-reaction (cheap read →
  first-reaction card → flag to Helm; sheds first under session pressure;
  mr-only for any code) → Helm attention board (board-weighted surface) →
  bead-host (resident conversation owning one bead).
• Defined in: agents/proactive, formulas/mol-first-reaction.toml,
  services/helm, agents/bead-host.

Flow 2 — Delivery (filed bead → landed, live change)

• Pattern: owned-convoy state machine (closed = landed) +
  integration-branch graduation (multi-bead) + two-sided merge-gate (human
  approval + codex-review-at-live-head) + refinery auto-merge + post-merge
  fast-forward sync of live rig checkouts.
• Pieces: sling/formulas → convoys + integration branches → merge-gates →
  refinery landing → reconcile-rig-checkouts (merged→live).
• Defined in: template-fragments/convoy-integration-branch,
  docs/work-bead-state-machine.md, doctor/check-merge-gate-drop +
  check-pr-prep-*, orders/reconcile-rig-checkouts.toml,
  docs/rig-checkout-reconciler.md.

Support layer — Engine health (keep the flows running unbabysat)

• Pattern: resident patrol loops + idempotent layered startup-discovery
  • deterministic cycle-recycle hook + invariant check-suite.
• Defined in: formulas/mol-*-patrol.toml,
  template-fragments/layered-startup-discovery, overlays/cycle-recycle,
  doctor/check-*.

Support layer — Fork & upstream (live alongside gascity without forking it)

• Pattern: git-native candidate-set model (every commit on origin/main
  diverging from upstream IS the candidate; no held branches/labels) +
  keeper-mediated rebase/land + commit-body-as-review-packet.
• Defined in: packs/gascity-keeper,
  template-fragments/upstream-engagement, docs/gascity-local-patching.md.

Support layer — Doc & knowledge cohesion (keep what's written true, incl. this doc)

• Pattern: two-tier filing (docs/ = true-now, specs// =
  historical) + automated drift/memory audits.
• Defined in: docs/file-structure.md, formulas/mol-doc-keeper-*.toml,
  orders/doc-keeper-*.toml.

Composition substrate — how all of the above is wired & where each lives

• Pattern: import base pack wholesale + additive bare-name fragment-append
  patches (never fork, never whole-file mirror) + opt-in sub-packs for
  rig-specific doctrine.
• Defined in: pack.toml ([imports.gastown]; [[patches.agent]] fragment
  lists), template-fragments/*, packs/gascity-keeper/.
• Native agents (mechanik, bead-host, proactive, polecat-codex/-gemini,
  *-thread) vs patched-imported gastown roster (mayor/deacon/polecat/refinery/
  witness); dog intentionally not vendored (agents/DOG-NOTE.md).

Steward

mechanik owns the pack's evolution; edits to versioned content flow through
beads to polecats (dispatch-don't-edit). Mention briefly, don't expand.

Per-capability entry contract

For each capability: what it delivers · the architectural pattern that
implements it · how it plays with the rest · where it's defined. A small
two-flows diagram (ASCII or mermaid) is welcome IF it aids the at-a-glance "how
they play together" — optional, keep it minimal.

Forward lever (keep it light — a few sentences, NOT a routing tree)

Close with a short note: the doc is the consistency map — new capabilities
should slot into one of these flows/layers and reuse its pattern; that's how
"what gets built next" stays coherent.

Verification (accuracy is the point of a cohesion doc)

• Verify every "where defined" against the actual files before asserting it.
  You are doing the file-level survey — the code wins. Correct any pattern name
  or definition-site this brief got wrong.
• Ground every pattern claim in the pack (pack.toml, the fragments, the
  formulas, the docs). If a claimed pattern isn't how it actually works, fix the
  doc.

Deliverables (both committed on your branch)

1. docs/architecture.md — the guide (central tier; standard frontmatter
   name/description per file-structure.md).
2. specs/<this-bead-id>/requirements.md — this brief as the durable decision
   record (local tier; per the filing-documentation rule it must not live only
   as a bead comment).

Acceptance criteria

• docs/architecture.md exists; central-tier frontmatter; ~1–2 pages; scannable.
• Organized as two flows + support + composition substrate; each capability
  entry carries delivers / pattern / plays-with / defined-in.
• Patterns named at 30k ft; no code / CLI / decision-tree.
• Every definition-site verified against real files.
• Links (not restatements) to foundation.md, roadmap.md,
  file-structure.md, work-bead-state-machine.md,
  gascity-local-patching.md; references epic tk-q4xaj.
• specs/<bead-id>/requirements.md committed.
• PR opened; passes the standard merge-gate. (Owned convoy: closed = landed.)

Process

• Owned convoy anchors this to landed (closed = landed).
• Standard merge-gate applies (human approval + codex). Do not self-merge.
• mechanik reviews before it lands.

Implementation notes

Implemented: docs/architecture.md (30k-ft architectural guide, two flows + 3 support layers + composition substrate; delivers/pattern/plays-with/defined-in per capability; Scope + frontmatter) and specs/tk-d6imi/requirements.md (decision record). All definition-sites verified against files at tip; base ff'd to e843524. Branch polecat/tk-d6imi @ 57592f6.

Refinery handoff

• Issue: tk-d6imi (task, P2)
• Source branch: polecat/tk-d6imi
• Target: main
• Codex signed off pre-open at 57592f62; PR opened codex-green.

[zook-bot]

Codex signoff (pre-open, comment-only — not an approval):

Codex pre-open review: COMMENT

Reviewed branch polecat/tk-d6imi against main at head 57592f62875c43241f84c254b7b0d6b45033999a.

Verdict: Ready to merge. No blocking findings.

Coverage:

• Reviewed docs/architecture.md and specs/tk-d6imi/requirements.md.
• Verified named definition sites against the reviewed tree.
• Spot-checked the architecture claims against pack metadata, the work-bead state-machine doc, refinery/proactive/doc-keeper formulas, Helm/bead-host/proactive files, and upstream keeper docs/fragments.
• Ran git diff --check e8435241a4c5a1db7c7bedb6ddfc999952b846d6 57592f62875c43241f84c254b7b0d6b45033999a; passed.

Artifact: /tmp/compound-engineering/ce-code-review/20260724-052913-f7d70263/report.md