viepilot 2.50.1 → 3.7.3

package/workflows/autonomous.md

@@ -37,6 +37,27 @@ Agent({
 
 See `agents/` directory for full agent specifications.
 
+## v3 Orchestration Agents (Phase 130 — FEAT-021)
+
+On Claude Code adapter (when `ADAPTER_CONTEXT.orchestration.parallel == true`), three dedicated
+subagent definitions in `agents/claude-code/` handle orchestrated execution:
+
+| Agent | File | Model | Role |
+|-------|------|-------|------|
+| vp-task-executor | `agents/claude-code/vp-task-executor.md` | claude-haiku-4-5 | Implements a single task contract; fresh context window per task |
+| vp-phase-planner | `agents/claude-code/vp-phase-planner.md` | claude-sonnet-4-6 | Reads phase, builds dependency graph, identifies parallel clusters |
+| vp-quality-gate | `agents/claude-code/vp-quality-gate.md` | claude-sonnet-4-6 | Runs verification commands; reports PASS/FAIL/PARTIAL |
+
+**Fan-out pattern** (implemented in Phase 133):
+```
+vp-phase-planner → clusters → Agent(vp-task-executor) × N (parallel) → Agent(vp-quality-gate)
+```
+
+**PreToolUse/PostToolUse hooks** (Claude Code only, registered via `vp-tools hooks install --adapter claude-code`):
+- `PreToolUse` on `Write`/`Edit` in task scope: validates path is repo-relative (BUG-009 gate)
+- `PostToolUse` on `Bash`: captures command output for quality-gate evidence log
+- Hook config lives in `~/.claude/settings.json` → `hooks` array
+
 <process>
 
 > **AUQ preload — Claude Code adapter (ENH-059):** At session start, before any interactive prompt, call `ToolSearch` with `query: "select:AskUserQuestion"` to load the deferred schema. Required on Claude Code (terminal). Skip only if `ToolSearch` returns an error → use text fallback for that session.
@@ -95,6 +116,39 @@ Build `SKILL_CONTEXT_MAP` in session memory:
 
 **If `## Skills` section absent or empty**: silent no-op — `SKILL_CONTEXT_MAP = { required: [], optional: [] }`.
 
+### ADAPTER_CONTEXT Injection (FEAT-021 Phase 127)
+
+Detect the active adapter and inject its capability map into session context. Skills use
+ADAPTER_CONTEXT to select correct tool names and fallback chains — no inline compat tables.
+
+```bash
+ADAPTER_CONTEXT_JSON=$(node "$HOME/.claude/viepilot/bin/vp-tools.cjs" detect-adapter --json 2>/dev/null \
+  || node "$(pwd)/bin/vp-tools.cjs" detect-adapter --json 2>/dev/null \
+  || echo '{"adapter":"claude-code","interactive_mode":"AUQ","orchestration":{"parallel":true,"teams":true},"capabilities":["shell","read","write","edit","search","agent","interactive"]}')
+```
+
+Parse into session variables:
+- `ADAPTER_ID` — e.g. `"claude-code"`
+- `ADAPTER_INTERACTIVE` — `"AUQ"` | `"text"` | `"none"`
+- `ADAPTER_PARALLEL` — `true` | `false` (orchestration.parallel)
+- `ADAPTER_TOOLS` — tools{} map (use `ctx.tools.shell` → correct tool name)
+
+**Shell tool resolution** (use `ADAPTER_TOOLS.shell` for all bash/cmd execution in tasks):
+| Adapter | Shell tool |
+|---|---|
+| claude-code | `Bash` |
+| cursor-agent | `run_terminal_cmd` |
+| antigravity | `shell` |
+| codex | `container.exec` |
+| copilot | `runCommands` |
+
+**Interactive fallback chain** (based on `ADAPTER_INTERACTIVE`):
+1. `"AUQ"` → call `AskUserQuestion` (preload via ToolSearch first)
+2. `"text"` → show numbered list in plain text
+3. `"none"` → proceed with defaults (log decision)
+
+Silent on error — do not fail the phase. Fallback: assume `claude-code` defaults.
+
 ### Tag Prefix Resolution (ENH-050)
 Resolve the enriched git tag prefix once at session start. All task/phase tags use `${TAG_PREFIX}`.
 
@@ -170,9 +224,137 @@ cat .viepilot/phases/{phase}/PHASE-STATE.md
 
 Check if phase already has completed tasks → resume from next task.
 
+### 3b. Orchestration Mode Selection (Phase 133 — FEAT-021)
+
+> ⛔ **ORCHESTRATOR STOP — Implementation Delegation Rule (ENH-096)**
+>
+> On Claude Code adapter, the main orchestrator agent MUST NOT:
+> - Call `Edit`, `Write`, or `MultiEdit` on implementation files (`lib/`, `bin/`, `tests/`, `agents/`, `skills/`, `workflows/` shipping content)
+> - Run `Bash` commands that write source code (e.g. `cat >`, `tee`, compiler/bundler invocations for production output)
+> - Implement features, fix bugs, or write tests inline in this context
+>
+> **Inline implementation is a framework violation.** It fills the orchestrator's context with
+> implementation tokens (file diffs, test output, compile logs), degrading orchestration quality
+> across subsequent tasks.
+>
+> The orchestrator is permitted ONLY to:
+> - `Read` — read PHASE-STATE.md, TRACKER.md, HANDOFF.json, task files, ROADMAP.md (read-only)
+> - `Bash` — read-only git checks ONLY: `git status --porcelain` (BUG-013: `??` lines = untracked, not dirty), `git rev-list --count @{u}..HEAD`, `node bin/vp-tools.cjs git-persistence --strict`
+> - `Agent` — spawn vp-task-executor, vp-quality-gate, vp-phase-planner, tracker-agent, vp-git-agent, changelog-agent
+>
+> The orchestrator MUST NOT call Edit, Write, or Bash for ANY writes — including state files.
+> All writes and git operations go through subagents (ENH-097).
+>
+> All implementation (file edits, test runs for implementation, commits) MUST go through
+> `vp-task-executor`. This applies even when there is only one task in the phase.
+
+Before entering the task loop, check `ADAPTER_PARALLEL` (set in ADAPTER_CONTEXT Injection step):
+
+```
+IF ADAPTER_PARALLEL == true AND ADAPTER_ID == "claude-code":
+  → ORCHESTRATOR MODE: fan-out dispatch via Agent tool (section 3b-orch)
+ELSE:
+  → SEQUENTIAL MODE: single-agent serial execution (section 3b-seq)
+```
+
+**Agent Teams mode** (when `ADAPTER_CONTEXT.orchestration.teams == true` AND pending task count ≥ 8):
+- Set `TEAMS_MODE = true`
+- Activate shared TodoWrite task list for teammate coordination
+- Each Agent worker reads from the shared list rather than receiving an explicit task prompt
+
+#### 3b-orch: Orchestrator Fan-out (Claude Code only)
+
+When `ADAPTER_PARALLEL == true`:
+
+**Step 1 — Dependency resolution** (via `vp-phase-planner` agent):
+```
+Agent(
+  subagent_type: "vp-phase-planner",
+  prompt: "Analyze phase {N} tasks in .viepilot/phases/{dir}/PHASE-STATE.md.
+           Return JSON: { clusters: [ { tasks: [id,...], can_parallel: bool,
+           sequential_fallback: [id,...] } ] }
+           Only include incomplete tasks."
+)
+```
+
+Parse `clusters` JSON from agent output. Each cluster is a set of independent tasks that can run in parallel.
+
+**Step 2 — Fan-out dispatch** (parallel `Agent` calls per cluster):
+```
+FOR each cluster in clusters:
+  IF cluster.can_parallel == true AND cluster.tasks.length > 1:
+    → Dispatch tasks in parallel:
+    FOR EACH task_id in cluster.tasks (simultaneously):
+      Agent(
+        subagent_type: "vp-task-executor",
+        prompt: "Execute task {task_id} in phase {N}.
+                 Task file: .viepilot/phases/{dir}/tasks/{task_id}.md
+                 PHASE-STATE: .viepilot/phases/{dir}/PHASE-STATE.md
+                 Repo root: {cwd}
+                 Return: TASK_RESULT: PASS|FAIL|PARTIAL + summary"
+      )
+    Collect all TASK_RESULT outputs before advancing.
+  ELSE:
+    → Execute tasks in sequence (cluster.sequential_fallback order)
+    Agent(vp-task-executor, single task)
+```
+
+**Spawn Template (copy-paste verbatim — do not paraphrase):**
+```
+Agent({
+  subagent_type: "vp-task-executor",
+  description: "Execute task {task_id} — phase {N}",
+  prompt: `Execute ViePilot task {task_id} for phase {N}.
+
+Task file: {task_path}
+Phase state: {phase_dir}/PHASE-STATE.md
+Repo root: {cwd}
+
+Read the task file completely, implement all acceptance criteria, run verification
+commands, commit with message format: {projectPrefix}-vp-p{N}-t{task_id}: <summary>,
+then report:
+TASK_RESULT: PASS|FAIL|PARTIAL
+Committed: <sha> — <message>
+Criteria: ✅/❌ per item`
+})
+```
+
+Replace `{task_id}`, `{N}`, `{task_path}`, `{phase_dir}`, `{cwd}`, `{projectPrefix}` with actual values.
+The orchestrator MUST NOT call Edit/Write/Bash for implementation — the subagent handles all of that.
+
+**Model tiering** (`ADAPTER_CONTEXT.orchestration.model_override`):
+- Worker agent (vp-task-executor): `claude-haiku-4-5` — routine file edits, low token cost
+- Planner/gate agent (vp-phase-planner, vp-quality-gate): `claude-sonnet-4-6` — reasoning, dependency analysis
+- Orchestrator (main agent): retains current model — coordination only, no implementation
+
+**Step 3 — Quality gate** (after each cluster completes):
+```
+Agent(
+  subagent_type: "vp-quality-gate",
+  prompt: "Run verification for phase {N} cluster {C}.
+           Tasks completed: {task_ids}
+           Check: acceptance criteria, tests, lint.
+           Return: QUALITY_GATE: PASS|FAIL|PARTIAL + findings"
+)
+```
+
+On `QUALITY_GATE: FAIL` or `PARTIAL` → route to control point (retry cluster / skip / stop).
+On `QUALITY_GATE: PASS` → update PHASE-STATE.md (all cluster tasks → done), update TRACKER.md, continue.
+
+**Teams mode** (when `TEAMS_MODE == true`):
+- Write all pending task IDs to shared `TodoWrite` list at phase start
+- Each `Agent(vp-task-executor)` reads next available task from shared list
+- Prevents duplicate execution when dispatching ≥ 8 tasks concurrently
+
+#### 3b-seq: Sequential Mode (non-Claude Code adapters)
+
+When `ADAPTER_PARALLEL == false` (Cursor / Antigravity / Codex / Copilot):
+
+Execute tasks one at a time in the main agent context. No fan-out, no subagent dispatch.
+
 ### 3b. Execute Tasks Loop
 
-For each task in phase:
+For each task in phase (sequential mode) or per cluster (orchestrator mode):
 
 #### Load Task Context
 ```yaml
@@ -449,9 +631,9 @@ IF (Paths block contains ≥5 files of the same type, e.g., skills/*/SKILL.md)
   OR (task description matches: "update all N files", "add row to all skills", "sync across N files")
 → Invoke doc-sync-agent instead of N sequential edits:
 
-   Agent({ subagent_type: "general-purpose",
+   Agent({ subagent_type: "doc-sync-agent",
      description: "doc-sync-agent: {change_mode} across {file_pattern}",
-     prompt: "Load agents/doc-sync-agent.md. Pattern: {glob}. Mode: {change_mode}. Anchor: {anchor}. Content: {content}."
+     prompt: "file_pattern: {glob}. change_mode: {change_mode}. anchor: {anchor}. content: {content}."
    })
    Non-Claude Code: apply changes sequentially inline.
 
@@ -507,6 +689,21 @@ quality_gate:
   - no_lint_errors: true
 ```
 
+#### Test Generation — test-generator-agent (ENH-057, BUG-028 fix)
+
+**Trigger**: current task is the last task in the phase AND task.md contains `## Acceptance Criteria`
+
+**Claude Code — invoke test-generator-agent:**
+```
+Agent({ subagent_type: "test-generator-agent",
+  description: "test-generator-agent: generate + run contract tests for phase {phase}",
+  prompt: "task_file: {task_md_path}. test_output_path: tests/unit/phase{phase}-{task}-contract.test.js. phase_number: {phase}. task_number: {task}."
+})
+```
+Non-Claude Code: generate test file inline from acceptance criteria, then run `npm test`.
+
+If test-generator-agent reports FAIL: **do NOT** mark task complete — fix failing criteria first.
+
 #### Git Persistence Gate (BUG-003)
 Before marking a task PASS, require durable git persistence:
 
@@ -540,6 +737,30 @@ If any check fails:
 - Update TRACKER.md immediately
 - Update HANDOFF.json immediately
 - Update CHANGELOG.md if feature/fix
+
+**Post-PASS: Intake Write-back (ENH-095)**
+
+After the above state updates, check the task `.md` for an `## Intake Source` block:
+```
+## Intake Source
+- channel_id:    trip-tracking-bug
+- sheet_name:    BUG
+- source_row:    1
+- manifest_path: .viepilot/intake/trip-tracking-bug-manifest.json
+- channel_type:  excel_m365
+- workbook_id:   {workbook_id or null}
+- sharing_url:   {sharing_url or null}
+```
+
+If the block is present:
+1. Parse the fields from the block
+2. Load manifest from `manifest_path` via `lib/intake/manifest.cjs → loadManifest()`
+3. Call `getWriteBackConfig(manifest, sheet_name)` → get `response_col`
+4. Build `response = { status: 'Fixed ✓', phaseTask: 'vp-p{N}-t{M}', version: currentVersion, date: YYYY-MM-DD }`
+5. Call `lib/intake/writeback.cjs → writebackIntakeResponse(channel, source_row, response, projectRoot, sheet_name, response_col)`
+6. Log: `[vp-auto] Intake write-back: row {source_row} → col {response_col}: "{text}" — {success|failed}`
+7. **Write-back failure is non-fatal** — log to stderr and continue to next task regardless
+
 - Move to next task
 
 **PARTIAL (some checks fail):**
@@ -564,14 +785,28 @@ update:
   - CHANGELOG.md: if feature/fix completed  ← via changelog-agent at end of phase (ENH-057)
 ```
 
-**Tracker updates — invoke tracker-agent:**
+**State updates — spawn subagents (Claude Code, ENH-097):**
+
 ```
-Agent({ subagent_type: "general-purpose",
-  description: "tracker-agent: update task {phase}.{task} → {status}",
-  prompt: "Load agents/tracker-agent.md. Operation: update-task-status. Phase: {phase}. Task: {task}. Status: {status}."
+# Task status (PHASE-STATE.md + TRACKER.md current state):
+Agent({ subagent_type: "tracker-agent",
+  description: "Update task {N}.{task_id} → {status}",
+  prompt: "operation: update-task-status. phase: {N}. task: {task_id}. status: {status}."
+})
+
+# HANDOFF.json update:
+Agent({ subagent_type: "tracker-agent",
+  description: "Update HANDOFF.json — phase {N} task {task_id}",
+  prompt: "operation: update-handoff. phase: {N}. phase_name: {phase_name}. task: {task_id}. task_name: {task_name}. status: {status}. version: {version}. tasks_total: {T}. tasks_completed: {C}. notes: [\"{note}\"]."
+})
+
+# ROADMAP.md phase status sync (after phase complete):
+Agent({ subagent_type: "tracker-agent",
+  description: "Update ROADMAP.md — phase {N} done",
+  prompt: "operation: update-roadmap-phase. phase_number: {N}. status: ✅ done. completed_date: {today}."
 })
 ```
-Non-Claude Code: update TRACKER.md inline as before.
+Non-Claude Code: update TRACKER.md, HANDOFF.json, ROADMAP.md inline as before.
 
 Rule:
 - Never defer state updates to end-of-phase only.
@@ -633,15 +868,21 @@ Before phase-level verification, run a UI stub check:
    | smarttrack-*/pom.xml (8 files) | 1.1 |   ← WRONG: glob pattern
    | smarttrack-*/src/** (7 files)  | 1.1 |   ← WRONG: summarized
    ```
-4. Create git tag: `{TAG_PREFIX}-vp-p{phase}-complete` (e.g. `git tag "${TAG_PREFIX}-vp-p${PHASE}-complete"`)
+4. Create phase-complete git tag — spawn vp-git-agent:
+   ```
+   Agent({ subagent_type: "vp-git-agent",
+     description: "Tag phase {N} complete",
+     prompt: "operation: create-tag. tag_name: {TAG_PREFIX}-vp-p{N}-complete."
+   })
+   ```
 5. Check version bump needed — apply `.viepilot/SYSTEM-RULES.md → Version Bump Rules`:
    - Features added → MINOR; Fixes only → PATCH; Mixed → MINOR; Breaking → MAJOR
 
    **Version bump — invoke changelog-agent (ENH-057, ENH-053 fix):**
    ```
-   Agent({ subagent_type: "general-purpose",
-     description: "changelog-agent: bump to {version} + CHANGELOG [{version}]",
-     prompt: "Load agents/changelog-agent.md. Version: {version}. Date: {today}. Entries: {phase_summary_bullets}. Files: package.json + CHANGELOG.md."
+   Agent({ subagent_type: "changelog-agent",
+     description: "Bump to {version} + CHANGELOG [{version}]",
+     prompt: "version: {version}. date: {today}. entries: {phase_summary_bullets}."
    })
    ```
    Non-Claude Code: update CHANGELOG.md + package.json inline as before.
@@ -649,13 +890,22 @@ Before phase-level verification, run a UI stub check:
    > changelog-agent is the **single authority** for version bumps. Both autonomous.md and
    > evolve.md invoke it — never do inline version bumps (resolves ENH-053).
 
-6. Update TRACKER.md
-7. Push all changes:
-   ```bash
-   git push
-   git push --tags
-   node bin/vp-tools.cjs git-persistence --strict
+6. Update TRACKER.md current state — spawn tracker-agent:
+   ```
+   Agent({ subagent_type: "tracker-agent",
+     description: "Update TRACKER.md — phase {N} complete",
+     prompt: "operation: update-current-state. data: Last completed phase {N} — {phase_name}. version: {version}."
+   })
+   ```
+7. Push branch + tags — spawn vp-git-agent:
+   ```
+   Agent({ subagent_type: "vp-git-agent",
+     description: "Push phase {N} complete",
+     prompt: "operation: push-all."
+   })
    ```
+   Then verify persistence (orchestrator may call this read-only check directly):
+   `node bin/vp-tools.cjs git-persistence --strict`
 
 ### 5a. Sync ROADMAP.md (after every phase complete)
 

package/workflows/brainstorm.md

@@ -5,12 +5,18 @@ Allows research inline within the same brainstorm session when needed.
 
 ## Adapter Compatibility
 
-| Feature | Claude Code (terminal) | Cursor (Agent/Skills) | Codex CLI | Antigravity (native) |
-|---------|----------------------|-----------------------|-----------|----------------------|
-| Interactive prompts | ✅ `AskUserQuestion` tool — **REQUIRED** | ❌ text fallback | ❌ text fallback | ❌ text fallback |
+Detected at session start via `vp-tools detect-adapter` → ADAPTER_CONTEXT. Use ADAPTER_CONTEXT.interactive to select prompt mode.
 
-**Claude Code (terminal):** Always call `AskUserQuestion` first. Only fall back to the plain-text menu below if the tool returns an error or is unavailable.
-**Cursor / Codex CLI / Antigravity / other adapters:** `AskUserQuestion` not available — use text menus below.
+| Feature | claude-code | cursor-agent | antigravity | codex | copilot |
+|---------|------------|--------------|-------------|-------|---------|
+| Interactive (ADAPTER_CONTEXT.interactive) | `AUQ` | `text` | `none` | `none` | `text` |
+| Prompt tool | `AskUserQuestion` | text list | defaults | defaults | text list |
+| Shell tool | `Bash` | `run_terminal_cmd` | `shell` | `container.exec` | `runCommands` |
+
+**Interactive fallback chain** (read from ADAPTER_CONTEXT.interactive):
+1. `"AUQ"` → call `AskUserQuestion` (preload via ToolSearch first)
+2. `"text"` → show plain-text numbered list
+3. `"none"` → proceed with session defaults (log decision)
 
 ## ViePilot Skill Scope Policy (BUG-004)
 
@@ -22,7 +28,24 @@ Allows research inline within the same brainstorm session when needed.
 <process>
 
 <step name="detect_session_language">
-## 0. Detect Session Language (ENH-032)
+## 0. ADAPTER_CONTEXT Load (FEAT-021)
+
+Detect active adapter and inject capability context. All interactive prompts in this workflow
+use ADAPTER_CONTEXT.interactive to select the correct prompt mode.
+
+```bash
+ADAPTER_CONTEXT_JSON=$(node "$HOME/.claude/viepilot/bin/vp-tools.cjs" detect-adapter --json 2>/dev/null \
+  || node "$(pwd)/bin/vp-tools.cjs" detect-adapter --json 2>/dev/null \
+  || echo '{"adapter":"claude-code","interactive_mode":"AUQ","orchestration":{"parallel":true}}')
+```
+
+Parse `interactive_mode` from JSON:
+- `"AUQ"` → use `AskUserQuestion` tool (preload via ToolSearch first)
+- `"text"` or `"none"` → use plain-text numbered list fallback
+
+Silent on error — fallback assumes claude-code defaults. Continue without blocking.
+
+## 0B. Detect Session Language (ENH-032)
 
 Read `~/.viepilot/config.json` → set `BRAINSTORM_LANG`:
 - `BRAINSTORM_LANG` = `language.document` from config (default: `en`)
@@ -254,6 +277,38 @@ If the user chooses to continue:
 5. If the session already has a **`## Phases`** section: briefly summarize existing phases; all subsequent updates must **merge** into that section (no silent deletion) unless the user explicitly requests narrowing/expanding scope.
 </step>
 
+<step name="reference_url_research">
+### Step 3A: Reference URL Research (ENH-092)
+
+**Trigger**: User provides a URL in their brainstorm input (competitor, reference app, documentation site).
+
+URL pattern detection: `https?://` present in user message before or during Step 3.
+
+When triggered:
+1. Extract URL from user message
+2. Dispatch research-agent with browser research op:
+   ```js
+   Agent({ subagent_type: "research-agent",
+     description: "research-agent: browse reference URL for brainstorm context",
+     prompt: `op: browse_url. url: "${url}". extract_focus: "features,ux-patterns,pricing,tech-stack". topic: "${sessionTitle}"` })
+   ```
+3. Present findings as `## Reference Research` section in brainstorm output:
+   - Key features / capabilities
+   - UX patterns observed
+   - Pricing model (if applicable)
+   - Tech stack clues
+4. Use findings as context for subsequent brainstorm questions
+5. If agent-browser not available: attempt WebFetch fallback (static HTML only — warn if empty)
+
+**Multiple URLs**: if user provides 2+ URLs, dispatch `compare_products` op:
+```js
+Agent({ subagent_type: "research-agent",
+  prompt: `op: compare_products. urls: ${JSON.stringify(urls)}. topic: "${sessionTitle}"` })
+```
+
+**Non-CC adapters**: skip agent dispatch, use WebFetch directly on the URL.
+</step>
+
 <step name="upgrade_gap_detection">
 ### Step 3B: Upgrade Gap Detection (ENH-067)
 
@@ -671,7 +726,7 @@ Map brainstorm UI signal keywords to capability tags:
 | UI Signal keywords | Capability match |
 |-------------------|-----------------|
 | `component`, `layout`, `screen`, `page`, `UI`, `UX` | `ui-generation`, `component-design` |
-| `responsive`, `mobile`, `grid` | `responsive-layout` |
+| `responsive`, `mobile`, `grid`, `breakpoint`, `viewport`, `adaptive`, `touch`, `swipe`, `safe-area`, `hamburger` | `responsive-layout` |
 | `design`, `theme`, `color`, `typography` | `design-system`, `design-tokens` |
 | `form`, `button`, `input`, `modal` | `component-design` |
 
@@ -699,6 +754,96 @@ After the session's first UI artifact is generated (or updated), append to `note
 If `## skills_used` already exists: merge (add new skills, update applied_at).
 If no skills matched or registry absent: omit `## skills_used` section.
 
+### Mobile Design Direction Sub-Phase (ENH-085)
+
+**Trigger:** UI Direction Mode is active AND any of these keywords appear in the session:
+`mobile` · `responsive` · `breakpoint` · `viewport` · `adaptive` · `touch` · `swipe`
+`safe-area` · `hamburger` · `tablet` · `phone` · `narrow` · `narrow screen` · `screen size`
+
+**When triggered — fire TWO sequential AUQ prompts before HTML generation begins:**
+
+**AUQ 1 — Viewport Strategy:**
+```
+question: "What is the responsive design strategy for this project?"
+options:
+  - label: "Mobile-first (Recommended)"
+    description: "Base styles target mobile; breakpoints (md:, lg:) scale up. Default for most web apps."
+  - label: "Desktop-first"
+    description: "Full desktop layout; shrink down with max-width breakpoints."
+  - label: "Mobile only"
+    description: "No desktop variant needed (PWA, native-style app, mobile-specific tool)."
+  - label: "Desktop only"
+    description: "Internal tool or dashboard — no mobile support required."
+```
+
+**AUQ 2 — Target Device Scope (multiSelect: true):**
+```
+question: "Which device types need UI direction?"
+multiSelect: true
+options:
+  - label: "Phone (≤767px)"
+    description: "Small screens, touch-first, vertical scroll, hamburger nav."
+  - label: "Tablet (768–1023px)"
+    description: "Medium screens, touch+pointer, hybrid layouts."
+  - label: "Desktop (≥1024px)"
+    description: "Large screens, pointer-first, dense information layouts."
+  - label: "Wide / TV (≥1280px)"
+    description: "Very large screens, 3+ column layouts, dashboard displays."
+```
+
+**Store answers as session context:**
+```yaml
+responsive_strategy: mobile-first | desktop-first | mobile-only | desktop-only
+target_devices: [phone, tablet, desktop, wide]   # subset based on AUQ selections
+```
+
+**Fallback (if AUQ not available):** set `responsive_strategy: mobile-first`, `target_devices: [phone, tablet, desktop]` silently.
+
+**Skip conditions:**
+- No mobile/responsive keywords in session → skip entirely (non-mobile project)
+- `responsive_strategy` already set in session context (resume) → skip AUQ, reuse stored values
+
+**Component Responsive Map in notes.md (ENH-085)**
+
+After the Mobile Design Direction AUQ completes (or on session resume with `responsive_strategy` set),
+append a `## Component Responsive Map` section to `notes.md`:
+
+```markdown
+## Component Responsive Map
+
+> ViePilot ENH-085 — Strategy: {responsive_strategy} | Devices: {target_devices joined with ", "}
+> Generated: {date}
+
+| Component      | Mobile (≤767px)        | Tablet (768–1023px)    | Desktop (≥1024px)    |
+|----------------|------------------------|------------------------|----------------------|
+| Navigation     | {mobile_nav}           | {tablet_nav}           | {desktop_nav}        |
+| Layout grid    | 1 column, full-width   | 2 columns              | 3+ columns / sidebar |
+| Data table     | Card list (stacked)    | Scrollable table       | Full table + filters |
+| Modal / dialog | Bottom sheet           | Centered dialog        | Centered dialog      |
+| Forms          | Single column          | 2-col grouped          | 2-col grouped        |
+| Buttons (CTA)  | Full-width             | Auto / inline          | Auto / inline        |
+| Images / media | 100% width, cropped    | 50–75% width           | Fixed aspect ratio   |
+
+### Navigation Pattern Detail
+- **Mobile**: {mobile_nav_detail}
+- **Tablet**: {tablet_nav_detail}
+- **Desktop**: {desktop_nav_detail}
+
+### Responsive Utilities Reference (Tailwind)
+```
+Mobile base  →  no prefix     (e.g., flex flex-col p-4)
+Tablet       →  `md:` prefix  (e.g., md:flex-row md:grid-cols-2)
+Desktop      →  `lg:` prefix  (e.g., lg:grid-cols-3 lg:sidebar-fixed)
+Wide         →  `xl:` prefix  (e.g., xl:max-w-7xl xl:px-12)
+```
+```
+
+Nav values for the table: use Navigation strategy lookup table defined in the per-breakpoint HTML section above.
+
+**Guard:** If `notes.md` already contains `## Component Responsive Map` → skip (do not overwrite).
+
+**Skip:** If `responsive_strategy` is null (non-mobile session) → omit section entirely.
+
 **Required hook (multi-page only)**
 
 When the `pages/` directory exists or any `pages/*.html` is added / renamed / removed:
@@ -707,6 +852,76 @@ When the `pages/` directory exists or any `pages/*.html` is added / renamed / re
 - Immediately update the **`## Pages inventory`** section in `notes.md` (table: Slug | File | Title | Purpose | Key sections | Nav to) — must match 100% of the current `pages/*.html` file set.
 - Do not end a topic / do not consider the UI session “synced” if the inventory diverges from files on disk.
 
+**Per-breakpoint sections in pages/*.html (ENH-085)**
+
+When `responsive_strategy` is set (from Mobile Design Direction sub-phase), append a
+`<div class="responsive-breakdown">` section to the bottom of every generated `pages/{slug}.html`:
+
+```html
+<!-- Responsive Breakdown — ViePilot ENH-085 -->
+<div class="responsive-breakdown">
+  <h2>Responsive Breakdown</h2>
+  <!-- Render only sections for active target_devices -->
+
+  <!-- Phone section: render when target_devices includes "phone" -->
+  <details open>
+    <summary>📱 Mobile (≤767px)</summary>
+    <div class="breakpoint-notes">
+      <p><strong>Layout:</strong> {mobile_layout}</p>
+      <p><strong>Navigation:</strong> {mobile_nav}</p>
+      <ul>{mobile_key_changes}</ul>
+    </div>
+  </details>
+
+  <!-- Tablet section: render when target_devices includes "tablet" -->
+  <details>
+    <summary>💻 Tablet (768–1023px)</summary>
+    <div class="breakpoint-notes">
+      <p><strong>Layout:</strong> {tablet_layout}</p>
+      <p><strong>Navigation:</strong> {tablet_nav}</p>
+      <ul>{tablet_key_changes}</ul>
+    </div>
+  </details>
+
+  <!-- Desktop section: render when target_devices includes "desktop" -->
+  <details>
+    <summary>🖥 Desktop (≥1024px)</summary>
+    <div class="breakpoint-notes">
+      <p><strong>Layout:</strong> {desktop_layout}</p>
+      <p><strong>Navigation:</strong> {desktop_nav}</p>
+    </div>
+  </details>
+</div>
+```
+
+**`<details open>`** = primary breakpoint (phone if mobile-first, desktop if desktop-first).
+
+**Navigation strategy lookup** (infer from page purpose):
+
+| Page purpose | Mobile nav | Tablet nav | Desktop nav |
+|---|---|---|---|
+| App / dashboard | Hamburger drawer | Bottom tab bar | Left sidebar |
+| Marketing / landing | Hamburger menu | Hamburger menu | Full horizontal nav |
+| E-commerce | Bottom tab (Home/Search/Cart/Profile) | Tab bar + filters | Full nav + mega menu |
+| Admin / internal | Bottom nav (compact) | Collapsible sidebar | Full left sidebar |
+| Auth (login/signup) | Single-column form | Centered card | Centered card |
+| Content / reader | Bottom nav | Collapsed sidebar | Persistent sidebar |
+
+**Skip conditions:**
+- `responsive_strategy` absent → skip block entirely
+- `responsive_strategy: mobile-only` → render Phone section only (no details wrapper needed)
+- `responsive_strategy: desktop-only` → render Desktop section only
+
+**CSS to append to shared `style.css`** (once per workspace, not per page):
+
+```css
+/* ENH-085 — Responsive Breakdown */
+.responsive-breakdown{margin-top:2rem;border-top:2px solid #e5e7eb;padding-top:1.5rem}
+.responsive-breakdown details{margin-bottom:1rem;border:1px solid #e5e7eb;border-radius:8px;padding:1rem}
+.responsive-breakdown summary{font-weight:600;cursor:pointer;padding:.25rem 0;user-select:none}
+.breakpoint-notes{padding-top:.75rem}
+```
+
 3. If the user sends references/components (including 21st.dev prompts/links), record clearly:
    - reference source
    - the UI area it applies to (page slug if multi-page)