agentic-team 0.0.0-stage → 6.2.0

package/template/hooks/review-rounds.sh

@@ -0,0 +1,172 @@
+#!/usr/bin/env bash
+# PreToolUse guard: a phase gets at most `thresholds.stuck_retry_limit`
+# review rounds, then a person decides.
+#
+# The cap was prose in lead.md, and a run went nine rounds on one phase
+# because the user's "loop until no high or medium remains" read as
+# overriding it. Each round found a new hole in the previous round's fix, so
+# nothing inside the loop could end it. Counting is the one part a machine
+# can do, so it is done here.
+#
+# A reviewer launch names its phase on a line
+# `Phase: <milestone directory>/<phase file name>`, and that file must exist
+# under .orchestra/milestones/ — a second spelling of the same phase would
+# start a fresh count. Lead must name it; any other session may leave it
+# out, uncounted, so a one-off review in discussion mode is never refused.
+#
+# The count lives in .orchestra/.sessions/review-rounds.json, keyed by phase
+# rather than by session, so a restarted lead does not start from zero, and
+# the installer keeps it across upgrades. Past the cap the launch is refused
+# until the prompt quotes the user's approval on a line
+# `Extra round approved by the user: …` — each launch past it carries its own
+# line, so one approval buys one round. Nothing
+# can check that the quote is real; it is honest by convention, like the
+# escape-hatch comments the policy check reads.
+#
+# Reads the tool call on stdin. Exit 0 allows, exit 2 blocks.
+set -euo pipefail
+
+input="$(cat)"
+
+verdict="$(printf '%s' "$input" | CLAUDE_PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$PWD}" node -e '
+  const fs = require("node:fs");
+  const path = require("node:path");
+  const { execFileSync } = require("node:child_process");
+
+  let s = "";
+  process.stdin.on("data", (d) => (s += d)).on("end", () => {
+    let call;
+    try {
+      call = JSON.parse(s);
+    } catch {
+      // Optional by design: an unparseable call is not ours to judge.
+      return;
+    }
+    if (call.tool_name !== "Agent") return;
+    const input = call.tool_input || {};
+    if (input.subagent_type !== "reviewer" && input.subagent_type !== "re-reviewer") return;
+    const prompt = String(input.prompt || "");
+
+    // The installer writes into the directory it ran in, which can be an app
+    // inside a larger repository, so the project directory comes first.
+    let root = process.env.CLAUDE_PROJECT_DIR;
+    if (!fs.existsSync(path.join(root, ".orchestra"))) {
+      try {
+        root = execFileSync("git", ["-C", root, "rev-parse", "--show-toplevel"], {
+          encoding: "utf8",
+          stdio: ["ignore", "pipe", "ignore"],
+        }).trim();
+      } catch {
+        return;
+      }
+    }
+    const milestones = path.join(root, ".orchestra", "milestones");
+    // Not an Orchestra project here: nothing to count against.
+    if (!root || !fs.existsSync(milestones)) return;
+    const dir = path.join(root, ".orchestra", ".sessions");
+
+    const phase = /^[ \t]*Phase:[ \t]*(\S[^\n]*?)[ \t]*$/m.exec(prompt);
+    if (!phase) {
+      const session = String(call.session_id || "").replace(/[^A-Za-z0-9._-]/g, "");
+      let role = "";
+      try {
+        role = session ? fs.readFileSync(path.join(dir, session), "utf8").trim() : "";
+      } catch {
+        // No marker: not a lead session, so an uncounted review is allowed.
+      }
+      if (role === "lead") {
+        process.stdout.write("A reviewer launch from lead names its phase on a line `Phase: <milestone directory>/<phase file name>`, so its review rounds can be counted.\n");
+      }
+      return;
+    }
+    const key = phase[1];
+    // Exactly two segments, matched by listing rather than by existsSync: a
+    // trailing slash, a third segment or a change of case on a
+    // case-insensitive disk would each name the same file under a new key.
+    const parts = key.split("/");
+    const listed = (d, name) => {
+      try {
+        return fs.readdirSync(d).includes(name);
+      } catch {
+        return false;
+      }
+    };
+    if (parts.length !== 2 || !listed(milestones, parts[0]) || !listed(path.join(milestones, parts[0], "phases"), `${parts[1]}.md`)) {
+      process.stdout.write(`Phase: ${key} names no file .orchestra/milestones/<milestone>/phases/<phase>.md. Spell it as the directory and the file name, e.g. Phase: M2-design-system/phase-3 — another spelling would start a fresh count.\n`);
+      return;
+    }
+
+    let cap = 3;
+    try {
+      const cfg = fs.readFileSync(path.join(root, ".orchestra", "config.yml"), "utf8");
+      const m = /^\s*stuck_retry_limit:\s*(\d+)/m.exec(cfg);
+      if (m) cap = Number(m[1]);
+    } catch {
+      // No config: the documented default is the only cap we know.
+    }
+
+    // Parallel phases launch reviewers at once. Without the lock two reads
+    // see the same count and one increment is lost; without the rename a
+    // reader can meet a half-written file and start every phase from zero.
+    fs.mkdirSync(dir, { recursive: true });
+    const lock = path.join(dir, "review-rounds.lock");
+    const sleep = (ms) => Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+    const deadline = Date.now() + 5000;
+    for (;;) {
+      try {
+        fs.mkdirSync(lock);
+        break;
+      } catch (e) {
+        if (e.code !== "EEXIST") throw e;
+        try {
+          // A launch holds the lock for milliseconds, so one older than this
+          // was left by a crash; shorter than the wait, so it clears in time.
+          if (Date.now() - fs.statSync(lock).mtimeMs > 3000) fs.rmdirSync(lock);
+        } catch {
+          // Another launch released or cleared it first; try again.
+        }
+        if (Date.now() > deadline) {
+          process.stdout.write("The review-round count is locked by another launch. Launch the reviewer again.\n");
+          return;
+        }
+        sleep(25);
+      }
+    }
+    try {
+      const file = path.join(dir, "review-rounds.json");
+      let counts = {};
+      try {
+        counts = JSON.parse(fs.readFileSync(file, "utf8"));
+      } catch {
+        // First reviewer launch in this project, or a file someone deleted:
+        // both mean no rounds recorded yet.
+      }
+      const done = counts[key] || 0;
+      const approved = /^[ \t]*Extra round approved by the user:[ \t]*\S/m.test(prompt);
+      if (done >= cap && !approved) {
+        process.stdout.write(
+          `Review round ${done + 1} for ${key} is past thresholds.stuck_retry_limit (${cap}). ` +
+          "Stop and give the user the open Blocking and Important findings. Under --auto, set the task blocked with a comment naming them. " +
+          "If the user approves another round, quote them on a line `Extra round approved by the user: …`.\n",
+        );
+        return;
+      }
+      counts[key] = done + 1;
+      const tmp = `${file}.${process.pid}`;
+      fs.writeFileSync(tmp, `${JSON.stringify(counts, null, 2)}\n`);
+      fs.renameSync(tmp, file);
+    } finally {
+      try {
+        fs.rmdirSync(lock);
+      } catch {
+        // Already cleared as stale by a waiter; there is nothing left to release.
+      }
+    }
+  });
+')"
+
+if [ -n "$verdict" ]; then
+  printf '%s\n' "$verdict" >&2
+  exit 2
+fi
+exit 0

