@yemi33/minions 0.1.2383 → 0.1.2384

package/playbooks/shared-rules.md

@@ -87,8 +87,8 @@ This task is part of a **shared-branch plan** — every plan item shares the bra
 
 - Do NOT write to `agents/*/status.json` — the engine manages your status automatically.
 - Do NOT remove worktrees — the engine handles cleanup automatically.
-- Do NOT checkout branches in the main working tree — use worktrees or `git diff`/`git show`.
-- **NEVER run `git checkout <branch>` / `git switch` / `git merge` / `git rebase` / `git cherry-pick` in a project's operator checkout (`project.localPath`, e.g. the configured repo root).** That tree must stay on its main branch. For ANY branch operation — backport, sync, cross-branch merge, "create a PR off branch X" — create an isolated worktree first: `git -C <localPath> worktree add <scratch-path> <base>`, do all checkout/merge/commit/push **inside that worktree**, then `git -C <localPath> worktree remove <scratch-path>`. Running these in the live checkout pollutes the operator's main, leaves stuck-merge conflicts, and resurrects gitignored runtime state (the "old PRDs came back" incident). The engine auto-restores a hijacked operator checkout and files an inbox alert, but do not rely on that — use a worktree.
+- In worktree mode, treat the configured operator checkout (`project.localPath`) as read-only. Never edit files, run write-producing builds, or perform `checkout` / `switch` / `merge` / `rebase` / `cherry-pick` / `reset` / `clean` there. Use your engine-assigned cwd for all work. The engine deliberately does not repair or clean the operator checkout.
+- For any explicit cross-branch operation, create an isolated worktree first: `git -C <localPath> worktree add <scratch-path> <base>`, perform every mutation inside that worktree, then remove only that engine-owned scratch worktree.
 - Treat `notes/inbox/` writes as success artifacts only. If the task fails, is blocked, is cancelled, or ends partial, do **not** create an inbox note; report the failure in your final response, completion block, PR/work-item comment, or other task-specific failure channel instead.
 - Read `notes.md` for team rules and decisions before starting.
 - **Check team memory first, then look outside.** Before researching from scratch, check what the team already knows — in this order:

package/prompts/cc-system.md

@@ -89,25 +89,25 @@ If you start a small task and discover it's actually Medium (3+ files, more tool
 
 When genuinely in doubt about the size, delegate — agents have isolated worktrees, full tool access, durable work-item tracking, and no turn limits.
 
-### HARD STOP — never edit files yourself in a live/hybrid project
-This overrides everything above, **including the direct-handling override**. For any project whose effective checkout mode is `live` (or `hybrid` for a code-authoring work-item type — `implement`/`fix`/`docs`/`decompose`), you MUST NOT use `Edit`/`Write`/`Bash` (or any tool) to mutate files inside that project's `localPath`, **regardless of task size** — not even a Small 1-line change, and not even when the human explicitly says to do it yourself. The Step-3 "do it yourself" allowance and the Step-1 direct-handling override do **not** apply to writes inside a live/hybrid checkout.
+### HARD STOP — never edit a configured project's operator checkout
+This overrides everything above, **including the direct-handling override**. For every configured project, you MUST NOT use `Edit`/`Write`/`Bash` (or any tool) to mutate files inside that project's `localPath`, **regardless of checkout mode or task size** — not even a Small 1-line change, and not even when the human explicitly says to do it yourself.
 
-Why: live-mode projects have no worktree isolation — the engine runs agents in-place inside `localPath` and caps dispatch to one mutating operation at a time. A stray CC edit is outside dispatch ownership: with dirty recovery disabled it causes a `live-checkout-dirty` refusal that blocks live work, while the default auto-stash policy can silently park that edit before the next dispatch, so the requested change is no longer present for the agent to validate or commit. Auto-stash/reset is a dispatch recovery mechanism, not ownership bookkeeping for CC edits.
+Why: in `worktree` mode, `localPath` is operator-owned and every project-bound dispatch (including read-only work) gets an isolated worktree. In `live`/`hybrid` mode, only the engine-owned dispatch path may deliberately operate there. A direct CC edit bypasses both ownership models.
 
-Instead, when a change is needed in a live/hybrid project, **dispatch a normal work item** (`POST /api/work-items`, `type: "implement"` or `"fix"` as usual) and let the engine own the live-checkout dispatch path (dirty-tree refusal, single-mutating-dispatch cap, auto-stash/auto-reset). Do not try to shortcut it with your own edit.
+Instead, **dispatch a normal work item** (`POST /api/work-items`, `type: "implement"` or `"fix"` as usual). The engine will choose an isolated worktree or the guarded live path from project configuration. Do not shortcut that path.
 
-Read-only inspection is still fine to do yourself in a live/hybrid checkout: viewing files, `git status`/`git log`/`git diff`, and non-mutating build/test commands are all fair game. The restriction is specifically about **writes**. See "Project checkout modes (worktree / live / hybrid)" below for the mode contract this rule protects.
+Read-only inspection is still fine: viewing files and `git status`/`git log`/`git diff` are allowed. Do not run builds/tests in `localPath` when they may generate files; dispatch them instead.
 
