Proposal: ch18 treatment of per-item convergence over Wave -- 'note on Wave' (Path A) OR narrowed Reconciliation Loop Tier-3 row (Path B)

[danielmeppiel]

Proposal: ch18 rosetta-stone treatment of Shepherd (per-item convergence over Wave) - "note on Wave" OR narrowed Tier-3 row

TL;DR

A real run of the batch-bug-shepherd skill in microsoft/apm (10 issues triaged, 7 PRs shepherded twice with a fold loop, all 7 converged to ship_now / ready-to-merge) surfaced a per-item convergence shape over a Wave macro that ch18's current entries do not name directly. Three independent adversarial subagents reviewed an initial proposal to add a Shepherd Tier-3 row between Wave and Scatter-Gather. Convergent verdict on the proposal as-stated: rejected for ch18 inclusion (insufficient cross-repo / cross-operator evidence; structurally reducible to existing entries; name violates the topology-axis convention; touches four ch19 anti-patterns without structural defense).

Two narrowed paths survive review. This issue documents both and asks the maintainer to pick.

Path A (safer, per handbook-rosetta adversarial reviewer)

Add a third "A note on..." commentary block under the ch18 dispatch table (parallel to the existing notes on Wave and Panel), titled "A note on per-item convergence over Wave". The note documents the composition Wave + Threading + Plan-Write-Then-Reload + Audit Trail + per-item bounded loop with operational stop predicate and names the failure mode Recommendation-as-backlog without minting a new pattern. Defer the Tier-3 promotion until convergence evidence exists across at least one independent operator and one second repo.

Path B (shippable, per genesis-rigor adversarial reviewer)

Add a narrowed Tier-3 row named Reconciliation Loop (NOT Shepherd) between Wave and Scatter-Gather, citing Kubernetes operator pattern as the classical analogue (decade-stable field literature for per-resource convergence loops with bounded backoff and declarative desired state), with batch-bug-shepherd as the worked agentic instance. Anti-pattern warnings enumerate all four ch19 risks (Scope Creep, Cost Runaway, Almost-Done Trap, Unbounded Agent). Dark-factory framing fully withdrawn.

Recommendation

Path A is the lower-risk default, per the handbook-rosetta reviewer's strongest finding: ch18 L165-171 explicitly excludes "patterns the field has not yet converged on," and N=6 in one repo by one operator is pre-convergence. Path B is shippable if you accept that rosetta tables tolerate composition recipes the genesis topology catalogue cannot, and if the disclosure + anti-pattern enumeration are airtight.

If you pick Path B, the genesis catalogue contribution moves to a separate addendum (see companion issue at danielmeppiel/genesis).

Why the original Shepherd Tier-3 proposal does not survive review

Four convergent adversarial findings:

1. Structurally reducible to existing ch18 entries (handbook-rosetta + genesis-rigor). The author's own decomposition (PART 3 of the original proposal): shepherd = A3 ORCHESTRATOR-SAGA (macro) + A5 WAVE EXECUTION (phase-to-phase) + B1 FAN-OUT + SYNTHESIZER (intra-wave) + a per-item inner loop. Three of four components are already in ch18. The fourth is one parameterization of A8.
2. Name on the wrong axis (handbook-rosetta + genesis-rigor). ch18 names are activity-shape (Panel, Wave, Scatter-Gather) or vendor-classical (Threading, Subagent Spawn). Shepherd is a role/person noun importing semantics (caring, watchful, patient) that mislead readers into reading discipline as structure.
3. Empirical base below the ch18 bar (handbook-rosetta blocking). ch18 L8 thesis: "the field has converged on recognizable solutions." ch18 L165-171 names "patterns the field has not yet converged on" as an explicit exclusion. N=6 in one repo by one operator is pre-convergence.
4. Four ch19 anti-patterns touched without structural defense (handbook-rosetta blocking): Unbounded Agent (capability gating absent), Scope Creep (fold rubric inverts ch19 L113 prescription), Cost Runaway (subagent capacity asserted unlimited), Almost-Done Trap (convergence loop does not first-class "accept the 90% and stop").

Strongest classical analogue (a reviewer-surfaced correction)

The original proposal cited "Saga (Garcia-Molina 1987) - partial" + "Closed-loop Controller - partial" as classical analogues, both flagged partial. The handbook-rosetta reviewer surfaced that Kubernetes operator pattern / Reconciliation Loop (2014-2016 vintage; decade-stable literature; per-resource convergence loop with bounded backoff and declarative desired state) maps the shape far more cleanly: per-item terminal state set, bounded iteration, deterministic-plus-arbiter stop predicate, persisted ground-truth log. This is the strong-form classical analogue ch18 expects (compare ch18 L188 Lockfile -> Kleppmann 2017, L196 Distributed Tracing -> Dapper 2010, L198 Audit Trail -> Fowler 2005).

If Path B is chosen, the entry should be named Reconciliation Loop and explicitly anchor to the Kubernetes operator literature, not to Saga.

Path A draft text - "A note on per-item convergence over Wave"

### A note on per-item convergence over Wave

