forgedock 1.26.0 → 1.28.0

package/commands/milestone.md

@@ -1,6 +1,6 @@
 ---
 description: Create, manage, and ship milestones — the top-level planning layer for feature development
-argument-hint: "[create <name> | status | ship <slug> | sync <slug>]"
+argument-hint: "[create <name> [--plan <file>] [--greenfield] [--spike <path>] | status | ship <slug> | sync <slug>]"
 install: extras
 ---
 <!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->
@@ -17,7 +17,7 @@ Milestones are the top-level planning unit. They group related issues into a shi
 **Hierarchy**: Milestone → Issues → Sub-issues (optional decomposition)
 
 **NEVER use plan mode (EnterPlanMode).**
-**NEVER use the Agent tool for issue work** — milestone dispatches issue work via `Skill(skill="{FORGE_SKILL_PREFIX}work-on", ...)` only. The Agent tool bypasses the Skill pipeline's label state machine, FORGE annotations, and structured review. The Agent tool may be used only for coordination tasks within milestone planning itself (e.g., parallel issue list queries) — never for /work-on sub-dispatch.
+**NEVER use the Agent tool for issue work** — milestone dispatches issue work via `Skill(skill="{FORGE_SKILL_PREFIX}work-on", ...)` only. Agent bypasses the Skill pipeline's label state machine, FORGE annotations and structured review; use it only to coordinate milestone planning (e.g. parallel issue-list queries), never for /work-on sub-dispatch.
 
 <!-- FORGE:SPEC_LOADED — milestone.md loaded and active. Agent is bound by this spec. -->
 
@@ -88,10 +88,12 @@ Parse `$ARGUMENTS` to determine which action to take:
 | Input Pattern | Action |
 |--------------|--------|
 | `create <name>` or just a descriptive phrase | → **Create Milestone** |
+| `create <name> --plan <file>` / `--greenfield` / `--spike <path>` | → **Create Milestone**, greenfield mode (Step 4G) |
 | `status` (no args, or "status") | → **Show All Milestones** |
 | `status <slug>` | → **Show Milestone Detail** |
 | `ship <slug>` | → **Ship Milestone** |
 | `sync <slug>` | → **Sync Milestone Branch** |
+| `drift <slug>` | → **Milestone Drift** |
 | `close <slug>` | → **Close Milestone** |
 
 ---
@@ -105,6 +107,25 @@ The user provides a name or description. Extract:
 - **Slug**: Lowercase, hyphenated, max 40 chars (e.g., `llm-extraction-platform`)
 - **Description**: What this milestone delivers, extracted from user's input
 