-### After you make a local code edit yourself — offer to open a PR
-This flow is **worktree-mode only** — it applies solely to projects whose effective checkout mode is `worktree`. For `live`/`hybrid` projects you never edit files yourself (see the HARD STOP above), so there is nothing to PR from a CC edit. If you ever find uncommitted changes sitting in a live-mode project's checkout anyway, do **not** commit or push them yourself — just report the dirty state to the user and let them decide how to clean it up.
+### Create a PR from pre-existing operator changes
+Use this only when the human asks to open a PR from changes that already exist in a configured worktree-mode project's operator checkout. CC must not create those changes itself.
 
-When you edit files **yourself** in a configured worktree-mode project's working tree (the Step-3 "do it yourself" path — NOT a change a dispatched agent made in its own worktree), don't leave the diff sitting uncommitted. After you finish editing, call:
+First call:
 ```
 curl -s -X POST http://localhost:{{dashboard_port}}/api/pr-action/offer-create-pr \
   -H 'Content-Type: application/json' -H 'X-CC-Turn-Id: {{cc_turn_id}}' \
   -d '{"project":"<project name>"}'
 ```
-This checks the project's working tree (`git status --porcelain`) and, when there are uncommitted changes, returns a **`[Create PR]`** follow-up chip to the user (same chip mechanism as the `pr-action` `[Comment]`/`[Fix once]`/`[Track for auto-fix]` chips). When the user clicks it, you'll receive a turn with **explicit step-by-step instructions — follow them exactly**. Because you only ever edit files yourself in worktree-mode projects (see the HARD STOP above), this is always the worktree-mode flow: the turn tells you to first `POST /api/pr-action/prepare-create-pr-worktree {"project":"…"}`. The server moves your uncommitted changes into an **isolated worktree** and restores the live checkout clean, returning `{worktreePath, branch, baseBranch}`. You then run **all git from inside `worktreePath`** (`git -C <worktreePath> …`) to commit/push/open the PR, then `POST /api/pr-action/cleanup-create-pr-worktree` to remove it. **Never commit, branch, or push in the live checkout** — that leaks commits onto the operator's `main`.
+This checks the source read-only and returns a **`[Create PR]`** chip when changes exist. The follow-up calls `POST /api/pr-action/prepare-create-pr-worktree {"project":"…"}`; the server **copies** the diff/untracked files into an isolated worktree and leaves `localPath` unchanged. Commit, push, and open the PR only from the returned `worktreePath`, then remove that worktree through the cleanup endpoint. Report that the operator's original changes remain untouched.
 
 Pass `"contextOnly":true` if the PR should be tracked-but-not-auto-reviewed; omit it to have the engine auto-manage the PR (review → fix → re-review → auto-merge). If `hasChanges` is `false`, there's nothing to PR — skip the offer. Don't commit/push on your own initiative; surface the chip and let the user decide.
 
@@ -332,11 +332,11 @@ The `X-CC-Turn-Id` header is the audit trail — the handler stamps it onto the
 
 Every configured project has an effective **checkout mode** — surfaced in your state snapshot next to the project as `[worktree]`, `[live]`, or `[hybrid (live-validation: <type>)]`. It controls where dispatched agents run:
 
-- **`worktree`** (default) — each dispatch gets its own isolated `git worktree`. Agents run fully in parallel; nothing touches the operator's working tree. Use for normal repos.
+- **`worktree`** (default) — every project-bound dispatch, including read-only types, gets an isolated `git worktree`. Agents run fully in parallel; Minions never uses `localPath` as agent cwd or repairs/cleans it. Use for normal repos.
 - **`live`** — agents run **in-place** inside the project's `localPath` (no worktree). The engine caps this to **one mutating dispatch at a time** per project. Dirty-tree behavior follows the configured auto-stash/reset policy (auto-stash defaults on); with recovery disabled, the item remains pending until the tree is clean. Use only when worktrees are unworkable.
 - **`hybrid`** — `live` **plus** a `liveValidation: { type, autoDispatch }` block. Work items not listed in `type` use isolated worktrees; listed live-capable canonical work-item types run in-place. The normal validation type is `test`. `build-and-test` is a playbook name, not a work-item type. `type` accepts one string or an array. When `autoDispatch:true`, `test` must be included; the engine creates one PR-targeted `test` WI with the `build-and-test` playbook after each eligible coding WI completes.
 
-**CC never writes into a live/hybrid checkout itself.** A one-off CC edit leaves untracked operator dirt that the next dispatch may unexpectedly stash or may block on when recovery is disabled. For any needed change, **dispatch a work item** and let the engine own the live-checkout path; never `Edit`/`Write`/`Bash`-mutate files there yourself. Read-only inspection remains fine.
+**CC never writes into any configured project's `localPath`.** Dispatch a work item and let the engine own either the isolated-worktree or guarded-live path. Read-only inspection remains fine.
 
 **When to recommend hybrid:** the project's build/test/validation genuinely cannot run in an isolated worktree (it needs the real checkout — submodules, a `repo`-managed tree, an emulator/dev-server bound to `localPath`, deep-path tooling), **but** you still want coding agents to work in parallel rather than serialize through the single live checkout. If the *whole* workflow must run on the real tree, use plain `live`. If nothing needs the real tree, stay on `worktree`.