@lovehlmmm/primekit 1.0.0

package/skills/plan/references/red-team-personas.md

@@ -0,0 +1,101 @@
+# Red Team Personas
+
+## Available Lenses
+
+| Reviewer | Lens | Focus |
+|----------|------|-------|
+| **Security Adversary** | Attacker mindset | Auth bypass, injection, data exposure, privilege escalation, supply chain, OWASP top 10 |
+| **Failure Mode Analyst** | Murphy's Law | Race conditions, data loss, cascading failures, recovery gaps, deployment risks, rollback holes |
+| **Assumption Destroyer** | Skeptic | Unstated dependencies, false "will work" claims, missing error paths, scale assumptions, integration assumptions. Target assumptions that are both load-bearing (the plan fails without them) and breakable within the plan's life; for each, state the condition under which the plan stops meeting its success criteria |
+| **Scope & Complexity Critic** | Unrequested-scope detector | Over-engineering, premature abstraction, unnecessary complexity, scope creep, gold plating |
+
+**Scope & Complexity Critic constraint:** requested scope is a constraint, not a
+finding. Flag only additions beyond the user's request; raise doubts about
+requested features as questions, never as cut recommendations — unless `--yagni`
+is active, in which case missing MVP cuts and scope-reduction findings are also
+in scope.
+
+## Verification Role Assignment
+
+Each reviewer carries their adversarial lens PLUS a verification role. Findings must include grep/glob evidence from the actual codebase, not just logical argument.
+Load: `references/verification-roles.md` for full role definitions.
+
+**Tier precedence rule:** The verification tier (Light/Standard/Full) determines which verification roles are active — NOT the reviewer's persona assignment. At Light tier, all reviewers use Fact Checker regardless of persona. At Standard tier, Fact Checker + Contract Verifier. At Full tier, the persona-specific role below applies.
+
+| Reviewer | Adversarial Lens | Verification Role (Full Tier) |
+|----------|-----------------|-------------------------------|
+| Security Adversary | Attacker mindset | Fact Checker |
+| Failure Mode Analyst | Murphy's Law | Flow Tracer |
+| Assumption Destroyer | Skeptic | Scope Auditor |
+| Scope & Complexity Critic | Unrequested-scope detector | Contract Verifier |
+
+### Evidence Requirement
+
+- Every finding MUST include verification evidence from the codebase
+- Run grep/glob to back up claims — cite file:line for every referenced symbol
+- If claiming "X doesn't handle Y", show the actual code path proving it
+- **Findings without codebase evidence = automatically rejected during adjudication**
+
+## Reviewer Prompt Template
+
+Each reviewer prompt MUST include:
+
+1. This override: `"IGNORE your default code quality checks (linting, type safety, build validation). You are reviewing a PLAN DOCUMENT, not code — do not lint, build, or test. DO run grep/glob to verify the plan's factual claims against the actual codebase. Focus on plan quality backed by codebase evidence."`
+2. Their specific adversarial lens and persona
+3. The plan file paths so they can read original files directly
+4. These instructions:
+
+```
+You are a hostile reviewer. Your job is to DESTROY this plan.
+Adopt the {LENS_NAME} perspective. Find every flaw you can.
+
+Rules:
+- Be specific: cite exact phase/section where the flaw lives
+- Be concrete: describe the failure scenario, not just "could be a problem"
+- Rate severity: Critical (blocks success) | High (significant risk) | Medium (notable concern)
+- Skip trivial observations (style, naming, formatting)
+- No praise. No "overall looks good". Only findings.
+- 5-10 findings per reviewer. Quality over quantity.
+- Back up every finding with grep/glob evidence from the codebase
+- Your assigned verification role: {VERIFICATION_ROLE} — use it to fact-check plan claims
+- Your verification role methods (apply these exactly):
+{VERIFICATION_ROLE_METHODS}
+- Findings without codebase evidence (file:line citations) will be rejected at adjudication
+
+Output format per finding:
+## Finding {N}: {title}
+- **Severity:** Critical | High | Medium
+- **Location:** Phase {X}, section "{name}"
+- **Flaw:** {what's wrong}
+- **Failure scenario:** {concrete description of how this fails}
+- **Evidence:** {quote from plan or missing element}
+- **Suggested fix:** {brief recommendation}
+```
+
+## Adjudication Format
+
+```markdown
+## Red Team Findings
+
+### Finding 1: {title} — {SEVERITY}
+**Reviewer:** {lens name}
+**Location:** {phase/section}
+**Flaw:** {description}
+**Failure scenario:** {concrete scenario}
+**Disposition:** Accept | Reject
+**Rationale:** {why accept/reject — be specific}
+```
+
+## Plan.md Section Format
+
+```markdown
+## Red Team Review
+
+### Session — {YYYY-MM-DD}
+**Findings:** {total} ({accepted} accepted, {rejected} rejected)
+**Severity breakdown:** {N} Critical, {N} High, {N} Medium
+
+| # | Finding | Severity | Disposition | Applied To |
+|---|---------|----------|-------------|------------|
+| 1 | {title} | Critical | Accept | Phase 2 |
+```

