@yemi33/minions 0.1.2424 → 0.1.2425

package/docs/internal-install.md

@@ -0,0 +1,190 @@
+# Internal install & state migration (ISS ProjectFeed-ISS)
+
+One command installs or upgrades the internal Minions package
+(`@opg-microsoft/minions`) from the **ISS `ProjectFeed-ISS` Azure Artifacts npm
+registry** using your existing Azure CLI login, then migrates the existing
+runtime in place — preserving config, SQLite state, notes, plans, knowledge, and
+project links.
+
+No manually created PAT is required, accepted, or stored.
+
+## One command
+
+```powershell
+# Windows (PowerShell)
+scripts\install-internal-minions.ps1
+```
+
+```bash
+# Linux / macOS
+./scripts/install-internal-minions.sh
+```
+
+```bash
+# Any platform, directly (also works from an installed package root)
+node bin/install-internal-minions.js
+```
+
+All three entry points are thin wrappers over `bin/install-internal-minions.js`,
+so behavior cannot drift between platforms.
+
+## Prerequisites
+
+| Requirement | Check | Notes |
+|---|---|---|
+| Azure CLI, signed in | `az account show` | Run `az login` first. The script acquires a short-lived token per run. |
+| Node.js >= 22.5 with npm | `node -v` / `npm -v` | Matches `package.json#engines` (the `node:sqlite` runtime backing the state DB). |
+| Read access to `ProjectFeed-ISS` | The script's own `validate-feed` step | Feed access is proven **before** anything is removed or replaced. |
+
+## Options
+
+| Flag | Default | Purpose |
+|---|---|---|
+| `--version <spec>` | `latest` | Version or dist-tag to install. Resolved to a concrete version before install, so a stale npm metadata cache cannot silently reinstall an older build. |
+| `--registry <url>` | the ISS `ProjectFeed-ISS` feed | Override the Azure Artifacts npm registry. Must be `https`. |
+| `--package <name>` | `@opg-microsoft/minions` | Override the internal package name. Must be scoped. |
+| `--backup-dir <dir>` | `<runtime root>/backups/internal-install-<timestamp>` | Where the pre-migration backup is written. |
+| `--keep-public` | off | Leave an existing `@yemi33/minions` global install in place instead of replacing it. |
+| `--no-restart` | off | Sync runtime files but skip the health-verified restart. |
+| `--force` | off | Proceed even while agents are active (see [Active agents](#active-agents)). |
+| `--dry-run` | off | Print the resolved plan and the exact commands; change nothing. |
+| `--help` | — | Usage. |
+
+Exit codes: `0` success, `1` failure, `2` usage error, `3` refused because agents
+are active.
+
+## What it does, in order
+
+The ordering is the safety contract, not a formality. `planSteps()` in
+`bin/install-internal-minions.js` is the single source of truth and is asserted
+by `test/unit/install-internal-minions.test.js`.
+
+1. **`acquire-token`** — `az account get-access-token --resource 499b84ac-1321-427f-aa17-267ca6975798`
+   (the same ADO resource id `engine/ado-token.js` uses).
+2. **`validate-feed`** — `npm view <package>@<spec> version` against the feed, and
+   resolve `latest` to a concrete version. **A feed that is unreachable, or a
+   version that does not exist, fails here — before anything is removed.**
+3. **`download-artifact`** — `npm pack <package>@<resolved-version> --pack-destination <temp>`
+   downloads the tarball without installing it. **This is what makes the cutover
+   safe:** the artifact is on local disk before the public package is removed, so
+   a feed, network, or auth failure during the global install is recoverable
+   offline. Skipped only when no install will run (see step 6).
+4. **`backup-state`** — checkpoints and copies the SQLite state
+   (`engine/state-operations.js#backupState`: `PRAGMA wal_checkpoint(TRUNCATE)` +
+   `VACUUM INTO`), then copies `config.json`, `routing.md`, `pinned.md`, parks a
+   copy of the downloaded tarball beside the backup, and writes a `manifest.json`
+   describing the from/to packages, the artifact, and the preserved paths.
+   Skipped on a machine with no existing runtime.
+   The backup runs against the **runtime's own** `engine/state-operations.js`,
+   which `minions init` copies into the runtime root and which is therefore always
+   present and version-matched to that runtime's `engine/state.db`. It does not
+   depend on a globally installed CLI: `minions init` deliberately excludes `bin/`
+   from the runtime-root copy, and the published public package predates the
+   `minions state` command. An installed CLI's `minions state backup` is kept only
+   as a fallback for runtime roots that predate the SQL store layout.
+5. **`uninstall-public`** — removes an existing global `@yemi33/minions` so the two
+   packages never race for the same `minions` bin shim. **Gated:** it runs only
+   once `assessCutoverReadiness()` confirms the internal artifact is downloaded
+   (or already installed at the target version) *and* a state backup exists
+   whenever there was a runtime to back up. Skipped with `--keep-public`, or when
+   no public install is present.
+6. **`install-internal`** — `npm install -g <package>@<resolved-version>` against the
+   feed. **If that fails, the script installs the already-downloaded tarball**
+   (`npm install -g <backup-dir>/<package>.tgz` — no registry, no token, so it
+   still works when the feed is exactly what failed) rather than leaving the
+   machine with no CLI. This is also the only step that (re-)links the `minions`
+   bin shim, so it is skipped as idempotent only when the resolved version is
+   already installed **and** `minions` already resolves to it **and** no
+   `uninstall-public` is planned. `npm uninstall -g` takes the shim with the
+   package that owns it, so skipping the install alongside an uninstall would
+   remove the command with nothing to restore it.
+7. **`verify-install`** — re-reads the installed `package.json` from disk and fails
+   loudly if npm did not actually land the resolved version.
+8. **`verify-shim`** — resolves the global npm prefix and proves the `minions`
+   command itself dispatches into the internal package (`minions.cmd` /
+   `minions.ps1` / the sh shim on Windows, the `<prefix>/bin/minions` symlink
+   elsewhere). Owning the package directory is not the same as owning the
+   command: a half-finished cutover can leave `@opg-microsoft/minions` installed
+   while `minions` still runs the public build. A shim still pointing at
+   `@yemi33/minions` is a hard failure with the repair commands printed.
+9. **`sync-init`** — `minions init --force --skip-start`, the supported runtime
+   synchronization. It overwrites `.js`/`.html` runtime files and preserves
+   user-modified `.md` files.
+10. **`restart`** — `minions restart`, which is health-verified
+    (`engine/restart-health.js`: PID + HTTP probe). Skipped with `--no-restart`.
+11. **`cleanup`** — always runs, on success and on every failure path. The
+    temporary npm config always goes; the downloaded artifact is retained (and its
+    path printed) when the run ended with the machine still needing it.
+
+After `sync-init` the script re-checks every runtime path that existed
+beforehand (`config.json`, `engine/state.db`, `notes/`, `notes.md`, `plans/`,
+`knowledge/`, `projects/`, `pinned.md`). A path that existed before and is
+missing after is a hard failure pointing at the backup, not a silent data loss.
+
+## Token handling
+
+- The ADO token is acquired **per run** and is short-lived.
+- It is written **only** into a `0600` temporary npm userconfig inside the OS temp
+  directory. It never reaches `argv`, the process environment, stdout, the
+  runtime root, or the repository.
+- Your existing user `.npmrc` is copied into that temporary config first, so a
+  custom `prefix`, proxy, or other global-install setting keeps applying —
+  replacing the userconfig wholesale would silently relocate a `-g` install.
+- Every line of child-process output and every error message is passed through a
+  redactor that scrubs both the raw token and its base64 form.
+- The temporary config directory is removed in a `finally`, so it is cleaned up on
+  success **and** on every failure path.
+
+## Active agents
+
+Replacing the runtime package rewrites the engine code that running agents are
+executing. The engine's restart/reattachment contract covers an engine restart —
+it does **not** cover rewriting the files underneath a live dispatch.
+
+So the script counts live agent PID files under `<runtime root>/engine/tmp/`
+(both the per-dispatch directory layout and the legacy flat layout, matching
+`engine/shared.js#forEachPidFile`) and **defers with exit code 3** when any are
+alive. Stale PID files from a crashed run do not block anything — each PID is
+liveness-checked.
+
+Wait for `minions status` to go idle, or pass `--force` to override.
+
+## Idempotency
+
+Re-running is safe. When the resolved version is already installed, `minions`
+already resolves to it, and there is no public package left to remove, the
+download and install steps are skipped and the run still converges the runtime
+(`init --force`) and proves health (`restart`). Nothing is uninstalled twice, and
+the temporary npm config is removed either way.
+
+Re-running is also the **repair** path: if a previous run left the internal
+package on disk while `minions` still resolved elsewhere (or nowhere), the plan
+reinstates `download-artifact` + `install-internal` so the shim is re-linked.
+
+## Relationship to `minions update`
+
+`minions update` is the in-place updater for whichever package is already
+installed. This script is the **channel bootstrap**: it is what moves a machine
+onto the internal ProjectFeed-ISS channel (including replacing a public
+`@yemi33/minions` install) and what installs the internal package on a machine
+that has no Minions at all. Once a machine is on the internal channel, routine
+upgrades are `minions update` — or this script again, which is idempotent.
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| `could not acquire an Azure DevOps token` | Not signed in, or no subscription selected | `az login`, then `az account set --subscription <id>` |
+| `could not read <pkg>@<spec> from the feed` | No feed read permission, or the version does not exist | Request Azure Artifacts read on `ProjectFeed-ISS`; check `--version`. Nothing was uninstalled. |
+| `REFUSED: N agent process(es) are still running` | Active dispatches | Wait for idle, or re-run with `--force` |
+| `expected <pkg>@<v> on disk, found …` | Stale npm metadata cache | `npm cache clean --force`, then re-run |
+| `refusing to uninstall @yemi33/minions — …` | The artifact or the backup is missing | Nothing was removed. Re-run; the message names which precondition failed. |
+| `no way to back up the existing runtime state was found` | The runtime root has neither `engine/state-operations.js` nor a resolvable CLI | Nothing was uninstalled. The error lists every path that was probed; run `minions init --force` against the existing install to restore its engine files, then re-run. |
+| `the minions shim … still points at @yemi33/minions` | A previous half-finished cutover left the public shim in place | `npm uninstall -g @yemi33/minions`, then re-run. The install commands are printed with the error. |
+| Feed install failed after the public package was removed | Feed/network failure mid-install | Handled automatically — the script reinstalls from the tarball it downloaded before the uninstall. If that also fails, the retained artifact path and the offline `npm install -g <tarball>` command are printed. |
+
+## See also
+
+- [distribution.md](distribution.md) — publish channels and the fork sync contract
+- [design-state-storage.md](design-state-storage.md) — the SQLite state authority
+- [engine-restart.md](engine-restart.md) — the health-verified restart contract

package/docs/kb-pr3223-cascade-archiving.md

@@ -0,0 +1,16 @@
+# KB PR #3223 - Cascade Archiving of PRDs on Markdown File Archive
+
+> Historical implementation note. PRD persistence moved to SQLite after this
+> change; filesystem reader, sidecar, and structural-test guidance from the
+> original implementation is no longer current.
+
+## Durable contract
+
+- `source_plan` is a plan Markdown basename.
+- Plan archive responses retain their documented compatibility fields.
+- PRD archive and cascade updates use `engine/prd-store.js` transactions.
+- Work-item cancellation uses scoped SQL work-item mutations.
+
+Use the current `handlePlansArchive` implementation and its behavioral tests as
+the source of truth. Do not reintroduce PRD file scanning or backup-sidecar
+logic.

package/docs/kb-pr696-merge-conflict-docs.md

@@ -0,0 +1,23 @@
+# KB PR #696 – Merge Conflict Resolution in KB-Sweep Documentation
+
+PR #696 resolved a merge conflict in `docs/kb-sweep.md:97-103` where both branch and main branches cited stale line numbers to `engine/kb-sweep.js`. Upstream code shifts had invalidated both references. Resolution consolidated the "Pass 1, 1.5, and 2" structure and verified the correct current location of `NORMALIZE_CONCURRENCY = 5` at `engine/kb-sweep.js:30`.
+
+## Key Findings
+
+- Merge conflict in `docs/kb-sweep.md:97-103` ("Pass 3 — Per-Entry Rewrite" section) with stale line citations
+- Branch cited `engine/kb-sweep.js:L26`, main cited `L30` with outdated "Pass 1 and 2" wording
+- Root cause: upstream commits shifted line numbers; neither reference remained valid post-merge
+- Resolved by merging branch's "Pass 1, 1.5, and 2" structure with main's corrected line reference to `engine/kb-sweep.js:30`
+- Verified `NORMALIZE_CONCURRENCY = 5` present at `engine/kb-sweep.js:30` in merged state
+- Syntax validation passed for `engine/shared.js`, `engine/kb-sweep.js`, `engine.js`, `dashboard.js`
+
+## Action Items
+
+- When resolving doc citation conflicts, re-verify current line numbers in merged source rather than trusting either branch's reference
+
+## References
+
+- PR #696: https://github.com/opg-microsoft/minions/pull/696
+- Merge commit: b91cb386
+- Fix comment: https://github.com/opg-microsoft/minions/pull/696#issuecomment-4905945906
+- Correct citation: `engine/kb-sweep.js:30` (`NORMALIZE_CONCURRENCY = 5`)

package/docs/kb-sweep.md

@@ -177,9 +177,9 @@ Sweep liveness is coordinated through `engine/kb-sweep-state.json` so the dashbo
 
 The state file plus runner PID liveness is the source of truth; the detached runner has no dashboard-owned in-memory lifecycle (source: [`engine/kb-sweep.js:747-778`](../engine/kb-sweep.js#L747), [`dashboard.js:7642-7654`](../dashboard.js#L7642)). A separate `engine/kb-swept.json` is written after each successful non-dry-run sweep with the human-readable summary shown by the dashboard's "swept N days ago" badge (source: [`engine/kb-sweep.js:1019-1024`](../engine/kb-sweep.js#L1019)).
 
-## Automatic Periodic Sweep (opt-in)
+## Automatic Periodic Sweep
 
-The engine tick loop can also auto-spawn the KB sweep without dashboard interaction. Gated by `engine.autoConsolidateMemory` (default `false` — source: [`engine/shared.js`](../engine/shared.js) `ENGINE_DEFAULTS.autoConsolidateMemory`):
+The engine tick loop can also auto-spawn the KB sweep without dashboard interaction. Gated by `engine.autoConsolidateMemory` (default `true`; set `false` to disable — source: [`engine/shared.js`](../engine/shared.js) `ENGINE_DEFAULTS.autoConsolidateMemory`):
 
 - When `engine.autoConsolidateMemory: true`, every tick the engine consults `shouldAutoSweep()` from [`engine/kb-sweep.js`](../engine/kb-sweep.js) and, when the 4-hour cadence has elapsed since the last completion, calls `spawnSweepRunnerDetached()` to fire-and-forget a fresh `engine/kb-sweep-runner.js` process (source: [`engine.js`](../engine.js) tick step 2.1).
 - The inbox→`notes.md` consolidation runs every tick *regardless* of this flag via `consolidateInbox()`; `autoConsolidateMemory` controls **only** the heavier `knowledge/` sweep.

package/docs/keep-processes.md

@@ -35,7 +35,7 @@ Set `meta.keep_processes: true` on the WI; agent writes `agents/<id>/keep-pids.j
 ## Lifecycle
 
 - **Validation:** sidecar shape + workdir checked in `onAgentClose`. Failure → non-retryable `failure_class: invalid-keep-processes-{workdir,schema}`.
-- **Sweep:** [`engine/keep-process-sweep.js`](../engine/keep-process-sweep.js) reaps at boot and every 30 ticks. Dead PIDs are pruned; expired TTL → process killed via `shared.killGracefully` then `killImmediate`.
+- **Sweep:** [`engine/keep-process-sweep.js`](../engine/keep-process-sweep.js) reaps at boot and every 180 ticks. Dead PIDs are pruned; expired TTL → process killed via `shared.killGracefully` then `killImmediate`.
 - **No healthcheck:** unlike managed-spawn, `keep_processes` does not gate WI completion on first-healthy. If the child crashes immediately the agent still succeeds — by design (ad-hoc helper semantics).
 
 ## Caps
@@ -43,6 +43,13 @@ Set `meta.keep_processes: true` on the WI; agent writes `agents/<id>/keep-pids.j
 - **PIDs:** ≤5 per sidecar.
 - **TTL:** ≤1440 min (24h). Default 60.
 - **Cwd:** must exist, resolve inside a git worktree, and stay at or below the current dispatch root from `MINIONS_AGENT_CWD`. Monorepo subdirs are allowed. In worktree mode, pointing at `project.localPath` is rejected before the wrapper decides which descendants survive. `keep_processes` dispatches use the cold spawn wrapper rather than the ACP pool so descendant ownership remains enforceable.
+- **Manual kill API:** `POST /api/keep-processes/kill` accepts only a safe
+  `agentId` and a numeric positive PID declared by a currently valid sidecar;
+  rejected requests do not kill a process or rewrite the file. The endpoint
+  atomically claims the declaration, verifies the OS process start identity,
+  and restores the claimed record if identity changes or termination fails.
+  Its filesystem-mtime identity anchor is preserved after both rejected and
+  successful partial-PID updates.
 
 After acceptance, the engine adds project/work-type/checkout-mode/dispatch-root
 provenance to the sidecar. Boot sweep uses it to kill and unlink any retained

package/docs/live-checkout-mode.md

@@ -355,7 +355,7 @@ The engine has no opinion about local branches; this hygiene is the operator's r
 Live-checkout mode is deliberately small. These are NOT supported and will not be added:
 
 - **No `auto` mode.** The choice between `worktree` and `live` is per-project and operator-set. The engine will not auto-detect submodules / `repo` workspaces and silently switch modes.
-- **No auto-stash on dirty refusal _by default_.** Out of the box the engine refuses and exits; it never `git stash`es to "make room" for a dispatch, because that silently mutates the operator's tree and conflates engine state with operator state. The operator can **opt in** per-project (`project.liveCheckoutAutoStash`) or fleet-wide (`engine.liveCheckoutAutoStash`) to auto-stash instead of refusing — see [2b](#2b-opt-in-auto-stash-on-dirty-w-mqtvnnj1000357fa). Even then the engine never **pops** the stash on the operator's behalf. (The `liveCheckoutAutoReset` escape hatch — **OFF by default** as of W-mrawgw4q000a6bff, and even when enabled now only runs as a last-resort fallback *after* auto-stash fails or is disabled — **discards** rather than stashes; set it to `true` per-project / fleet-wide to opt in. See [§2b](#2b-opt-in-auto-reset-on-dirty-livecheckoutautoreset-w-mqvejug6000eeb20).)
+- **Auto-stash is ON fleet-wide by default (W-mrawiym8000c42c9).** Out of the box a dirty tree is `git stash push --include-untracked`'d before dispatch instead of refusing, because the stash is non-destructive and recoverable via `git stash pop` — see [2b](#2b-auto-stash-on-dirty-w-mqtvnnj1000357fa). The operator can **opt out** per-project (`project.liveCheckoutAutoStash: false`) or fleet-wide (`engine.liveCheckoutAutoStash: false`) to restore the terminal dirty-tree refusal instead. Even with auto-stash on, the engine never **pops** the stash on the operator's behalf. (The `liveCheckoutAutoReset` escape hatch — **OFF by default** as of W-mrawgw4q000a6bff, and even when enabled now only runs as a last-resort fallback *after* auto-stash fails or is disabled — **discards** rather than stashes; set it to `true` per-project / fleet-wide to opt in. See [§2b](#2b-opt-in-auto-reset-on-dirty-livecheckoutautoreset-w-mqvejug6000eeb20).)
 - **No concurrent dispatches per project.** The cap is 1; raising it would require per-WI subdirectories, which live mode explicitly does not provide.
 - **No per-WI subdirectory isolation.** Live mode is one-checkout-per-project by design. If you need isolation, use `checkoutMode: 'worktree'` (the default).
 - **No per-WI override.** `checkoutMode` is per-project only. There is no `meta.checkoutMode` on a work item that overrides the project setting.

package/docs/managed-spawn.md

@@ -57,7 +57,12 @@ The sidecar lives at `<MINIONS_DIR>/agents/<agentId>/managed-spawn.json` and is
 }
 ```
 
-The renderer in [`buildManagedSpawnHint`](../engine/managed-spawn.js) at `engine/managed-spawn.js:419` emits this exact shape (with allowlist + cap reminders) into the agent's prompt whenever the work item has `meta.managed_spawn: true`. Treat the rendered hint as the source of truth — if this doc and the hint drift, the hint wins.
+The renderer in [`buildManagedSpawnHint`](../engine/managed-spawn.js) emits this exact shape (with allowlist + cap reminders) into the agent's prompt whenever the work item has `meta.managed_spawn: true`. Treat the rendered hint as the source of truth — if this doc and the hint drift, the hint wins.
+
+For an opted-in dispatch, the sidecar is mandatory. Completion acceptance reads
+only the canonical running agent's directory and requires `written_by` and
+`wi_id` to match that agent and work item exactly; a missing file or stale
+identity fails with `invalid-managed-spawn` instead of completing successfully.
 
 The engine also confines every spec to the dispatch root: `cwd` must resolve at
 or below `MINIONS_AGENT_CWD`. In worktree mode, `project.localPath` is rejected
@@ -176,8 +181,9 @@ Single quotes (`'…'`) work the same way. No `powershell -Command "& '<path>' <
                                     ▼
 ┌───────────────────────────────────────────────────────────────────┐
 │ 2. evaluateManagedSpawnAcceptance(agentId)                        │
-│    - Validates schema, allowlists, caps                           │
-│    - Rejects → ERROR + alert + sidecar deleted                    │
+│    - Requires the canonical agent/WI sidecar                      │
+│    - Validates identity, schema, allowlists, caps                 │
+│    - Rejects → ERROR + alert (+ delete when present)              │
 │      failure_class: invalid-managed-spawn (non-retryable)         │
 └───────────────────────────────────┬───────────────────────────────┘
                                     │ accepted
@@ -247,6 +253,9 @@ Outcome: if WI 2 fails, the spec stays alive (TTL-managed) and the next dispatch
 | Dashboard | http://localhost:7331/engine → "Managed Processes" |
 
 The list endpoint returns an ETag; pass it as `If-None-Match` on follow-up polls to get `304 Not Modified` when nothing changed. The dashboard panel does this automatically.
+API process names use the same kebab-case/length validator as sidecar specs,
+project filters must name a configured project, and log-stream `tail` is a
+single integer from 1 byte through 1 MiB (default 64 KiB).
 
 ### Force a restart / kill
 
@@ -255,6 +264,15 @@ The list endpoint returns an ETag; pass it as `If-None-Match` on follow-up polls
 | Kill (PID terminated, removed from state) | `POST /api/managed-processes/kill` `{"name":"…"}` | Per-row "Kill" button |
 | Restart (kill old PID, respawn from saved state, kick first healthcheck) | `POST /api/managed-processes/restart` `{"name":"…"}` | Per-row "Restart" button |
 
+Both controls bind the request to the selected row's `pid` + `started_at`
+generation and verify the live OS process start identity before killing. A
+concurrent replacement, recycled PID, or failed kill returns `409` without
+deleting the surviving generation; restart also reserves the name before
+spawning so concurrent calls cannot orphan duplicate generations. Engine batch
+spawns use the same reservation protocol, first-health and boot-probe writes
+must match the reserved generation, and failed rollback kills remain as
+immediately-expired tracked rows for the sweep to retry.
+
 Killing a spec from outside Minions (raw `Stop-Process`) leaves a stale SQL row until the next 30-tick sweep notices the dead PID. Prefer the API.
 
 ### View logs

package/docs/named-agents.md

@@ -83,8 +83,8 @@ defaults (`WORKSPACE_MANIFEST_DEFAULTS` in `engine/shared.js`):
 | `memory_scope` | `'shared'` | One of `private`, `shared`, `read-only-shared`. |
 
 Enforcement helpers (also in `engine/shared.js`): `validateWorkspaceManifest`,
-`resolveAgentManifest`, `agentCanUseRepo`, `agentCanUseTool`, `agentCanFetchUrl`,
-`mergeManifestAllowedTools`. Today the engine actively enforces (a) the
+`resolveAgentManifest`, `agentCanUseRepo`, and `mergeManifestAllowedTools`. Today the
+engine actively enforces (a) the
 **repo gate** at dispatch time in `engine.js spawnAgent`
 (`FAILURE_CLASS.WORKSPACE_MANIFEST_REPO`, non-retryable) and (b) the **tool merge** into the
 runtime `--allowedTools` flag at spawn time. Defaults are permissive — an agent with no
@@ -105,6 +105,7 @@ Routing maps a `work_type` to a `preferred` agent and a `fallback`:
 | implement:large | rebecca | dallas |
 | review | ripley | lambert |
 | fix | `_author_` | `_any_` |
+| build-fix-complex | `_author_` | dallas |
 | plan | ripley | rebecca |
 | plan-to-prd | lambert | rebecca |
 | explore | ripley | rebecca |

package/docs/plan-lifecycle.md

@@ -9,12 +9,12 @@ How plans go from idea to verified, running code.
   → agent writes plan markdown (plans/plan-*.md)
   → human reviews and explicitly runs plan-to-prd
   → agent converts plan into structured PRD items with acceptance criteria
-  → engine materializes PRD items as work items (PL-W001, PL-W002, ...)
+  → engine materializes each PRD item under the same id as a work item (P-001, P-002, ...)
   → engine dispatches work items respecting dependency order
   → agents implement each item, create PRs
   → engine auto-reviews PRs, handles feedback loops
-  → all items done → engine creates VERIFY task
-  → verify agent builds everything, starts webapp, writes testing guide
+  → all items terminal → engine creates VERIFY task(s) for completed work
+  → verify agent builds everything, starts a webapp if applicable, writes testing guide
   → human archives the PRD/plan from the dashboard when ready
 ```
 
@@ -26,29 +26,29 @@ PRD items can declare `depends_on: ["P001", "P003"]`. The engine won't dispatch
 
 ### Branch Merging at Spawn
 
-When an agent is spawned for a work item with dependencies, the engine merges the dependency PR branches into the worktree **before the agent starts**. This solves the problem where dependencies have PRs but haven't been merged to `main` yet.
+When an agent is spawned for a work item with dependencies, the engine merges same-project dependency PR branches into the worktree **before the agent starts**. Cross-repo dependencies are exposed as advisory refs instead of being merged. This lets later items inspect prerequisite code that has not reached the target repo's main branch.
 
 ```
-Agent gets work item PL-W006 (plan item P009)
+Agent gets work item P009
   depends_on: ["P006", "P007"]
 
 spawnAgent():
   1. Create worktree from main:
-     git worktree add ../worktrees/work/PL-W006 -b work/PL-W006 main
+     git worktree add ../worktrees/work/P009 -b work/P009 main
 
   2. Resolve dependencies:
-     P006 → work item PL-W001 → PR-4970100 → branch work/PL-W001
-     P007 → work item PL-W002 → PR-4970101 → branch work/PL-W002
+     P006 → work item P006 → PR-4970100 → branch work/P006
+     P007 → work item P007 → PR-4970101 → branch work/P007
 
   3. Merge dependency branches:
-     git fetch origin work/PL-W001 work/PL-W002
-     git merge origin/work/PL-W001 --no-edit
-     git merge origin/work/PL-W002 --no-edit
+     git fetch origin work/P006 work/P007
+     git merge origin/work/P006 --no-edit
+     git merge origin/work/P007 --no-edit
 
   4. Agent starts with all dependency changes present
 ```
 
-If a merge conflict occurs, it's logged as a warning. The agent will see conflict markers and can resolve them, or the task will fail and get retried after the dependency PRs are merged to `main`.
+If dependency merging still conflicts after the engine's clean reset/re-merge attempt, the engine aborts the partial merge and fails the dispatch **before spawning the runtime** with `FAILURE_CLASS.MERGE_CONFLICT`. When it can identify the conflicting dependency branch it also queues a conflict-fix work item on that branch; the dependent item waits for the branch to become mergeable.
 
 ### Resolution Chain
 
@@ -57,17 +57,17 @@ depends_on: ["P-43e5ac28"]
   → find work items where id = "P-43e5ac28" (across all projects)
   → find PRs where prdItems includes "P-43e5ac28"
   → extract branch names from those PRs
-  → fetch + merge into worktree
+  → fetch + merge into worktree (same project), or expose an advisory ref (cross-repo)
 ```
 
 ## Plan Completion
 
-When all PRD items reach `done` or `failed` status, `checkPlanCompletion()` fires:
+When every materialized PRD item reaches a `PLAN_TERMINAL_STATUSES` value (`done`/legacy-done, `failed`, or `cancelled`), `checkPlanCompletion()` fires:
 
 1. **Completion summary** written to `notes/inbox/` with results, timing, and PR list
-2. **Verification task** created (type `verify`, priority `high`) — see below
+2. **Verification task(s)** created (type `verify`, priority `high`) when at least one item completed — one per touched project; see below
 3. **PR work item** created for shared-branch plans (to merge the feature branch)
-4. **PRD status** persisted as `completed` with `_completionNotified`; files stay active until manual archive
+4. **PRD status** persisted as `completed` with `_completionNotified`; the SQL record stays active until manual archive
 
 `checkPlanCompletion()` also **self-heals a stale `completed` PRD**: if a completed plan later gains an unmaterialized item or one of its items regresses off a terminal status, the PRD is reverted to `active` (status flipped, `_completionNotified` cleared) so the materializer recreates the missing work item and the normal completion flow can run again.
 
@@ -75,16 +75,16 @@ When all PRD items reach `done` or `failed` status, `checkPlanCompletion()` fire
 
 ## Verification Task
 
-The verification task (`planItemId: "VERIFY"`) is the final step. It:
+The verification task (`itemType: "verify"`, `type: "verify"`) is the final step. It:
 
-1. **Creates one worktree per affected project** with all PR branches merged in — not separate worktrees per branch. This means the agent builds and tests from a single directory per project with all changes combined.
+1. **Creates one worktree per affected project.** Parallel-branch plans merge that project's PR branches into it; shared-branch plans check out `origin/<feature_branch>` without merging PR branches.
 
 2. **Builds and tests** every affected project from its worktree.
 
-3. **Starts the webapp** on localhost if applicable, and keeps it running so the user can see it.
+3. **Starts and smoke-checks the app** on localhost when applicable, leaving it running only when it must survive verification.
 
-4. **Writes a canonical manual testing guide** (`prd/guides/verify-*.md`) plus
-   an inbox copy (`notes/inbox/verify-*.md`) for merge decisions, containing:
+4. **Writes a canonical manual testing guide** (`prd/guides/verify-*.md`) and,
+   only after successful verification, an inbox copy (`notes/inbox/verify-*.md`) for merge decisions, containing:
    - Build/test status table per project
    - Feature-by-feature testing steps based on acceptance criteria
    - Integration points to verify across projects
@@ -97,20 +97,20 @@ The verification task (`planItemId: "VERIFY"`) is the final step. It:
 ```
 # project-a — 3 PRs merged into one worktree
 cd ~/project-a
-git fetch origin "work/PL-W001" "work/PL-W002" "work/PL-W003" "main"
-git worktree add "../worktrees/verify-my-plan-2026-03-15" "origin/main"
-cd "../worktrees/verify-my-plan-2026-03-15"
-git merge "origin/work/PL-W001" --no-edit
-git merge "origin/work/PL-W002" --no-edit
-git merge "origin/work/PL-W003" --no-edit
+git fetch origin "work/P001" "work/P002" "work/P003" "main"
+git worktree add "../worktrees/verify-project-a-my-plan-<uid>" "origin/main"
+cd "../worktrees/verify-project-a-my-plan-<uid>"
+git merge "origin/work/P001" --no-edit
+git merge "origin/work/P002" --no-edit
+git merge "origin/work/P003" --no-edit
 
 # project-b — 2 PRs merged into one worktree
 cd ~/project-b
-git fetch origin "feat/PL-W004" "feat/PL-W005" "master"
-git worktree add "../worktrees/verify-my-plan-2026-03-15" "origin/master"
-cd "../worktrees/verify-my-plan-2026-03-15"
-git merge "origin/feat/PL-W004" --no-edit
-git merge "origin/feat/PL-W005" --no-edit
+git fetch origin "work/P004" "work/P005" "master"
+git worktree add "../worktrees/verify-project-b-my-plan-<uid>" "origin/master"
+cd "../worktrees/verify-project-b-my-plan-<uid>"
+git merge "origin/work/P004" --no-edit
+git merge "origin/work/P005" --no-edit
 ```
 
 The verify agent and the user can then build and run from these paths.