Repository navigation
Task: Strip opinions from loop-harness.md, leaving mechanics #12
Description
Goal
Strip from docs/loopwright/loop-harness.md:44-77 the rules that are core
opinions, leaving behind only harness mechanics. Today that file carries eight
bolded "Rules of the loop", several of which assert the same things the new doc
asserts — two lists of rules is two sources of truth, and the one nobody updates
starts lying.
This task does not write any principle. principles.md is the sole author of
P1–P12; its own task writes them in full. The change here is one-directional:
delete the opinion from loop-harness.md and replace it with a reference to the
principle that now owns it.
It also reconciles the one place where the new doc changes a rule rather than
describing it: line 66 states that merging is always the human's decision,
absolutely, while P8 makes it opt-in-automatable.
Acceptance criteria
-
All eight rules at
loop-harness.md:44-77are handled per this fixed
classification, with no rule left undecided:| Lines | Rule | Verdict | |---|---|---| | 46-49 | Base branch | mechanics — stays | | 50-54 | Closing keywords | mechanics — stays | | 55-57 | Draft until ready | mechanics — stays | | 58-60 | The gate is the only source of truth for "done" | opinion **P2** — deleted, replaced by a reference | | 61-65 | State lives in artifacts, not sessions | opinion **P1** — deleted, replaced by a reference | | 66 | Merging is always the human's decision | opinion **P8** — deleted, replaced by a reference | | 67-72 | Architecture is scaffolding, not a spec | mechanics — stays | | 73-77 | `boundary-reviewer` is the first thing to cut | mechanics — stays | -
No rule that is an opinion remains stated in
loop-harness.md— the file
references the principle by its id instead of repeating it, so no rule
exists in both files and no principle text is authored here. -
The merge rule at
loop-harness.md:66is replaced by a bare reference to
P8 — not by a restatement of it.loop-harness.mdmay still describe that
a merge step exists at the end of the flow, which is mechanics; it must not
state who holds the authority or under what condition, which is P8's.
Concretely: "See P8" and not "merging is the human's by default, automating
it is an opt-in" — the second sentence is principle text, and authoring it
here is what recreates the two-sources-of-truth problem this task exists to
remove. -
What remains in
loop-harness.mdstill reads coherently on its own as the
execution half — base branch, closing keywords, draft-until-ready, the flow
diagram and thePiecestable are intact. -
docs/loopwright/quality-gate.md:7-9("The one rule") is left untouched:
"onlyquality-gate.mjscan fail the build" is CI mechanics, not an
opinion, and P2 does not replace it.
Pointers into the RFC
- Scope, second bullet: what moves and what stays.
- "Why the contested branches settled where they did" → the P2/P8 split, and
the explicit note that thequality-gate.mjsrule is mechanics living in a
different doc. - Risks → P8 is the one non-descriptive line in a descriptive document; the
reconciliation of line 66 is where that shows up in the repo.
Blocked by
#11 — the destination has to exist before anything moves into
it, or the move produces a dangling reference.
Activity
SamuelDenani commentedon Oct 7, 2026
Spec committed:
docs/specs/issue-12.mdontask/12-strip-harness-opinions(basefeat/rfc-5-core-principles).Three steps: delete the P2 and P8 rules, re-home the grill-phase fact and delete the P1 rule, then rename the section and add the reference block. No test is written — markdown is outside every collector's scope, so each step carries a check-first command that fails before the change and passes after.
docs: strip the opinions from loop-harness, leaving mechanics (#12)
SamuelDenani commentedon Oct 8, 2026
done in #18, merged into feat/rfc-5-core-principles