Skip to content

feat(genesis/A11): Reconciliation Loop architectural pattern + selection rule#7

Merged
danielmeppiel merged 2 commits into
mainfrom
feat/a11-reconciliation-loop
May 28, 2026
Merged

feat(genesis/A11): Reconciliation Loop architectural pattern + selection rule#7
danielmeppiel merged 2 commits into
mainfrom
feat/a11-reconciliation-loop

Conversation

@danielmeppiel

Copy link
Copy Markdown
Owner

Closes #6.

TL;DR

Adds A11 RECONCILIATION LOOP to the Tier-3 catalogue (sibling of A8 ALIGNMENT LOOP, not a sub-entry) and B11 FOLD-BY-DEFAULT to the Tier-2 catalogue as its queue-level policy primitive. Wires both into the Step-3 selection rule so the architect persona surfaces the pattern when the intent describes a queue of items each driven to a terminal state under non-determinism.

Recognition, not invention. The agentic instance of the Kubernetes Operator pattern (CoreOS 2016) and the SRE control loop (Beyer et al. 2016); ancestral lineage in PDCA (Shewhart 1939) and the cybernetic loop (Wiener 1948); form-analogue REST (Fielding 2000) for the discipline-over-substrate framing.

What this PR changes

flowchart LR
  C1[architectural-patterns.md] --> C1A[+ A11 entry full template]
  C1 --> C1B[+ catalogue table row]
  C1 --> C1C[+ A8 SEE ALSO one liner]
  C1 --> C1D[+ A11 in selection heuristic]
  C1 --> C1E[+ composition diagram in How-tier3-compose section]
  C2[design-patterns.md] --> C2A[+ B11 FOLD-BY-DEFAULT entry]
  C2 --> C2B[+ Where-each-pattern-lives row]
  C2 --> C2C[+ selection-heuristic row]
  C3[SKILL.md] --> C3A[+ Step-3 trigger phrases for A11]
Loading

Three files, additive only, no existing pattern reshaped.

Why a sibling (A11), not a sub-entry of A8

A8 and A11 are both loop-shaped but their composes-list, anti-pattern set, and selection trigger phrases overlap by <30%:

  • A8 = single-target convergence. One artifact, N rounds, one steward. "Iterate on this PR description until reviewers approve."
  • A11 = queue-of-targets convergence. Per-item bounded loop, per-item stop-predicate from the system of record, cross-item interlocks (single-writer per item), fold-vs-defer policy at the queue level. "Drive N bug-flagged issues each to merged-PR state."

A sub-entry would force readers to skim A8 to find A11. The sibling slot is the honest signal that an architect is making a different call. A8 gets a one-line SEE ALSO; the catalogue table lists both at the same level.

Substrate-portability claim (made precise)

A11 needs only three baseline primitives from the harness:

  1. Sub-agent dispatch -- the runner can spawn a fresh-context sub-agent per item.
  2. Persistent state -- a write surface that survives across spawns and runner re-entry.
  3. Completion signal -- each sub-agent returns a structured verdict.