+Optional greenfield flags (strip them from the name before deriving title and slug): <!-- Added: forge#4175 -->
+
+| Flag | Meaning |
+|------|---------|
+| `--plan <file>` | Precomputed plan from `/bootstrap`: per issue a title, type, priority, size, dependencies, planned Affected Files and acceptance criteria. Implies greenfield mode. |
+| `--greenfield` | Greenfield mode: the milestone builds code that does not exist yet, so Step 4 code-read gating is replaced by Step 4G. |
+| `--spike <path>` | Spike doc declaring the `Repo layout` (implies greenfield mode). Default `docs/engineering/technical-spike.md`, repo-relative, same semantics as `commands/issue.md` `--spike`. |
+
+```bash
+PLAN_FILE=""; GREENFIELD=false; SPIKE_DOC="docs/engineering/technical-spike.md"
+# set from the flags above: --plan => PLAN_FILE + GREENFIELD=true; --greenfield => GREENFIELD=true; --spike => SPIKE_DOC + GREENFIELD=true
+# A plan with a spike doc declaring a Repo layout is greenfield even without the flag (same predicate as /issue Phase 3E).
+[ -n "$PLAN_FILE" ] && [ -f "$SPIKE_DOC" ] && grep -qiE '^#+[[:space:]].*repo layout' "$SPIKE_DOC" && GREENFIELD=true
+# Passed to every default-repo /issue call in Step 6; empty in brownfield mode.
+GREENFIELD_ARGS=""; [ "$GREENFIELD" = "true" ] && GREENFIELD_ARGS=" --greenfield --spike \"$SPIKE_DOC\""
+```
+
+Without any of these flags `GREENFIELD=false`, `GREENFIELD_ARGS` is empty and every step below behaves as in brownfield mode.
+
 ### Step 2: Create the GitHub milestone
 
 ```bash
@@ -127,7 +148,9 @@ git push origin milestone/{slug}
 
 ### Step 4: Scope decomposition
 
-**Investigation-gated decomposition** — do NOT skip code reads. The single-pass shallow-planning approach (one agent, whole milestone, no per-issue code reads) produces under-specified issues that ship incomplete. This step mandates per-proposed-issue investigation before any issue body is written. See `work-on/decompose.md` Phase D0 for the reference pattern that enforces this gate. <!-- Added: forge#293 -->
+**Greenfield mode** (`GREENFIELD=true`): skip 4A–4C and run **Step 4G** instead. Steps 2, 3 (the `milestone/{slug}` branch), 5, 6 and 6B run unchanged in both modes. Brownfield (`GREENFIELD=false`): Step 4G does not apply and 4A–4C below are mandatory. <!-- Added: forge#4175 -->
+
+**Investigation-gated decomposition** — do NOT skip code reads: one shallow pass with no per-issue code reads yields under-specified issues that ship incomplete, so investigate each proposed issue before writing its body. See `work-on/decompose.md` Phase D0 for the reference pattern that enforces this gate. <!-- Added: forge#293 -->
 
 **4A: First pass — enumerate proposed issues (no code reads yet)**
 
@@ -153,7 +176,21 @@ For each proposed issue, after completing the per-issue investigation in Step 4B
 - **Size**: S (1-2 files), M (3-5 files), L (6+ files)
 - **Dependencies**: Which other issues must be done first (by number)
 - **Affected files**: Full list of files enumerated during the Step 4B code read (not estimated)
-- **Acceptance criteria**: Exhaustive and falsifiable. For coverage/refactor tasks: one criterion per affected call site or pattern, written as a grep/absence assertion. No cap on criteria count — the list must be complete enough that a reviewer can verify coverage without reading the implementation.
+- **Acceptance criteria**: Exhaustive and falsifiable. For coverage/refactor tasks: one criterion per affected call site or pattern, written as a grep/absence assertion. No cap: a reviewer must be able to verify coverage without reading the implementation.
+
+**4G: Greenfield / precomputed plan (only when `GREENFIELD=true`)** <!-- Added: forge#4175 -->
+
+There is no code to read yet, so the per-issue code reads of 4B are skipped. The spike doc's `Repo layout` replaces them as the source of truth for paths:
+
+1. **Issue list**: with `--plan`, take the issues from `PLAN_FILE` as-is (title, type, priority, size, dependencies, planned Affected Files, acceptance criteria). Without a plan, enumerate them as in 4A and write each per 4C, reading the spike doc (layout, data model, route/API map) instead of code.
+2. **Validate planned paths**: write each issue body (Step 6 template) to an entity-scoped `mktemp` file and run the same deterministic check `/issue` Phase 3E uses. Exit 1 (`MISSING <path>`) or 2 (spike doc missing or no layout) → fix the plan or the spike layout; do not create that issue.
+   ```bash
+   type forge_resolve >/dev/null 2>&1 || { setopt nonomatch 2>/dev/null || true; FORGE_SOURCED_ROOT='${CLAUDE_PLUGIN_ROOT}'; for _r in "$(cygpath -u "${FORGEDOCK_HOME:-}" 2>/dev/null || printf %s "${FORGEDOCK_HOME:-}")" '${CLAUDE_PLUGIN_ROOT}' "${FORGE_ROOT:-}" "${FORGE_HOME:-}" "$(readlink -f "$HOME/.claude/commands/work-on.md" 2>/dev/null | sed 's|/commands/work-on\.md$||')" "$(head -n 1 "${CODEX_HOME:-$HOME/.codex}/forge-home" 2>/dev/null)" "$HOME/.claude/plugins/marketplaces/forgedock" "${CLAUDE_CONFIG_DIR:-$HOME/.claude}"/plugins/cache/forgedock/forgedock/* "$HOME/.claude"/plugins/cache/forgedock/forgedock/*; do case "$_r" in /*) [ -f "$_r/scripts/lib/forge-resolve.sh" ] && { . "$_r/scripts/lib/forge-resolve.sh"; break; };; esac; done; type forge_resolve >/dev/null 2>&1 || forge_resolve() { :; }; }
+   AF_CHECK_SCRIPT=$(forge_resolve affected-files-check.sh)
+   [ -n "$AF_CHECK_SCRIPT" ] && bash "$AF_CHECK_SCRIPT" "$PLAN_ISSUE_BODY_FILE" --spike "$SPIKE_DOC"
+   ```
+   If the helper does not resolve, leave the check to `/issue` Phase 3E, which runs it again on every Step 6 call because `GREENFIELD_ARGS` carries `--greenfield --spike`.
+3. Acceptance criteria stay exhaustive and falsifiable (4B rule 3); the plan's `Depends on` order is kept.
 
 **Project ecosystem context** (from `forge.yaml`):
 - **Primary repo** (`{GH_REPO}`): The main project codebase at `{REPO_PATH}`
@@ -168,7 +205,7 @@ Present the proposed issues to the user. Ask:
 
 ### Step 6: Create issues and assign to milestone
 
-**Issue body standard**: Use the **Pipeline Issue Template** from `issue.md` Phase 3D as the body structure for every issue created here. Do NOT use a bespoke inline template — the Pipeline Issue Template is the single canonical standard for all automated issue creation across the pipeline. The body content (Problem, Root Cause, Affected Files, Acceptance Criteria, Context, Dependencies) comes from the per-issue investigation in Step 4B. <!-- Added: forge#293 -->
+**Issue body standard**: Use the **Pipeline Issue Template** from `issue.md` Phase 3D as the body structure for every issue created here (it is the single canonical standard; no bespoke inline template). The body content (Problem, Root Cause, Affected Files, Acceptance Criteria, Context, Dependencies) comes from the per-issue investigation in Step 4B. <!-- Added: forge#293 --> In greenfield mode it comes from the Step 4G plan instead, and Affected Files are planned paths inside the spike's `Repo layout`. <!-- Added: forge#4175 -->
 
 **Route creation through `/issue`'s programmatic invocation contract** (`commands/issue.md`, added #2085) instead of calling `gh issue create` directly — this gets dedup (Phase 2D) and mandatory-section body validation (Phase 3F) for free. <!-- Changed: forge#2086 — route through /issue create-hook -->
 
@@ -213,7 +250,7 @@ BODY_EOF
 ```
 
 ```
-ISSUE_SKILL_OUTPUT=$(Skill(skill="{FORGE_SKILL_PREFIX}issue", args="--title \"{fix|feat|refactor}: {issue_title}\" --body-file \"${MILESTONE_ISSUE_BODY_FILE}\" --label \"{type}\" --label \"{priority}\" --milestone \"{TITLE}\""))
+ISSUE_SKILL_OUTPUT=$(Skill(skill="{FORGE_SKILL_PREFIX}issue", args="--title \"{fix|feat|refactor}: {issue_title}\" --body-file \"${MILESTONE_ISSUE_BODY_FILE}\" --label \"{type}\" --label \"{priority}\" --milestone \"{TITLE}\"${GREENFIELD_ARGS}"))
 ```
 
 ```bash
@@ -381,6 +418,18 @@ Show detailed progress with per-issue status.
 
 ---
 
+## Action: Milestone Drift (drift <slug>)
+
+Print verbatim (forge#4161); no LLM, no issue filing.
+
+```bash
+git fetch origin "{STAGING_BRANCH}" "milestone/{slug}"
+type forge_resolve >/dev/null 2>&1 || { setopt nonomatch 2>/dev/null || true; FORGE_SOURCED_ROOT='${CLAUDE_PLUGIN_ROOT}'; for _r in "$(cygpath -u "${FORGEDOCK_HOME:-}" 2>/dev/null || printf %s "${FORGEDOCK_HOME:-}")" '${CLAUDE_PLUGIN_ROOT}' "${FORGE_ROOT:-}" "${FORGE_HOME:-}" "$(readlink -f "$HOME/.claude/commands/work-on.md" 2>/dev/null | sed 's|/commands/work-on\.md$||')" "$(head -n 1 "${CODEX_HOME:-$HOME/.codex}/forge-home" 2>/dev/null)" "$HOME/.claude/plugins/marketplaces/forgedock" "${CLAUDE_CONFIG_DIR:-$HOME/.claude}"/plugins/cache/forgedock/forgedock/* "$HOME/.claude"/plugins/cache/forgedock/forgedock/*; do case "$_r" in /*) [ -f "$_r/scripts/lib/forge-resolve.sh" ] && { . "$_r/scripts/lib/forge-resolve.sh"; break; };; esac; done; type forge_resolve >/dev/null 2>&1 || forge_resolve() { :; }; }
+bash "$(forge_resolve milestone-drift.sh)" "{slug}" --format text
+```
+
+---
+
 ## Action: Ship Milestone
 
 **This is the human-gated deployment step.** When the user says "ship {slug}", they've decided this feature set is ready for production.

package/commands/orchestrate.md

@@ -81,6 +81,11 @@ issue right away (priority label first, then the smaller size). Never hold a rea
 lanes finish. To reduce simultaneous base-syncs, don't start two lanes that name the same function within the
 same minute; start another ready issue first instead of waiting.
 
+**Maintenance budget** (off unless forge.yaml `maintenance.enabled: true`). The runner pulls open issues carrying a
+`maintenance.labels` label into the batch and admits in this order: P0/P1 features > maintenance, while maintenance
+starts stay within `maintenance.share` of all starts (0.2 = 1 lane in 5) > P2+ features. With `when_idle` it drains the
+remaining maintenance once no feature is pending; otherwise the rest ends `held (maintenance share)` for a later batch.
+
 - **Batch runner (default, when `forgedock` is on PATH).** Launch the whole set as one durable batch in a single
   `Bash` call with `run_in_background: true`. Do NOT write a scheduler, wrapper or queue script, and do not launch one
   `run-issue` per issue yourself: the runner schedules from the issues' `Depends on` / `Blocked by` lines.
@@ -93,9 +98,12 @@ same minute; start another ready issue first instead of waiting.
   own session, so the batch survives this session: if the runner dies, run `forgedock orchestrate --resume <id>`
   (live lanes are re-adopted, nothing is launched twice). Change K of a running batch with
   `forgedock orchestrate --set-parallel <id> K`. The runner requeues `deferred` lanes by code (host busy after its
-  retry-in, a usage limit holds all admissions until the reset, transient merge/push/idle failures back off; non-host
+  retry-in, a usage limit holds admissions for that account (backend identity) until the reset, across every batch on
+  the host; `forgedock limits show|clear <id>|--all` lists or drops holds; transient merge/push/idle failures back off; non-host
   deferrals stop after `orchestration.max_deferrals`), relaunches an `engine-error` once, and stops admitting after
-  `orchestration.breaker` engine-errors (`errors` within `window_min`; held issues continue on `--resume`). Logical
+  `orchestration.breaker` engine-errors (`errors` within `window_min`; held issues continue on `--resume`). Lanes are
+  capped host-wide (`orchestration.global_parallel`, `forgedock sched cap N|show`), highest priority first; within a
+  priority, slots are shared across repos by weight (`forgedock sched weight <owner/repo> N`, default equal). Logical
   edges you found in step 2.4 must be written to the dependent issue as a `Depends on #X` line before launching. The
   last lines are the report table.
 - **Agent lane (only when the `forgedock` CLI is unavailable).** Spawn one background agent per issue.

package/commands/review-pr.md

@@ -294,7 +294,7 @@ Substitute each printed value into later fences as `{NAME}` (`{CONTEXT_FILE}`, `
 The 2D env-var, 2E secrets and 2F SQL scans ran in Phase 1 (`PHASE2_FINDINGS`): **a secrets hit is CRITICAL and BLOCKING**; an env var missing from `.env.example` and a migration hazard (`FOR UPDATE` with an aggregate, `DROP` without `IF EXISTS`, `NOT NULL` without `DEFAULT`) are findings. Execution (format, lint, typecheck, build, tests) stays here: it is long-running and needs a throwaway checkout (HARD RULE 7). Commands come from the main checkout's `forge.yaml → verification.commands.*` and run for the changed languages only; a missing command prints `SKIPPED`, never a silent pass, and exit codes are printed so the verdict is not inferred from truncated output.
 
 ```bash
-PR_NUMBER="{PR_NUMBER}"; REPO="{GH_REPO}"; REVIEW_SHA="{REVIEW_SHA}"; REQUIRES_FULL_BUILD="{REQUIRES_FULL_BUILD}"
+PR_NUMBER="{PR_NUMBER}"; REPO="{GH_REPO}"; REVIEW_SHA="{REVIEW_SHA}"; REQUIRES_FULL_BUILD="{REQUIRES_FULL_BUILD}"; CTX="{CONTEXT_FILE}"
 type forge_resolve >/dev/null 2>&1 || { setopt nonomatch 2>/dev/null || true; FORGE_SOURCED_ROOT='${CLAUDE_PLUGIN_ROOT}'; for _r in "$(cygpath -u "${FORGEDOCK_HOME:-}" 2>/dev/null || printf %s "${FORGEDOCK_HOME:-}")" '${CLAUDE_PLUGIN_ROOT}' "${FORGE_ROOT:-}" "${FORGE_HOME:-}" "$(readlink -f "$HOME/.claude/commands/work-on.md" 2>/dev/null | sed 's|/commands/work-on\.md$||')" "$(head -n 1 "${CODEX_HOME:-$HOME/.codex}/forge-home" 2>/dev/null)" "$HOME/.claude/plugins/marketplaces/forgedock" "${CLAUDE_CONFIG_DIR:-$HOME/.claude}"/plugins/cache/forgedock/forgedock/* "$HOME/.claude"/plugins/cache/forgedock/forgedock/*; do case "$_r" in /*) [ -f "$_r/scripts/lib/forge-resolve.sh" ] && { . "$_r/scripts/lib/forge-resolve.sh"; break; };; esac; done; type forge_resolve >/dev/null 2>&1 || forge_resolve() { :; }; }
 MAIN_ROOT="$(cd "$(git rev-parse --path-format=absolute --git-common-dir)/.." && pwd)"   # main checkout even when run from a linked worktree
 REVIEW_WT="${TMPDIR:-/tmp}/forge-review-wt-${PR_NUMBER}-$$"
@@ -304,7 +304,7 @@ git worktree add --detach "$REVIEW_WT" "$REVIEW_SHA" 2>/dev/null
 { cd "$REVIEW_WT" && [ "$(git rev-parse HEAD)" = "$(git -C "$MAIN_ROOT" rev-parse "$REVIEW_SHA")" ]; } || { echo "SKIPPED — could not create per-PR worktree at $REVIEW_SHA"; exit 0; }
 CFG="${FORGE_CONFIG:-$MAIN_ROOT/forge.yaml}"
 vcmd() { yq ".verification.commands.${1}.${2} // \"\"" "$CFG" 2>/dev/null || echo ''; }
-CHANGED=$(gh pr diff "$PR_NUMBER" -R "$REPO" --name-only)
+CHANGED=$(jq -r '.full_files[]?' "$CTX" 2>/dev/null); [ -n "$CHANGED" ] || CHANGED=$(gh pr diff "$PR_NUMBER" -R "$REPO" --name-only)   # Phase 1 list survives an API 406 (forge#4154)
 [ -d "$MAIN_ROOT/node_modules" ] && [ ! -e node_modules ] && ln -s "$MAIN_ROOT/node_modules" node_modules
 run_step() { # run_step <lang> <step> <tail-lines>: prints the exit code; empty command = SKIPPED
   local c; c=$(vcmd "${1}" "${2}")

package/commands/upgrade-deps.md

@@ -257,7 +257,7 @@ Major upgrades detected (not auto-processed — require human review):
 
 ## Phase 3: Issue Creation
 
-For each eligible package (or batch), create a GitHub issue:
+For each eligible package (or batch), create a GitHub issue. Each carries the `maintenance` label, so `forgedock orchestrate` dispatches it within the maintenance budget (forge.yaml `maintenance.share`, #4197):
 
 ### 3A: Per-package issue (patch or minor, non-batched)
 
@@ -269,7 +269,7 @@ if [ "$DRY_RUN" = "true" ]; then
 else
 gh issue create $GH_FLAG \
   --title "feat(deps): upgrade {PACKAGE} from {CURRENT} to {LATEST} ({SEMVER_LEVEL})" \
-  --label "enhancement" \
+  --label "enhancement" --label "maintenance" \
   --body "$(cat <<'ISSUE_EOF'
 ## Problem
 
@@ -327,7 +327,7 @@ if [ "$DRY_RUN" = "true" ]; then
 else
 gh issue create $GH_FLAG \
   --title "feat(deps): batch patch upgrades — {COUNT} packages ({DATE})" \
-  --label "enhancement" \
+  --label "enhancement" --label "maintenance" \
   --body "$(cat <<'BATCH_ISSUE_EOF'
 ## Problem
 

package/commands/work-on/build/validate.md

@@ -357,8 +357,12 @@ else
 fi
 [ "$TEST_FAILED" -eq 1 ] && LEARNED_FAILED=1
 echo "TEST_FAILED=${TEST_FAILED}"
+# #4183: reclaim owned, expired test containers/volumes and scratch (never unowned ones); non-fatal.
+npx forgedock gc --apply --docker --tmp >/dev/null 2>&1 || true
 ```
 
+Test services you start yourself (`docker run`, compose) carry the `forgedock.*` labels (#4181), use `--rm`, and are removed in a `trap` on exit.
+
 The configured `verification.commands.<lang>.test` always runs here, whether or not V4.8's `ci-local.sh` resolves (forge#4040): the local CI gate never runs that command, so a failing configured suite must fail V2 on its own. Only a wall-clock timeout (rc 124) is DEGRADED. Test command failures (`TEST_FAILED=1`, also reported as `LEARNED_FAILED=1`) are BLOCKING (same as `verification.commands` failures): fix and re-run. A command matched and skipped by the known-slow gate is never executed and never counted as a failure, but it is DEGRADED, not verified. Each `DEGRADED_CHECKS+=` line printed here is a carry-forward line: record it in your notes, V5 Step 1 and Step 4 rebuild `DEGRADED_CHECKS` from them (a fresh shell does not keep the variable).
 
 ---

package/commands/work-on/close.md

@@ -1830,6 +1830,8 @@ if [ -n "{WORKTREE_PATH}" ] && [ -d "{WORKTREE_PATH}" ]; then
 else
   echo "Worktree cleanup skipped: path not provided or does not exist"
 fi
+# #4183: reap ForgeDock-owned, stale leftovers (labelled docker, tmp scratch, orphans); core lanes tear down from the ledger.
+npx forgedock gc --apply --docker --tmp --processes >/dev/null 2>&1 || true
 ```
 
 Set `{CLEANUP_STATUS}` based on outcome:

package/commands/work-on/decompose.md

@@ -135,11 +135,24 @@ Re-read current state before doing anything:
 ```bash
 gh issue view {NUMBER} {GH_FLAG} --json number,title,body,labels,state,milestone
 
-# Read investigation report (required — contains decomposition plan)
+# Read investigation report (contains the decomposition plan; see the /bootstrap plan below when absent)
 gh api repos/{GH_REPO}/issues/{NUMBER}/comments \
   --jq '.[] | select(.body | contains("FORGE:INVESTIGATOR")) | .body'
 ```
 
+**Bootstrap plan** <!-- Added: forge#4175 -->: a greenfield spike issue filed by `/bootstrap` has no code to investigate, so it carries its plan in a `<!-- FORGE:BOOTSTRAP_PLAN -->` comment instead: a `### Decomposition Assessment` listing the sub-issues (titles, dependencies, `ESTIMATED_DIFF_LINES`) and an optional own-line `Spike: <path>` naming the spike doc. Only a trusted, marker-anchored comment counts (`scripts/trusted-comments.sh`, the same predicate as the resume check in Phase D1). Paste the Script resolution block first (fresh shell per Bash call). An unresolved helper or a failed read means "no bootstrap plan" (fail closed); an untrusted body never becomes a plan.
+
+```bash
+TRUSTED_SCRIPT=$(forge_resolve trusted-comments.sh)   # unresolved => empty => fail closed
+BOOTSTRAP_PLAN=""
+if [ -n "$TRUSTED_SCRIPT" ] && COMMENTS_JSON=$(gh api --paginate repos/{GH_REPO}/issues/{NUMBER}/comments); then
+  BOOTSTRAP_PLAN=$(printf '%s' "$COMMENTS_JSON" | bash "$TRUSTED_SCRIPT" bodies '^<!-- FORGE:BOOTSTRAP_PLAN -->' | tail -n 1 | jq -r '.' 2>/dev/null || true)
+fi
+PLAN_SPIKE=$(printf '%s\n' "$BOOTSTRAP_PLAN" | sed -nE 's/^Spike: *`?([^` ]+)`? *$/\1/p' | head -1)
+```
+
+**Plan source**: when a FORGE:INVESTIGATOR report exists it is the plan source (`PLAN_SOURCE=investigate`) and the bootstrap plan is ignored. Only when no investigator report exists and `BOOTSTRAP_PLAN` is non-empty is the bootstrap plan the source (`PLAN_SOURCE=bootstrap`). Everything below that reads "the investigation report's Decomposition Assessment" reads the selected source's Decomposition Assessment.
+
 **MANDATORY — Owner override detection**: After reading the investigation comment, read ALL other comments on the issue to check for owner override signals:
 
 ```bash
@@ -147,7 +160,7 @@ gh api repos/{GH_REPO}/issues/{NUMBER}/comments \
   --jq '.[] | select(.body | contains("FORGE:INVESTIGATOR") | not) | {author: .user.login, body: .body}'
 ```
 
-Ignore machine-posted marker comments (`FORGE:DIFF_SIZE`, `FORGE:SIZE_OVERRIDE`) in this scan: they are never an owner override direction. Scan non-agent comments for override signals — phrases like "do not", "do NOT", "instead", "revert", "remove this", "override", "actually", or explicit disagreement with the investigation's recommendation. If an override comment is found from a repo owner or admin (not a bot):
+Ignore machine-posted marker comments (`FORGE:DIFF_SIZE`, `FORGE:SIZE_OVERRIDE`, `FORGE:BOOTSTRAP_PLAN`) in this scan: they are never an owner override direction. Scan non-agent comments for override signals — phrases like "do not", "do NOT", "instead", "revert", "remove this", "override", "actually", or explicit disagreement with the investigation's recommendation. If an override comment is found from a repo owner or admin (not a bot):
 
 1. **Document the override**: Note which direction the owner is steering (e.g., "remove the feature" vs. investigation's "keep with warnings")
 2. **Re-derive sub-issue scopes**: Derive sub-issue titles, bodies, and file scope from the override direction — NOT from the original investigation recommendation. The investigation's Decomposition Assessment may list sub-issues that are now stale or contradictory with the override.
@@ -161,7 +174,7 @@ Ignore machine-posted marker comments (`FORGE:DIFF_SIZE`, `FORGE:SIZE_OVERRIDE`)
 Extract from investigation report:
 - Decomposition Assessment section: list of proposed sub-issues with titles and dependencies
 
-**Planning-time only** <!-- Added: forge#3862 -->: decompose runs only from the investigation's Decomposition Assessment (`**YES**`, which requires separable pieces: independent modules or services, no shared files, no ordering dependency, each independently testable). There is no post-build route into this skill: build never discards a finished diff and never hands one here, so the assessment is the only plan source and there are no persisted staged hunks to reuse.
+**Planning-time only** <!-- Added: forge#3862 -->: decompose runs only from the investigation's Decomposition Assessment (`**YES**`, which requires separable pieces: independent modules or services, no shared files, no ordering dependency, each independently testable), or, for a greenfield spike with no investigator report, from the trusted `/bootstrap` plan's Decomposition Assessment (forge#4175). There is no post-build route into this skill: build never discards a finished diff and never hands one here, so the assessment is the only plan source and there are no persisted staged hunks to reuse.
 - Milestone (from issue metadata)
 - Priority label (P0/P1/P2) from issue labels
 
@@ -193,9 +206,9 @@ PARENT_REF=$(printf '%s\n' "$ISSUE_BODY" | grep -E '^\*\*Parent\*\*: #[0-9]+' |
 
 If `PARENT_REF` is non-empty → BLOCKED, blocker: "Issue #{NUMBER} is a sub-issue (${PARENT_REF}) — sub-issues are never decomposed again; run /work-on build on it directly".
 
-**Guard 2 — investigation report present**: If the FORGE:INVESTIGATOR comment is absent → BLOCKED, blocker: "No investigation report found — run investigate first".
+**Guard 2 — investigation report present**: If the FORGE:INVESTIGATOR comment is absent and there is no trusted `/bootstrap` plan (`BOOTSTRAP_PLAN` empty, Phase D0) → BLOCKED, blocker: "No investigation report found — run investigate first". A trusted bootstrap plan satisfies this guard only for an issue with no investigator report. <!-- Changed: forge#4175 -->
 
-**Guard 3 — decomposition plan present**: If the investigation report has no Decomposition Assessment section, OR the assessment does not list any sub-issues → BLOCKED, blocker: "Investigation report has no decomposition plan — re-run investigate with explicit decomposition scope".
+**Guard 3 — decomposition plan present**: If the investigation report has no Decomposition Assessment section, OR the assessment does not list any sub-issues → BLOCKED, blocker: "Investigation report has no decomposition plan — re-run investigate with explicit decomposition scope". When `PLAN_SOURCE=bootstrap` the same check applies to the bootstrap plan's Decomposition Assessment; on failure the blocker is "Bootstrap plan has no decomposition plan — re-run /bootstrap for this spike".
 
 **Resume check** <!-- Added: forge#3881 -->: the marker comment drives parent edits and the D6.5 close, so only a trusted, marker-anchored comment counts (`scripts/trusted-comments.sh`, the same predicate as the review gates). Paste the Script resolution block first (fresh shell per Bash call). An unresolved helper or a failed read is treated as "no trusted comment" and the normal path continues (the D2.5 equivalent-set check still guards duplicates); an untrusted body never reaches `SUB_LIST`.
 
@@ -373,12 +386,15 @@ SUB_BODY_EOF
 ```bash
 MILESTONE_ARG=""
 [ -n "$MILESTONE_TITLE" ] && MILESTONE_ARG=" --milestone \"${MILESTONE_TITLE}\""
+# Greenfield (forge#4175): a bootstrap plan naming a spike doc lets sub-issues list planned Affected Files.
+SPIKE_ARG=""
+[ "$PLAN_SOURCE" = "bootstrap" ] && [ -n "$PLAN_SPIKE" ] && SPIKE_ARG=" --greenfield --spike \"${PLAN_SPIKE}\""
 ```
 
 **Invoke `/issue` in programmatic mode**:
 
 ```
-ISSUE_SKILL_OUTPUT=$(Skill(skill="{FORGE_SKILL_PREFIX}issue", args="--title \"${SUB_TITLE}\" --body-file \"${SUB_BODY_FILE}\" --label \"{PRIORITY_LABEL}\"${MILESTONE_ARG}"))
+ISSUE_SKILL_OUTPUT=$(Skill(skill="{FORGE_SKILL_PREFIX}issue", args="--title \"${SUB_TITLE}\" --body-file \"${SUB_BODY_FILE}\" --label \"{PRIORITY_LABEL}\"${MILESTONE_ARG}${SPIKE_ARG}"))
 ```
 
 If the skill is not found → BLOCKED, blocker: "skill not found: issue".
@@ -488,6 +504,8 @@ COMMENT_URL=$(gh issue comment {NUMBER} {GH_FLAG} --body "<!-- FORGE:DECOMPOSED
 
 This issue has been broken into sub-issues. Each sub-issue runs through its own /work-on pipeline independently.
 
+**Plan source**: ${PLAN_SOURCE}
+
 ### Sub-Issues Created
 
 {for each sub-issue, in dependency order:}

package/docs/CI.md

@@ -137,10 +137,10 @@ Separately, `npx forgedock run <command>` (the standalone, non-Claude-Code comma
 | Backend | When used | Credential needed |
 |---------|-----------|--------------------|
 | `cli` (via `--backend cli` or `FORGEDOCK_BACKEND=cli`) | Explicit, or auto-selected when a working `claude` CLI is detected on PATH | None — reuses the CLI's own authentication (Pro/Max OAuth or a CLI-managed key) |
-| `api` (via `--backend api` or `FORGEDOCK_BACKEND=api`) | Explicit, or auto-selected fallback when `claude` is not detected | `ANTHROPIC_API_KEY` |
-| `auto` (default) | No `--backend` / `FORGEDOCK_BACKEND` given | Prefers `cli`, falls back to `api` |
+| `api` (via `--backend api` or `FORGEDOCK_BACKEND=api`) | Explicit only, or the `auto` fallback when the owner opted in (forge.yaml `execution.agent_backend: api` plus `FORGEDOCK_ALLOW_API_BACKEND=1`) | `ANTHROPIC_API_KEY` |
+| `auto` (default) | No `--backend` / `FORGEDOCK_BACKEND` given | Uses `cli`; never falls back to `api` without the owner opt-in. With no CLI it fails with `CLI_BACKEND_UNAVAILABLE` |
 
-**When CI still needs `ANTHROPIC_API_KEY` for `forgedock run`**: CI runners generally do not have an interactively-authenticated `claude` CLI (no browser/OAuth flow available in a headless job), so `auto` detection will typically fall back to `api` there anyway. If your CI runner does install and log in the `claude` CLI (e.g. via a headless API-key-based login), you can force `--backend cli` to skip the SDK/API path entirely. Otherwise, keep `ANTHROPIC_API_KEY` configured as a repository secret (see Setup above) and either let `auto` fall back naturally or set `--backend api` / `FORGEDOCK_BACKEND=api` explicitly for a deterministic CI backend regardless of what happens to be on the runner's PATH.
+**When CI still needs `ANTHROPIC_API_KEY` for `forgedock run`**: CI runners generally do not have an interactively-authenticated `claude` CLI (no browser/OAuth flow available in a headless job), so `auto` there fails with `CLI_BACKEND_UNAVAILABLE`: the API backend is never the default, because it bills an API key (#4257). If your CI runner does install and log in the `claude` CLI (e.g. via a headless API-key-based login), you can force `--backend cli` to skip the SDK/API path entirely. Otherwise, keep `ANTHROPIC_API_KEY` configured as a repository secret (see Setup above) and set `--backend api` / `FORGEDOCK_BACKEND=api` explicitly, or opt in to the `auto` fallback with forge.yaml `execution.agent_backend: api` plus `FORGEDOCK_ALLOW_API_BACKEND=1`.
 
 `npx forgedock run <command> --dry-run` always reports which backend it resolved to, without making any network call or requiring a key either way.