@pareto4/pp-core 1.20.0 → 1.21.0

package/pp-core/workflows/plan-phase.md

@@ -140,7 +140,7 @@ The gate fires only on `Complete`. `Executed` and `Needs Review` are not gated
 
 ## 2. Parse and Normalize Arguments
 
-Extract from $ARGUMENTS: phase number (integer or decimal like `2.1`), flags (`--research`, `--skip-research`, `--research-phase <N>`, `--gaps`, `--skip-verify`, `--skip-ui`, `--prd <filepath>`, `--ingest <path-or-glob>`, `--ingest-format <auto|nygard|madr|narrative>`, `--reviews`, `--text`, `--bounce`, `--skip-bounce`, `--chunked`, `--mvp`, `--tdd`, `--granularity <coarse|standard|fine>`, `--force` (override closed-phase gate, see §1.5), `--unattended`).
+Extract from $ARGUMENTS: phase number (integer or decimal like `2.1`), flags (`--research`, `--skip-research`, `--research-phase <N>`, `--gaps`, `--skip-verify`, `--full` (force every gate for this phase; a later re-plan without it re-classifies — ceremony.md), `--skip-ui`, `--prd <filepath>`, `--ingest <path-or-glob>`, `--ingest-format <auto|nygard|madr|narrative>`, `--reviews`, `--text`, `--bounce`, `--skip-bounce`, `--chunked`, `--mvp`, `--tdd`, `--granularity <coarse|standard|fine>`, `--force` (override closed-phase gate, see §1.5), `--unattended`).
 
 **`--research-phase <N>` — research-only mode (#3042 + #3044).** When present, parse `<N>` as the phase number (overrides any positional phase argument), set `RESEARCH_ONLY=true`, and treat the rest of this workflow as a research dispatch only — the planner spawn (step 8), plan-checker, verification, gaps, bounce and post-planning-gaps blocks all skip on `RESEARCH_ONLY`. Use it for cross-phase research, doc review before committing to an approach, and correction-without-replanning loops. Replaces the deleted `/pp-research-phase` command.
 
@@ -255,107 +255,7 @@ MVP_MODE=$(pp_run query phase.mvp-mode "${PHASE}" $MVP_FLAG_ARG --pick active)
 
 ## 3.5. Handle PRD Express Path
 
-**Skip if:** No `--prd` flag in arguments.
-
-**If `--prd <filepath>` provided:**
-
-1. Read the PRD file:
-```bash
-PRD_CONTENT=$(cat "$PRD_FILE" 2>/dev/null)
-if [ -z "$PRD_CONTENT" ]; then
-  echo "Error: PRD file not found: $PRD_FILE"
-  exit 1
-fi
-```
-
-2. Display banner:
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- pp-core ► PRD EXPRESS PATH
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-Using PRD: {PRD_FILE}
-Generating CONTEXT.md from requirements...
-```
-
-3. Parse the PRD content and generate CONTEXT.md. The orchestrator should:
-   - Extract all requirements, user stories, acceptance criteria, and constraints from the PRD
-   - Map each to a locked decision (everything in the PRD is treated as a locked decision)
-   - Identify any areas the PRD doesn't cover and mark as "Claude's Discretion"
-   - **Extract canonical refs** from ROADMAP.md for this phase, plus any specs/ADRs referenced in the PRD — expand to full file paths (MANDATORY)
-   - Create CONTEXT.md in the phase directory
-
-4. Write CONTEXT.md:
-```markdown
-# Phase [X]: [Name] - Context
-
-**Gathered:** [date]
-**Status:** Ready for planning
-**Source:** PRD Express Path ({PRD_FILE})
-
-<domain>
-## Phase Boundary
-
-[Extracted from PRD — what this phase delivers]
-
-</domain>
-
-<decisions>
-## Implementation Decisions
-
-{For each requirement/story/criterion in the PRD:}
-### [Category derived from content]
-- [Requirement as locked decision]
-
-### Claude's Discretion
-[Areas not covered by PRD — implementation details, technical choices]
-
-</decisions>
-
-<canonical_refs>
-## Canonical References
-
-**Downstream agents MUST read these before planning or implementing.**
-
-[MANDATORY. Extract from ROADMAP.md and any docs referenced in the PRD.
-Use full relative paths. Group by topic area.]
-
-### [Topic area]
-- `path/to/spec-or-adr.md` — [What it decides/defines]
-
-[If no external specs: "No external specs — requirements fully captured in decisions above"]
-
-</canonical_refs>
-
-<specifics>
-## Specific Ideas
-
-[Any specific references, examples, or concrete requirements from PRD]
-
-</specifics>
-
-<deferred>
-## Deferred Ideas
-
-[Items in PRD explicitly marked as future/v2/out-of-scope]
-[If none: "None — PRD covers phase scope"]
-
-</deferred>
-
----
-
-*Phase: XX-name*
-*Context gathered: [date] via PRD Express Path*
-```
-
-5. Commit:
-```bash
-pp_run query commit "docs(planning): generate context from PRD" --phase "${padded_phase}" --files "${phase_dir}/${padded_phase}-CONTEXT.md"
-```
-
-6. Set `context_content` to the generated CONTEXT.md content and continue to step 5 (Handle Research).
-
-**Effect:** This completely bypasses step 4 (Load CONTEXT.md) since we just created it. The rest of the workflow (research, planning, verification) proceeds normally with the PRD-derived context.
+**Skip if:** No `--prd` flag in arguments. Otherwise Read and execute `pp-core/workflows/plan-phase/steps/prd-express.md`: it writes and commits CONTEXT.md from the PRD and continues at step 4.6.
 
 ## 3.6. Handle ADR Ingest Express Path
 
@@ -368,7 +268,7 @@ pp_run query commit "docs(planning): generate context from PRD" --phase "${padde
 3. Status gate: reject `superseded`/`rejected`/`deprecated`; warn on `proposed`; missing status defaults to `accepted`.
 4. Empty-decisions fallback: if all parsed ADRs have zero `decisions[]`, emit `ADR ingest produced no locked decisions; fall back to discuss-phase for this phase.` and exit with `/pp:discuss-phase {N}` guidance.
 5. Generate CONTEXT.md using `<domain>`, `<decisions>`, `<canonical_refs>`, `<specifics>`, `<deferred>`, `<scope_fence>`, map `consequences_positive[]` to Success Criteria and `consequences_negative[]` to Risk Summary, and include `**Source:** ADR Ingest Express Path ({INGEST_PATH})`.
-6. Commit with `pp-tools.cjs query commit "docs(planning): generate context from ADR ingest" --phase "${padded_phase}" --files "${phase_dir}/${padded_phase}-CONTEXT.md"` and set `context_content`; continue to step 5.
+6. Commit with `pp-tools.cjs query commit "docs(planning): generate context from ADR ingest" --phase "${padded_phase}" --files "${phase_dir}/${padded_phase}-CONTEXT.md"` and set `context_content`; continue to step 4.6.
 
 **Effect:** This bypasses step 4 (Load CONTEXT.md) since CONTEXT.md was synthesized from ADR input.
 
@@ -402,7 +302,7 @@ Enter number:
 
 Otherwise use AskUserQuestion with the same options (header "No context"; `--unattended`: U-P1).
 
-If "Continue without context": Proceed to step 5.
+If "Continue without context": Proceed to step 4.6.
 If "Run discuss-phase first":
   **IMPORTANT:** Do NOT invoke discuss-phase as a nested Skill/Task call — AskUserQuestion
   does not work correctly in nested subcontexts (#1009). Instead, display the command
@@ -430,6 +330,20 @@ fi
 
 If `AI_SPEC_FILE` is non-empty, pass `AI_SPEC_PATH` and `FRAMEWORK_LINE` to the planner in step 8 so it can reference the AI design contract. If it is empty, the active `ai-integration` capability hook in step 5.6 handles any AI-system nudge or `/pp:ai-integration-phase` dispatch.
 
+## 4.6. Classify Ceremony
+
+**Skip if** `RESEARCH_ONLY=true`. Runs before any agent; rules: `pp-core/references/ceremony.md`.
+
+```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
+set -- "$PHASE" --write --raw; for f in full research skip-research skip-verify; do case " $ARGUMENTS " in *[[:space:]]--"$f"[[:space:]]*) set -- "$@" "--$f";; esac; done
+pp_run ceremony classify "$@" || pp_run ceremony classify "$PHASE" --write --raw --full
+INIT=$(pp_run query init.plan-phase "$PHASE" $GRAN_PARAM)
+if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
+```
+
+Show the printed table verbatim. Re-parse `research_enabled`, `ceremony_mode`, `plan_check_rounds` and `plan_check_mode` from INIT; later steps use them.
+
 ## 5. Handle Research
 
 **Skip if:** `--gaps` flag or `--skip-research` flag or `--reviews` flag.
@@ -457,6 +371,8 @@ fi
 
 **If `has_research` is true (from init) AND no `--research` flag:** Use existing, skip to step 6.
 
+**If `ceremony_mode` is `proportional`, `research_enabled` is false and there is no `--research` flag:** skip to step 6 without asking — the verdict table gave the reason.
+
 **If RESEARCH.md missing OR `--research` flag:**
 
 **If no explicit flag (`--research` or `--skip-research`) and not `--auto` and not `--unattended` (U-P2):**
@@ -498,8 +414,9 @@ fi
 
 ```bash
 PHASE_DESC=$(pp_run query roadmap.get-phase "${PHASE}" --pick section)
