@remits/remits-cli 0.1.122 → 0.1.125

package/package.json

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

package/skills/remits-cli/SKILL.md

@@ -74,7 +74,9 @@ reference named after it.
   (`development-loop.md`)
 - **Give each agent its own lane: `remits-cli workspace use --auto`.** Without a workspace you are in
   the SHARED lane, where a full stage replaces what another agent is testing rather than merging with
-  it. (`component-resolution.md`)
+  it. Each agent works in its own **clone**, never a same-branch worktree: worktrees share the branch
+  ref, so one agent's pull moves `HEAD` under the others, and `components commit` refuses there.
+  (`component-resolution.md`)
 - **On a variant branch, sync with `remits-cli components sync --safe`.** It dry-runs first and refuses
   a plan that would write components this checkout did not change — which is what a branch that is
   behind trunk produces, because it still physically carries old copies of files nobody touched.
@@ -82,8 +84,12 @@ reference named after it.
 - **`stage` is always safe. `components commit` on trunk is the most dangerous command in the CLI.**
   It is not a convenience wrapper: it `git add -A`, commits, pushes, and then reconciles the whole
   pushed repo into the live component database — creating, updating, renaming, and **hard-deleting**
-  rows. Prefer the observable `git commit → git push → components sync → git pull`.
-  (`component-integrity.md`)
+  rows. Prefer the observable `git commit → git push → components sync → git pull`. On trunk it refuses
+  before any git write unless you pass `--yes`. (`component-integrity.md`)
+- **After anyone lands, ask whether your lane is stale: `remits-cli components status`.** A landing clears
+  only the lander's lane; yours keeps shadowing their new rows with content staged from the old base.
+  `LANDED SINCE YOUR BASE` / `STALE OVERLAY` mean pull, re-stage, then verify — a pass against a stale
+  lane proves nothing. (`component-resolution.md`)
 - **A component filename's numeric id prefix is load-bearing.** Renumber it and the next trunk sync
   creates a duplicate at the new id and hard-deletes the original. A live component whose files are
   missing from the repo at trunk-sync time is hard-deleted. Never renumber, rename across ids, or

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

