agentic-team 0.0.0-stage → 6.2.0

package/template/rules/observability.orchestra.md

@@ -0,0 +1,121 @@
+# 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`.
+
+<!-- platforms: backend -->
+## 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.
+
+<!-- platforms: backend -->
+## 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.
+
+<!-- platforms: backend -->
+## 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,190 @@
+# 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.
+
+<!-- platforms: web, expo, ios, android -->
+## 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.
+
+<!-- platforms: web -->
+## 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.
+
+<!-- platforms: web, expo, backend -->
+## 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, and installed
+only for web. 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. Name it in your result's notes, don't implement; lead records it with `.orchestra/scripts/context.mjs journal`.

package/template/rules/pull-request.orchestra.md

@@ -0,0 +1,218 @@
+---
+paths:
+  - ".github/**"
+---
+
+# Pull Requests
+
+**One task, one PR.** Always — there is no mode in which work reaches the
+user any other way.
+
+One per milestone is the failure this rule exists to prevent, and it happened
+anyway: the diff spans every phase, no reviewer can hold it, and the design
+table has one row while the milestone has ten screens — so the screenshots get
+dropped and nobody notices. A PR is one task, one commit, one screen.
+
+## Body
+
+Use the repo's PR template. Keep it short — the reader wants to know what
+changed and whether it is safe, not how you got there.
+
+- **What** — one or two sentences
+- **Why** — link the milestone or task
+- **Design** — required for any UI change: expected and implemented, side by
+  side, in the template's table. Any deliberate difference is stated with
+  its reason. "Close enough" is not a reason.
+
+  One PR is one task is one screen, so the table has one row and an empty
+  cell has no excuse. The implemented image is the task's `design_capture`,
+  committed under `designs/.captures/` **in this branch** — `gh` cannot
+  upload an image, so a screenshot outside the branch cannot appear here. If
+  it could not be captured, the cell carries the reason. An empty cell reads
+  as a pass nobody observed.
+- **Verification** — the checklist, actually checked
+
+Do not paste the diff into the description. Do not narrate your process.
+Do not paste the acceptance criteria. Read the body back as the colleague
+who will review it: a table of files, a `path:line`, a list of what was
+checked — those came from a tool, and the reader wanted a person.
+
+## Mechanism
+
+The `gh` CLI. Check it before relying on it:
+
+```bash
+gh auth status   # not authenticated → stop and tell the user, do not work around it
+```
+
+Open with a body file, never an inline string — the body contains newlines,
+a table, and backticks:
+
+```bash
+gh pr create --base <delivery.base_branch> --title "#<task-id> - <subject>" --body-file .git/PR_BODY.md
+```
+
+## Naming
+
+| | Shape | Example |
+|---|---|---|
+| Branch | `<git-user>/<task-id>-<slug>` | `sulhadin/123-add-login` |
+| PR title | `#<task-id> - <subject>` | `#123 - Add login` |
+
+The id goes in both so the board finds the work without anyone pasting a link,
+and it is the tracker's own id — a GitHub issue number or a ClickUp task id. With `tracker.provider: none` there is no id, so the branch drops
+that segment and the title is the subject alone.
+
+**The title is not conventional-commit form**, and that is deliberate. A task
+PR accumulates commits — the implementation, then whatever review asked for —
+and each of those *is* conventional. The squash collapses them, and its
+subject is the one place the board's id has to appear.
+
+That squashed subject still passes the scaffolded `commit-msg` hook, which
+accepts `#<task-id> - <subject>` alongside the conventional form for exactly
+this case. Without that, the delivery flow would produce the one commit the
+repo's own gate rejects.
+
+Record the returned URL. Lead reports it and stores it in the phase's note (`context.mjs phase … "pr: <url>"`), so a
+later session can find the PR without searching.
+
+Reading the change is `gh pr diff <n>`, and a diff read straight into
+context spends four lines per file on the `diff --git`/`index`/`---`/`+++`
+header. Pipe it — or any `git diff` / `git show` — through
+`.orchestra/scripts/compact-diff.awk`; it replaces those four with one and
+touches nothing else, so every hunk line comes through as git wrote it.
+
+Reading review feedback is also `gh`, and it is two different calls — a
+review body and inline line comments are separate objects, and reading only
+one loses half the feedback:
+
+```bash
+gh pr view <n> --json reviews,comments
+gh api repos/{owner}/{repo}/pulls/<n>/comments
+```
+
+Never poll in a loop. Fetch when the user says the review is ready.
+
+## Review cycle
+
+The review happens **on the pull request**, not in a file beside it. Findings
+land inline, on the line they are about, and the engineer answers them on the
+thread. Nothing about the conversation lives only on somebody's disk.
+
+The loop is: reviewer comments → a fresh engineer with the phase's identity
+fixes, replies and resolves → re-review. Max rounds is `thresholds.stuck_retry_limit`,
+counted by `.claude/hooks/review-rounds.sh`. On exhaustion the user decides
+whether another round is worth it — say what is still open rather than going
+round again.
+
+**An engineer answers, not lead.** It reads the code, the diff and the thread
+before it replies. A thread answered from a summary is a thread answered
+wrong. It is a new engineer each round rather than the one that wrote the
+code, because a resumed agent re-reads its whole history on every call.
+
+### Posting the review — one call, every finding
+
+```bash
+cat > .git/REVIEW.json <<'JSON'
+{
+  "event": "COMMENT",
+  "body": "changes-requested — two or three sentences",
+  "comments": [
+    { "path": "src/auth/session.ts", "line": 42, "side": "RIGHT",
+      "body": "[blocking] The session id is compared with ===, which is not constant time.\n\nUse `crypto.timingSafeEqual` over the two buffers." }
+  ]
+}
+JSON
+gh api repos/{owner}/{repo}/pulls/<n>/reviews --input .git/REVIEW.json
+```
+
+One review, not one call per finding — each separate call is a separate
+notification.
+
+**`COMMENT`, never `APPROVE` or `REQUEST_CHANGES`.** The same account authored
+the pull request and GitHub refuses to let an author approve their own.
+
+So the verdict travels as a **label**, which is the part GitHub will let the
+author set and the part everything else can read — the board, a filter, a
+human scanning the list, and the next agent.
+
+| Label | Means |
+|---|---|
+| `review:changes-requested` | unresolved findings; the engineer is up |
+| `review:approved` | nothing blocking; the task can move on |
+
+```bash
+# once per repo, idempotent — the scaffold does this
+gh label create review:changes-requested -c D93F0B -d "Reviewer found blocking issues" -f
+gh label create review:approved          -c 0E8A16 -d "Reviewer found nothing blocking" -f
+
+# one state at a time, so the two can never both be on
+gh pr edit <n> --add-label review:changes-requested --remove-label review:approved
+```
+
+The label is the handshake between reviewer and engineer, and it is what lead
+reads to decide the next move. The review body still carries the summary, but
+a body has to be parsed and a label does not — and a run that dies between
+rounds can pick up exactly where it left off by asking the pull request what
+state it is in.
+
+Every inline comment names the problem in a sentence and says what to do
+instead. A comment that only objects makes the next agent guess.
+
+### Reading the threads
+
+REST returns comments; only GraphQL carries the thread id and whether it is
+resolved, and both are needed to answer one.
+
+```bash
+gh api graphql -f query='
+  query($o:String!,$r:String!,$n:Int!) {
+    repository(owner:$o, name:$r) { pullRequest(number:$n) {
+      reviewThreads(first:50) { nodes {
+        id isResolved path line
+        comments(first:20) { nodes { body author { login } } }
+      } } } } }' -f o={owner} -f r={repo} -F n=<n>
+```
+
+### Answering and resolving
+
+Reply on the thread, then resolve it. A few words on what was done and the
+commit id — the diff says the rest.
+
+```bash
+gh api graphql -f query='
+  mutation($t:ID!, $b:String!) {
+    addPullRequestReviewThreadReply(input:{pullRequestReviewThreadId:$t, body:$b}) {
+      comment { id } } }' -f t=<thread-id> -f b="Fixed with timingSafeEqual — a1b2c3d"
+
+gh api graphql -f query='
+  mutation($t:ID!) {
+    resolveReviewThread(input:{threadId:$t}) { thread { isResolved } } }' -f t=<thread-id>
+```
+
+Resolve only what you actually addressed. A thread resolved without a fix is
+worse than one left open, because the next reader believes it.
+
+If you did something other than what was asked, say why in the reply. If you
+disagree, say so and leave the thread open — resolving a disagreement is not
+answering it.
+
+Never poll in a loop. A human review is fetched when the user says it is
+ready.
+
+## Who merges
+
+Decided by the `--auto` flag on `/orchestra:start`, and by nothing else.
+
+| | Who merges | What follows |
+|---|---|---|
+| normal | **the human**, squashing | lead waits; a task whose `depends_on` is unmerged does not start |
+| `--auto` | lead, squash-merging | commit link posted on the tracker task, status moved, branch deleted |
+
+Outside `--auto`, **never merge your own PR unless explicitly told to.**
+
+**Never stack a branch on an unmerged branch** to avoid waiting. The human
+squashes, so the parent's commits reappear in the child's diff until it is
+rebased, and an agent doing that on every task will get it wrong. Waiting is
+the honest cost of reviewing per task — say what is open and what is blocked
+rather than stalling silently.

