its-magic 0.1.2-39 → 0.1.2-42

package/template/.cursor/scratchpad.md

@@ -15,7 +15,7 @@
 # - DONE: 0|1 (stop hook loops)
 MAGIC_CONTEXT_STRICT=1
 LOOP_UNTIL_GREEN=1
-RUN_TESTS_ON_EDIT=0
+RUN_TESTS_ON_EDIT=1
 AUTO_IMPLEMENTATION_LOOP=1
 AUTO_LOOP_MAX_CYCLES=5
 AUTO_PAUSE_REQUEST=0
@@ -41,13 +41,24 @@ MAGIC_BENCH_SESSION=
 # - AUTO_EXECUTE_ON_BLOCK: stop|skip (behavior when a planned item blocks)
 # - AUTO_EXECUTE_SELECTION: planned_then_priority
 # - AUTO_TEAM_SCOPE_ENFORCE: 0|1 (when TEAM_MODE=1, enforce TEAM_MEMBER + ACTIVE_TASK_IDS)
+# Optional bug-queue mode (US-0087) — default-off when absent/unset after merge
+# - AUTO_BUG_QUEUE: 0|1 (1 = enable bug-targeted /auto; mutex vs AUTO_BACKLOG_DRAIN without bug-target argv)
+# - AUTO_BUG_TARGET: all-open|BUG-#### (required when AUTO_BUG_QUEUE=1 unless bug-target= argv supplies target)
+# - AUTO_BUG_MAX_ITEMS: non-negative integer (0 or unset = no cap for all-open queue per run)
+# - AUTO_BUG_ON_BLOCK: stop|skip (bug segment pause/stop boundary)
+# Quiet mode (US-0088) — suppress routine per-phase success chatter only
+# - AUTO_QUIET: 0|1 (default 0; 1 = quiet routine notifications)
+#   Non-suppressible: decision_gate, errors, pause, loop_max, blocked, missing inputs.
+#   Orthogonal to TOKEN_PROFILE (DEC-0035 / US-0080) — TOKEN_PROFILE controls
+#   context breadth / token cost, not notification policy.
+AUTO_QUIET=0
 AUTO_FLOW_MODE=auto_until_decision
 PHASE_MODE=auto
 PERMISSION_MODE=auto
 AUTO_INSTALL_DEPS=1
 AUTO_RELEASE_NOTES=1
-AUTO_BACKLOG_DRAIN=0
-AUTO_BACKLOG_MAX_STORIES=1
+AUTO_BACKLOG_DRAIN=1
+AUTO_BACKLOG_MAX_STORIES=10
 AUTO_BACKLOG_ON_BLOCK=stop
 AUTO_STORY_SELECTION=priority_then_backlog_order
 AUTO_EXECUTE_BULK=0
@@ -55,6 +66,10 @@ AUTO_EXECUTE_MAX_ITEMS=1
 AUTO_EXECUTE_ON_BLOCK=stop
 AUTO_EXECUTE_SELECTION=planned_then_priority
 AUTO_TEAM_SCOPE_ENFORCE=1
+AUTO_BUG_QUEUE=0
+AUTO_BUG_TARGET=
+AUTO_BUG_MAX_ITEMS=0
+AUTO_BUG_ON_BLOCK=stop
 #
 # `/auto` phase role policy (US-0069 / DEC-0051)
 # - AUTO_ROLE_RESEARCH: po|tech-lead (empty -> default tech-lead)
@@ -101,11 +116,21 @@ SPRINT_BULK_MAX_STORIES=5
 SPRINT_BULK_MAX_SPRINTS=3
 SPRINT_BULK_SELECTION=priority_then_backlog_order
 #
-# Remote execution
-# - REMOTE_EXECUTION: 0|1
-# - REMOTE_CONFIG: path to remote config
-REMOTE_EXECUTION=0
+# Remote execution (US-0086 / US-0084 / US-0064)
+# - REMOTE_EXECUTION: 0|1 — 0 skips remote.json validation (zero overhead; DEC-0070).
+# - REMOTE_CONFIG: path to dev/Cursor remote JSON (default .cursor/remote.json).
+# - AUTO_REMOTE_AUTOMATION_PROFILE: off|deterministic_v1 (default off; manual
+#   mode remains unchanged unless explicitly enabled for automation workflows).
+# - AUTO_REMOTE_ENVIRONMENT_LABEL: local|docker|ssh (names-only evidence label
+#   for execute/qa/release handoffs when automation routing is used).
+#   Release/QA SSH/Docker connectivity fields live in docs/engineering/release-targets.json
+#   (ssh-server, dockerOverSsh); map WSL vs SSH vs Docker-over-SSH in
+#   docs/engineering/runtime-connectivity.md and docs/engineering/us-0084-remote-e2e.md.
+# - Summary helper (names-only stdout): python scripts/remote_config_summary.py
+REMOTE_EXECUTION=1
 REMOTE_CONFIG=.cursor/remote.json