@@ -274,7 +274,8 @@ remits-cli components branch <name> --retire [--force]
 ```
 
 Branch administration commands act **as the account you are running from**, which is treated as the branch
-**owner** — run them from the owner's trunk checkout. Authorization is downward-only.
+**owner** — run them from the owner's trunk checkout. Authorization is downward-only. (`--retire` checks
+this and refuses from a non-owner; the read commands below resolve the owner for you.)
 
 - **`--subscribe` sets the branch on an edge that must already exist — it cannot create one.** Failure
   reads *"Account N has no relationship edge to subscribe; add a membership edge first"*. Create it with
@@ -295,7 +296,22 @@ Branch administration commands act **as the account you are running from**, whic
   subscriptions.
 - **Retiring is explicit.** Deleting the *git* branch does **not** remove its overlays; subscribers would
   keep resolving a branch that no longer exists. `--retire` refuses while subscribers remain unless you
-  pass `--force`.
+  pass `--force`, and it refuses (naming the owner) when run from any account other than the branch owner.
+- **Reads work from any checkout.** `components branch <name>` (status, `--diff`, `--subscribers`) and
+  `components promotion` resolve the branch owner the account actually resolves the branch from —
+  including an inherited subscription held by an ancestor — and report it as `branchOwnerAccountId`.
+  `components branches` lists branches this account OWNS; from a subscriber it also names the branch it
+  resolves and from whom. If `components status` prints `INHERITED BRANCH`, this account gets the branch
+  through an ancestor's subscription: a sync from here varies THIS account's own components (for it and the
+  accounts beneath it). To change the owner's components, work in the owner's repository on that branch.
+- **A commit must push to the repository the platform syncs.** `components status` names it (`sync reads
+  repository`). `components commit` refuses before any git write, and `components sync --safe` refuses,
+  when this checkout's `origin` is a different repository; a plain sync warns.
+- **Every prompt varies on a branch, including the README and agent prompts.** Edit the repo-root
+  `README.md`, an agent's `.md` in `components/agents/`, or a prompt in `components/prompts/` exactly as
+  you would any other component file: stage, verify, sync, and subscribers resolve it; merging to trunk
+  lands it. The README becomes an overlay of the account's README prompt (a branch without `README.md`
+  reverts to trunk's); an agent's prompt travels inside that agent's overlay.
 
 **Every component kind can be varied** — `schema`, `reader`, `action`, `embeddable`, `i18n`, `htmltemplate`,
 `rule`, `test`, `utility` (agent), `tool`, `prompt` — including tombstones and branch-only additions. A

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

@@ -193,20 +193,20 @@ remits-cli listen [stop|status] [--foreground true]   # compatibility alias
 remits-cli data-mode [set test|prod]
 remits-cli components stage [--workset | --changed-only] [--branch <name>] [--workspace <name>] [--empty-workset clear] [--data-mode test|prod] [--json|--verbose]   # default = FULL SNAPSHOT of the repo; --workset = only what git says changed, lane reconciled to it
 remits-cli workspace [show | use <name> | use --auto | clear]
-remits-cli components status [--branch <name>] [--component-type <type>] [--component-id <id>] [--json|--verbose]
+remits-cli components status [--branch <name>] [--component-type <type>] [--component-id <id>] [--json|--verbose]   # also: has anyone landed since this lane was staged (freshness)
 remits-cli components lanes [--json]                         # every indexed staging lane on the account
 remits-cli components entries --lane-id <id> [--json|--verbose]  # authoritative staged files for one lane
 remits-cli components clear [--branch <name>] [--component-type <type>] [--component-id <id>] [--all] [--json|--verbose]   # id alone scopes to one component when unambiguous (ids are type-local; add --component-type if the same id is staged in multiple families); no filter clears the whole branch scope; --all forces the full wipe
 remits-cli components sync [--safe [--yes]] [--branch <name>] [--data-mode test|prod] [--force-tombstones] [--dry-run] [--summary] [--changed-only [--changed-since <ref>]]   # gated; on trunk = full repo->DB reconcile, on a variant branch = ComponentVariant overlays only
-remits-cli components commit [--safe] [--message "msg"] [--data-mode test|prod] [--force-tombstones]   # phase 1 merge-stages + compile-validates changed source (never reconciles the lane); --safe gates sync writes
+remits-cli components commit [--yes] [--safe] [--allow-shared-branch] [--message|-m "msg"] [--data-mode test|prod] [--force-tombstones] [--json [--summary]]   # phase 1 merge-stages + compile-validates changed source (never reconciles the lane); on TRUNK refuses before any git write unless --yes; --safe gates variant sync writes
 remits-cli components branches [--json]                                # branches carrying committed variants, with counts + drift
-remits-cli components branch <name> [--json]                           # one branch: overridden / added / removed, drift flags, subscribers
+remits-cli components branch <name> [--json]                           # one branch: owner account, overridden / added / removed, drift flags, subscribers
 remits-cli components branch <name> --diff <componentId> --component-type <kind> [--json]
 remits-cli components branch <name> --subscribers [--json]
 remits-cli components branch <name> --subscribe <accountId> [--parent-account <id>] [--domain <host>] [--dry-run] [--confirm-primary-edge]   # make an account resolve this branch
 remits-cli components branch <name> --unsubscribe <accountId>                          # return that account to trunk
 remits-cli components branch <name> --retire [--force]                                 # delete the branch's overlays
-remits-cli test run --test <id|name> [--branch <stagingScope>] [--names "a|b"] [--watch true|false] [--data-mode test|prod] [--as-account <ID>] [--variant-branch <name|none>]
+remits-cli test run --test <id|name> [--branch <stagingScope>] [--names "a|b"] [--watch true|false] [--data-mode test|prod] [--as-account <ID>] [--variant-branch <name|none>] [--json]
 remits-cli token [--path <embeddablePathOrId>] [--data-mode test|prod] [--as-account <ID>] [--variant-branch <name|none>]
 remits-cli token inspect --token <token|tokenKey|URL>                  # inspect token metadata, safety/dataMode evidence, and full context
 remits-cli tools [--branch <name>] [--data-mode test|prod] [--variant-branch <name|none>]
@@ -316,16 +316,39 @@ For tests specifically:
   `--variant-branch none` when an existing staged cache on the real git branch would shadow committed trunk
   or variant rows. On `components sync` / `commit`, `--branch` is different: it names the GitHub branch to
   reconcile.
+- `--json` on `test run` prints exactly one JSON document to stdout: the final status/result. Safety
+  banners, start/progress lines, and websocket case progress go to stderr so shell callers can parse
+  stdout directly. The exit code is non-zero when the run fails, does not complete, or a requested case
+  selector matches nothing.
 - `--force-tombstones` is only for non-trunk variant syncs, when missing trunk component files are known,
   intentional tombstone overrides. It is rejected on trunk.
 - `--dry-run` is only for `components sync` on non-trunk variant branches. It reports the variant write
   plan without writing rows, caching the sync SHA, or clearing staging.
-- `--summary` on `components sync --dry-run` prints compact counts, removals/tombstones, skipped items, errors,
-  and warnings instead of the full override/add/remove payload.
+- `--summary` on `components sync` prints compact counts plus named updated (with the fields that
+  changed), renamed, skipped, removal/tombstone, error, and gate details instead of the full payload. A
+  trunk sync reports an untouched component under `unchanged`, not `updated`.
+- `--json` on `components stage`, `components sync`, `components commit`, and `tool` prints one
+  parseable JSON document to stdout. Safety banners and prose go to stderr, and sync safety-gate failures
+  are reported inside `gateViolations` with a non-zero exit code instead of appending prose after the JSON.
+- `components commit --json` prints the COMMIT outcome, not the sync's: `phase` (`stage` → `git` → `sync`
+  → `pull` → `complete`), `gitCommitted`, `pushed`, `pushedSha`, `synced`, `postSyncSha`, `pulled`, the
+  nested `sync` (summary with `--summary`), and on failure `error` + `nextStep`. It stops at the first
+  failed phase. `phase: "sync"` with `pushed: true` means the remote holds work the platform has not
+  reconciled — follow `nextStep`; do not re-run `components commit`.
+- `components commit` on trunk refuses before staging, committing, or pushing unless `--yes` is present —
+  with or without `--safe`. Trunk has no dry-run plan, so nothing can preview the full repo-to-DB reconcile.
+- `components commit` refuses before any git write while its branch is checked out in another worktree
+  (`sharedBranchWorktrees` in `--json`). Worktrees of one branch share its ref, so a stale one would commit
+  over landed work. Use one clone per agent; `--allow-shared-branch` overrides after `git status` is clean
+  apart from your own changes.
+- `components commit` refuses before any git write, and `components sync --safe` refuses, when this checkout's
+  `origin` is not the repository the platform syncs for the resolved account (`branchContext.repository` in
+  `components status`). A plain sync warns and reports `repositoryCheck`, including under `--summary`.
 - **Fail-closed sync gates.** On non-trunk variant branches these flags now force a server dry-run first,
   evaluate that plan before any overlay row is written, and only then run the mutating sync when the plan
   passes. On trunk, there is no safe dry-run plan, so do not treat these as scoped commit controls:
-  - `--changed-only` — fail unless every planned write is a component **this checkout actually changed**.
+  - `--changed-only` — fail unless every planned write is a component **this checkout actually changed**
+    (matched by type + id, type + name, or the repo file it came from — so a root `README.md` edit counts).
     This is the strongest guard against a sync that quietly rewrites components you never touched. It
     also fails when the checkout is not a git working tree, because "git could not answer" must never
     be read as "nothing changed".
@@ -388,6 +411,11 @@ REPRESENTABLE. On a non-trunk variant branch, prove a deletion through
 `components sync --dry-run --summary --fail-on-errors`; on trunk there is no dry-run plan, so use the
 full pre-sync safety check before any mutating reconcile.
 
+The repo-root `README.md` is staged as the account's README-purpose Prompt. It is part of the git workset
+for `components stage --workset`, even though it does not live under `components/`. It behaves like any
+other component on trunk AND on a variant branch: a variant sync stores a README change as an overlay of
+the README prompt, and an agent's `.md` in `components/agents/` travels with that agent's overlay.
+
 ### Prod banners and retryable failures
 
 - Every command that can touch production (`tool`, `test run`, `components sync`) prints a `PROD DATA`

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

@@ -115,6 +115,18 @@ Key implications:
   immediately syncs. Never run it while the tree contains drift or unexplained changes. Prefer the explicit,
   observable `components stage → git commit → git push → components sync → git pull` sequence so each
   phase can be inspected.
+- **`components commit` on trunk refuses before any git write unless `--yes` is present** — with or
+  without `--safe`, and with `--skip-git`. Trunk has no dry-run sync plan, so an explicit acknowledgement
+  is the only honest gate; the CLI must not create or push a commit and only then discover it.
+- **A commit that fails after the push says so.** `phase`, `pushed`, `pushedSha` and `nextStep` (in
+  `--json`, one document on stdout) tell you whether the remote now holds work the platform has not
+  reconciled. If it does, fix the cause and run `components sync` — do not re-run `components commit`.
+- **A commit refuses when the push and the sync would hit different repositories** — this checkout's
+  `origin` versus the repository the platform syncs for the account the command resolved. Fix the account
+  (account-info.json, `--account-id`) or run from the right checkout; never force it.
+- **A commit refuses while its branch is checked out in another worktree.** Worktrees of one branch share
+  its ref: a pull in one moves `HEAD` under the others, and `git add -A` from a stale one reverts work that
+  has already landed. Give each agent its own clone.
 - **`components sync` acts on the pushed remote**, so local edits are invisible to it until committed **and
   pushed**, and a drifted **remote** is dangerous even when your local tree looks fine.
 - **Runtime-compiled component source is validated before durable writes.** When a trunk sync or variant
@@ -165,14 +177,14 @@ file is catastrophic.
   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
+  > **Do not run this comparison against `account-info.json` alone — it can still be incomplete.** That
   > file omits `auxiliary: true` components by design, so every auxiliary component looks like a repo file
   > with no DB row, i.e. exactly the "a trunk sync will CREATE a duplicate" signal this check exists to
-  > catch. It also omits README- and AGENT-purpose Prompts, which live at the repo root and as `.md`
-  > sidecars in `components/agents/` rather than in `components/prompts/`, so they look like DB rows with
-  > no repo file — the "will be DELETED" signal. Both are benign. Before treating a flagged component as
-  > drift, confirm against the live row: `mcp_component_view`, or
-  > `mcp_run_action controlAction:"describe"` for an Action. A component that answers is not an orphan.
+  > catch. README- and AGENT-purpose Prompts are also intentionally absent from the `Prompts` collection:
+  > they live at repo-root `README.md` and as `.md` sidecars in `components/agents/`, not in
+  > `components/prompts/`. Before treating a flagged component as drift, confirm against the live row:
+  > `mcp_component_view`, or `mcp_run_action controlAction:"describe"` for an Action. A component that
+  > answers is not an orphan.
 - You can state the expected create/update/delete set. **If any delete or renumber is unexpected, stop.**
 
 ### If something looks wrong — stop, don't paper over

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

@@ -174,22 +174,21 @@ 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 fetch origin
+git clone <repository-url> repo-agent-a                  # one CLONE per agent, same branch
+cd repo-agent-a
 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
 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
+**A clone, not `git worktree add --force`.** Worktrees of one branch share its ref: a pull or commit in one
+moves `HEAD` under the others, and a `components commit` from a stale one reverts work that already landed.
+`components commit` refuses while its branch is checked out in another worktree (`--allow-shared-branch`
+overrides, only once `git status` shows nothing but your own changes). A stale clone is still stale: before
+the first edit in a new or reused clone, `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.
@@ -199,7 +198,7 @@ account, and the run still resolves whatever committed variant branch the accoun
 does **not** have the side effects of inventing a throwaway git branch per agent (which would make a
 commit write `ComponentVariant` overlays for a branch nobody subscribes to).
 
