Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
32 changes: 20 additions & 12 deletions docs/loopwright/loop-harness.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,8 @@

How work flows through this repo when coding agents execute it. The quality
gate (`docs/loopwright/quality-gate.md`) is the enforcement half; this is the
execution half.
execution half. The opinions both halves serve are stated in
`docs/loopwright/principles.md`.

## Flow

Expand Down Expand Up @@ -38,10 +39,10 @@ Draft PR
│ gate green, draft → promote to ready (triggers Claude review)
│ review findings → fix or reply with reasons, never ignore
▼
Ready PR, gate green, reviews addressed → human merges
Ready PR, gate green, reviews addressed → merge
```

## Rules of the loop
## Mechanics

- **Base branch**: a task with no open `blockedBy` always branches from
`origin/main`. A task inside a feature-branch RFC branches from
Expand All @@ -55,15 +56,10 @@ Ready PR, gate green, reviews addressed → human merges
- **Draft until ready**: PRs open as drafts. The quality gate runs on drafts
(cheap, mechanical signal for the babysitting loop); the Claude review
workflow skips drafts and runs on `ready_for_review`.
- **The gate is the only source of truth for "done".** No agent may override
a red verdict, regenerate `.loopwright/baseline.json`, or take any of the
gated shortcuts listed in `CLAUDE.md`.
- **State lives in artifacts, not sessions**: the refined RFC and its comment
trail on the issue, the committed spec in `docs/specs/`, per-step commits,
and the PR conversation. Any session (or human) can pick up a half-done
task from these alone — except the grill phase itself, whose task spine and
drafts are session-scoped, so a crashed grill restarts.
- **Merging is always the human's decision.**
- **The grill phase is session-scoped.** `/grill-rfc` holds its task spine
and its sub-issue drafts in the session that runs it: the spine is a native
task list, the drafts are `draft-<slug>.md` files in a scratch directory,
and neither is committed. A crashed grill restarts.
- **Architecture is scaffolding, not a spec.** The architect phase's mermaid
lives in an RFC issue comment and never in the issue body, because
`planner.md` reads the body via `gh issue view` and comments are not
Expand All @@ -76,6 +72,18 @@ Ready PR, gate green, reviews addressed → human merges
it reports `no change` across three RFCs, delete it and rely on the ledger's
mandatory reasoned exclusion list alone.

## Opinions

The opinions the loop runs on are stated once, in
`docs/loopwright/principles.md`, and this file does not restate them. Three
of them bear directly on the mechanics above:

| Opinion | The question it settles |
|---|---|
| P1 | Where loop state lives |
| P2 | What counts as "done" |
| P8 | Who may perform an irreversible action, merge included |

## Pieces

| Piece | Where |
Expand Down
Loading
Loading