Skip to content

Task: Write docs/loopwright/principles.md #11

Description

@SamuelDenani

Goal

Write docs/loopwright/principles.md: the descriptive statement of loopwright's
core opinions and its detail territory, with the classification rule and the
amendment mechanism. This is the artifact the whole RFC exists to produce, and
the three downstream RFCs that already cite it depend on it existing.

The doc must match the conventions of its two siblings in docs/loopwright/:
single # title then ## sections, sentence-case short section names, tables
as the default format for anything enumerable, hard wrap at ~78 columns, no
front matter, no date, no emoji, impersonal declarative voice, every path and
tool name backticked.

Acceptance criteria

  • docs/loopwright/principles.md exists and opens with the Context that
    states near-autonomy as the destination and the core opinions as its
    preconditions, not its constraints.
  • P1–P12 are present as a list with stable ids, and each carries three
    things: the assertion, a rejects: line naming one concrete change it
    refuses, and an enforcement pointer that is a file name with no line
    number (left empty where nothing enforces it).
  • T1–T8 are present, each with its territory and its current default. Six
    carry a named seam; T4 and T6 carry none — the RFC omits them
    deliberately, so inventing one is a defect, not a completion. No contract is
    specified for T1, T2, T3, T7 or T8 — the seam is named, the shape is its own
    RFC's — with T5 the one exception, whose four required capabilities are
    enumerated in full because this RFC resolves them.
  • The classification rule and an Amendments section are present; the
    amendment rule states that ids are stable, amendments never renumber, and
    a withdrawn opinion stays as P4 (withdrawn, RFC #N).
  • P7 names the policy file only. baseline.json is described as measured
    state belonging to P3, never as policy.
  • P12's assertion carries the three-valued connector contract — a value for a
    core-owned key, unconfigured, failed — with each state's verdict stated
    (unconfigured warns and never blocks; failed always blocks), not only
    "connectors never invent a key". This is normative content and belongs in
    the doc; see the note on the RFC's rationale prose below.
  • Read against RFC: Stack connectors, decouple the quality gate from JS/TS #6, RFC: Isolated agent runtime with a mediated, async channel #7, RFC: One config file, YAML, sectioned by feature #8, RFC: Versioned releases with changesets, and automatic changesets in the loop #9 and RFC (draft): Interactive installer for first-time setup #10, the doc contradicts none of them
    except the RFC: Versioned releases with changesets, and automatic changesets in the loop #9 version-bump contradiction, which the RFC states is
    deliberate.

Pointers into the RFC

  • The twelve opinions and the eight territories are tabulated in the RFC's
    Decision section.
  • On the RFC's "Why the contested branches settled where they did" section: what
    must not travel into the doc is the history — which alternative was
    rejected, what the original RFC said before the grill, which RFC a decision
    contradicts. What must travel is any normative content that happens to
    live only in that prose, because the Decision tables are summaries: the
    three-valued connector contract for P12, the P2/P8 division of labour, and the
    fact that baseline.json is measured state and not the policy file P7 names.
    The test is: a rule a reader must obey belongs in the doc; the story of how it
    was decided belongs in this issue.
  • The four agent-host capabilities (T5) and the T6/T7 relationship are spelled
    out in the RFC's Detail territory section.
  • The architecture comment on issue RFC: Core principles, opinionated about process, agnostic about stack #5 has the four boundary diagrams; the seams
    it draws are core ↔ connector, engine ↔ host, loop ↔ agent host and
    host ↔ harness. The doc names seams but draws nothing.
  • docs/loopwright/loop-harness.md and docs/loopwright/quality-gate.md are the
    style reference.

Blocked by

Nothing.

Activity

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

    @SamuelDenani
    OwnerAuthor

    Spec and implementation plan: docs/specs/issue-11.md (committed as f981739 on task/11-principles-doc, cut from feat/rfc-5-core-principles).

    7 steps, 8 acceptance criteria. No test step — markdown is outside every collector's scope (.loopwright/config.json sets sources.roots to the engine's .mjs files), so each step substitutes a check first command that fails before the change and passes after.

    Orchestrator rulings recorded in the plan:

  3. added a commit that references this issue on Oct 7, 2026
  4. SamuelDenani commented on Oct 7, 2026

    @SamuelDenani
    OwnerAuthor

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