arcane-cli 0.20.2 → 0.21.0

package/dist/assets/.arcane/governance/agent-policies.md

@@ -275,8 +275,9 @@ If an agent encounters a situation outside its defined parameters, it should:
 
 4. **Push the branch** to origin (after rebase).
 
-5. **Merge or queue** based on your power level:
-   - **Magus+ power level:** self-merge via `git merge --ff-only`, push main, delete branch.
+5. **Merge or queue** based on your power level — and merge by the mechanism your isolation primitive allows (ARC-028 R1):
+   - **Magus+ power level, in the primary checkout:** self-merge via `git merge --ff-only`, push main, delete branch.
+   - **Magus+ power level, in a linked worktree or a clone:** self-merge through the platform's PR merge instead. The authority is identical; only the mechanism changes, because a local ff-merge requires checking out `main` and another working tree already holds it. Power level decides *whether* you may merge without review; the isolation primitive decides *how*.
    - **Below Magus:** push the branch, report the branch name, and queue for human merge.
 
 6. **Delete the branch** (local and remote) after merge.
@@ -286,7 +287,7 @@ If an agent encounters a situation outside its defined parameters, it should:
 - The agent-slug prefix makes ownership obvious and prevents naming collisions.
 - Use standard commit types: `feat`, `fix`, `docs`, `refactor`, `chore`, etc.
 
-**What happens if ff-only fails:** Another actor merged to main first. This should not happen if you followed step 3. If it does, rebase and retry:
+**What happens if ff-only fails:** Another actor merged to main first. This should not happen if you followed step 3. If it does, rebase and retry — **from the primary checkout**, since this block checks out `main`:
 
 ```bash
 git fetch origin
@@ -295,6 +296,8 @@ git checkout main
 git merge --ff-only {your-slug}/type/short-description
 ```
 
+From a linked worktree or a clone, stop after the rebase and merge through the platform's PR instead (ARC-028 R1). `git checkout main` there fails with `fatal: 'main' is already used by worktree at '<path>'`.
+
 ### Multi-Agent Concurrency Rules
 
 When more than one agent may work in the same repository simultaneously:

package/dist/assets/.arcane/governance/git-conventions.md

@@ -204,7 +204,7 @@ type/short-description
 sessions/YYYY-MM-DD-topic-slug
 ```
 
-Create the session branch as the **first action** of any session, before any file edits or commits. All session commits land on this branch. At close, push and open a PR. After merge, return to `main`.
+Create the session branch as the **first action** of any session, before any file edits or commits. All session commits land on this branch. At close, push and open a PR. After merge, return to `main` — **in the primary checkout only** (ARC-028 R8). A session running in a linked worktree ends with push → PR → worktree removal instead; it must not check out `main`, because the primary checkout already holds it and Git will refuse the second checkout.
 
 **Examples:**
 
@@ -257,7 +257,9 @@ The agent slug prefix makes branch ownership obvious in `git branch -r` output a
    ```bash
    git push origin docs/my-topic
    ```
-4. **Merge to main via fast-forward** when done:
+4. **Merge to main via fast-forward** when done. **This step is primary-checkout work** (ARC-028 R1)
+   — it checks out `main`, which a linked worktree cannot do while the primary holds it. From a
+   worktree or a clone, open a PR and merge through the platform instead:
    ```bash
    git checkout main
    git pull origin main
@@ -266,7 +268,7 @@ The agent slug prefix makes branch ownership obvious in `git branch -r` output a
    git branch -d docs/my-topic
    git push origin --delete docs/my-topic
    ```
-5. **If ff-only fails** (someone else merged first), rebase and retry:
+5. **If ff-only fails** (someone else merged first), rebase and retry — **primary checkout only**, same as step 4:
    ```bash
    git checkout docs/my-topic
    git rebase main
@@ -295,7 +297,11 @@ The agent slug prefix makes branch ownership obvious in `git branch -r` output a
    stale divergence. Resolve conflicts locally — never push a branch with known merge conflicts.
 4. **Push the branch to origin** (after rebase).
 5. **Merge or queue for review** based on power level:
-   - **Magus+ agents:** self-merge via `git merge --ff-only`, then push main
+   - **Magus+ agents, working in the primary checkout:** self-merge via `git merge --ff-only`, then push main
+   - **Magus+ agents, working in a linked worktree or a clone:** self-merge through the platform's PR
+     merge instead (ARC-028 R1). The authority is the same; only the mechanism changes, because a
+     local ff-merge requires checking out `main` and the primary checkout already holds it. Power
+     level decides *whether* you may merge without review; the isolation primitive decides *how*.
    - **Below Magus:** push the branch, report branch name, and queue for human merge
 6. **Delete the branch** after merge.
 