package/skills/plan/references/red-team-workflow.md

@@ -0,0 +1,97 @@
+# Red Team Review
+
+Adversarially review an implementation plan by spawning parallel reviewer subagents that try to tear it apart. Each reviewer adopts a different hostile lens. You then adjudicate findings, and the user decides which to apply.
+
+**Mindset:** Like hiring someone who hates the implementer to destroy their work.
+
+## Plan Resolution
+
+1. If `$ARGUMENTS` provided → Use that path
+2. Else check `## Plan Context` section → Use active plan path
+3. If no plan found → Ask user to specify path or run `/pk:plan` first
+
+## Workflow
+
+### Step 1: Read Plan Files
+Read the plan directory:
+- `plan.md` — Overview, phases, dependencies
+- `phase-*.md` — All phase files (full content)
+
+### Step 2: Scale Reviewer Count
+
+| Phase Count | Reviewers | Lenses Selected |
+|-------------|-----------|-----------------|
+| 1-2 phases | 2 | Security Adversary + Assumption Destroyer |
+| 3-5 phases | 3 | + Failure Mode Analyst |
+| 6+ phases | 4 | + Scope & Complexity Critic (all lenses) |
+
+### Step 3: Define Adversarial Lenses
+Load: `references/red-team-personas.md`
+
+### Step 4: Spawn Reviewers
+Launch reviewers simultaneously via delegate_agent capability with `subagent_type: "code-reviewer"`.
+Each reviewer prompt MUST include override, persona, plan file paths, and hostile instructions.
+Load: `references/red-team-personas.md` for reviewer prompt template.
+
+### Step 5: Collect, Deduplicate & Cap
+1. Collect all findings
+2. Deduplicate overlapping findings
+3. Sort by severity: Critical → High → Medium
+4. Cap at 15 findings
+
+### Step 5.5: Evidence Filter
+For each finding, check: does the `Evidence:` field contain at least one `file:line` citation (pattern `path/to/file.ext:NNN`)? If not, auto-set disposition to **Reject** with rationale "No codebase evidence." Do not evaluate merit for evidence-free findings.
+
+### Step 6: Adjudicate
+For each finding that passed the evidence filter, evaluate and propose: **Accept** or **Reject**.
+
+### Step 7: User Review
+Present via `ask_user capability`:
+- "Looks good, apply accepted findings"
+- "Let me review each one"
+- "Reject all, plan is fine"
+
+**If "Let me review each one":**
+For each finding marked Accept, ask via `ask_user capability`:
+- Options: "Yes, apply" | "No, reject" | "Modify suggestion"
+
+**If "Modify suggestion":**
+Ask via `ask_user capability`: "Describe your modification to this finding's suggested fix:"
+(user provides free text via "Other" option)
+Record the modified suggestion. Set disposition to "Accept (modified)" in the Red Team Review table.
+
+### Step 8: Apply to Plan
+For accepted findings, edit target phase files inline with marker.
+Add `## Red Team Review` section to `plan.md`.
+
+### Step 9: Whole-Plan Consistency Sweep
+Load: `references/verification-roles.md` → "Whole-Plan Consistency Sweep".
+
+After accepted findings are applied, re-read `plan.md` and every `phase-*.md` file. Red-team edits often change one local phase; this sweep prevents stale claims from surviving elsewhere.
+
+Required checks:
+- Convert accepted findings into a decision delta list.
+- Search all plan files for old terms, rejected assumptions, renamed files/APIs/fields, and superseded implementation details.
+- Reconcile `plan.md` summaries, dependencies, phase requirements, implementation steps, success criteria, and existing validation/red-team logs.
+- If a finding updates an embedded draft, pseudo-query, command, or API contract, update duplicate prose/draft copies too.
+- Append `### Whole-Plan Consistency Sweep` to `## Red Team Review`.
+- If contradictions remain, list them as unresolved and do not present the plan as ready for implementation.
+
+## Output
+- Total findings by severity
+- Accepted vs rejected count
+- Files modified
+- Whole-plan consistency sweep results
+- Key risks addressed
+
+## Next Steps
+Remind user they can run `/pk:plan validate {plan-directory-path}` before implementation.
+When the user approves implementation, run `/pk:cook {ABSOLUTE_PATH_TO_PLAN_DIR}/plan.md`.
+Add `--auto` only when the user explicitly asks for autonomous implementation.
+
+## Important Notes
+- Reviewers must be HOSTILE, not helpful
+- Deduplicate aggressively
+- Adjudication must be evidence-based
+- Reviewers read plan files directly
+- Never recommend cooking until the whole-plan consistency sweep has no unresolved contradictions

