cokit-cli 1.2.7 → 1.3.0

package/templates/repo/.github/skills/planning/references/output-standards.md

@@ -2,10 +2,6 @@
 
 ## Plan File Format
 
-**Important:**
-- DO NOT create plans or reports in USER directory.
-- ALWAYS create plans or reports in CURRENT WORKING PROJECT DIRECTORY.
-
 ### YAML Frontmatter (Required for plan.md)
 
 All `plan.md` files MUST include YAML frontmatter at the top:
@@ -20,6 +16,8 @@ effort: 4h       # Estimated total effort
 issue: 74        # GitHub issue number (if applicable)
 branch: kai/feat/feature-name
 tags: [frontend, api]  # Category tags
+blockedBy: []    # Plan dirs this plan waits on (e.g., [260301-1200-auth-system])
+blocks: []       # Plan dirs this plan blocks (e.g., [260228-0900-user-dashboard])
 created: 2025-12-16
 ---
 ```
@@ -35,6 +33,8 @@ When creating plans, auto-populate these fields:
 - **issue**: Parse from branch name or context
 - **branch**: Current git branch (`git branch --show-current`)
 - **tags**: Infer from task keywords (e.g., frontend, backend, api, auth)
+- **blockedBy**: Detected during pre-creation scan (empty `[]` if none)
+- **blocks**: Detected during pre-creation scan (empty `[]` if none)
 - **created**: Today's date in YYYY-MM-DD format
 
 ### Tag Vocabulary (Recommended)
@@ -44,6 +44,18 @@ Use these predefined tags for consistency:
 - **Domain**: `frontend`, `backend`, `database`, `api`, `auth`
 - **Scope**: `critical`, `tech-debt`, `experimental`
 
+### Task Naming Conventions
+
+**subject** (imperative): Action verb + deliverable, <60 chars
+  Examples: "Setup database migrations", "Implement OAuth2 flow"
+
+**activeForm** (continuous): Present participle of subject
+  Examples: "Setting up database", "Implementing OAuth2"
+
+**description**: 1-2 sentences, concrete deliverables, reference phase file
+
+See `task-management.md` for full TaskCreate patterns and metadata.
+
 ## Task Breakdown
 
 - Transform complex requirements into manageable, actionable tasks
@@ -55,10 +67,6 @@ Use these predefined tags for consistency:
 
 ### File Management
 
-**Important:**
-- DO NOT create plans or reports in USER directory.
-- ALWAYS create plans or reports in CURRENT WORKING PROJECT DIRECTORY.
-
 List affected files with:
 - Full paths (not relative)
 - Action type (modify/create/delete)
@@ -77,10 +85,6 @@ List affected files with:
 
 ## Output Requirements
 
-**Important:**
-- DO NOT create plans or reports in USER directory.
-- ALWAYS create plans or reports in CURRENT WORKING PROJECT DIRECTORY.
-
 ### What Planners Do
 - Create plans ONLY (no implementation)
 - Provide plan file path and summary
@@ -98,7 +102,7 @@ List affected files with:
 - Prioritize actionable info
 
 ### Unresolved Questions
-**IMPORTANT:** List unresolved questions at the end of your response and ask users directly. Wait for their answers before finalizing.
+**IMPORTANT:** Use asking the user to ask users for unresolved questions at the end
 - Questions needing clarification
 - Technical decisions requiring input
 - Unknowns impacting implementation

package/templates/repo/.github/skills/planning/references/plan-organization.md

@@ -4,10 +4,6 @@
 
 ### Plan Location
 
-**Important:**
-- DO NOT create plans or reports in USER directory.
-- ALWAYS create plans or reports in CURRENT WORKING PROJECT DIRECTORY.
-
 Use `Plan dir:` from `## Naming` section injected by hooks. This is the full computed path.
 
 **Example:** `plans/251101-1505-authentication/` or `ai_docs/feature/MRR-1453/`
