@remits/remits-cli 0.1.114 → 0.1.115

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remits/remits-cli",
-  "version": "0.1.114",
+  "version": "0.1.115",
   "description": "Local CLI for auth, component sync, and live test execution against Remits",
   "license": "MIT",
   "private": false,

package/skills/remits-cli/SKILL.md

@@ -76,11 +76,20 @@ reference named after it.
 - **Ask which world your checkout resolves before you run anything:** `remits-cli components status`.
   A trunk checkout and a variant-branch checkout differ on both ends of the loop — what a run resolves
   and what a sync writes. Do not infer it from the branch name. (`branch-variants.md`)
+- **Start from a steady git baseline before the first edit.** Run `git fetch origin`; confirm
+  `git log origin/<branch>..<branch>` and `git log <branch>..origin/<branch>` are both empty; then run
+  `remits-cli components status`. On a variant branch also run `remits-cli components promotion --branch
+  <branch>`. A workspace isolates staging, not the commit your files are based on. (`development-loop.md`,
+  `branch-variants.md`)
 - **Resolution order is staged → variant → trunk, and each layers over the one beneath.** A populated
   staging cache makes a committed variant look broken through any tokenized entry point; clear it before
   verifying variant resolution. (`component-resolution.md`)
 - **Host and data mode are two independent decisions.** `--base-url` picks the Remits host,
   `--data-mode` picks the data segment on it. Neither implies the other. (`command-reference.md`)
+- **`test run` ignores the stored session data lane.** It defaults to `test` even when `whoami` shows
+  the session parked on prod; production Test runs require explicit prod provenance (`--data-mode prod`)
+  or Test source declaring `dataMode 'prod'` / `[dataMode:'prod']`. Check returned `dataModeSource`
+  when auditing a run. (`command-reference.md`)
 - **A tool's `dataMode` input never widens the lane.** It may narrow `prod` → `test`, never escalate
   `test` → `prod`. The response's `dataMode` is the truth, not your input. To reach prod data, pass
   `--data-mode prod` on the command line. (`account-targeting.md`)
@@ -95,6 +104,10 @@ reference named after it.
   component (preferred, because it becomes regression protection) or a browser flow through
   `remits-cli token`. "Just do it" and "that's fine, commit it" are not evidence. If you genuinely
   cannot verify, say what you would need and ask. (`development-loop.md`)
+- **Read the component's `.meta.yml` before changing behavior.** Sidecar descriptions can be dated
+  decision records. Before changing a displayed value, helper, calculation, schema field, or prompt
+  contract, check the sidecar and either preserve its decision or explicitly supersede it.
+  (`development-loop.md`)
 - **Read the account's `resolution` block before acting on it** — `role`, `type`,
   `resolvedDatabaseName`, `relationships`. More than one relationship means the account can legitimately
   resolve differently depending on the path a request travelled. Never infer an account's shape from its
@@ -111,6 +124,12 @@ reference named after it.
 - **Reading and investigating are parallel-safe; editing one account's repository is exclusive**, via a
   lease. A refusal is not an error — carry on read-only and hand off with `ticket progress --next-step`.
   Never wait or poll for a lease. (`support-tickets.md`)
+- **A brief's `## Rules you will be held to` section is ENFORCED, not requested.** The platform refuses
+  the verb and the message says what to do instead — act on that sentence rather than retrying or
+  looking for another door. A `[require]` rule needs a person; hand off. (`support-tickets.md`)
+- **`components commit` takes a short landing lease on `(account, branch)`.** Refused means somebody else
+  is landing right now — keep staging and iterating, which is lane-isolated, and retry in a minute.
+  Never loop on it. (`development-loop.md`)
 - **If something looks wrong, stop — do not paper over it.** Unexpected deletes, creates, renames,
   uniqueness errors, id drift, or a 500 from the platform: stop, preserve the session log and tool
   responses, and escalate. Never create replacement components to make ids line up, and never discover
@@ -139,7 +158,11 @@ repo's `account-info.json`. `cli-state.md` maps every remaining question to its
 
 Keep support and development sessions lean:
 