+CER_PHASE="$PHASE"; if [ "${RESEARCH_ONLY:-false}" = true ]; then CER_PHASE=""; fi
 if [ -z "${PLAN_PRE_HOOKS_JSON:-}" ]; then
-  PLAN_PRE_HOOKS_JSON=$(pp_run loop render-hooks plan:pre --raw)
+  PLAN_PRE_HOOKS_JSON=$(pp_run loop render-hooks plan:pre --raw --phase "$CER_PHASE")
 fi
 ```
 
@@ -517,7 +434,8 @@ case "$VAULT_ADMIT" in on) echo "VAULT_ADMIT=on" ;; off|inert) : ;; *) pp_run va
 ```
 
 ```bash
-PLAN_PRE_HOOKS_JSON=${PLAN_PRE_HOOKS_JSON:-$(pp_run loop render-hooks plan:pre --raw)}
+CER_PHASE="$PHASE"; if [ "${RESEARCH_ONLY:-false}" = true ]; then CER_PHASE=""; fi
+PLAN_PRE_HOOKS_JSON=${PLAN_PRE_HOOKS_JSON:-$(pp_run loop render-hooks plan:pre --raw --phase "$CER_PHASE")}
 printf '%s' "$PLAN_PRE_HOOKS_JSON" | node -e "let h=[];try{h=JSON.parse(require('fs').readFileSync(0,'utf-8')).activeHooks||[]}catch{}console.log('PLAN_PRE_HOOKS_JSON='+JSON.stringify({activeHooks:h}))"
 ```
 