@@ -34,34 +30,48 @@ IN CURRENT WORKING PROJECT DIRECTORY:
 └── phase-07-write-tests.md                    # Tests
 ```
 
+### Task Hydration
+
+After creating plan.md and phase files, hydrate tasks (unless `--no-tasks`):
+1. TaskCreate per phase with `addBlockedBy` dependency chain
+2. Add critical step tasks for high-risk items
+3. See `task-management.md` for patterns and cook handoff protocol
+
 ### Active Plan State Tracking
 
-Check the `## Plan Context` section injected by hooks:
-- **"Plan: {path}"** = Active plan - use for reports
-- **"Suggested: {path}"** = Branch-matched, hint only - do NOT auto-use
-- **"Plan: none"** = No active plan
+See SKILL.md "Active Plan State" section for full rules. Key points:
+- Check `## Plan Context` injected by hooks for active/suggested/none state
+- Active plans use plan-specific reports path; suggested plans use default path
 
-**Pre-Creation Check:**
-1. If "Plan:" shows a path → ask "Continue with existing plan? [Y/n]"
-2. If "Suggested:" shows a path → inform user (hint only, do NOT auto-use)
-3. If "Plan: none" → create new plan using naming from `## Naming` section
+## Plan Creation via CLI
 
-**After Creating Plan:**
-```bash
-# Update session state so agents get the new plan context:
-node $HOME/.copilot/scripts/set-active-plan.cjs {plan-dir}
-```
+After determining phases from research/design:
 
-**Report Output Rules:**
-1. Use `Report:` and `Plan dir:` from `## Naming` section
-2. Active plans use plan-specific reports path
-3. Suggested plans use default reports path to prevent old plan pollution
+1. **Scaffold via CLI:**
+   ```bash
+   ck plan create \
+     --title "{plan title}" \
+     --phases "{Phase1},{Phase2},{Phase3}" \
+     --dir {plan-dir} \
+     --priority {P1|P2|P3} \
+     [--issue {N}]
+   ```
 
-## File Structure
+2. **Fill content sections** in plan.md via Edit tool:
+   - `## Overview` — brief description
+   - `## Dependencies` — cross-plan dependencies
+
+3. **Fill each phase-XX.md** with:
+   - Architecture, implementation steps, success criteria
+   - Requirements, risk assessment, security considerations
 