package/template/rules/acceptance-check.orchestra.md

@@ -0,0 +1,11 @@
+# Acceptance Check
+
+After implementation, check whether you built **the right thing** — not just whether it works.
+
+1. Re-read the phase file's acceptance criteria
+2. For EACH criterion: "Does my implementation satisfy this?"
+3. If YES → proceed
+4. If NO → fix it
+5. If UNCERTAIN → flag: "Unverified: {criterion} — {reason}"
+
+This catches "code works but doesn't do what was asked."

package/template/rules/analytics-kpi.orchestra.md

@@ -0,0 +1,56 @@
+# Analytics & KPIs
+
+**Mandatory.** A milestone that cannot state how its success is measured is
+not ready to build.
+
+## KPIs come before code
+
+Every milestone declares, in `milestone.md`, before implementation starts:
+
+- **The metric** — one primary number this work is meant to move
+- **The baseline** — what it is today, or explicitly "unknown, this
+  establishes it"
+- **The target** — the number that would make this worth having built
+- **How it is read** — the query, dashboard, or event that produces it
+
+If you cannot fill these in, the milestone is a guess. Say so to the user
+rather than building it and finding out later.
+
+A metric that cannot go down is not a KPI. "Number of features shipped"
+measures activity, not outcome.
+
+## Events
+
+Instrument the user's action, at the point it happens. An event fired from
+a wrapper three layers away eventually fires for the wrong reason.
+
+- **Naming** is consistent and boring: `object_action` — `checkout_started`,
+  `signup_completed`. Pick the convention once, never mix styles.
+- **Typed and centralised.** Event names and payload shapes live in one
+  schema module per app, and instrumentation imports from it. A string
+  literal at a call site is how analytics quietly rots.
+- **No PII in properties.** No email, no name, no free-text the user typed.
+  Identify with a stable anonymous id.
+- **Respect consent.** Where consent is required, no event leaves the device
+  until it is given. This is not a preference.
+
+## Every screen and every failure
+
+- Each screen or route reports a view event.
+- Each critical flow reports start, success, **and failure** — with a reason
+  code. A funnel that only records success cannot tell you why people left,
+  which is the only thing you actually wanted to know.
+
+## Verifying
+
+Instrumentation is code, so it is tested like code: assert the event fires
+once, with the right name and shape. An analytics call is exactly the kind
+of third-party seam the testing rule exists to cover.
+
+Before a milestone closes, confirm the events actually arrived. Untested
+instrumentation is usually broken instrumentation.
+
+## Defaults
+
+PostHog. A default, not a mandate — substitute freely, but the capability
+is required. Configure under `observability` in `.orchestra/config.yml`.

package/template/rules/code-standards.orchestra.md

@@ -0,0 +1,35 @@
+# Code Standards
+
+**SOLID** — Single responsibility, open/closed, Liskov substitution, interface segregation, dependency inversion. Open/closed and dependency inversion earn their place once a second real consumer needs the seam — see DRY below. Built before that consumer exists, they are over-engineering wearing a principle's name.
+
+**KISS** — Keep it simple. Don't over-engineer.
+
+**YAGNI** — Don't build what you don't need right now.
+
+**DRY** — Don't repeat yourself. Extract after second duplication, not before. The same rule covers an interface, a seam, or an injection point built for open/closed or dependency inversion: add it when a second real caller needs it, never for a hypothetical one.
+
+**Before writing code, stop at the first rung that holds:**
+1. Does this need to exist? → no: skip it (YAGNI)
+2. Already in this codebase? → reuse it
+3. Stdlib does it? → use it
+4. Native platform feature? → use it
+5. Installed dependency? → use it directly
+6. One line? → one line
+7. Only then: the minimum that works
+
+This governs volume, never correctness. Validation, error handling, security
+and accessibility are never on this ladder — they apply at every rung,
+covered by their own rules (`security.orchestra.md`,
+`observability.orchestra.md`, and the `accessibility` skill where the
+platform has one), regardless of how
+small the change looks. Rung 5 does not skip the wrapper
+`testing-standards.orchestra.md` requires for anything calling a third-party
+library (`src/integrations/<provider>/`) — that wrapper exists for the seam
+test, not for swapability, and the ladder governs what sits on top of it,
+never whether it exists.
+
+**Zero-tolerance rules:**
+- No workarounds — if the right solution is hard, do it right. Flag the effort in your report.
+- No unused code — delete dead imports, functions, files. Don't comment out.
+- No breaking changes without migration — update every consumer.
+- Current library versions only — verify before using, don't assume from memory.

package/template/rules/comments.orchestra.md

@@ -0,0 +1,77 @@
+# Comments
+
+Default to no comment.
+
+A comment explains *why*, never *what*. The "what" is the job of naming: if
+a comment is needed to say what the code does, rename or extract instead.
+The test — would a reviewer ask *why* here? Then comment. Would they only
+ask *what*? Then rename.
+
+Write one only for:
+
+- a workaround or constraint imposed from outside — bundler, driver, API
+  quirk — linking the upstream issue when one exists
+- a non-obvious invariant the reader cannot derive locally
+- a deliberate trade-off, including "do not simplify this to X" where X
+  looks tempting and is wrong
+
+When a comment is warranted, write the single most accurate sentence you
+can, and stop. It has to close the question, not open new ones: name the
+consequence or the rejected alternative, not the restated rule. If a reader
+would still ask *why* after reading it, the sentence is not finished.
+
+Never: restating the next line, section banners, commented-out code, a
+comment duplicating a test name. Put it above the line it guards, not
+trailing a long line.
+
+## Some comments are read by the gate
+
+Two checks in `scripts/policy-check.mjs` clear on a comment — `await-in-loop`
+on one above the loop, `swallowed-error` on one inside the catch. Those are
+not prose for a reviewer; they are the escape hatch, and deleting one as
+noise turns the gate red.
+
+They are also exactly the *why* this rule asks for: which of the sequential
+cases this loop is, why failure on this path is acceptable. `// ok` clears
+the check and tells the next reader nothing — that is a review finding, not
+a pass.
+
+`.claude/rules/security.orchestra.md` asks for the same shape beside a
+security setting: the value taken and where it came from.
+
+## A TODO is a tech debt that skipped the tracker
+
+`.claude/rules/tracker-authority.orchestra.md` gives a workaround a home: a
+`tech_debt` task naming what should have been done instead. A TODO is that
+task written where nobody will find it.
+
+So a TODO carries the task — `TODO(#123)`, `TODO(CU-86abc)`, or a link — and
+the task carries the reason. With `tracker.provider: none` there is no task,
+so there is no TODO: do the work, or report it in the phase result as left
+undone.
+
+## Doc comments
+
+JSDoc, KDoc, Swift `///` — one rule for all three. Not mandatory. Add one
+only when it says something the signature cannot.
+
+Never restate the signature: no `@param value - the value`, no `@returns
+the result`, no "this function does X" above a function named X.
+`@deprecated` always earns its place — name the replacement.
+
+## While editing
+
+Delete a restating comment on a line you are already changing. Leave the
+rest — `.claude/rules/phase-limits.orchestra.md` applies, and a comment
+sweep is not the phase.
+
+## What is enforced
+
+Only what can be decided precisely. A restating comment cannot be — a
+machine cannot tell "increment the counter" from a reason — so it stays a
+review item above.
+
+| Check | Fails on |
+|---|---|
+| `commented-out-code` | a `//` line that parses as a statement |
+| `todo-without-task` | `TODO`, `FIXME`, `HACK`, `XXX` with no task id or link |

package/template/rules/commit-format.orchestra.md

@@ -0,0 +1,20 @@
+# Commit Format
+
+All commits MUST use conventional commit format.
+
+**Format:** `<type>(<scope>): <description>`
+
+**Types:** feat, fix, refactor, perf, test, chore, docs, style, ci, build, revert
+
+**Rules:**
+- Each phase produces exactly ONE commit
+- Subject line max 72 characters
+- Body explains WHY, not WHAT
+- Breaking changes add `!` after type: `feat!(scope): description`
+- No `Co-Authored-By` trailers — never add co-author lines
+
+**The one exception is a squashed task pull request.** Its subject is
+`#<task-id> - <subject>`, because that is where the tracker's link lives and a
+task PR collapses several conventional commits into one. The `commit-msg` hook
+accepts that shape and nothing else outside the convention — see
+`.claude/rules/pull-request.orchestra.md`.

package/template/rules/dependency-upgrade.orchestra.md

@@ -0,0 +1,112 @@
+# Dependency Upgrades
+
+Dependabot opens the PR. The test suite decides.
+
+## Merging
+
+Green CI is the merge signal for a **minor or patch** bump. That is the
+entire reason the seams are covered: a bump that changes behaviour has to
+turn the suite red.
+
+- **minor / patch, green** → merge. No changelog reading required.
+- **major, green** → a human reads the changelog first. A major version is
+  the maintainer stating the contract changed, and some of what changed —
+  default timeouts, retry behaviour, performance, error types — is not
+  visible to any test. Green means "nothing we assert broke", not "nothing
+  broke".
+- **Red** → **do not** loosen the test to make it pass. The test is doing
+  its job. Fix our code to match the new behaviour, or hold the upgrade.
+- Never merge a red dependency PR "because it's just a minor."
+
+The split is recorded in `.orchestra/config.yml` under
+`testing.dependencies.automerge`, and it is **automation, not etiquette**:
+
+- A dependency PR that changes a test file **fails**. A bump that needed a
+  test loosened is a behaviour change wearing a version number.
+- A major is labelled `needs-human` with a comment saying why green is not
+  the same as safe.
+- Minor and patch auto-merge with `--auto`, so they still wait for every
+  required check.
+
+Nothing here is a bot deciding a major is fine. It only removes the queue of
+patches that would otherwise be merged in a batch with the majors hidden in
+it.
+
+## When a test fails on a bump
+
+1. Read the library's changelog for that version range before touching code.
+2. Fix forward — update our wrapper to the new behavior.
+3. If the change is genuinely breaking and the fix is large, hold the
+   upgrade and open a task. Do not half-migrate.
+
+## Adding a dependency
+
+- Check it is maintained: when did it last publish? A package quiet for a
+  year is a liability, not a dependency.
+- Prefer the platform. Do not add a library for something the language or
+  framework already does.
+- Anything we wrap gets a test, so the next bump is checked automatically.
+
+## Framework-managed versions
+
+Some frameworks pin their dependency tree on purpose, and there the registry
+is not the authority — the framework's own table is.
+
+Expo is the case that bites. The SDK is built against specific versions of
+react, react-native, typescript and every native module. `expo install`
+resolves against that table; `yarn add <pkg>` resolves against the registry
+and installs something the SDK rejects — often at runtime, on a device, long
+after the install reported success.
+
+- **In an Expo app, install with `expo install`.** Never `yarn add` a
+  package the SDK manages.
+- `expo install --check` says whether the tree is aligned. Run it after
+  touching dependencies; it is the honest answer, not a guess.
+- `expo install --fix` is what moves these versions, and an SDK upgrade is
+  the event that triggers it.
+- Dependabot cannot see that table, so SDK-managed packages are in the
+  `ignore` list in `.github/dependabot.yml`. Do not remove them to "get
+  updates" — a green CI on one of those bumps still breaks the app.
+
+The same reasoning applies to any framework that ships a compatibility
+table. Check for one before reaching for `@latest`.
+
+## A fresh repo has no upgrades pending
+
+Scaffolding is where staleness gets in. A create tool writes its own
+dependency versions into the package.json it generates, and those were
+current on the day its template was published — `create-next-app` ships
+`"@types/node": "^20"`, `create-expo-app` ships jest 29. A workflow written
+from memory pins `actions/checkout@v4` the same way.
+
+So a scaffold ends by resolving everything the template left behind against
+the registry, and the check is simple: **if Dependabot opens a PR against a
+repo created the same day, the scaffold is broken.** Fix it in the stack —
+`refresh_scaffold_deps` and `latest_action_ref` in
+`.orchestra/stacks/_lib/common.sh` — not in the project.
+
+## A scaffold proves it is clean, and fixes nothing at the end
+
+Every deterministic fix happens *during* setup. The last step only verifies:
+
+- peers this app should provide and does not → **fails**
+- unmet peers inside a dependency's own manifest → reported, never fatal,
+  because it cannot be fixed from here and a gate nobody can satisfy is a
+  gate that gets disabled
+- `yarn npm audit --severity critical` → fails
+
+It deliberately does not upgrade or downgrade anything. Changing versions
+after the verification gate has run leaves a repo whose gate passed against
+different versions than the ones committed — and it would quietly undo the
+deliberate pins: the age-gate deferral, the Expo SDK table, Robolectric's
+supported API level.
+
+When it fails, fix it in `.orchestra/stacks/`. Fixing it in the project means
+the next project meets the same thing.
+
+## Versions
+
+Install at `@latest`; the lockfile records what landed. Pin to a range only
+where a real compatibility constraint exists, and write the reason next to
+it. Gradle is the exception — versions are explicit in the version catalog,
+because dynamic versions destroy build reproducibility.

