@remits/remits-cli 0.1.104 → 0.1.106

package/index.js

@@ -74,7 +74,7 @@ const ACCOUNT_SCAN_EXCLUDE_DIRS = new Set([
 
 // Flags that are legitimately repeatable accumulate into an array instead of last-wins. Every other
 // flag keeps last-wins so existing callers are unaffected.
-const REPEATABLE_FLAGS = new Set(['expected-removed', 'expectedRemoved']);
+const REPEATABLE_FLAGS = new Set(['expected-removed', 'expectedRemoved', 'names']);
 
 function parseArgs(argv) {
   const out = { _: [] };
@@ -1572,6 +1572,42 @@ function changedComponentsFromWorkingTree(cwd) {
   });
 }
 
+/**
+ * Components touched by commits between `ref` and HEAD.
+ *
+ * `changedComponentsFromWorkingTree` reads `git status`, i.e. UNCOMMITTED edits only — which is empty
+ * at exactly the moment `--changed-only` is meant to run, because the documented flow is
+ * commit -> push -> sync (sync reads the pushed remote, so it cannot see uncommitted work at all).
+ * The gate was therefore unusable in the flow it exists to guard: it refused every plan with
+ * "plan touches N component(s) this working tree did not edit". `--changed-since <ref>` supplies the
+ * base so the same guard works after the commit.
+ */
+function changedComponentsSinceRef(cwd, ref) {
+  let output = '';
+  try {
+    output = execSync('git diff --name-only ' + JSON.stringify(ref) + '...HEAD -- components', {
+      cwd,
+      stdio: ['ignore', 'pipe', 'pipe']
+    }).toString();
+  } catch (_) {
+    return null;
+  }
+  const byKey = new Map();
+  for (const rawLine of output.split(/\r?\n/)) {
+    const filePath = rawLine.trim();
+    if (!filePath) continue;
+    const info = componentPathInfo(cwd, filePath);
+    if (!info) continue;
+    if (!byKey.has(info.key)) {
+      byKey.set(info.key, { type: info.type, id: info.id, name: info.name, fields: [], paths: [] });
+    }
+    const entry = byKey.get(info.key);
+    if (!entry.fields.includes(info.field)) entry.fields.push(info.field);
+    if (!entry.paths.includes(info.path)) entry.paths.push(info.path);
+  }
+  return Array.from(byKey.values());
+}
+
 function parsePositiveInt(value, fallback) {
   const parsed = Number(value);
   return Number.isFinite(parsed) && parsed > 0 ? Math.floor(parsed) : fallback;
@@ -2309,7 +2345,7 @@ async function syncComponentsCommand(flags) {
       throw new Error(previewResponse.message || 'Server sync dry-run failed');
     }
 
-    preflightGate = evaluateSyncGates(previewResponse, flags, changedFromWorkingTree);
+    preflightGate = evaluateSyncGates(previewResponse, flags, changedFromWorkingTree, cwd);
 
     if (namesOnly) {
       printSessionResolutionWarning(sessionContext);
@@ -2332,7 +2368,7 @@ async function syncComponentsCommand(flags) {
   }
 
   const summary = buildSyncSummary(response);
-  const gate = preflightGate || evaluateSyncGates(response, flags, changedFromWorkingTree);
+  const gate = preflightGate || evaluateSyncGates(response, flags, changedFromWorkingTree, cwd);
   summary.gates = gate.checks;
 
   if (flagEnabled(flags.json)) {
@@ -2505,7 +2541,7 @@ function parseExpectedRemoved(flags) {
 }
 
 // Fail-closed gates. Each returns a violation string or null; the command exits non-zero if any fire.
-function evaluateSyncGates(response, flags, changedFromWorkingTree) {
+function evaluateSyncGates(response, flags, changedFromWorkingTree, cwd) {
   const entries = syncPlanEntries(response);
   const results = ((response && response.sync) || {}).syncResults || {};
   const removed = entries.filter((e) => e.bucket === 'removed');
@@ -2536,13 +2572,19 @@ function evaluateSyncGates(response, flags, changedFromWorkingTree) {
   }
 
   if (flagEnabled(flags['changed-only']) || flagEnabled(flags.changedOnly)) {
-    if (changedFromWorkingTree === null) {
+    const since = flags['changed-since'] || flags.changedSince;
+    const fromRef = since ? changedComponentsSinceRef(cwd, String(since)) : null;
+    if (since && fromRef === null) {
+      violations.push('--changed-since: could not diff against "' + since + '". Check the ref exists (git fetch first for a remote ref).');
+      checks.changedOnly = false;
+    } else if (changedFromWorkingTree === null && fromRef === null) {
       violations.push('--changed-only: this checkout is not a git working tree, so the changed set cannot be established.');
       checks.changedOnly = false;
     } else {
+      const changedSet = (changedFromWorkingTree || []).concat(fromRef || []);
       // A component the checkout edited is identified by type + id, or type + name for `new_` files.
-      const allowedIds = new Set(changedFromWorkingTree.filter((c) => c.id != null).map((c) => c.type + ':' + c.id));
-      const allowedNames = new Set(changedFromWorkingTree.filter((c) => c.name).map((c) => c.type + ':' + String(c.name).toLowerCase()));
+      const allowedIds = new Set(changedSet.filter((c) => c.id != null).map((c) => c.type + ':' + c.id));
+      const allowedNames = new Set(changedSet.filter((c) => c.name).map((c) => c.type + ':' + String(c.name).toLowerCase()));
       const unexpected = entries.filter((entry) => {
         if (entry.id != null && allowedIds.has(entry.type + ':' + entry.id)) return false;
         if (entry.name && allowedNames.has(entry.type + ':' + String(entry.name).toLowerCase())) return false;
@@ -2550,8 +2592,15 @@ function evaluateSyncGates(response, flags, changedFromWorkingTree) {
       });
       checks.changedOnly = unexpected.length === 0;
       if (unexpected.length) {
-        violations.push('--changed-only: plan touches ' + unexpected.length + ' component(s) this working tree did not edit: ' +
-          unexpected.slice(0, 20).map(syncEntryToken).join(', ') + (unexpected.length > 20 ? ', ...' : ''));
+        // Name the most likely cause instead of only the symptom. An empty changed set with a non-empty
+        // plan is the ordinary post-commit state, not evidence that the plan is dangerous.
+        const hint = (!changedSet.length && !since)
+          ? '\n    The changed set is EMPTY: --changed-only reads UNCOMMITTED edits, and the documented flow ' +
+            'commits and pushes before syncing. Pass --changed-since <ref> (e.g. the commit you branched ' +
+            'from, or origin/main) so the gate can see committed work.'
+          : '';
+        violations.push('--changed-only: plan touches ' + unexpected.length + ' component(s) this checkout did not change: ' +
+          unexpected.slice(0, 20).map(syncEntryToken).join(', ') + (unexpected.length > 20 ? ', ...' : '') + hint);
       }
     }
   }
@@ -2571,6 +2620,36 @@ function buildSyncSummary(response) {
   const errors = Array.isArray(results.errors) ? results.errors : [];
   const skipped = Array.isArray(results.skipped) ? results.skipped : [];
 
+  // A sync that SHORT-CIRCUITED on the cached branch SHA did no work at all, and the server says so
+  // (`skipped: true` plus a message). Rendering it through the normal shape below printed
+  // `overridden: 0, added: 0, removed: []` — which is what a sync that ran and found nothing to do
+  // prints, so the two were indistinguishable. That matters because the cache can hold a SHA whose
+  // overlays were since removed by another path: an ordinary re-sync then reports zeros forever and
+  // the operator has no reason to suspect the branch was never re-read. Report the skip as itself.
+  // `syncResults` absent is the fallback signal, so this still reads correctly against a server that
+  // predates the explicit `skipped` flag rather than silently falling back to the misleading zeros.
+  const shortCircuited = sync.skipped === true
+    || (sync.syncResults == null && !!sync.message && sync.dryRun !== true);
+  if (shortCircuited) {
+    return {
+      success: response && response.success === true,
+      accountId: response && response.accountId,
+      branchName: sync.branchName || (response && response.branchName),
+      mode: sync.mode || 'variant',
+      skipped: true,
+      reason: sync.message || 'branch head matches the cached sync SHA; the branch was not re-read',
+      branchHeadSha: sync.branchHeadSha || sync.postSyncSha || null,
+      warnings: [
+        // Scoped to COMPONENTS deliberately: the short-circuit still refreshes the delivered guides and
+        // account metadata, so "nothing happened" would be its own small untruth.
+        'NO COMPONENTS WERE SYNCED. This is the cached-SHA short-circuit, not an empty plan — the ' +
+          'branch was never re-read.',
+        'Use --dry-run to see the real plan (a dry run always re-reads the branch), or ' +
+          '--force-tombstones to re-read and apply it.'
+      ]
+    };
+  }
+
   // A TRUNK sync and a VARIANT sync report in different vocabularies, and this summary only ever spoke
   // variant. So the single most consequential line of a promotion — "component X was CREATED on trunk as
   // id N" — printed as `added: 0`, and the runbook's definition of done ("components created, with their
@@ -3153,7 +3232,26 @@ async function testCommand(flags) {
     throw new Error('Missing --test <id-or-name>');
   }
 
-  const names = flags.names ? String(flags.names).split(',').map((s) => s.trim()).filter(Boolean) : [];
+  // Test case names are English prose, so COMMAS occur in them naturally. A comma-delimited selector
+  // therefore split a legitimate name in half, matched nothing, and (before the server learned to
+  // report unmatched selectors) reported a clean run of zero cases. `|` is the delimiter now; the
+  // comma still works when no `|` is present, so existing invocations keep behaving as before.
+  // `--names` may also be repeated, which needs no delimiter at all.
+  const rawNames = flags.names === undefined || flags.names === null
+    ? []
+    : (Array.isArray(flags.names) ? flags.names : [flags.names]);
+  const repeated = rawNames.length > 1;
+  const names = rawNames
+    .flatMap((value) => {
+      const text = String(value);
+      if (text.includes('|')) return text.split('|');
+      // Comma-splitting is the legacy behaviour, kept so existing invocations still work. It is applied
+      // ONLY to a single --names value: repeating the flag is already unambiguous, so splitting there
+      // would take a deliberate literal name back apart.
+      return repeated ? [text] : text.split(',');
+    })
+    .map((s) => s.trim())
+    .filter(Boolean);
 
   const api = buildAxios(baseUrl, session.token);
   // --as-account runs the Test AS a (descendant) subscriber account, so that account's relationship
@@ -3209,6 +3307,23 @@ async function testCommand(flags) {
   }
 
   console.log('Final status:', JSON.stringify(status, null, 2));
+
+  // A selector that matched no case is a mis-specified run, not a passing one. Say so in the terminal
+  // and exit non-zero, or "0 passed, 0 failed" reads exactly like a suite where everything passed.
+  const unmatched = (status.result && status.result.unmatchedTestNames) || [];
+  if (unmatched.length) {
+    console.error('');
+    console.error('No test case matched: ' + unmatched.map((n) => '"' + n + '"').join(', '));
+    const declared = (status.result && status.result.declaredTestNames) || [];
+    if (declared.length) {
+      console.error('Cases declared by this suite:');
+      declared.forEach((n) => console.error('  - ' + n));
+    }
+    console.error('--names is delimited by "|" (a comma still works when no "|" is present), so a case');
+    console.error('name containing a comma must be passed with "|" or by repeating --names.');
+    process.exitCode = 1;
+  }
+
   if (status.status !== 'completed') {
     process.exitCode = 1;
   } else if (status.result && status.result.failed > 0) {
@@ -5977,6 +6092,8 @@ function printComponentsHelp(subcommand) {
     console.log('');
     console.log('Agent safety gates (each exits non-zero instead of printing a wall of JSON):');
     console.log('  --changed-only            dry-run first; fail unless every planned write is a component this checkout changed');
+    console.log('  --changed-since <ref>     pair with --changed-only after committing: the changed set becomes');
+    console.log('                            the components touched between <ref> and HEAD, plus uncommitted edits');
     console.log('  --names-only              dry-run first; print only "type id name" lines and write nothing');
     console.log('  --fail-on-removed         dry-run first; fail if the plan removes/tombstones anything');
     console.log('  --fail-on-errors          dry-run first; fail if the server reported any per-component sync error');
@@ -6037,7 +6154,7 @@ function printComponentsHelp(subcommand) {
 }
 
 function printTestHelp() {
-  console.log('Usage: remits-cli test run --test <id|name> [--base-url URL] [--branch stagingScope] [--names name1,name2] [--watch true|false] [--data-mode test|prod] [--as-account ID] [--variant-branch NAME|none]');
+  console.log('Usage: remits-cli test run --test <id|name> [--base-url URL] [--branch stagingScope] [--names "a|b"] [--watch true|false] [--data-mode test|prod] [--as-account ID] [--variant-branch NAME|none]');
   console.log('');
   console.log('Runs a Test component against the staged/variant world for this checkout.');
   console.log('Examples:');
@@ -6045,7 +6162,8 @@ function printTestHelp() {
   console.log('  remits-cli test run --test "Merchant Statements" --names "managed account case"');
   console.log('');
   console.log('Notes:');
-  console.log('  --names is comma-delimited, so avoid commas in individual test case names.');
+  console.log('  --names is delimited by "|" (comma also works when no "|" is present), and may be repeated.');
+  console.log('    A selector that matches no case fails the run rather than reporting 0 passed / 0 failed.');
   console.log('  --as-account changes the execution account so subscriber branch edges apply.');
   console.log('  --variant-branch <name> probes a committed variant branch; use "none" or "trunk"');
   console.log('       to force production/subscription semantics from a variant checkout.');
@@ -6146,7 +6264,7 @@ async function main() {
     console.log('  remits-cli components branch <name> --subscribe <accountId> [--dry-run] [--confirm-primary-edge]');
     console.log('  remits-cli components branch <name> --unsubscribe <accountId>    # return that account to trunk');
     console.log('  remits-cli components branch <name> --retire [--force]           # delete the branch\'s overlays');
-    console.log('  remits-cli test run --test <id|name> [--base-url URL] [--branch stagingScope] [--names name1,name2] [--watch true|false] [--data-mode test|prod] [--as-account ID] [--variant-branch NAME]');
+    console.log('  remits-cli test run --test <id|name> [--base-url URL] [--branch stagingScope] [--names "a|b"] [--watch true|false] [--data-mode test|prod] [--as-account ID] [--variant-branch NAME]');
     console.log('  remits-cli token [--base-url URL] [--branch BRANCH] [--path embeddable/path] [--data-mode test|prod] [--as-account ID] [--variant-branch NAME|none]');
     console.log('  remits-cli token inspect --token <token|tokenKey|URL> [--base-url URL] [--account-id ID]');
     console.log('');

package/package.json

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

package/skills/remits-cli/SKILL.md

@@ -339,6 +339,14 @@ file is catastrophic.
 - Local branch is committed and pushed; sync will read the intended remote commit.
 - 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
+  > 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.
 - 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
@@ -895,7 +903,16 @@ Tests run on the platform against your staged snapshot. They stream results in r
 
 Important test-runner constraints:
 - `remits-cli test run` now defaults to `test` dataMode unless you explicitly pass `--data-mode prod`.
-- Do not put commas in individual `test("...")` names. The CLI `--names` filter is comma-delimited, so comma-bearing test names cannot be targeted cleanly as a single selected case.
+- **`--names` is delimited by `|`, and may be repeated.** A comma still splits a single `--names` value
+  (legacy behaviour), which is why a case name containing a comma used to be cut in half and match
+  nothing. Prefer `|` or repetition whenever a name might contain punctuation:
+  ```bash
+  remits-cli test run --test 13 --names "a case, with a comma|another case"
+  remits-cli test run --test 13 --names "a case, with a comma" --names "another case"
+  ```
+- **A selector that matches no case FAILS the run.** It used to report `0 passed, 0 failed`,
+  `completed`, and exit 0 — indistinguishable from a suite where everything passed. The run now names
+  the unmatched selectors and lists the cases the suite actually declared, and exits non-zero.
 
 If no relevant Test component exists yet, consider creating one. Test components live in `components/tests/` and follow the same component structure. They provide permanent regression protection — every test you write today saves debugging time tomorrow.
 
@@ -1617,6 +1634,15 @@ a confirm-gated override when the removal guard refuses. Preview there is the sa
 - A test/tool response reports `testComponentSource` as `staged` | `variant` | `db`, so you can see which
   layer the run resolved without reading logs.
 
+> **A populated staging cache makes a variant look broken.** Anything carrying a CLI `TestMode` — a
+> `remits-cli token` URL, `/s/<tokenKey>/...`, an `X-Auth-Token` request, a script-loader embed — resolves
+> the STAGED layer, which outranks the variant. So with components staged under the same branch/user, a
+> tokenized page reports `Component Branch: <branch>` but `Variant Applied: none` and renders trunk, while
+> an anonymous `?account_id=` request to the same page reports the variant. That is the documented
+> precedence (staged -> variant -> trunk) working correctly, and it reads exactly like "tokens break
+> variant resolution". **Run `remits-cli components clear --all` before verifying variant resolution
+> through any tokenized entry point**, or check `remits-cli components status` first.
+
 ## Production Support Workflow
 
 Switch to prod mode for investigations:
@@ -2804,7 +2830,7 @@ remits-cli data-mode [set test|prod]
 remits-cli components stage [--branch <name>] [--data-mode test|prod] [--json|--verbose]
 remits-cli components status [--branch <name>] [--component-type <type>] [--component-id <id>] [--json|--verbose]
 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 [--branch <name>] [--data-mode test|prod] [--force-tombstones] [--dry-run] [--summary]   # gated; on trunk = full repo->DB reconcile, on a variant branch = ComponentVariant overlays only
+remits-cli components sync [--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 [--message "msg"] [--data-mode test|prod] [--force-tombstones]
 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
@@ -2813,7 +2839,7 @@ 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>]
 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>]
@@ -2823,7 +2849,8 @@ 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`.
-- `--names` is comma-delimited, so keep individual test names comma-free.
+- `--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
   (*"what does customer X get?"*); `--variant-branch <name>` probes a branch from any checkout
   (*"what does branch Y look like?"*), and `--variant-branch none` forces production/subscription semantics.
@@ -2841,10 +2868,16 @@ For tests specifically:
 - **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 edited**.
+  - `--changed-only` — fail unless every planned write is a component **this checkout actually changed**.
     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".
+    > **Pair it with `--changed-since <ref>` after you have committed.** On its own `--changed-only`
+    > reads UNCOMMITTED edits, and the documented flow commits and pushes *before* syncing (sync reads
+    > the pushed remote, so it cannot see uncommitted work at all) — so the changed set is empty at
+    > exactly the moment the gate runs, and it refuses the whole plan. `--changed-since origin/main`
+    > (or the commit you branched from) makes the changed set the components your commits touched.
+    > The refusal message says this when it detects the empty-set case.
   - `--fail-on-removed` — fail if the plan removes or tombstones anything.
   - `--expected-removed <type:id>` — whitelist the removals you intend (repeatable, or comma-delimited,
     e.g. `--expected-removed action:5,reader:9`). It **implies** `--fail-on-removed`, so any removal you
@@ -2902,6 +2935,8 @@ For tests specifically:
 | A component vanished for one account after a variant-branch sync | Its file is missing from that branch, so the sync created a **tombstone** that hides it from subscribers. Restore the file on the branch and re-sync. Trunk is unaffected. |
 | A variant Test suite fails wholesale, asserting trunk where you expect a variant | You are almost certainly running it from a **variant checkout**: `variantBranch` outranks every subscription, so the suite's own fixture accounts resolve YOUR branch. Re-run from trunk or with `--variant-branch none` before treating it as a regression. |
 | `components sync` on a branch says "No changes detected" but trunk has moved | Re-run it; a trunk sync now invalidates the branch's cached verdict. If it still skips, the branch genuinely matches trunk - check `components branch <name>` for what is actually stored. |
+| A sync summary reports `skipped: true` with `NO COMPONENTS WERE SYNCED` | The branch head matches the cached sync SHA, so the branch was never re-read — this is NOT an empty plan. It matters when something else changed the overlays at that same SHA: an ordinary re-sync then answers "nothing to do" forever. `--dry-run` always re-reads the branch and shows the real plan; `--force-tombstones` re-reads and applies it. |
+| A branch sync stores overlays for components you never edited on the branch | **Trunk moved.** Sparseness compares the branch against CURRENT trunk, so editing a component on trunk without merging trunk into the branch turns it into a branch overlay on the next branch sync. The branch did not change. Merge trunk in, push, re-sync — the overlays prune. Check `components promotion` for the phase. |
 | After promoting a `new_*` component to trunk, the branch still shows it as `added` | You have not re-synced the branch since the trunk sync. Merge trunk into the branch and `components sync`: the file adopts the promoted id and, if unchanged, removes its own overlay. If the branch carries BOTH `new_Foo.*` and `<id>_Foo.*`, the id file wins and the `new_` one is reported `skipped: superseded` - delete it. |
 | After promoting a standalone Prompt, the branch still shows `OVERRIDDEN prompt:<id>` with only `purpose` changed | The trunk Prompt row does not match repo metadata. Ensure the Prompt sidecar has `description` and `purpose: CUSTOM`, run a platform build that imports Prompt `purpose`, re-sync trunk, merge back, and re-sync the branch. |
 | A branch preview reports a `removed` component nobody deleted | Check whether that component has a file on **trunk**. A DB row with no trunk file is missing from every branch, so it reads as a removal everywhere (and the trunk sync tries to hard-delete it each run). Repair trunk, not the branch. |