-**Important:**
-- DO NOT create plans or reports in USER directory.
-- ALWAYS create plans or reports in CURRENT WORKING PROJECT DIRECTORY.
+4. **NEVER edit the Phases table directly** — it's CLI-owned.
+   Use `ck plan check/uncheck/add-phase` for structural changes.
+
+**Fallback:** If `ck` CLI is not available (e.g., user hasn't installed),
+write plan.md directly using the canonical 3-column format.
+
+## File Structure
 
 ### Overview Plan (plan.md)
 
@@ -78,6 +88,8 @@ effort: 8h
 issue: 123
 branch: kai/feat/oauth-auth
 tags: [auth, backend, security]
+blockedBy: []
+blocks: [260115-0900-user-dashboard]
 created: 2025-12-16
 ---
 
@@ -87,13 +99,23 @@ created: 2025-12-16
 
 Brief description of what this plan accomplishes.
 
+## Cross-Plan Dependencies
+
+| Relationship | Plan | Status |
+|-------------|------|--------|
+| Blocks | [260115-0900-user-dashboard](../260115-0900-user-dashboard/plan.md) | pending |
+
 ## Phases
 
-| # | Phase | Status | Effort | Link |
-|---|-------|--------|--------|------|
-| 1 | Setup | Pending | 2h | [phase-01](./phase-01-setup.md) |
-| 2 | Implementation | Pending | 4h | [phase-02](./phase-02-impl.md) |
-| 3 | Testing | Pending | 2h | [phase-03](./phase-03-test.md) |
+| Phase | Name | Status |
+|-------|------|--------|
+| 1 | [Setup Environment](./phase-01-setup.md) | Pending |
+| 2 | [Core Implementation](./phase-02-impl.md) | Pending |
+| 3 | [Testing & Validation](./phase-03-test.md) | Pending |
+
+<!-- IMPORTANT: Link text MUST be human-readable names (not filenames).
+     Bad:  [phase-01-setup.md](./phase-01-setup.md)
+     Good: [Setup Environment](./phase-01-setup.md) -->
 
 ## Dependencies
 

package/templates/repo/.github/skills/planning/references/red-team-personas.md

@@ -0,0 +1,69 @@
+# 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 |
+| **Scope & Complexity Critic** | YAGNI enforcer | Over-engineering, premature abstraction, unnecessary complexity, missing MVP cuts, scope creep, gold plating |
+
+## Reviewer Prompt Template
+
+Each reviewer prompt MUST include:
+
+1. This override: `"IGNORE your default code-review instructions. You are reviewing a PLAN DOCUMENT, not code. There is no code to lint, build, or test. Focus exclusively on plan quality."`
+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.
+
+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/templates/repo/.github/skills/planning/references/red-team-workflow.md

@@ -0,0 +1,77 @@
+# 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 `/ck-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 Task tool 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 6: Adjudicate
+For each finding, evaluate and propose: **Accept** or **Reject**.
+
+### Step 7: User Review
+Present by asking the user:
+- "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 by asking the user:
+- Options: "Yes, apply" | "No, reject" | "Modify suggestion"
+
+**If "Modify suggestion":**
+Ask by asking the user: "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`.
+
+## Output
+- Total findings by severity
+- Accepted vs rejected count
+- Files modified
+- Key risks addressed
+
+## Next Steps (MANDATORY)
+Remind user to run `/ck-plan validate` then `/ck-cook --auto`.
+
+## Important Notes
+- Reviewers must be HOSTILE, not helpful
+- Deduplicate aggressively
+- Adjudication must be evidence-based
+- Reviewers read plan files directly

package/templates/repo/.github/skills/planning/references/scope-challenge.md

@@ -0,0 +1,90 @@
+# 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:
+- `--fast` mode explicitly set (user already wants minimal)
+- 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
+
+## 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 is the minimum change set?
+- Identify work that could be deferred without blocking core goal
+- Flag scope creep: nice-to-haves disguised as requirements
+- Be ruthless about what's truly necessary vs aspirational
+
+### 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 by asking the user:
+
+**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 |
+
+## 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]
+- Minimum changes: [what's essential vs deferrable]
+- Complexity: [estimated files, new abstractions]
+- Selected mode: [EXPANSION/HOLD/REDUCTION]
+```
+
+Then proceed to mode detection and research phase.

package/templates/repo/.github/skills/planning/references/task-management.md

@@ -0,0 +1,134 @@
+# Task Management Integration
+
+## Session-Scoped Reality
+
+Tasks are **ephemeral** — they die when the session ends. `tasks/` holds lock files only, NOT task data. Plan files (plan.md, phase-XX.md with checkboxes) are the **persistent** layer.
+
+**Tool Availability:** `TaskCreate`/`TaskUpdate`/`TaskGet`/`TaskList` are **CLI-only** — disabled in VSCode extension (`isTTY` check). If these tools error, use `TodoWrite` for progress tracking. Plan files remain the source of truth; hydration is an optimization, not a requirement.
+
+The **hydration pattern** bridges sessions:
+
+```
+┌──────────────────┐  Hydrate   ┌───────────────────┐
+│ Plan Files       │ ─────────► │ Tasks      │
+│ (persistent)     │            │ (session-scoped)  │
+│ [ ] Phase 1      │            │ ◼ pending         │
+│ [ ] Phase 2      │            │ ◼ pending         │
+└──────────────────┘            └───────────────────┘
+                                        │ Work
+                                        ▼
+┌──────────────────┐  Sync-back ┌───────────────────┐
+│ Plan Files       │ ◄───────── │ Task Updates      │
+│ (updated)        │            │ (completed)       │
+│ [x] Phase 1      │            │ ✓ completed       │
+│ [ ] Phase 2      │            │ ◼ in_progress     │
+└──────────────────┘            └───────────────────┘
+```
+
+- **Hydrate:** Read plan files → TaskCreate per unchecked `[ ]` item
+- **Work:** TaskUpdate tracks in_progress/completed in real-time
+- **Sync-back:** Update `[ ]` → `[x]` in phase files, update plan.md frontmatter status
+
+## When to Create Tasks
+
+**Default:** On — auto-hydrate after plan files are written
+**Skip with:** `--no-tasks` flag in planning request
+**3-Task Rule:** <3 phases → skip tasks (overhead exceeds benefit)
+
+| Scenario | Tasks? | Why |
+|----------|--------|-----|
+| Multi-phase feature (3+ phases) | Yes | Track progress, enable parallel |
+| Complex dependencies between phases | Yes | Automatic unblocking |
+| Plan will be executed by cook | Yes | Seamless handoff |
+| Single-phase quick fix | No | Just do it directly |
+| Trivial 1-2 step plan | No | Overhead not worth it |
+
+## Task Creation Patterns
+
+### Phase-Level TaskCreate
+
+```
+TaskCreate(
+  subject: "Setup environment and dependencies",
+  activeForm: "Setting up environment",
+  description: "Install packages, configure env, setup database. See phase-01-setup.md",
+  metadata: { phase: 1, priority: "P1", effort: "2h",
+              planDir: "plans/260205-auth/", phaseFile: "phase-01-setup.md" }
+)
+```
+
+### Critical Step TaskCreate
+
+For high-risk/complex steps within phases:
+
+```
+TaskCreate(
+  subject: "Implement OAuth2 token refresh",
+  activeForm: "Implementing token refresh",
+  description: "Handle token expiry, refresh flow, error recovery",
+  metadata: { phase: 3, step: "3.4", priority: "P1", effort: "1.5h",
+              planDir: "plans/260205-auth/", phaseFile: "phase-03-api.md",
+              critical: true, riskLevel: "high" },
+  addBlockedBy: ["{phase-2-task-id}"]
+)
+```
+
+## Metadata & Naming Conventions
+
+**Required metadata:** `phase`, `priority` (P1/P2/P3), `effort`, `planDir`, `phaseFile`
+**Optional metadata:** `step`, `critical`, `riskLevel`, `dependencies`
+
+**subject** (imperative): Action verb + deliverable, <60 chars
+- "Setup database migrations", "Implement OAuth2 flow", "Create user profile endpoints"
+
+**activeForm** (present continuous): Matches subject in -ing form
+- "Setting up database", "Implementing OAuth2", "Creating user profile endpoints"
+
+**description**: 1-2 sentences, concrete deliverables, reference phase file
+
+## Dependency Chains
+
+```
+Phase 1 (no blockers)              ← start here
+Phase 2 (addBlockedBy: [P1-id])    ← auto-unblocked when P1 completes
+Phase 3 (addBlockedBy: [P2-id])
+Step 3.4 (addBlockedBy: [P2-id])   ← critical steps share phase dependency
+```
+
+Use `addBlockedBy` for forward references ("I need X done first").
+Use `addBlocks` when creating parent first ("X blocks these children").
+
+## Cook Handoff Protocol
+
+### Same-Session (planning → cook immediately)
+
+1. Planning hydrates tasks → tasks exist in session
+2. Cook Step 3: `TaskList` → finds existing tasks → picks them up
+3. Cook skips re-creation, begins implementation directly
+
+### Cross-Session (new session, resume plan)
+
+1. User runs `/ck-cook path/to/plan.md` in new session
+2. Cook Step 3: `TaskList` → empty (tasks died with old session)
+3. Cook reads plan files → re-hydrates from unchecked `[ ]` items
+4. Already-checked `[x]` items = done, skip those
+
+### Sync-Back (cook Step 6)
+
+1. `TaskUpdate` marks all session tasks complete.
+2. `project-manager` subagent runs full-plan sync-back:
+   - Sweep all `phase-XX-*.md` files.
+   - Reconcile completed tasks by metadata (`phase`, `phaseFile`).
+   - Backfill stale completed checkboxes `[ ]` → `[x]` across all phases (not only current phase).
+   - Update `plan.md` status/progress from actual checkbox state.
+3. If any completed task cannot be mapped to a phase file, report unresolved mappings before claiming completion.
+4. Git commit captures the state transition for next session.
+
+## Quality Checks
+
+After task hydration, verify:
+- Dependency chain has no cycles
+- All phases have corresponding tasks
+- Required metadata fields present (phase, priority, effort, planDir, phaseFile)
+- Task count matches unchecked `[ ]` items in plan files
+- Output: `✓ Hydrated [N] phase tasks + [M] critical step tasks with dependency chain`

package/templates/repo/.github/skills/planning/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) |