From d934659787ac1b382616a334f00768b2e628e4db Mon Sep 17 00:00:00 2001 From: Greg Allen Date: Wed, 25 Mar 2026 14:14:23 -0400 Subject: [PATCH 01/10] Initial fullsend design. --- docs/ADRs/0002-initial-fullsend-design.md | 465 ++++++++++++++++++++++ docs/architecture.md | 14 +- 2 files changed, 476 insertions(+), 3 deletions(-) create mode 100644 docs/ADRs/0002-initial-fullsend-design.md diff --git a/docs/ADRs/0002-initial-fullsend-design.md b/docs/ADRs/0002-initial-fullsend-design.md new file mode 100644 index 0000000000..1ad79851be --- /dev/null +++ b/docs/ADRs/0002-initial-fullsend-design.md @@ -0,0 +1,465 @@ +--- +title: "Initial Fullsend Design" +status: Proposed +relates_to: + - agent-architecture + - autonomy-spectrum + - code-review + - governance + - intent-representation + - security-threat-model +topics: + - fullsend + - github + - workflow + - agents +--- + +# Initial Fullsend Design + +Date: 2026-03-23 + +## Status + +Proposed + +## Context + +This ADR is the **initial Fullsend design** for a **GitHub-centric issue-to-merge agent workflow**: autonomous agents handling routine work from **issue creation** through **merged PR**. It targets **GitHub-hosted organizations** exploring the [Fullsend vision](../vision.md). Downstream consumers (for example teams in the Konflux ecosystem) may implement it concretely, but the workflow is defined in terms of **GitHub primitives** (issues, PRs, labels, checks, branch protection, CODEOWNERS) so it stays portable. + +Contributors need a **clear, implementable picture** of how work flows when **multiple independent agents** can be triggered: + +- **Automatically** (e.g. when specific labels are applied), and +- **On demand** via **`/` commands** in issue or PR comments, so humans can **restart or resume** the pipeline from any stage without a single central orchestrator process. + +This matches Fullsend’s stated design direction: **trust derives from repository permissions**, **CODEOWNERS and similar rules remain human-owned guardrails**, and **the repository plus branch protection and checks act as the coordination layer** rather than a privileged coordinator agent (see [README](../../README.md) and [agent architecture](../problems/agent-architecture.md)). + +This ADR records a **high-level workflow design** and decomposes it into **building blocks** that teams can implement and harden separately. It assumes **adversarial thinking** and **sandboxed execution** for anything that runs untrusted code or fetches third-party content (aligned with [security threat model](../problems/security-threat-model.md)). + +This document does **not** mandate a single implementation (GitHub App vs Actions vs external runner); it describes **interfaces** (labels, comments, checks) and **responsibilities** so implementations can vary. + +## Decision + +We propose adopting the following **reference workflow** as the mental model for issue → PR → merge with multiple agents, **label-driven state transitions**, **slash-command overrides**, and **explicit sandbox boundaries** underneath each agent class. + +### Actors and triggers + +| Trigger | Purpose | +|--------|---------| +| **Label applied** (automation or human) | Idempotent signal to enqueue or resume work for a named agent role | +| **`/` command in a comment** | Human-in-the-loop control: re-run a stage, override a stuck state, or inject intent | +| **GitHub webhooks** | Delivery mechanism for label/comment/PR/check events to whatever executes agents | +| **Branch protection + required checks** | Non-bypassable quality bar; agents must converge checks before review handoff | +| **CODEOWNERS + branch rules** | Human approval on guarded paths remains **outside** this ADR’s automation scope | + +**Slash commands (illustrative, configurable per repo):** + +- `/triage` — run or re-run triage on the issue +- `/code` — hand issue to PR agent (expects readiness or forces with human ack — policy per repo) +- `/review` — enqueue review swarm for current PR head +- `/reset-triage` — clear triage outcome labels and re-open triage (optional) +- `/flow-trace` — re-generate the **post-merge flow trace** comment (optional; restricted commenters — e.g. maintainers — for recovery or correction after a bad edit) + +Commands should be validated (e.g. authorized commenters, org members only) in implementation. + +### Labels as state machine (reference set) + +Repos may extend this set; names below are **semantic**, not prescriptive strings. + +| Label | Meaning | +|-------|---------| +| `duplicate` | Triage: same work is already tracked elsewhere; this issue should be **closed** and discussion continues on the canonical issue | +| `not-ready` | Triage: insufficient information or failed reproducibility gate | +| `ready-for-coding` | Triage passed; implementation may proceed | +| `ready-for-review` | PR agent finished implementation + checks; awaiting multi-agent review | +| `ready-for-merge` | Review coordinator: **all** reviewers **unanimously** approved merge for this round (subject to branch protection / humans) | +| `requires-manual-review` | Review coordinator: reviewers **did not** unanimously agree to merge (split vote, conflicting conclusions, or conflicting **security severities**); **humans** must decide next steps | + +**Mutual exclusion:** Implementation should enforce consistent label sets (e.g. removing `ready-for-coding` when setting `ready-for-review`). An issue marked **`duplicate`** must **not** carry **`ready-for-coding`**, **`ready-for-review`**, **`ready-for-merge`**, or **`requires-manual-review`**. **`ready-for-merge`** and **`requires-manual-review`** must **not** be applied together on the same issue/PR. + +**Later-phase labels (for reset semantics):** Labels **`ready-for-review`**, **`ready-for-merge`**, and **`requires-manual-review`** are treated as **downstream of triage**; triage and PR-agent **starts** strip them when resetting pipeline state (see below). + +### Agent roles (logical; may map to one or many processes) + +1. **Triage agent** — Duplicate detection, issue intake, reproducibility, test artifact proposal +2. **PR agent** — Branch, implement, test iteratively, open/update PR, fix checks +3. **Review agents** — N parallel reviewers + **one coordinator** (randomly designated per review round) to coalesce feedback +4. **Post-merge trace agent** — After a PR is **merged**, produces a **single audit-style comment** that reconstructs the **end-to-end flow** (issue → triage → implementation → checks → review → merge) so reviewers and auditors can see **what happened at each stage** without replaying the entire thread + +Each role is a **building block**: separate prompts, policies, sandboxes, and CI jobs can evolve independently. + +--- + +## Workflow narrative + +### Phase A — Issue triage + +**Inputs (strict):** The triage agent considers **only**: + +- Issue **`title`** and **`body`** (GitHub REST/GraphQL fields of the same names), +- **GitHub-native file/image attachments** on the issue (when the **Issues** APIs or UI expose them to the agent), +- **Repo context** needed for reproduction and conventions (default branch, contributing guide, etc.). + +It **does not** read the **issue comment thread** for intake decisions—no scanning prior human discussion, `@mentions`, or buried requirements in comments. That keeps triage **bounded**, **cheaper**, and **less exposed** to prompt-injection and noise in long threads. + +**Contributor rule:** If something is missing or wrong for triage, **edit the issue `body`** (and **`title`** if needed) and add or replace **attachments** using **only GitHub’s native issue attachments** (uploads GitHub stores and exposes on the issue—see **Test case artifact** below). Do **not** expect the triage agent to discover updates hidden in comments. **Edits to `title` or `body`** trigger triage again automatically; you can also use **`/triage`**. + +**Triage agent responsibilities:** + +1. **Duplicate detection** — Before investing in reproduction or coding, check whether the same (or substantially the same) problem is **already tracked** in another issue. Use **repo/org search**, **issue list filters**, **embedding or keyword similarity**, or other **policy-defined** signals (implementation choice). Base the match **only** on **`title`**, **`body`**, and **attachments** of the current issue compared to **indexed metadata** of candidate issues—not on reading arbitrary comment threads for candidates unless the search backend already summarized them. If triage concludes the new issue is a **duplicate** with **high enough confidence** (threshold per repo): apply the **`duplicate`** label; post a **triage-output comment** that **links the canonical issue** (GitHub URL or `#NNN` reference) and briefly states why it is considered the same; **close** the **new** issue (`state: closed` via API). Do **not** apply **`ready-for-coding`** or **`not-ready`** for an implementation track. If uncertain, **do not** mark duplicate—continue with normal triage. +2. **Information sufficiency** — From the **`title`**, **`body`**, and **attachments** only, decide whether the issue contains enough detail to act (expected behavior, actual behavior, version/context, minimal steps). If not, post a **structured triage-output comment** listing **specific** missing items and apply **`not-ready`**. Do not start implementation. (That comment is **machine handoff and feedback**, not something the triage agent re-reads as user input on the next run—the next run still trusts **`title` + `body` + attachments**.) +3. **Reproducibility** — When feasible, attempt to **reproduce** the problem inside the **triage sandbox** (see Sandboxing), using **only** what appears in the **`title`**, **`body`**, and attachments. Reproducibility is a **primary** signal for readiness: failure to reproduce with given steps strengthens the case for `not-ready`. **Skip** if the issue was already handled as a **duplicate** (closed). +4. **Test case artifact** — When possible, produce a **test case** aligned with the repo’s **existing test framework** (same runner, conventions, paths). **Attachments** mean **only** what GitHub supports as **issue attachments** (native uploads on the issue via GitHub UI or **Issues API** attachment mechanisms the platform provides). Do **not** rely on ad hoc binary hosting, external blob stores, or non-GitHub “attachment” URLs as a substitute—if it cannot be expressed as **body** text, **fenced code in a triage-output comment**, or a **GitHub-native attachment**, the triage-output comment must still specify exact file paths and patch-shaped instructions for the PR agent. + +**Outcomes:** + +- **Duplicate path:** Apply **`duplicate`**, comment with **link to canonical issue**, **close** this issue; no implementation workflow. +- **Ready path:** Apply **`ready-for-coding`**, summarize reproduction result in the triage-output comment and point to the proposed test artifact. (**`not-ready`** was already cleared at triage **start** if it was set.) +- **Not ready path:** Apply **`not-ready`**, do not apply `ready-for-coding`. + +**Triggers (triage agent):** + +1. **Issue created** (`issues` **`opened`**). +2. **Issue `title` or `body` edited** (`issues` **`edited`** when `title` or `body` changed). +3. **`/triage`** in a comment. + +**When a triage run starts** (before duplicate detection and the rest): **remove** **`not-ready`**, **`ready-for-coding`**, and **all later-phase labels** (**`ready-for-review`**, **`ready-for-merge`**, **`requires-manual-review`**). That **resets the pipeline** on the issue so triage outcomes are authoritative for a new pass. (**`duplicate`** is a triage outcome: do **not** remove it here unless **repo policy** says a new triage run clears it—default is to **leave** **`duplicate`** unless humans removed it.) + +### Phase B — Implementation (PR agent) + +**Entry:** The **`ready-for-coding`** label was **applied** to the issue (trigger event) **or** **`/code`** was invoked—**before** the run strips labels. Issue is **open** and **not** **`duplicate`** (and no other conflicting state). + +**Triggers (PR agent):** + +1. **`ready-for-coding`** label **added** to the issue. +2. **`/code`** in a comment. + +**When a PR-agent run starts:** **remove** **`ready-for-coding`** and **all later-phase labels** (**`ready-for-review`**, **`ready-for-merge`**, **`requires-manual-review`**). Implementation proceeds from the issue **`title` / `body` / attachments** and triage handoff comments—not from stale review/merge labels. + +**PR agent responsibilities:** + +1. **Read issue handoff** — Issue **`title`**, **`body`**, and **attachments** (the canonical human-maintained spec), plus **labels**, plus **triage agent output** (the structured triage-output comment(s) with reproduction summary and proposed test artifact). Do **not** depend on informal human comments for requirements unless repo policy explicitly expands scope. +2. **Branch and implement** — Produce a fix following repo conventions; respect CODEOWNERS implications (agent may still open PR but cannot satisfy human review on guarded paths without humans). +3. **Testing loop (iterative)** — Run the **existing test suite** in the **PR sandbox**. Incorporate **triage-provided tests** if present; if none, **author tests** consistent with the framework. Repeat **implement → test** until **local/CI-equivalent tests pass** in the sandbox used for iteration. +4. **Open or update PR** — Link issue; describe changes. +5. **GitHub checks loop** — After push, **required checks** run on GitHub. On failure, PR agent **fetches logs**, fixes, pushes; repeat until **all required checks pass** (or until policy caps retries — implementation detail). +6. **Handoff to review** — When checks are green: add **`ready-for-review`**. (**`ready-for-coding`** was already removed when this run **started**.) PR agent then **waits** until review outcome. + +### Phase C — Multi-agent review + +**Entry:** The **`ready-for-review`** label was **applied** (or **`/review`** or **PR synchronize** per re-review policy)—**before** the run strips **`ready-for-review`**. + +**Triggers (review swarm + coordinator):** + +1. **`ready-for-review`** label **added** to the issue (or linked PR—policy per repo). +2. **`/review`** in a comment. +3. **PR synchronize** (push to the PR branch)—**re-review** per policy below. + +**When a review run starts:** **remove** **`ready-for-review`**. Reviewers evaluate the current PR head; the coordinator applies outcomes using the algorithm below. + +**Review swarm:** + +- **Configurable count N** of **independent review agents** run in parallel (separate invocations, separate context windows where applicable). +- **Coordinator selection:** One reviewer is **randomly chosen** as **coordinator** for this round (deterministic seed optional for auditability). +- **Coordinator duties:** Collect reviewer outputs; produce **one consolidated GitHub comment** (findings, severity, requested changes); apply the **coordinator algorithm** below; update labels per rules below. + +**Coordinator algorithm (merge vs manual vs rework):** + +- Each reviewer outputs a structured verdict (e.g. **approve merge**, **request changes**, **comment-only**), including **security severity** when relevant. +- **Unanimous approve-merge:** **All** counted reviewers **approve merge** with **no** outstanding **request changes** and **no** **conflicting security severities** on whether the PR is safe to merge. Apply **`ready-for-merge`**, remove **`ready-for-review`** and **`requires-manual-review`** if present. +- **Unanimous request-changes:** **All** agree the PR needs revision (no one approves merge yet). Apply **`ready-for-coding`**, remove **`ready-for-review`** — same as **Changes requested** below (not **`requires-manual-review`**). +- **Not unanimous** (split votes, some approve and some reject, or **conflicting security severities** that prevent a single merge judgment): Apply **`requires-manual-review`**, remove **`ready-for-review`**, do **not** apply **`ready-for-merge`**. The coordinator comment must summarize **who said what** so humans can decide. + +**Outcomes:** + +- **Changes requested** (coordinator maps to unanimous rework): Coordinator comment documents issues; remove **`ready-for-review`**, add **`ready-for-coding`** so the PR agent can resume; clear **`requires-manual-review`** if set. +- **Unanimous merge:** Add **`ready-for-merge`** (and remove **`ready-for-review`**). Actual merge may still require **human approval**, merge queue, or bot merge permission per [governance](../problems/governance.md) — this ADR only defines **agent-visible** labels. +- **Requires manual review:** Add **`requires-manual-review`** (and remove **`ready-for-review`**); do **not** add **`ready-for-merge`**. + +**Re-review policy:** + +- **On every push** to the PR head while the change is **in the review stage** (implementation has handed off to review; automation tracks round state—the **`ready-for-review`** label may already have been **cleared** when the current round **started**): **automatically** enqueue a **new** multi-agent review round (same N, new coordinator selection). This keeps review aligned with the latest diff without waiting for humans. +- **On demand:** **`/review`** in a comment **also** enqueues a review round (re-run or extra pass). **Both** apply: pushes trigger re-review **and** maintainers can force a round via **`/review`** even without a new push. + +### Phase D — Post-merge flow trace + +**Entry:** The linked PR has **merged** to the target branch (merge event / `pull_request` closed as merged, or equivalent signal). Implementation may require an issue link on the PR for a well-formed trace. + +**Purpose:** Support **human review and audit** of autonomous runs. A long issue/PR thread, retried checks, and multiple agent comments are hard to reconstruct. The trace comment is the **canonical narrative** of the run, grounded in **observable platform facts** (timestamps, actors, labels, check conclusions, SHAs, comment links) rather than a free-form recap alone. + +**Post-merge trace agent responsibilities:** + +1. **Collect evidence** — From GitHub (and internal dispatch logs if available): issue and PR timelines, **label transitions** (including **`duplicate`**, **`requires-manual-review`**, **`not-ready`** ↔ **`ready-for-coding`**, **`ready-for-review` ↔ `ready-for-coding`**, and triage re-runs), **issue `body` / `title` edit** events when available, comment timelines with **stable permalinks**, required check runs and final conclusions, merge commit SHA, base/head SHAs at merge (including **head SHA per review round** when useful), and **correlation identifiers** (e.g. trace IDs from the observability building block) when the implementation emits them. Attribute comments to **agent vs human** when the platform provides that signal (e.g. GitHub App actor). +2. **Structure by workflow phase** — Emit sections that mirror **Phase A–C** (triage, implementation, review), each listing **what ran**, **outcome**, and **pointers** (e.g. permalink to the final check suite). Include explicit **handoff points** (labels applied/removed, PR opened, first and last **ready-for-review** / **ready-for-merge** transitions). +3. **Enumerate every triage “not ready” iteration** — The trace **must** document **each** period or pass where the issue was **not workable** yet: every application of **`not-ready`**, every **triage re-run** after a **`body` or `title` edit**, and every transition back toward **`ready-for-coding`** when triage eventually passed. **Do not omit** “failed triage” history because a PR never existed yet—those iterations are often where intent was clarified. If triage instead applied **`duplicate`**, record that pass (label, **link to canonical issue** in the triage comment, **issue closed**) even when **no PR** exists. For **each** triage pass (chronological): + - Note **bounding facts**: label changes, triage trigger (if known), and **issue `updated_at`** (or finer-grained **`body`/`title` change** metadata) when the API exposes it. + - List **triage agent output comments** for that pass (missing-info checklist, ready summary, test proposal) with the same **short summary + permalink** pattern as review rounds. + - If the triage agent applied **`not-ready`** without a comment (misconfiguration), still record the pass and link the best artifact (label timeline only). +4. **Enumerate every implementation–review round-trip** — The trace **must** document **each time** the PR moved from **implementation** into **review** and **back** (the loop in Phase B/C: checks green → `ready-for-review` → coordinator requests changes → `ready-for-coding` → further commits → `ready-for-review` again, etc.). Treat **each** such cycle as a first-class part of the narrative—**do not collapse** multiple review rounds into one paragraph. For **every** cycle, in chronological order: + - Identify the **review round** (e.g. “Review round 1”, “Review round 2”) and anchor it with **facts**: approximate time span, **head SHA** (or merge preview SHA) when available, and label transitions that bound the round. + - Under that round, list **every agent comment that materially drove the workflow** (at minimum the **coordinator** consolidated comment; also **individual review-agent** comments when those are posted separately; **PR-agent** comments that summarize fixes, push results, or responses to review). For **each** such comment, provide: + - A **short summary** (one or two sentences: what was found, decided, or changed). + - A **direct link** to that comment (issue or PR thread) so readers can open the **full** text, images, and code blocks on GitHub. + - If a round produced **no** standalone comment (e.g. only labels or check failures), still record the round and **link** to the best **primary artifact** (coordinator comment if any; otherwise the **check run** or **bot summary** for that push). +5. **Publish** — Post one **top-level comment** on the **issue** (and optionally a shorter pointer on the merged PR — policy per repo). Use a stable heading or marker (e.g. `## Fullsend flow trace`) so `/flow-trace` or automation can **update or replace** the same logical artifact idempotently. +6. **Safety** — **Redact** secrets and sensitive tokens; do not paste large log bodies into the comment—**link** to check runs or artifacts instead. Treat prior issue/PR bodies as **untrusted** when summarizing; prefer **API-sourced facts** over model paraphrase for state transitions. Summaries are **for navigation**; the **permalink** is the source of truth for detail. + +**Triggers:** Merge event (primary); optional `/flow-trace` for regeneration. + +**Note:** This agent runs **after** merge; it does not gate merge. It supports **transparency over trust** (see [vision](../vision.md)) and complements the review swarm by making the **full story** inspectable in one place. + +--- + +## Building blocks (independent work streams) + +These can be owned and shipped separately: + +### 1. Webhook + dispatch service + +Normalize GitHub events, idempotency keys, dedupe label flapping. ([Architecture](../architecture.md#1-webhook--dispatch-service)) + +### 2. Slash-command parser + ACL + +Map comments to intents; audit log. ([Architecture](../architecture.md#2-slash-command-parser--acl)) + +### 3. Label state machine guard + +Validates legal transitions; prevents contradictory labels (including **`duplicate`** vs implementation labels). Coordinates **atomic** **on-start** label strips for triage, PR, and review runs so resets are race-safe. ([Architecture](../architecture.md#3-label-state-machine-guard)) + +### 4. Triage agent runtime + +Prompt, tools, repo context packaging, output schema (triage-output **comment** + labels + optional **close issue**). Context fetchers **must** supply issue **`title`**, **`body`**, and **attachments** only for intake—not the full comment thread. ([Architecture](../architecture.md#4-triage-agent-runtime)) + +### 5. Duplicate / similarity search + +Issue index, search API integration, or LLM-assisted candidate retrieval with **confidence thresholds** and audit logging; feeds triage **before** reproduction. ([Architecture](../architecture.md#5-duplicate--similarity-search)) + +### 6. Repro sandbox template + +Hermetic-ish environment for repro commands (language-specific images). ([Architecture](../architecture.md#6-repro-sandbox-template)) + +### 7. Test artifact formatter + +Emits framework-native test snippets and attachment bundles. ([Architecture](../architecture.md#7-test-artifact-formatter)) + +### 8. PR agent runtime + +Git operations (token-scoped), patch application, local test runner integration. ([Architecture](../architecture.md#8-pr-agent-runtime)) + +### 9. PR sandbox / CI mirror + +Same toolchain as contributors; secrets policy. ([Architecture](../architecture.md#9-pr-sandbox--ci-mirror)) + +### 10. Check failure triage + +Log fetch, classification, fix loop policies (max iterations, escalation). ([Architecture](../architecture.md#10-check-failure-triage)) + +### 11. Review agent runtime + +Static/dynamic analysis hooks, policy packs, output schema. ([Architecture](../architecture.md#11-review-agent-runtime)) + +### 12. Coordinator merge algorithm + +Random coordinator selection; **unanimous** approve-merge → **`ready-for-merge`**; **unanimous** rework → **`ready-for-coding`**; **split or conflicting severities** → **`requires-manual-review`**; consolidated comment schema. ([Architecture](../architecture.md#12-coordinator-merge-algorithm)) + +### 13. Observability + +Trace IDs spanning issue → PR → checks → review for incident response; **feeds the post-merge trace** when logs are queryable by correlation ID. ([Architecture](../architecture.md#13-observability)) + +### 14. Post-merge trace agent runtime + +Merge webhook handler, timeline/check-run fetchers, trace comment schema (markdown), idempotent create/update, redaction rules. ([Architecture](../architecture.md#14-post-merge-trace-agent-runtime)) + +### 15. Flow trace formatter + +Maps raw events into the Phase A–C narrative; **detects triage “not ready” iterations** and **implementation–review cycles** from label/timeline (and **`body`/`title`-edit** signals when available); resolves **comment permalinks** for triage, coordinator, review, and PR agents; emits **summary + link** rows per comment. May be **deterministic** (template + sorted events) or **LLM-assisted** with a **fact bundle** input and strict output schema (implementation choice); if LLM-assisted, summaries must still **not contradict** linked comments. ([Architecture](../architecture.md#15-flow-trace-formatter)) + +--- + +## Sandboxing (underneath the agents) + +**Principle:** Anything that **executes repository code**, **runs user-supplied repro steps**, or **fetches network content** runs in a **dedicated sandbox** with **least privilege**, **no write access to production systems**, and **ephemeral credentials**. + +**Layers (conceptual):** + +| Sandbox | Used by | Contains | +|--------|---------|----------| +| **Triage / repro** | Triage agent | Issue-derived commands, dependency install, repro script; **read-only** clone or shallow fetch; network egress policy per threat model | +| **PR / build-test** | PR agent | Full dev dependencies, test execution, compiler; **push** only to bot-owned branches; PR secrets (tokens) scoped to repo | +| **Review** | Review agents | Optional dynamic checks; **no** merge rights; optional read-only or isolated run for fuzzing | +| **Post-merge trace** | Post-merge trace agent | **Read-mostly** access to GitHub APIs and optional internal observability stores; **post comment** (and edit own trace comment) only; **no** merge or branch write; no execution of repo code unless explicitly required for forensics (default: none) | +| **GitHub Actions / hosted runner** | Checks | Org-controlled workflows; OIDC where possible | + +**Data flow:** Agents receive **minimal** tokens (fine-scoped GitHub App). **Secrets** never appear in issue **`body`**, PR **`body`**, or **comments**. **Prompt injection** from those surfaces is assumed — see [security threat model](../problems/security-threat-model.md): triage and review prompts should treat **`body`** text and **comments** as **untrusted**, with tool allowlists and output validation. The post-merge trace agent should **anchor** the trace in **API-derived events** so an attacker cannot rewrite history via issue **`body`** alone; any narrative layer must not contradict those facts. + +--- + +## Diagrams + +The first figure is the **happy-path lifecycle** with **explicit triggers** (labels, slash commands, merge). The second is a **layered platform view**: what lives in GitHub vs dispatch vs agents vs sandboxes. + +### End-to-end flow (labels, slash commands, merge) + +```mermaid +flowchart TB + subgraph TRG["Triggers"] + direction LR + LB[Label events] + S1["/triage"] + S2["/code"] + end + + subgraph PH1["Phase A — Issue triage"] + T[Triage agent] + TR{Sufficient info + repro?} + NR[not-ready] + RFC1[ready-for-coding] + end + + subgraph PH2["Phase B — PR implementation"] + P[PR agent] + TC{Tests + checks green?} + RFR[ready-for-review] + end + + subgraph PH3["Phase C — Multi-agent review"] + S3["Slash: /review"] + RW["Review swarm + coordinator"] + CHG{Changes needed?} + RFC2[ready-for-coding] + RFM[ready-for-merge] + end + + subgraph PH4["Phase D — Post-merge"] + M["Merged PR (merge event)"] + S4["Slash: /flow-trace"] + PT[Post-merge trace agent] + FC[Flow trace comment] + end + + LB --> T + S1 --> T + T --> TR + TR -->|no| NR + TR -->|yes| RFC1 + + RFC1 --> P + LB --> P + S2 --> P + P --> TC + TC -->|iterate| P + TC -->|yes| RFR + + S3 -->|dispatch| RW + RFR --> RW + LB --> RW + RW --> CHG + CHG -->|yes| RFC2 + RFC2 --> P + CHG -->|no| RFM + + RFM --> M + M -->|merge webhook| PT + S4 -.->|optional regen| PT + PT --> FC +``` + +**How to read it:** **`/triage`** and **`/code`** sit in the top **Triggers** strip with **labels**. **`/review`** and **`/flow-trace`** sit **inside** Phases C and D so the **arrows into** the review swarm and post-merge trace agent are short and obvious. **`M --> PT`** is the primary merge path; **`S4 --> PT`** is **regeneration** of the flow-trace comment after merge. + +### Sandbox stack (layered platform) + +```mermaid +flowchart TB + subgraph L1["GitHub — surfaces"] + direction LR + IPL["Issues & PRs · labels · checks"] + CMT["Comments · slash commands"] + MRG[Merge & PR closed events] + end + + subgraph L2["Control plane"] + direction TB + WH[Webhook ingest & normalize] + SP[Slash parser + ACL] + SM[Label state guard] + WH --> SP + SP --> SM + end + + subgraph L3["Agent runtimes"] + direction LR + TA[Triage agent] + PA[PR agent] + RA[Review + coordinator] + PT[Post-merge trace] + end + + subgraph L4["Sandboxes (least privilege)"] + direction LR + SB1["Triage / repro"] + SB2["PR build-test"] + SB3[Review] + SB4["Trace · read-mostly"] + end + + IPL --> WH + CMT --> WH + MRG --> WH + SM --> TA + SM --> PA + SM --> RA + SM --> PT + SP -->|"/review"| RA + SP -->|"/flow-trace"| PT + TA --> SB1 + PA --> SB2 + RA --> SB3 + PT --> SB4 + PA <--> IPL + PT --> IPL +``` + +**How to read it:** **Comments** (including **`/triage`**, **`/code`**, **`/review`**, **`/flow-trace`**) feed **webhook ingest** together with **issues/PRs/labels/checks** and **merge / PR-closed** events. **`/review`** and **`/flow-trace`** also show as **explicit edges** from the **slash parser** to the **review** and **post-merge trace** runtimes (alongside the **label-guard** dispatch). The **PR agent** ↔ **checks** loop is the **bidirectional** edge on the issue/PR surface. + +--- + +## Consequences + +### Positive + +- **Composable delivery:** Teams can implement dispatch, triage, PR, and review independently. +- **Human operability:** Labels + slash commands give **observable** state and **recovery** without a single orchestrator brain. +- **Alignment with Fullsend themes:** Sandboxes and check loops mirror **autonomy is earned** from [vision](../vision.md); coordination stays in repo mechanics rather than a coordinator agent. +- **Reviewable audit trail:** The **post-merge flow trace** gives a **single place** to reconstruct what each stage did, improving **post-merge review**, incident analysis, and onboarding without reading entire threads. + +### Negative / risks + +- **Label races:** Concurrent automation can fight; requires idempotency and state guard (building block). +- **Cost and latency:** Multi-agent review × N is expensive; needs quotas and backoff. +- **False readiness:** Over-trusting reproduction in a sandbox unlike user environments — mitigated by documenting environment assumptions in triage comments. +- **Governance:** `ready-for-merge` must not bypass **branch protection** or **CODEOWNERS** unless org policy explicitly allows bot merge. +- **Trace fidelity vs cost:** Large repos or noisy automation may produce huge timelines; the formatter must **summarize with links** and cap inline content to avoid unusable comments and API rate-limit pain. Many **code–review cycles** can make the trace long; prefer **compact summaries** while **retaining every cycle** and **every** agent-comment link. +- **Narrative drift:** If the trace uses an LLM, it could **misstate** history unless constrained to **verified facts**; deterministic or schema-locked output reduces that risk. + +## Open questions + +- Exact **label naming** and **per-repo customization** (config file in repo vs org defaults). +- **Merge authority:** When may a bot merge after `ready-for-merge`? (Overlaps [governance](../problems/governance.md) and [autonomy spectrum](../problems/autonomy-spectrum.md).) +- **Interaction with** [intent representation](../problems/intent-representation.md) and [autonomy spectrum](../problems/autonomy-spectrum.md) for repos that should not auto-advance stages. +- **Flow trace placement:** Issue only, PR only, or both; how to handle **multiple PRs** per issue or **squash** vs **merge** commit naming in the narrative. +- **Flow trace implementation:** Fully **deterministic** formatter vs **LLM** with structured inputs; minimum **fact** fields required before posting. +- **Comment graph:** How to reliably associate review sub-comments with a **round** when threading or edits differ by GitHub surface (issue vs PR conversation). +- **Issue `body`/`title` history:** GitHub may not expose full revision history for **`body`** and **`title`** via API; tracing *what* changed between triage passes may be limited to **`updated_at`** (and webhook payloads) unless the org adds external logging. +- **Duplicate detection:** Search scope (repo vs org), **confidence threshold**, human override when the bot marks **`duplicate`** incorrectly, and whether to require **linked** duplicate-of metadata (GitHub **linked issues**) in addition to labels. + +## References + +- [Vision](../vision.md) +- [Roadmap](../roadmap.md) +- [README](../../README.md) +- [Agent architecture](../problems/agent-architecture.md) +- [Security threat model](../problems/security-threat-model.md) +- [Autonomy spectrum](../problems/autonomy-spectrum.md) +- [Code review](../problems/code-review.md) +- [Governance](../problems/governance.md) +- [ADR 0001 — Use ADRs for decision making](./0001-use-adrs-for-decision-making.md) diff --git a/docs/architecture.md b/docs/architecture.md index 4cbd5525ed..a612ee53fc 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -16,6 +16,8 @@ Infrastructure platform choice and configuration are specified in the org's `/.fullsend` repo and can be overridden per-repo. (See [ADR 0003](ADRs/0003-org-config-repo-convention.md).) + +**Open questions:** Sandbox defaults (network policy, filesystem restrictions) are configured in the org's `/.fullsend` repo and can be overridden per-repo. (See [ADR 0003](ADRs/0003-org-config-repo-convention.md).) @@ -37,9 +41,13 @@ Sandbox defaults (network policy, filesystem restrictions) are configured in the ## Agent Harness -The configuration and context layer that prepares an agent for its task. Responsible for providing skills, system prompts, codebase context, tool definitions, and behavioral instructions to the agent runtime. +The harness draws its configuration from the org's `/.fullsend` repo — skills, workflow definitions, and agent behavioral instructions are assembled from the layered config (fullsend defaults < org config < per-repo overrides). (See [ADR 0003](ADRs/0003-org-config-repo-convention.md).) -The harness is what makes a generic LLM into a specific agent with a specific role. It assembles what the agent needs to know and what it's allowed to do before the agent starts working. +**Open questions:** + +- Does the harness live inside the sandbox (configuring the agent from within its isolation boundary) or outside it (preparing the environment before the agent starts)? +- How is codebase context assembled? (See [codebase-context.md](problems/codebase-context.md).) +- How do we version and test harness configurations? (See [testing-agents.md](problems/testing-agents.md).) The harness draws its configuration from the org's `/.fullsend` repo — skills, workflow definitions, and agent behavioral instructions are assembled from the layered config (fullsend defaults < org config < per-repo overrides). (See [ADR 0003](ADRs/0003-org-config-repo-convention.md).) From ebca15ae42994ca00331bdfd90a978f988c477cf Mon Sep 17 00:00:00 2001 From: Greg Allen Date: Thu, 26 Mar 2026 20:11:51 -0400 Subject: [PATCH 02/10] Fixes. --- docs/architecture.md | 109 ++++++++++++++++++++++++++++++++++++------- 1 file changed, 92 insertions(+), 17 deletions(-) diff --git a/docs/architecture.md b/docs/architecture.md index a612ee53fc..ffa22375d8 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -12,9 +12,7 @@ The compute and orchestration layer that runs agent workloads. Responsible for p This is the "where do agents physically run" question — whether that's a managed platform, internal Kubernetes, CI runners repurposed for agent work, or something purpose-built. -Infrastructure platform choice and configuration are specified in the org's `/.fullsend` repo. (See [ADR 0003](ADRs/0003-org-config-repo-convention.md).) - -**Open questions:** +Infrastructure platform choice and configuration are specified in the adopting organization's **`.fullsend`** repository. (See [ADR 0003](ADRs/0003-org-config-repo-convention.md).) **Open questions:** @@ -26,11 +24,9 @@ Infrastructure platform choice and configuration are specified in the org's `/.fullsend` repo and can be overridden per-repo. (See [ADR 0003](ADRs/0003-org-config-repo-convention.md).) - -**Open questions:** +The sandbox is a security primitive. Its job is containment: if an agent is compromised or misbehaves, the blast radius is limited to what the sandbox permits. -Sandbox defaults (network policy, filesystem restrictions) are configured in the org's `/.fullsend` repo and can be overridden per-repo. (See [ADR 0003](ADRs/0003-org-config-repo-convention.md).) +Sandbox defaults (network policy, filesystem restrictions) are configured in the adopting organization's **`.fullsend`** repository and can be overridden per-repo. (See [ADR 0003](ADRs/0003-org-config-repo-convention.md).) **Open questions:** @@ -41,15 +37,11 @@ Sandbox defaults (network policy, filesystem restrictions) are configured in the ## Agent Harness -The harness draws its configuration from the org's `/.fullsend` repo — skills, workflow definitions, and agent behavioral instructions are assembled from the layered config (fullsend defaults < org config < per-repo overrides). (See [ADR 0003](ADRs/0003-org-config-repo-convention.md).) +The configuration and context layer that prepares an agent for its task. Responsible for providing skills, system prompts, codebase context, tool definitions, and behavioral instructions to the agent runtime. -**Open questions:** +The harness is what makes a generic LLM into a specific agent with a specific role. It assembles what the agent needs to know and what it's allowed to do before the agent starts working. -- Does the harness live inside the sandbox (configuring the agent from within its isolation boundary) or outside it (preparing the environment before the agent starts)? -- How is codebase context assembled? (See [codebase-context.md](problems/codebase-context.md).) -- How do we version and test harness configurations? (See [testing-agents.md](problems/testing-agents.md).) - -The harness draws its configuration from the org's `/.fullsend` repo — skills, workflow definitions, and agent behavioral instructions are assembled from the layered config (fullsend defaults < org config < per-repo overrides). (See [ADR 0003](ADRs/0003-org-config-repo-convention.md).) +The harness draws its configuration from the adopting organization's **`.fullsend`** repository — skills, workflow definitions, and agent behavioral instructions are assembled from the layered config (fullsend defaults, then org config, then per-repo overrides). (See [ADR 0003](ADRs/0003-org-config-repo-convention.md).) **Open questions:** @@ -102,7 +94,7 @@ Where agent behavioral rules live. Responsible for holding autonomy levels, revi Policy is distinct from the harness (which configures *how* an agent works) and from intent (which defines *what* work is authorized). Policy defines the *boundaries* of agent behavior — what an agent is allowed to do regardless of what it's asked to do. -The org's `/.fullsend` repo is the natural home for policy configuration — org-wide guardrails, per-repo autonomy levels, and escalation rules all live there, governed by the org's own CODEOWNERS and review process. (See [ADR 0003](ADRs/0003-org-config-repo-convention.md).) +The adopting organization's **`.fullsend`** repository is the natural home for policy configuration — org-wide guardrails, per-repo autonomy levels, and escalation rules all live there, governed by the org's own CODEOWNERS and review process. (See [ADR 0003](ADRs/0003-org-config-repo-convention.md).) **Open questions:** @@ -116,7 +108,7 @@ The system that provides authorized intent for agent work. Responsible for repre Intent answers the question "should this change exist?" before anyone asks "is this change correct?" Without authorized intent, an agent has no basis for deciding what to work on or whether its output matches what was asked for. -The org's `/.fullsend` repo holds the pointer to the intent source (e.g., `intent_repo: /features`), so tooling discovers where intent lives without hardcoding. (See [ADR 0003](ADRs/0003-org-config-repo-convention.md).) +The adopting organization's **`.fullsend`** repository holds the pointer to the intent source (for example, `intent_repo: your-org/features`), so tooling discovers where intent lives without hardcoding. (See [ADR 0003](ADRs/0003-org-config-repo-convention.md).) **Open questions:** @@ -145,10 +137,93 @@ The catalog of available agent roles and their configurations. Responsible for d The registry is the bridge between the abstract roles defined in [agent-architecture.md](problems/agent-architecture.md) (correctness agent, intent alignment agent, etc.) and the concrete runtime configurations that the harness uses to set up each agent. -Fullsend provides a base set of agent definitions. The org's `/.fullsend` repo extends this with org-specific agents in its `agents/` directory, following the inheritance model: fullsend defaults < org config < per-repo overrides. (See [ADR 0003](ADRs/0003-org-config-repo-convention.md).) +Fullsend provides a base set of agent definitions. The adopting organization's **`.fullsend`** repository extends this with org-specific agents in its `agents/` directory, following the inheritance model: fullsend defaults, then org config, then per-repo overrides. (See [ADR 0003](ADRs/0003-org-config-repo-convention.md).) **Open questions:** - How are new agent roles added, tested, and promoted to production? (See [testing-agents.md](problems/testing-agents.md).) - Does the registry include version information, so we can roll back to a previous agent configuration? - How does the registry relate to the policy store — does policy reference registry entries, or are they independent? + +## Reference workflow components (ADR 0002) + +The [Initial Fullsend Design](ADRs/0002-initial-fullsend-design.md) describes a concrete GitHub-centric issue→merge workflow. Its **building blocks** are named below so this document and the ADR stay aligned. Descriptions are brief; the ADR is normative for behavior. + +### 1. Webhook + dispatch service + +Normalizes GitHub events (issue/PR/label/comment/check/merge), deduplicates flapping events, and dispatches work to agent runtimes. +ADR 0002: [Building block 1](ADRs/0002-initial-fullsend-design.md#1-webhook--dispatch-service). + +### 2. Slash-command parser + ACL + +Parses `/triage`, `/code`, `/review`, `/flow-trace` and enforces who is allowed to invoke each command. +ADR 0002: [Building block 2](ADRs/0002-initial-fullsend-design.md#2-slash-command-parser--acl). + +### 3. Label state machine guard + +Validates legal label transitions and enforces mutual exclusion and run-start reset semantics (triage/PR/review label stripping). +ADR 0002: [Building block 3](ADRs/0002-initial-fullsend-design.md#3-label-state-machine-guard). + +### 4. Triage agent runtime + +Runs triage from issue `title`/`body` + GitHub-native attachments only; performs duplicate detection, readiness assessment, reproducibility, test artifact handoff, and can close duplicate issues. +ADR 0002: [Building block 4](ADRs/0002-initial-fullsend-design.md#4-triage-agent-runtime). + +### 5. Duplicate / similarity search + +Provides candidate duplicate retrieval and confidence scoring for triage duplicate decisions. +ADR 0002: [Building block 5](ADRs/0002-initial-fullsend-design.md#5-duplicate--similarity-search). + +### 6. Repro sandbox template + +Isolated environment used by triage for reproducibility checks. +ADR 0002: [Building block 6](ADRs/0002-initial-fullsend-design.md#6-repro-sandbox-template). + +### 7. Test artifact formatter + +Formats triage test artifacts in repo-native conventions for PR handoff. +ADR 0002: [Building block 7](ADRs/0002-initial-fullsend-design.md#7-test-artifact-formatter). + +### 8. PR agent runtime + +Implements changes, runs local/CI-equivalent tests, handles check failures, and advances handoff to review (`ready-for-review`). +ADR 0002: [Building block 8](ADRs/0002-initial-fullsend-design.md#8-pr-agent-runtime). + +### 9. PR sandbox / CI mirror + +Execution environment for implementation and test loops, aligned to contributor/CI toolchains. +ADR 0002: [Building block 9](ADRs/0002-initial-fullsend-design.md#9-pr-sandbox--ci-mirror). + +### 10. Check failure triage + +Fetches and classifies failing check logs to guide PR-agent remediation loops. +ADR 0002: [Building block 10](ADRs/0002-initial-fullsend-design.md#10-check-failure-triage). + +### 11. Review agent runtime + +Runs N parallel reviewers and produces structured review verdicts/comments. +ADR 0002: [Building block 11](ADRs/0002-initial-fullsend-design.md#11-review-agent-runtime). + +### 12. Coordinator merge algorithm + +Aggregates review verdicts and applies labels: + +- unanimous approve-merge → `ready-for-merge` +- unanimous rework → `ready-for-coding` +- split/conflicting (including conflicting security severities) → `requires-manual-review` +ADR 0002: [Building block 12](ADRs/0002-initial-fullsend-design.md#12-coordinator-merge-algorithm). + +### 13. Observability + +Traceability layer across issue, triage, implementation, review, checks, and merge; provides evidence used by post-merge flow tracing. +ADR 0002: [Building block 13](ADRs/0002-initial-fullsend-design.md#13-observability). + +### 14. Post-merge trace agent runtime + +After merge, creates/updates a canonical flow-trace comment with links and short summaries for each workflow stage and iteration. +ADR 0002: [Building block 14](ADRs/0002-initial-fullsend-design.md#14-post-merge-trace-agent-runtime). + +### 15. Flow trace formatter + +Converts raw events into the phase-based trace narrative, including not-ready/duplicate triage iterations and implementation-review round-trips. +ADR 0002: [Building block 15](ADRs/0002-initial-fullsend-design.md#15-flow-trace-formatter). From 591847b397ad27a54e9a458fefa60b3da05f2e14 Mon Sep 17 00:00:00 2001 From: Greg Allen Date: Fri, 27 Mar 2026 14:55:54 -0400 Subject: [PATCH 03/10] Add non-reproducible label. --- docs/ADRs/0002-initial-fullsend-design.md | 34 +++++++++++++---------- 1 file changed, 19 insertions(+), 15 deletions(-) diff --git a/docs/ADRs/0002-initial-fullsend-design.md b/docs/ADRs/0002-initial-fullsend-design.md index 1ad79851be..917253cbf2 100644 --- a/docs/ADRs/0002-initial-fullsend-design.md +++ b/docs/ADRs/0002-initial-fullsend-design.md @@ -57,7 +57,7 @@ We propose adopting the following **reference workflow** as the mental model for - `/triage` — run or re-run triage on the issue - `/code` — hand issue to PR agent (expects readiness or forces with human ack — policy per repo) - `/review` — enqueue review swarm for current PR head -- `/reset-triage` — clear triage outcome labels and re-open triage (optional) +- `/reset-triage` — clear triage outcome labels (including **`not-ready`** and **`not-reproducible`**) and re-open triage (optional) - `/flow-trace` — re-generate the **post-merge flow trace** comment (optional; restricted commenters — e.g. maintainers — for recovery or correction after a bad edit) Commands should be validated (e.g. authorized commenters, org members only) in implementation. @@ -69,13 +69,14 @@ Repos may extend this set; names below are **semantic**, not prescriptive string | Label | Meaning | |-------|---------| | `duplicate` | Triage: same work is already tracked elsewhere; this issue should be **closed** and discussion continues on the canonical issue | -| `not-ready` | Triage: insufficient information or failed reproducibility gate | +| `not-ready` | Triage: insufficient information to proceed (detail missing before a reliable repro attempt) | +| `not-reproducible` | Triage: enough information was available to attempt reproduction, but the reported bug **could not be reproduced** in the triage sandbox; **human intervention** is required. **No further automated processing** (no PR agent, no implementation/review pipeline) while this label is present | | `ready-for-coding` | Triage passed; implementation may proceed | | `ready-for-review` | PR agent finished implementation + checks; awaiting multi-agent review | | `ready-for-merge` | Review coordinator: **all** reviewers **unanimously** approved merge for this round (subject to branch protection / humans) | | `requires-manual-review` | Review coordinator: reviewers **did not** unanimously agree to merge (split vote, conflicting conclusions, or conflicting **security severities**); **humans** must decide next steps | -**Mutual exclusion:** Implementation should enforce consistent label sets (e.g. removing `ready-for-coding` when setting `ready-for-review`). An issue marked **`duplicate`** must **not** carry **`ready-for-coding`**, **`ready-for-review`**, **`ready-for-merge`**, or **`requires-manual-review`**. **`ready-for-merge`** and **`requires-manual-review`** must **not** be applied together on the same issue/PR. +**Mutual exclusion:** Implementation should enforce consistent label sets (e.g. removing `ready-for-coding` when setting `ready-for-review`). An issue marked **`duplicate`** must **not** carry **`ready-for-coding`**, **`ready-for-review`**, **`ready-for-merge`**, or **`requires-manual-review`**. An issue marked **`not-reproducible`** must **not** carry **`ready-for-coding`**, **`ready-for-review`**, **`ready-for-merge`**, or **`requires-manual-review`** — automation stops until humans resolve the situation or triage runs again (see Phase A). **`not-reproducible`** and **`not-ready`** should **not** be applied together (triage picks one outcome per pass). **`ready-for-merge`** and **`requires-manual-review`** must **not** be applied together on the same issue/PR. **Later-phase labels (for reset semantics):** Labels **`ready-for-review`**, **`ready-for-merge`**, and **`requires-manual-review`** are treated as **downstream of triage**; triage and PR-agent **starts** strip them when resetting pipeline state (see below). @@ -106,16 +107,17 @@ It **does not** read the **issue comment thread** for intake decisions—no scan **Triage agent responsibilities:** -1. **Duplicate detection** — Before investing in reproduction or coding, check whether the same (or substantially the same) problem is **already tracked** in another issue. Use **repo/org search**, **issue list filters**, **embedding or keyword similarity**, or other **policy-defined** signals (implementation choice). Base the match **only** on **`title`**, **`body`**, and **attachments** of the current issue compared to **indexed metadata** of candidate issues—not on reading arbitrary comment threads for candidates unless the search backend already summarized them. If triage concludes the new issue is a **duplicate** with **high enough confidence** (threshold per repo): apply the **`duplicate`** label; post a **triage-output comment** that **links the canonical issue** (GitHub URL or `#NNN` reference) and briefly states why it is considered the same; **close** the **new** issue (`state: closed` via API). Do **not** apply **`ready-for-coding`** or **`not-ready`** for an implementation track. If uncertain, **do not** mark duplicate—continue with normal triage. +1. **Duplicate detection** — Before investing in reproduction or coding, check whether the same (or substantially the same) problem is **already tracked** in another issue. Use **repo/org search**, **issue list filters**, **embedding or keyword similarity**, or other **policy-defined** signals (implementation choice). Base the match **only** on **`title`**, **`body`**, and **attachments** of the current issue compared to **indexed metadata** of candidate issues—not on reading arbitrary comment threads for candidates unless the search backend already summarized them. If triage concludes the new issue is a **duplicate** with **high enough confidence** (threshold per repo): apply the **`duplicate`** label; post a **triage-output comment** that **links the canonical issue** (GitHub URL or `#NNN` reference) and briefly states why it is considered the same; **close** the **new** issue (`state: closed` via API). Do **not** apply **`ready-for-coding`**, **`not-ready`**, or **`not-reproducible`** for an implementation track. If uncertain, **do not** mark duplicate—continue with normal triage. 2. **Information sufficiency** — From the **`title`**, **`body`**, and **attachments** only, decide whether the issue contains enough detail to act (expected behavior, actual behavior, version/context, minimal steps). If not, post a **structured triage-output comment** listing **specific** missing items and apply **`not-ready`**. Do not start implementation. (That comment is **machine handoff and feedback**, not something the triage agent re-reads as user input on the next run—the next run still trusts **`title` + `body` + attachments**.) -3. **Reproducibility** — When feasible, attempt to **reproduce** the problem inside the **triage sandbox** (see Sandboxing), using **only** what appears in the **`title`**, **`body`**, and attachments. Reproducibility is a **primary** signal for readiness: failure to reproduce with given steps strengthens the case for `not-ready`. **Skip** if the issue was already handled as a **duplicate** (closed). +3. **Reproducibility** — When feasible, attempt to **reproduce** the problem inside the **triage sandbox** (see Sandboxing), using **only** what appears in the **`title`**, **`body`**, and attachments. **Skip** if the issue was already handled as a **duplicate** (closed). If information is **insufficient** to attempt reproduction meaningfully, apply **`not-ready`** (do not apply **`not-reproducible`**). If information is **sufficient** but the bug **cannot be reproduced** after a good-faith attempt, apply **`not-reproducible`**: post a **triage-output comment** stating what was tried, flag the issue for **human intervention**, and **do not** enqueue further automated work (**no** PR agent, **no** implementation/review pipeline) until triage runs again. Do **not** use **`not-reproducible`** when the right outcome is simply “need more detail” (**`not-ready`**). 4. **Test case artifact** — When possible, produce a **test case** aligned with the repo’s **existing test framework** (same runner, conventions, paths). **Attachments** mean **only** what GitHub supports as **issue attachments** (native uploads on the issue via GitHub UI or **Issues API** attachment mechanisms the platform provides). Do **not** rely on ad hoc binary hosting, external blob stores, or non-GitHub “attachment” URLs as a substitute—if it cannot be expressed as **body** text, **fenced code in a triage-output comment**, or a **GitHub-native attachment**, the triage-output comment must still specify exact file paths and patch-shaped instructions for the PR agent. **Outcomes:** - **Duplicate path:** Apply **`duplicate`**, comment with **link to canonical issue**, **close** this issue; no implementation workflow. -- **Ready path:** Apply **`ready-for-coding`**, summarize reproduction result in the triage-output comment and point to the proposed test artifact. (**`not-ready`** was already cleared at triage **start** if it was set.) -- **Not ready path:** Apply **`not-ready`**, do not apply `ready-for-coding`. +- **Ready path:** Apply **`ready-for-coding`**, summarize reproduction result in the triage-output comment and point to the proposed test artifact. (**`not-ready`** and **`not-reproducible`** were already cleared at triage **start** if they were set.) +- **Not ready path:** Apply **`not-ready`**, do not apply `ready-for-coding` or `not-reproducible`. +- **Not reproducible path:** Apply **`not-reproducible`**, post a triage-output comment explaining the failed repro attempt, do not apply `ready-for-coding`. **Stop** automated processing for this issue until a **new triage run** (automation or human-triggered) **starts** — at triage **start**, **`not-reproducible`** is **removed** together with **`not-ready`**, **`ready-for-coding`**, and later-phase labels, and triage executes the **full** Phase A sequence again from a clean slate. **Triggers (triage agent):** @@ -123,11 +125,11 @@ It **does not** read the **issue comment thread** for intake decisions—no scan 2. **Issue `title` or `body` edited** (`issues` **`edited`** when `title` or `body` changed). 3. **`/triage`** in a comment. -**When a triage run starts** (before duplicate detection and the rest): **remove** **`not-ready`**, **`ready-for-coding`**, and **all later-phase labels** (**`ready-for-review`**, **`ready-for-merge`**, **`requires-manual-review`**). That **resets the pipeline** on the issue so triage outcomes are authoritative for a new pass. (**`duplicate`** is a triage outcome: do **not** remove it here unless **repo policy** says a new triage run clears it—default is to **leave** **`duplicate`** unless humans removed it.) +**When a triage run starts** (before duplicate detection and the rest): **remove** **`not-ready`**, **`not-reproducible`**, **`ready-for-coding`**, and **all later-phase labels** (**`ready-for-review`**, **`ready-for-merge`**, **`requires-manual-review`**). That **resets the pipeline** on the issue so triage outcomes are authoritative for a new pass and a prior **`not-reproducible`** handoff does not block a full re-triage. (**`duplicate`** is a triage outcome: do **not** remove it here unless **repo policy** says a new triage run clears it—default is to **leave** **`duplicate`** unless humans removed it.) ### Phase B — Implementation (PR agent) -**Entry:** The **`ready-for-coding`** label was **applied** to the issue (trigger event) **or** **`/code`** was invoked—**before** the run strips labels. Issue is **open** and **not** **`duplicate`** (and no other conflicting state). +**Entry:** The **`ready-for-coding`** label was **applied** to the issue (trigger event) **or** **`/code`** was invoked—**before** the run strips labels. Issue is **open** and **not** **`duplicate`**, **not** **`not-reproducible`**, and in no other conflicting state. **Triggers (PR agent):** @@ -189,9 +191,9 @@ It **does not** read the **issue comment thread** for intake decisions—no scan **Post-merge trace agent responsibilities:** -1. **Collect evidence** — From GitHub (and internal dispatch logs if available): issue and PR timelines, **label transitions** (including **`duplicate`**, **`requires-manual-review`**, **`not-ready`** ↔ **`ready-for-coding`**, **`ready-for-review` ↔ `ready-for-coding`**, and triage re-runs), **issue `body` / `title` edit** events when available, comment timelines with **stable permalinks**, required check runs and final conclusions, merge commit SHA, base/head SHAs at merge (including **head SHA per review round** when useful), and **correlation identifiers** (e.g. trace IDs from the observability building block) when the implementation emits them. Attribute comments to **agent vs human** when the platform provides that signal (e.g. GitHub App actor). +1. **Collect evidence** — From GitHub (and internal dispatch logs if available): issue and PR timelines, **label transitions** (including **`duplicate`**, **`not-reproducible`**, **`requires-manual-review`**, **`not-ready`** ↔ **`ready-for-coding`**, **`ready-for-review` ↔ `ready-for-coding`**, and triage re-runs), **issue `body` / `title` edit** events when available, comment timelines with **stable permalinks**, required check runs and final conclusions, merge commit SHA, base/head SHAs at merge (including **head SHA per review round** when useful), and **correlation identifiers** (e.g. trace IDs from the observability building block) when the implementation emits them. Attribute comments to **agent vs human** when the platform provides that signal (e.g. GitHub App actor). 2. **Structure by workflow phase** — Emit sections that mirror **Phase A–C** (triage, implementation, review), each listing **what ran**, **outcome**, and **pointers** (e.g. permalink to the final check suite). Include explicit **handoff points** (labels applied/removed, PR opened, first and last **ready-for-review** / **ready-for-merge** transitions). -3. **Enumerate every triage “not ready” iteration** — The trace **must** document **each** period or pass where the issue was **not workable** yet: every application of **`not-ready`**, every **triage re-run** after a **`body` or `title` edit**, and every transition back toward **`ready-for-coding`** when triage eventually passed. **Do not omit** “failed triage” history because a PR never existed yet—those iterations are often where intent was clarified. If triage instead applied **`duplicate`**, record that pass (label, **link to canonical issue** in the triage comment, **issue closed**) even when **no PR** exists. For **each** triage pass (chronological): +3. **Enumerate every triage “not ready” or “not reproducible” iteration** — The trace **must** document **each** period or pass where the issue was **not workable** yet or was **handed off for human intervention** after a failed repro: every application of **`not-ready`**, every application of **`not-reproducible`** (with summary of what triage attempted), every **triage re-run** after a **`body` or `title` edit** (including reruns that **cleared** **`not-reproducible`** at triage start), and every transition back toward **`ready-for-coding`** when triage eventually passed. **Do not omit** “failed triage” history because a PR never existed yet—those iterations are often where intent was clarified. If triage instead applied **`duplicate`**, record that pass (label, **link to canonical issue** in the triage comment, **issue closed**) even when **no PR** exists. For **each** triage pass (chronological): - Note **bounding facts**: label changes, triage trigger (if known), and **issue `updated_at`** (or finer-grained **`body`/`title` change** metadata) when the API exposes it. - List **triage agent output comments** for that pass (missing-info checklist, ready summary, test proposal) with the same **short summary + permalink** pattern as review rounds. - If the triage agent applied **`not-ready`** without a comment (misconfiguration), still record the pass and link the best artifact (label timeline only). @@ -224,7 +226,7 @@ Map comments to intents; audit log. ([Architecture](../architecture.md#2-slash-c ### 3. Label state machine guard -Validates legal transitions; prevents contradictory labels (including **`duplicate`** vs implementation labels). Coordinates **atomic** **on-start** label strips for triage, PR, and review runs so resets are race-safe. ([Architecture](../architecture.md#3-label-state-machine-guard)) +Validates legal transitions; prevents contradictory labels (including **`duplicate`** and **`not-reproducible`** vs implementation labels). Coordinates **atomic** **on-start** label strips for triage, PR, and review runs so resets are race-safe. ([Architecture](../architecture.md#3-label-state-machine-guard)) ### 4. Triage agent runtime @@ -311,8 +313,9 @@ flowchart TB subgraph PH1["Phase A — Issue triage"] T[Triage agent] - TR{Sufficient info + repro?} + TR{Triage outcome} NR[not-ready] + NREP[not-reproducible] RFC1[ready-for-coding] end @@ -340,8 +343,9 @@ flowchart TB LB --> T S1 --> T T --> TR - TR -->|no| NR - TR -->|yes| RFC1 + TR -->|missing info| NR + TR -->|not reproducible| NREP + TR -->|ready| RFC1 RFC1 --> P LB --> P From 38c2947e2c58cbd0fcd12e25804fe73b1e01c1fa Mon Sep 17 00:00:00 2001 From: Greg Allen Date: Fri, 27 Mar 2026 15:02:39 -0400 Subject: [PATCH 04/10] Make sure not-ready and not-reproducible include a comment with why. Signed-off-by: Greg Allen --- docs/ADRs/0002-initial-fullsend-design.md | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-) diff --git a/docs/ADRs/0002-initial-fullsend-design.md b/docs/ADRs/0002-initial-fullsend-design.md index 917253cbf2..be351569ec 100644 --- a/docs/ADRs/0002-initial-fullsend-design.md +++ b/docs/ADRs/0002-initial-fullsend-design.md @@ -69,8 +69,8 @@ Repos may extend this set; names below are **semantic**, not prescriptive string | Label | Meaning | |-------|---------| | `duplicate` | Triage: same work is already tracked elsewhere; this issue should be **closed** and discussion continues on the canonical issue | -| `not-ready` | Triage: insufficient information to proceed (detail missing before a reliable repro attempt) | -| `not-reproducible` | Triage: enough information was available to attempt reproduction, but the reported bug **could not be reproduced** in the triage sandbox; **human intervention** is required. **No further automated processing** (no PR agent, no implementation/review pipeline) while this label is present | +| `not-ready` | Triage: insufficient information to proceed (detail missing before a reliable repro attempt). Applying this label **must** be accompanied by a **triage-output comment on the issue** that explains **why** (what is missing, unclear, or insufficient)—humans and the next triage pass need that context; **do not** set **`not-ready`** without posting that comment | +| `not-reproducible` | Triage: enough information was available to attempt reproduction, but the reported bug **could not be reproduced** in the triage sandbox; **human intervention** is required. **No further automated processing** (no PR agent, no implementation/review pipeline) while this label is present. Applying this label **must** be accompanied by a **triage-output comment on the issue** that records **what was tried** (commands, versions, environment assumptions) and **how it failed** to match the report (e.g. expected symptom absent, wrong error, tests green, timeouts)—**do not** set **`not-reproducible`** without that comment | | `ready-for-coding` | Triage passed; implementation may proceed | | `ready-for-review` | PR agent finished implementation + checks; awaiting multi-agent review | | `ready-for-merge` | Review coordinator: **all** reviewers **unanimously** approved merge for this round (subject to branch protection / humans) | @@ -108,16 +108,16 @@ It **does not** read the **issue comment thread** for intake decisions—no scan **Triage agent responsibilities:** 1. **Duplicate detection** — Before investing in reproduction or coding, check whether the same (or substantially the same) problem is **already tracked** in another issue. Use **repo/org search**, **issue list filters**, **embedding or keyword similarity**, or other **policy-defined** signals (implementation choice). Base the match **only** on **`title`**, **`body`**, and **attachments** of the current issue compared to **indexed metadata** of candidate issues—not on reading arbitrary comment threads for candidates unless the search backend already summarized them. If triage concludes the new issue is a **duplicate** with **high enough confidence** (threshold per repo): apply the **`duplicate`** label; post a **triage-output comment** that **links the canonical issue** (GitHub URL or `#NNN` reference) and briefly states why it is considered the same; **close** the **new** issue (`state: closed` via API). Do **not** apply **`ready-for-coding`**, **`not-ready`**, or **`not-reproducible`** for an implementation track. If uncertain, **do not** mark duplicate—continue with normal triage. -2. **Information sufficiency** — From the **`title`**, **`body`**, and **attachments** only, decide whether the issue contains enough detail to act (expected behavior, actual behavior, version/context, minimal steps). If not, post a **structured triage-output comment** listing **specific** missing items and apply **`not-ready`**. Do not start implementation. (That comment is **machine handoff and feedback**, not something the triage agent re-reads as user input on the next run—the next run still trusts **`title` + `body` + attachments**.) -3. **Reproducibility** — When feasible, attempt to **reproduce** the problem inside the **triage sandbox** (see Sandboxing), using **only** what appears in the **`title`**, **`body`**, and attachments. **Skip** if the issue was already handled as a **duplicate** (closed). If information is **insufficient** to attempt reproduction meaningfully, apply **`not-ready`** (do not apply **`not-reproducible`**). If information is **sufficient** but the bug **cannot be reproduced** after a good-faith attempt, apply **`not-reproducible`**: post a **triage-output comment** stating what was tried, flag the issue for **human intervention**, and **do not** enqueue further automated work (**no** PR agent, **no** implementation/review pipeline) until triage runs again. Do **not** use **`not-reproducible`** when the right outcome is simply “need more detail” (**`not-ready`**). +2. **Information sufficiency** — From the **`title`**, **`body`**, and **attachments** only, decide whether the issue contains enough detail to act (expected behavior, actual behavior, version/context, minimal steps). If not, post a **structured triage-output comment on the issue** first (or in the **same atomic update** as the label) that lists **specific** missing items and explains **why** the issue cannot proceed yet—then apply **`not-ready`**. **Never** apply **`not-ready`** without that explanatory comment. Do not start implementation. (That comment is **machine handoff and feedback**, not something the triage agent re-reads as user input on the next run—the next run still trusts **`title` + `body` + attachments**.) +3. **Reproducibility** — When feasible, attempt to **reproduce** the problem inside the **triage sandbox** (see Sandboxing), using **only** what appears in the **`title`**, **`body`**, and attachments. **Skip** if the issue was already handled as a **duplicate** (closed). If information is **insufficient** to attempt reproduction meaningfully, apply **`not-ready`** only after posting a **triage-output comment on the issue** explaining what is missing or ambiguous for repro (do not apply **`not-reproducible`**). If information is **sufficient** but the bug **cannot be reproduced** after a good-faith attempt, post a **structured triage-output comment on the issue** first (or in the **same atomic update** as the label) that documents **what was tried** (steps, commands, branch/commit or version context, sandbox constraints) and **how it failed** to reproduce the issue as described (e.g. observed behavior vs reported behavior, logs or exit codes, “expected failure did not occur”). Then apply **`not-reproducible`**. **Never** apply **`not-reproducible`** without that comment. Flag for **human intervention**; **do not** enqueue further automated work (**no** PR agent, **no** implementation/review pipeline) until triage runs again. Do **not** use **`not-reproducible`** when the right outcome is simply “need more detail” (**`not-ready`**). 4. **Test case artifact** — When possible, produce a **test case** aligned with the repo’s **existing test framework** (same runner, conventions, paths). **Attachments** mean **only** what GitHub supports as **issue attachments** (native uploads on the issue via GitHub UI or **Issues API** attachment mechanisms the platform provides). Do **not** rely on ad hoc binary hosting, external blob stores, or non-GitHub “attachment” URLs as a substitute—if it cannot be expressed as **body** text, **fenced code in a triage-output comment**, or a **GitHub-native attachment**, the triage-output comment must still specify exact file paths and patch-shaped instructions for the PR agent. **Outcomes:** - **Duplicate path:** Apply **`duplicate`**, comment with **link to canonical issue**, **close** this issue; no implementation workflow. - **Ready path:** Apply **`ready-for-coding`**, summarize reproduction result in the triage-output comment and point to the proposed test artifact. (**`not-ready`** and **`not-reproducible`** were already cleared at triage **start** if they were set.) -- **Not ready path:** Apply **`not-ready`**, do not apply `ready-for-coding` or `not-reproducible`. -- **Not reproducible path:** Apply **`not-reproducible`**, post a triage-output comment explaining the failed repro attempt, do not apply `ready-for-coding`. **Stop** automated processing for this issue until a **new triage run** (automation or human-triggered) **starts** — at triage **start**, **`not-reproducible`** is **removed** together with **`not-ready`**, **`ready-for-coding`**, and later-phase labels, and triage executes the **full** Phase A sequence again from a clean slate. +- **Not ready path:** Apply **`not-ready`** only with a **triage-output comment on the issue** that explains **why** (per **Information sufficiency** and **Reproducibility** above); do not apply `ready-for-coding` or `not-reproducible`. +- **Not reproducible path:** Apply **`not-reproducible`** only with a **triage-output comment on the issue** that records **what was tried** and **how it failed** (per **Reproducibility** above); do not apply `ready-for-coding`. **Stop** automated processing for this issue until a **new triage run** (automation or human-triggered) **starts** — at triage **start**, **`not-reproducible`** is **removed** together with **`not-ready`**, **`ready-for-coding`**, and later-phase labels, and triage executes the **full** Phase A sequence again from a clean slate. **Triggers (triage agent):** @@ -193,10 +193,11 @@ It **does not** read the **issue comment thread** for intake decisions—no scan 1. **Collect evidence** — From GitHub (and internal dispatch logs if available): issue and PR timelines, **label transitions** (including **`duplicate`**, **`not-reproducible`**, **`requires-manual-review`**, **`not-ready`** ↔ **`ready-for-coding`**, **`ready-for-review` ↔ `ready-for-coding`**, and triage re-runs), **issue `body` / `title` edit** events when available, comment timelines with **stable permalinks**, required check runs and final conclusions, merge commit SHA, base/head SHAs at merge (including **head SHA per review round** when useful), and **correlation identifiers** (e.g. trace IDs from the observability building block) when the implementation emits them. Attribute comments to **agent vs human** when the platform provides that signal (e.g. GitHub App actor). 2. **Structure by workflow phase** — Emit sections that mirror **Phase A–C** (triage, implementation, review), each listing **what ran**, **outcome**, and **pointers** (e.g. permalink to the final check suite). Include explicit **handoff points** (labels applied/removed, PR opened, first and last **ready-for-review** / **ready-for-merge** transitions). -3. **Enumerate every triage “not ready” or “not reproducible” iteration** — The trace **must** document **each** period or pass where the issue was **not workable** yet or was **handed off for human intervention** after a failed repro: every application of **`not-ready`**, every application of **`not-reproducible`** (with summary of what triage attempted), every **triage re-run** after a **`body` or `title` edit** (including reruns that **cleared** **`not-reproducible`** at triage start), and every transition back toward **`ready-for-coding`** when triage eventually passed. **Do not omit** “failed triage” history because a PR never existed yet—those iterations are often where intent was clarified. If triage instead applied **`duplicate`**, record that pass (label, **link to canonical issue** in the triage comment, **issue closed**) even when **no PR** exists. For **each** triage pass (chronological): +3. **Enumerate every triage “not ready” or “not reproducible” iteration** — The trace **must** document **each** period or pass where the issue was **not workable** yet or was **handed off for human intervention** after a failed repro: every application of **`not-ready`**, every application of **`not-reproducible`** (with **permalink** to the triage-output comment that should state **what was tried** and **how it failed**), every **triage re-run** after a **`body` or `title` edit** (including reruns that **cleared** **`not-reproducible`** at triage start), and every transition back toward **`ready-for-coding`** when triage eventually passed. **Do not omit** “failed triage” history because a PR never existed yet—those iterations are often where intent was clarified. If triage instead applied **`duplicate`**, record that pass (label, **link to canonical issue** in the triage comment, **issue closed**) even when **no PR** exists. For **each** triage pass (chronological): - Note **bounding facts**: label changes, triage trigger (if known), and **issue `updated_at`** (or finer-grained **`body`/`title` change** metadata) when the API exposes it. - List **triage agent output comments** for that pass (missing-info checklist, ready summary, test proposal) with the same **short summary + permalink** pattern as review rounds. - - If the triage agent applied **`not-ready`** without a comment (misconfiguration), still record the pass and link the best artifact (label timeline only). + - If **`not-ready`** appears **without** a matching triage-output explanation comment (implementation bug or misconfiguration—**violates** this ADR), still record the pass and link the best artifact (label timeline only). + - If **`not-reproducible`** appears **without** a matching triage-output comment that documents **what was tried** and **how it failed** (**violates** this ADR), still record the pass and link the best artifact (label timeline only). 4. **Enumerate every implementation–review round-trip** — The trace **must** document **each time** the PR moved from **implementation** into **review** and **back** (the loop in Phase B/C: checks green → `ready-for-review` → coordinator requests changes → `ready-for-coding` → further commits → `ready-for-review` again, etc.). Treat **each** such cycle as a first-class part of the narrative—**do not collapse** multiple review rounds into one paragraph. For **every** cycle, in chronological order: - Identify the **review round** (e.g. “Review round 1”, “Review round 2”) and anchor it with **facts**: approximate time span, **head SHA** (or merge preview SHA) when available, and label transitions that bound the round. - Under that round, list **every agent comment that materially drove the workflow** (at minimum the **coordinator** consolidated comment; also **individual review-agent** comments when those are posted separately; **PR-agent** comments that summarize fixes, push results, or responses to review). For **each** such comment, provide: From 29d10c3699290d0ee0564ee664f12b9793c73e92 Mon Sep 17 00:00:00 2001 From: Greg Allen Date: Sat, 28 Mar 2026 09:41:02 -0400 Subject: [PATCH 05/10] Remove trailing whitespace. Signed-off-by: Greg Allen --- docs/ADRs/0002-initial-fullsend-design.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/ADRs/0002-initial-fullsend-design.md b/docs/ADRs/0002-initial-fullsend-design.md index be351569ec..2ce4d5e0e4 100644 --- a/docs/ADRs/0002-initial-fullsend-design.md +++ b/docs/ADRs/0002-initial-fullsend-design.md @@ -82,10 +82,10 @@ Repos may extend this set; names below are **semantic**, not prescriptive string ### Agent roles (logical; may map to one or many processes) -1. **Triage agent** — Duplicate detection, issue intake, reproducibility, test artifact proposal -2. **PR agent** — Branch, implement, test iteratively, open/update PR, fix checks -3. **Review agents** — N parallel reviewers + **one coordinator** (randomly designated per review round) to coalesce feedback -4. **Post-merge trace agent** — After a PR is **merged**, produces a **single audit-style comment** that reconstructs the **end-to-end flow** (issue → triage → implementation → checks → review → merge) so reviewers and auditors can see **what happened at each stage** without replaying the entire thread +1. **Triage agent** — Duplicate detection, issue intake, reproducibility, test artifact proposal +2. **PR agent** — Branch, implement, test iteratively, open/update PR, fix checks +3. **Review agents** — N parallel reviewers + **one coordinator** (randomly designated per review round) to coalesce feedback +4. **Post-merge trace agent** — After a PR is **merged**, produces a **single audit-style comment** that reconstructs the **end-to-end flow** (issue → triage → implementation → checks → review → merge) so reviewers and auditors can see **what happened at each stage** without replaying the entire thread Each role is a **building block**: separate prompts, policies, sandboxes, and CI jobs can evolve independently. From 40a2166a650d0be3d26f07472b35cd41288ad0cb Mon Sep 17 00:00:00 2001 From: Greg Allen Date: Sat, 28 Mar 2026 09:49:48 -0400 Subject: [PATCH 06/10] Handle removing ready-for-merge label when appropriate. Signed-off-by: Greg Allen --- docs/ADRs/0002-initial-fullsend-design.md | 12 ++++++------ docs/architecture.md | 3 ++- 2 files changed, 8 insertions(+), 7 deletions(-) diff --git a/docs/ADRs/0002-initial-fullsend-design.md b/docs/ADRs/0002-initial-fullsend-design.md index 2ce4d5e0e4..9564540cd7 100644 --- a/docs/ADRs/0002-initial-fullsend-design.md +++ b/docs/ADRs/0002-initial-fullsend-design.md @@ -73,7 +73,7 @@ Repos may extend this set; names below are **semantic**, not prescriptive string | `not-reproducible` | Triage: enough information was available to attempt reproduction, but the reported bug **could not be reproduced** in the triage sandbox; **human intervention** is required. **No further automated processing** (no PR agent, no implementation/review pipeline) while this label is present. Applying this label **must** be accompanied by a **triage-output comment on the issue** that records **what was tried** (commands, versions, environment assumptions) and **how it failed** to match the report (e.g. expected symptom absent, wrong error, tests green, timeouts)—**do not** set **`not-reproducible`** without that comment | | `ready-for-coding` | Triage passed; implementation may proceed | | `ready-for-review` | PR agent finished implementation + checks; awaiting multi-agent review | -| `ready-for-merge` | Review coordinator: **all** reviewers **unanimously** approved merge for this round (subject to branch protection / humans) | +| `ready-for-merge` | Review coordinator: **all** reviewers **unanimously** approved merge **for the PR head SHA at the end of that review round** (subject to branch protection / humans). The label **must not** remain set across a **new** review round or a **new** PR head without a **fresh** unanimous round—see Phase C (**When a review run starts**). Downstream automation and humans should treat **`ready-for-merge`** as **invalid** unless it reflects the **current** head after the **latest** completed review round | | `requires-manual-review` | Review coordinator: reviewers **did not** unanimously agree to merge (split vote, conflicting conclusions, or conflicting **security severities**); **humans** must decide next steps | **Mutual exclusion:** Implementation should enforce consistent label sets (e.g. removing `ready-for-coding` when setting `ready-for-review`). An issue marked **`duplicate`** must **not** carry **`ready-for-coding`**, **`ready-for-review`**, **`ready-for-merge`**, or **`requires-manual-review`**. An issue marked **`not-reproducible`** must **not** carry **`ready-for-coding`**, **`ready-for-review`**, **`ready-for-merge`**, or **`requires-manual-review`** — automation stops until humans resolve the situation or triage runs again (see Phase A). **`not-reproducible`** and **`not-ready`** should **not** be applied together (triage picks one outcome per pass). **`ready-for-merge`** and **`requires-manual-review`** must **not** be applied together on the same issue/PR. @@ -157,7 +157,7 @@ It **does not** read the **issue comment thread** for intake decisions—no scan 2. **`/review`** in a comment. 3. **PR synchronize** (push to the PR branch)—**re-review** per policy below. -**When a review run starts:** **remove** **`ready-for-review`**. Reviewers evaluate the current PR head; the coordinator applies outcomes using the algorithm below. +**When a review run starts** (initial review, **`/review`**, or **push-triggered re-review**): **remove** **`ready-for-review`** **and** **`ready-for-merge`**. A new round **supersedes** any prior merge verdict until the coordinator finishes this round—otherwise **`ready-for-merge`** could describe an **old** head after the author **pushed** new commits, which is **unsafe** for bots and humans. Reviewers evaluate the **current** PR head; the coordinator applies outcomes using the algorithm below. (**`requires-manual-review`** is **not** removed here by default—humans may still need to resolve an earlier split verdict unless **repo policy** clears it when enqueueing a new round.) **Review swarm:** @@ -175,13 +175,13 @@ It **does not** read the **issue comment thread** for intake decisions—no scan **Outcomes:** - **Changes requested** (coordinator maps to unanimous rework): Coordinator comment documents issues; remove **`ready-for-review`**, add **`ready-for-coding`** so the PR agent can resume; clear **`requires-manual-review`** if set. -- **Unanimous merge:** Add **`ready-for-merge`** (and remove **`ready-for-review`**). Actual merge may still require **human approval**, merge queue, or bot merge permission per [governance](../problems/governance.md) — this ADR only defines **agent-visible** labels. +- **Unanimous merge:** Add **`ready-for-merge`** (and remove **`ready-for-review`**). This label applies **only** to the **PR head SHA** the reviewers just evaluated in **this** round. Actual merge may still require **human approval**, merge queue, or bot merge permission per [governance](../problems/governance.md) — this ADR only defines **agent-visible** labels. - **Requires manual review:** Add **`requires-manual-review`** (and remove **`ready-for-review`**); do **not** add **`ready-for-merge`**. **Re-review policy:** -- **On every push** to the PR head while the change is **in the review stage** (implementation has handed off to review; automation tracks round state—the **`ready-for-review`** label may already have been **cleared** when the current round **started**): **automatically** enqueue a **new** multi-agent review round (same N, new coordinator selection). This keeps review aligned with the latest diff without waiting for humans. -- **On demand:** **`/review`** in a comment **also** enqueues a review round (re-run or extra pass). **Both** apply: pushes trigger re-review **and** maintainers can force a round via **`/review`** even without a new push. +- **On every push** to the PR head while the change is **in the review stage** (implementation has handed off to review; automation tracks round state—the **`ready-for-review`** label may already have been **cleared** when the current round **started**): **automatically** enqueue a **new** multi-agent review round (same N, new coordinator selection). **When that round starts**, **`ready-for-merge`** is cleared together with **`ready-for-review`** (see **When a review run starts**), so merge approval is **never** left pointing at a **superseded** head SHA. This keeps review aligned with the latest diff without waiting for humans. +- **On demand:** **`/review`** in a comment **also** enqueues a review round (re-run or extra pass). **Both** apply: pushes trigger re-review **and** maintainers can force a round via **`/review`** even without a new push. A **`/review`**-triggered round **also** clears **`ready-for-merge`** at **start**, so an extra review pass invalidates the previous unanimous verdict until the new round completes. ### Phase D — Post-merge flow trace @@ -263,7 +263,7 @@ Static/dynamic analysis hooks, policy packs, output schema. ([Architecture](../a ### 12. Coordinator merge algorithm -Random coordinator selection; **unanimous** approve-merge → **`ready-for-merge`**; **unanimous** rework → **`ready-for-coding`**; **split or conflicting severities** → **`requires-manual-review`**; consolidated comment schema. ([Architecture](../architecture.md#12-coordinator-merge-algorithm)) +Random coordinator selection; **unanimous** approve-merge → **`ready-for-merge`** (scoped to **current** PR head for that round); **review run start** clears **`ready-for-merge`** with **`ready-for-review`** so pushes do not leave stale merge approval; **unanimous** rework → **`ready-for-coding`**; **split or conflicting severities** → **`requires-manual-review`**; consolidated comment schema. ([Architecture](../architecture.md#12-coordinator-merge-algorithm)) ### 13. Observability diff --git a/docs/architecture.md b/docs/architecture.md index ffa22375d8..21b6ab84f0 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -208,9 +208,10 @@ ADR 0002: [Building block 11](ADRs/0002-initial-fullsend-design.md#11-review-age Aggregates review verdicts and applies labels: -- unanimous approve-merge → `ready-for-merge` +- unanimous approve-merge → `ready-for-merge` (for the **current** PR head at the end of that round only) - unanimous rework → `ready-for-coding` - split/conflicting (including conflicting security severities) → `requires-manual-review` +- each **review run start** (including push-triggered re-review) clears **`ready-for-merge`** together with **`ready-for-review`** so merge approval is never stale after new commits ADR 0002: [Building block 12](ADRs/0002-initial-fullsend-design.md#12-coordinator-merge-algorithm). ### 13. Observability From d9c85474cd8efe82d331df2edd2be828a48346d0 Mon Sep 17 00:00:00 2001 From: Greg Allen Date: Sat, 28 Mar 2026 10:06:02 -0400 Subject: [PATCH 07/10] Remove flow-trace to future-considerations. Signed-off-by: Greg Allen --- docs/ADRs/0002-initial-fullsend-design.md | 104 ++++++++-------------- docs/architecture.md | 14 +-- 2 files changed, 41 insertions(+), 77 deletions(-) diff --git a/docs/ADRs/0002-initial-fullsend-design.md b/docs/ADRs/0002-initial-fullsend-design.md index 9564540cd7..d7f5987394 100644 --- a/docs/ADRs/0002-initial-fullsend-design.md +++ b/docs/ADRs/0002-initial-fullsend-design.md @@ -58,7 +58,6 @@ We propose adopting the following **reference workflow** as the mental model for - `/code` — hand issue to PR agent (expects readiness or forces with human ack — policy per repo) - `/review` — enqueue review swarm for current PR head - `/reset-triage` — clear triage outcome labels (including **`not-ready`** and **`not-reproducible`**) and re-open triage (optional) -- `/flow-trace` — re-generate the **post-merge flow trace** comment (optional; restricted commenters — e.g. maintainers — for recovery or correction after a bad edit) Commands should be validated (e.g. authorized commenters, org members only) in implementation. @@ -85,7 +84,6 @@ Repos may extend this set; names below are **semantic**, not prescriptive string 1. **Triage agent** — Duplicate detection, issue intake, reproducibility, test artifact proposal 2. **PR agent** — Branch, implement, test iteratively, open/update PR, fix checks 3. **Review agents** — N parallel reviewers + **one coordinator** (randomly designated per review round) to coalesce feedback -4. **Post-merge trace agent** — After a PR is **merged**, produces a **single audit-style comment** that reconstructs the **end-to-end flow** (issue → triage → implementation → checks → review → merge) so reviewers and auditors can see **what happened at each stage** without replaying the entire thread Each role is a **building block**: separate prompts, policies, sandboxes, and CI jobs can evolve independently. @@ -183,33 +181,7 @@ It **does not** read the **issue comment thread** for intake decisions—no scan - **On every push** to the PR head while the change is **in the review stage** (implementation has handed off to review; automation tracks round state—the **`ready-for-review`** label may already have been **cleared** when the current round **started**): **automatically** enqueue a **new** multi-agent review round (same N, new coordinator selection). **When that round starts**, **`ready-for-merge`** is cleared together with **`ready-for-review`** (see **When a review run starts**), so merge approval is **never** left pointing at a **superseded** head SHA. This keeps review aligned with the latest diff without waiting for humans. - **On demand:** **`/review`** in a comment **also** enqueues a review round (re-run or extra pass). **Both** apply: pushes trigger re-review **and** maintainers can force a round via **`/review`** even without a new push. A **`/review`**-triggered round **also** clears **`ready-for-merge`** at **start**, so an extra review pass invalidates the previous unanimous verdict until the new round completes. -### Phase D — Post-merge flow trace - -**Entry:** The linked PR has **merged** to the target branch (merge event / `pull_request` closed as merged, or equivalent signal). Implementation may require an issue link on the PR for a well-formed trace. - -**Purpose:** Support **human review and audit** of autonomous runs. A long issue/PR thread, retried checks, and multiple agent comments are hard to reconstruct. The trace comment is the **canonical narrative** of the run, grounded in **observable platform facts** (timestamps, actors, labels, check conclusions, SHAs, comment links) rather than a free-form recap alone. - -**Post-merge trace agent responsibilities:** - -1. **Collect evidence** — From GitHub (and internal dispatch logs if available): issue and PR timelines, **label transitions** (including **`duplicate`**, **`not-reproducible`**, **`requires-manual-review`**, **`not-ready`** ↔ **`ready-for-coding`**, **`ready-for-review` ↔ `ready-for-coding`**, and triage re-runs), **issue `body` / `title` edit** events when available, comment timelines with **stable permalinks**, required check runs and final conclusions, merge commit SHA, base/head SHAs at merge (including **head SHA per review round** when useful), and **correlation identifiers** (e.g. trace IDs from the observability building block) when the implementation emits them. Attribute comments to **agent vs human** when the platform provides that signal (e.g. GitHub App actor). -2. **Structure by workflow phase** — Emit sections that mirror **Phase A–C** (triage, implementation, review), each listing **what ran**, **outcome**, and **pointers** (e.g. permalink to the final check suite). Include explicit **handoff points** (labels applied/removed, PR opened, first and last **ready-for-review** / **ready-for-merge** transitions). -3. **Enumerate every triage “not ready” or “not reproducible” iteration** — The trace **must** document **each** period or pass where the issue was **not workable** yet or was **handed off for human intervention** after a failed repro: every application of **`not-ready`**, every application of **`not-reproducible`** (with **permalink** to the triage-output comment that should state **what was tried** and **how it failed**), every **triage re-run** after a **`body` or `title` edit** (including reruns that **cleared** **`not-reproducible`** at triage start), and every transition back toward **`ready-for-coding`** when triage eventually passed. **Do not omit** “failed triage” history because a PR never existed yet—those iterations are often where intent was clarified. If triage instead applied **`duplicate`**, record that pass (label, **link to canonical issue** in the triage comment, **issue closed**) even when **no PR** exists. For **each** triage pass (chronological): - - Note **bounding facts**: label changes, triage trigger (if known), and **issue `updated_at`** (or finer-grained **`body`/`title` change** metadata) when the API exposes it. - - List **triage agent output comments** for that pass (missing-info checklist, ready summary, test proposal) with the same **short summary + permalink** pattern as review rounds. - - If **`not-ready`** appears **without** a matching triage-output explanation comment (implementation bug or misconfiguration—**violates** this ADR), still record the pass and link the best artifact (label timeline only). - - If **`not-reproducible`** appears **without** a matching triage-output comment that documents **what was tried** and **how it failed** (**violates** this ADR), still record the pass and link the best artifact (label timeline only). -4. **Enumerate every implementation–review round-trip** — The trace **must** document **each time** the PR moved from **implementation** into **review** and **back** (the loop in Phase B/C: checks green → `ready-for-review` → coordinator requests changes → `ready-for-coding` → further commits → `ready-for-review` again, etc.). Treat **each** such cycle as a first-class part of the narrative—**do not collapse** multiple review rounds into one paragraph. For **every** cycle, in chronological order: - - Identify the **review round** (e.g. “Review round 1”, “Review round 2”) and anchor it with **facts**: approximate time span, **head SHA** (or merge preview SHA) when available, and label transitions that bound the round. - - Under that round, list **every agent comment that materially drove the workflow** (at minimum the **coordinator** consolidated comment; also **individual review-agent** comments when those are posted separately; **PR-agent** comments that summarize fixes, push results, or responses to review). For **each** such comment, provide: - - A **short summary** (one or two sentences: what was found, decided, or changed). - - A **direct link** to that comment (issue or PR thread) so readers can open the **full** text, images, and code blocks on GitHub. - - If a round produced **no** standalone comment (e.g. only labels or check failures), still record the round and **link** to the best **primary artifact** (coordinator comment if any; otherwise the **check run** or **bot summary** for that push). -5. **Publish** — Post one **top-level comment** on the **issue** (and optionally a shorter pointer on the merged PR — policy per repo). Use a stable heading or marker (e.g. `## Fullsend flow trace`) so `/flow-trace` or automation can **update or replace** the same logical artifact idempotently. -6. **Safety** — **Redact** secrets and sensitive tokens; do not paste large log bodies into the comment—**link** to check runs or artifacts instead. Treat prior issue/PR bodies as **untrusted** when summarizing; prefer **API-sourced facts** over model paraphrase for state transitions. Summaries are **for navigation**; the **permalink** is the source of truth for detail. - -**Triggers:** Merge event (primary); optional `/flow-trace` for regeneration. - -**Note:** This agent runs **after** merge; it does not gate merge. It supports **transparency over trust** (see [vision](../vision.md)) and complements the review swarm by making the **full story** inspectable in one place. +**Merge:** After **`ready-for-merge`**, the PR is merged per [governance](../problems/governance.md), branch protection, and org policy. This ADR does **not** define further **automated** steps on the repo after merge; see [Future considerations](#future-considerations) for an optional **merge-time audit trail**. --- @@ -267,15 +239,7 @@ Random coordinator selection; **unanimous** approve-merge → **`ready-for-merge ### 13. Observability -Trace IDs spanning issue → PR → checks → review for incident response; **feeds the post-merge trace** when logs are queryable by correlation ID. ([Architecture](../architecture.md#13-observability)) - -### 14. Post-merge trace agent runtime - -Merge webhook handler, timeline/check-run fetchers, trace comment schema (markdown), idempotent create/update, redaction rules. ([Architecture](../architecture.md#14-post-merge-trace-agent-runtime)) - -### 15. Flow trace formatter - -Maps raw events into the Phase A–C narrative; **detects triage “not ready” iterations** and **implementation–review cycles** from label/timeline (and **`body`/`title`-edit** signals when available); resolves **comment permalinks** for triage, coordinator, review, and PR agents; emits **summary + link** rows per comment. May be **deterministic** (template + sorted events) or **LLM-assisted** with a **fact bundle** input and strict output schema (implementation choice); if LLM-assisted, summaries must still **not contradict** linked comments. ([Architecture](../architecture.md#15-flow-trace-formatter)) +Trace IDs spanning issue → PR → checks → review for incident response and correlation across automation runs. ([Architecture](../architecture.md#13-observability)) --- @@ -290,16 +254,15 @@ Maps raw events into the Phase A–C narrative; **detects triage “not ready” | **Triage / repro** | Triage agent | Issue-derived commands, dependency install, repro script; **read-only** clone or shallow fetch; network egress policy per threat model | | **PR / build-test** | PR agent | Full dev dependencies, test execution, compiler; **push** only to bot-owned branches; PR secrets (tokens) scoped to repo | | **Review** | Review agents | Optional dynamic checks; **no** merge rights; optional read-only or isolated run for fuzzing | -| **Post-merge trace** | Post-merge trace agent | **Read-mostly** access to GitHub APIs and optional internal observability stores; **post comment** (and edit own trace comment) only; **no** merge or branch write; no execution of repo code unless explicitly required for forensics (default: none) | | **GitHub Actions / hosted runner** | Checks | Org-controlled workflows; OIDC where possible | -**Data flow:** Agents receive **minimal** tokens (fine-scoped GitHub App). **Secrets** never appear in issue **`body`**, PR **`body`**, or **comments**. **Prompt injection** from those surfaces is assumed — see [security threat model](../problems/security-threat-model.md): triage and review prompts should treat **`body`** text and **comments** as **untrusted**, with tool allowlists and output validation. The post-merge trace agent should **anchor** the trace in **API-derived events** so an attacker cannot rewrite history via issue **`body`** alone; any narrative layer must not contradict those facts. +**Data flow:** Agents receive **minimal** tokens (fine-scoped GitHub App). **Secrets** never appear in issue **`body`**, PR **`body`**, or **comments**. **Prompt injection** from those surfaces is assumed — see [security threat model](../problems/security-threat-model.md): triage and review prompts should treat **`body`** text and **comments** as **untrusted**, with tool allowlists and output validation. --- ## Diagrams -The first figure is the **happy-path lifecycle** with **explicit triggers** (labels, slash commands, merge). The second is a **layered platform view**: what lives in GitHub vs dispatch vs agents vs sandboxes. +The first figure is the **happy-path lifecycle** with **explicit triggers** (labels, slash commands, merge). The second is a **layered platform view**: what lives in GitHub vs dispatch vs agents vs sandboxes for **Phases A–C** only. ### End-to-end flow (labels, slash commands, merge) @@ -334,13 +297,6 @@ flowchart TB RFM[ready-for-merge] end - subgraph PH4["Phase D — Post-merge"] - M["Merged PR (merge event)"] - S4["Slash: /flow-trace"] - PT[Post-merge trace agent] - FC[Flow trace comment] - end - LB --> T S1 --> T T --> TR @@ -363,13 +319,10 @@ flowchart TB RFC2 --> P CHG -->|no| RFM - RFM --> M - M -->|merge webhook| PT - S4 -.->|optional regen| PT - PT --> FC + RFM --> DONE["Merge per governance; end of automated pipeline in this ADR"] ``` -**How to read it:** **`/triage`** and **`/code`** sit in the top **Triggers** strip with **labels**. **`/review`** and **`/flow-trace`** sit **inside** Phases C and D so the **arrows into** the review swarm and post-merge trace agent are short and obvious. **`M --> PT`** is the primary merge path; **`S4 --> PT`** is **regeneration** of the flow-trace comment after merge. +**How to read it:** **`/triage`** and **`/code`** sit in the top **Triggers** strip with **labels**. **`/review`** sits inside Phase C. **`ready-for-merge`** leads to **human- or policy-governed merge**; this ADR does not show further automation after merge (see [Future considerations](#future-considerations)). ### Sandbox stack (layered platform) @@ -396,7 +349,6 @@ flowchart TB TA[Triage agent] PA[PR agent] RA[Review + coordinator] - PT[Post-merge trace] end subgraph L4["Sandboxes (least privilege)"] @@ -404,7 +356,6 @@ flowchart TB SB1["Triage / repro"] SB2["PR build-test"] SB3[Review] - SB4["Trace · read-mostly"] end IPL --> WH @@ -413,18 +364,14 @@ flowchart TB SM --> TA SM --> PA SM --> RA - SM --> PT SP -->|"/review"| RA - SP -->|"/flow-trace"| PT TA --> SB1 PA --> SB2 RA --> SB3 - PT --> SB4 PA <--> IPL - PT --> IPL ``` -**How to read it:** **Comments** (including **`/triage`**, **`/code`**, **`/review`**, **`/flow-trace`**) feed **webhook ingest** together with **issues/PRs/labels/checks** and **merge / PR-closed** events. **`/review`** and **`/flow-trace`** also show as **explicit edges** from the **slash parser** to the **review** and **post-merge trace** runtimes (alongside the **label-guard** dispatch). The **PR agent** ↔ **checks** loop is the **bidirectional** edge on the issue/PR surface. +**How to read it:** **Comments** (including **`/triage`**, **`/code`**, **`/review`**) feed **webhook ingest** together with **issues/PRs/labels/checks** and **merge / PR-closed** events (merge events may still be logged for policy or observability). **`/review`** also shows as an **explicit edge** from the **slash parser** to the **review** runtime (alongside **label-guard** dispatch). The **PR agent** ↔ **checks** loop is the **bidirectional** edge on the issue/PR surface. --- @@ -435,7 +382,6 @@ flowchart TB - **Composable delivery:** Teams can implement dispatch, triage, PR, and review independently. - **Human operability:** Labels + slash commands give **observable** state and **recovery** without a single orchestrator brain. - **Alignment with Fullsend themes:** Sandboxes and check loops mirror **autonomy is earned** from [vision](../vision.md); coordination stays in repo mechanics rather than a coordinator agent. -- **Reviewable audit trail:** The **post-merge flow trace** gives a **single place** to reconstruct what each stage did, improving **post-merge review**, incident analysis, and onboarding without reading entire threads. ### Negative / risks @@ -443,20 +389,48 @@ flowchart TB - **Cost and latency:** Multi-agent review × N is expensive; needs quotas and backoff. - **False readiness:** Over-trusting reproduction in a sandbox unlike user environments — mitigated by documenting environment assumptions in triage comments. - **Governance:** `ready-for-merge` must not bypass **branch protection** or **CODEOWNERS** unless org policy explicitly allows bot merge. -- **Trace fidelity vs cost:** Large repos or noisy automation may produce huge timelines; the formatter must **summarize with links** and cap inline content to avoid unusable comments and API rate-limit pain. Many **code–review cycles** can make the trace long; prefer **compact summaries** while **retaining every cycle** and **every** agent-comment link. -- **Narrative drift:** If the trace uses an LLM, it could **misstate** history unless constrained to **verified facts**; deterministic or schema-locked output reduces that risk. ## Open questions - Exact **label naming** and **per-repo customization** (config file in repo vs org defaults). - **Merge authority:** When may a bot merge after `ready-for-merge`? (Overlaps [governance](../problems/governance.md) and [autonomy spectrum](../problems/autonomy-spectrum.md).) - **Interaction with** [intent representation](../problems/intent-representation.md) and [autonomy spectrum](../problems/autonomy-spectrum.md) for repos that should not auto-advance stages. -- **Flow trace placement:** Issue only, PR only, or both; how to handle **multiple PRs** per issue or **squash** vs **merge** commit naming in the narrative. -- **Flow trace implementation:** Fully **deterministic** formatter vs **LLM** with structured inputs; minimum **fact** fields required before posting. - **Comment graph:** How to reliably associate review sub-comments with a **round** when threading or edits differ by GitHub surface (issue vs PR conversation). - **Issue `body`/`title` history:** GitHub may not expose full revision history for **`body`** and **`title`** via API; tracing *what* changed between triage passes may be limited to **`updated_at`** (and webhook payloads) unless the org adds external logging. - **Duplicate detection:** Search scope (repo vs org), **confidence threshold**, human override when the bot marks **`duplicate`** incorrectly, and whether to require **linked** duplicate-of metadata (GitHub **linked issues**) in addition to labels. +## Future considerations + +This ADR’s **normative** workflow ends when the PR is ready to merge and merge is carried out under **governance** and branch protection. The following is **not** required for that pipeline; it is a plausible **follow-on** for orgs that want a **single, readable audit trail** after merge. + +### Merge-time audit trail + +**Motivation:** Long issue/PR threads, retried checks, and many agent comments make it hard to reconstruct **what happened at each stage**. A **merge-time audit trail** (for example one **canonical comment** on the issue, updated after merge) can give **post-merge review**, incident analysis, and onboarding a **navigation layer** grounded in **observable platform facts** (timestamps, actors, labels, check conclusions, SHAs, comment links) rather than a free-form recap alone. It supports **transparency over trust** (see [vision](../vision.md)) but **does not gate merge**. + +**Possible shape when adopted:** + +1. **Trigger** — Merge event / `pull_request` closed as merged (primary); optional slash command (e.g. **`/flow-trace`**) for regeneration or repair (restricted commenters — e.g. maintainers). + +2. **Evidence collection** — From GitHub (and internal dispatch logs if available): issue and PR timelines, **label transitions** (including **`duplicate`**, **`not-reproducible`**, **`requires-manual-review`**, **`not-ready`** ↔ **`ready-for-coding`**, **`ready-for-review` ↔ `ready-for-coding`**, and triage re-runs), **issue `body` / `title` edit** events when available, comment timelines with **stable permalinks**, required check runs and final conclusions, merge commit SHA, base/head SHAs at merge (including **head SHA per review round** when useful), and **correlation identifiers** (e.g. trace IDs from the observability building block) when the implementation emits them. Attribute comments to **agent vs human** when the platform provides that signal (e.g. GitHub App actor). + +3. **Narrative structure** — Sections that mirror **triage, implementation, and review** (the stages this ADR defines), each listing **what ran**, **outcome**, and **pointers** (e.g. permalink to the final check suite). Explicit **handoff points** (labels applied/removed, PR opened, first and last **ready-for-review** / **ready-for-merge** transitions). + +4. **Triage history** — Document **each** period where the issue was **not workable** or **not reproducible**: every **`not-ready`** and **`not-reproducible`** (with **permalink** to triage-output comments that record **why** or **what was tried**), triage re-runs after **`body` or `title` edit**, and transitions toward **`ready-for-coding`**. Include **`duplicate`** outcomes (canonical link, issue closed) when no PR exists. For ADR violations (label without required comment), still record the pass and link the best artifact. + +5. **Implementation–review cycles** — Document **each** PR loop between implementation and review (checks green → **`ready-for-review`** → coordinator rework → **`ready-for-coding`** → commits → **`ready-for-review`** again, etc.). Per cycle: review round identity, head SHA when available, label bounds, and **summary + permalink** for every material agent comment (coordinator, reviewers, PR agent). If a round has no standalone comment, link the best primary artifact (check run, bot summary). + +6. **Publish** — One **top-level comment** on the **issue** (and optionally a shorter pointer on the merged PR — policy per repo). Stable heading or marker (e.g. `## Fullsend audit trail`) so automation or **`/flow-trace`** can **update or replace** the same logical artifact idempotently. + +7. **Safety** — **Redact** secrets; **link** to check runs instead of pasting large logs. Treat issue/PR bodies as **untrusted** when summarizing; **anchor** the trail in **API-derived events** so issue **`body`** edits cannot rewrite history. Summaries are for navigation; **permalinks** are the source of truth. + +**Likely building blocks** (if implemented): a **read-mostly** runtime subscribed to merge (and optional slash) events, plus a **formatter** that maps raw events into the narrative — **deterministic** (template + sorted events) or **LLM-assisted** with a strict fact bundle; if LLM-assisted, summaries must **not contradict** linked comments. + +**Sandbox (conceptual):** **Read-mostly** GitHub API access and optional internal observability stores; **post or edit** only the audit comment; **no** merge or branch write; no execution of repo code unless explicitly required for forensics (default: none). + +**Risks if adopted:** Noisy timelines and **API rate limits** — formatters should **summarize with links** and cap inline content. **Narrative drift** if an LLM misstates history unless output is **schema-locked** to verified facts. + +**Open design questions** (defer until adoption): Audit comment on **issue only**, **PR only**, or both; **multiple PRs** per issue; **squash** vs **merge** commit naming in the narrative; minimum **fact** fields before posting; deterministic vs LLM formatter trade-offs. + ## References - [Vision](../vision.md) diff --git a/docs/architecture.md b/docs/architecture.md index 21b6ab84f0..63400cba2b 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -156,7 +156,7 @@ ADR 0002: [Building block 1](ADRs/0002-initial-fullsend-design.md#1-webhook--dis ### 2. Slash-command parser + ACL -Parses `/triage`, `/code`, `/review`, `/flow-trace` and enforces who is allowed to invoke each command. +Parses `/triage`, `/code`, `/review`, and related commands and enforces who is allowed to invoke each. ADR 0002: [Building block 2](ADRs/0002-initial-fullsend-design.md#2-slash-command-parser--acl). ### 3. Label state machine guard @@ -216,15 +216,5 @@ ADR 0002: [Building block 12](ADRs/0002-initial-fullsend-design.md#12-coordinato ### 13. Observability -Traceability layer across issue, triage, implementation, review, checks, and merge; provides evidence used by post-merge flow tracing. +Traceability layer across issue, triage, implementation, review, checks, and merge for incident response and correlation across automation runs. ADR 0002: [Building block 13](ADRs/0002-initial-fullsend-design.md#13-observability). - -### 14. Post-merge trace agent runtime - -After merge, creates/updates a canonical flow-trace comment with links and short summaries for each workflow stage and iteration. -ADR 0002: [Building block 14](ADRs/0002-initial-fullsend-design.md#14-post-merge-trace-agent-runtime). - -### 15. Flow trace formatter - -Converts raw events into the phase-based trace narrative, including not-ready/duplicate triage iterations and implementation-review round-trips. -ADR 0002: [Building block 15](ADRs/0002-initial-fullsend-design.md#15-flow-trace-formatter). From d9e9931066ca2faa4d913c67fa7dee562ce4ba32 Mon Sep 17 00:00:00 2001 From: Greg Allen Date: Sat, 28 Mar 2026 10:14:08 -0400 Subject: [PATCH 08/10] Remove duplicate label when triage starts. Signed-off-by: Greg Allen --- docs/ADRs/0002-initial-fullsend-design.md | 19 +++++++++---------- docs/architecture.md | 4 ++-- 2 files changed, 11 insertions(+), 12 deletions(-) diff --git a/docs/ADRs/0002-initial-fullsend-design.md b/docs/ADRs/0002-initial-fullsend-design.md index d7f5987394..7a25a5f663 100644 --- a/docs/ADRs/0002-initial-fullsend-design.md +++ b/docs/ADRs/0002-initial-fullsend-design.md @@ -54,10 +54,9 @@ We propose adopting the following **reference workflow** as the mental model for **Slash commands (illustrative, configurable per repo):** -- `/triage` — run or re-run triage on the issue +- `/triage` — run or re-run triage on the issue **from scratch** (clears **`duplicate`** and other triage/ downstream labels at run start; **reopens** the issue if **`closed`**—see **When a triage run starts**) - `/code` — hand issue to PR agent (expects readiness or forces with human ack — policy per repo) - `/review` — enqueue review swarm for current PR head -- `/reset-triage` — clear triage outcome labels (including **`not-ready`** and **`not-reproducible`**) and re-open triage (optional) Commands should be validated (e.g. authorized commenters, org members only) in implementation. @@ -67,7 +66,7 @@ Repos may extend this set; names below are **semantic**, not prescriptive string | Label | Meaning | |-------|---------| -| `duplicate` | Triage: same work is already tracked elsewhere; this issue should be **closed** and discussion continues on the canonical issue | +| `duplicate` | Triage: same work is already tracked elsewhere; this issue should be **closed** and discussion continues on the canonical issue. A **new** triage run **removes** this label first (see **When a triage run starts**), so **`/triage`** or a fresh run after edits can **re-open** the question from scratch | | `not-ready` | Triage: insufficient information to proceed (detail missing before a reliable repro attempt). Applying this label **must** be accompanied by a **triage-output comment on the issue** that explains **why** (what is missing, unclear, or insufficient)—humans and the next triage pass need that context; **do not** set **`not-ready`** without posting that comment | | `not-reproducible` | Triage: enough information was available to attempt reproduction, but the reported bug **could not be reproduced** in the triage sandbox; **human intervention** is required. **No further automated processing** (no PR agent, no implementation/review pipeline) while this label is present. Applying this label **must** be accompanied by a **triage-output comment on the issue** that records **what was tried** (commands, versions, environment assumptions) and **how it failed** to match the report (e.g. expected symptom absent, wrong error, tests green, timeouts)—**do not** set **`not-reproducible`** without that comment | | `ready-for-coding` | Triage passed; implementation may proceed | @@ -101,21 +100,21 @@ Each role is a **building block**: separate prompts, policies, sandboxes, and CI It **does not** read the **issue comment thread** for intake decisions—no scanning prior human discussion, `@mentions`, or buried requirements in comments. That keeps triage **bounded**, **cheaper**, and **less exposed** to prompt-injection and noise in long threads. -**Contributor rule:** If something is missing or wrong for triage, **edit the issue `body`** (and **`title`** if needed) and add or replace **attachments** using **only GitHub’s native issue attachments** (uploads GitHub stores and exposes on the issue—see **Test case artifact** below). Do **not** expect the triage agent to discover updates hidden in comments. **Edits to `title` or `body`** trigger triage again automatically; you can also use **`/triage`**. +**Contributor rule:** If something is missing or wrong for triage, **edit the issue `body`** (and **`title`** if needed) and add or replace **attachments** using **only GitHub’s native issue attachments** (uploads GitHub stores and exposes on the issue—see **Test case artifact** below). Do **not** expect the triage agent to discover updates hidden in comments. **Edits to `title` or `body`** trigger triage again automatically; you can also use **`/triage`**, which always starts triage **from scratch** (including clearing **`duplicate`**—see below). To dispute a **duplicate** closure, use **`/triage`** (or edit **`title`/`body`** if the issue is still open and that trigger applies). **Triage agent responsibilities:** 1. **Duplicate detection** — Before investing in reproduction or coding, check whether the same (or substantially the same) problem is **already tracked** in another issue. Use **repo/org search**, **issue list filters**, **embedding or keyword similarity**, or other **policy-defined** signals (implementation choice). Base the match **only** on **`title`**, **`body`**, and **attachments** of the current issue compared to **indexed metadata** of candidate issues—not on reading arbitrary comment threads for candidates unless the search backend already summarized them. If triage concludes the new issue is a **duplicate** with **high enough confidence** (threshold per repo): apply the **`duplicate`** label; post a **triage-output comment** that **links the canonical issue** (GitHub URL or `#NNN` reference) and briefly states why it is considered the same; **close** the **new** issue (`state: closed` via API). Do **not** apply **`ready-for-coding`**, **`not-ready`**, or **`not-reproducible`** for an implementation track. If uncertain, **do not** mark duplicate—continue with normal triage. 2. **Information sufficiency** — From the **`title`**, **`body`**, and **attachments** only, decide whether the issue contains enough detail to act (expected behavior, actual behavior, version/context, minimal steps). If not, post a **structured triage-output comment on the issue** first (or in the **same atomic update** as the label) that lists **specific** missing items and explains **why** the issue cannot proceed yet—then apply **`not-ready`**. **Never** apply **`not-ready`** without that explanatory comment. Do not start implementation. (That comment is **machine handoff and feedback**, not something the triage agent re-reads as user input on the next run—the next run still trusts **`title` + `body` + attachments**.) -3. **Reproducibility** — When feasible, attempt to **reproduce** the problem inside the **triage sandbox** (see Sandboxing), using **only** what appears in the **`title`**, **`body`**, and attachments. **Skip** if the issue was already handled as a **duplicate** (closed). If information is **insufficient** to attempt reproduction meaningfully, apply **`not-ready`** only after posting a **triage-output comment on the issue** explaining what is missing or ambiguous for repro (do not apply **`not-reproducible`**). If information is **sufficient** but the bug **cannot be reproduced** after a good-faith attempt, post a **structured triage-output comment on the issue** first (or in the **same atomic update** as the label) that documents **what was tried** (steps, commands, branch/commit or version context, sandbox constraints) and **how it failed** to reproduce the issue as described (e.g. observed behavior vs reported behavior, logs or exit codes, “expected failure did not occur”). Then apply **`not-reproducible`**. **Never** apply **`not-reproducible`** without that comment. Flag for **human intervention**; **do not** enqueue further automated work (**no** PR agent, **no** implementation/review pipeline) until triage runs again. Do **not** use **`not-reproducible`** when the right outcome is simply “need more detail” (**`not-ready`**). +3. **Reproducibility** — When feasible, attempt to **reproduce** the problem inside the **triage sandbox** (see Sandboxing), using **only** what appears in the **`title`**, **`body`**, and attachments. **Skip** information sufficiency, reproducibility, and test artifact for **the rest of this pass** if **duplicate detection** (step 1) already applied **`duplicate`** and **closed** the issue. If information is **insufficient** to attempt reproduction meaningfully, apply **`not-ready`** only after posting a **triage-output comment on the issue** explaining what is missing or ambiguous for repro (do not apply **`not-reproducible`**). If information is **sufficient** but the bug **cannot be reproduced** after a good-faith attempt, post a **structured triage-output comment on the issue** first (or in the **same atomic update** as the label) that documents **what was tried** (steps, commands, branch/commit or version context, sandbox constraints) and **how it failed** to reproduce the issue as described (e.g. observed behavior vs reported behavior, logs or exit codes, “expected failure did not occur”). Then apply **`not-reproducible`**. **Never** apply **`not-reproducible`** without that comment. Flag for **human intervention**; **do not** enqueue further automated work (**no** PR agent, **no** implementation/review pipeline) until triage runs again. Do **not** use **`not-reproducible`** when the right outcome is simply “need more detail” (**`not-ready`**). 4. **Test case artifact** — When possible, produce a **test case** aligned with the repo’s **existing test framework** (same runner, conventions, paths). **Attachments** mean **only** what GitHub supports as **issue attachments** (native uploads on the issue via GitHub UI or **Issues API** attachment mechanisms the platform provides). Do **not** rely on ad hoc binary hosting, external blob stores, or non-GitHub “attachment” URLs as a substitute—if it cannot be expressed as **body** text, **fenced code in a triage-output comment**, or a **GitHub-native attachment**, the triage-output comment must still specify exact file paths and patch-shaped instructions for the PR agent. **Outcomes:** - **Duplicate path:** Apply **`duplicate`**, comment with **link to canonical issue**, **close** this issue; no implementation workflow. -- **Ready path:** Apply **`ready-for-coding`**, summarize reproduction result in the triage-output comment and point to the proposed test artifact. (**`not-ready`** and **`not-reproducible`** were already cleared at triage **start** if they were set.) +- **Ready path:** Apply **`ready-for-coding`**, summarize reproduction result in the triage-output comment and point to the proposed test artifact. (**`duplicate`**, **`not-ready`**, and **`not-reproducible`** were already cleared at triage **start** if they were set.) - **Not ready path:** Apply **`not-ready`** only with a **triage-output comment on the issue** that explains **why** (per **Information sufficiency** and **Reproducibility** above); do not apply `ready-for-coding` or `not-reproducible`. -- **Not reproducible path:** Apply **`not-reproducible`** only with a **triage-output comment on the issue** that records **what was tried** and **how it failed** (per **Reproducibility** above); do not apply `ready-for-coding`. **Stop** automated processing for this issue until a **new triage run** (automation or human-triggered) **starts** — at triage **start**, **`not-reproducible`** is **removed** together with **`not-ready`**, **`ready-for-coding`**, and later-phase labels, and triage executes the **full** Phase A sequence again from a clean slate. +- **Not reproducible path:** Apply **`not-reproducible`** only with a **triage-output comment on the issue** that records **what was tried** and **how it failed** (per **Reproducibility** above); do not apply `ready-for-coding`. **Stop** automated processing for this issue until a **new triage run** (automation or human-triggered) **starts** — at triage **start**, **`not-reproducible`** is **removed** together with **`duplicate`**, **`not-ready`**, **`ready-for-coding`**, and later-phase labels, and triage executes the **full** Phase A sequence again from a clean slate. **Triggers (triage agent):** @@ -123,7 +122,7 @@ It **does not** read the **issue comment thread** for intake decisions—no scan 2. **Issue `title` or `body` edited** (`issues` **`edited`** when `title` or `body` changed). 3. **`/triage`** in a comment. -**When a triage run starts** (before duplicate detection and the rest): **remove** **`not-ready`**, **`not-reproducible`**, **`ready-for-coding`**, and **all later-phase labels** (**`ready-for-review`**, **`ready-for-merge`**, **`requires-manual-review`**). That **resets the pipeline** on the issue so triage outcomes are authoritative for a new pass and a prior **`not-reproducible`** handoff does not block a full re-triage. (**`duplicate`** is a triage outcome: do **not** remove it here unless **repo policy** says a new triage run clears it—default is to **leave** **`duplicate`** unless humans removed it.) +**When a triage run starts** (before duplicate detection and the rest): **remove** **`duplicate`**, **`not-ready`**, **`not-reproducible`**, **`ready-for-coding`**, and **all later-phase labels** (**`ready-for-review`**, **`ready-for-merge`**, **`requires-manual-review`**). That **resets the pipeline** from scratch: **`/triage`** and every triage trigger begin with a clean slate relative to prior triage outcomes. If the issue **`state` is `closed`**, **reopen** it (`state: open`) as part of this step so duplicate detection, reproduction, and the rest of Phase A can run (needed after a mistaken **duplicate** closure; **repo policy** may restrict which triggers may reopen closed issues). ### Phase B — Implementation (PR agent) @@ -199,7 +198,7 @@ Map comments to intents; audit log. ([Architecture](../architecture.md#2-slash-c ### 3. Label state machine guard -Validates legal transitions; prevents contradictory labels (including **`duplicate`** and **`not-reproducible`** vs implementation labels). Coordinates **atomic** **on-start** label strips for triage, PR, and review runs so resets are race-safe. ([Architecture](../architecture.md#3-label-state-machine-guard)) +Validates legal transitions; prevents contradictory labels (including **`duplicate`** and **`not-reproducible`** vs implementation labels). Coordinates **atomic** **on-start** label strips for triage (**including `duplicate`**), PR, and review runs so resets are race-safe. ([Architecture](../architecture.md#3-label-state-machine-guard)) ### 4. Triage agent runtime @@ -397,7 +396,7 @@ flowchart TB - **Interaction with** [intent representation](../problems/intent-representation.md) and [autonomy spectrum](../problems/autonomy-spectrum.md) for repos that should not auto-advance stages. - **Comment graph:** How to reliably associate review sub-comments with a **round** when threading or edits differ by GitHub surface (issue vs PR conversation). - **Issue `body`/`title` history:** GitHub may not expose full revision history for **`body`** and **`title`** via API; tracing *what* changed between triage passes may be limited to **`updated_at`** (and webhook payloads) unless the org adds external logging. -- **Duplicate detection:** Search scope (repo vs org), **confidence threshold**, human override when the bot marks **`duplicate`** incorrectly, and whether to require **linked** duplicate-of metadata (GitHub **linked issues**) in addition to labels. +- **Duplicate detection:** Search scope (repo vs org), **confidence threshold**, whether **`/triage`** (or other triggers) should **reopen** **all** closed issues or only when **`duplicate`** was present, and whether to require **linked** duplicate-of metadata (GitHub **linked issues**) in addition to labels. ## Future considerations diff --git a/docs/architecture.md b/docs/architecture.md index 63400cba2b..e81875ee6f 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -161,12 +161,12 @@ ADR 0002: [Building block 2](ADRs/0002-initial-fullsend-design.md#2-slash-comman ### 3. Label state machine guard -Validates legal label transitions and enforces mutual exclusion and run-start reset semantics (triage/PR/review label stripping). +Validates legal label transitions and enforces mutual exclusion and run-start reset semantics (triage start clears **`duplicate`** and downstream labels; PR/review strips per ADR). ADR 0002: [Building block 3](ADRs/0002-initial-fullsend-design.md#3-label-state-machine-guard). ### 4. Triage agent runtime -Runs triage from issue `title`/`body` + GitHub-native attachments only; performs duplicate detection, readiness assessment, reproducibility, test artifact handoff, and can close duplicate issues. +Runs triage from issue `title`/`body` + GitHub-native attachments only; each run starts with **`duplicate`** and other reset labels cleared; duplicate detection, readiness, reproducibility, test handoff; can close as duplicate again if still a match. ADR 0002: [Building block 4](ADRs/0002-initial-fullsend-design.md#4-triage-agent-runtime). ### 5. Duplicate / similarity search From d864b2fc3505832e93dc23bb66050a77dfdee9c2 Mon Sep 17 00:00:00 2001 From: Greg Allen Date: Sat, 28 Mar 2026 12:44:37 -0400 Subject: [PATCH 09/10] Normalize agent and trigger names. Signed-off-by: Greg Allen --- docs/ADRs/0002-initial-fullsend-design.md | 164 +++++++++++----------- docs/architecture.md | 22 +-- 2 files changed, 93 insertions(+), 93 deletions(-) diff --git a/docs/ADRs/0002-initial-fullsend-design.md b/docs/ADRs/0002-initial-fullsend-design.md index 7a25a5f663..8db0ddceb8 100644 --- a/docs/ADRs/0002-initial-fullsend-design.md +++ b/docs/ADRs/0002-initial-fullsend-design.md @@ -55,7 +55,7 @@ We propose adopting the following **reference workflow** as the mental model for **Slash commands (illustrative, configurable per repo):** - `/triage` — run or re-run triage on the issue **from scratch** (clears **`duplicate`** and other triage/ downstream labels at run start; **reopens** the issue if **`closed`**—see **When a triage run starts**) -- `/code` — hand issue to PR agent (expects readiness or forces with human ack — policy per repo) +- `/implement` — hand off to the **Implement** stage (implementation agent; expects **`ready-for-implement`** or forces with human ack — policy per repo) - `/review` — enqueue review swarm for current PR head Commands should be validated (e.g. authorized commenters, org members only) in implementation. @@ -66,23 +66,23 @@ Repos may extend this set; names below are **semantic**, not prescriptive string | Label | Meaning | |-------|---------| -| `duplicate` | Triage: same work is already tracked elsewhere; this issue should be **closed** and discussion continues on the canonical issue. A **new** triage run **removes** this label first (see **When a triage run starts**), so **`/triage`** or a fresh run after edits can **re-open** the question from scratch | -| `not-ready` | Triage: insufficient information to proceed (detail missing before a reliable repro attempt). Applying this label **must** be accompanied by a **triage-output comment on the issue** that explains **why** (what is missing, unclear, or insufficient)—humans and the next triage pass need that context; **do not** set **`not-ready`** without posting that comment | -| `not-reproducible` | Triage: enough information was available to attempt reproduction, but the reported bug **could not be reproduced** in the triage sandbox; **human intervention** is required. **No further automated processing** (no PR agent, no implementation/review pipeline) while this label is present. Applying this label **must** be accompanied by a **triage-output comment on the issue** that records **what was tried** (commands, versions, environment assumptions) and **how it failed** to match the report (e.g. expected symptom absent, wrong error, tests green, timeouts)—**do not** set **`not-reproducible`** without that comment | -| `ready-for-coding` | Triage passed; implementation may proceed | -| `ready-for-review` | PR agent finished implementation + checks; awaiting multi-agent review | -| `ready-for-merge` | Review coordinator: **all** reviewers **unanimously** approved merge **for the PR head SHA at the end of that review round** (subject to branch protection / humans). The label **must not** remain set across a **new** review round or a **new** PR head without a **fresh** unanimous round—see Phase C (**When a review run starts**). Downstream automation and humans should treat **`ready-for-merge`** as **invalid** unless it reflects the **current** head after the **latest** completed review round | -| `requires-manual-review` | Review coordinator: reviewers **did not** unanimously agree to merge (split vote, conflicting conclusions, or conflicting **security severities**); **humans** must decide next steps | +| `duplicate` | **Triage**: same work is already tracked elsewhere; this issue should be **closed** and discussion continues on the canonical issue. A **new** triage run **removes** this label first (see **When a triage run starts**), so **`/triage`** or a fresh run after edits can **re-open** the question from scratch | +| `not-ready` | **Triage**: insufficient information to proceed (detail missing before a reliable repro attempt). Applying this label **must** be accompanied by a **triage-output comment on the issue** that explains **why** (what is missing, unclear, or insufficient)—humans and the next triage pass need that context; **do not** set **`not-ready`** without posting that comment | +| `not-reproducible` | **Triage**: enough information was available to attempt reproduction, but the reported bug **could not be reproduced** in the triage sandbox; **human intervention** is required. **No further automated processing** (no **Implement** / **Review** pipeline) while this label is present. Applying this label **must** be accompanied by a **triage-output comment on the issue** that records **what was tried** (commands, versions, environment assumptions) and **how it failed** to match the report (e.g. expected symptom absent, wrong error, tests green, timeouts)—**do not** set **`not-reproducible`** without that comment | +| `ready-for-implement` | **Triage** passed; **Implement** stage may proceed | +| `ready-for-review` | **Implement** finished (PR + checks); awaiting **Review** (multi-agent review) | +| `ready-for-merge` | **Review** coordinator: **all** reviewers **unanimously** approved merge **for the PR head SHA at the end of that review round** (subject to branch protection / humans). The label **must not** remain set across a **new** review round or a **new** PR head without a **fresh** unanimous round—see **Review** (**When a review run starts**). Downstream automation and humans should treat **`ready-for-merge`** as **invalid** unless it reflects the **current** head after the **latest** completed review round | +| `requires-manual-review` | **Review** coordinator: reviewers **did not** unanimously agree to merge (split vote, conflicting conclusions, or conflicting **security severities**); **humans** must decide next steps | -**Mutual exclusion:** Implementation should enforce consistent label sets (e.g. removing `ready-for-coding` when setting `ready-for-review`). An issue marked **`duplicate`** must **not** carry **`ready-for-coding`**, **`ready-for-review`**, **`ready-for-merge`**, or **`requires-manual-review`**. An issue marked **`not-reproducible`** must **not** carry **`ready-for-coding`**, **`ready-for-review`**, **`ready-for-merge`**, or **`requires-manual-review`** — automation stops until humans resolve the situation or triage runs again (see Phase A). **`not-reproducible`** and **`not-ready`** should **not** be applied together (triage picks one outcome per pass). **`ready-for-merge`** and **`requires-manual-review`** must **not** be applied together on the same issue/PR. +**Mutual exclusion:** **Tooling** should enforce consistent label sets (e.g. removing **`ready-for-implement`** when setting **`ready-for-review`**). An issue marked **`duplicate`** must **not** carry **`ready-for-implement`**, **`ready-for-review`**, **`ready-for-merge`**, or **`requires-manual-review`**. An issue marked **`not-reproducible`** must **not** carry **`ready-for-implement`**, **`ready-for-review`**, **`ready-for-merge`**, or **`requires-manual-review`** — automation stops until humans resolve the situation or triage runs again (see **Triage**). **`not-reproducible`** and **`not-ready`** should **not** be applied together (**Triage** picks one outcome per pass). **`ready-for-merge`** and **`requires-manual-review`** must **not** be applied together on the same issue/PR. -**Later-phase labels (for reset semantics):** Labels **`ready-for-review`**, **`ready-for-merge`**, and **`requires-manual-review`** are treated as **downstream of triage**; triage and PR-agent **starts** strip them when resetting pipeline state (see below). +**Downstream labels (for reset semantics):** **`ready-for-implement`**, **`ready-for-review`**, **`ready-for-merge`**, and **`requires-manual-review`** are **downstream of Triage**; **Triage** and **Implement** run starts strip them according to **When a triage run starts** and **When an implementation agent run starts** (see below). ### Agent roles (logical; may map to one or many processes) -1. **Triage agent** — Duplicate detection, issue intake, reproducibility, test artifact proposal -2. **PR agent** — Branch, implement, test iteratively, open/update PR, fix checks -3. **Review agents** — N parallel reviewers + **one coordinator** (randomly designated per review round) to coalesce feedback +1. **triage agent** — Duplicate detection, issue intake, reproducibility, test artifact proposal +2. **implementation agent** — Branch, implement, test iteratively, open/update PR, fix checks +3. **review agent** — N parallel reviewer instances + **one coordinator** (randomly designated per review round) to coalesce feedback Each role is a **building block**: separate prompts, policies, sandboxes, and CI jobs can evolve independently. @@ -90,9 +90,9 @@ Each role is a **building block**: separate prompts, policies, sandboxes, and CI ## Workflow narrative -### Phase A — Issue triage +### Triage -**Inputs (strict):** The triage agent considers **only**: +**Inputs (strict):** The **triage agent** considers **only**: - Issue **`title`** and **`body`** (GitHub REST/GraphQL fields of the same names), - **GitHub-native file/image attachments** on the issue (when the **Issues** APIs or UI expose them to the agent), @@ -100,55 +100,55 @@ Each role is a **building block**: separate prompts, policies, sandboxes, and CI It **does not** read the **issue comment thread** for intake decisions—no scanning prior human discussion, `@mentions`, or buried requirements in comments. That keeps triage **bounded**, **cheaper**, and **less exposed** to prompt-injection and noise in long threads. -**Contributor rule:** If something is missing or wrong for triage, **edit the issue `body`** (and **`title`** if needed) and add or replace **attachments** using **only GitHub’s native issue attachments** (uploads GitHub stores and exposes on the issue—see **Test case artifact** below). Do **not** expect the triage agent to discover updates hidden in comments. **Edits to `title` or `body`** trigger triage again automatically; you can also use **`/triage`**, which always starts triage **from scratch** (including clearing **`duplicate`**—see below). To dispute a **duplicate** closure, use **`/triage`** (or edit **`title`/`body`** if the issue is still open and that trigger applies). +**Contributor rule:** If something is missing or wrong for triage, **edit the issue `body`** (and **`title`** if needed) and add or replace **attachments** using **only GitHub’s native issue attachments** (uploads GitHub stores and exposes on the issue—see **Test case artifact** below). Do **not** expect the **triage agent** to discover updates hidden in comments. **Edits to `title` or `body`** trigger triage again automatically; you can also use **`/triage`**, which always starts triage **from scratch** (including clearing **`duplicate`**—see below). To dispute a **duplicate** closure, use **`/triage`** (or edit **`title`/`body`** if the issue is still open and that trigger applies). -**Triage agent responsibilities:** +**triage agent responsibilities:** -1. **Duplicate detection** — Before investing in reproduction or coding, check whether the same (or substantially the same) problem is **already tracked** in another issue. Use **repo/org search**, **issue list filters**, **embedding or keyword similarity**, or other **policy-defined** signals (implementation choice). Base the match **only** on **`title`**, **`body`**, and **attachments** of the current issue compared to **indexed metadata** of candidate issues—not on reading arbitrary comment threads for candidates unless the search backend already summarized them. If triage concludes the new issue is a **duplicate** with **high enough confidence** (threshold per repo): apply the **`duplicate`** label; post a **triage-output comment** that **links the canonical issue** (GitHub URL or `#NNN` reference) and briefly states why it is considered the same; **close** the **new** issue (`state: closed` via API). Do **not** apply **`ready-for-coding`**, **`not-ready`**, or **`not-reproducible`** for an implementation track. If uncertain, **do not** mark duplicate—continue with normal triage. -2. **Information sufficiency** — From the **`title`**, **`body`**, and **attachments** only, decide whether the issue contains enough detail to act (expected behavior, actual behavior, version/context, minimal steps). If not, post a **structured triage-output comment on the issue** first (or in the **same atomic update** as the label) that lists **specific** missing items and explains **why** the issue cannot proceed yet—then apply **`not-ready`**. **Never** apply **`not-ready`** without that explanatory comment. Do not start implementation. (That comment is **machine handoff and feedback**, not something the triage agent re-reads as user input on the next run—the next run still trusts **`title` + `body` + attachments**.) -3. **Reproducibility** — When feasible, attempt to **reproduce** the problem inside the **triage sandbox** (see Sandboxing), using **only** what appears in the **`title`**, **`body`**, and attachments. **Skip** information sufficiency, reproducibility, and test artifact for **the rest of this pass** if **duplicate detection** (step 1) already applied **`duplicate`** and **closed** the issue. If information is **insufficient** to attempt reproduction meaningfully, apply **`not-ready`** only after posting a **triage-output comment on the issue** explaining what is missing or ambiguous for repro (do not apply **`not-reproducible`**). If information is **sufficient** but the bug **cannot be reproduced** after a good-faith attempt, post a **structured triage-output comment on the issue** first (or in the **same atomic update** as the label) that documents **what was tried** (steps, commands, branch/commit or version context, sandbox constraints) and **how it failed** to reproduce the issue as described (e.g. observed behavior vs reported behavior, logs or exit codes, “expected failure did not occur”). Then apply **`not-reproducible`**. **Never** apply **`not-reproducible`** without that comment. Flag for **human intervention**; **do not** enqueue further automated work (**no** PR agent, **no** implementation/review pipeline) until triage runs again. Do **not** use **`not-reproducible`** when the right outcome is simply “need more detail” (**`not-ready`**). -4. **Test case artifact** — When possible, produce a **test case** aligned with the repo’s **existing test framework** (same runner, conventions, paths). **Attachments** mean **only** what GitHub supports as **issue attachments** (native uploads on the issue via GitHub UI or **Issues API** attachment mechanisms the platform provides). Do **not** rely on ad hoc binary hosting, external blob stores, or non-GitHub “attachment” URLs as a substitute—if it cannot be expressed as **body** text, **fenced code in a triage-output comment**, or a **GitHub-native attachment**, the triage-output comment must still specify exact file paths and patch-shaped instructions for the PR agent. +1. **Duplicate detection** — Before investing in reproduction or **Implement**, check whether the same (or substantially the same) problem is **already tracked** in another issue. Use **repo/org search**, **issue list filters**, **embedding or keyword similarity**, or other **policy-defined** signals (implementation choice). Base the match **only** on **`title`**, **`body`**, and **attachments** of the current issue compared to **indexed metadata** of candidate issues—not on reading arbitrary comment threads for candidates unless the search backend already summarized them. If triage concludes the new issue is a **duplicate** with **high enough confidence** (threshold per repo): apply the **`duplicate`** label; post a **triage-output comment** that **links the canonical issue** (GitHub URL or `#NNN` reference) and briefly states why it is considered the same; **close** the **new** issue (`state: closed` via API). Do **not** apply **`ready-for-implement`**, **`not-ready`**, or **`not-reproducible`** for an **Implement** track. If uncertain, **do not** mark duplicate—continue with normal triage. +2. **Information sufficiency** — From the **`title`**, **`body`**, and **attachments** only, decide whether the issue contains enough detail to act (expected behavior, actual behavior, version/context, minimal steps). If not, post a **structured triage-output comment on the issue** first (or in the **same atomic update** as the label) that lists **specific** missing items and explains **why** the issue cannot proceed yet—then apply **`not-ready`**. **Never** apply **`not-ready`** without that explanatory comment. Do not start **Implement**. (That comment is **machine handoff and feedback**, not something the **triage agent** re-reads as user input on the next run—the next run still trusts **`title` + `body` + attachments**.) +3. **Reproducibility** — When feasible, attempt to **reproduce** the problem inside the **triage sandbox** (see Sandboxing), using **only** what appears in the **`title`**, **`body`**, and attachments. **Skip** information sufficiency, reproducibility, and test artifact for **the rest of this pass** if **duplicate detection** (step 1) already applied **`duplicate`** and **closed** the issue. If information is **insufficient** to attempt reproduction meaningfully, apply **`not-ready`** only after posting a **triage-output comment on the issue** explaining what is missing or ambiguous for repro (do not apply **`not-reproducible`**). If information is **sufficient** but the bug **cannot be reproduced** after a good-faith attempt, post a **structured triage-output comment on the issue** first (or in the **same atomic update** as the label) that documents **what was tried** (steps, commands, branch/commit or version context, sandbox constraints) and **how it failed** to reproduce the issue as described (e.g. observed behavior vs reported behavior, logs or exit codes, “expected failure did not occur”). Then apply **`not-reproducible`**. **Never** apply **`not-reproducible`** without that comment. Flag for **human intervention**; **do not** enqueue further automated work (**no** **implementation agent**, **no** **Implement** / **Review** pipeline) until triage runs again. Do **not** use **`not-reproducible`** when the right outcome is simply “need more detail” (**`not-ready`**). +4. **Test case artifact** — When possible, produce a **test case** aligned with the repo’s **existing test framework** (same runner, conventions, paths). **Attachments** mean **only** what GitHub supports as **issue attachments** (native uploads on the issue via GitHub UI or **Issues API** attachment mechanisms the platform provides). Do **not** rely on ad hoc binary hosting, external blob stores, or non-GitHub “attachment” URLs as a substitute—if it cannot be expressed as **body** text, **fenced code in a triage-output comment**, or a **GitHub-native attachment**, the triage-output comment must still specify exact file paths and patch-shaped instructions for the **implementation agent**. **Outcomes:** -- **Duplicate path:** Apply **`duplicate`**, comment with **link to canonical issue**, **close** this issue; no implementation workflow. -- **Ready path:** Apply **`ready-for-coding`**, summarize reproduction result in the triage-output comment and point to the proposed test artifact. (**`duplicate`**, **`not-ready`**, and **`not-reproducible`** were already cleared at triage **start** if they were set.) -- **Not ready path:** Apply **`not-ready`** only with a **triage-output comment on the issue** that explains **why** (per **Information sufficiency** and **Reproducibility** above); do not apply `ready-for-coding` or `not-reproducible`. -- **Not reproducible path:** Apply **`not-reproducible`** only with a **triage-output comment on the issue** that records **what was tried** and **how it failed** (per **Reproducibility** above); do not apply `ready-for-coding`. **Stop** automated processing for this issue until a **new triage run** (automation or human-triggered) **starts** — at triage **start**, **`not-reproducible`** is **removed** together with **`duplicate`**, **`not-ready`**, **`ready-for-coding`**, and later-phase labels, and triage executes the **full** Phase A sequence again from a clean slate. +- **Duplicate path:** Apply **`duplicate`**, comment with **link to canonical issue**, **close** this issue; no **Implement** workflow. +- **Ready path:** Apply **`ready-for-implement`**, summarize reproduction result in the triage-output comment and point to the proposed test artifact. (**`duplicate`**, **`not-ready`**, and **`not-reproducible`** were already cleared at triage **start** if they were set.) +- **Not ready path:** Apply **`not-ready`** only with a **triage-output comment on the issue** that explains **why** (per **Information sufficiency** and **Reproducibility** above); do not apply `ready-for-implement` or `not-reproducible`. +- **Not reproducible path:** Apply **`not-reproducible`** only with a **triage-output comment on the issue** that records **what was tried** and **how it failed** (per **Reproducibility** above); do not apply `ready-for-implement`. **Stop** automated processing for this issue until a **new triage run** (automation or human-triggered) **starts** — at triage **start**, **`not-reproducible`** is **removed** together with **`duplicate`**, **`not-ready`**, **`ready-for-implement`**, and **downstream labels**, and triage executes the **full** **Triage** sequence again from a clean slate. -**Triggers (triage agent):** +**Triggers (triage agent run):** 1. **Issue created** (`issues` **`opened`**). 2. **Issue `title` or `body` edited** (`issues` **`edited`** when `title` or `body` changed). 3. **`/triage`** in a comment. -**When a triage run starts** (before duplicate detection and the rest): **remove** **`duplicate`**, **`not-ready`**, **`not-reproducible`**, **`ready-for-coding`**, and **all later-phase labels** (**`ready-for-review`**, **`ready-for-merge`**, **`requires-manual-review`**). That **resets the pipeline** from scratch: **`/triage`** and every triage trigger begin with a clean slate relative to prior triage outcomes. If the issue **`state` is `closed`**, **reopen** it (`state: open`) as part of this step so duplicate detection, reproduction, and the rest of Phase A can run (needed after a mistaken **duplicate** closure; **repo policy** may restrict which triggers may reopen closed issues). +**When a triage run starts** (before duplicate detection and the rest): **remove** **`duplicate`**, **`not-ready`**, **`not-reproducible`**, **`ready-for-implement`**, and **all downstream labels** (**`ready-for-review`**, **`ready-for-merge`**, **`requires-manual-review`**). That **resets the pipeline** from scratch: **`/triage`** and every triage trigger begin with a clean slate relative to prior triage outcomes. If the issue **`state` is `closed`**, **reopen** it (`state: open`) as part of this step so duplicate detection, reproduction, and the rest of **Triage** can run (needed after a mistaken **duplicate** closure; **repo policy** may restrict which triggers may reopen closed issues). -### Phase B — Implementation (PR agent) +### Implement (implementation agent) -**Entry:** The **`ready-for-coding`** label was **applied** to the issue (trigger event) **or** **`/code`** was invoked—**before** the run strips labels. Issue is **open** and **not** **`duplicate`**, **not** **`not-reproducible`**, and in no other conflicting state. +**Entry:** The **`ready-for-implement`** label was **applied** to the issue (trigger event) **or** **`/implement`** was invoked—**before** the run strips labels. Issue is **open** and **not** **`duplicate`**, **not** **`not-reproducible`**, and in no other conflicting state. -**Triggers (PR agent):** +**Triggers (Implement — **implementation agent**):** -1. **`ready-for-coding`** label **added** to the issue. -2. **`/code`** in a comment. +1. **`ready-for-implement`** label **added** to the issue. +2. **`/implement`** in a comment. -**When a PR-agent run starts:** **remove** **`ready-for-coding`** and **all later-phase labels** (**`ready-for-review`**, **`ready-for-merge`**, **`requires-manual-review`**). Implementation proceeds from the issue **`title` / `body` / attachments** and triage handoff comments—not from stale review/merge labels. +**When an implementation agent run starts:** **remove** **`ready-for-implement`** and **all downstream labels** (**`ready-for-review`**, **`ready-for-merge`**, **`requires-manual-review`**). The **Implement** stage proceeds from the issue **`title` / `body` / attachments** and triage handoff comments—not from stale **Review** / merge labels. -**PR agent responsibilities:** +**implementation agent responsibilities:** -1. **Read issue handoff** — Issue **`title`**, **`body`**, and **attachments** (the canonical human-maintained spec), plus **labels**, plus **triage agent output** (the structured triage-output comment(s) with reproduction summary and proposed test artifact). Do **not** depend on informal human comments for requirements unless repo policy explicitly expands scope. +1. **Read issue handoff** — Issue **`title`**, **`body`**, and **attachments** (the canonical human-maintained spec), plus **labels**, plus **triage agent** output (the structured triage-output comment(s) with reproduction summary and proposed test artifact). Do **not** depend on informal human comments for requirements unless repo policy explicitly expands scope. 2. **Branch and implement** — Produce a fix following repo conventions; respect CODEOWNERS implications (agent may still open PR but cannot satisfy human review on guarded paths without humans). 3. **Testing loop (iterative)** — Run the **existing test suite** in the **PR sandbox**. Incorporate **triage-provided tests** if present; if none, **author tests** consistent with the framework. Repeat **implement → test** until **local/CI-equivalent tests pass** in the sandbox used for iteration. 4. **Open or update PR** — Link issue; describe changes. -5. **GitHub checks loop** — After push, **required checks** run on GitHub. On failure, PR agent **fetches logs**, fixes, pushes; repeat until **all required checks pass** (or until policy caps retries — implementation detail). -6. **Handoff to review** — When checks are green: add **`ready-for-review`**. (**`ready-for-coding`** was already removed when this run **started**.) PR agent then **waits** until review outcome. +5. **GitHub checks loop** — After push, **required checks** run on GitHub. On failure, the **implementation agent** **fetches logs**, fixes, pushes; repeat until **all required checks pass** (or until policy caps retries — implementation detail). +6. **Handoff to Review** — When checks are green: add **`ready-for-review`**. (**`ready-for-implement`** was already removed when this run **started**.) The **implementation agent** then **waits** until **Review** outcome. -### Phase C — Multi-agent review +### Review **Entry:** The **`ready-for-review`** label was **applied** (or **`/review`** or **PR synchronize** per re-review policy)—**before** the run strips **`ready-for-review`**. -**Triggers (review swarm + coordinator):** +**Triggers (Review — **review agent** + coordinator):** 1. **`ready-for-review`** label **added** to the issue (or linked PR—policy per repo). 2. **`/review`** in a comment. @@ -158,7 +158,7 @@ It **does not** read the **issue comment thread** for intake decisions—no scan **Review swarm:** -- **Configurable count N** of **independent review agents** run in parallel (separate invocations, separate context windows where applicable). +- **review agent** — **Configurable count N** of **independent** invocations run in parallel (separate invocations, separate context windows where applicable). - **Coordinator selection:** One reviewer is **randomly chosen** as **coordinator** for this round (deterministic seed optional for auditability). - **Coordinator duties:** Collect reviewer outputs; produce **one consolidated GitHub comment** (findings, severity, requested changes); apply the **coordinator algorithm** below; update labels per rules below. @@ -166,21 +166,21 @@ It **does not** read the **issue comment thread** for intake decisions—no scan - Each reviewer outputs a structured verdict (e.g. **approve merge**, **request changes**, **comment-only**), including **security severity** when relevant. - **Unanimous approve-merge:** **All** counted reviewers **approve merge** with **no** outstanding **request changes** and **no** **conflicting security severities** on whether the PR is safe to merge. Apply **`ready-for-merge`**, remove **`ready-for-review`** and **`requires-manual-review`** if present. -- **Unanimous request-changes:** **All** agree the PR needs revision (no one approves merge yet). Apply **`ready-for-coding`**, remove **`ready-for-review`** — same as **Changes requested** below (not **`requires-manual-review`**). +- **Unanimous request-changes:** **All** agree the PR needs revision (no one approves merge yet). Apply **`ready-for-implement`**, remove **`ready-for-review`** — same as **Changes requested** below (not **`requires-manual-review`**). Returns work to **Implement**. - **Not unanimous** (split votes, some approve and some reject, or **conflicting security severities** that prevent a single merge judgment): Apply **`requires-manual-review`**, remove **`ready-for-review`**, do **not** apply **`ready-for-merge`**. The coordinator comment must summarize **who said what** so humans can decide. **Outcomes:** -- **Changes requested** (coordinator maps to unanimous rework): Coordinator comment documents issues; remove **`ready-for-review`**, add **`ready-for-coding`** so the PR agent can resume; clear **`requires-manual-review`** if set. +- **Changes requested** (coordinator maps to unanimous rework): Coordinator comment documents issues; remove **`ready-for-review`**, add **`ready-for-implement`** so the **implementation agent** can resume **Implement**; clear **`requires-manual-review`** if set. - **Unanimous merge:** Add **`ready-for-merge`** (and remove **`ready-for-review`**). This label applies **only** to the **PR head SHA** the reviewers just evaluated in **this** round. Actual merge may still require **human approval**, merge queue, or bot merge permission per [governance](../problems/governance.md) — this ADR only defines **agent-visible** labels. - **Requires manual review:** Add **`requires-manual-review`** (and remove **`ready-for-review`**); do **not** add **`ready-for-merge`**. **Re-review policy:** -- **On every push** to the PR head while the change is **in the review stage** (implementation has handed off to review; automation tracks round state—the **`ready-for-review`** label may already have been **cleared** when the current round **started**): **automatically** enqueue a **new** multi-agent review round (same N, new coordinator selection). **When that round starts**, **`ready-for-merge`** is cleared together with **`ready-for-review`** (see **When a review run starts**), so merge approval is **never** left pointing at a **superseded** head SHA. This keeps review aligned with the latest diff without waiting for humans. +- **On every push** to the PR head while the change is **in the Review stage** (**Implement** has handed off to **Review**; automation tracks round state—the **`ready-for-review`** label may already have been **cleared** when the current round **started**): **automatically** enqueue a **new** multi-agent review round (same N, new coordinator selection). **When that round starts**, **`ready-for-merge`** is cleared together with **`ready-for-review`** (see **When a review run starts**), so merge approval is **never** left pointing at a **superseded** head SHA. This keeps review aligned with the latest diff without waiting for humans. - **On demand:** **`/review`** in a comment **also** enqueues a review round (re-run or extra pass). **Both** apply: pushes trigger re-review **and** maintainers can force a round via **`/review`** even without a new push. A **`/review`**-triggered round **also** clears **`ready-for-merge`** at **start**, so an extra review pass invalidates the previous unanimous verdict until the new round completes. -**Merge:** After **`ready-for-merge`**, the PR is merged per [governance](../problems/governance.md), branch protection, and org policy. This ADR does **not** define further **automated** steps on the repo after merge; see [Future considerations](#future-considerations) for an optional **merge-time audit trail**. +**Merge:** After **`ready-for-merge`**, the PR is merged per [governance](../problems/governance.md), branch protection, and org policy. This ADR does **not** define further **automated** steps on the repo after merge; see [Future considerations](#future-considerations) for optional **[Audit](#audit)**. --- @@ -198,9 +198,9 @@ Map comments to intents; audit log. ([Architecture](../architecture.md#2-slash-c ### 3. Label state machine guard -Validates legal transitions; prevents contradictory labels (including **`duplicate`** and **`not-reproducible`** vs implementation labels). Coordinates **atomic** **on-start** label strips for triage (**including `duplicate`**), PR, and review runs so resets are race-safe. ([Architecture](../architecture.md#3-label-state-machine-guard)) +Validates legal transitions; prevents contradictory labels (including **`duplicate`** and **`not-reproducible`** vs **Implement**/**Review** labels). Coordinates **atomic** **on-start** label strips for **Triage** (**triage agent**; **including `duplicate`**), **Implement** (**implementation agent**), and **Review** (**review agent** + coordinator) runs so resets are race-safe. ([Architecture](../architecture.md#3-label-state-machine-guard)) -### 4. Triage agent runtime +### 4. triage agent runtime Prompt, tools, repo context packaging, output schema (triage-output **comment** + labels + optional **close issue**). Context fetchers **must** supply issue **`title`**, **`body`**, and **attachments** only for intake—not the full comment thread. ([Architecture](../architecture.md#4-triage-agent-runtime)) @@ -216,9 +216,9 @@ Hermetic-ish environment for repro commands (language-specific images). ([Archit Emits framework-native test snippets and attachment bundles. ([Architecture](../architecture.md#7-test-artifact-formatter)) -### 8. PR agent runtime +### 8. implementation agent runtime -Git operations (token-scoped), patch application, local test runner integration. ([Architecture](../architecture.md#8-pr-agent-runtime)) +Git operations (token-scoped), patch application, local test runner integration. ([Architecture](../architecture.md#8-implementation-agent-runtime)) ### 9. PR sandbox / CI mirror @@ -228,13 +228,13 @@ Same toolchain as contributors; secrets policy. ([Architecture](../architecture. Log fetch, classification, fix loop policies (max iterations, escalation). ([Architecture](../architecture.md#10-check-failure-triage)) -### 11. Review agent runtime +### 11. review agent runtime Static/dynamic analysis hooks, policy packs, output schema. ([Architecture](../architecture.md#11-review-agent-runtime)) ### 12. Coordinator merge algorithm -Random coordinator selection; **unanimous** approve-merge → **`ready-for-merge`** (scoped to **current** PR head for that round); **review run start** clears **`ready-for-merge`** with **`ready-for-review`** so pushes do not leave stale merge approval; **unanimous** rework → **`ready-for-coding`**; **split or conflicting severities** → **`requires-manual-review`**; consolidated comment schema. ([Architecture](../architecture.md#12-coordinator-merge-algorithm)) +Random coordinator selection; **unanimous** approve-merge → **`ready-for-merge`** (scoped to **current** PR head for that round); **review run start** clears **`ready-for-merge`** with **`ready-for-review`** so pushes do not leave stale merge approval; **unanimous** rework → **`ready-for-implement`**; **split or conflicting severities** → **`requires-manual-review`**; consolidated comment schema. ([Architecture](../architecture.md#12-coordinator-merge-algorithm)) ### 13. Observability @@ -250,18 +250,18 @@ Trace IDs spanning issue → PR → checks → review for incident response and | Sandbox | Used by | Contains | |--------|---------|----------| -| **Triage / repro** | Triage agent | Issue-derived commands, dependency install, repro script; **read-only** clone or shallow fetch; network egress policy per threat model | -| **PR / build-test** | PR agent | Full dev dependencies, test execution, compiler; **push** only to bot-owned branches; PR secrets (tokens) scoped to repo | -| **Review** | Review agents | Optional dynamic checks; **no** merge rights; optional read-only or isolated run for fuzzing | +| **Triage / repro** | **triage agent** | Issue-derived commands, dependency install, repro script; **read-only** clone or shallow fetch; network egress policy per threat model | +| **PR / build-test** | **implementation agent** | Full dev dependencies, test execution, compiler; **push** only to bot-owned branches; PR secrets (tokens) scoped to repo | +| **Review** | **review agent** (N parallel) | Optional dynamic checks; **no** merge rights; optional read-only or isolated run for fuzzing | | **GitHub Actions / hosted runner** | Checks | Org-controlled workflows; OIDC where possible | -**Data flow:** Agents receive **minimal** tokens (fine-scoped GitHub App). **Secrets** never appear in issue **`body`**, PR **`body`**, or **comments**. **Prompt injection** from those surfaces is assumed — see [security threat model](../problems/security-threat-model.md): triage and review prompts should treat **`body`** text and **comments** as **untrusted**, with tool allowlists and output validation. +**Data flow:** Agents receive **minimal** tokens (fine-scoped GitHub App). **Secrets** never appear in issue **`body`**, PR **`body`**, or **comments**. **Prompt injection** from those surfaces is assumed — see [security threat model](../problems/security-threat-model.md): **triage agent** and **review agent** prompts should treat **`body`** text and **comments** as **untrusted**, with tool allowlists and output validation. --- ## Diagrams -The first figure is the **happy-path lifecycle** with **explicit triggers** (labels, slash commands, merge). The second is a **layered platform view**: what lives in GitHub vs dispatch vs agents vs sandboxes for **Phases A–C** only. +The first figure is the **happy-path lifecycle** with **explicit triggers** (labels, slash commands, merge). The second is a **layered platform view**: what lives in GitHub vs dispatch vs agents vs sandboxes for **Triage**, **Implement**, and **Review** only. ### End-to-end flow (labels, slash commands, merge) @@ -271,28 +271,28 @@ flowchart TB direction LR LB[Label events] S1["/triage"] - S2["/code"] + S2["/implement"] end - subgraph PH1["Phase A — Issue triage"] - T[Triage agent] + subgraph PH1["Triage"] + T[triage agent] TR{Triage outcome} NR[not-ready] NREP[not-reproducible] - RFC1[ready-for-coding] + RFC1[ready-for-implement] end - subgraph PH2["Phase B — PR implementation"] - P[PR agent] + subgraph PH2["Implement"] + P[implementation\nagent] TC{Tests + checks green?} RFR[ready-for-review] end - subgraph PH3["Phase C — Multi-agent review"] + subgraph PH3["Review"] S3["Slash: /review"] - RW["Review swarm + coordinator"] + RW["review agent (N) +\ncoordinator"] CHG{Changes needed?} - RFC2[ready-for-coding] + RFC2[ready-for-implement] RFM[ready-for-merge] end @@ -321,7 +321,7 @@ flowchart TB RFM --> DONE["Merge per governance; end of automated pipeline in this ADR"] ``` -**How to read it:** **`/triage`** and **`/code`** sit in the top **Triggers** strip with **labels**. **`/review`** sits inside Phase C. **`ready-for-merge`** leads to **human- or policy-governed merge**; this ADR does not show further automation after merge (see [Future considerations](#future-considerations)). +**How to read it:** **`/triage`** and **`/implement`** sit in the top **Triggers** strip with **labels**. **`/review`** sits inside **Review**. **`ready-for-merge`** leads to **human- or policy-governed merge**; this ADR does not show further automation after merge (see [Future considerations](#future-considerations)). ### Sandbox stack (layered platform) @@ -345,9 +345,9 @@ flowchart TB subgraph L3["Agent runtimes"] direction LR - TA[Triage agent] - PA[PR agent] - RA[Review + coordinator] + TA[triage agent] + PA[implementation\nagent] + RA["review agent (N) +\ncoordinator"] end subgraph L4["Sandboxes (least privilege)"] @@ -370,7 +370,7 @@ flowchart TB PA <--> IPL ``` -**How to read it:** **Comments** (including **`/triage`**, **`/code`**, **`/review`**) feed **webhook ingest** together with **issues/PRs/labels/checks** and **merge / PR-closed** events (merge events may still be logged for policy or observability). **`/review`** also shows as an **explicit edge** from the **slash parser** to the **review** runtime (alongside **label-guard** dispatch). The **PR agent** ↔ **checks** loop is the **bidirectional** edge on the issue/PR surface. +**How to read it:** **Comments** (including **`/triage`**, **`/implement`**, **`/review`**) feed **webhook ingest** together with **issues/PRs/labels/checks** and **merge / PR-closed** events (merge events may still be logged for policy or observability). **`/review`** also shows as an **explicit edge** from the **slash parser** to the **review agent** runtime (alongside **label-guard** dispatch). The **implementation agent** ↔ **checks** loop is the **bidirectional** edge on the issue/PR surface. --- @@ -378,7 +378,7 @@ flowchart TB ### Positive -- **Composable delivery:** Teams can implement dispatch, triage, PR, and review independently. +- **Composable delivery:** Teams can implement dispatch, **Triage** (**triage agent**), **Implement** (**implementation agent**), and **Review** (**review agent** + coordinator) independently. - **Human operability:** Labels + slash commands give **observable** state and **recovery** without a single orchestrator brain. - **Alignment with Fullsend themes:** Sandboxes and check loops mirror **autonomy is earned** from [vision](../vision.md); coordination stays in repo mechanics rather than a coordinator agent. @@ -400,35 +400,35 @@ flowchart TB ## Future considerations -This ADR’s **normative** workflow ends when the PR is ready to merge and merge is carried out under **governance** and branch protection. The following is **not** required for that pipeline; it is a plausible **follow-on** for orgs that want a **single, readable audit trail** after merge. +This ADR’s **normative** workflow ends when the PR is ready to merge and merge is carried out under **governance** and branch protection. The following is **not** required for that pipeline; it is a plausible **follow-on** for orgs that want a single, readable **Audit** after merge. -### Merge-time audit trail +### Audit -**Motivation:** Long issue/PR threads, retried checks, and many agent comments make it hard to reconstruct **what happened at each stage**. A **merge-time audit trail** (for example one **canonical comment** on the issue, updated after merge) can give **post-merge review**, incident analysis, and onboarding a **navigation layer** grounded in **observable platform facts** (timestamps, actors, labels, check conclusions, SHAs, comment links) rather than a free-form recap alone. It supports **transparency over trust** (see [vision](../vision.md)) but **does not gate merge**. +**Motivation:** Long issue/PR threads, retried checks, and many agent comments make it hard to reconstruct **what happened at each stage**. **Audit** (for example one **canonical comment** on the issue, updated after merge) can give **post-merge review**, incident analysis, and onboarding a **navigation layer** grounded in **observable platform facts** (timestamps, actors, labels, check conclusions, SHAs, comment links) rather than a free-form recap alone. It supports **transparency over trust** (see [vision](../vision.md)) but **does not gate merge**. **Possible shape when adopted:** -1. **Trigger** — Merge event / `pull_request` closed as merged (primary); optional slash command (e.g. **`/flow-trace`**) for regeneration or repair (restricted commenters — e.g. maintainers). +1. **Trigger** — Merge event / `pull_request` closed as merged (primary); optional slash command **`/audit`** for regeneration or repair (restricted commenters — e.g. maintainers). -2. **Evidence collection** — From GitHub (and internal dispatch logs if available): issue and PR timelines, **label transitions** (including **`duplicate`**, **`not-reproducible`**, **`requires-manual-review`**, **`not-ready`** ↔ **`ready-for-coding`**, **`ready-for-review` ↔ `ready-for-coding`**, and triage re-runs), **issue `body` / `title` edit** events when available, comment timelines with **stable permalinks**, required check runs and final conclusions, merge commit SHA, base/head SHAs at merge (including **head SHA per review round** when useful), and **correlation identifiers** (e.g. trace IDs from the observability building block) when the implementation emits them. Attribute comments to **agent vs human** when the platform provides that signal (e.g. GitHub App actor). +2. **Evidence collection** — From GitHub (and internal dispatch logs if available): issue and PR timelines, **label transitions** (including **`duplicate`**, **`not-reproducible`**, **`requires-manual-review`**, **`not-ready`** ↔ **`ready-for-implement`**, **`ready-for-review` ↔ `ready-for-implement`**, and **Triage** re-runs), **issue `body` / `title` edit** events when available, comment timelines with **stable permalinks**, required check runs and final conclusions, merge commit SHA, base/head SHAs at merge (including **head SHA per review round** when useful), and **correlation identifiers** (e.g. trace IDs from the observability building block) when the deployment emits them. Attribute comments to **agent vs human** when the platform provides that signal (e.g. GitHub App actor). -3. **Narrative structure** — Sections that mirror **triage, implementation, and review** (the stages this ADR defines), each listing **what ran**, **outcome**, and **pointers** (e.g. permalink to the final check suite). Explicit **handoff points** (labels applied/removed, PR opened, first and last **ready-for-review** / **ready-for-merge** transitions). +3. **Narrative structure** — Sections that mirror **Triage**, **Implement**, and **Review** (the stages this ADR defines), each listing **what ran**, **outcome**, and **pointers** (e.g. permalink to the final check suite). Explicit **handoff points** (labels applied/removed, PR opened, first and last **ready-for-review** / **ready-for-merge** transitions). -4. **Triage history** — Document **each** period where the issue was **not workable** or **not reproducible**: every **`not-ready`** and **`not-reproducible`** (with **permalink** to triage-output comments that record **why** or **what was tried**), triage re-runs after **`body` or `title` edit**, and transitions toward **`ready-for-coding`**. Include **`duplicate`** outcomes (canonical link, issue closed) when no PR exists. For ADR violations (label without required comment), still record the pass and link the best artifact. +4. **Triage history** — Document **each** period where the issue was **not workable** or **not reproducible**: every **`not-ready`** and **`not-reproducible`** (with **permalink** to triage-output comments that record **why** or **what was tried**), **Triage** re-runs after **`body` or `title` edit**, and transitions toward **`ready-for-implement`**. Include **`duplicate`** outcomes (canonical link, issue closed) when no PR exists. For ADR violations (label without required comment), still record the pass and link the best artifact. -5. **Implementation–review cycles** — Document **each** PR loop between implementation and review (checks green → **`ready-for-review`** → coordinator rework → **`ready-for-coding`** → commits → **`ready-for-review`** again, etc.). Per cycle: review round identity, head SHA when available, label bounds, and **summary + permalink** for every material agent comment (coordinator, reviewers, PR agent). If a round has no standalone comment, link the best primary artifact (check run, bot summary). +5. **Implement–Review cycles** — Document **each** PR loop between **Implement** and **Review** (checks green → **`ready-for-review`** → coordinator rework → **`ready-for-implement`** → commits → **`ready-for-review`** again, etc.). Per cycle: review round identity, head SHA when available, label bounds, and **summary + permalink** for every material agent comment (coordinator, **review agent** invocations, **implementation agent**). If a round has no standalone comment, link the best primary artifact (check run, bot summary). -6. **Publish** — One **top-level comment** on the **issue** (and optionally a shorter pointer on the merged PR — policy per repo). Stable heading or marker (e.g. `## Fullsend audit trail`) so automation or **`/flow-trace`** can **update or replace** the same logical artifact idempotently. +6. **Publish** — One **top-level comment** on the **issue** (and optionally a shorter pointer on the merged PR — policy per repo). Stable heading or marker (e.g. `## Fullsend audit`) so automation or **`/audit`** can **update or replace** the same logical artifact idempotently. 7. **Safety** — **Redact** secrets; **link** to check runs instead of pasting large logs. Treat issue/PR bodies as **untrusted** when summarizing; **anchor** the trail in **API-derived events** so issue **`body`** edits cannot rewrite history. Summaries are for navigation; **permalinks** are the source of truth. -**Likely building blocks** (if implemented): a **read-mostly** runtime subscribed to merge (and optional slash) events, plus a **formatter** that maps raw events into the narrative — **deterministic** (template + sorted events) or **LLM-assisted** with a strict fact bundle; if LLM-assisted, summaries must **not contradict** linked comments. +**Likely building blocks** (if implemented): an **audit agent** — **read-mostly**, subscribed to merge (and optional **`/audit`**) events; **post or edit** the **Audit** comment only; plus a **formatter** (part of or separate from the **audit agent**) that maps raw events into the narrative — **deterministic** (template + sorted events) or **LLM-assisted** with a strict fact bundle; if LLM-assisted, summaries must **not contradict** linked comments. -**Sandbox (conceptual):** **Read-mostly** GitHub API access and optional internal observability stores; **post or edit** only the audit comment; **no** merge or branch write; no execution of repo code unless explicitly required for forensics (default: none). +**Sandbox (conceptual):** **Read-mostly** GitHub API access and optional internal observability stores; **audit agent** may **post or edit** only the **Audit** comment; **no** merge or branch write; no execution of repo code unless explicitly required for forensics (default: none). **Risks if adopted:** Noisy timelines and **API rate limits** — formatters should **summarize with links** and cap inline content. **Narrative drift** if an LLM misstates history unless output is **schema-locked** to verified facts. -**Open design questions** (defer until adoption): Audit comment on **issue only**, **PR only**, or both; **multiple PRs** per issue; **squash** vs **merge** commit naming in the narrative; minimum **fact** fields before posting; deterministic vs LLM formatter trade-offs. +**Open design questions** (defer until adoption): **Audit** comment on **issue only**, **PR only**, or both; **multiple PRs** per issue; **squash** vs **merge** commit naming in the narrative; minimum **fact** fields before posting; deterministic vs LLM formatter trade-offs. ## References diff --git a/docs/architecture.md b/docs/architecture.md index e81875ee6f..99cff6620d 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -156,7 +156,7 @@ ADR 0002: [Building block 1](ADRs/0002-initial-fullsend-design.md#1-webhook--dis ### 2. Slash-command parser + ACL -Parses `/triage`, `/code`, `/review`, and related commands and enforces who is allowed to invoke each. +Parses `/triage`, `/implement`, `/review`, and related commands and enforces who is allowed to invoke each. ADR 0002: [Building block 2](ADRs/0002-initial-fullsend-design.md#2-slash-command-parser--acl). ### 3. Label state machine guard @@ -164,7 +164,7 @@ ADR 0002: [Building block 2](ADRs/0002-initial-fullsend-design.md#2-slash-comman Validates legal label transitions and enforces mutual exclusion and run-start reset semantics (triage start clears **`duplicate`** and downstream labels; PR/review strips per ADR). ADR 0002: [Building block 3](ADRs/0002-initial-fullsend-design.md#3-label-state-machine-guard). -### 4. Triage agent runtime +### 4. triage agent runtime Runs triage from issue `title`/`body` + GitHub-native attachments only; each run starts with **`duplicate`** and other reset labels cleared; duplicate detection, readiness, reproducibility, test handoff; can close as duplicate again if still a match. ADR 0002: [Building block 4](ADRs/0002-initial-fullsend-design.md#4-triage-agent-runtime). @@ -184,24 +184,24 @@ ADR 0002: [Building block 6](ADRs/0002-initial-fullsend-design.md#6-repro-sandbo Formats triage test artifacts in repo-native conventions for PR handoff. ADR 0002: [Building block 7](ADRs/0002-initial-fullsend-design.md#7-test-artifact-formatter). -### 8. PR agent runtime +### 8. implementation agent runtime -Implements changes, runs local/CI-equivalent tests, handles check failures, and advances handoff to review (`ready-for-review`). -ADR 0002: [Building block 8](ADRs/0002-initial-fullsend-design.md#8-pr-agent-runtime). +Implements changes, runs local/CI-equivalent tests, handles check failures, and advances handoff to **Review** (`ready-for-review`). +ADR 0002: [Building block 8](ADRs/0002-initial-fullsend-design.md#8-implementation-agent-runtime). ### 9. PR sandbox / CI mirror -Execution environment for implementation and test loops, aligned to contributor/CI toolchains. +Execution environment for **Implement** and test loops, aligned to contributor/CI toolchains. ADR 0002: [Building block 9](ADRs/0002-initial-fullsend-design.md#9-pr-sandbox--ci-mirror). ### 10. Check failure triage -Fetches and classifies failing check logs to guide PR-agent remediation loops. +Fetches and classifies failing check logs to guide **implementation agent** remediation loops. ADR 0002: [Building block 10](ADRs/0002-initial-fullsend-design.md#10-check-failure-triage). -### 11. Review agent runtime +### 11. review agent runtime -Runs N parallel reviewers and produces structured review verdicts/comments. +Runs N parallel **review agent** invocations and produces structured review verdicts/comments. ADR 0002: [Building block 11](ADRs/0002-initial-fullsend-design.md#11-review-agent-runtime). ### 12. Coordinator merge algorithm @@ -209,12 +209,12 @@ ADR 0002: [Building block 11](ADRs/0002-initial-fullsend-design.md#11-review-age Aggregates review verdicts and applies labels: - unanimous approve-merge → `ready-for-merge` (for the **current** PR head at the end of that round only) -- unanimous rework → `ready-for-coding` +- unanimous rework → `ready-for-implement` - split/conflicting (including conflicting security severities) → `requires-manual-review` - each **review run start** (including push-triggered re-review) clears **`ready-for-merge`** together with **`ready-for-review`** so merge approval is never stale after new commits ADR 0002: [Building block 12](ADRs/0002-initial-fullsend-design.md#12-coordinator-merge-algorithm). ### 13. Observability -Traceability layer across issue, triage, implementation, review, checks, and merge for incident response and correlation across automation runs. +Traceability layer across issue, **Triage**, **Implement**, **Review**, checks, and merge for incident response and correlation across automation runs. ADR 0002: [Building block 13](ADRs/0002-initial-fullsend-design.md#13-observability). From 915f2b76a6497247b63a8757e65a028b84560db3 Mon Sep 17 00:00:00 2001 From: Greg Allen Date: Sat, 28 Mar 2026 12:52:43 -0400 Subject: [PATCH 10/10] Fix implement/implementation. Signed-off-by: Greg Allen --- docs/ADRs/0002-initial-fullsend-design.md | 68 +++++++++++------------ docs/architecture.md | 6 +- 2 files changed, 37 insertions(+), 37 deletions(-) diff --git a/docs/ADRs/0002-initial-fullsend-design.md b/docs/ADRs/0002-initial-fullsend-design.md index 8db0ddceb8..4b90f43a5a 100644 --- a/docs/ADRs/0002-initial-fullsend-design.md +++ b/docs/ADRs/0002-initial-fullsend-design.md @@ -55,7 +55,7 @@ We propose adopting the following **reference workflow** as the mental model for **Slash commands (illustrative, configurable per repo):** - `/triage` — run or re-run triage on the issue **from scratch** (clears **`duplicate`** and other triage/ downstream labels at run start; **reopens** the issue if **`closed`**—see **When a triage run starts**) -- `/implement` — hand off to the **Implement** stage (implementation agent; expects **`ready-for-implement`** or forces with human ack — policy per repo) +- `/implement` — hand off to the **Implementation** stage (implementation agent; expects **`ready-to-implement`** or forces with human ack — policy per repo) - `/review` — enqueue review swarm for current PR head Commands should be validated (e.g. authorized commenters, org members only) in implementation. @@ -68,15 +68,15 @@ Repos may extend this set; names below are **semantic**, not prescriptive string |-------|---------| | `duplicate` | **Triage**: same work is already tracked elsewhere; this issue should be **closed** and discussion continues on the canonical issue. A **new** triage run **removes** this label first (see **When a triage run starts**), so **`/triage`** or a fresh run after edits can **re-open** the question from scratch | | `not-ready` | **Triage**: insufficient information to proceed (detail missing before a reliable repro attempt). Applying this label **must** be accompanied by a **triage-output comment on the issue** that explains **why** (what is missing, unclear, or insufficient)—humans and the next triage pass need that context; **do not** set **`not-ready`** without posting that comment | -| `not-reproducible` | **Triage**: enough information was available to attempt reproduction, but the reported bug **could not be reproduced** in the triage sandbox; **human intervention** is required. **No further automated processing** (no **Implement** / **Review** pipeline) while this label is present. Applying this label **must** be accompanied by a **triage-output comment on the issue** that records **what was tried** (commands, versions, environment assumptions) and **how it failed** to match the report (e.g. expected symptom absent, wrong error, tests green, timeouts)—**do not** set **`not-reproducible`** without that comment | -| `ready-for-implement` | **Triage** passed; **Implement** stage may proceed | -| `ready-for-review` | **Implement** finished (PR + checks); awaiting **Review** (multi-agent review) | +| `not-reproducible` | **Triage**: enough information was available to attempt reproduction, but the reported bug **could not be reproduced** in the triage sandbox; **human intervention** is required. **No further automated processing** (no **Implementation** / **Review** pipeline) while this label is present. Applying this label **must** be accompanied by a **triage-output comment on the issue** that records **what was tried** (commands, versions, environment assumptions) and **how it failed** to match the report (e.g. expected symptom absent, wrong error, tests green, timeouts)—**do not** set **`not-reproducible`** without that comment | +| `ready-to-implement` | **Triage** passed; **Implementation** stage may proceed | +| `ready-for-review` | **Implementation** finished (PR + checks); awaiting **Review** (multi-agent review) | | `ready-for-merge` | **Review** coordinator: **all** reviewers **unanimously** approved merge **for the PR head SHA at the end of that review round** (subject to branch protection / humans). The label **must not** remain set across a **new** review round or a **new** PR head without a **fresh** unanimous round—see **Review** (**When a review run starts**). Downstream automation and humans should treat **`ready-for-merge`** as **invalid** unless it reflects the **current** head after the **latest** completed review round | | `requires-manual-review` | **Review** coordinator: reviewers **did not** unanimously agree to merge (split vote, conflicting conclusions, or conflicting **security severities**); **humans** must decide next steps | -**Mutual exclusion:** **Tooling** should enforce consistent label sets (e.g. removing **`ready-for-implement`** when setting **`ready-for-review`**). An issue marked **`duplicate`** must **not** carry **`ready-for-implement`**, **`ready-for-review`**, **`ready-for-merge`**, or **`requires-manual-review`**. An issue marked **`not-reproducible`** must **not** carry **`ready-for-implement`**, **`ready-for-review`**, **`ready-for-merge`**, or **`requires-manual-review`** — automation stops until humans resolve the situation or triage runs again (see **Triage**). **`not-reproducible`** and **`not-ready`** should **not** be applied together (**Triage** picks one outcome per pass). **`ready-for-merge`** and **`requires-manual-review`** must **not** be applied together on the same issue/PR. +**Mutual exclusion:** **Tooling** should enforce consistent label sets (e.g. removing **`ready-to-implement`** when setting **`ready-for-review`**). An issue marked **`duplicate`** must **not** carry **`ready-to-implement`**, **`ready-for-review`**, **`ready-for-merge`**, or **`requires-manual-review`**. An issue marked **`not-reproducible`** must **not** carry **`ready-to-implement`**, **`ready-for-review`**, **`ready-for-merge`**, or **`requires-manual-review`** — automation stops until humans resolve the situation or triage runs again (see **Triage**). **`not-reproducible`** and **`not-ready`** should **not** be applied together (**Triage** picks one outcome per pass). **`ready-for-merge`** and **`requires-manual-review`** must **not** be applied together on the same issue/PR. -**Downstream labels (for reset semantics):** **`ready-for-implement`**, **`ready-for-review`**, **`ready-for-merge`**, and **`requires-manual-review`** are **downstream of Triage**; **Triage** and **Implement** run starts strip them according to **When a triage run starts** and **When an implementation agent run starts** (see below). +**Downstream labels (for reset semantics):** **`ready-to-implement`**, **`ready-for-review`**, **`ready-for-merge`**, and **`requires-manual-review`** are **downstream of Triage**; **Triage** and **Implementation** run starts strip them according to **When a triage run starts** and **When an implementation agent run starts** (see below). ### Agent roles (logical; may map to one or many processes) @@ -104,17 +104,17 @@ It **does not** read the **issue comment thread** for intake decisions—no scan **triage agent responsibilities:** -1. **Duplicate detection** — Before investing in reproduction or **Implement**, check whether the same (or substantially the same) problem is **already tracked** in another issue. Use **repo/org search**, **issue list filters**, **embedding or keyword similarity**, or other **policy-defined** signals (implementation choice). Base the match **only** on **`title`**, **`body`**, and **attachments** of the current issue compared to **indexed metadata** of candidate issues—not on reading arbitrary comment threads for candidates unless the search backend already summarized them. If triage concludes the new issue is a **duplicate** with **high enough confidence** (threshold per repo): apply the **`duplicate`** label; post a **triage-output comment** that **links the canonical issue** (GitHub URL or `#NNN` reference) and briefly states why it is considered the same; **close** the **new** issue (`state: closed` via API). Do **not** apply **`ready-for-implement`**, **`not-ready`**, or **`not-reproducible`** for an **Implement** track. If uncertain, **do not** mark duplicate—continue with normal triage. -2. **Information sufficiency** — From the **`title`**, **`body`**, and **attachments** only, decide whether the issue contains enough detail to act (expected behavior, actual behavior, version/context, minimal steps). If not, post a **structured triage-output comment on the issue** first (or in the **same atomic update** as the label) that lists **specific** missing items and explains **why** the issue cannot proceed yet—then apply **`not-ready`**. **Never** apply **`not-ready`** without that explanatory comment. Do not start **Implement**. (That comment is **machine handoff and feedback**, not something the **triage agent** re-reads as user input on the next run—the next run still trusts **`title` + `body` + attachments**.) -3. **Reproducibility** — When feasible, attempt to **reproduce** the problem inside the **triage sandbox** (see Sandboxing), using **only** what appears in the **`title`**, **`body`**, and attachments. **Skip** information sufficiency, reproducibility, and test artifact for **the rest of this pass** if **duplicate detection** (step 1) already applied **`duplicate`** and **closed** the issue. If information is **insufficient** to attempt reproduction meaningfully, apply **`not-ready`** only after posting a **triage-output comment on the issue** explaining what is missing or ambiguous for repro (do not apply **`not-reproducible`**). If information is **sufficient** but the bug **cannot be reproduced** after a good-faith attempt, post a **structured triage-output comment on the issue** first (or in the **same atomic update** as the label) that documents **what was tried** (steps, commands, branch/commit or version context, sandbox constraints) and **how it failed** to reproduce the issue as described (e.g. observed behavior vs reported behavior, logs or exit codes, “expected failure did not occur”). Then apply **`not-reproducible`**. **Never** apply **`not-reproducible`** without that comment. Flag for **human intervention**; **do not** enqueue further automated work (**no** **implementation agent**, **no** **Implement** / **Review** pipeline) until triage runs again. Do **not** use **`not-reproducible`** when the right outcome is simply “need more detail” (**`not-ready`**). +1. **Duplicate detection** — Before investing in reproduction or **Implementation**, check whether the same (or substantially the same) problem is **already tracked** in another issue. Use **repo/org search**, **issue list filters**, **embedding or keyword similarity**, or other **policy-defined** signals (implementation choice). Base the match **only** on **`title`**, **`body`**, and **attachments** of the current issue compared to **indexed metadata** of candidate issues—not on reading arbitrary comment threads for candidates unless the search backend already summarized them. If triage concludes the new issue is a **duplicate** with **high enough confidence** (threshold per repo): apply the **`duplicate`** label; post a **triage-output comment** that **links the canonical issue** (GitHub URL or `#NNN` reference) and briefly states why it is considered the same; **close** the **new** issue (`state: closed` via API). Do **not** apply **`ready-to-implement`**, **`not-ready`**, or **`not-reproducible`** for an **Implementation** track. If uncertain, **do not** mark duplicate—continue with normal triage. +2. **Information sufficiency** — From the **`title`**, **`body`**, and **attachments** only, decide whether the issue contains enough detail to act (expected behavior, actual behavior, version/context, minimal steps). If not, post a **structured triage-output comment on the issue** first (or in the **same atomic update** as the label) that lists **specific** missing items and explains **why** the issue cannot proceed yet—then apply **`not-ready`**. **Never** apply **`not-ready`** without that explanatory comment. Do not start **Implementation**. (That comment is **machine handoff and feedback**, not something the **triage agent** re-reads as user input on the next run—the next run still trusts **`title` + `body` + attachments**.) +3. **Reproducibility** — When feasible, attempt to **reproduce** the problem inside the **triage sandbox** (see Sandboxing), using **only** what appears in the **`title`**, **`body`**, and attachments. **Skip** information sufficiency, reproducibility, and test artifact for **the rest of this pass** if **duplicate detection** (step 1) already applied **`duplicate`** and **closed** the issue. If information is **insufficient** to attempt reproduction meaningfully, apply **`not-ready`** only after posting a **triage-output comment on the issue** explaining what is missing or ambiguous for repro (do not apply **`not-reproducible`**). If information is **sufficient** but the bug **cannot be reproduced** after a good-faith attempt, post a **structured triage-output comment on the issue** first (or in the **same atomic update** as the label) that documents **what was tried** (steps, commands, branch/commit or version context, sandbox constraints) and **how it failed** to reproduce the issue as described (e.g. observed behavior vs reported behavior, logs or exit codes, “expected failure did not occur”). Then apply **`not-reproducible`**. **Never** apply **`not-reproducible`** without that comment. Flag for **human intervention**; **do not** enqueue further automated work (**no** **implementation agent**, **no** **Implementation** / **Review** pipeline) until triage runs again. Do **not** use **`not-reproducible`** when the right outcome is simply “need more detail” (**`not-ready`**). 4. **Test case artifact** — When possible, produce a **test case** aligned with the repo’s **existing test framework** (same runner, conventions, paths). **Attachments** mean **only** what GitHub supports as **issue attachments** (native uploads on the issue via GitHub UI or **Issues API** attachment mechanisms the platform provides). Do **not** rely on ad hoc binary hosting, external blob stores, or non-GitHub “attachment” URLs as a substitute—if it cannot be expressed as **body** text, **fenced code in a triage-output comment**, or a **GitHub-native attachment**, the triage-output comment must still specify exact file paths and patch-shaped instructions for the **implementation agent**. **Outcomes:** -- **Duplicate path:** Apply **`duplicate`**, comment with **link to canonical issue**, **close** this issue; no **Implement** workflow. -- **Ready path:** Apply **`ready-for-implement`**, summarize reproduction result in the triage-output comment and point to the proposed test artifact. (**`duplicate`**, **`not-ready`**, and **`not-reproducible`** were already cleared at triage **start** if they were set.) -- **Not ready path:** Apply **`not-ready`** only with a **triage-output comment on the issue** that explains **why** (per **Information sufficiency** and **Reproducibility** above); do not apply `ready-for-implement` or `not-reproducible`. -- **Not reproducible path:** Apply **`not-reproducible`** only with a **triage-output comment on the issue** that records **what was tried** and **how it failed** (per **Reproducibility** above); do not apply `ready-for-implement`. **Stop** automated processing for this issue until a **new triage run** (automation or human-triggered) **starts** — at triage **start**, **`not-reproducible`** is **removed** together with **`duplicate`**, **`not-ready`**, **`ready-for-implement`**, and **downstream labels**, and triage executes the **full** **Triage** sequence again from a clean slate. +- **Duplicate path:** Apply **`duplicate`**, comment with **link to canonical issue**, **close** this issue; no **Implementation** workflow. +- **Ready path:** Apply **`ready-to-implement`**, summarize reproduction result in the triage-output comment and point to the proposed test artifact. (**`duplicate`**, **`not-ready`**, and **`not-reproducible`** were already cleared at triage **start** if they were set.) +- **Not ready path:** Apply **`not-ready`** only with a **triage-output comment on the issue** that explains **why** (per **Information sufficiency** and **Reproducibility** above); do not apply `ready-to-implement` or `not-reproducible`. +- **Not reproducible path:** Apply **`not-reproducible`** only with a **triage-output comment on the issue** that records **what was tried** and **how it failed** (per **Reproducibility** above); do not apply `ready-to-implement`. **Stop** automated processing for this issue until a **new triage run** (automation or human-triggered) **starts** — at triage **start**, **`not-reproducible`** is **removed** together with **`duplicate`**, **`not-ready`**, **`ready-to-implement`**, and **downstream labels**, and triage executes the **full** **Triage** sequence again from a clean slate. **Triggers (triage agent run):** @@ -122,18 +122,18 @@ It **does not** read the **issue comment thread** for intake decisions—no scan 2. **Issue `title` or `body` edited** (`issues` **`edited`** when `title` or `body` changed). 3. **`/triage`** in a comment. -**When a triage run starts** (before duplicate detection and the rest): **remove** **`duplicate`**, **`not-ready`**, **`not-reproducible`**, **`ready-for-implement`**, and **all downstream labels** (**`ready-for-review`**, **`ready-for-merge`**, **`requires-manual-review`**). That **resets the pipeline** from scratch: **`/triage`** and every triage trigger begin with a clean slate relative to prior triage outcomes. If the issue **`state` is `closed`**, **reopen** it (`state: open`) as part of this step so duplicate detection, reproduction, and the rest of **Triage** can run (needed after a mistaken **duplicate** closure; **repo policy** may restrict which triggers may reopen closed issues). +**When a triage run starts** (before duplicate detection and the rest): **remove** **`duplicate`**, **`not-ready`**, **`not-reproducible`**, **`ready-to-implement`**, and **all downstream labels** (**`ready-for-review`**, **`ready-for-merge`**, **`requires-manual-review`**). That **resets the pipeline** from scratch: **`/triage`** and every triage trigger begin with a clean slate relative to prior triage outcomes. If the issue **`state` is `closed`**, **reopen** it (`state: open`) as part of this step so duplicate detection, reproduction, and the rest of **Triage** can run (needed after a mistaken **duplicate** closure; **repo policy** may restrict which triggers may reopen closed issues). -### Implement (implementation agent) +### Implementation -**Entry:** The **`ready-for-implement`** label was **applied** to the issue (trigger event) **or** **`/implement`** was invoked—**before** the run strips labels. Issue is **open** and **not** **`duplicate`**, **not** **`not-reproducible`**, and in no other conflicting state. +**Entry:** The **`ready-to-implement`** label was **applied** to the issue (trigger event) **or** **`/implement`** was invoked—**before** the run strips labels. Issue is **open** and **not** **`duplicate`**, **not** **`not-reproducible`**, and in no other conflicting state. -**Triggers (Implement — **implementation agent**):** +**Triggers (Implementation — **implementation agent**):** -1. **`ready-for-implement`** label **added** to the issue. +1. **`ready-to-implement`** label **added** to the issue. 2. **`/implement`** in a comment. -**When an implementation agent run starts:** **remove** **`ready-for-implement`** and **all downstream labels** (**`ready-for-review`**, **`ready-for-merge`**, **`requires-manual-review`**). The **Implement** stage proceeds from the issue **`title` / `body` / attachments** and triage handoff comments—not from stale **Review** / merge labels. +**When an implementation agent run starts:** **remove** **`ready-to-implement`** and **all downstream labels** (**`ready-for-review`**, **`ready-for-merge`**, **`requires-manual-review`**). The **Implementation** stage proceeds from the issue **`title` / `body` / attachments** and triage handoff comments—not from stale **Review** / merge labels. **implementation agent responsibilities:** @@ -142,7 +142,7 @@ It **does not** read the **issue comment thread** for intake decisions—no scan 3. **Testing loop (iterative)** — Run the **existing test suite** in the **PR sandbox**. Incorporate **triage-provided tests** if present; if none, **author tests** consistent with the framework. Repeat **implement → test** until **local/CI-equivalent tests pass** in the sandbox used for iteration. 4. **Open or update PR** — Link issue; describe changes. 5. **GitHub checks loop** — After push, **required checks** run on GitHub. On failure, the **implementation agent** **fetches logs**, fixes, pushes; repeat until **all required checks pass** (or until policy caps retries — implementation detail). -6. **Handoff to Review** — When checks are green: add **`ready-for-review`**. (**`ready-for-implement`** was already removed when this run **started**.) The **implementation agent** then **waits** until **Review** outcome. +6. **Handoff to Review** — When checks are green: add **`ready-for-review`**. (**`ready-to-implement`** was already removed when this run **started**.) The **implementation agent** then **waits** until **Review** outcome. ### Review @@ -166,18 +166,18 @@ It **does not** read the **issue comment thread** for intake decisions—no scan - Each reviewer outputs a structured verdict (e.g. **approve merge**, **request changes**, **comment-only**), including **security severity** when relevant. - **Unanimous approve-merge:** **All** counted reviewers **approve merge** with **no** outstanding **request changes** and **no** **conflicting security severities** on whether the PR is safe to merge. Apply **`ready-for-merge`**, remove **`ready-for-review`** and **`requires-manual-review`** if present. -- **Unanimous request-changes:** **All** agree the PR needs revision (no one approves merge yet). Apply **`ready-for-implement`**, remove **`ready-for-review`** — same as **Changes requested** below (not **`requires-manual-review`**). Returns work to **Implement**. +- **Unanimous request-changes:** **All** agree the PR needs revision (no one approves merge yet). Apply **`ready-to-implement`**, remove **`ready-for-review`** — same as **Changes requested** below (not **`requires-manual-review`**). Returns work to **Implementation**. - **Not unanimous** (split votes, some approve and some reject, or **conflicting security severities** that prevent a single merge judgment): Apply **`requires-manual-review`**, remove **`ready-for-review`**, do **not** apply **`ready-for-merge`**. The coordinator comment must summarize **who said what** so humans can decide. **Outcomes:** -- **Changes requested** (coordinator maps to unanimous rework): Coordinator comment documents issues; remove **`ready-for-review`**, add **`ready-for-implement`** so the **implementation agent** can resume **Implement**; clear **`requires-manual-review`** if set. +- **Changes requested** (coordinator maps to unanimous rework): Coordinator comment documents issues; remove **`ready-for-review`**, add **`ready-to-implement`** so the **implementation agent** can resume **Implementation**; clear **`requires-manual-review`** if set. - **Unanimous merge:** Add **`ready-for-merge`** (and remove **`ready-for-review`**). This label applies **only** to the **PR head SHA** the reviewers just evaluated in **this** round. Actual merge may still require **human approval**, merge queue, or bot merge permission per [governance](../problems/governance.md) — this ADR only defines **agent-visible** labels. - **Requires manual review:** Add **`requires-manual-review`** (and remove **`ready-for-review`**); do **not** add **`ready-for-merge`**. **Re-review policy:** -- **On every push** to the PR head while the change is **in the Review stage** (**Implement** has handed off to **Review**; automation tracks round state—the **`ready-for-review`** label may already have been **cleared** when the current round **started**): **automatically** enqueue a **new** multi-agent review round (same N, new coordinator selection). **When that round starts**, **`ready-for-merge`** is cleared together with **`ready-for-review`** (see **When a review run starts**), so merge approval is **never** left pointing at a **superseded** head SHA. This keeps review aligned with the latest diff without waiting for humans. +- **On every push** to the PR head while the change is **in the Review stage** (**Implementation** has handed off to **Review**; automation tracks round state—the **`ready-for-review`** label may already have been **cleared** when the current round **started**): **automatically** enqueue a **new** multi-agent review round (same N, new coordinator selection). **When that round starts**, **`ready-for-merge`** is cleared together with **`ready-for-review`** (see **When a review run starts**), so merge approval is **never** left pointing at a **superseded** head SHA. This keeps review aligned with the latest diff without waiting for humans. - **On demand:** **`/review`** in a comment **also** enqueues a review round (re-run or extra pass). **Both** apply: pushes trigger re-review **and** maintainers can force a round via **`/review`** even without a new push. A **`/review`**-triggered round **also** clears **`ready-for-merge`** at **start**, so an extra review pass invalidates the previous unanimous verdict until the new round completes. **Merge:** After **`ready-for-merge`**, the PR is merged per [governance](../problems/governance.md), branch protection, and org policy. This ADR does **not** define further **automated** steps on the repo after merge; see [Future considerations](#future-considerations) for optional **[Audit](#audit)**. @@ -198,7 +198,7 @@ Map comments to intents; audit log. ([Architecture](../architecture.md#2-slash-c ### 3. Label state machine guard -Validates legal transitions; prevents contradictory labels (including **`duplicate`** and **`not-reproducible`** vs **Implement**/**Review** labels). Coordinates **atomic** **on-start** label strips for **Triage** (**triage agent**; **including `duplicate`**), **Implement** (**implementation agent**), and **Review** (**review agent** + coordinator) runs so resets are race-safe. ([Architecture](../architecture.md#3-label-state-machine-guard)) +Validates legal transitions; prevents contradictory labels (including **`duplicate`** and **`not-reproducible`** vs **Implementation**/**Review** labels). Coordinates **atomic** **on-start** label strips for **Triage** (**triage agent**; **including `duplicate`**), **Implementation** (**implementation agent**), and **Review** (**review agent** + coordinator) runs so resets are race-safe. ([Architecture](../architecture.md#3-label-state-machine-guard)) ### 4. triage agent runtime @@ -234,7 +234,7 @@ Static/dynamic analysis hooks, policy packs, output schema. ([Architecture](../a ### 12. Coordinator merge algorithm -Random coordinator selection; **unanimous** approve-merge → **`ready-for-merge`** (scoped to **current** PR head for that round); **review run start** clears **`ready-for-merge`** with **`ready-for-review`** so pushes do not leave stale merge approval; **unanimous** rework → **`ready-for-implement`**; **split or conflicting severities** → **`requires-manual-review`**; consolidated comment schema. ([Architecture](../architecture.md#12-coordinator-merge-algorithm)) +Random coordinator selection; **unanimous** approve-merge → **`ready-for-merge`** (scoped to **current** PR head for that round); **review run start** clears **`ready-for-merge`** with **`ready-for-review`** so pushes do not leave stale merge approval; **unanimous** rework → **`ready-to-implement`**; **split or conflicting severities** → **`requires-manual-review`**; consolidated comment schema. ([Architecture](../architecture.md#12-coordinator-merge-algorithm)) ### 13. Observability @@ -261,7 +261,7 @@ Trace IDs spanning issue → PR → checks → review for incident response and ## Diagrams -The first figure is the **happy-path lifecycle** with **explicit triggers** (labels, slash commands, merge). The second is a **layered platform view**: what lives in GitHub vs dispatch vs agents vs sandboxes for **Triage**, **Implement**, and **Review** only. +The first figure is the **happy-path lifecycle** with **explicit triggers** (labels, slash commands, merge). The second is a **layered platform view**: what lives in GitHub vs dispatch vs agents vs sandboxes for **Triage**, **Implementation**, and **Review** only. ### End-to-end flow (labels, slash commands, merge) @@ -279,10 +279,10 @@ flowchart TB TR{Triage outcome} NR[not-ready] NREP[not-reproducible] - RFC1[ready-for-implement] + RFC1[ready-to-implement] end - subgraph PH2["Implement"] + subgraph PH2["Implementation"] P[implementation\nagent] TC{Tests + checks green?} RFR[ready-for-review] @@ -292,7 +292,7 @@ flowchart TB S3["Slash: /review"] RW["review agent (N) +\ncoordinator"] CHG{Changes needed?} - RFC2[ready-for-implement] + RFC2[ready-to-implement] RFM[ready-for-merge] end @@ -378,7 +378,7 @@ flowchart TB ### Positive -- **Composable delivery:** Teams can implement dispatch, **Triage** (**triage agent**), **Implement** (**implementation agent**), and **Review** (**review agent** + coordinator) independently. +- **Composable delivery:** Teams can implement dispatch, **Triage** (**triage agent**), **Implementation** (**implementation agent**), and **Review** (**review agent** + coordinator) independently. - **Human operability:** Labels + slash commands give **observable** state and **recovery** without a single orchestrator brain. - **Alignment with Fullsend themes:** Sandboxes and check loops mirror **autonomy is earned** from [vision](../vision.md); coordination stays in repo mechanics rather than a coordinator agent. @@ -410,13 +410,13 @@ This ADR’s **normative** workflow ends when the PR is ready to merge and merge 1. **Trigger** — Merge event / `pull_request` closed as merged (primary); optional slash command **`/audit`** for regeneration or repair (restricted commenters — e.g. maintainers). -2. **Evidence collection** — From GitHub (and internal dispatch logs if available): issue and PR timelines, **label transitions** (including **`duplicate`**, **`not-reproducible`**, **`requires-manual-review`**, **`not-ready`** ↔ **`ready-for-implement`**, **`ready-for-review` ↔ `ready-for-implement`**, and **Triage** re-runs), **issue `body` / `title` edit** events when available, comment timelines with **stable permalinks**, required check runs and final conclusions, merge commit SHA, base/head SHAs at merge (including **head SHA per review round** when useful), and **correlation identifiers** (e.g. trace IDs from the observability building block) when the deployment emits them. Attribute comments to **agent vs human** when the platform provides that signal (e.g. GitHub App actor). +2. **Evidence collection** — From GitHub (and internal dispatch logs if available): issue and PR timelines, **label transitions** (including **`duplicate`**, **`not-reproducible`**, **`requires-manual-review`**, **`not-ready`** ↔ **`ready-to-implement`**, **`ready-for-review` ↔ `ready-to-implement`**, and **Triage** re-runs), **issue `body` / `title` edit** events when available, comment timelines with **stable permalinks**, required check runs and final conclusions, merge commit SHA, base/head SHAs at merge (including **head SHA per review round** when useful), and **correlation identifiers** (e.g. trace IDs from the observability building block) when the deployment emits them. Attribute comments to **agent vs human** when the platform provides that signal (e.g. GitHub App actor). -3. **Narrative structure** — Sections that mirror **Triage**, **Implement**, and **Review** (the stages this ADR defines), each listing **what ran**, **outcome**, and **pointers** (e.g. permalink to the final check suite). Explicit **handoff points** (labels applied/removed, PR opened, first and last **ready-for-review** / **ready-for-merge** transitions). +3. **Narrative structure** — Sections that mirror **Triage**, **Implementation**, and **Review** (the stages this ADR defines), each listing **what ran**, **outcome**, and **pointers** (e.g. permalink to the final check suite). Explicit **handoff points** (labels applied/removed, PR opened, first and last **ready-for-review** / **ready-for-merge** transitions). -4. **Triage history** — Document **each** period where the issue was **not workable** or **not reproducible**: every **`not-ready`** and **`not-reproducible`** (with **permalink** to triage-output comments that record **why** or **what was tried**), **Triage** re-runs after **`body` or `title` edit**, and transitions toward **`ready-for-implement`**. Include **`duplicate`** outcomes (canonical link, issue closed) when no PR exists. For ADR violations (label without required comment), still record the pass and link the best artifact. +4. **Triage history** — Document **each** period where the issue was **not workable** or **not reproducible**: every **`not-ready`** and **`not-reproducible`** (with **permalink** to triage-output comments that record **why** or **what was tried**), **Triage** re-runs after **`body` or `title` edit**, and transitions toward **`ready-to-implement`**. Include **`duplicate`** outcomes (canonical link, issue closed) when no PR exists. For ADR violations (label without required comment), still record the pass and link the best artifact. -5. **Implement–Review cycles** — Document **each** PR loop between **Implement** and **Review** (checks green → **`ready-for-review`** → coordinator rework → **`ready-for-implement`** → commits → **`ready-for-review`** again, etc.). Per cycle: review round identity, head SHA when available, label bounds, and **summary + permalink** for every material agent comment (coordinator, **review agent** invocations, **implementation agent**). If a round has no standalone comment, link the best primary artifact (check run, bot summary). +5. **Implementation–Review cycles** — Document **each** PR loop between **Implementation** and **Review** (checks green → **`ready-for-review`** → coordinator rework → **`ready-to-implement`** → commits → **`ready-for-review`** again, etc.). Per cycle: review round identity, head SHA when available, label bounds, and **summary + permalink** for every material agent comment (coordinator, **review agent** invocations, **implementation agent**). If a round has no standalone comment, link the best primary artifact (check run, bot summary). 6. **Publish** — One **top-level comment** on the **issue** (and optionally a shorter pointer on the merged PR — policy per repo). Stable heading or marker (e.g. `## Fullsend audit`) so automation or **`/audit`** can **update or replace** the same logical artifact idempotently. diff --git a/docs/architecture.md b/docs/architecture.md index 99cff6620d..36db8d47fc 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -191,7 +191,7 @@ ADR 0002: [Building block 8](ADRs/0002-initial-fullsend-design.md#8-implementati ### 9. PR sandbox / CI mirror -Execution environment for **Implement** and test loops, aligned to contributor/CI toolchains. +Execution environment for **Implementation** and test loops, aligned to contributor/CI toolchains. ADR 0002: [Building block 9](ADRs/0002-initial-fullsend-design.md#9-pr-sandbox--ci-mirror). ### 10. Check failure triage @@ -209,12 +209,12 @@ ADR 0002: [Building block 11](ADRs/0002-initial-fullsend-design.md#11-review-age Aggregates review verdicts and applies labels: - unanimous approve-merge → `ready-for-merge` (for the **current** PR head at the end of that round only) -- unanimous rework → `ready-for-implement` +- unanimous rework → `ready-to-implement` - split/conflicting (including conflicting security severities) → `requires-manual-review` - each **review run start** (including push-triggered re-review) clears **`ready-for-merge`** together with **`ready-for-review`** so merge approval is never stale after new commits ADR 0002: [Building block 12](ADRs/0002-initial-fullsend-design.md#12-coordinator-merge-algorithm). ### 13. Observability -Traceability layer across issue, **Triage**, **Implement**, **Review**, checks, and merge for incident response and correlation across automation runs. +Traceability layer across issue, **Triage**, **Implementation**, **Review**, checks, and merge for incident response and correlation across automation runs. ADR 0002: [Building block 13](ADRs/0002-initial-fullsend-design.md#13-observability).