-- Prefer local repo files over remote tools whenever the target account repo exists locally.
+- Prefer local repo files over remote component tools whenever the target account repo exists locally.
+  `mcp_component_view` / `mcp_component_grep` are fallback surfaces for agents without that checkout,
+  or for confirming what the live DB has stored after you already understand the files. For a ticket
+  with `implementationAccountId`, resolve that account's indexed repo first, pull the appropriate
+  branch when the checkout is clean, and inspect `account-info.json` + `components/` there.
 - Do not read entire `.remits-cli/sessions/*.jsonl` or large tool response files unless you first narrow
   to the relevant request, endpoint, tool, or ticket.
 - Prefer targeted Firestore queries: use `documentId`, tight `filters`, narrow `fields`, and low `limit`

package/skills/remits-cli/references/account-targeting.md

@@ -53,9 +53,18 @@ Two more, easily confused: top-level **`componentBranches`** lists the variant b
 
 ### Repo selection rules
 
-- **Inside the target implementation repo**: read `account-info.json` and inspect `components/` directly.
-- **Inside one repo but supporting a different account**: switch to that account's repo if it exists;
-  otherwise use `mcp_account_view` / `mcp_component_view` / `mcp_component_grep`.
+- **Inside the target implementation repo**: make sure you are on the relevant branch and the checkout is
+  current before reading source or editing. Run `git fetch origin`; when the tree is clean,
+  `git pull --ff-only origin <branch>`; then confirm `git log origin/<branch>..<branch>` and
+  `git log <branch>..origin/<branch>` are both empty. A worktree can have an isolated staging workspace
+  and still be based on a stale commit. Then read `account-info.json` and inspect `components/` directly.
+- **Inside one repo but supporting a different account**: switch to that account's indexed repo if it
+  exists. For tickets, prefer `implementationAccountId` / `implementationAccountName` over the reporting
+  `accountId` when choosing that repo; a subscriber or client often reports the symptom while the
+  implementation lives in an upstream `PLATFORM` / `PRODUCT` repo.
+- **Only use `mcp_component_view` / `mcp_component_grep` when the correct repo is not available locally,**
+  or when you are deliberately comparing local source to the live DB after reading the files. They are not
+  the normal way to learn source on a machine with the account repo.
 - **Outside any repo**: rely on the tools, and `mcp_get_guide` for the front-stage guides.
 - **Never create a new local repo/directory just because a ticket references an account name.** Resolve the
   account type and parent hierarchy first, and work only from an existing indexed repo unless the user

package/skills/remits-cli/references/agent-sessions.md

@@ -68,7 +68,7 @@ capacity. For each new ticket it launches a headless worker:
 
 | | headless invocation | edit mode | investigate mode |
 |---|---|---|---|
-| `codex` | `codex exec --cd <repo>` | `--sandbox workspace-write` | `--sandbox read-only` |
+| `codex` | `codex exec --cd <repo>` | `--sandbox workspace-write` | `workspace-write with investigation-only brief and no edit lease` |
 | `claude` | `claude -p --add-dir <repo>` | `--permission-mode acceptEdits` | `--permission-mode plan` |
 | `gemini` | `gemini -p` in `<repo>` | `--approval-mode auto_edit` | `--approval-mode plan` |
 
@@ -83,6 +83,9 @@ and the worker are one answer, not two.
 The brief always arrives on **stdin**, never in argv — it is a page of prose and argv has a hard
 length limit, so an argv brief would fail on exactly the detailed tickets that most need the detail.
 The brief itself is generated by the platform, so all three worker types are told the same thing.
+In `--mode investigate`, the supervisor still claims tickets and may update them with findings, but it
+does **not** acquire or renew the repository edit lease. The brief says the run was launched for
+investigation only and forbids file edits, component staging, commits, and manual lease escalation.
 
 **Following a run.** `remits-cli start`'s control center lists every worker; **Follow live** streams
 that run's transcript into the page, rendering commands with their exit codes, file edits, and the
@@ -162,6 +165,7 @@ and holds a PID lock (`~/.remits-cli/listener.pid`) so only one runs per machine
 
 The control center shows, in one browser view:
 - which agent sessions are registered, what each is doing right now, and its recent activity
+- live and recent worker runs, with historical transcript follow/stop controls keyed to the exact run
 - the open support-ticket queue, and which agent each ticket is routed to
 - a control to route a ticket at a specific available agent
 - websocket connection and topic health

package/skills/remits-cli/references/branch-variants.md

@@ -81,6 +81,22 @@ checkout and 15/15 from trunk, with no code difference.) **Run branch-variant su
 - **Nothing is renamed.** A variant sync never renames files and never repoints the account's trunk
   branch. A `new_*` file stays `new_*`.
 