package/skills/plan/references/research-phase.md

@@ -0,0 +1,49 @@
+# Research & Analysis Phase
+
+**When to skip:** If provided with researcher reports, skip this phase.
+
+## Core Activities
+
+### Parallel Researcher Agents
+- Spawn multiple `researcher` agents in parallel to investigate different approaches
+- Wait for all researcher agents to report back before proceeding
+- Each researcher investigates a specific aspect or approach
+
+### Sequential Thinking
+- Use `pk:sequential-thinking` skill for dynamic and reflective problem-solving
+- Structured thinking process for complex analysis
+- Enables multi-step reasoning with revision capability
+
+### Documentation Research
+- Use `pk:docs-seeker` skill to read and understand documentation
+- Research plugins, packages, and frameworks
+- Find latest technical documentation using llms.txt standard
+
+### GitHub Analysis
+- Use `gh` command to read and analyze:
+  - GitHub Actions logs
+  - Pull requests
+  - Issues and discussions
+- Extract relevant technical context from GitHub resources
+
+### Remote Repository Analysis
+When given GitHub repository URL, generate fresh codebase summary:
+```bash
+# usage: 
+repomix --remote <github-repo-url>
+# example: 
+repomix --remote https://github.com/mrgoonie/human-mcp
+```
+
+### Debugger Delegation
+- Delegate to `debugger` agent for root cause analysis
+- Use when investigating complex issues or bugs
+- Debugger agent specializes in diagnostic tasks
+
+## Best Practices
+
+- Research breadth before depth
+- Document findings for synthesis phase
+- Identify multiple approaches for comparison
+- Consider edge cases during research
+- Note security implications early

package/skills/plan/references/scope-challenge.md