When the Wave pattern's per-stratum work is itself a long-lived
convergence over independent items (each item iterates a fold-review-push-
verify body until reaching a closed-set terminal verdict), the resulting
composition is `Wave + Threading + Plan-Write-Then-Reload + Audit Trail
+ per-item bounded loop with operational stop predicate`. The terminal
verdict set for each item is closed (typical: `ready-to-merge`,
`advisory-with-deferred`, `superseded`, `blocked`); the stop predicate
is the conjunction of N deterministic system predicates (e.g., CI green,
lint silent, zero foldable items) and one bounded arbitration verdict
(e.g., panel-CEO `ship_now`). Worked reference in microsoft/apm
batch-bug-shepherd. Closest classical kin: Kubernetes operator pattern
(2014-, per-resource reconciliation loop with bounded backoff).

The failure mode this composition exists to defeat is
`Recommendation-as-backlog`: posting an advisory and stopping on first
review instead of folding-then-iterating, collapsing to a panel-with-
extra-ceremony and re-introducing the queue the composition exists to
close.

Not yet promoted to a Tier-3 row in this chapter; field convergence
across independent operators and independent repos has not been
established at time of writing.

Path B draft text - Reconciliation Loop Tier-3 entry

### Reconciliation Loop

Drive a batch of work items in mixed lifecycle states to one of a
closed set of terminal verdicts, by composing a bounded per-item
convergence loop whose stop predicate is the conjunction of N
deterministic system predicates and one arbiter verdict.

Classical analogue: Kubernetes operator pattern / Reconciliation
Loop (Hightower 2016, Beda 2017). Per-resource convergence over a
declarative desired state, with bounded backoff and observed-vs-desired
gap as the inner loop driver. The agentic adaptation substitutes
declarative desired state with a stated PR / item scope, and substitutes
operator code with a per-item subagent dispatched under the Wave
pattern.

When to apply:
- Input is a heterogeneous batch (mixed lifecycle states per item).
- Per item, the terminal condition is operational (deterministic
  predicates plus an arbiter), not creative alignment.
- The cost of leaving items in a partial/advisory state exceeds the
  cost of an extra fold iteration.

Anti-pattern warnings:
- Recommendation-as-backlog: posting advisory and stopping on first
  review instead of folding-then-iterating.
- Unbounded Agent (ch19 L76-86): holding write capability for
  irreversible effects rather than delegating to a deterministic
  post-stage.
- Cost Runaway (ch19 L205-216): asserting "unlimited subagent capacity"
  without per-sweep concurrency budget.
- Scope Creep (ch19 L102-114): folding scope-expansion items by
  default without an absolute fold-count cap; the fold-by-default
  rubric must define a hard ceiling.
- Almost-Done Trap (ch19 L220-232): the convergence loop must
  first-class "accept the partial result and stop" as a distinct
  verdict from cap-driven `advisory-with-deferred`.
- Flaky-Predicate Oscillation: deterministic stop predicates on
  non-deterministic signals (flaky CI, network-dependent lint)
  oscillate the loop indefinitely; pair every operational stop with a
  per-predicate retry-and-quarantine policy.

Worked agentic instance: microsoft/apm batch-bug-shepherd (10 issues
triaged, 7 PRs converged to ready-to-merge in 2 waves on PRs
#1472, #1486, #1512, #1513, #1514, #1515, #1516).

Architecture diagram (the composition either path documents)

flowchart TD
    Intake["Intake<br/>(open issues or<br/>in-flight PRs)"]
    Wave["A5 WAVE EXECUTION<br/>scope -> triage -> alignment<br/>-> xref -> shepherd/fix<br/>-> completion -> report"]
    Subagent["Per-item subagent<br/>(Threading / Subagent Spawn)"]
    Loop["Per-item convergence loop<br/>(bounded outer cap)"]
    Body["Body:<br/>review -> classify -> fold -> push -> verify"]
    Stop["Stop predicate<br/>conjunction:<br/>CI_green AND lint_silent<br/>AND zero_foldable<br/>AND arbiter says ship"]
    Verdicts["Closed terminal-verdict set<br/>{ready-to-merge,<br/>advisory-with-deferred,<br/>superseded, blocked}"]
    Plan["Plan-Write-Then-Reload<br/>(persisted ground-truth table,<br/>re-read at every phase)"]
    Audit["Audit Trail<br/>(per-iteration JSON return,<br/>append-only event log)"]

    Intake --> Wave
    Wave --> Subagent
    Subagent --> Loop
    Loop --> Body
    Body --> Stop
    Stop -->|conjunction met| Verdicts
    Stop -->|cap hit| Verdicts
    Stop -->|not yet| Body
    Loop -.-> Plan
    Loop -.-> Audit

    classDef existing fill:#d4edda,stroke:#155724
    classDef new fill:#fff3cd,stroke:#856404
    class Wave,Subagent,Plan,Audit existing
    class Loop,Body,Stop,Verdicts new

Loading

Green = already in ch18. Yellow = the composition the note (Path A) or row (Path B) names.

Failure-mode diagram (what either path teaches a reader to avoid)

flowchart LR
    R["Per-item review surfaces<br/>panel followups<br/>+ Copilot inline comments"]
    A["DEFAULT: post advisory<br/>+ stop on first review"]
    B["DEFAULT: fold scope-aligned items<br/>+ iterate until conjunction met"]

    R -->|Recommendation-as-backlog| A
    R -->|fold-by-default rubric| B

    A --> AOut["Outcome:<br/>advisory queue grows,<br/>items never converge,<br/>panel-with-extra-ceremony"]
    B --> BOut["Outcome:<br/>items converge to terminal verdict,<br/>bounded by outer cap +<br/>fold-count ceiling"]

    classDef bad fill:#f8d7da,stroke:#721c24
    classDef good fill:#d4edda,stroke:#155724
    class A,AOut bad
    class B,BOut good

Loading

Reconciliation with ch19 Scope Creep prescription

ch19 L102-114 prescribes "When scope expansion is discovered mid-task, the correct response is escalation (create a follow-up task), not absorption." The fold-by-default rubric this proposal references inverts that prescription as default.

The reconciliation: the rubric does not absorb ALL scope expansions; it absorbs items that DO NOT cross the stated scope boundary of the work artifact. Items that DO cross are deferred with written scope_boundary_crossed justification. The escalation channel ch19 requires is preserved; the default is flipped only for in-scope items where the cost of queue-and-revisit exceeds the cost of fold-now.

If this reconciliation is unsatisfactory, ch19 L113 should be updated to acknowledge the in-scope-vs-out-of-scope distinction; otherwise the proposed entry inherits ch19 anti-pattern status by default.

Acceptance criteria (Path A)

• A note titled A note on per-item convergence over Wave is added below the ch18 dispatch table, parallel to the existing notes on Wave (L111) and Panel (L109).
• The note names the failure mode Recommendation-as-backlog and the closest classical kin (Kubernetes operator pattern / Reconciliation Loop).
• The note explicitly states that Tier-3 promotion is deferred until field convergence is established.
• No reference to dark software factory or assembly line appears in the note text.

Acceptance criteria (Path B)

• A new Tier-3 row Reconciliation Loop is added between Wave and Scatter-Gather in the ch18 dispatch table.
• The entry's classical analogue is Kubernetes operator pattern / Reconciliation Loop (Hightower 2016, Beda 2017), NOT Saga (Garcia-Molina 1987).
• The entry enumerates six named anti-patterns (Recommendation-as-backlog, Unbounded Agent, Cost Runaway, Scope Creep, Almost-Done Trap, Flaky-Predicate Oscillation) with explicit mitigations.
• The reconciliation paragraph with ch19 L113 is included, or ch19 L113 is updated in the same PR.
• The contribution carries no dark software factory, assembly line, or non-structural framing in the entry text. Dark-factory mapping is published separately, if at all, as a distance-map artifact.
• No reference to dark software factory or assembly line appears in the entry text.

Evidence base

• Realization: microsoft/apm .agents/skills/batch-bug-shepherd/ post-refactor (PR #1518).
• Empirical run: 10 issues triaged, 7 PRs through wave-1-vs-wave-2 fold loop (microsoft/apm #1472, #1486, #1512, #1513, #1514, #1515, #1516), all converged to ship_now.
• Backfilled evals: PR #1518 commit c8ddee45 (3 content evals, 20 trigger evals, real-task refinement doc).
• N=6 across 1 repo by 1 operator: sufficient for Path A (a note); explicitly INSUFFICIENT for Tier-3 promotion under the strict reading of ch18 L165-171, sufficient under the lenient reading favored by the genesis-rigor reviewer.

What was withdrawn from the original proposal (transparency)

The following framings were in the initial pattern-analysis artifact and are NOT being proposed for handbook inclusion:

• Shepherd name (replaced with Reconciliation Loop per the classical-analogue strengthening, or omitted entirely under Path A).
• dark software factory threshold framing. Reviewer surfaced: (i) BCG's "assembly line" is anchored to delivery archetypes (greenfield/brownfield/legacy modernization); batch-bug-shepherd is a brownfield-maintenance CELL, not a peer assembly line; (ii) cross-archetype generality claim is unsupported and likely false at the stop-predicate layer; (iii) the human is still in the per-item loop (one advisory read per iteration per PR), not the per-exception loop BCG defines.
• Non-structural framing of any kind. Removed entirely.
• Operational Convergence Loop as standalone Tier-3 entry (in the companion genesis catalogue). Replaced with an A8 addendum.

Related work

• Companion catalogue contribution at danielmeppiel/genesis: A8 ALIGNMENT LOOP operational-variant addendum + B9 fold-by-default named policy + SKILL.md selection-rule row. Captures the structural insight at zero genesis-catalogue surface-area growth.

[danielmeppiel]

Framing evolved during discovery -- the original Path A / Path B asks have been superseded by an architectural-style framing (Fielding 2000 sense). The pattern is recognised as a discipline asserted continuously over the substrate, not as a feature of any particular runtime. PR coming next applies the superseded framing as its load-bearing move: a new Mode axis (static / style / sugar) alongside the existing Layer axis, with the Reconciliation Loop as the first style-mode entry in the catalogue.