Skip to content

Task: Strip opinions from loop-harness.md, leaving mechanics #12

Closed

Description

@SamuelDenani

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-77 are 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:66 is replaced by a bare reference to
    P8
    — not by a restatement of it. loop-harness.md may 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.md still reads coherently on its own as the
    execution half — base branch, closing keywords, draft-until-ready, the flow
    diagram and the Pieces table are intact.

  • docs/loopwright/quality-gate.md:7-9 ("The one rule") is left untouched:
    "only quality-gate.mjs can 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 the quality-gate.mjs rule 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

  1. added
    taskTask: implementable unit linked to an RFC
    on Oct 5, 2026
  2. SamuelDenani commented on Oct 7, 2026

    @SamuelDenani
    OwnerAuthor

    Spec committed: docs/specs/issue-12.md on task/12-strip-harness-opinions (base feat/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.

  3. SamuelDenani commented on Oct 8, 2026

    @SamuelDenani
    OwnerAuthor

    done in #18, merged into feat/rfc-5-core-principles

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    taskTask: implementable unit linked to an RFC

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions