agentic-team 0.0.0-stage → 6.1.0

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,170 @@
+# 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
+```
+
+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.

package/template/rules/observability.orchestra.md

@@ -0,0 +1,118 @@
+# Observability
+
+**Mandatory.** An app without error monitoring is not shippable, and this
+is not a launch-day task — it goes in before the first release, not after
+the first incident.
+
+## Error monitoring
+
+Every app reports uncaught errors and crashes to a monitoring service
+before it reaches any real user.
+
+- **Release tagging is required.** An error you cannot tie to a build is an
+  error you cannot fix. Every report carries the app version and commit.
+- **Upload the symbols** — source maps for web and Node, dSYMs for iOS,
+  mapping files for Android. A minified stack trace tells you nothing.
+- **Attach context**: route or screen, and a stable anonymous session id.
+- **Never attach secrets or PII.** No tokens, no emails, no request bodies
+  that might contain either. Scrub before send, not after.
+
+## Swallowed errors are bugs
+
+```
+catch (e) { }               // defect
+catch (e) { console.log(e) } // defect
+```
+
+Every catch either **handles** the error meaningfully, or **reports** it and
+rethrows. "Handled" means the user gets a correct outcome — not that the
+crash was hidden from them.
+
+The one exception is a genuinely optional path, and it carries a comment
+saying why failure is acceptable.
+
+Depth on what "handled" means — typed errors, propagation, what the user
+sees, degrading instead of crashing — in
+`.claude/skills/error-handling/SKILL.md`.
+
+## Structured logging
+
+Logs are data, not prose. JSON, one event per line.
+
+- Levels used honestly: `error` means someone should look, `warn` means it
+  might become an error, `info` is a business event, `debug` is off in
+  production.
+- Every server request carries a correlation id, and it appears in every
+  log line for that request. Without it you cannot follow a failure across
+  services. Take it from the caller's `x-request-id` when present, so a trace
+  that started upstream stays one trace, and echo it back so a caller can
+  quote it in a bug report.
+- **Redaction is configured in the logger**, not trusted to every call site.
+  "Never log a token" holds until the one time somebody logs the whole
+  request object, and by then it is in the log store.
+- No secrets, no PII, no full request bodies.
+- One line per request, at completion, where status and duration are known.
+  Logging on the way in as well doubles the volume and answers nothing.
+- Never log inside a hot loop.
+- Every line carries the release and environment, so a log and an error
+  report line up against the same deploy.
+
+## Health is two endpoints, not one
+
+- **`/health`** — liveness. The process is up. Cheap, no dependencies.
+- **`/ready`** — readiness. Every dependency this service cannot serve
+  without is reachable. Answers 503, naming the one that failed.
+
+The platform's healthcheck points at **readiness**. On Railway the previous
+deployment keeps serving until the new one answers 200, so a readiness probe
+that returns 200 while the database is unreachable does not merely mislead a
+dashboard — it promotes a broken release.
+
+That makes readiness load-bearing infrastructure. Anything missing from the
+checks map is a dependency that can be broken while a release is promoted
+anyway.
+
+**A readiness check that cannot fail is worse than none.** There is a test
+that makes it fail; if you add a dependency, add its probe and its failing
+test in the same change.
+
+## Releasing
+
+There is no percentage canary on Railway. What protects a release is:
+
+1. the healthcheck gating promotion,
+2. a smoke test against the real URL afterwards, and
+3. putting the last good commit back when that fails.
+
+Rollback is the same path as a normal deploy, deliberately — an untested
+recovery path is not a recovery path. The `last-good-deploy` tag moves only
+after the smoke passes, so it always names a release observed working rather
+than one that merely deployed.
+
+Confidence comes from being able to undo, not from being sure.
+
+## Feature flags
+
+A risky change ships dark and is turned off in seconds without a deploy.
+
+The flag exists to protect the service, so a lookup must never be able to
+take it down: bounded by a timeout, failures reported and answered with the
+flag's own fallback rather than thrown into a handler. For a kill switch the
+fallback is **false** — if we cannot ask whether a risky path is allowed, the
+answer is no.
+
+Flags live in one typed registry. A string literal at a call site is how they
+rot: the flag is deleted, the call still compiles, and nobody finds out until
+the behaviour quietly changes.
+
+## Defaults
+
+Sentry for error monitoring, `pino` for structured logging in Node. Both
+are defaults, not mandates — substitute freely. What is **not** optional is
+that the capability exists and is wired before release.
+
+Configure the provider in `.orchestra/config.yml` under `observability`.
+
+`observability.require_before_release` (true by default) is checked by lead
+at milestone completion. Setting it false defers the requirement — it does
+not remove it.

package/template/rules/performance.orchestra.md

@@ -0,0 +1,186 @@
+# Performance
+
+Performance is a property of the code as it is written, not a phase that
+happens later. A task whose acceptance criteria say nothing about it still has
+to meet what is below — the same way security and accessibility apply without
+being restated per task.
+
+Nothing here names a framework. What is fast on one platform is irrelevant on
+another, and a rule that enumerates today's libraries is wrong within a year.
+**Decide what applies from the code in front of you**, and reach for the
+platform's own skill when you need depth.
+
+## Measure before claiming
+
+The rule that outranks the rest of this file: **do not assert a performance
+win you have not measured.**
+
+An optimisation with no before-and-after is a guess that made the code harder
+to read. State what was measured, what was assumed, and the numbers. When you
+cannot measure, say *unmeasured* — that is the honest word, and
+`.claude/rules/observability.orchestra.md` asks for it everywhere else too.
+
+Two failures, and the second is the common one:
+
+- optimising something that was never slow
+- *making it slower* while believing otherwise, because the cheap-looking
+  change added work on a path that runs more often than the one it saved
+
+## Scale is the only question worth asking first
+
+Before anything else: **how does this behave when the input grows?**
+
+Everything is fast at n=10. The defect that matters is the one that is
+invisible in development and fatal in production — and it is almost always
+one of three shapes:
+
+| Shape | Looks like |
+|---|---|
+| Work inside a loop that should have happened once | a query, a request, a file read, a compile, a sort |
+| Complexity that is one order worse than it needs to be | a nested scan where a lookup table would do |
+| Unbounded input | no limit, no pagination, no size cap, no timeout |
+
+The first is the same defect whether the loop calls a database, an HTTP API,
+the filesystem, or a native bridge. Naming it "N+1" is a database habit; the
+pattern is general.
+
+The third is the one that turns into an incident rather than a slow page.
+Anything that accepts input from outside states its bound.
+
+## Do the work once
+
+Batch, cache, precompute, reuse. In that order of preference, because each
+step down adds a thing that can be stale.
+
+A cache with no stated lifetime and no invalidation path is a correctness bug
+scheduled for later. Say how long it lives and what clears it, next to it.
+
+## Do not pay for what you do not use
+
+- Load it when it is needed, not at startup — code, data, connections,
+  images, permissions.
+- Send the fields the caller asked for.
+- Release what you hold. A subscription, a listener, a timer or a connection
+  that outlives its owner is a leak, and leaks read as "gets slower the longer
+  it runs" rather than as an error.
+
+## Memory is a question of lifetime, not of size
+
+Every platform this system builds for has a collector — a tracing GC on the
+JVM, V8 and Hermes, reference counting on Apple platforms. A collector frees
+what is unreachable. So on a managed platform **a leak is never lost memory;
+it is a reference that outlived its purpose** — a listener on a global, a
+closure held in a long-lived map, a cache with no bound, a child holding its
+parent, a timer nobody cleared. The collector cannot fix any of those,
+because by its definition they are not garbage.
+
+The tell is the axis the growth follows. Memory proportional to **load** is
+a size problem — bound the input, stream, page. Memory proportional to
+**uptime** is a leak, and it arrives as "gets slower the longer it runs,"
+then as an out-of-memory in the one process that stayed up over the weekend.
+
+**Whoever starts a lifetime ends it, in the same place.** A subscription, a
+listener, a timer, a connection, a task: the code that creates it is the
+code that names where it stops — the effect's cleanup, the `deinit`, the
+scope's cancellation. A lifetime with no stated end is a leak with a delay.
+
+**Allocation is deferred, not free.** A collector turns an allocation into a
+later pause, and where the budget is a frame or a request, the pause lands
+inside it. An object, closure or array created per frame, per row, or per
+request is the shape to look for — it reads as ordinary code and is paid
+for on the path that runs most often. Hoist it, reuse it, or make it a value
+type.
+
+**Test for it where the platform lets you.** A `deinit` that must fire, a
+leak detector in the debug build, a heap that is the same size after ten
+thousand iterations as after ten. A leak found in review is luck; one found
+by a test is a rule.
+
+## Data and I/O, wherever the work is served
+
+The tier most likely to fail at scale, and the one where the failure arrives
+as an outage rather than as a slow screen.
+
+- **One round trip, not one per row.** Fetch the set, join it, or batch it. A
+  loop that awaits is the shape to look for — it reads as ordinary code and
+  costs a full round trip per iteration.
+- **Index what is filtered, joined and sorted on.** An index nobody measured
+  is a write cost with no read benefit, so check the query plan rather than
+  adding one by reflex.
+- **Ask for the columns you use.** Selecting everything moves data you throw
+  away, through the driver, the network and the serialiser.
+- **Every list endpoint has a hard maximum**, not just a default. A caller
+  passing a large enough page size is the same outage as no limit at all.
+- **Every outbound call has a timeout**, and every pool has a ceiling. A
+  dependency that hangs should fail your request, not exhaust your process.
+- **Stream what is large.** Buffering a response into memory to send it makes
+  the peak proportional to the biggest caller.
+- **Keep slow work off the path that answers.** Hashing, image work, report
+  building and anything unbounded belong in a job, not in a request.
+
+Where the runtime is single-threaded, a synchronous call on a request path
+stops every other request, not just this one. Blocking work there is a defect
+even when it is fast in isolation.
+
+## Rendering and interaction, wherever the UI runs
+
+The words differ per platform; the constraints do not.
+
+- **Re-render only what changed.** Anything drawn inside a list or under a
+  frequently-changing parent is the thing to look at, and allocating a new
+  object or closure per frame defeats whatever memoization sits above it.
+- **Identity, not position.** A list keyed by index reuses the wrong element
+  with the wrong state when the list reorders. That is a correctness bug that
+  merely looks like a performance one.
+- **Long lists are windowed.** Rendering ten thousand rows to show twelve is
+  the same waste on every platform.
+- **Never block the thread that draws.** Move parsing, crypto, image work and
+  large loops off it.
+
+## The shipped size is a budget
+
+Whatever the user downloads or installs has a number, and the number only goes
+down. `.claude/rules/testing-standards.orchestra.md` holds the ratchet: it may
+fall and may not rise, and deliberate growth is re-recorded in its own commit
+so it is a decision rather than a drift.
+
+## What is enforced
+
+Only what can be decided precisely. Complexity, cache lifetime, index choice
+and unbounded input all matter more than the four below and none of them is
+mechanically decidable — a gate that cries wolf is a gate people learn to
+override, so they stay review items above.
+
+| Check | Fails on |
+|---|---|
+| `await-in-loop` | a round trip per iteration |
+| `array-index-key` | a list keyed by position |
+| `inline-style-object` | an object allocated in a component kit's render |
+| `unmemoized-kit-component` | a kit component memoizing nothing, where the toolchain is not doing it for you |
+| `effect-without-cleanup` | a React effect that subscribes, listens or schedules and returns no cleanup |
+
+These five are concrete because the stacks this system scaffolds are concrete.
+They are the floor, not the definition of performance work.
+
+`effect-without-cleanup` sees a lifetime start with no stated end — the
+memory rule above, in the one place a script can see it. An effect that
+genuinely needs none says so in a comment, and the check reads it.
+
+`await-in-loop` has an escape hatch, because sequential really is the answer
+sometimes — an ordered write, a rate limit, a cursor that depends on the
+previous page. A comment above the loop saying which one it is clears the
+check. Nothing else does: `Promise.all` over the batch is the fix in every
+other case.
+
+**Read the toolchain before applying the third.** React 19's compiler
+memoizes automatically, so on a project with `reactCompiler` enabled,
+hand-written `memo` is redundant noise and the check stays silent. Whether it
+is on is a fact to read from the project, never recalled — the same discipline
+as a library version.
+
+## Depth
+
+`.claude/skills/code-optimizer/SKILL.md` is for optimising code that already
+exists. `.claude/skills/core-web-vitals/SKILL.md` is web-specific. Neither
+covers writing something performant the first time, which is what this rule is
+for.

package/template/rules/phase-limits.orchestra.md

@@ -0,0 +1,3 @@
+# Phase Limits
+
+**Scope guard:** Working on something NOT in phase acceptance criteria → STOP. Note in context.md, don't implement.