+AUTO_REMOTE_AUTOMATION_PROFILE=off
+AUTO_REMOTE_ENVIRONMENT_LABEL=local
 #
 # Sync policy
 # - SYNC_POLICY_MODE: disabled|manual|by_phase|by_milestone|custom_phase_list
@@ -114,10 +139,10 @@ REMOTE_CONFIG=.cursor/remote.json
 # - ALLOW_AUTO_PUSH: 0|1 (default off; explicit opt-in required)
 # - AUTO_PUSH_BRANCH_ALLOWLIST: comma-separated branches/patterns eligible for
 #   auto-push. Protected/default branches are denied unless allowlisted.
-SYNC_POLICY_MODE=manual
+SYNC_POLICY_MODE=by_phase
 SYNC_CUSTOM_PHASES=
-ALLOW_AUTO_PUSH=0
-AUTO_PUSH_BRANCH_ALLOWLIST=
+ALLOW_AUTO_PUSH=1
+AUTO_PUSH_BRANCH_ALLOWLIST=main
 #
 # Knowledge curation
 # - EARLY_RESEARCH: 0|1 (PO/TL search web during intake/architecture)

package/template/.cursorignore

@@ -0,0 +1,5 @@
+# Agent exclusion — secrets must not be ingested by AI tools (US-0085 / DEC-0071)
+.env
+.env.local
+.env.*
+!.env.example

package/template/.env.example

@@ -0,0 +1,28 @@
+# .env.example — operator-local secret values (US-0085 / DEC-0071)
+# Copy to .env, fill in values, source before remote/SSH/release ops.
+# .env is gitignored and must NEVER be committed.
+# This file lists names only — no secret values.
+
+# ── From template/.cursor/remote.json (Cursor dev/remote targets) ──
+REMOTE_DOCKER_TOKEN=
+REMOTE_SSH_USER=
+REMOTE_SSH_KEY_PATH=
+
+# ── From docs/engineering/release-targets.json (release/QA targets) ──
+PUBLIC_DOMAIN=
+CHOCO_API_KEY=
+GITHUB_TOKEN=
+DOCKER_TOKEN=
+DOCKER_RUNTIME_HOST=
+AWS_PROFILE=
+APP_DOMAIN=
+APP_IP=
+CUSTOM_DOMAIN=
+CUSTOM_IP=
+SSH_HOST=
+SSH_USER=
+SSH_PRIVATE_KEY=
+RUNTIME_DOMAIN=
+RUNTIME_IP=
+DOCKER_HOST=
+DOCKER_CONTEXT=

package/template/README.md

@@ -44,6 +44,10 @@ Pick one method:
 | Chocolatey | `choco install its-magic` (Admin shell) |
 | Homebrew | `brew tap USER/tap && brew install its-magic` |
 
+### Global Linux install: empty `install_include_paths` (CRLF manifest)
+
+If **`its-magic --target <repo> --mode missing`** fails with **`[INSTALL_MANIFEST_ERROR] install_include_paths section is empty`** on Debian/Linux while the packaged manifest still lists paths, the global install likely has **CRLF** line endings in **`installer-owned-paths.manifest`** (visible as **`^M$`** with **`cat -A`**). **Fix in-tree** from **`0.1.2-41`**: **`installer.sh`** strips trailing carriage returns before section matching; **`.gitattributes`** keeps **`*.manifest`** LF; **`prepublishOnly`** runs **`guard_installer_publish`**. **Upgrade**: install a build **≥ `0.1.2-41`** (or reinstall from a fresh **`npm pack`** tarball after pull). Older tarballs such as **`its-magic@0.1.2-40`** may remain broken until republished — see **`docs/engineering/architecture.md`** **`# BUG-0008`**.
+
 ### 2) Apply to a repo
 
 New repo:

package/template/docs/engineering/auto-orchestration-reference.md

@@ -7,11 +7,38 @@
 - tech-lead
 
 ## Execution model