package/template/rules/role-boundaries.orchestra.md

@@ -0,0 +1,132 @@
+---
+paths:
+  - ".orchestra/**"
+  - ".claude/**"
+  - "CLAUDE.md"
+---
+
+# Role Boundary Enforcement
+
+Before writing ANY file, check your role's ownership scope.
+
+## Ownership Map
+
+| Role | Can Write | Everything Else |
+|------|-----------|----------------|
+| Orchestrator | `.orchestra/roles/`, `.orchestra/config.yml`, `.orchestra/README.md`, `.orchestra/blueprints/`, `.orchestra/stacks/`, `.orchestra/trackers/`, `.orchestra/scripts/`, `.claude/agents/`, `.claude/hooks/`, `.claude/rules/*.orchestra.md`, `.claude/skills/*/SKILL.md`, `.claude/commands/orchestra/`, `CLAUDE.md`, `docs/` | Refuse |
+| PM | `.orchestra/milestones/*` (prd, milestone, grooming, phases) | Refuse |
+| Lead | `.orchestra/milestones/*/{context,decisions,journal}.md`, through `.orchestra/scripts/context.mjs` | Refuse |
+| Scaffolder | `.orchestra/config.yml` (verification, tracker, observability, `delivery.base_branch`, `project.platforms` keys only), scaffolded app files, repo config | Refuse |
+| Tracker | Tracker id frontmatter in `.orchestra/milestones/*` | Refuse |
+| Sub-agents | Only what phase `## Scope` defines | Refuse |
+| Reviewer | Review verdict in phase file only | Refuse |
+
+Some entries on the Orchestrator's list are **not** blocked by the hook below,
+each for its own reason. `.orchestra/blueprints/` is where `/orchestra
+blueprint` writes, `.orchestra/config.yml` is merged rather than overwritten,
+and `CLAUDE.md` keeps everything outside the orchestra section for the user —
+the installer preserves all three on upgrade, so an edit there is not lost
+work. `docs/` is not installed into a project at all; it is this repo's own
+documentation, so in an installed copy there is nothing under that name to
+protect and blocking it would only block the user's own docs.
+
+They stay on the ownership map because a role should still not reach into
+them. They are simply not things a hook can decide.
+
+## Enforced, not asked for
+
+Three `PreToolUse` hooks. The first blocks Write and Edit against installed
+system files. The second holds a session inside the role it declared. The
+third caps review rounds per phase.
+
+### The system-file hook
+
+Two questions decide it, and neither is "which role is running": a slash
+command is a markdown prompt and cannot export anything a hook could read on
+its own, so a guard built only on the role would never fire.
+
+**Which repo is this?** In the agentic-team repo these files are source, and
+the hook allows everything. Elsewhere they are build output.
+
+**Did Orchestra put this file here?** `.orchestra/.installed.json` records
+every file the installer wrote, and the hook blocks exactly that list.
+
+The manifest exists because the answer stopped being guessable. Rules carry a
+`.orchestra.md` suffix, so a system rule can be told from one you wrote.
+Skills lost that marker when they became directories, and a list of globs
+cannot tell a shipped skill from yours — so it blocked both, including the
+extension point `docs/skills.md` tells you to use, and including a stack's
+own `apps/<name>/.claude/` pack. The upgrade had the same blindness from the
+other side: a skill this project stops shipping looked like one you wrote, and
+survived forever. The manifest answers both, and retires what a new version no
+longer ships.
+
+**`.orchestra/config.yml` is never blocked.** It is merged on upgrade rather
+than overwritten, so an edit survives — and `/orchestra:setup` writes its
+verification keys, which `.orchestra/README.md` has always documented as an
+exception the hook did not implement.
+
+Neither are `.orchestra/milestones/`, `blueprints/`, roles you create, or
+skills and rules you write: none of them is in the manifest, because the
+installer preserves them.
+
+When it blocks: make the change in the agentic-team repo and reinstall, or —
+if it is genuinely project-specific — put it in the app's own `CLAUDE.md`, a
+project skill of your own, or `config.yml`, none of which is overwritten.
+
+### The role hook
+
+The ownership map above was prose, and a PM opened a pull request. So the
+role is now something a hook can read: each role command has the agent run
+one Bash line — `true # orchestra-role=product-manager` — and the hook, which
+sees every Bash call together with the session id Claude Code passes it,
+records the pair under `.orchestra/.sessions/`. Every later call in that
+session is judged against it. Two terminals are two sessions; the PM's marker
+never touches lead.
+
+What it refuses for the PM: a Write or Edit outside `.orchestra/milestones/`;
+`gh pr` in any form; a new branch; merge, rebase, cherry-pick, a hard reset,
+a force push; `git commit -a`; `git add` of anything but milestone files;
+any `Agent` launch other than `milestone-reviewer` and `tracker`; any
+`Workflow`; and a ClickUp task write carrying a status other than the
+backlog one. The last three came from one afternoon: the word "ultracode" in
+a message told the platform to use the Workflow tool, and a PM whose role
+said "cannot review code" ran a multi-agent code review, recommended itself
+for it, and opened the task straight into `in progress`.
+
+Lead is held to one rule: phase work starts inside a milestone agent. An
+`engineer-*`, `reviewer` or `re-reviewer` launched from the lead session
+itself is refused; one launched by a milestone agent passes, because a call
+from a sub-agent carries `agent_id` and one from the session does not —
+verified against a live payload. A hotfix engineer whose prompt starts with
+`Hotfix:` passes. One run kept two milestones in the lead session and grew
+to 738 calls and a 925k-token context. Sub-agents share the session id, so
+the role marker reaches them; lead's own sub-agents still write code, which
+is why nothing else is restricted. The Orchestrator is recorded and not
+restricted.
+
+Two things are structural rather than hook-judged, because they do not
+depend on the role. `Workflow` is denied in the project's `settings.json`;
+no role runs one. The reviewer, the re-reviewer and the milestone reviewer carry
+`disallowedTools: [Write, Edit, NotebookEdit]` in their frontmatter; they
+review, and Claude Code removes the tools rather than asking them not to.
+
+No marker means no role, and nothing is refused. That is discussion mode.
+
+When it blocks, the message says why. Say so to the user and stop; the
+answer is never to find a command the pattern does not match.
+
+### The review-round hook
+
+`.claude/hooks/review-rounds.sh` counts reviewer launches per phase, from the
+`Phase:` line lead puts in every reviewer prompt, in
+`.orchestra/.sessions/review-rounds.json`. Past `thresholds.stuck_retry_limit`
+it refuses the launch until the prompt quotes the user's approval. The cap
+was prose, and a run read "loop until clean" as overriding it.
+
+## Rules
+
+- Check what file you'd write to, not what the user said
+- If user insists → still refuse: "Outside my scope as {role}. Use /orchestra:{command}."
+- Discussion mode (no role) → no restrictions
+- Reading → always allowed