@@ -354,16 +360,35 @@ Commit execution rights depend on the interaction context:
 
 ### Post-Merge Cleanup
 
-After every PR merge or local fast-forward merge, **always return to main and prune the branch**. Failing to do this leaves you on a stale branch where new work gets committed to the wrong place or stays unpushed.
+After every PR merge or local fast-forward merge, **from the primary checkout, always return to main and prune the branch** (ARC-028 R8 — the worktree procedure is below, and differs). Failing to do this leaves you on a stale branch where new work gets committed to the wrong place or stays unpushed.
 
 ```bash
-# After PR merges on remote:
+# After PR merges on remote — from the primary checkout:
 git checkout main
 git pull origin main
 git branch -d type/old-topic            # delete local branch
 git push origin --delete type/old-topic  # delete remote branch (safety net; ignore 'does not exist' errors if already auto-deleted)
 ```
 
+**From a linked worktree, do not run the block above** (ARC-028 R8). `git checkout main` fails with
+`fatal: 'main' is already used by worktree at <path>` when the primary checkout holds it, and
+`git branch -d` fails with `error: cannot delete branch '<branch>' used by worktree at <path>` for
+any branch still attached to a worktree — including your own, from inside it. Those are the exact
+messages; recognising them is the point, because neither is a malfunction. A worktree session cleans
+up like this instead:
+
+```bash
+# From the worktree: push and let the PR merge land.
+git push origin type/old-topic
+# Then, from the PRIMARY checkout (R7 — a worktree cannot remove itself safely):
+git worktree remove <path>               # after the same-vantage-point check below
+git fetch --prune origin                 # drops the remote-tracking ref
+git push origin --delete type/old-topic  # if the platform did not auto-delete
+```
+
+Neither failure is an obstacle to work around: Git refusing to double-check-out a branch, and
+refusing to delete a worktree-attached one, are the enforcement ARC-028 R3/R7 rely on.
+
 This applies to all actors — humans, interactive tools (Copilot, Claude), and autonomous agents. The `spell-commit-work` and `spell-close-session` prompts enforce this check.
 
 ### Same-Vantage-Point Check (EF-33 / ARC-028 R7)
@@ -423,7 +448,9 @@ az repos pr reviewer list --id <PR_ID> --org https://dev.azure.com/<org>
 # Allowed merge strategies: Merge (no fast forward) or Rebase+fast-forward
 az repos pr update --id <PR_ID> --org https://dev.azure.com/<org> --status completed --delete-source-branch true --squash false
 
-# 8. Pull merge commit and clean up (worktree-safe)
+# 8. Pull merge commit and clean up — PRIMARY CHECKOUT ONLY (ARC-028 R8).
+#    From a linked worktree, `git checkout main` fails first and the rest of
+#    this block never runs; see Post-Merge Cleanup for the worktree procedure.
 git checkout main
 git pull origin main
 git branch -d <branch>                    # delete local branch (skip if branch is attached to an active worktree)

package/dist/assets/.arcane/governance/threat-model.md

@@ -49,7 +49,8 @@ See also: [Hardening Checklist](hardening-checklist.md), [Authentication Strateg
 | Network exposure on the agent host | **Mitigated** | Gateway bound to loopback only. An encrypted tunnel/VPN is the only remote-access path. No ports open on the LAN. |
 | Supply chain (package installs) | **Mitigated** | Global package installs use a user-owned directory, not a system directory. No `sudo` during install. |
 | Inter-machine communication | **Mitigated** | Encrypted mesh tunnel/VPN. No direct unencrypted LAN communication. |
-| Token/credential exposure | **Mitigated** | Token stored as an env var in a `.env` file. Config uses a secret reference, not plaintext. State directory is mode `700`. |
+| Token/credential exposure (at rest) | **Mitigated** | Token stored as an env var in a `.env` file. Config uses a secret reference, not plaintext. State directory is mode `700`. |
+| Credential committed to version control | **Not mitigated** | Storage conventions are documented (secret references, `.gitignore` entries for `.env`/`*.pem`/`*.key`) but **no detection exists** — no scanner runs on the commit path, the push path, or in CI, and nothing verifies the conventions were followed. `spell-security-review`'s secrets step is an on-demand agent read, not a control. Treat every credential that reaches a commit as compromised and rotate it — history, existing clones, and remote backups all survive deleting the file (EF-35). |
 
 ---
 

package/dist/assets/.github/prompts/spell-close-session.prompt.md

@@ -151,11 +151,30 @@ Rules:
    - Skip this entire step for local-only and read-only sessions.
    - Resolve `<remote>` and `<trunk>` from observed Git/provider state: use the usable authenticated remote selected in step 9 and the merged PR's target branch (falling back to that remote's default branch). Never assume `origin` or `main`.
    - Verify through the detected provider that the PR is merged before changing branches.