@@ -0,0 +1,104 @@
+# Step 0: Scope Challenge
+
+Run BEFORE research or design. Forces intent clarification before investing time.
+
+**Inspired by:** gstack `/plan-eng-review` Step 0 + `/plan-ceo-review` scope modes.
+
+## Skip Conditions
+
+Skip Step 0 when:
+- Task is clearly trivial (single file fix, typo, config change)
+- User says "just plan it", "quick", or similar urgency signal
+- Task description is under 20 words and unambiguous
+
+When Step 0 is skipped, preserve the full requested scope. Only `--yagni` or a
+direct user instruction to cut a named item authorizes scope reduction.
+`--fast` changes planning depth only and is not a skip condition here.
+
+## The 3 Questions
+
+Before planning, answer these concisely:
+
+### 1. What already exists?
+- Scan codebase for code that partially/fully solves sub-problems
+- Check existing utilities, services, patterns that can be reused
+- Flag if plan would rebuild something that exists
+
+### 2. What did the user actually ask for?
+- Restate the requested scope; it is the baseline the plan must deliver in full
+- Flag additions **beyond** the request that crept in during analysis
+- Note work that could be deferred, as information for the user's choice below —
+  do not defer anything on your own
+
+### 3. Complexity check
+- If plan would touch **>8 files**: challenge whether same goal achievable with fewer
+- If plan would introduce **>2 new classes/services**: smell — justify each
+- If plan would have **>3 phases**: consider if phases can be merged
+
+## Scope Modes
+
+After answering the 3 questions, present this fork via `ask_user capability`
+only when the user passed `--yagni`:
+
+**Header:** "Scope Challenge"
+**Question:** "Based on analysis, how should we scope this plan?"
+
+| Option | Label | Description |
+|--------|-------|-------------|
+| A | **SCOPE EXPANSION** | Dream big — explore the 10-star version, research deeply, add delight features |
+| B | **HOLD SCOPE** | Scope is right — focus on bulletproof execution, edge cases, test coverage |
+| C | **SCOPE REDUCTION** | Strip to essentials — defer everything non-blocking, minimal phases |
+
+**`--yagni` passed:** the user has opted into scope-cutting, so REDUCTION is
+pre-authorized — present the fork with C as the recommended option instead of
+asking neutrally. Still surface EXPANSION if the analysis found scope that is
+missing and blocking; the flag authorizes cutting, not skipping the analysis.
+
+**Without `--yagni`:** do not present the scope-mode fork or recommend
+reductions. Record `HOLD SCOPE`, reject only unrequested additions, and deliver
+the full requested scope.
+
+## After Selection
+
+### EXPANSION selected
+- Suggest `--hard` or `--two` mode if not already set
+- Research phase should explore alternatives and adjacent features
+- Plan should include "stretch" items clearly labeled
+- More phases are acceptable
+
+### HOLD selected
+- Proceed with auto-detected mode
+- Respect scope exactly — no silent reduction or expansion
+- Focus on failure modes, edge cases, test coverage
+- Standard number of phases
+
+### REDUCTION selected
+- Suggest `--fast` mode if not already set
+- Propose minimal version that achieves core goal
+- Defer everything non-critical to "NOT in scope" section
+- Fewer phases, simpler architecture
+
+## Critical Rule
+
+**Once user selects a mode, RESPECT IT.**
+
+Do not:
+- Silently reduce scope when user chose HOLD or EXPANSION
+- Silently expand scope when user chose REDUCTION
+- Re-argue for different scope in later review sections
+
+Raise scope concerns ONCE in Step 0. After that, commit to chosen scope and optimize within it.
+
+## Output Format
+
+After scope challenge, output brief summary before proceeding:
+
+```
+Scope Challenge:
+- Existing code: [what was found that's reusable]
+- Requested scope: [what the user asked for — delivered in full unless they choose REDUCTION]
+- Complexity: [estimated files, new abstractions]
+- Selected mode: [EXPANSION/HOLD/REDUCTION]
+```
+
+Then proceed to mode detection and research phase.

package/skills/plan/references/solution-design.md

