[jflavan]

Rules a team writes once, checked at every gate, with a record per change of how each rule was kept.

• Design: docs/superpowers/specs/2026-10-28-standards-design.md, with a "Changed while building" list at its end.
• Plan: docs/superpowers/plans/2026-10-28-standards.md.
• Every call made while building is a bullet in docs/decisions.md under "Standards (2026-10-28)".

Standards

• The files. A standard is loopstra/standards/<name>.md:
  • a title, free context text, and ## Rules written as - LABEL: text;
  • optional front matter: applies_to (globs), needs_person, and check (a command).
• Where they are read. Always from main's commit, never the checkout.
• When a file cannot be read. The loop starts no steps until it is fixed, but requests, syncing and signals keep working, so a fix from the console still lands. loopstra start warns rather than refuses.
• Spec gate.
  • The spec's ## Standards section lists only the rules its design decides something about, plus exceptions.
  • A code check confirms each label is real.
  • spec-check judges breaches.
• Plan gate.
  • The plan covers every rule that applies to its files.
  • A code check confirms full coverage.
  • plan-challenge judges breaches.
• Build, resolve and review are told the rules that apply. A review finding can name a rule, and review.md gets a "Findings against the standards" list.
• Merge gate.
  • A diff that edits loopstra/standards/ blocks. The test-protection hook also refuses such edits in every writing session, resolve included.
  • A needs_person standard that applies, or that a person added, makes the change wait for a person through the existing risky-change gate.
  • Tool checks run after the tests, through the existing fix loop. They get LOOPSTRA_BASE, the merge base, so scanners can report only new findings.
• Done. The done-check judges each rule. The runtime appends a ## Standards section to outcome.md that names the standards' commit and lists the rules, exceptions, tool checks and scope changes. Unmet rules block.
• Exceptions.
  • A spec or plan can write - LABEL: exception: why. No agent can grant one.
  • The gate waits for a person (spec_gate / plan_gate), even when nobody is on that gate in the config.
  • Each approval is recorded with who, where and when in the change's intent/<slug>/standards.md. Undoing the approval takes it back out.
• Per-change scope. A person can add a standard to one change, or remove one with a note. This is a new standards-scope request, recorded in the same file.
• Repositories without standards are unchanged. A golden test checks that the prompts are byte-identical. The standards instructions are appended from code only when standards apply; no shipped prompt template changed.

Surfaces

• loopstra standards lists the standards, their scopes and labels, and any problems.
• loopstra setup standards adds, edits and removes standards interactively. It suggests a base-aware scanner that is already installed and tries each new or changed check on main. setup --check checks every standard and warns when a check already fails on main.
• Console:
  • Settings › Standards: a form with an "Edit as Markdown" toggle, and "Try it on main".
  • "Exceptions granted": every exception and scope change across changes.
  • A Standards panel on each change, with an explicit "Allow the exception and approve the plan" button and an add/remove dialog.
  • Writes go through agent-files and standards-scope requests that the loop applies and commits. The Origin check covers every POST, and "try" never runs a command the page sends.
• Onboarding. The operator skill gets a "Set up the standards" step: draft standards from the team's design records, policies, lint configs and CI, then check them. The agent never commits.

Review

• Building. Built task by task (20 tasks), each with its own spec-and-quality review and fix rounds. Those reviews caught, among others:
  • git failures silently dropping rules;
  • undoing an approval keeping its exceptions;
  • the done-check's schema forcing a standards field in every repository;
  • "Edit as a form" bouncing back to Markdown.
• Branch review. I ran /code-review high on the whole branch and fixed all 10 findings, plus 6 smaller ones left from the task reviews, in one wave that was then re-reviewed:
  • files the checks rewrote are put back when a tool check keeps failing;
  • an added needs_person standard waits for a person;
  • setup's edit leaves a file untouched rather than dropping text it cannot keep;
  • loopstra start warns instead of refusing, so the console's fix can land;
  • outcome lines with empty evidence read back;
  • the console names uncommitted files the way git does (-z);
  • Needs attention survives a failed read;
  • reads of the standards are cached per commit, and the merge diff is computed once;
  • duplicated helpers are merged;
  • main is resolved once in "try on main";
  • one-line review lines;
  • tool checks start after the tests in parallel_checks mode;
  • the scope dialog can't be sent twice;
  • glob and label edge cases;
  • the hook normalizes paths.
• Left as is.
  • The outcome parser takes the last ): before a result word, so evidence shaped like (x): met: could be misread.
  • standardsFilesAt reads one blob per file at a time, which is fine for a handful of standards.

Test plan

• bun run check: typecheck, lint, dead-code, and 2203 tests pass, 0 fail, up from 1953
• New tests:
  • standards, standards-record, standards-command, setup-standards, console-standards and ui-standards;
  • the standards cases in stages-*, apply, risk, hook, status, envelopes and context;
  • tests/integration/standards-tick.test.ts, standards-run.test.ts and golden-prompts.test.ts.
• CI on ubuntu, macOS and Windows (a second run after making three tests portable to Windows)

🤖 Generated with Claude Code