package/template/rules/design-parity.orchestra.md

@@ -0,0 +1,181 @@
+---
+paths:
+  - "designs/**"
+---
+
+# Design Parity
+
+## What a design source is
+
+A phase has a design source when its frontmatter declares one:
+
+```yaml
+design: designs/checkout/payment-step.png    # file in the repo
+design: https://…                            # published Claude Design artboard
+```
+
+No `design:` field means no parity check. Do not infer one from a phase
+title, and do not invent a path — a check against a guessed design is worse
+than no check.
+
+Design files live under `designs/` at the repo root, mirroring the screen
+structure. A URL is fetched at check time.
+
+## What the check needs
+
+Two images: the design, and the implemented screen. If you cannot produce
+the second one, **the check cannot run** — say so plainly and mark the
+criterion unverified. Do not approve on the strength of reading the code.
+
+Producing it needs a render target and a capture tool:
+
+| App | Render target | Capture |
+|---|---|---|
+| Web | react-cosmos fixture | browser tool screenshot |
+| Expo | the screen in a simulator | simulator screenshot |
+| Native iOS / Android | the screen in a simulator | simulator screenshot |
+
+Capture with the session's own tools — a browser tool screenshot for web, the
+simulator tool for mobile. Where the simulator integration is unavailable
+(a machine whose `xcode-select` points elsewhere, a session without the
+panel), fall back to the platform's own command and **say that you did**:
+
+```bash
+xcrun simctl io booted screenshot designs/.captures/<phase>.png     # iOS
+adb exec-out screencap -p > designs/.captures/<phase>.png           # Android
+```
+
+If no capture is possible at all, report that as the reason the check was
+skipped. That is an honest unverified, not a pass.
+
+### Where the files live
+
+```
+designs/
+├── <screen>.png          the design, committed, mirroring the screen structure
+├── .fetched/             a URL design, fetched once at milestone start
+├── .captures/            what was built, committed so the PR can show it
+└── .reports/             machine output of a comparison, gitignored
+```
+
+Only the images a pull request shows are committed. A comparison tool's
+output — JSON reports, logs, diffs — goes to `designs/.reports/`, which is
+never committed: it is regenerated from the images, and one project committed
+~100k lines of it, which agents then read back as context.
+
+A URL is fetched **once** into `designs/.fetched/`, when lead composes the
+phase, not at each comparison. The capture goes to `designs/.captures/` and is
+committed with the change, because `gh` cannot upload an image and a
+screenshot outside the branch cannot appear in a pull request. A design edited mid-milestone would otherwise silently change what
+the phase was measured against, and the PR would show a pair that never
+existed together.
+
+Applies when the task has a design source. Who judges what is left over
+depends on whether anyone is watching — the `--auto` flag.
+
+## Measured where it can be measured, judged where it cannot
+
+The goal is the design, exactly — not something in its spirit. But a literal
+pixel threshold cannot be the gate: fonts hint differently, antialiasing
+differs, and a capture at device scale is not the design's export scale, so
+the difference is never zero and a run would never exit. A gate that can never
+pass is a gate that gets disabled.
+
+So the strictness goes where it can actually bite. Most of what people mean by
+"pixel perfect" is a **number**, and numbers are checkable:
+
+| What | How it is checked | Verdict if wrong |
+|---|---|---|
+| Spacing, padding, gaps | Measured off the capture against the design's value | **blocking** |
+| Type size, weight, line height | Read from the design, compared to the token used | **blocking** |
+| Colour | The design's value, matched to a token value | **blocking** |
+| Radius, border width, elevation | Same | **blocking** |
+| Element present, ordered, aligned | Read from both | **blocking** |
+| Every state the design shows — hover, pressed, disabled, empty, error | Rendered and compared | **blocking** |
+| Content: real strings, not lorem | Read from both | **blocking** |
+| Font rendering, sub-pixel antialiasing, capture scale artefacts | — | non-blocking |
+
+A colour or a spacing that is *close* is wrong. The app has a token module for
+exactly this reason, and "16 where the design says 12" is not a judgement call
+— it is a defect with a number attached. Report it that way: the value in the
+design, the value in the build, and the token that should have carried it.
+
+Only the last row is non-blocking, and it is the only row a machine cannot
+decide. Everything above it, you can.
+
+If a value in the design cannot be expressed by the app's token module, that is
+a **blocker to report** — the design and the design system disagree, and
+splitting the difference silently is how a token module stops being true.
+
+## The value comes from the source, not from the pixels
+
+The design's value in the table above is read from the source when the
+design states it — CSS, a token file, an export with numbers — and sampled
+from the image only when it does not. The capture is still needed for
+what only a render can show: placement, order, states, whether an element is
+there at all.
+
+Recovering from pixels a number the design already wrote down means building
+a measuring engine, and where the design renders through a different engine
+than the app — an HTML board against a native screen — that engine never
+converges, because what is left over is the renderers' difference, not the
+build's. One run spent most of a weekly budget on exactly that.
+
+## The non-blocking row is not promoted
+
+Font rendering, sub-pixel antialiasing and capture scale artefacts stay
+non-blocking. No agent makes them blocking — not lead by a decision, not the
+architect by an RFC, not an engineer or a reviewer by a tolerance. Only the
+user can, by saying so; the PM then writes it into that phase's acceptance
+criteria, where lead and the reviewer read it.
+
+"Perfect" and "pixel perfect" from the user mean the table above, exactly.
+They are not a request for this row. If the words seem to ask for more, ask.
+
+A check whose job is to tell a renderer difference from a defect is this row
+being worked on, and it does not belong in the gate.
+
+## Who fixes what
+
+The agent building the screen fixes every blocking discrepancy it can see,
+before it reports done. Always — "build it, then let someone else notice it is
+wrong" is not a workflow, it is how an approximation reaches a reviewer with a
+straight face.
+
+What changes is who judges the remainder.
+
+## Without `--auto` — the human judges
+
+Both images go in the pull request body's table and a person decides. Lead
+does not loop on its own: the builder already fixed what it could see, and the
+call that is left is the one a person is better at.
+
+`gh` cannot upload an image. Reference the design by its repo path or URL, and
+commit the capture into the branch under `designs/.captures/` so the pull
+request can show it. If you could not capture, write
+"not captured — {reason}" in the cell rather than leaving it blank.
+
+## With `--auto` — nobody is watching, so it loops
+
+1. Implement, render, compare.
+2. Blocking discrepancies → fix and repeat.
+3. Stop at `delivery.max_design_iterations`.
+4. On exhaustion, apply `delivery.on_parity_exhausted`:
+   - `tech-debt` — open a tech debt task naming the exact discrepancies that
+     remain, and move on. See
+     `.claude/rules/tracker-authority.orchestra.md`.
+   - `fail` — mark the phase failed and stop
+
+The pull request still carries both images, and it still gets reviewed. The
+loop exists because there is no human at the gate to catch what the builder
+could not see, not because the work is invisible.
+
+Never silently accept a screen that does not match. Never quietly raise the
+iteration cap to make a run succeed.
+
+## Render target
+
+Prefer the component workbench over a live app screen. A fixture renders
+deterministically; a real screen carries real data, loading states, and
+timing, all of which produce differences that have nothing to do with the
+design.