-- `/auto` is an orchestrator only. It must not execute phase work directly.
-- For each phase, spawn a fresh subagent context for that phase role.
+- `/auto` is a **spawn-only orchestrator**: it schedules materialization, spawns
+  fresh **phase-role** subagents, and verifies phase boundaries—it **must not**
+  execute lifecycle phase work, perform phase-role duties, or author **phase
+  deliverables** in the orchestrator context.
+- For each phase, **spawn a fresh subagent** for that phase’s canonical role;
+  phase output must arrive only via artifacts and handoff files (no in-turn
+  orchestrator execution of that phase).
 - Phase context transfer happens only through artifacts and handoff files.
 - Scope is process/workflow orchestration only. Do not claim runtime product
   orchestration changes.
+- **Bug-queue mode** (**`US-0087`**) uses the same **spawn-only** model: schedule
+  materialization and spawn phase-role subagents per bug segment — **never** in-turn
+  **`execute`**, **`qa`**, or other lifecycle work in the orchestrator context.
+  Missing spawn → **`AUTO_ORCHESTRATOR_PHASE_EXECUTION`** (**`BUG-0006`**,
+  **`US-0069`**, **`DEC-0051`**).
+
+## Spawn-boundary integrity (BUG-0006 / US-0080)
+
+This gate is **orthogonal** to per-phase isolation (**DEC-0029**, see
+`decisions/DEC-0029.md`) and strict runtime proof (**DEC-0038**, see
+`decisions/DEC-0038.md`): satisfying one does not excuse skipping the others.
+
+- **Forbidden**: using the orchestrator context to **perform** a lifecycle phase
+  instead of **spawning** the required role subagent (for example in-turn
+  **`architecture`**, **`execute`**, or **`qa`** work attributed to the
+  orchestrator).
+- **Fail fast** with **`AUTO_ORCHESTRATOR_PHASE_EXECUTION`**. **Remediation**:
+  stop; spawn a **fresh** subagent for the canonical **`phase_id`** and **`role`**
+  per the phase→role matrix (**DEC-0051**); continue only through artifacts and
+  handoffs. **Do not** overload **`PHASE_CONTEXT_ISOLATION_VIOLATION`** or
+  **`RUNTIME_PROOF_*`** for a spawn-boundary violation—those address wrong-writer
+  isolation breaks and attestation failures, not missing spawn.
 
 ## Per-phase isolation enforcement (US-0048 / DEC-0029)
 
@@ -190,7 +217,7 @@ behavior applies otherwise.
 
 ### Plan materialization pipeline (evaluation order)
 
-On every `/auto` entry (including resume, backlog-drain, bulk execute, and
+On every `/auto` entry (including resume, backlog-drain, bug-queue, bulk execute, and
 team-mode runs), **recompute** from merged scratchpad:
 
 1. Parse merged scratchpad policy inputs for phase selection + `SECURITY_REVIEW`.
@@ -224,7 +251,8 @@ team-mode runs), **recompute** from merged scratchpad:
 
 After computing the **resolved phase plan**, resolve the **nominal** start
 phase using **Deterministic resume-source precedence** (explicit `start-from`
-→ `resume_brief` → `state` fallback → fail-fast).
+→ **`bug-target=`** argv (when present) → merged scratchpad → `resume_brief` →
+`state` fallback → fail-fast).
 
 Then **intersect**:
 
@@ -267,6 +295,19 @@ continuation breadcrumbs) including:
 - `phase_boundary` (completed `phase_id`)
 - `next_scheduled_phase` (or `none` when complete/stopped)
 
+**`US-0087` bug-queue extensions** (when bug scheduler is active or segment is
+bug-scoped; see **`architecture.md`** **`# US-0087`**):
+
+- `segment_work_item_kind` (`story|bug`)
+- `active_bug_id` (`BUG-####` or `(none)`)
+- `bug_queue_position` (1-based into **OPEN** ordering for `all-open`, or `(none)`)
+- `bug_queue_remaining` (integer or `(none)`)
+- `backlog_drain_active` (boolean — story **`AUTO_BACKLOG_DRAIN`** drives **this** run)
+- `bug_queue_active` (boolean — bug scheduler drives **this** run)
+
+**Invariant**: `backlog_drain_active` and `bug_queue_active` must **not** both be
+true for the same materialized run (scheduler mutex).
+
 ## Inputs
 - Merged scratchpad policy (`US-0073` / `DEC-0055`): resolve flags from **local >
   materialized `.cursor/scratchpad.md` > `.cursor/scratchpad.local.example.md`**
@@ -287,11 +328,69 @@ continuation breadcrumbs) including:
 - `TEAM_MODE`, `TEAM_MEMBER`, `ACTIVE_TASK_IDS` from merged scratchpad context
 - Current product and engineering docs
 - Optional explicit argument: `start-from=<phase>`