+   - **Determine the isolation primitive first (ARC-028 R8).** Run both of these and compare:
+     ```bash
+     git rev-parse --path-format=absolute --git-common-dir
+     git rev-parse --path-format=absolute --git-dir
+     ```
+     Equal → **primary checkout**. Different → **linked worktree**, and the two paths below diverge. `spell-open-session` should already have named the primitive; re-derive it here rather than trusting the handoff, because the session may have moved.
+
+     **`--path-format=absolute` is required, not decorative.** Without it, `--git-dir` returns an absolute path while `--git-common-dir` stays relative whenever the current directory is *below* the repository root — so a plain comparison reports the primary checkout as a linked worktree from any subdirectory, which is most of the time. If your git predates `--path-format` (2.31), use `git rev-parse --git-dir` and test whether the result contains `/worktrees/` instead.
+
+   **Primary checkout (the default path):**
    - Run `git switch <trunk>` followed by `git pull --ff-only <remote> <trunk>`. Do not end a remote-backed session on a topic branch.
-    - Delete the local topic branch: `git branch -d <branch>` — if the repository or its linked worktrees might be reached through more than one filesystem view, run the same-vantage-point check first (EF-33 / ARC-028 R7, [governance/git-conventions.md](../../.arcane/governance/git-conventions.md) Same-Vantage-Point Check section).
+   - Delete the local topic branch: `git branch -d <branch>` — if the repository or its linked worktrees might be reached through more than one filesystem view, run the same-vantage-point check first (EF-33 / ARC-028 R7, [governance/git-conventions.md](../../.arcane/governance/git-conventions.md) Same-Vantage-Point Check section).
    - Verify `git log --oneline -3` shows the merged change at HEAD.
-    - If stale local branches exist (merged or older than 7 days), list them and suggest cleanup.
-    - See [governance/git-conventions.md](../../.arcane/governance/git-conventions.md) Post-Merge Cleanup section.
+
+   **Linked worktree:**
+   - First establish whether any working tree currently holds `<trunk>`: run `git worktree list` and look for `[<trunk>]`. That, not the mere fact of being in a worktree, is what determines the two rules below — a **bare** repository with worktrees attached (a common agent-fleet layout: one bare clone, one worktree per agent) usually has no checkout holding `<trunk>` at all, and there `git switch <trunk>` and `git branch -d` both succeed normally. Verified: they do.
+   - **If a working tree holds `<trunk>`, do not run `git switch <trunk>`.** It will fail — Git refuses to check out one branch in two worktrees (`fatal: '<trunk>' is already used by worktree at '<path>'`). Ending on the session branch is correct here, not a lapse; the branch is already merged and the worktree is about to be removed.
+   - **Do not run `git branch -d <branch>` while this worktree is attached to it.** It will fail (`error: cannot delete branch '<branch>' used by worktree at '<path>'`), from inside the worktree and from the primary alike. Both refusals are the guardrail ARC-028 R3/R7 leans on, not an obstacle to work around — never reach for `-D`, `--force`, or manual deletion of `.git/worktrees/<name>` to get past them. (`-D` does not bypass this either; the refusal is about attachment, not about merge state.)
+   - Report the worktree path and the branch name, and name **where** removal must happen: `git worktree remove <path>` then `git fetch --prune <remote>`, run after the same-vantage-point check from a checkout that is not this one. A worktree cannot safely remove itself. If `git worktree list` shows a working tree holding `<trunk>`, that is the vantage point; if the repository is **bare**, run it from the bare repository itself (`git -C <bare> worktree remove <path>`) — do not report the work as belonging to a "primary checkout" that does not exist.
+   - If this worktree was created with `--detach` there is no branch to name; report the path and the detached HEAD sha instead.
+   - Verify the merge landed with `git log --oneline -3 <remote>/<trunk>` (the remote-tracking ref), since local `<trunk>` is not checked out here to fast-forward.
+
+   - Common to both: if stale local branches exist (merged or older than 7 days), list them and suggest cleanup.
+   - See [governance/git-conventions.md](../../.arcane/governance/git-conventions.md) Post-Merge Cleanup section.
 
 11. **Return a concise closure report.**
 