-- `.remits-cli/workspace` is per-checkout and gitignored, so each worktree keeps its own lane.
+- `.remits-cli/workspace` is per-checkout and gitignored, so each clone keeps its own lane.
 - Precedence: `--workspace NAME` > `REMITS_WORKSPACE` > `.remits-cli/workspace` > shared default lane.
 - `--no-workspace` targets the shared lane for one command without clearing the file.
 - Every stage / test run / token / clear prints its `Staging lane:` — if a change seems to have had no
@@ -211,6 +210,18 @@ commit write `ComponentVariant` overlays for a branch nobody subscribes to).
 - `remits-cli components lanes` is the review view across users/branches/workspaces, and
   `remits-cli components entries --lane-id <id>` is the drill-down into actual staged files.
 - `remits-cli components clear --all` is scoped to YOUR lane and never touches another agent's.
+- In lane rows, `currentLane` (also `mine`) marks THIS command's lane; `ownedByCaller` marks every lane
+  staged by your CLI user — your other clones' agents included.
+- **A landing clears only the lander's lane.** Every stage records the commit it came from
+  (`stageBaseSha`), and `components status` compares that with the last commit the platform synced for the
+  branch (`branchContext.lastSyncedSha`) using your local git:
+  - `LANDED SINCE YOUR BASE` — the platform synced a commit this checkout does not contain. Somebody landed
+    after you pulled: `git fetch origin && git pull --ff-only`, then re-stage.
+  - `STALE OVERLAY` — entries staged from a commit older than the last sync. They shadow rows that landed
+    after they were staged; re-stage with `--workset` or clear them.
+  - `--json` carries the same answer as `freshness` (`landedSinceHead`, `entriesBehindLastSync`, `stale`).
+    `null` means unknown — a lane staged by an older CLI, or a branch whose last sync is not recorded —
+    never "fresh".
 
 ### A lane holds an OVERLAY; your workset is a different number
 

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

@@ -235,6 +235,11 @@ Two things to read correctly when it refuses:
   lease) and writes nothing at all.
 - **Every failure is printed, not just the first.** The one-line error is the first failure; the full list
   (identified by type and id) follows it. Fix them in one pass rather than one round trip each.
+- **`N NOT compile-checked` is not a pass.** A `new_` component whose source file is empty or blank cannot
+  be judged, so it is listed by name with its reason instead of being counted as compiled. It will not run.
+- **Deleting a component's source file while its sidecar stays is `content-file-deleted`.** The lane keeps
+  the source it already held, and that is what gets compiled and run. Clear that one component with the
+  command the CLI prints (`components clear --component-type <type> --component-id <id>`).
 
 If git cannot identify the changed set — you are not in a working tree, or git failed — there is no
 workset to validate, and the CLI prints `Compile validation: NOT RUN — workset-unknown` rather than