+- Optional explicit argument: **`bug-target=BUG-####`** or **`bug-target=all-open`**
+  (**`US-0087`**; parsed before merged scratchpad scheduler keys)
 - Optional explicit argument: `--execute-bulk` (one-run explicit override)
+- `AUTO_BUG_QUEUE`, `AUTO_BUG_TARGET`, `AUTO_BUG_MAX_ITEMS`, `AUTO_BUG_ON_BLOCK`
+  from merged scratchpad (**`US-0087`**)
 - Resume-source artifacts:
   - `handoffs/resume_brief.md`
   - `docs/engineering/state.md`
 
+## Automation remote routing contract (US-0086)
+
+This contract is deterministic and default-off. It composes with `US-0064`,
+`DEC-0070`, `US-0085`, and `DEC-0071`.
+
+Automation profile controls (merged scratchpad):
+
+- `AUTO_REMOTE_AUTOMATION_PROFILE`: `off|deterministic_v1`
+- `AUTO_REMOTE_ENVIRONMENT_LABEL`: `local|docker|ssh` (names-only evidence)
+- `REMOTE_EXECUTION`: `0|1` (remote config validation gate from `US-0084`)
+- `REMOTE_CONFIG`: canonical remote config path
+
+Mode split:
+
+- `AUTO_REMOTE_AUTOMATION_PROFILE=off` -> preserve manual/local behavior; no
+  silent remote reroute.
+- `AUTO_REMOTE_AUTOMATION_PROFILE=deterministic_v1` -> routing policy may resolve
+  Docker/SSH/local targets for automation workflows.
+
+NL intent resolution (v1 literal):
+
+- Parse only the exact phrase `start container <target_id>`.
+- Resolve `<target_id>` against canonical enabled `targets[].id`.
+- Unknown id -> fail closed `REMOTE_TARGET_UNKNOWN`.
+- Known but disabled id -> fail closed `REMOTE_TARGET_DISABLED`.
+
+Routing precedence when profile is enabled:
+
+1. Explicit NL intent target (`start container <target_id>`).
+2. Canonical target validation (`targets[].id`, enabled state).
+3. Heuristic fallback (documented file-class matrix).
+4. Local default when no remote target is selected.
+
+Fail-closed reason codes (locked by `architecture.md` `# US-0086`):
+
+- `REMOTE_AUTOMATION_MODE_OFF`
+- `REMOTE_TARGET_UNKNOWN`
+- `REMOTE_TARGET_DISABLED`
+- `REMOTE_TARGET_UNROUTABLE`
+
+Evidence tuple contract for execute/qa/release handoffs and `state.md`:
+
+- `target_id`
+- `environment_label`
+- `automation_profile`
+- `routing_source` (`explicit_intent|heuristic_fallback|local_default`)
+- `secret_surface=names_only`
+
+Security continuity:
+
+- Automation must not read `.env` directly.
+- Output remains names-only; do not print secret values in logs, handoffs, or
+  state artifacts.
+
 ## Canonical status contract (US-0045)
 
 - Story status authority is `docs/product/backlog.md` only.
@@ -307,10 +406,17 @@ continuation breadcrumbs) including:
 - Deterministic continuation breadcrumbs in relevant artifacts
 
 ## Stop conditions
-- Decision gate triggered
-- Missing critical input
-- `AUTO_PAUSE_REQUEST=1` reached at a safe boundary
-- `AUTO_LOOP_MAX_CYCLES` reached with unresolved defects
+
+Deterministic stop reasons for continuous and looping runs (aligned with
+**Deterministic stop matrix (US-0088)** above):
+
+- `completed` — all intersected phases finished; segment done.
+- `decision_gate` — decision gate triggered; non-suppressible.
+- `missing_input` — missing critical input; non-suppressible.
+- `pause_request` — `AUTO_PAUSE_REQUEST=1` reached at a safe boundary; non-suppressible.
+- `loop_max` — `AUTO_LOOP_MAX_CYCLES` reached with unresolved defects; non-suppressible.
+- `error` — runtime or configuration error; non-suppressible.
+- `blocked` — sync/scope gate or external blocker; non-suppressible.
 
 ## Optional backlog-drain mode (US-0044 / DEC-0022)
 
@@ -325,18 +431,113 @@ Canonical controls from `.cursor/scratchpad.md`:
 
 Deterministic behavior when enabled (`AUTO_BACKLOG_DRAIN=1`):
 - Select next eligible OPEN story via `AUTO_STORY_SELECTION`.