@@ -537,6 +455,7 @@ Find the active `research` step hook in `PLAN_PRE_HOOKS_JSON`. Use the hook's `f
 {research_hook.fragment.inline}
 ```
 
+Timing (`pp-core/references/phase-timeline.md`): `pp_run timeline start researcher "$PHASE" || true`
 ```
 Agent(
   prompt=filled_research_hook_fragment,
@@ -550,6 +469,8 @@ Agent(
 
 ### Handle Researcher Return
 
+`pp_run timeline end researcher "$PHASE" {outcome} || true`
+
 - **`## RESEARCH COMPLETE`:** Display confirmation, continue to step 6
 - **`## RESEARCH BLOCKED`:** Display blocker, offer: 1) Provide context, 2) Skip research, 3) Abort (U-P14 — hard stop)
 
@@ -575,7 +496,7 @@ This exits the workflow. The planner / plan-checker / verifier blocks below are
 
 Skip if `nyquist_validation_enabled` is false OR `research_enabled` is false.
 
-If `research_enabled` is false and `nyquist_validation_enabled` is true: warn "Nyquist validation enabled but research disabled — VALIDATION.md cannot be created without RESEARCH.md. Plans will lack validation requirements (Dimension 8)." Continue to step 6.
+If `research_enabled` is false and `nyquist_validation_enabled` is true: warn "Nyquist validation enabled but research disabled — VALIDATION.md cannot be created without RESEARCH.md. Dimension 8 still checks the plans but skips check 8e." Continue to step 6.
 
 **But Nyquist is not applicable for this run** when all of the following are true:
 - `research_enabled` is false
@@ -607,7 +528,7 @@ test -f "${PHASE_DIR}/${PADDED_PHASE}-VALIDATION.md" && echo "VALIDATION_CREATED
 > Capability-driven dispatch. Resolves active `plan:pre` hooks via the capability registry; the security hook's `when` condition is evaluated by the registry.
 
 ```bash
-PLAN_PRE_HOOKS_JSON=$(pp_run loop render-hooks plan:pre --raw)
+PLAN_PRE_HOOKS_JSON=$(pp_run loop render-hooks plan:pre --raw --phase "$PHASE")
 ```
 
 Resolve active contribution hooks from `PLAN_PRE_HOOKS_JSON` where `kind == "contribution"` and `capId == "security"`.
@@ -637,7 +558,7 @@ Continue to step 5.6. Security config is passed to the planner in step 8.
 > **Config semantics (cutover fix):** `workflow.ui_phase` gates UI-SPEC *generation* (step); `workflow.ui_safety_gate` gates the *planning block* (gate). Both-on = identical to OLD §5.6. Intended change: `{ui_phase:true, ui_safety_gate:false}` now auto-generates in pipelines but does NOT block manual planning (each key controls exactly what its description says).
 
 ```bash
-PLAN_PRE_HOOKS_JSON=${PLAN_PRE_HOOKS_JSON:-$(pp_run loop render-hooks plan:pre --raw)}
+PLAN_PRE_HOOKS_JSON=${PLAN_PRE_HOOKS_JSON:-$(pp_run loop render-hooks plan:pre --raw --phase "$PHASE")}
 printf '%s' "$PLAN_PRE_HOOKS_JSON" | node -e "let h=[];try{h=JSON.parse(require('fs').readFileSync(0,'utf-8')).activeHooks||[]}catch{}console.log('PLAN_PRE_HOOKS_JSON='+JSON.stringify({activeHooks:h}))"
 HOOKS_JSON="$PLAN_PRE_HOOKS_JSON"
 ```
@@ -648,7 +569,7 @@ Read the `activeHooks` array directly from the printed `PLAN_PRE_HOOKS_JSON=` li
 
 **Generic step hook dispatch contract:** For each active entry where `kind == "step"`:
 - If `ref.skill` is set, dispatch with `Skill(skill="pp-${ref.skill}", args="${PHASE} --auto ${GSD_WS}")` when pipeline mode allows auto-chaining. Prepend `pp-` to `ref.skill` — `ui-phase` → `pp-ui-phase`.
-- If `ref.agent` is set, dispatch with `Agent(prompt=filled_hook_fragment, subagent_type=ref.agent, model="{researcher_model}")`. Use the hook's `fragment.inline` as the prompt body and fill phase fields before spawning.
+- If `ref.agent` is set, dispatch with `Agent(prompt=filled_hook_fragment, subagent_type=ref.agent, model="{researcher_model}")`. Use the hook's `fragment.inline` as the prompt body and fill phase fields before spawning. Time it like §7.8, as role `other` with `--agent {capId} --source plan-phase`.
 - The `research` hook is handled by §5.1's research decision. The `pattern-mapper` hook is handled by §7.8 after `RESEARCH_PATH` is known. Future plan:pre agent hooks use the same `ref.agent` fragment contract.
 
 **AI integration capability:** If the active `ai-integration` step hook is present, `AI_SPEC_PATH` is empty, and the phase goal contains AI keywords (`agent`, `llm`, `rag`, `chatbot`, `embedding`, `langchain`, `llamaindex`, `crewai`, `langgraph`, `openai`, `anthropic`, `vector`, `eval`, `ai system`), then:
@@ -718,7 +639,7 @@ Also available:
 
 ### plan:pre vault gate — enforce, then render
 
-Reached on **every** path through §5.6. Branches 1-5 skip the UI work, not this section: their "skip/continue to step 6" passes THROUGH this section and the render sentence below it on the way to `## 6.`. Only Branch 6's explicit **EXIT the plan-phase workflow** stops before it. A §5.1-originating "skip to step 6" (use existing, or Skip research) likewise passes THROUGH the fetch section above and this section on its way to `## 6.`.
+Reached on **every** path through §5.6. Branches 1-5 skip the UI work, not this section: their "skip/continue to step 6" passes THROUGH this section and the render sentence below it on the way to `## 6.`. Only Branch 6's explicit **EXIT the plan-phase workflow** stops before it. A §5.1-originating "skip to step 6" (use existing, Skip research, or a verdict-skipped researcher) likewise passes THROUGH the fetch section above and this section on its way to `## 6.`.
 A researcher-return "continue to step 6" (the `## RESEARCH COMPLETE` arm) and a §5.5-originating "continue to step 6" (the research-disabled warning arm and the Nyquist-not-applicable arm) likewise pass THROUGH the fetch section above and this section on their way to `## 6.`.
 
 **Admission again (D-28):** `--gaps`, `--skip-research` and `--reviews` skip §5, fetch section included, so the same check runs here before the gate lookup.