+**Start from a current branch, not just an isolated workspace.** Before the first edit in a variant
+checkout:
+
+```bash
+git fetch origin
+git status --porcelain
+git log origin/<branch>..<branch>              # must be empty: nothing local-only
+git log <branch>..origin/<branch>              # must be empty: not behind the remote
+remits-cli components promotion --branch <branch>
+```
+
+`components promotion` reads the remote and reports whether the branch is also current with trunk. If it
+says `diverged` or `STALE`, merge trunk in or sync first, as instructed, before writing new work. A
+workspace lane prevents another agent from overwriting your staged Redis snapshot; it does not say which
+commit your files are based on.
+
 **Branch-local `account-info.json` can describe a subscriber.** On a variant branch the repository is
 still the OWNER's component repo — files overlay that owner's trunk ids and sync writes overlays owned by
 that owner. But when the checkout was synced from a subscribing account reached through an
@@ -193,7 +209,10 @@ resolution on production/subscription semantics. Do **not** use this pattern wit
 ### The SDLC is identical on a variant branch
 
 ```bash
-git checkout feature_branch          # or: git checkout -b feature_branch
+git fetch origin
+git checkout feature_branch
+git pull --ff-only origin feature_branch
+remits-cli components promotion --branch feature_branch
 # edit components/actions/50_ExtractInvoice.groovy   (KEEP the trunk id)
 remits-cli components stage          # Redis, scoped to this branch — same as always
 remits-cli test run --test "Invoice Tests"                    # the feature_branch world

package/skills/remits-cli/references/command-reference.md

@@ -158,7 +158,7 @@ remits-cli data-mode set test         # Switch back to test for development
 remits-cli auth [--base-url URL] [--account-id ID] [--data-mode test|prod]
 remits-cli sessions [list|remove] [--account-id ID]
 remits-cli config [set] [--agent claude|codex|gemini]
-remits-cli agent serve [--worker-agent claude|codex|gemini] [--max-concurrent N] [--mode edit|investigate] [--label NAME] [--data-mode test|prod]
+remits-cli agent serve [--worker-agent claude|codex|gemini] [--max-concurrent N] [--mode edit|investigate] [--serves a,b] [--label NAME] [--data-mode test|prod]
 remits-cli agent workers [--json]
 remits-cli agent register [--label NAME] [--data-mode test|prod] [--account-id ID] [--max-concurrent N]
 remits-cli agent work [--wait SECONDS] [--json]
@@ -181,7 +181,7 @@ remits-cli ticket artifact --ticket ID --type TYPE --label "..." [--url U | --co
 remits-cli ticket participant --ticket ID --email E [--role watcher|requester|agent]
 remits-cli ticket field --ticket ID --key K --value V  # the ORGANIZATION's own field, outside the planning slots
 remits-cli ticket reclaim [--ticket ID | --account-id ID] [--stale-hours 24] [--apply]   # OPERATOR: take back an agent's abandoned ticket
-remits-cli ticket queue --account-id ID [--status ...] [--unrouted] [--unassigned] [--awaiting-response] [--workstream W] [--board-stage S] [--planned-in P] [--search "..."] [--sort-by ...] [--json]
+remits-cli ticket queue --account-id ID [--status ...] [--unrouted] [--unassigned] [--awaiting-response] [--min-runs N] [--workstream W] [--board-stage S] [--planned-in P] [--search "..."] [--sort-by ...] [--json]
 remits-cli ticket create --account-id ID --subject "..." --type defect|question|task|incident|enhancement [--priority P] [--description "..."] [--tags a,b] [--workstream W] [--affected-component C] [--implementation-account-id ID] [--reference-id KEY]
 remits-cli start [--foreground true] [--port 8787]
 remits-cli stop
@@ -211,7 +211,9 @@ remits-cli tool status --call-id <callId> [--data-mode test|prod]
 ```
 
 For tests specifically:
-- If `--data-mode` is omitted, `remits-cli test run` uses `test`.
+- If `--data-mode` is omitted, `remits-cli test run` uses `test` and sends `dataModeSource:"cliDefault"`.
+  An explicit `--data-mode prod` sends `dataModeSource:"explicitFlag"` so production test runs are
+  auditable from the server status payload even when the original terminal history is gone.
 - `--names` is `|`-delimited (a comma still splits a single value) and may be repeated; an unmatched
   selector fails the run instead of reporting zero cases as success.
 - `--as-account <ID>` runs AS a descendant subscriber so its edge selects the component branch