-- Run full story lifecycle (`discovery -> ... -> release -> refresh-context`).
-- After each story completion, continue to next eligible story until:
-  - `AUTO_BACKLOG_MAX_STORIES` limit reached, or
+- **Advance through multiple phases** of the resolved lifecycle per story
+  (**reference Step 5**) — the orchestrator does not stop after one phase
+  unless a deterministic stop condition fires (see **Deterministic stop matrix
+  (US-0088)**).
+- After each story's terminal boundary (`refresh-context` completion or policy
+  stop), **recompute the materialized phase plan** by reloading merged
+  scratchpad phase-selection inputs at the story boundary (**US-0044** /
+  **US-0088**). The next eligible OPEN story starts with a fresh plan class —
+  no silent revival of omitted phases from the prior story's plan.
+- Continue to next eligible OPEN story until:
+  - `AUTO_BACKLOG_MAX_STORIES` limit reached (`BACKLOG_MAX_STORIES_REACHED`), or
   - no eligible stories remain, or
   - stop condition / decision gate occurs.
 - On blocked story:
-  - `AUTO_BACKLOG_ON_BLOCK=stop` -> stop immediately.
-  - `AUTO_BACKLOG_ON_BLOCK=skip` -> record skip reason and continue.
+  - `AUTO_BACKLOG_ON_BLOCK=stop` → stop immediately.
+  - `AUTO_BACKLOG_ON_BLOCK=skip` → record skip reason and continue to next story.
+- Track `backlog_drain_stories_remaining_budget` across boundaries; notify
+  operator on segment handoff / drain advance (non-routine, non-suppressible
+  even when `AUTO_QUIET=1`).
 
 Default-safe behavior:
 - With `AUTO_BACKLOG_DRAIN=0`, preserve existing single-segment continuation.
 
+## Optional bug-queue mode (US-0087)
+
+`/auto` supports an optional, **default-off** bug-queue scheduler for **OPEN**
+defects in **`docs/product/backlog.md`** **`## Bug issues (canonical)`**,
+orthogonal to story-only **`AUTO_BACKLOG_DRAIN`** (**`US-0044`** / **`DEC-0022`**).
+Bug-queue mode is **spawn-only** — same **`AUTO_ORCHESTRATOR_PHASE_EXECUTION`**
+contract as other phases (**`BUG-0006`**, **`US-0069`** / **`DEC-0051`**).
+
+### Canonical argv literals (AC-1)
+
+Exact tokens (**no aliases** in v1; contract-tested):
+
+- **`bug-target=BUG-####`** — single **OPEN** bug (example: **`bug-target=BUG-0007`**).
+- **`bug-target=all-open`** — deterministic **OPEN**-only queue.
+
+### Scratchpad keys (merged; `template/` parity)
+
+Default-off when unset (see **`architecture.md`** **`# US-0087`**):
+
+- **`AUTO_BUG_QUEUE`**: `0|1`
+- **`AUTO_BUG_TARGET`**: `all-open` | **`BUG-####`** — required when **`AUTO_BUG_QUEUE=1`**
+  unless **`bug-target=`** argv supplies the target for this invocation.
+- **`AUTO_BUG_MAX_ITEMS`**: non-negative integer — optional cap on bugs consumed per
+  orchestrator run for **`all-open`**; **`0`** or unset = no cap beyond queue length.
+- **`AUTO_BUG_ON_BLOCK`**: `stop|skip` — queue behavior when a bug segment stops at a
+  pause/stop boundary.
+
+### Scheduler mutex and argv precedence (AC-3)
+
+**One active scheduler** per materialized run:
+
+- If merged scratchpad has **`AUTO_BACKLOG_DRAIN=1`** **and** **`AUTO_BUG_QUEUE=1`**
+  **and** this invocation has **no** explicit **`bug-target=`** argv token → fail
+  closed with **`[AUTO_RESUME_ERROR] AUTO_SCHEDULER_CONFLICT: ...`**.
+- When **`bug-target=`** argv is present, it **selects** the bug scheduler for this
+  run; **`AUTO_BACKLOG_DRAIN`** must **not** drive story selection for the same
+  materialized run (story drain keys ignored for scheduler selection; record
+  **`backlog_drain_active=false`**, **`bug_queue_active=true`** in **AC-10** for
+  that run).
+
+**Parsing order** before nominal resume resolution: **`start-from`** → **`bug-target=`**
+argv → merged scratchpad (**`AUTO_BACKLOG_DRAIN`**, **`AUTO_BUG_*`**) →
+**`resume_brief.md`** → **`state.md`** fallback (**`architecture.md`** **`# US-0087`**).
+
+### OPEN queue semantics (AC-4)
+
+- **OPEN** rows only in the canonical bug section — exclude **DONE** and non-matching ids.
+- **Ordering**: ascending **numeric** sort on **`BUG-####`** (stable document-order
+  tie-break if needed).
+- **`AUTO_BUG_MAX_ITEMS`**: when set to positive integer *N*, consume at most *N*
+  bugs from the head of the ordered queue this run; record **`bug_queue_remaining`**
+  for operator visibility.
+- **Empty queue** when **`bug-target=all-open`** (or equivalent) and zero **OPEN**
+  bugs → **`[AUTO_RESUME_ERROR] AUTO_BUG_QUEUE_EMPTY: ...`** (or equivalent
+  deterministic envelope).
+
+### Fail-closed reason codes (AC-1, AC-4, AC-8)
+
+| Code | When |
+|------|------|
+| **`AUTO_BUG_QUEUE_EMPTY`** | **`all-open`** and zero **OPEN** bugs. |
+| **`AUTO_BUG_TARGET_UNKNOWN`** | Malformed id / pattern, or id missing from canonical bug section. |
+| **`AUTO_BUG_TARGET_NOT_OPEN`** | Known id, status not **OPEN**. |
+| **`AUTO_SCHEDULER_CONFLICT`** | **`AUTO_BACKLOG_DRAIN=1`** ∧ **`AUTO_BUG_QUEUE=1`** without **`bug-target=`** argv. |
+
+Do **not** overload **`PHASE_POLICY_CONFLICT`** or backlog-drain codes for these.
+
+### Bug segment fields: `resume_brief.md` + `state.md` (`DEC-0069` / AC-5)
+
+Default: **paired** refresh at segment boundaries — update **`handoffs/resume_brief.md`**
+**and** append **`docs/engineering/state.md`** breadcrumbs together so continuation
+without **`start-from`** avoids false **`RESUME_BRIEF_STALE`**.
+
+| Field | Purpose |
+|-------|---------|
+| **`bug_id`** | Active **`BUG-####`** for this segment (**OPEN**), or **`(none)`**. |
+| **`bug_queue_position`** | 1-based index into **OPEN** ordering for **`all-open`**; else **`(none)`**. |
+| **`bug_queue_remaining`** | Count of **OPEN** bugs after current position; **`(none)`** when not queue-scoped. |
+| **`intended_resume_phase`** | Next phase for this segment (align with **`next_scheduled_phase`** on `state.md`). |
+
+Mirror the **AC-10** tuple (`segment_work_item_kind`, `active_bug_id`,
+`backlog_drain_active`, `bug_queue_active`, etc.) in both surfaces per
+**`architecture.md`** **`# US-0087`**.
+
 ## Optional bulk execute mode (US-0047 / DEC-0024)
 
 `/auto` supports an explicit bulk execute orchestration mode for continuous