Vendor sugar (Codex /goal, Claude Code /loop + /goal, Copilot CLI issues #2129 and #3364) packages the re-entry contract; not a prerequisite. We tested this by building the worked example in Copilot CLI specifically because it ships neither -- the discipline rendered without the sugar. Single worked example, framed honestly as our own workbench, not a population claim.

Composition with adjacent patterns

A11 is rarely deployed bare. It nests with three other catalogue entries along independent axes -- this is the production-deployment shape:

flowchart TB
  EV[event trigger] --> GATE
  GATE[A10 capability and sandbox gate] --> RUN
  RUN[A11 runner reads state table B4] --> SPAWN
  SPAWN[spawn per item sub-agent C2 plus C4] --> WORK
  WORK[item work]
  WORK --> A8[per item A8 ALIGNMENT LOOP if item is a draft]
  WORK --> A1[per item A1 PANEL if multi lens decision]
  A8 --> SP
  A1 --> SP
  WORK --> SP[S4 stop predicate from system of record]
  SP -->|terminal| UPD[update state table]
  SP -->|non terminal within budget| SPAWN
  SP -->|budget exhausted| HC[B10 human checkpoint]
  UPD --> POL{B11 fold or defer}
  POL -->|fold| RUN
  POL -->|defer| OUT[external queue]
  POL -->|all terminal| DONE[queue closed]
  DONE --> AUDIT[A10 audit surface]
  HC --> AUDIT
  OUT --> AUDIT
Loading

Three composition axes, each independently optional:

Axis Pattern Fits when Adds
Outer wrap A10 GOVERNED OUTER LOOP event-triggered, audited, capability-gated sandbox, audit surface, bounded service-account authority
Per-item drop-in A8 ALIGNMENT LOOP or A1 PANEL item is a draft (A8) or a multi-lens decision (A1) per-item convergence or deliberation, independent of queue mechanics
Queue policy B11 FOLD-BY-DEFAULT follow-ups emerge during convergence fold-by-default vs defer, decided at queue level

Start with A11 alone; add A10 when moving to unattended deployment; add A8 or A1 per item when the per-item work warrants the upgrade. Each addition is a separate decision.

Anti-patterns named in the entry

  • LOOP WITHOUT STOP-PREDICATE -- terminates on token exhaustion, not on a deterministic gate
  • DEFER-BY-DEFAULT -- the queue grows faster than it drains (B11 inverts this)
  • DRIFT WITHOUT REASSERTION -- iteration re-derives state from in-context recall instead of the table
  • MULTI-WRITER PER ITEM -- two sub-agents touch the same item without an interlock
  • QUEUE-LEVEL INTERLOCK -- single-writer per queue is wrong grain; collapses fan-out
  • A8 MISCAST AS A11 / A11 MISCAST AS A8 -- pick the right loop

Maps cleanly to handbook ch19 #10 (Not Fixing Primitives), #14 (Cost Runaway), #17 (Persona Drift).

Worked example

batch-bug-shepherd in microsoft/apm -- the first concrete realization we built while developing this pattern, not external industry validation. Ran a saga in Copilot CLI (no /goal, no /loop) driving ten bug-flagged issues to seven merged PRs across two waves. The signal isn't the conversion rate; it's that the discipline rendered, terminated, and produced merged artifacts on a substrate exposing only the three baseline primitives.

Out of scope (deliberate)

  • New worked-example file under skills/genesis/examples/. Real-world reference is named in the entry; a longer walkthrough is a follow-up if wanted.
  • pattern-tradeoffs.md row for A8-vs-A11. Discriminator lives in both entries' bodies; a formal matrix row is a follow-up if architects report ambiguity in practice.
  • Renaming A8 or renumbering the catalogue.

Companion artifact

A handbook treatment landed in parallel: danielmeppiel/agentic-sdlc-handbook#8 introduces a Mode axis (static / style / sugar) and adds Reconciliation Loop as the first style-mode entry to ch18. Same convergent framing; different audience (handbook is reader-facing prose, this PR is architect-facing reference).

Copilot AI and others added 2 commits May 28, 2026 09:15
…ion rule (refs #6)

Add A11 RECONCILIATION LOOP as a Tier-3 architectural pattern in
the genesis catalogue, sibling to A8 ALIGNMENT LOOP. A8 stays as
single-target convergence; A11 covers queue-of-targets convergence
with per-item bounded loops, cross-item interlocks, and a fold-vs-
defer policy at the queue level.

Classical lineage: Kubernetes Operator pattern (CoreOS, 2016) and
SRE control loop (Beyer et al., 2016); ancestral PDCA (Shewhart
1939) and cybernetic loop (Wiener 1948); form-analogue REST
(Fielding 2000) for the discipline-over-substrate framing.

Real example: the batch-bug-shepherd skill in microsoft/apm, which
runs in GitHub Copilot CLI today without /goal or /loop. Substrate-
portability claim: A11 needs only sub-agent dispatch + persistent
state + completion signal from the harness. Vendor sugar (Codex
/goal, Claude Code /loop, Copilot CLI #2129 + #3364) packages the
re-entry contract; the discipline does not depend on the sugar.

Edits:
- skills/genesis/assets/architectural-patterns.md: A11 entry,
  catalogue-at-a-glance row, A8 forward-reference, bottom
  selection-heuristic entry.
- skills/genesis/assets/design-patterns.md: B11 FOLD-BY-DEFAULT
  entry, layer diagram update, bottom selection-heuristic entry.
- skills/genesis/SKILL.md: Step 3 selection rule expanded to
  include RECONCILIATION LOOP with trigger phrases.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
…mplify mermaid

- batch-bug-shepherd reframed as worked example we built while
  developing the pattern, not external industry validation
- Add A10-wraps-A11-with-per-item-A8-or-A1 composition diagram
  to the 'How Tier-3 patterns compose with each other' section
  with three-axis explanation (outer wrap / per-item drop-in /
  queue policy)
- Simplify A11 topology mermaid: remove <br/> tags, parens-in-
  labels, and edge-label colons so it renders on stricter
  mermaid frontends (Copilot CLI chat, etc.)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Proposal: A8 ALIGNMENT LOOP operational-variant addendum + B9 fold-by-default policy + Shepherd selection-rule (narrowed per adversarial review)

2 participants