package/skills/remits-cli/references/component-integrity.md

@@ -135,9 +135,14 @@ file is catastrophic.
   variant branch the id/delete/renumber checks below apply to the **overlay set** instead: confirm every
   component absent from the branch is *meant* to be tombstoned for subscribers.
 - The user intends durable platform promotion now — not just local edits, staging, or verification.
+- `git fetch origin` has run, and this checkout matches the remote branch the platform will sync:
+  `git log origin/<branch>..<branch>` and `git log <branch>..origin/<branch>` are both empty. A local
+  commit that is not pushed is invisible to Remits; a local branch behind the remote is a stale baseline.
 - `git status --short` shows only intended changes; every rename/delete is explained. **No component file has
   been renumbered to a different id.**
-- Local branch is committed and pushed; sync will read the intended remote commit.
+- Local branch is committed and pushed; sync will read the intended remote commit. If a sync just
+  completed, `git pull --ff-only origin <branch>` has run before any next git operation, because sync may
+  push generated artifacts back to the branch.
 - Local filenames and live inventory (`mcp_account_view`) **agree on id and name for every component**: no live
   component appears locally under a different id, and no expected component is missing a repo file.
   > **Do not run this comparison against `account-info.json` alone — it will report false orphans.** That

package/skills/remits-cli/references/component-resolution.md

@@ -153,7 +153,11 @@ overwrite each other, and a `components commit` clears the lane out from under t
 If more than one agent is working on the same branch, give each its own workspace:
 
 ```bash
-git worktree add ../repo-agent-a forked      # one checkout per agent, same branch
+git fetch origin
+git switch forked
+git pull --ff-only origin forked
+git rev-list --left-right --count HEAD...origin/forked   # must print: 0  0
+git worktree add --force ../repo-agent-a forked           # one checkout per agent, same branch
 cd ../repo-agent-a
 remits-cli workspace use --auto              # names the lane after this directory
 remits-cli components stage                  # isolated: nobody else sees it, nobody overwrites it
@@ -161,6 +165,14 @@ remits-cli test run --test 42
 remits-cli token --path /page/whatever
 ```
 