package/dist/assets/.github/prompts/spell-full-cycle.prompt.md

@@ -107,6 +107,12 @@ Execute the `spell-implement` workflow:
    git checkout main && git pull --ff-only
    ```
    If `pull --ff-only` fails, halt and report — manual rebase is needed.
+
+   **In a linked worktree, do not run the `checkout main` line** (ARC-028 R1/R8). It fails with `fatal: 'main' is already used by worktree at '<path>'` when another working tree holds `main`, and the halt instruction above only covers a `pull` failure — so an agent that runs it there has no branch to take. This matters especially here: the R4 rule below sends genuinely disjoint epics into parallel worktrees, so this pipeline reaches that state by design. Sync the remote-tracking ref instead:
+   ```bash
+   git fetch --prune origin        # origin/main is now current
+   ```
+   and branch from `origin/main` in step 1. Check which primitive you are in with `git rev-parse --path-format=absolute --git-common-dir` vs `--git-dir` — equal means primary checkout. `--path-format=absolute` is required, or every primary checkout looks like a worktree from any subdirectory.
 1. Create the topic branch from `stories.json.branchName` (format: `{agent}/type/description`).
 2. Loop:
    a. Pick the next story where `passes: false`, ordered by priority.
@@ -200,3 +206,6 @@ After each phase completes, output a brief status line:
 - **Branch discipline.** All work on topic branches, never on main. Per ADR-048.
 - **Fresh context per story.** Do not carry assumptions between stories during Phase 3.
 - **Epic checkpointing.** When this spell is run as one epic in a multi-epic plan, recommend running `spell-commit-work` before starting the next epic.
+- **Multi-epic runs serialize by default (ARC-028 R4).** Before running two or more epics concurrently in separate worktrees, compare their footprints: the file and directory globs each will touch, plus any **shared sequence** — database migration numbers, generated indexes and manifests, lockfiles, fixture IDs, anything where correctness depends on what another epic picked. If the footprints overlap on either axis, run the epics **sequentially in one workspace**, or re-scope them to disjoint footprints first. State the comparison and the resulting decision in the run's opening report; "they seemed unrelated" is not a footprint comparison.
+
+  This is a default derived from evidence, not caution for its own sake. A four-epic run with three executing in parallel isolated worktrees produced two epics independently claiming the same migration sequence number and two adding conflicting imports to the same file region — none of it visible until a human reached merge review. A three-epic re-run, strictly serialized in one workspace, produced zero collisions. Isolation prevents epics from *disturbing* each other; it does nothing to stop them *agreeing on the same answer* to a question neither knew the other was asking, and it delays the discovery until the most expensive moment. Serialization stays the default until re-derivation tooling exists (fresh-pull sequence re-derivation, shared numbering locks) — parallelism is available for genuinely disjoint footprints, and should be used there.

package/dist/assets/.github/prompts/spell-implement.prompt.md

@@ -33,6 +33,13 @@ Workflow (loop until all stories pass):
    ```
    If `pull --ff-only` fails, halt and report — manual rebase is needed.
 
