@pareto4/pp-core 1.11.1 → 1.12.1

package/pp-core/references/autonomous-best-effort.md

@@ -0,0 +1,461 @@
+# Autonomous — Best-Effort Rules
+
+This file is Read at the start of EVERY phase (`autonomous.md` §3, first line) and again at §6, so
+context compaction cannot erode the rules below. It contains bare `pp_run` calls and relies on the
+caller's launcher — it carries no preamble of its own.
+
+Mode model:
+
+- **Default — best-effort.** At every decision point take the recommended option, record it in the
+  phase's report (§ Recording) at the moment it is taken, and continue.
+- **`--supervised`** — every prompt is restored. The menus live in § Supervised menus, including the
+  `--text` numbered-list variant.
+- **`--interactive`** — discuss runs inline (`pp-discuss-phase`). Orthogonal to the other two: it
+  never restores plan/execute prompts on its own; combine it with `--supervised` for that.
+
+Autonomous passes ` --unattended` (leading space, held in `UNATTENDED_ARG`) to `pp-plan-phase` and
+`pp-execute-phase` unless `--supervised` is set, and never `--auto`: plan-phase §15 would
+auto-advance into a second execute-phase.
+
+## Hard stops
+
+These stop the run in every mode. Best-effort never answers them.
+
+- Blocking capability `check.query` gates (`blocking: true` and `block: true`) — the host workflow
+  HALTs, which ends the run like an `exit 1`; unchanged.
+- `human-action` checkpoints (auth/credentials) in execute-phase.
+- Any checkpoint with `gate="blocking-human"` — package legitimacy (`agents/pp-executor.md`,
+  `agents/pp-planner.md`: never auto-approvable). Presented to the user under `UNATTENDED` and
+  `AUTO_MODE` alike; never deferred. The executor carries the attribute into its return as
+  `**Gate:** blocking-human`, which is what U-E1 keys on — a planner-inserted checkpoint is
+  recognised through that line, not through its prose.
+- A planner `## CHECKPOINT REACHED` (U-P4) and a researcher `## RESEARCH BLOCKED` (U-P14).
+- The client-vault and client-context **`confirmed` acknowledgements** —
+  `execute-phase/steps/vault-load-gate.md` (plan:pre and execute:pre; its `AUTO_MODE` reads only
+  `--auto`/`--chain`, so `--unattended` does not surface-and-continue) and
+  `execute-phase/steps/client-context-gate.md`. They are governance gates: best-effort never types
+  `confirmed` for the operator, in any mode.
+- A worktree base/HEAD mismatch (`FATAL:` / exit 42) and a partial-execution recovery choice
+  (commits without a SUMMARY) in execute-phase — both fail closed and need the operator.
+- A `.continue-here.md` blocking anti-pattern that cannot be answered from context.
+- Anything outward — push, PR, deploy.
+- Lifecycle audit/complete/cleanup never runs from a single-phase run.
+- A `human_needed` verification is never flipped to `passed` by autonomous.
+
+## Recording
+
+Each phase has one report, next to its artifacts:
+
+`REPORT="${PHASE_DIR}/$(basename "$PHASE_DIR" | cut -d- -f1)-AUTONOMOUS-REPORT.md"`
+
+(the padded phase is the basename's first dash-segment, so `02.1-slug` gives `02.1`). Each entry
+carries Point, Options, Choice, Why, Reverse and a UTC timestamp. Append AT THE MOMENT the decision
+is taken, before continuing. Values are passed only as `%s` arguments, never interpolated into the
+format string — phase names and gap text are untrusted.
+
+```bash
+# snippet: report-append
+# expects REPORT, PHASE_NUM, POINT, OPTIONS, CHOICE, WHY, REVERSE
+if [ ! -f "$REPORT" ]; then
+  printf '# Phase %s — Autonomous Report\n\nRun started: %s\nMode: best-effort\n\n' \
+    "$PHASE_NUM" "$(date -u +%Y-%m-%dT%H:%M:%SZ)" > "$REPORT"
+fi
+N=$(( $(grep -c '^## Decision ' "$REPORT" 2>/dev/null || true) + 1 ))
+printf '## Decision %s — %s\n\n- **Point:** %s\n- **Options:** %s\n- **Choice:** %s\n- **Why:** %s\n- **Reverse:** %s\n- **At:** %s\n\n' \
+  "$N" "$POINT" "$POINT" "$OPTIONS" "$CHOICE" "$WHY" "$REVERSE" "$(date -u +%Y-%m-%dT%H:%M:%SZ)" >> "$REPORT"
+```
+
+The counter uses `|| true`, not `|| echo 0`: on a header-only report `grep -c` already prints `0`
+and exits 1, so `echo 0` would yield `0\n0` and the arithmetic dies (bash: `syntax error in
+expression`; zsh: `bad math expression`). Header-only → 1, one entry → 2, missing file → 1 in both
+shells.
+
+**Phase exit** — `autonomous.md` §3d ends every branch here (passed, human_needed, gaps_found,
+and an A-4 stop before its banner), so the `handled=` line and the report commit can never be
+skipped by a branch that "continues". `OUTCOME` ∈ passed | human_needed | gaps_found | blocked;
+`pp_run query commit` honours `commit_docs`.
+
+```bash
+# snippet: phase-exit
+# expects RUN_STATE, PHASE_NUM, PHASE_DIR, REPORT, OUTCOME; pp_run from the caller's launcher
+grep -q "^handled=${PHASE_NUM}:" "$RUN_STATE" 2>/dev/null ||
+  printf 'handled=%s:%s\n' "$PHASE_NUM" "$OUTCOME" >> "$RUN_STATE"
+PADDED_PHASE=$(basename "$PHASE_DIR" | cut -d- -f1)
+if [ -f "$REPORT" ]; then
+  pp_run query commit "docs(${PADDED_PHASE}): autonomous report" --files "$REPORT"
+fi
+```
+
+## Run state
+
+`.autonomous-run` lives next to the resolved STATE.md, so it is workstream-aware:
+
+`RUN_STATE="$(dirname "$(pp_run query init.phase-op "$FIRST_PHASE" --pick state_path)")/.autonomous-run"`
+
+`FIRST_PHASE` is the lowest selected phase number. `--pick state_path` prints
+`.planning/workstreams/<ws>/STATE.md` on a partitioned project and `.planning/STATE.md` on a flat
+one, for any phase number. The file is plain `key=value` lines — `started=`, `args=`, `from=`,
+`to=`, `only=`, `supervised=`, `strategy=` — written fresh at every run start. During the run,
+append `handled=<phase>:<outcome>` (outcome ∈ passed | human_needed | gaps_found | blocked |
+skipped) with `printf 'handled=%s:%s\n' "$PHASE_NUM" "$OUTCOME" >> "$RUN_STATE"`, and
+`retry=<phase>:<step>:1` the same way. Never commit this file.
+
+```bash
+# snippet: run-state-write
+# expects RUN_STATE, ARGUMENTS, FROM_PHASE, TO_PHASE, ONLY_PHASE, SUPERVISED, PLAN_STRATEGY
+printf 'started=%s\nargs=%s\nfrom=%s\nto=%s\nonly=%s\nsupervised=%s\nstrategy=%s\n' \
+  "$(date -u +%Y-%m-%dT%H:%M:%SZ)" "$ARGUMENTS" "$FROM_PHASE" "$TO_PHASE" "$ONLY_PHASE" \
+  "$SUPERVISED" "$PLAN_STRATEGY" > "$RUN_STATE"
+```
+
+```bash
+# snippet: run-state-read
+# expects RUN_STATE, PHASE_NUM, STEP
+HANDLED=$(grep '^handled=' "$RUN_STATE" 2>/dev/null | cut -d= -f2 | cut -d: -f1 | tr '\n' ' ')
+RETRIES=$(grep -c "^retry=${PHASE_NUM}:${STEP}:" "$RUN_STATE" 2>/dev/null || true)
+```
+
+`grep -c` exits 1 on zero matches, hence `|| true`: `RETRIES` is `0` on no match and EMPTY only when
+the file is missing — treat empty as 0 (verified in bash and zsh).
+
+**Iterate rule (review defect 6a):** a phase whose number appears in `HANDLED` is excluded from
+re-selection. A deferred or blocked phase stays incomplete on disk, so without this it would be
+picked again on the next pass.
+
+## Rules — autonomous.md
+
+### A-1 Smart discuss
+
+Display every grey-area table exactly as before. Accept all ✅ Recommended answers; no
+AskUserQuestion. One report entry per area. CONTEXT.md carries
+`**Mode:** Autonomous best-effort — grey areas auto-decided; see {REPORT basename}` under
+`**Status:**`, and every accepted bullet ends with ` *(auto-decided; alternatives: {alt1}; {alt2})*`.
+Infrastructure detection and Sub-steps 1–3 and 5 are unchanged.
+
+Record: Point `Smart discuss — Grey Area M/N: {name}`; Options = the table's questions with the
+recommended answer and alternatives; Choice = recommended; Why = the rationale column; Reverse =
+`edit ${CONTEXT_PATH} and re-run /pp:plan-phase ${PHASE_NUM}`.
+
+Supervised: the per-area prompts in `autonomous-smart-discuss.md` Sub-step 4 (§ Supervised menus).
+
+### A-2 human_needed
+
+Read the human_verification items and display them. Record, then display exactly:
+
+`Phase ${PHASE_NUM} ⏭ Human validation deferred — phase stays incomplete (never marked passed); finish with /pp:verify-work ${PHASE_NUM}`
+
+Set `OUTCOME=human_needed` and go to §3d exit (`phase-exit` appends `handled=` and commits the report). Autonomous NEVER
+edits VERIFICATION.md and never writes a `passed` status anywhere for a human_needed phase.
+
+Record: Point `Verification human_needed — {count} item(s)`; Options
+`Validate now / Continue without validation`; Choice `deferred`; Why
+`an unattended run cannot perform manual verification`; Reverse `/pp:verify-work ${PHASE_NUM}`.
+
+Supervised: the two-step menu in § Supervised menus.
+
+### A-3 gaps_found
+
+Display the score. Make ONE automatic closure attempt — the two Skill calls stay in `autonomous.md`,
+both with `${UNATTENDED_ARG}` — then re-read the status with `verification.status`:
+
+- `passed` → Record the attempt (Choice `gap closure run once — resolved`) and continue.
+- `human_needed` → rule A-2.
+- still `gaps_found` → Record (Choice `continue with gaps deferred`; Reverse
+  `/pp:plan-phase ${PHASE_NUM} --gaps` then `/pp:execute-phase ${PHASE_NUM}`), display exactly
+  `Phase ${PHASE_NUM} ⏭ Gaps deferred — phase stays incomplete`, set `OUTCOME=gaps_found`, go to
+  §3d exit.
+
+Closure planning that produces no plans → rule A-4 (step `gap-closure`).
+
+Record: Point `Verification gaps_found — score {N}/{M}`; Options
+`Run gap closure / Continue without fixing / Stop autonomous mode`; Why
+`one bounded closure attempt, then continue — the phase stays incomplete`.
+
+Supervised: the three-option menu and the "Gaps persist" follow-up in § Supervised menus.
+
+### A-4 Blocker
+
+`{step}` ∈ discuss | plan | execute | gap-closure | verification. Set `STEP` and run
+`run-state-read`:
+
+1. `RETRIES` empty or `0` → append `retry=${PHASE_NUM}:${step}:1`, display
+   `↻ Retrying ${step} for phase ${PHASE_NUM} (1 of 1)`, re-run the failed step.
+2. Otherwise → Record, set `OUTCOME=blocked` and run `phase-exit`, print the STOPPED banner (§ Supervised
+   menus, verbatim, including its `Resume with: /pp:autonomous …` line) and the end-of-run summary,
+   then exit. The run stops — a later phase is never built on one that failed.
+
+Record: Point `Blocker — {description}`; Options `Fix and retry / Skip this phase / Stop`; Choice
+`stopped after one retry`; Why `the single retry did not clear it`; Reverse = the resume command
+from the STOPPED banner.
+
+Supervised: the three-option menu verbatim (§ Supervised menus).
+
+### A-5 Waiting on the operator (no-argument runs only)
+
+After the default selection, before any work:
+
+```bash
+PD=$(pp_run query init.phase-op "$ONLY_PHASE" --pick phase_dir)
+[ -n "$PD" ] && WAIT=$(pp_run query verification.status "$PD" --pick status 2>/dev/null)
+```
+
+If `WAIT` is `human_needed` or `gaps_found`, print:
+
+```
+Phase ${ONLY_PHASE} is waiting on you — verification status: ${WAIT}.
+  Finish it with: /pp:verify-work ${ONLY_PHASE}
+  Or run the next phase instead: /pp:autonomous --only ${NEXT}
+```
+
+(the last line only when a later incomplete phase `NEXT` exists) and exit 0 without writing run state
+or a report entry — nothing was decided. The phase is not re-run.
+
+Supervised: same stop (it is not a prompt).
+
+### A-7 Run end — never claim completion for a deferred phase
+
+A phase handled this run with any outcome other than `passed` stays incomplete on disk, and the
+iterate exclusion (§ Run state) drops it from selection. So "no selectable phase remains" does NOT
+mean "all phases complete". Before any end banner, compute the deferred set:
+
+```bash
+# snippet: run-end
+# expects RUN_STATE
+DEFERRED=$(grep '^handled=' "$RUN_STATE" 2>/dev/null | grep -v ':passed$' | cut -d= -f2 | cut -d: -f1 | tr '\n' ' ')
+```
+
+- `DEFERRED` non-empty → print the end-of-run summary, then one line per deferred phase:
+  `Phase N — {outcome}: finish with /pp:verify-work N` (blocked: the resume command). Exit. Never
+  enter the milestone lifecycle and never print "All phases complete"; the `--to` REACHED banner
+  adds its `Deferred (not complete)` line.
+- `DEFERRED` empty → the normal end (lifecycle, or the single-phase banner).
+
+A `--only`/no-argument run whose phase was deferred prints the single-phase banner with
+`DEFERRED ⏭` in place of `COMPLETE ✓` (`autonomous-lifecycle.md`).
+
+Supervised: same rule — it is a report, not a prompt.
+
+### A-6 Lifecycle — deliberately NOT converted
+
+The audit gaps / tech-debt prompts and cleanup's own confirmation in `autonomous-lifecycle.md` stay
+interactive in every mode. They are milestone-level and destructive, and unreachable from a
+single-phase run.
+
+Supervised: unchanged.
+
+## Rules — nested sites (plan-phase.md, execute-phase.md)
+
+The host workflows receive `--unattended` from autonomous and carry a one-line `U-Pn` / `U-En`
+marker at each prompt site. At a marked site, apply the row below instead of prompting.
+
+| Rule | Host site | Best-effort action | Bound | Record (Point → Choice; Reverse) |
+|------|-----------|--------------------|-------|----------------------------------|
+| U-P1 | plan-phase §4 no CONTEXT.md | Continue without context (defensive — autonomous writes CONTEXT.md first) | — | No context → Continue without context; `/pp:discuss-phase N` |
+| U-P2 | plan-phase §5.1 research | Behave as `--auto`: research when `research_enabled`, else skip | — | none (config-driven) |
+| U-P3 | plan-phase §9 `PLANNING INCONCLUSIVE` | Retry once, then exit without plans (autonomous A-4 takes over) | once | Planning inconclusive → retried once; `/pp:plan-phase N` |
+| U-P4 | plan-phase §9 `CHECKPOINT REACHED` | Hard stop — present to user | — | none (hard stop) |
+| U-P5 | plan-phase §9a planner filesystem fallback | Accept plans on disk | — | Planner fallback → accepted plans on disk; `/pp:plan-phase N` |
+| U-P6 | plan-phase §9b phase split | Proceed anyway (never `/pp:phase --insert` — it mutates ROADMAP structure) | — | Phase split suggested → proceeded anyway; `/pp:phase --insert` |
+| U-P7 | plan-phase §9c source-audit gaps | Add plan once, then Defer, written to CONTEXT.md `## Deferred Ideas` as `auto-deferred by unattended run — not developer-confirmed` | once | Source-audit gap → added plan / deferred; `/pp:plan-phase N` |
+| U-P8 | plan-phase §11 thinking partner | Apply the recommendation | — | Thinking partner → applied; revert the revision |
+| U-P9 | plan-phase §11a checker fallback | Retry checker once, then Accept verification | once | Checker fallback → retried / accepted; `/pp:plan-phase N` |
+| U-P10 | plan-phase §12 max iterations | Force proceed; record the remaining issue list | — | Max iterations → force proceeded (issues listed); `/pp:plan-phase N` |
+| U-P11 | plan-phase §13 requirements coverage | Re-plan once, then Proceed anyway | once | Requirements coverage → re-planned / proceeded; `/pp:plan-phase N` |
+| U-P12 | plan-phase §13a decision coverage | Re-plan once, then Proceed anyway (the workflow already records the override in STATE.md) | once | Decision coverage → re-planned / proceeded; `/pp:plan-phase N` |
+| U-E1 | execute-phase checkpoint_handling | human-action, or `**Gate:** blocking-human` in the executor's return (`gate="blocking-human"` / a `Package` what-built are the pre-`Gate:` fallback): hard stop, present to user; other human-verify: continuation with `{user_response}` = `DEFERRED — not verified by a human (unattended run); record this checkpoint as not done in the SUMMARY and continue`, log `⏭ Checkpoint deferred (recorded, not approved)`; decision: the option marked recommended, else the first | — | Checkpoint → deferred / auto-selected; `/pp:verify-work N` |
+| U-E2 | execute-phase post-merge test failure | Fix now once, then Continue | once | Post-merge tests failed → fixed once / continued; `/pp:execute-phase N` |
+| U-E3 | execute-phase §7.1 quota exceeded | Option 3 — abort, report partial state (an unattended run cannot wait) | — | Quota exceeded → aborted; re-run after reset |
+| U-E4 | execute-phase §7.3 unknown failure Continue/Stop | Stop (cascade risk) — autonomous A-4 retries once | — | Unknown failure → stopped; `/pp:execute-phase N` |
+| U-E5 | execute-phase §7b cross-plan wiring gap | Investigate + fix once, then continue | once | Wiring gap → fixed once / continued; `/pp:verify-work N` |
+| U-E6 | execute-phase cross-phase regression | Option 1 once, then option 2 | once | Regression → option 1 / option 2; `/pp:execute-phase N` |
+| U-P13 | plan-phase §6 existing plans | `--gaps`: Add more plans (gap closure adds plans). Otherwise keep the existing plans and end planning — never Replan from scratch | — | Existing plans → added / kept; `/pp:plan-phase N` (choose Replan) |
+| U-P14 | plan-phase §5 `RESEARCH BLOCKED` | Hard stop — the missing context is the operator's | — | none (hard stop) |
+| U-P15 | plan-phase/steps/chunked-planning.md outline failure | Retry outline once, then Stop (autonomous A-4 takes over) | once | Outline failed → retried; `/pp:plan-phase N` |
+| U-P16 | plan-phase §12 revision-loop stall | Proceed anyway; record the remaining issue list (never Adjust approach — it opens a discussion) | — | Stall → proceeded (issues listed); `/pp:plan-phase N` |
+| U-E7 | execute-phase executor stall | Kill and retry once in a fresh worktree; a second stall → Stop. Never switch to inline execution | once | Stall → retried / stopped; `/pp:execute-phase N` |
+| U-E8 | execute-phase/steps/cross-ai-delegation.md failure | Retry once, then abort (never fall back silently to the local executor) | once | Cross-AI failure → retried / aborted; `/pp:execute-phase N` |
+| U-E9 | execute-phase `human_needed` result | Present the items and the `/pp:verify-work` command, do not wait for an acknowledgement, return to the caller (A-2 records it) | — | recorded by A-2 |
+
+Hosts derive `REPORT` with the § Recording one-liner from their own `PHASE_DIR` and append with the
+`report-append` snippet. "Once" bounds inside a host are per invocation.
+
+## Prompt-site inventory (sweep)
+
+Every prompt reachable from an unattended run, classified. Swept on 2026-09-29 by grepping
+`AskUserQuestion`, `Enter number`, `Offer`, `Options:`, `ask`, `confirmed` and `CHECKPOINT` across the
+two hosts, every file under `execute-phase/steps/` and `plan-phase/steps/`, the Skills autonomous
+calls (`pp-ui-phase`, `pp-code-review`, `pp-ui-review`) and the agents on the path (`pp-planner`,
+`pp-phase-researcher`, `pp-executor`, `pp-verifier`).
+
+| Site | Class |
+|------|-------|
+| plan-phase §4, §5.1, §9 inconclusive, §9a, §9b, §9c, §11, §11a, §12, §13, §13a, §6, §12 stall | converted — U-P1…U-P3, U-P5…U-P13, U-P16 |
+| plan-phase/steps/chunked-planning.md outline failure | converted — U-P15 |
+| plan-phase §9 planner `CHECKPOINT REACHED`; §5 `RESEARCH BLOCKED` | hard stop — U-P4, U-P14 |
+| execute-phase post-merge failure, quota, unknown failure, wiring gap, regression, stall, `human_needed` | converted — U-E2…U-E7, U-E9 |
+| execute-phase checkpoint_handling (executor `human-verify` / `decision`) | converted — U-E1 |
+| execute-phase checkpoint_handling (`human-action`, `gate="blocking-human"`) | hard stop — U-E1 |
+| execute-phase/steps/cross-ai-delegation.md failure | converted — U-E8 |
+| execute-phase/steps/vault-load-gate.md, client-context-gate.md `confirmed` | hard stop (governance) |
+| execute-phase / plan-phase blocking capability `check.query` gates (`blocking: true`, `block: true`) | hard stop (HALT) |
+| execute-phase/steps/worktree-recovery-policy.md exit 42; execute-phase partial-execution recovery | hard stop (fail closed) |
+| execute-phase `state_exists` false; `--interactive` per-plan menu | unreachable — autonomous requires STATE.md and never passes `--interactive` to execute-phase |
+| post-merge-gate | build-failure "Fix now / Continue" (step 5.8) — this is the U-E2 site: fix once, then continue and record |
+| codebase-drift-gate, serial-group-dispatch, vault-fetch | no prompt (non-blocking) |
+| `pp-code-review --fix --auto` (3c.5) | no prompt |
+| **`pp-ui-phase`** (§3a.5): step 9 max-revision choice, and its `pp-ui-researcher` design questions | **remaining stop** — ui-phase has no non-interactive flag; filed as deferred |
+| **`pp-ui-review`** (§3d.5): "UI-REVIEW.md already exists" | **remaining stop** (only on a re-run) — no non-interactive flag; filed as deferred |
+| agents: `pp-planner` / `pp-phase-researcher` / `pp-executor` / `pp-verifier` returns | routed through the host sites above; `pp-executor`'s own auto-approve under `workflow.auto_advance` is filed as deferred (not reached — autonomous sets neither auto flag) |
+
+Sweep result: no reachable prompt is unclassified. The two remaining stops (ui-phase, ui-review)
+are the only prompts an unattended run can still hit that are neither converted nor a deliberate
+hard stop.
+
+## Supervised menus
+
+Used only when `SUPERVISED` is set. Every label below is exactly the pre-best-effort text.
+
+**Text mode (`workflow.text_mode: true` in config or `--text` flag):** Set `TEXT_MODE=true` if `--text` is present in `$ARGUMENTS` OR `text_mode` from init JSON is `true`. When TEXT_MODE is active, replace every `AskUserQuestion` call with a plain-text numbered list and ask the user to type their choice number. This is required for non-Claude runtimes (OpenAI Codex, Gemini CLI, etc.) where `AskUserQuestion` is not available.
+
+### human_needed
+
+Display the items, then ask user via AskUserQuestion:
+- **question:** "Phase ${PHASE_NUM} has items needing manual verification. Validate now or continue to next phase?"
+- **options:** "Validate now" / "Continue without validation"
+
+On **"Validate now"**: Present the specific items from VERIFICATION.md's human_verification section. After user reviews, ask:
+- **question:** "Validation result?"
+- **options:** "All good — continue" / "Found issues"
+
+On "All good — continue": Display `Phase ${PHASE_NUM} ✅ Human validation passed` and proceed to iterate step.
+
+On "Found issues": Go to handle_blocker with the user's reported issues as the description.
+
+On **"Continue without validation"**: Display `Phase ${PHASE_NUM} ⏭ Human validation deferred` and proceed to iterate step.
+
+### gaps_found
+
+Ask user via AskUserQuestion:
+- **question:** "Gaps found in phase ${PHASE_NUM}. How to proceed?"
+- **options:** "Run gap closure" / "Continue without fixing" / "Stop autonomous mode"
+
+On **"Run gap closure"**: run the closure cycle in `autonomous.md` §3d (limit: 1 attempt), then re-read the status.
+
+If still `gaps_found` after this retry: Display "Gaps persist after closure attempt." and ask via AskUserQuestion:
+- **question:** "Gap closure did not fully resolve issues. How to proceed?"
+- **options:** "Continue anyway" / "Stop autonomous mode"
+
+On "Continue anyway": Proceed to iterate step.
+On "Stop autonomous mode": Go to handle_blocker.
+
+This limits gap closure to 1 automatic retry to prevent infinite loops.
+
+On **"Continue without fixing"**: Display `Phase ${PHASE_NUM} ⏭ Gaps deferred` and proceed to iterate step.
+
+On **"Stop autonomous mode"**: Go to handle_blocker with "User stopped — gaps remain in phase ${PHASE_NUM}".
+
+### Blocker (§6)
+
+When any phase operation fails or a blocker is detected, present 3 options via AskUserQuestion:
+
+**Prompt:** "Phase {N} ({Name}) encountered an issue: {description}"
+
+**Options:**
+1. **"Fix and retry"** — Re-run the failed step (discuss, plan, or execute) for this phase
+2. **"Skip this phase"** — Mark phase as skipped, continue to the next incomplete phase
+3. **"Stop autonomous mode"** — Display summary of progress so far and exit cleanly
+
+**On "Fix and retry":** Loop back to the failed step within execute_phase. If the same step fails again after retry, re-present these options.
+
+**On "Skip this phase":** Log `Phase {N} ⏭ {Name} — Skipped by user` and proceed to iterate.
+
+**On "Stop autonomous mode":** Display progress summary:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ pp-core ► AUTONOMOUS ▸ STOPPED
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+ Completed: {list of completed phases}
+ Skipped: {list of skipped phases}
+ Remaining: {list of remaining phases}
+
+ Resume with: /pp:autonomous ${ONLY_PHASE ? "--only " + ONLY_PHASE : "--from " + next_phase}${TO_PHASE ? " --to " + TO_PHASE : ""}
+```
+
+## End-of-run summary
+
+For each phase handled this run (the `handled=` lines in `$RUN_STATE`, or `ONLY_PHASE`): if its
+report exists, print
+
+`Decisions taken on your behalf — phase N: K (see {REPORT})`
+
+where K = `grep -c '^## Decision ' "$REPORT"`, then one line per entry,
+`- {Point} → {Choice} (reverse: {Reverse})`, read from the file. No report → print nothing for that
+phase. Printed by the lifecycle single-phase banner, the STOPPED banner and the lifecycle 5d banner.
+
+## Minimal CONTEXT.md (skip_discuss)
+
+Used by `autonomous.md` §3a when `workflow.skip_discuss` is true. Get phase details:
+
+```bash
+DETAIL=$(pp_run query roadmap.get-phase ${PHASE_NUM})
+```
+
+Extract `goal` and `requirements` from JSON. Write `${phase_dir}/${padded_phase}-CONTEXT.md` with:
+
+```markdown
+# Phase {PHASE_NUM}: {Phase Name} - Context
+
+**Gathered:** {date}
+**Status:** Ready for planning
+**Mode:** Auto-generated (discuss skipped via workflow.skip_discuss)
+
+<domain>
+## Phase Boundary
+
+{goal from ROADMAP phase description}
+
+</domain>
+
+<decisions>
+## Implementation Decisions
+
+### Claude's Discretion
+All implementation choices are at Claude's discretion — discuss phase was skipped per user setting. Use ROADMAP phase goal, success criteria, and codebase conventions to guide decisions.
+
+</decisions>
+
+<code_context>
+## Existing Code Insights
+
+Codebase context will be gathered during plan-phase research.
+
+</code_context>
+
+<specifics>
+## Specific Ideas
+
+No specific requirements — discuss phase skipped. Refer to ROADMAP phase description and success criteria.
+
+</specifics>
+
+<deferred>
+## Deferred Ideas
+
+None — discuss phase skipped.
+
+</deferred>
+```
+
+Commit the minimal context:
+
+```bash
+pp_run query commit "docs(${padded_phase}): auto-generated context (discuss skipped)" --files "${phase_dir}/${padded_phase}-CONTEXT.md"
+```
+
+## Banner math
+
+Where N = current phase number (from the ROADMAP, e.g., 63), T = total milestone phases (from `phase_count` parsed in initialize step, e.g., 67). **Important:** T must be `phase_count` (the total number of phases in this milestone), NOT the count of remaining/incomplete phases. When phases are numbered 61-67, T=7 and the banner should read `Phase 63/7` (phase 63, 7 total in milestone), not `Phase 63/3` (which would confuse 3 remaining with 3 total). P = percentage of all milestone phases completed so far. Calculate P as: (number of phases with `disk_status` "complete" from the latest `roadmap analyze` / T × 100). Use █ for filled and ░ for empty segments in the progress bar (8 characters wide).
+
+**Alternative display when phase numbers exceed total** (e.g., multi-milestone projects where phases are numbered globally): If N > T (phase number exceeds milestone phase count), use the format `Phase {N} ({position}/{T})` where `position` is the 1-based index of this phase among incomplete phases being processed. This prevents confusing displays like "Phase 63/5".

package/pp-core/references/autonomous-lifecycle.md

@@ -0,0 +1,146 @@
+# Autonomous — Milestone Lifecycle (§5)
+
+Extracted from `pp-core/workflows/autonomous.md` to keep that file under the
+Claude Code 10K-token Read limit (#2196), the same reason `smart_discuss` lives
+in `autonomous-lifecycle.md`'s sibling `autonomous-smart-discuss.md`.
+
+This file contains NO `pp_run` invocations, so it needs no launcher preamble —
+it is prose plus `Skill(...)` dispatches. Read it and follow it exactly when
+`## 5. Lifecycle` is reached in `autonomous.md`.
+
+---
+
+## Lifecycle
+
+The audit/cleanup prompts below are deliberately not converted to best-effort (rule A-6).
+
+**If `ONLY_PHASE` is set:** Skip lifecycle. A single phase does not trigger audit/complete/cleanup. Run `run-end` (rule A-7 in `autonomous-best-effort.md`); if the phase is in `DEFERRED`, the banner reads `DEFERRED ⏭` instead of `COMPLETE ✓` and `{outcome} — finish with /pp:verify-work ${ONLY_PHASE}` instead of `Done`. Display:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ pp-core ► AUTONOMOUS ▸ PHASE ${ONLY_PHASE} COMPLETE ✓
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+ Phase ${ONLY_PHASE}: ${PHASE_NAME} — Done
+ Mode: Single phase
+
+ Next: /pp:autonomous (runs the next incomplete phase) — lifecycle (audit → complete → cleanup) runs only when a --from/--to run finishes the last phase, or via /pp:audit-milestone and /pp:complete-milestone.
+```
+
+Print the end-of-run summary (reference § End-of-run summary), then exit cleanly.
+
+**If `TO_PHASE` is set and a fresh `pp_run query roadmap.analyze` still lists any phase with `disk_status != "complete"` or `roadmap_complete == false`:** the `--to` run stopped before the milestone's end. Skip lifecycle — never print "All phases complete". Print the end-of-run summary (reference § End-of-run summary) with `Remaining: {those phases}` and `Next: /pp:autonomous --from {first of them}`, then exit cleanly.
+
+**Otherwise:** Only when `run-end` (rule A-7) leaves `DEFERRED` empty AND no incomplete phase remains in the milestone — a deferred phase is not complete, so autonomous.md §4 exits before this point — run the milestone lifecycle sequence: audit → complete → cleanup.
+
+Display lifecycle transition banner:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ pp-core ► AUTONOMOUS ▸ LIFECYCLE
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+ All phases complete → Starting lifecycle: audit → complete → cleanup
+ Milestone: {milestone_version} — {milestone_name}
+```
+
+**5a. Audit**
+
+```
+Skill(skill="pp-audit-milestone")
+```
+
+After audit completes, detect the result:
+
+```bash
+AUDIT_FILE=".planning/v${milestone_version}-MILESTONE-AUDIT.md"
+AUDIT_STATUS=$(grep "^status:" "${AUDIT_FILE}" 2>/dev/null | head -1 | cut -d: -f2 | tr -d ' ')
+```
+
+**If AUDIT_STATUS is empty** (no audit file or no status field):
+
+Go to handle_blocker: "Audit did not produce results — audit file missing or malformed."
+
+**If `passed`:**
+
+Display:
+```
+Audit ✅ passed — proceeding to complete milestone
+```
+
+Proceed to 5b (no user pause — per CTRL-01).
+
+**If `gaps_found`:**
+
+Read the gaps summary from the audit file. Display:
+```
+⚠ Audit: Gaps Found
+```
+
+Ask user via AskUserQuestion:
+- **question:** "Milestone audit found gaps. How to proceed?"
+- **options:** "Continue anyway — accept gaps" / "Stop — fix gaps manually"
+
+On **"Continue anyway"**: Display `Audit ⏭ Gaps accepted — proceeding to complete milestone` and proceed to 5b.
+
+On **"Stop"**: Go to handle_blocker with "User stopped — audit gaps remain. Run /pp:audit-milestone to review, then /pp:complete-milestone when ready."
+
+**If `tech_debt`:**
+
+Read the tech debt summary from the audit file. Display:
+```
+⚠ Audit: Tech Debt Identified
+```
+
+Show the summary, then ask user via AskUserQuestion:
+- **question:** "Milestone audit found tech debt. How to proceed?"
+- **options:** "Continue with tech debt" / "Stop — address debt first"
+
+On **"Continue with tech debt"**: Display `Audit ⏭ Tech debt acknowledged — proceeding to complete milestone` and proceed to 5b.
+
+On **"Stop"**: Go to handle_blocker with "User stopped — tech debt to address. Run /pp:audit-milestone to review details."
+
+**5b. Complete Milestone**
+
+```
+Skill(skill="pp-complete-milestone", args="${milestone_version}")
+```
+
+After complete-milestone returns, verify it produced output:
+
+```bash
+ls .planning/milestones/v${milestone_version}-ROADMAP.md 2>/dev/null || true
+```
+
+If the archive file does not exist, go to handle_blocker: "Complete milestone did not produce expected archive files."
+
+**5c. Cleanup**
+
+```
+Skill(skill="pp-cleanup")
+```
+
+Cleanup shows its own dry-run and asks user for approval internally — this is an acceptable pause per CTRL-01 since it's an explicit decision about file deletion.
+
+**5d. Final Completion**
+
+Display final completion banner:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ pp-core ► AUTONOMOUS ▸ COMPLETE 🎉
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+ Milestone: {milestone_version} — {milestone_name}
+ Status: Complete ✅
+ Lifecycle: audit ✅ → complete ✅ → cleanup ✅
+
+ Ship it! 🚀
+```
+
+Print the end-of-run summary (`pp-core/references/autonomous-best-effort.md` § End-of-run summary).
+
+</step>
+
+<step name="handle_blocker">
+