+That first block matters. `git worktree add ... forked` uses the local `forked` ref; it does not fetch or
+prove that `forked` equals `origin/forked`. If the local ref is stale, every isolated staging lane starts
+from the same stale files and a later sync looks like a deliberate revert. Before the first edit in a new
+or reused worktree, `git status --porcelain`, `git log origin/<branch>..<branch>`, and
+`git log <branch>..origin/<branch>` should all be empty. For variant branches, run
+`remits-cli components promotion --branch <branch>` too; a branch can be current with its own remote and
+still stale relative to trunk.
+
 A workspace narrows STAGING and nothing else. A commit still targets the same branch and the same owner
 account, and the run still resolves whatever committed variant branch the account subscribes to — so it
 does **not** have the side effects of inventing a throwaway git branch per agent (which would make a

package/skills/remits-cli/references/development-loop.md

@@ -93,6 +93,22 @@ This is how every development task should flow:
 #### Step 1: Understand the Request
 Read the user's request. If you may need a repo other than the current one, read `~/.remits-cli/account-repos.json` first. Then review `account-info.json` and `README.md` to understand what components exist and how they relate. Read the source of any component you'll modify before changing it.
 
+**Establish a steady git baseline before the first edit.** The platform syncs from the GitHub remote, not
+from your local files, and a worktree can be stale even when its staging lane is isolated. In the checkout
+you will edit:
+
+```bash
+git fetch origin
+git status --porcelain                         # empty, or only generated guide files you will discard
+git log origin/<branch>..<branch>              # empty: no local commits invisible to the platform
+git log <branch>..origin/<branch>              # empty: not behind the remote the platform syncs
+remits-cli components status
+```
+
+For a non-trunk variant branch, also run `remits-cli components promotion --branch <branch>`. If it reports
+that the branch is behind trunk or that overlays were computed from an old SHA, settle that before changing
+code. A workspace prevents staged-cache collisions; it does not make a stale branch current.
+
 **Establish the account's shape too, not just its components.** Read the `resolution` block in
 `account-info.json` (or `mcp_account_view`): the account `type` decides whether this repo is even the right
 place to change code, `resolution.relationships` shows whether the account has more than one parent (and
@@ -108,6 +124,11 @@ variants of these components exist: editing an origin component will drift them,
 #### Step 2: Make the Change
 Edit component files under `components/`. This is local file editing — the platform doesn't know about your changes yet.
 
+Before changing a displayed value, helper, calculation, schema field, or prompt contract, read that
+component's existing `.meta.yml` sidecar too. Descriptions often carry dated decisions and line-number
+references explaining why a value looks odd. If you are reversing one, say so in the new sidecar text;
+otherwise you are probably reopening a closed bug.
+
 **Creating a component that does not exist yet.** Files are named `<id>_<Name>.<ext>`, where the numeric
 prefix is the platform's component id. A new component has no id, so name its files with the **`new_`
 prefix** and let the sync assign one (it then renames the files to that id):
@@ -272,7 +293,7 @@ If the work is tied to a support ticket:
 
 Before committing, update metadata so the next session understands what changed:
 
-1. **`.meta.yml` sidecars** — Update `summary`, `description`, and `mermaid` for each modified component. `summary` is what drives the compact component description in generated `account-info.json`; `description` is the fallback when no summary is set and is capped in that file.
+1. **`.meta.yml` sidecars** — Update `summary`, `description`, and `mermaid` for each modified component. `summary` is what drives the compact component description in generated `account-info.json`; `description` is the fallback when no summary is set and is capped in that file. Preserve or explicitly revise dated decision notes; do not delete the evidence the next agent needs.
 2. **`README.md`** — If the change affects account-level capabilities or workflows.
 3. **New components** — Always fill in `.meta.yml` immediately.
 
@@ -316,7 +337,15 @@ This separates the local failure boundaries cleanly:
 1. Local git commit
 2. Remote push
 
-After the push, run the **`component-integrity.md`** safety checks before any durable platform sync. Do not run
+After the push, run `git fetch origin` and confirm both local and remote agree on the branch you are about
+to sync:
+
+```bash
+git log origin/<branch>..<branch>              # empty
+git log <branch>..origin/<branch>              # empty
+```
+
+Then run the **`component-integrity.md`** safety checks before any durable platform sync. Do not run
 `remits-cli components sync` when local files, `account-info.json`, and live inventory disagree about component
 IDs or when unexpected deletes/renumbers are present.
 
@@ -340,6 +369,29 @@ unexpectedly, stop and inspect the repo-local session log before running any mut
 
 **Git is required for durable sync.** The platform syncs by pulling from the git remote (`GitHubClient.syncFromRepository`). If `git push` fails, the server has nothing new to sync. You can still **stage** and **test** without git — only durable sync requires it.
 
+**Landing is serial, and the platform now enforces it.** `components commit` takes a short exclusive
+landing lease on `(account, branch)` before it pushes, and `components sync` takes it too. If another agent
+is landing that branch you are refused with a sentence naming who holds it and how long is left:
+
+```
+Refused: Branch 'forked' on account 33 is being landed by dev@acme.test in /Users/dev/wt/acme-a ...
+Keep staging and iterating — staging is lane-isolated — and land when this clears.
+```
+
+Do exactly that. **Do not loop on the refusal**: the lease is minutes at most, staging and testing are
+unaffected because they are lane-isolated, and retrying in a tight loop just burns the run. The reason it
+is serial at all is that `git add -A` sweeps a shared checkout and the platform pushes a regenerated
+`account-info.json` back to the branch during sync, so two commits racing one branch collide on the remote.
+
+**Staging also refreshes your presence.** You do not need `remits-cli agent register` for other agents to
+see you: `components stage` records `(user, checkout, branch, workspace)` so headless workers on other
+machines find you in their "current repository activity" block instead of assuming the repository is
+theirs. A derived record is never routed work.
+
+**An account may make `commit` a refusal outright.** A `no-commit` rule in its `OPERATIONS` process means
+the platform refuses the landing lease and the sync — leave your changes in the working tree and describe
+them on the ticket. Read `support-tickets.md` §"Some of that process is enforced, not requested".
+
 #### Step 8: Close the Ticket
 
 If the request came from a support ticket, the task is not complete until you update the ticket lifecycle yourself:

package/skills/remits-cli/references/investigation.md

@@ -187,7 +187,10 @@ Before starting an investigation outside the confirmed current repo:
 8. `mcp_user_activity` — for "user X is slow right now" reports, list sessions by `userId`/`accountId`, open the session story, and use the returned beat pivots.
 9. `mcp_performance_trace` — for slow/sluggish reports, open the beat `traceId` with `action:"trace"`; use `action:"slowest"` when you only have a broad time window.
 10. `mcp_system_logs` — correlate via `threadGroupingId` for raw log context when the trace needs supporting log lines.
-11. `mcp_component_view`/`mcp_component_grep` — explain how the responsible component works.
+11. If no local checkout exists for the responsible implementation account, use
+    `mcp_component_view`/`mcp_component_grep` to explain how the component works. If the repo exists on
+    this machine, inspect the branch/files there instead; the remote component tools are fallback and
+    live-DB comparison surfaces, not the starting point for source comprehension.
 
 **Slow / sluggish user report:**
 

package/skills/remits-cli/references/support-tickets.md

@@ -11,10 +11,12 @@
 - [Support Ticket Mental Model](#support-ticket-mental-model)
   - [You are an agent, and you register yourself](#you-are-an-agent-and-you-register-yourself)
   - [Autonomous: one ticket, one process](#autonomous-one-ticket-one-process)
+  - [Serving only some workstreams](#serving-only-some-workstreams)
   - [The manual loop](#the-manual-loop)
   - [If you are the worker](#if-you-are-the-worker)
   - [Before you edit anything: where you are, and whether you may](#before-you-edit-anything-where-you-are-and-whether-you-may)
   - [Your account's process is binding, and it is already in your brief](#your-accounts-process-is-binding-and-it-is-already-in-your-brief)
+  - [Some of that process is enforced, not requested](#some-of-that-process-is-enforced-not-requested)
   - [Seeing the queue as a human does](#seeing-the-queue-as-a-human-does)
   - [Agent components are workers too](#agent-components-are-workers-too)
   - [Moving a ticket through its lifecycle](#moving-a-ticket-through-its-lifecycle)
@@ -80,10 +82,17 @@ and it expires on its own so a killed worker cannot park a ticket forever. You d
 remits-cli agent serve                          # workers are whichever agent THIS session is
 remits-cli agent serve --worker-agent codex --max-concurrent 2
 remits-cli agent serve --mode investigate       # read-only workers: no file edits
+remits-cli agent serve --serves support,sdlc    # only these workstreams are routed here
 remits-cli agent workers                        # what is running right now
 remits-cli agent release                        # stop serving, go offline
 ```
 
+`--mode investigate` is still autonomous ticket work. The supervisor claims a ticket, launches a
+worker, and the worker should read/reproduce/localize the issue and update the ticket with useful
+findings or a handoff. What it must **not** do is become the repository editor: investigation-mode
+polls do not acquire or renew the repo edit lease, and the brief explicitly forbids file edits,
+component staging, commits, and `remits-cli ticket lease`.
+
 **Run it in a plain terminal tab.** That tab becomes the agent host: `serve` returns immediately, a
 detached supervisor is anchored to the tab's shell, and closing the tab stops the agent. Nothing in
 that tab is an AI session — the AI only ever appears as the worker processes the supervisor spawns.
@@ -111,6 +120,33 @@ runs, reporting the worker's activity to the dashboard, dropping the claim when
 failed ticket once, and releasing a ticket back to the queue when it has failed too often. Closing
 the terminal stops everything and hands any in-flight work back.
 
+### Serving only some workstreams
+
+`--serves` declares which of the account's **workstreams** this machine covers, so a fleet can be a
+set of queues rather than a pool of interchangeable machines:
+
+```bash
+remits-cli agent serve --serves support,incident --mode investigate   # the support desk box
+remits-cli agent serve --serves sdlc --max-concurrent 2               # the engineering box
+```
+
+The names are the account's own — the platform compares them and learns nothing about any of them.
+Read `remits-cli ticket queue --workstream ...` or the account's `OPERATIONS` prompts to find out
+what this account calls its processes; do not invent names.
+
+**Omit it unless the user asked for it.** A session that declares nothing is a generalist and takes
+everything, which is the right default and what every existing fleet does. Specialising has a real
+cost: a specialist is only routed tickets in its workstreams *and its unrouted sweep takes only
+those*, so a workstream no live session covers is routed to nobody. The platform reports that rather
+than quietly overriding the declaration —
+
+- `dispatch` answers `reason: 'no_agent_serves_workstream'` and names what the live sessions do cover;
+- `agent map` prints each session's declared queues;
+- the supervisor logs `serve.out_of_scope` when it passes over unrouted work it does not serve.
+
+**So after specialising a fleet, run `remits-cli agent map`** and confirm every workstream the
+account ingests is covered by something.
+
 ### The manual loop
 
 Only when the session registered with `agent register` rather than `agent serve`.
@@ -137,6 +173,15 @@ timer.
 local directory through `~/.remits-cli/account-repos.json` and `cd` there before making changes. You
 registered from anywhere; you do not fix anything from anywhere.
 
+For subscriber/fork tickets, this is also the investigation starting point. The reporting account may be
+the fork or client that observed the issue, while `implementationAccountId` names the repo whose branch
+contains the front-stage source. Read the ticket, run/inspect the run context (`ticket where` when useful),
+open the indexed implementation repo, then establish the relevant branch's steady starting state before
+the first edit: fetch origin, fast-forward the branch, and confirm local and remote have no commits missing
+from either side. Then read `account-info.json` and the component files. Use `mcp_component_view` /
+`mcp_component_grep` only when that repo is unavailable locally or when explicitly comparing live DB source
+to the files.
+
 **Capacity is real, not advisory.** A serving session tells the platform how many workers it can run
 (`--max-concurrent`, default 1), and the router will not send it more than that. So a session at
 capacity is skipped in favour of one that is free, rather than accumulating tickets it will never
@@ -155,6 +200,14 @@ headless run is invisible otherwise), and **end in a terminal state** — `compl
 resolution, or `update_status` with what you established and what the next agent should try. Exiting
 quietly leaves a ticket that looks in-flight forever.
 
+**If your brief says this is not the first autonomous run on this ticket, believe it.** Earlier runs
+picked it up and handed it back unfinished; whatever they tried did not work, so repeating it will not
+work either. Read what they recorded, then either take a genuinely different approach or **stop and
+ask** (`remits-cli ticket ask`). Asking is a complete, successful outcome, and it is the right one when
+the obstacle is not something a run can remove. Accounts cap how many times a ticket may be picked up
+and handed back — past that the ticket stops being offered to workers at all and waits for a person, so
+a run that exits quietly at the limit has cost every earlier run as well as its own.
+
 ### Before you edit anything: where you are, and whether you may
 
 Presence answers *who*. Two more facts answer *whether you may edit*, and with git worktrees and
@@ -185,12 +238,31 @@ Four things are worth knowing and are not obvious:
 - **A staging workspace does not replace the lease.** Separate lanes stop two runs *resolving* each
   other's staged code; they do nothing about two processes writing the same files or pushing the same
   branch, which is what actually destroys work.
-- **One editing worker per repository account per lane — worktrees do not change this.** Two worktrees
-  of one repo push to the same branch on the same remote, so per-directory leases would trade file
-  conflicts for non-fast-forward push conflicts, which surface later and are worse.
-- **A spawned ticket worker already has its own staging lane** (`REMITS_WORKSPACE=ticket-<id>`). You do
-  not set it, and your brief states it. Say which lane you staged into when you report what you verified
-  — somebody looking at the shared lane will not see your changes.
+- **You are not restricted to trunk, and you do not choose the branch.** You work on whatever branch your
+  checkout is on — `ticket where` prints it — and nothing switches it underneath you. Separately, if this
+  account subscribes to a **component variant branch**, its variant components (including its
+  `OPERATIONS` process) resolve for you automatically, server-side, without you doing anything. Those are
+  two different facts and only the first is about your files. Load `branch-variants.md` before working in
+  a non-trunk checkout.
+- **The edit lease excludes per repository account and lane, NOT per branch.** So an agent editing a
+  different branch of this same repository still blocks you, even though your files and your pushes would
+  not collide. That is deliberate over-exclusion, not a bug — investigate read-only and hand off, exactly
+  as for any other refusal.
+- **A spawned local ticket worker owns its checkout grounding and already has its staging lane.** For
+  repository work, `remits-cli agent serve` appends the local repository checkout, target branch and a
+  suggested per-ticket worktree path. Before editing, create or choose an isolated worktree appropriate to
+  the ticket. For a ticket with no component branch subscription, the target branch is the repository
+  default before it is the launch checkout's current branch. The supervisor sets
+  `REMITS_WORKSPACE=ticket-<id>` for you; if you choose a detached worktree, export
+  `REMITS_GIT_BRANCH=<branch>` before running `remits-cli`. A worktree is a checkout-isolation tool, not
+  a freshness proof: fetch, fast-forward and prove `HEAD...origin/<branch>` is `0  0` before the first
+  edit, following `multi-agent-development.md`.
+- **GCP Agent components do not get a local checkout.** The same ticket brief can name a component branch
+  subscription, but for a GCP Agent component that is component-resolution context, not a filesystem
+  instruction.
+- **One editing worker per repository account per lane is still the server lease rule.** The worker-owned
+  worktree protects a human's checkout from the spawned worker; it does not make the edit lease
+  per-directory. A branch-aware edit lease with same-branch exclusion is a separate design.
 
 `unlease` returns **your own** lease and deliberately cannot touch anybody else's. Breaking a stale one
 is a separate, human verb: `remits-cli ticket force-unlease --ticket ID --reason "..."`.
@@ -213,6 +285,27 @@ from the prompt, so **edit the prompt, not the file**.
 `workstream` is not `type`: a type classifies the request, a workstream names the procedure, and they
 cross — a `defect` handled by incident response out of hours goes through the SDLC in the morning.
 
+### Some of that process is enforced, not requested
+
+Part of an account's process can be **deterministic**. If your brief has a `## Rules you will be held to`
+section, those rules are enforced by the platform at the write door — the verb is refused, not
+discouraged.
+
+- **Read that section before you act.** A refusal you were warned about costs one command; a refusal you
+  were not costs the run.
+- **A refusal is an ANSWER.** The message names the rule and says what to do instead. Act on that
+  sentence. Do not retry the identical call, and do not go looking for another door — the rules govern the
+  DSL, the MCP tools and this CLI identically.
+- **`[require]` rules mean a human.** You cannot acknowledge one: the platform decides "human" from the
+  absence of an agent run identity, which your commands always carry. Record what you found with
+  `ticket progress` and hand off.
+- **`[warn]` rules let the call through and write a `policy` worklog entry.** Mention it in your handoff.
+- **If you see "POLICY NOT ENFORCED"**, the account's rules could not be parsed. Do not read the absence
+  of a refusal as permission — say so on the ticket. It is a defect in the account's `OPERATIONS` prompt.
+
+The same rules govern `components stage` and `components commit`. A `no-commit` rule is why
+`remits-cli components commit` refuses rather than asks.
+
 ### Seeing the queue as a human does
 
 `remits-cli start` opens a browser control center showing the same facts you are acting on: which
@@ -385,5 +478,6 @@ Sandbox note:
 Use the same repo/context rules as other tools:
 - If the ticket targets a `CLIENT` account, do not assume that client's repo is the implementation repo. Confirm the parent `PLATFORM` / `PRODUCT` relationship first.
 - Read `~/.remits-cli/account-repos.json` before choosing which local repo to open.
-- If the correct repo for the relevant account type exists locally, switch there and inspect `account-info.json` and `/components`.
+- If the correct repo for the relevant account type exists locally, switch there, confirm/pull the relevant
+  branch when clean, and inspect `account-info.json` and `/components`.
 - If the repo is not available locally, use `mcp_account_view`, `mcp_component_view`, and `mcp_component_grep`.

package/skills/remits-cli/references/tool-reference.md

@@ -880,7 +880,7 @@ When a component "can't find" an obviously-present document, run `action:'inspec
 first — that shows what was indexed, which is usually the answer.
 
 ### `mcp_get_guide`
-Load the packaged front-stage guides — the same `docs/guides/` set `remits-cli` syncs into a repo. Use it when
+Load the packaged front-stage guides — the same `docs/front-stage/` set `remits-cli` syncs into a repo. Use it when
 you are working **outside a repo** (or the repo's `guides/` is stale) and need the authoritative guidance
 before writing a component.
 

package/skills/remits-cli/references/troubleshooting.md

@@ -81,7 +81,7 @@ with `REMITS_PLATFORM_DIR`); `remits-cli` clones it on first authenticated run i
 
 Apply the boy-scout rule to the guides themselves: **whenever you only solved the problem by reading the
 core back stage because a front-stage guide was unclear or missing — even when there was no platform
-defect at all — open a guide-only PR** updating the relevant guide in the platform repo's `docs/guides/`,
+defect at all — open a guide-only PR** updating the relevant guide in the platform repo's `docs/front-stage/`,
 which is the source served to every account repo. Better guides over time are an explicit goal.
 
 #### Escalation Bundle (tooling/operational issue)