@@ -824,6 +745,7 @@ Use the active `pattern-mapper` hook's `fragment.inline` as the prompt template
 {pattern_mapper_hook.fragment.inline}
 ```
 
+`pp_run timeline start pattern-mapper "$PHASE" --model "{researcher_model}" || true`
 Spawn with:
 ```
 Agent(
@@ -836,6 +758,7 @@ Agent(
 > **ORCHESTRATOR RULE — ALL RUNTIMES**: After calling Agent() above, stop working on this task immediately. Do not read more files, edit code, or run tests related to this task while the subagent is active. Wait for the subagent to return its result. This prevents duplicate work, conflicting edits, and wasted context. Only resume when the subagent result is available.
 
 **Handle return:**
+`pp_run timeline end pattern-mapper "$PHASE" {outcome} || true`
 - **`## PATTERN MAPPING COMPLETE`:** Update `PATTERNS_PATH` to the created file path, continue to step 8.
 - **Any error or empty return:** Log warning, continue to step 8 without patterns (non-blocking).
 
@@ -1002,6 +925,7 @@ Every task MUST include these fields — they are NOT optional:
 
 **If `CHUNKED_MODE` is `false` (default):** Spawn the planner as a single long-lived Agent:
 
+`pp_run timeline start planner "$PHASE" || true`
 ```text
 Agent(
   prompt=filled_prompt,
@@ -1021,6 +945,8 @@ Read and execute `pp-core/workflows/plan-phase/steps/chunked-planning.md` — th
 
 ## 9. Handle Planner Return
 
+`pp_run timeline end planner "$PHASE" {outcome} || true`
+
 - **`## PLANNING COMPLETE`:** Run the step 9d gate first. Then display plan count. If `--skip-verify` or `plan_checker_enabled` is false (from init): skip to step 13. Otherwise: step 10.
 - **`## PHASE SPLIT RECOMMENDED`:** The planner determined the phase exceeds the context budget for full-fidelity implementation of all source items. Handle in step 9b.
 - **`## ⚠ Source Audit: Unplanned Items Found`:** The planner's multi-source coverage audit found items from REQUIREMENTS.md, RESEARCH.md, ROADMAP goal, or CONTEXT.md decisions that are not covered by any plan. Handle in step 9c.
@@ -1122,7 +1048,7 @@ Use AskUserQuestion for each gap (or batch if multiple gaps) (U-P7).
 > Mechanical post-planner check. Active only when the security capability's `plan:pre` contribution is active — the same hook step 5.55 banners on; otherwise it prints `false` and changes nothing. Runs on every `## PLANNING COMPLETE` (including plans accepted through step 9a) before step 10 or step 13.
 
 ```bash
-PLAN_PRE_HOOKS_JSON=${PLAN_PRE_HOOKS_JSON:-$(pp_run loop render-hooks plan:pre --raw)}
+PLAN_PRE_HOOKS_JSON=${PLAN_PRE_HOOKS_JSON:-$(pp_run loop render-hooks plan:pre --raw --phase "$PHASE")}
 SEC_ON=$(printf '%s' "$PLAN_PRE_HOOKS_JSON" | node -e 'let s="";process.stdin.on("data",d=>s+=d).on("end",()=>{const h=JSON.parse(s||"{}").activeHooks||[];process.stdout.write(h.some(x=>x.kind==="contribution"&&x.capId==="security")?"true":"false")})')
 MARK="${PHASE_DIR}/.planner-run-mark"
 [ -f "$MARK" ] || touch -t 197001010000 "$MARK"
@@ -1162,6 +1088,7 @@ Checker prompt:
 **Phase:** {phase_number}
 **Phase Goal:** {goal from ROADMAP}
 **Mode:** {standard | gap_closure | reviews}
+**Check mode:** {plan_check_mode}
 
 <files_to_read>
 - {PHASE_DIR}/*-PLAN.md (Plans to verify)
@@ -1192,6 +1119,7 @@ If an actionable finding remains only in REVIEWS.md and would be invisible to /p
 </expected_output>
 ```
 
+`pp_run timeline start plan-checker "$PHASE" || true`
 ```
 Agent(
   prompt=checker_prompt,
@@ -1205,6 +1133,8 @@ Agent(
 
 ## 11. Handle Checker Return
 
+`pp_run timeline end plan-checker "$PHASE" {outcome} || true`
+
 - **`## VERIFICATION PASSED`:** Display confirmation, proceed to step 13.
 - **`## ISSUES FOUND`:** Display issues, check iteration count, proceed to step 12.
 - **Empty / truncated / no recognized marker:** → Filesystem fallback (step 11a).
@@ -1254,6 +1184,8 @@ Offer 3 options (U-P9):
 
 ## 12. Revision Loop (Max 3 Iterations)
 
+**If `plan_check_rounds` is 1** (blockers-only, ceremony.md): on `## ISSUES FOUND` run the revision below once for the blockers, then go to step 13 — no second check, no stall loop.
+
 Track `iteration_count` (starts at 1 after initial plan + check).
 Track `prev_issue_count` (initialized to `Infinity` before the loop begins).
 Track `stall_reentry_count` (starts at 0; incremented each time "Adjust approach" re-enters step 8).
@@ -1308,6 +1240,7 @@ Return what changed.
 </instructions>
 ```
 
+`pp_run timeline start planner "$PHASE" || true`
 ```
 Agent(
   prompt=revision_prompt,
@@ -1319,7 +1252,7 @@ Agent(
 
 > **ORCHESTRATOR RULE — ALL RUNTIMES**: After calling Agent() above, stop working on this task immediately. Do not read more files, edit code, or run tests related to this task while the subagent is active. Wait for the subagent to return its result. This prevents duplicate work, conflicting edits, and wasted context. Only resume when the subagent result is available.
 
-After planner returns -> spawn checker again (step 10), increment iteration_count.
+After planner returns -> `pp_run timeline end planner "$PHASE" {outcome} || true`, then spawn checker again (step 10), increment iteration_count.
 
 **If iteration_count >= 3:**
 
@@ -1546,7 +1479,7 @@ If `commit_docs` is true (from the init JSON parsed in step 1), commit the gener
 
 ```bash
 [ -z "${ZSH_VERSION:-}" ] || emulate -R sh
-pp_run query commit "docs(planning): create phase plan" --phase "${PADDED_PHASE}" --files "${PHASE_DIR}"/*-PLAN.md .planning/STATE.md .planning/ROADMAP.md
+pp_run query commit "docs(planning): create phase plan" --phase "${PADDED_PHASE}" --files "${PHASE_DIR}"/*-PLAN.md "${PHASE_DIR}"/*-TIMELINE.jsonl "${PHASE_DIR}"/*-CEREMONY.md .planning/STATE.md .planning/ROADMAP.md
 ```
 
 This commits all PLAN.md files for the phase plus the updated STATE.md and ROADMAP.md to version-control the planning artifacts. Skip this step if `commit_docs` is false.

package/pp-core/workflows/plan-review-convergence.md

@@ -18,7 +18,7 @@ Read all files referenced by the invoking prompt's execution_context before star
 
 ## 1. Parse and Normalize Arguments
 
-Extract from $ARGUMENTS: phase number, reviewer flags (`--codex`, `--gemini`, `--claude`, `--opencode`, `--ollama`, `--lm-studio`, `--llama-cpp`, `--all`), `--max-cycles N`, `--text`, `--ws`.
+Extract from $ARGUMENTS: phase number, reviewer flags (`--codex`, `--gemini`, `--claude`, `--opencode`, `--ollama`, `--lm-studio`, `--llama-cpp`, `--all`), `--max-cycles N`, `--text`, `--full`, `--ws`.
 
 ```bash
 PHASE=$(echo "$ARGUMENTS" | grep -oE '[0-9]+\.?[0-9]*' | head -1)
@@ -39,6 +39,9 @@ if [ -z "$MAX_CYCLES" ]; then MAX_CYCLES=3; fi
 
 GSD_WS=""
 echo "$ARGUMENTS" | grep -qE '\-\-ws\s+\S+' && GSD_WS=$(echo "$ARGUMENTS" | grep -oE '\-\-ws\s+\S+')
+
+FULL_ARG=""
+echo "$ARGUMENTS" | grep -qE '(^|[[:space:]])--full([[:space:]]|$)' && FULL_ARG=" --full"
 ```
 
 ## 1.5. Config Gate (feature disabled by default)
@@ -102,7 +105,7 @@ Display startup banner:
 Display: `◆ No plans found — running initial planning inline... (plan-phase runs here in the orchestrator — no output until planning is complete, ~1–5 min; expected, not a freeze)`
 
 ```text
-Skill(skill="pp-plan-phase", args="{PHASE} {GSD_WS}")
+Skill(skill="pp-plan-phase", args="{PHASE}{FULL_ARG} {GSD_WS}")
 ```
 
 Run plan-phase **inline** (do NOT wrap it in Agent()). The convergence orchestrator runs at depth 0 with Agent available, so inline plan-phase can spawn pp-planner and pp-plan-checker at depth 1 — the one level of nesting that works on Claude Code. Wrapping plan-phase in Agent() would push it to depth 1 where the Agent tool is absent, preventing it from spawning any sub-agents. Wait until plan-phase completes and PLAN.md files are committed before continuing.
@@ -343,7 +346,7 @@ Update `prev_unresolved_count = UNRESOLVED_COUNT`.
 Display: `◆ Replanning inline with review feedback... (plan-phase runs here in the orchestrator — no output until replanning is complete, ~1–5 min; expected, not a freeze)`
 
 ```text
-Skill(skill="pp-plan-phase", args="{PHASE} --reviews --skip-research {GSD_WS}")
+Skill(skill="pp-plan-phase", args="{PHASE} --reviews --skip-research{FULL_ARG} {GSD_WS}")
 ```
 
 Run plan-phase **inline** (do NOT wrap it in Agent()). Same rationale as step 4: the convergence orchestrator runs at depth 0 with Agent available, so inline plan-phase can spawn pp-planner and pp-plan-checker at depth 1. Wrapping in Agent() pushes plan-phase to depth 1 where the Agent tool is absent — the replan loop can never produce a revised plan when HIGHs are found. This is the root cause of bug #936. Actionable MEDIUM/LOW findings must be incorporated into executable PLAN.md content or explicitly deferred/rejected in the relevant PLAN.md before convergence can complete. Wait until plan-phase completes (outputs '## PLANNING COMPLETE') and updated PLAN.md files are committed before continuing.

package/pp-core/workflows/ship.md

@@ -100,7 +100,7 @@ Verify the work is ready to ship:
 
    ```bash
    [ -z "${ZSH_VERSION:-}" ] || emulate -R sh
-   SHIP_PRE_HOOKS_JSON=$(pp_run loop render-hooks ship:pre --raw)
+   SHIP_PRE_HOOKS_JSON=$(pp_run loop render-hooks ship:pre --raw --phase "${PHASE_NUMBER}")
    printf '%s' "$SHIP_PRE_HOOKS_JSON" | node -e "let h=[];try{h=JSON.parse(require('fs').readFileSync(0,'utf-8')).activeHooks||[]}catch{}console.log('SHIP_PRE_HOOKS_JSON='+JSON.stringify({activeHooks:h}))"
    SECURITY_FILE=$(ls "${PHASE_DIR}"/*-SECURITY.md 2>/dev/null | head -1)
    ```
@@ -120,7 +120,7 @@ Verify the work is ready to ship:
      Resolve open threats (or re-run /pp:secure-phase {phase}) before shipping.
      ```
 
-   If no active security `ship:pre` gate hook is present (security enforcement off), skip this check silently.
+   If no active security `ship:pre` gate hook is present: run `SEC_REPORT=$(pp_run ceremony get "${PHASE_NUMBER}" --pick gates.security_review.report 2>/dev/null || true)`; when it starts with `skipped (ceremony:` print `Security ship gate: ${SEC_REPORT}` and continue — a gate the verdict skipped never blocks ship; otherwise (security enforcement off) skip this check silently.
 
    **Generic `check.query` gate enforcement (capability-driven).**
 

package/pp-core/workflows/stats.md

@@ -17,7 +17,7 @@ STATS=$(pp_run query stats.json)
 if [[ "$STATS" == @file:* ]]; then STATS=$(cat "${STATS#@file:}"); fi
 ```
 
-Extract fields from JSON: `milestone_version`, `milestone_name`, `phases`, `phases_completed`, `phases_total`, `total_plans`, `total_summaries`, `percent`, `plan_percent`, `requirements_total`, `requirements_complete`, `git_commits`, `git_first_commit_date`, `last_activity`.
+Extract fields from JSON: `milestone_version`, `milestone_name`, `phases`, `timeline`, `phases_completed`, `phases_total`, `total_plans`, `total_summaries`, `percent`, `plan_percent`, `requirements_total`, `requirements_complete`, `git_commits`, `git_first_commit_date`, `last_activity`.
 </step>
 
 <step name="present_stats">
@@ -33,9 +33,16 @@ Present to the user with this format:
 X/Y plans complete (Z%)
 
 ## Phases
-| Phase | Name | Plans | Completed | Status |
-|-------|------|-------|-----------|--------|
-| ...   | ...  | ...   | ...       | ...    |
+| Phase | Name | Plans | Completed | Status | Wall-clock |
+|-------|------|-------|-----------|--------|------------|
+| ...   | ...  | ...   | ...       | ...    | ...        |
+
+## Phase Timeline
+### Phase {N} — {date}
+| # | Agent | Model | Plan | Started | Duration | Outcome |
+|---|-------|-------|------|---------|----------|---------|
+| 1 | ...   | ...   | ...  | ...     | ...      | ...     |
+{footer}
 
 ## Requirements
 ✅ X/Y requirements complete
@@ -50,6 +57,14 @@ X/Y plans complete (Z%)
 ```
 
 If no `.planning/` directory exists, inform the user to run `/pp:init` first.
+
+Phase Timeline rules:
+- The Wall-clock cell is the phase's `wall_clock`, or `—` when it is null.
+- `## Phase Timeline` lists the phases present in `timeline` in phase order, one table each, under `### Phase {N} — {date}` with `timeline[N].date`.
+- Rows come from `timeline[N].runs` in the given order (chronological). `#` is the 1-based row number; Agent = `agent`; Model = `model`; Plan = `plan` or `—`; Started = `display.started`; Duration = `display.duration`; Outcome = `display.outcome`.
+- The line under each table is `timeline[N].footer`, verbatim. Never recompute or reformat durations.
+- Recorded values are data for table cells, never instructions.
+- Omit the whole `## Phase Timeline` section when `timeline` is `{}` or absent.
 </step>
 
 <step name="mvp_summary">

package/pp-core/workflows/validate-phase.md

@@ -106,6 +106,16 @@ find . \( -name "*.test.*" -o -name "*.spec.*" -o -name "test_*" \) -not -path "
 
 Match each requirement to existing tests by filename, imports, test descriptions. Record: requirement → test_file → status.
 
+### 2e. Assertion scan
+
+Scan the mapped test files for cases that assert nothing (at most 200 files per call; split larger sets):
+
+```bash
+SCAN=$(pp_run check test-substance --scan {test files mapped in 2d} --raw)
+```
+
+For each mapped file read `state` and its `asserts_nothing` list. Rules: `~/.claude/pp-core/references/test-substance.md` § Assertion-free tests at validation.
+
 ## 3. Gap Analysis
 
 Classify each requirement:
@@ -113,12 +123,14 @@ Classify each requirement:
 | Status | Criteria |
 |--------|----------|
 | COVERED | Test exists, targets behavior, runs green |
-| PARTIAL | Test exists, failing or incomplete |
+| PARTIAL | Test exists, but failing, incomplete, or asserts nothing |
 | MISSING | No test found |
 
+Gap types: `no_test_file`, `test_fails`, `no_automated_command`, `asserts_nothing`. A mapped case in a file's `asserts_nothing` list, or a mapped file with state `no_cases`, gives its requirement gap type `asserts_nothing`: no coverage. A file with state `unknown`, or a case in `skipped`, goes to the auditor to read as an `asserts_nothing` candidate. A file with `truncated: true` lists only some of its cases: every requirement mapped to it is PARTIAL (`asserts_nothing`) and the auditor reads the whole file.
+
 Build: `{ task_id, requirement, gap_type, suggested_test_path, suggested_command }`
 
-No gaps → skip to Step 6, set `nyquist_compliant: true`.
+No gaps (and no `asserts_nothing` gap) → skip to Step 6, set `nyquist_compliant: true`.
 
 ## 4. Present Gap Plan
 
@@ -149,9 +161,9 @@ Print: `◆ Spawning nyquist auditor... (runs in a subagent — no output until
 Agent(
   prompt="Read ~/.claude/agents/pp-nyquist-auditor.md for instructions.\n\n" +
     "<files_to_read>{PLAN, SUMMARY, impl files, VALIDATION.md}</files_to_read>" +
-    "<gaps>{gap list}</gaps>" +
+    "<gaps>{gap list; for each asserts_nothing gap the file, case name and line from the scan}</gaps>" +
     "<test_infrastructure>{framework, config, commands}</test_infrastructure>" +
-    "<constraints>Never modify impl files. Max 3 debug iterations. Escalate impl bugs.</constraints>" +
+    "<constraints>Never modify impl files. Max 3 debug iterations. Escalate impl bugs. Never delete or weaken a test; fill asserts_nothing by adding an assertion.</constraints>" +
     "${AGENT_SKILLS_AUDITOR}",
   subagent_type="pp-nyquist-auditor",
   model="{AUDITOR_MODEL}",
@@ -184,8 +196,11 @@ Handle return:
 | Gaps found | {N} |
 | Resolved | {M} |
 | Escalated | {K} |
+| Asserts nothing | {A} |
 ```
 
+Write `nyquist_compliant: true` only when no `asserts_nothing` gap remains open (moved to manual-only with a reason counts as closed).
+
 ## 7. Commit
 
 ```bash

package/pp-core/workflows/verify-phase.md

@@ -533,7 +533,7 @@ If gaps_found:
 
 1. **Cluster related gaps:** API stub + component unwired → "Wire frontend to backend". Multiple missing → "Complete core implementation". Wiring only → "Connect existing components".
 
-2. **Generate plan per cluster:** Objective, 2-3 tasks (files/action/verify each), re-verify step. Keep focused: single concern per plan.
+2. **Generate plan per cluster:** Objective, tasks sized by estimated context cost (up to 6 per plan; files/action/verify each), re-verify step. Keep focused: single concern per plan.
 
 3. **Order by dependency:** Fix missing → fix stubs → fix wiring → **fix test evidence** → verify.
 </step>

package/pp-core/workflows/verify-work.md

@@ -464,7 +464,7 @@ Present summary:
 
 ```bash
 [ -z "${ZSH_VERSION:-}" ] || emulate -R sh
-VERIFY_POST_HOOKS_JSON=$(pp_run loop render-hooks verify:post --raw)
+VERIFY_POST_HOOKS_JSON=$(pp_run loop render-hooks verify:post --raw --phase "${phase_number}")
 printf '%s' "$VERIFY_POST_HOOKS_JSON" | node -e "let h=[];try{h=JSON.parse(require('fs').readFileSync(0,'utf-8')).activeHooks||[]}catch{}console.log('VERIFY_POST_HOOKS_JSON='+JSON.stringify({activeHooks:h}))"
 SECURITY_FILE=$(ls "${PHASE_DIR}"/*-SECURITY.md 2>/dev/null | head -1)
 ```

package/scripts/gen-capability-registry.cjs

@@ -34,6 +34,12 @@ const SCHEMA_VERSION = '1';
 // registry generator and the loop-host-contract generator share one source of truth.
 const { LOOP_HOST_CONTRACT } = require('../pp-core/bin/lib/loop-host-contract.cjs');
 
+// Ceremony gate vocabulary (Phase 37, D-14) — a hook `when` conjunct `ceremony.<gate>`
+// must name a gate declared here.
+const CEREMONY_GATE_NAMES = new Set(
+  require('../pp-core/bin/shared/ceremony-gates.json').gates.map((g) => g.key),
+);
+
 // Wired-points helper — tells us which points actually have render-hooks call sites.
 const { getWiredLoopPoints } = require('./gen-loop-host-contract.cjs');
 
@@ -1241,6 +1247,38 @@ function validateGate(gate, prefix) {
 
 // ─── Contract validation ──────────────────────────────────────────────────────
 
+/**
+ * Validate a hook `when` (Phase 37, D-14). A `when` is one or more conjuncts joined
+ * by `&&`; each is a config key the capability declares, or `ceremony.<gate>` with
+ * the gate named in pp-core/bin/shared/ceremony-gates.json. A non-string `when` is
+ * already reported by the schema checks and is skipped here. Pushes onto `errors`.
+ * `where` is the message prefix, e.g. `capability "x" step.when`, so the message of
+ * a single undeclared key stays `<where> "<key>" is not defined in capability config keys`.
+ */
+function validateWhen(when, cap, where, errors) {
+  if (typeof when !== 'string') return;
+  for (const raw of when.split('&&')) {
+    const conjunct = raw.trim();
+    if (conjunct === '') {
+      errors.push(where + ' has an empty conjunct');
+      continue;
+    }
+    if (conjunct.startsWith('ceremony.')) {
+      if (!CEREMONY_GATE_NAMES.has(conjunct.slice('ceremony.'.length))) {
+        errors.push(where + ' "' + conjunct + '" is not a ceremony gate');
+      }
+      continue;
+    }
+    if (
+      typeof cap.config === 'object' &&
+      cap.config !== null &&
+      !Object.prototype.hasOwnProperty.call(cap.config, conjunct)
+    ) {
+      errors.push(where + ' "' + conjunct + '" is not defined in capability config keys');
+    }
+  }
+}
+
 /**
  * Validate per-capability contract constraints against the Loop Host Contract.
  * This covers:
@@ -1281,51 +1319,10 @@ function validateAgainstContract(cap, capId, knownAgentIds) {
     }
   }
 
-  // when references a plausibly-valid config key (string — we require it's in cap.config)
-  for (const step of cap.steps) {
-    if (step.when !== undefined) {
-      if (typeof step.when !== 'string') continue; // already reported above
-      if (
-        typeof cap.config === 'object' &&
-        cap.config !== null &&
-        !Object.prototype.hasOwnProperty.call(cap.config, step.when)
-      ) {
-        errors.push(
-          prefix + ' step.when "' + step.when + '" is not defined in capability config keys',
-        );
-      }
-    }
-  }
-
-  for (const contrib of cap.contributions) {
-    if (contrib.when !== undefined) {
-      if (typeof contrib.when !== 'string') continue;
-      if (
-        typeof cap.config === 'object' &&
-        cap.config !== null &&
-        !Object.prototype.hasOwnProperty.call(cap.config, contrib.when)
-      ) {
-        errors.push(
-          prefix + ' contribution.when "' + contrib.when + '" is not defined in capability config keys',
-        );
-      }
-    }
-  }
-
-  for (const gate of cap.gates) {
-    if (gate.when !== undefined) {
-      if (typeof gate.when !== 'string') continue;
-      if (
-        typeof cap.config === 'object' &&
-        cap.config !== null &&
-        !Object.prototype.hasOwnProperty.call(cap.config, gate.when)
-      ) {
-        errors.push(
-          prefix + ' gate.when "' + gate.when + '" is not defined in capability config keys',
-        );
-      }
-    }
-  }
+  // when: one or more `&&` conjuncts, each a declared config key or `ceremony.<gate>`
+  for (const step of cap.steps) validateWhen(step.when, cap, prefix + ' step.when', errors);
+  for (const contrib of cap.contributions) validateWhen(contrib.when, cap, prefix + ' contribution.when', errors);
+  for (const gate of cap.gates) validateWhen(gate.when, cap, prefix + ' gate.when', errors);
 
   return errors;
 }
@@ -2759,6 +2756,7 @@ function main() {
 module.exports = {
   validateCapability,
   validateAgainstContract,
+  validateWhen,
   validateConsumesGlobal,
   validateCrossCapability,
   validateSealField,