@@ -0,0 +1,83 @@
+# Solution Design
+
+## Core Principles
+
+Follow these fundamental principles:
+- **Full requested scope** - Design for everything the user asked for; never trim
+  or defer it. Add nothing unrequested.
+- **KISS** (Keep It Simple, Stupid) - Prefer simple solutions over complex ones
+- **DRY** (Don't Repeat Yourself) - Avoid code duplication
+
+With `--yagni`, additionally apply **YAGNI** (You Aren't Gonna Need It):
+challenge and cut any scope not needed for the stated outcome.
+
+## Design Activities
+
+### Technical Trade-off Analysis
+- Evaluate multiple approaches for each requirement
+- Compare pros and cons of different solutions
+- Compare approaches on their worst plausible case, not only the expected one
+- Consider short-term vs long-term implications
+- Balance complexity with maintainability
+- Assess development effort vs benefit
+- Recommend optimal solution based on current best practices
+
+### Load-Bearing Assumptions
+- List the assumptions the design fails without — not every assumption, only the
+  ones that carry weight
+- Mark which of those could realistically break within the life of this work;
+  resolve the ones a read of source, tests, or live state can settle, and carry
+  only the rest forward
+- State the condition under which the chosen design stops meeting its success
+  criteria
+- When a load-bearing assumption stays unresolved, prefer the design that is
+  cheapest to switch away from; note switching cost and any lock-in the design
+  creates
+- For each unresolved assumption, record in the phase's Risk Assessment the
+  observable signal that it broke and the pre-decided response — adjust within
+  the plan, or stop and replan
+
+### Security Assessment
+- Identify potential vulnerabilities during design phase
+- Consider authentication and authorization requirements
+- Assess data protection needs
+- Evaluate input validation requirements
+- Plan for secure configuration management
+- Address OWASP Top 10 concerns
+- Consider API security (rate limiting, CORS, etc.)
+
+### Performance & Scalability
+- Identify potential bottlenecks early
+- Consider database query optimization needs
+- Plan for caching strategies
+- Assess resource usage (memory, CPU, network)
+- Design for horizontal/vertical scaling
+- Plan for load distribution
+- Consider asynchronous processing where appropriate
+
+### Edge Cases & Failure Modes
+- Think through error scenarios
+- Plan for network failures
+- Consider partial failure handling
+- Design retry and fallback mechanisms
+- Plan for data consistency
+- Consider race conditions
+- Design for graceful degradation
+
+### Architecture Design
+- Create scalable system architectures
+- Design for maintainability
+- Plan component interactions
+- Design data flow
+- Consider microservices vs monolith trade-offs
+- Plan API contracts
+- Design state management
+
+## Best Practices
+
+- Document design decisions and rationale
+- Consider both technical and business requirements
+- Think through the entire user journey
+- Plan for monitoring and observability
+- Design with testing in mind
+- Consider deployment and rollback strategies

package/skills/plan/references/task-management.md

@@ -0,0 +1,52 @@
+# Task Management Integration
+
+Plan files are the durable source of truth. A runtime task view is an optional,
+session-scoped projection that can improve visibility and coordination without
+becoming a dependency.
+
+## Runtime Capability Contract
+
+1. Discover the live task-management surface at runtime.
+2. If available, mirror actionable plan items, dependencies, ownership, and status.
+3. If unavailable, update the active plan directly.
+4. Never infer support from a client name, environment, or cached tool list.
+5. Sync completed work back to plan files before claiming completion.
+
+## When to Hydrate
+
+Hydrate by default after writing a plan with at least three meaningful phases.
+Skip when `--no-tasks` is requested or when the plan is too small to benefit.
+
+For an HTML-authoritative plan, hydrate only from a companion Markdown index
+that contains actionable checkboxes. Otherwise, leave runtime tracking empty.
+
+## Hydration
+
+1. Read `plan.md` and every `phase-XX-*.md` file.
+2. Treat checked items as complete and unchecked items as remaining work.
+3. Discover the live task-management surface.
+4. If available, mirror remaining work and preserve phase dependencies.
+5. Retain enough context to map each runtime item back to its phase file and checklist item.
+6. If no live surface exists, keep status current in the plan files.
+
+## Cook Handoff
+
+In the same session, Cook may reuse the live view after confirming it matches
+the plan. In a new session, or when the view is absent or stale, Cook rebuilds
+it from unchecked plan items. The plan always wins when states disagree.
+
+## Sync-Back
+
+1. Sweep every phase file, not only the active phase.
+2. Reconcile completed runtime work with source checklist items.
+3. Backfill stale completed checkboxes in earlier phases.
+4. Derive plan status and progress from actual checkbox state.
+5. Report any item that cannot be mapped before claiming full completion.
+
+## Quality Checks
+
+- No dependency cycles.
+- Every runtime item maps to durable plan work.
+- Runtime ownership does not overlap.
+- Checked items have completion evidence.
+- Runtime counts are advisory; plan checkbox state determines durable progress.

package/skills/plan/references/validate-question-framework.md

@@ -0,0 +1,80 @@
+# Validation Question Framework
+
+## Question Categories
+
+| Category | Keywords to detect |
+|----------|-------------------|
+| **Architecture** | "approach", "pattern", "design", "structure", "database", "API" |
+| **Assumptions** | "assume", "expect", "should", "will", "must", "default" |
+| **Tradeoffs** | "tradeoff", "vs", "alternative", "option", "choice", "either/or" |
+| **Risks** | "risk", "might", "could fail", "dependency", "blocker", "concern" |
+| **Scope** | "phase", "MVP", "future", "out of scope", "nice to have" |
+
+## Question Format Rules
+
+- Each question must have 2-4 concrete options
+- Mark recommended option with "(Recommended)" suffix
+- "Other" option is automatic
+- Questions should surface implicit decisions
+
+## Example Questions
+
+Category: Architecture
+Question: "How should the validation results be persisted?"
+Options:
+1. Save to plan.md frontmatter (Recommended)
+2. Create validation-answers.md
+3. Don't persist
+
+Category: Assumptions
+Question: "The plan assumes API rate limiting is not needed. Is this correct?"
+Options:
+1. Yes, not needed for MVP
+2. No, add basic rate limiting now (Recommended)
+3. Defer to Phase 2
+
+## Validation Log Format
+
+```markdown
+## Validation Log
+
+### Session {N} — {YYYY-MM-DD}
+**Trigger:** {what prompted this validation}
+**Questions asked:** {count}
+
+#### Questions & Answers
+
+1. **[{Category}]** {full question text}
+   - Options: {A} | {B} | {C}
+   - **Answer:** {user's choice}
+   - **Custom input:** {verbatim "Other" text if applicable}
+   - **Rationale:** {why this decision matters}
+
+#### Confirmed Decisions
+- {decision}: {choice} — {brief why}
+
+#### Action Items
+- [ ] {specific change needed}
+
+#### Impact on Phases
+- Phase {N}: {what needs updating and why}
+```
+
+## Recording Rules
+
+- **Full question text**: exact question, not summary
+- **All options**: every option presented
+- **Verbatim custom input**: record "Other" text exactly
+- **Rationale**: explain why decision affects implementation
+- **Session numbering**: increment from last session
+- **Trigger**: state what prompted validation
+
+## Section Mapping for Phase Propagation
+
+| Change Type | Target Section |
+|-------------|----------------|
+| Requirements | Requirements |
+| Architecture | Architecture |
+| Scope | Overview / Implementation Steps |
+| Risk | Risk Assessment |
+| Unknown | Key Insights (new subsection) |

package/skills/plan/references/validate-workflow.md

@@ -0,0 +1,107 @@
+# Validate Workflow
+
+Interview the user with critical questions to validate assumptions, confirm decisions, and surface potential issues in an implementation plan before coding begins.
+
+## Plan Resolution
+
+1. If `$ARGUMENTS` provided → Use that path
+2. Else check `## Plan Context` section → Use active plan path
+3. If no plan found → Ask user to specify path or run `/pk:plan --hard` first
+
+## Configuration
+
+Check `## Plan Context` section for validation settings:
+- `mode` - Controls auto/prompt/off behavior
+- `questions` - Range like `3-8` (min-max)
+
+## Workflow
+
+### Step 1: Read Plan Files
+- `plan.md` - Overview and phases list
+- `phase-*.md` - All phase files
+- Look for decision points, assumptions, risks, tradeoffs
+
+### Step 2: Extract Question Topics
+Load: `references/validate-question-framework.md`
+
+### Step 2.5: Verification Pass (Auto-Scaled)
+
+Before interviewing the user, verify plan accuracy against the actual codebase.
+Load: `references/verification-roles.md`
+
+**Guard:** If `## Red Team Review` section already exists in `plan.md` with verification evidence, skip to Step 3 — limit this step to resolving any remaining `[UNVERIFIED]` tags only.
+
+1. **Tier detection** — Count phases in the plan:
+   - 1-2 phases → Light (Fact Checker only, 5 claims/phase)
+   - 3-4 phases → Standard (Fact Checker + Contract Verifier, 10 claims/phase)
+   - 5+ phases → Full (all 4 roles, 15+ claims/phase)
+2. **For each active role at the current tier:**
+   - Sample N claims per phase (per tier budget)
+   - Run grep/glob to verify file paths, symbols, endpoints
+   - Collect findings: VERIFIED | FAILED | UNVERIFIED
+3. **Handle failures:**
+   - Surface ALL failures as additional interview questions in Step 4 (with glob-suggested alternatives as "(Recommended)" options)
+   - Never auto-correct plan files — all corrections require user confirmation via interview
+4. **Check `[UNVERIFIED]` tags** — Scan plan for planner-tagged unverified claims, attempt to resolve
+5. **Append results** to `## Validation Log`:
+   ```
+   ### Verification Results
+   - Claims checked: N
+   - Verified: N | Failed: N | Unverified: N
+   - Tier: Light|Standard|Full
+   - Failures: [list with file:line evidence]
+   ```
+
+### Step 3: Generate Questions
+For each detected topic, formulate a concrete question with 2-4 options.
+Mark recommended option with "(Recommended)" suffix.
+
+### Step 4: Interview User
+Use `ask_user capability` tool.
+- Use question count from `## Plan Context` validation settings
+- Group related questions (max 4 per tool call)
+- Focus on: assumptions, risks, tradeoffs, architecture
+
+### Step 5: Document Answers
+Add or append `## Validation Log` section in `plan.md`.
+Load: `references/validate-question-framework.md` for recording format.
+
+### Step 6: Propagate Changes to Phases
+Auto-propagate validation decisions to affected phase files.
+Add marker: `<!-- Updated: Validation Session N - {change} -->`
+
+### Step 7: Whole-Plan Consistency Sweep
+Load: `references/verification-roles.md` → "Whole-Plan Consistency Sweep".
+
+After propagation, re-read `plan.md` and every `phase-*.md` file. Check the whole plan for stale or contradictory claims caused by the validation decisions.
+
+Required checks:
+- Search all plan files for old terms, renamed fields/APIs/files, rejected assumptions, and superseded validation decisions.
+- Reconcile `plan.md` overview, phase summaries, implementation steps, success criteria, risk notes, and validation logs.
+- If the same SQL/query/API/body/contract appears as both prose and embedded draft, update both copies or mark the unresolved conflict.
+- Append `### Whole-Plan Consistency Sweep` to the current `## Validation Log`.
+- If any unresolved contradiction remains, ask the user before recommending implementation.
+
+## Output
+- Number of questions asked
+- Key decisions confirmed
+- Phase propagation results
+- Whole-plan consistency sweep results
+- Recommendation: proceed or revise
+
+## Next Steps
+Present user-choice next steps with the absolute path:
+> **Best Practice:** Run `/clear` before implementing to start with fresh context.
+> If the user chooses implementation, run:
+> ```
+> /pk:cook {ABSOLUTE_PATH_TO_PLAN_DIR}/plan.md
+> ```
+> **Flag selection:** If Verification Results show `Failed: 0`, the plan is eligible for implementation. Ask the user before proceeding. Add `--auto` only when the user explicitly asks for autonomous implementation. If `Failed: N > 0`, revise the plan before cooking.
+> **Why absolute path?** After `/clear`, the new session loses previous context.
+> Fresh context helps Claude focus solely on implementation without planning context pollution.
+
+## Important Notes
+- Only ask about genuine decision points
+- If plan is simple, fewer than min questions is okay
+- Prioritize questions that could change implementation significantly
+- Never recommend cooking until the whole-plan consistency sweep has no unresolved contradictions