+   **In a linked worktree, do not run the `checkout main` line** (ARC-028 R1/R8). It fails with `fatal: 'main' is already used by worktree at '<path>'` when another working tree holds `main`, and the halt instruction above only covers a `pull` failure — so an agent that runs it there has no branch to take. Sync the remote-tracking ref instead, which is all this step actually needs:
+   ```bash
+   git fetch --prune origin        # origin/main is now current
+   git rebase origin/main          # or branch from origin/main directly in step 1
+   ```
+   Check with `git rev-parse --path-format=absolute --git-common-dir` vs `--git-dir`: equal means primary checkout, different means linked worktree. `--path-format=absolute` is required — without it the two differ from any subdirectory and every primary checkout looks like a worktree.
+
 1. **Load stories.json** — locate the feature folder from the current branch:
    ```bash
    # Derive feature folder from branch name (works for lafayette/feat/541-phase-2a or lafayette/feat/phase-2a)

package/dist/assets/.github/prompts/spell-open-session.prompt.md

@@ -71,6 +71,13 @@ Then produce output in this exact structure:
 Before anything else, check:
 
 - **Current branch:** Run `git branch --show-current` and `git worktree list`. Report the current state; do not switch during this read-only check. Branch creation/switching is owned by the lazy Mutation Guard. **Caveat (EF-33):** if this repository or its linked worktrees might be reached through more than one filesystem view (a bridged/remote mount, a container bind-mount), `git worktree list` can truthfully report a live, healthy worktree as `prunable` when read from a vantage point that can't resolve its registered path — this is a read-only report, not a reason to act; never run a destructive worktree/branch command on its output alone (see git-conventions.md's Same-Vantage-Point Check section before any such command elsewhere in this or later sessions).
+- **Isolation primitive (ARC-028 R1–R5):** name where this session will run *before* the Mutation Guard creates anything, and state it in the session output. Every unit of work lives in exactly one of three primitives — the **primary checkout**, a **linked worktree**, or a **full clone**. Select from what the previous bullet's `git worktree list` and `git status` already showed, in this order:
+  - **Managing repository state** — reconciling uncommitted files, pruning branches, fast-forwarding `main`, cutting a release, or any `git worktree` lifecycle operation → **primary checkout** (R1). These are the only operations that require holding `main`, and only one working tree can.
+  - **The primary checkout is occupied** — another session's branch is checked out there, or it holds uncommitted work that is not yours → **linked worktree** (R3). At most one actor occupies the primary checkout at a time. Create it with `git worktree add <path> -b <session-branch>`; never switch or delete a branch attached to a worktree you are not in.
+  - **Unattended/automated git operations** (cron, daemon fleets, anything pulling or pushing without a human present) → **full clone** (R5). Linked worktrees share one physical `.git`, so concurrent unattended operations contend on the same locks.
+  - **Otherwise** → **primary checkout on a session branch** (R2). This is the default and it is deliberately the do-nothing path: one actor, one checkout, no new tooling.
+  - **Footprint overlap overrides the choice (R4).** If this session's work touches the same files or the same shared sequence (migration numbers, generated indexes, lockfiles) as work already running in another primitive, do **not** isolate it — serialize instead: wait, or re-scope to a disjoint footprint first. Isolation does not prevent those collisions, it hides them until merge review.
+  - Working in a linked worktree changes two things later in the session and nothing else: `spell-close-session` must not check out `main` (see git-conventions.md's Post-Merge Cleanup section), and the worktree contains no untracked tooling state — budget for `npm install` or equivalent in a code repo. Branch naming, attribution, and the PR gate are identical from every primitive (R8).
 - **Session branch naming compliance:** Branch names must be human-readable and policy-compliant:
   - Interactive session default: `sessions/YYYY-MM-DD-<topic-slug>` (kebab-case topic from current task/session objective).
   - Disallow random adjective-noun generator names (example: `ideal-disco`) as session defaults.

package/dist/assets/.github/prompts/spell-ship.prompt.md

@@ -91,6 +91,7 @@ Workflow:
    - Tag release if applicable.
 
 9. **Post-merge branch cleanup** (after the PR merges) — the merge was the human gate, so cleanup is automatic:
+   - **First, which primitive are you in?** `git rev-parse --path-format=absolute --git-common-dir` vs `--git-dir` — equal means primary checkout, different means linked worktree. (`--path-format=absolute` is required; without it the two differ from any subdirectory and every primary checkout reads as a worktree.) **In a linked worktree, skip the two steps below** (ARC-028 R1/R8): `git checkout main` fails when another working tree holds `main`, and it fails *first*, so the rest of this cleanup block never runs and the remote branch deletion below is left half-done. Report the worktree path for removal from another vantage point instead, and go straight to the remote-branch and prune steps.
    - Switch to the main branch (e.g. `git checkout main`).
    - Pull the latest (e.g. `git pull`).
    - Delete the merged topic branch locally (e.g. `git branch -d <branch>`) — if the repository or its linked worktrees might be reached through more than one filesystem view, run the same-vantage-point check first (EF-33 / ARC-028 R7, [governance/git-conventions.md](../../.arcane/governance/git-conventions.md) Same-Vantage-Point Check section).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arcane-cli",
-  "version": "0.20.2",
+  "version": "0.21.0",
   "description": "Arcane framework CLI — scaffold and manage governance files in consuming repositories",
   "keywords": [
     "arcane",