Skip to content

Task: Describe loopwright by its principles, not its stack #13

Closed

Description

@SamuelDenani

Goal

Make loopwright describe itself by its principles first and its stack second, in
the four places where its identity is currently written through the stack. The
most consequential of the four is .loopwright/claude-md-section.md: it is the
block install.sh injects into every host repo's CLAUDE.md, so it is how
loopwright introduces itself to everyone who adopts it. Leaving it as is would
mean the source repo talks about principles while every adopter still reads a
description by directory and test runner.

What "nothing is removed" means here, precisely, because one line is an
exception: every requirement fact survives — Node ≥ 20.11, the need for a
package.json, npm/pnpm/yarn support. They stop being the identity, but they stay
stated. The one line whose truth value changes, not just its framing, is the
merge-authority sentence at README.md:142-143: "always the human's decision"
becomes the human's decision by default. That is P8, and it is a real change,
not a reframing.

The checkable test for "principles first", so this is not a matter of taste:
in each rewritten lead, the first sentence must name a concrete opinion — the
tone to match is docs/loopwright/quality-gate.md:3-5 — and must not contain
"JS/TS" or "vendor" before that opinion has been stated. Any coder and any
reviewer can run that test without judgement.

Acceptance criteria

  • README.md:3-6 leads with a named opinion and the "vendor it into any
    JS/TS repo" clause follows rather than defines — per the textual test above.
  • README.md:89 ("Your stack, not loopwright's") and README.md:173 (the
    parenthetical "loopwright targets JS/TS repos") no longer frame identity as
    the stack, while remaining factually accurate about what is required.
    README.md:174 (package managers) carries no identity framing and needs no
    edit.
  • README.md:158-169 ("How it's wired") gains a row for
    docs/loopwright/principles.md.
  • README.md:142-143 — "Two rules hold the whole thing together: the gate
    is the only source of truth for "done"
    , and merging is always the
    human's decision.
    " — is reconciled with P8: merge is the human's by
    default, automating it is an explicit opt-in. This is the second site of the
    absolute rule, and README.md has only this draft as its owner.
  • CLAUDE.md and .loopwright/claude-md-section.md both point at three docs
    with principles first, and both describe loopwright by what it is
    opinionated about before naming .loopwright/. This includes
    CLAUDE.md:1-6, the preamble above the <!-- loopwright:start -->
    marker — it is unique to this repo, is not shared with
    claude-md-section.md, and is the single worst identity-by-mechanism site
    in the repo ("the engine lives in .loopwright/scripts/, its tests in
    .loopwright/tests/").
  • package.json:4 describes loopwright by its process opinions rather than
    as a "quality layer for AI-assisted JS/TS repos".
  • No factual requirement is lost in the rewrite: Node ≥ 20.11, the need for a
    package.json, and npm/pnpm/yarn support remain stated somewhere in
    README.md.

Pointers into the RFC

  • Context → the exact sentences that currently carry the stack framing, with
    their locations.
  • Scope, third bullet → the four files, why claude-md-section.md is the most
    important of them, and the README.md:142-143 reconciliation.
  • "Why the contested branches settled where they did" → the P2/P8 split, which
    is what README.md:142-143 has to be rewritten against: the gate half of that
    sentence survives as P2, the merge half becomes P8's default.
  • docs/loopwright/quality-gate.md:3-5 is the one place in the repo that already
    states purpose process-first; it is the tone to match.

Blocked by

#11 — these files link to the doc and summarise it, so it has
to exist first.

Activity

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

    @SamuelDenani
    OwnerAuthor

    Spec and implementation plan committed: docs/specs/issue-13.md (on task/13-principles-first-identity, based on feat/rfc-5-core-principles).

    Six steps. Notes worth surfacing from planning:

    • CLAUDE.md:8-62 is verified byte-identical to .loopwright/claude-md-section.md, and install.sh:53-63 splices the latter into every host repo's CLAUDE.md. Those two edits are one edit applied twice, propagated with the installer's own awk splice and guarded by a byte-identity sync check.
    • CLAUDE.md:1-6 (above the <!-- loopwright:start --> marker, shared with nothing) gets its own step, since editing the shared block does not touch it and the sync check cannot see it.
    • There is no test to write: .loopwright/config.json scopes sources.roots to .mjs under .loopwright/scripts and .loopwright/tests, so markdown and one JSON string move no metric. Each step substitutes a runnable check with recorded before-output.
    • "Leads with the process opinion" is made checkable: the lead's first sentence must name a concrete opinion and must not contain the stack/mechanism words before it.
    • README.md:142-143 is the one line whose truth value changes rather than its framing, per P8.
  3. SamuelDenani commented on Oct 7, 2026

    @SamuelDenani
    OwnerAuthor

    done in #17, 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