Write the GitHub feedback re-entry RFC

[markfreeman-dot-dev]

v2 migration #100 › M7-lifecycle (epic #15) · Size S · Architecture

Goal

An RFC treating GitHub review mechanics as structured re-entry: PR-per-cell, changes-requested comments become a focused_directive, merge unblocks dependents.

Context

Petri's human touchpoints are CLI prompts today; the focused-directive mechanism already exists on the weakest_link path. The mapping raises real questions worth a document first: cell-to-PR identity, auth, poll vs webhook, and merge vs mechanical convergence.

Scope

In:

• RFC in docs/, linked from the ARCHITECTURE-V2 ADR index: motivation, non-goals, and cell-to-PR mapping options (branch-per-cell vs PR-per-colony vs labels).
• Event model: github_feedback_received domain events carrying the focused-directive payload, registered in EVENT_DATA_MODELS.
• Directive-extraction rules (which comment content becomes the directive, how multi-reviewer disagreement resolves) and merge-unblock semantics (flag-don't-requeue default; merge is explicit human requeue).
• Auth model (gh CLI vs token vs GitHub App) and the poll-vs-webhook tradeoff for a tool with no always-on server.
• Invariant stated outright: GitHub approval never substitutes for mechanical convergence; plus a sequence diagram and proposed follow-on issue split.

Out:

• No code, GitHub App registration, or dashboard integration.
• No implementation scheduling (a future milestone decides).

Acceptance criteria

• RFC merged in docs/ and linked from the ARCHITECTURE-V2 ADR index.
• Covers cell-to-PR mapping, directive extraction, merge-unblock semantics, auth, and poll-vs-webhook, each with a recommended option and rationale.
• States the invariant that GitHub approval never bypasses mechanical convergence.
• Proposes the follow-on implementation issue split with rough sizes.
• Explicitly labeled design-first: no implementation is scheduled by this RFC.

Pointers

• docs/ARCHITECTURE-V2.md ADR index
• petri/analysis/convergence.py:130-147 (weakest_link/focused-directive path)
• Issue Add the re-decomposition approval gate to petri grow #87 re-decomposition approval gate (CLI approval precedent)

---

#N in this issue refers to entries in docs/field-reports.md, not issues in this repo.
To claim this issue, leave a comment. Questions welcome — see CONTRIBUTING.md.