@@ -470,23 +671,38 @@ Reason-code baseline:
 
 ## Deterministic resume-source precedence
 
-Resolve start phase in strict order:
+Resolve nominal start phase and scheduler inputs in strict order (**`US-0087`**
+extends ordering vs legacy two-step resume):
 
 1. Explicit `/auto start-from=<phase>`
-2. `handoffs/resume_brief.md`
-3. Conservative `docs/engineering/state.md` fallback
-4. Fail fast on ambiguity/conflict/unrecoverable inputs
+2. Explicit **`bug-target=`** argv token when present (`bug-target=BUG-####` or
+   `bug-target=all-open`) — parsed **before** merged scratchpad scheduler keys;
+   selects bug scheduler for this run when applicable.
+3. Merged scratchpad (**`US-0073`** / **`DEC-0055`**) — `AUTO_BACKLOG_DRAIN`,
+   **`AUTO_BUG_QUEUE`**, **`AUTO_BUG_TARGET`**, related flags.
+4. `handoffs/resume_brief.md`
+5. Conservative `docs/engineering/state.md` fallback
+6. Fail fast on ambiguity/conflict/unrecoverable inputs (including
+   **`AUTO_SCHEDULER_CONFLICT`** when **`AUTO_BACKLOG_DRAIN=1`** ∧
+   **`AUTO_BUG_QUEUE=1`** without **`bug-target=`** argv).
 
 Deterministic precedence behavior:
-- If explicit `start-from` is valid, it wins and lower-priority sources do not
-  affect selected start phase.
-- `state.md` fallback is used only when `resume_brief.md` is absent.
+- If explicit `start-from` is valid, it wins for the **nominal start phase** anchor;
+  scheduler mutex (**`AUTO_SCHEDULER_CONFLICT`**) is still evaluated when scratchpad
+  enables both drains without **`bug-target=`** argv resolution.
+- **`bug-target=`** argv when present overrides conflicting scratchpad scheduler
+  selection for **this** run (bug queue active; story drain inactive for scheduling).
+- `state.md` fallback applies only per the ordered chain above when higher-priority
+  sources do not supply a trustworthy anchor.
 - If `resume_brief.md` is present but stale or unparseable, fail fast instead
   of silently falling back.
 
 ## Conflict and stale/unparseable policy
 
 - Explicit valid override always wins and is logged as override.
+- **`AUTO_BACKLOG_DRAIN=1`** and **`AUTO_BUG_QUEUE=1`** together without explicit
+  **`bug-target=`** argv → **`AUTO_SCHEDULER_CONFLICT`** (fail fast; do not pick a
+  silent default scheduler).
 - No override + `resume_brief` conflicts with `state` inference: fail fast.
 - `resume_brief` exists but stale: fail fast.
 - `resume_brief` exists but unparseable: fail fast.
@@ -508,6 +724,61 @@ Required codes:
 - `STATE_PHASE_AMBIGUOUS`
 - `STATE_PHASE_UNRECOVERABLE`
 
+Bug-queue extensions (**`US-0087`**; use the same **`[AUTO_RESUME_ERROR]`** envelope
+for resolver/materialization failures):
+
+- `AUTO_SCHEDULER_CONFLICT`
+- `AUTO_BUG_QUEUE_EMPTY`
+- `AUTO_BUG_TARGET_UNKNOWN`
+- `AUTO_BUG_TARGET_NOT_OPEN`
+
+## Continuous multi-phase execution (US-0088)
+
+A single `/auto` orchestrated run (or a **documented equivalent outer driver** —
+see **AC-1 equivalence** below) advances through **all phases** in the
+**intersected resolved schedule** (**Step 5** below — cross-anchor:
+**"reference Step 5"**) until a **deterministic stop condition** fires. The
+orchestrator does **not** stop after spawning one phase unless the stop matrix
+requires it.
+
+### Outer-driver equivalence (AC-1, Option B)
+
+When a single Cursor `/auto` invocation cannot schedule multiple fresh subagent
+turns (product/runtime constraint), a **documented outer driver** (operator
+script or manual re-invocation with `start-from` / refreshed `resume_brief`) is
+**deterministically equivalent** provided all of the following hold:
+
+- Same intersected phase order as a single-invocation run.
+- Same per-phase isolation evidence (**DEC-0029**) + strict-proof attestation
+  (**DEC-0038**).
+- Same deterministic stop reasons and stop matrix evaluation.
+- Same `resume_brief` + `state.md` refresh at every materialized phase boundary.
+- Operators must follow the runbook recipe
+  (**`docs/engineering/runbook.md`** § Continuous `/auto` + backlog drain).
+
+### Deterministic stop matrix (US-0088)
+
+| Condition | Behavior | Operator notify (AC-2) |
+|-----------|----------|------------------------|
+| Next phase exists, no hard stop | **Continue** — preflight US-0069, spawn next phase | Quiet OK when `AUTO_QUIET=1` |
+| `decision_gate` | **Stop** until resolved | **Always** (non-suppressible) |
+| `error` / missing critical input | **Stop** | **Always** (non-suppressible) |
+| `AUTO_PAUSE_REQUEST` / `pause` | **Stop** at safe boundary | **Always** (non-suppressible) |
+| `AUTO_LOOP_MAX_CYCLES` / `loop_max` | **Stop** | **Always** (non-suppressible) |
+| `blocked` (sync/scope gate) | **Stop** | **Always** (non-suppressible) |
+| US lifecycle DONE / sprint segment complete | **Stop** segment; `AUTO_BACKLOG_DRAIN=1` may advance to next OPEN story (recompute phase plan — **Step 5**) | Notify on segment handoff (non-routine) |
+| `BACKLOG_MAX_STORIES_REACHED` | **Stop** | **Always** (non-suppressible) |
+
+`stop_reason` vocabulary: `completed`, `decision_gate`, `missing_input`,
+`pause_request`, `loop_max`, `error`, `blocked`.
+
+### `AUTO_QUIET` vs `TOKEN_PROFILE` (US-0088 / AC-2)
+
+| Key | Values | Role |
+|-----|--------|------|
+| `AUTO_QUIET` | `0` \| `1` (default `0`) | `1` = suppress routine per-phase success chatter; must **not** suppress `decision_gate`, errors, pause, `loop_max`, `blocked`, or missing inputs. |
+| `TOKEN_PROFILE` | `lean` \| `balanced` \| `full` | Unchanged — **DEC-0035** / **US-0080**; **orthogonal** to `AUTO_QUIET`. |
+
 ## Steps
 1. Read automation flags from merged scratchpad and **materialize the resolved
    phase plan** per **Configurable phase selection policy (US-0070 / DEC-0052)**:
@@ -517,9 +788,13 @@ Required codes:
    `docs/engineering/state.md` **before** any phase spawn. On failure, emit
    deterministic phase-plan reason codes and stop (no partial schedule).
 2. Parse optional `start-from=<phase>` and validate canonical phase ID rules.
+   Parse optional **`bug-target=`** argv literals (**`US-0087`**) and evaluate
+   **scheduler mutex** (`AUTO_SCHEDULER_CONFLICT` when **`AUTO_BACKLOG_DRAIN=1`**
+   ∧ **`AUTO_BUG_QUEUE=1`** without **`bug-target=`** argv).
    Parse optional `--execute-bulk` and treat it as explicit one-run override.
 3. Resolve **nominal** start phase using deterministic precedence:
-   - explicit argument -> resume brief -> state fallback -> fail-fast.
+   - explicit `start-from` → **`bug-target=`** argv (when present) → merged scratchpad
+     → resume brief → state fallback → fail-fast.
    - Emit `[AUTO_RESUME_ERROR] ...` message on resolver failure.
 3a. **Intersect** the nominal start anchor with the resolved phase plan (plan
    order preserved; drop scheduled phases strictly before the anchor in canonical
@@ -534,9 +809,15 @@ Required codes:
    - `resolution_source` (`argument|resume_brief|state_fallback`)
    - `resolution_status` (`resolved|fail-fast`)
    - `timestamp`
-5. Spawn a fresh subagent for each remaining phase in **the intersected
-   resolved schedule order** (not the full canonical list when phases are
-   omitted), starting at `resolved_start_phase`:
+5. **(reference Step 5 — continuous multi-phase spawn)** Spawn a fresh subagent
+   for each remaining phase in **the intersected resolved schedule order** (not
+   the full canonical list when phases are omitted), starting at
+   `resolved_start_phase`, and **advance through all subsequent phases** until a
+   **deterministic stop condition** fires (see **Deterministic stop matrix
+   (US-0088)** above). The orchestrator does **not** stop after a single phase
+   spawn unless the stop matrix requires it; outer-driver equivalence applies
+   when a single invocation cannot schedule multiple subagent turns (see
+   **Outer-driver equivalence (AC-1, Option B)** above):
    default full path:
    intake -> discovery -> research -> architecture -> sprint plan ->
    plan verify -> execute -> QA -> verify work -> release -> refresh context.
@@ -548,6 +829,12 @@ Required codes:
      story using deterministic selection policy until bounded stop criteria.
      **Reload merged scratchpad phase-selection inputs and recompute the phase
      plan at each story boundary** (same policy class as single-segment runs).
+   - If bug-queue mode is active (**`bug-target=`** argv or **`AUTO_BUG_QUEUE=1`**
+     with resolved target), iterate **OPEN** bugs per **Optional bug-queue mode
+     (US-0087)** — ascending numeric **`BUG-####`** order, **`AUTO_BUG_MAX_ITEMS`**
+     cap, **`AUTO_BUG_ON_BLOCK`** stop/skip — running the same **resolved phase plan**
+     per bug segment with fresh spawns only. **Reload scratchpad and revalidate
+     mutex at each bug boundary.** Empty **OPEN** queue → **`AUTO_BUG_QUEUE_EMPTY`**.
    - If bulk execute mode is active (`--execute-bulk` or
      `AUTO_EXECUTE_BULK=1`), iterate eligible planned items using
      `AUTO_EXECUTE_SELECTION` with bounded item count
@@ -614,11 +901,12 @@ Required codes:
     - `push_decision` (`pushed|blocked|not_eligible`)
     - `reason_code`
     - `evidence_refs`
-13. When backlog-drain mode or bulk execute mode is enabled, append per-item run
-    summary entries:
+13. When backlog-drain mode, bug-queue mode, or bulk execute mode is enabled,
+    append per-item run summary entries:
     - `item_id`
-    - `item_kind` (`story|sprint`)
+    - `item_kind` (`story|sprint|bug`)
     - `story_id`
+    - `bug_id` (when `item_kind=bug`)
     - `sprint_id`
     - `story_start_phase`
     - `story_stop_phase`