viepilot 2.45.5 → 2.47.0

package/CHANGELOG.md

@@ -7,6 +7,79 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.47.0] - 2026-05-06
+
+### Added
+- **ENH-081** Brownfield Scan Trace Log — `BROWNFIELD-TRACE.md` real-time trace artifact
+  (`workflows/crystallize.md`). Before any signal category scanning begins, crystallize now
+  writes `.viepilot/BROWNFIELD-TRACE.md` to disk with all 13 categories pre-populated as
+  `planned`. Full feature set:
+  - **Trace initialization + resume detection**: on session start, checks for existing trace;
+    if `Status: scan_complete` → AUQ offers skip re-scan or re-scan from scratch; if trace is
+    mid-scan (interrupted) → AUQ offers resume from the last completed signal category
+  - **Per-Category Update Protocol (ENH-081)**: on category start → row moves to `scanning`;
+    on completion → row moves to `done`/`assumed`/`skipped` with file count, signals found,
+    start time, and duration; `## Files Read Log` appended with `[x]` (read) / `[ ]` (not found)
+    per file probed
+  - **Coverage gate (ENH-081)**: before presenting Scan Report, counts remaining `planned` rows;
+    non-blocking warning if any categories were not executed; sets `Status: scan_complete` in
+    trace header after gate passes
+  - **Gap Filling Log (ENH-081)**: each user response during Step 0-B-ii gap-filling is
+    immediately appended to `## Gap Filling Log` — no batching
+  - **Step Completion tracking**: `## Step Completion` rows updated after Step 0-C (Brainstorm
+    Stub) and Step 0-D (UI Workspace, 3 cases: done / skipped / N/A)
+
+## [2.46.1] - 2026-05-06
+
+### Fixed
+- **ENH-080** Upgrade re-scan (ENH-067 Step 0-B) now detects Signal Category 13 gap for
+  projects crystallized before v2.46.0:
+  - Delta computation table extended with `v2.46.0` row: detection field `ui_signals_imported`
+    absent from HANDOFF.json; trigger re-check prevents false-positive for backend-only projects
+    (no CSS, no Tailwind, no UI component files)
+  - Step 0-D now persists `ui_signals_imported: true/false` + `ui_signals_imported_at`/
+    `ui_signals_skipped_at` to `HANDOFF.json` after workspace generation or skip — marks gap
+    as "evaluated"; prevents re-asking on every crystallize run; `--upgrade` forces re-evaluation
+  - Patch mode handler added: re-runs Signal Cat 13 (Sub-scans A/B/C) + Step 0-D when UI gap
+    detected; AUQ gate preserved; no brainstorm supplement check (reads codebase directly)
+
+## [2.46.0] - 2026-04-27
+
+### Added
+- **ENH-079** Signal Category 13 — UI/Design System Signals in brownfield scanner
+  (`workflows/crystallize.md`). When an existing project has a real UI layer, the
+  brownfield scan now reverse-engineers it into a complete `.viepilot/ui-direction/`
+  workspace automatically:
+  - Sub-scan A: CSS custom properties (`--color-*`, `--font-*`, `--spacing-*`, `--radius-*`),
+    Tailwind config (`theme.extend.colors`, `fontFamily`, `spacing`, `borderRadius`),
+    SCSS variables, design token JSON files → Design.MD v1 `design.md`
+  - Sub-scan B: Page/route inventory for 8 framework types (Next.js App Router, Next.js Pages
+    Router, React Router, Vue Router, Angular, Nuxt 3, SvelteKit, plain HTML) →
+    `index.html` hub + `pages/{slug}.html` stubs per discovered route
+  - Sub-scan C: Component inventory via file glob + UI library detection from `package.json`
+    (shadcn/ui, Material UI, Chakra UI, Ant Design, Headless UI, Bootstrap, Radix) →
+    `notes.md ## components_inventory`
+  - AUQ gate: "Generate ui-direction workspace?" before reverse-engineering (skippable)
+  - Scan Report `ui_signals` field: `triggered`, `workspace_generated`, `ui_tokens`,
+    `ui_pages`, `ui_components`
+  - `notes.md` front matter: `reverse_engineered: true` flag — distinguishes auto-generated
+    sessions from manually crafted brainstorm sessions
+  - `workflows/brainstorm.md` Step 3C: imports Signal 13 data when brownfield stub contains
+    `ui_signals`; handles 3 cases (workspace generated / data present / not triggered);
+    offers on-demand workspace generation via AUQ
+
+## [2.45.6] - 2026-04-27
+
+### Fixed
+- **BUG-026**: `vp-brainstorm` internal session sub-commands (`/save`, `/research-ui`,
+  `/review-arch`, `/sync-ui`) conflicted with Claude Code's `/` command prefix —
+  typed as slash commands they were intercepted as unknown skill invocations.
+  Fix: removed all slash sub-command documentation; replaced with proactive AUQ
+  triggers that fire on intent detection (multi-language save signals: "save",
+  "done", "xong", "lưu"; UI walkthrough offered on research intent; arch review
+  offered on review intent). Consistent behavior across ALL adapters — no
+  adapter-specific typing rules (BUG-026)
+
 ## [2.45.5] - 2026-04-27
 
 ### Enhanced

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "viepilot",
-  "version": "2.45.5",
+  "version": "2.47.0",
   "description": "**Autonomous Vibe Coding Framework / Bộ khung phát triển tự động có kiểm soát**",
   "main": "index.js",
   "bin": {

package/skills/vp-brainstorm/SKILL.md

@@ -63,6 +63,19 @@ Prompt user conversationally with numbered list options.
 
 ## C. Tool Usage
 Use Cursor tools: `Shell`, `ReadFile`, `Glob`, `rg`, `ApplyPatch`, `WebSearch`, `WebFetch`, `Subagent`
+
+## D. Session Actions — Proactive AUQ Triggers (BUG-026)
+**No slash sub-commands.** All session actions are triggered proactively by the AI via
+`AskUserQuestion` at the right moment — no user typing required.
+
+| Action | Trigger condition | AUQ prompt |
+|--------|-------------------|------------|
+| **Save + crystallize handoff** | User signals done: "save", "done", "xong", "lưu", "finished", "ready", "crystallize", or equivalent intent | "Save session and prepare for /vp-crystallize?" |
+| **UX walkthrough** | In UI session AND user mentions "research", "test", "UX", "walkthrough" — OR ≥1 UI signals accumulated | "Run UX walkthrough (3-phase simulate + research + update HTML)?" |
+| **Architecture review** | User asks "review decisions", "check arch", "summarize choices", or equivalent intent | "Generate architecture review summary table?" |
+| **Sync UI → Arch** | After arch update when UI workspace also active | "Sync architecture changes to UI Direction workspace?" |
+
+**Why:** In Claude Code terminal, any `/command` is intercepted by the shell as a skill invocation. Using proactive AUQ triggers works identically on ALL adapters — no adapter-specific typing rules needed.
 </cursor_skill_adapter>
 <scope_policy>
 ## ViePilot Namespace Guard (BUG-004)
@@ -90,15 +103,15 @@ Supports:
 - UI Direction mode: create/update HTML prototype + notes under `.viepilot/ui-direction/{session-id}/` — supports **multi-page** (`pages/{slug}.html` + hub `index.html`) and the **`## Pages inventory`** hook in `notes.md` when `pages/` exists (FEAT-007)
 - **Phase assignment (ENH-030):** in every session, features/capabilities are assigned directly to Phase 1, Phase 2, Phase 3... — no MVP/Post-MVP/Future tiers. Session file stores assignments in the `## Phases` section.
 - **Project meta intake (FEAT-009):** after **scope locked**, **before** `Completed` / `/end`, if `.viepilot/META.md` (`viepilot_profile_id`) is missing — run **sequential** Q&A with proposals; read/write `~/.viepilot/profile-map.md`; create `~/.viepilot/profiles/<slug>.md` + binding per **`docs/dev/global-profiles.md`**. If a profile is already bound — skip intake by default (ask if change needed).
-- **UX walkthrough (FEAT-010 + ENH-019 + ENH-020):** in **`--ui`** mode, command **`/research-ui`** or **`/research ui`** runs 3 phases — simulates **end-user** (with **content stress pass** + **stress recipes by archetype** → **Stress findings**) → **UX designer + web research** → update `index.html` / `pages/*.html` / `style.css` and write **`## UX walkthrough log`** in `notes.md` (sync hub + **Pages inventory** for multi-page).
-- **Background UI extraction (ENH-026 + ENH-060):** automatically detects UI signal keywords in every brainstorm session (no `--ui` flag required). **Auto-suggests itself (ENH-060):** if the initial message contains ≥1 UI keyword, shows a proactive 🎨 banner immediately — mirrors Architect Design Mode's 🏗️ proactive activation. Accumulation starts at ≥1 signal (was ≥3); surfaces for confirmation when topic ends, `/save`, or **≥2 unique signals** accumulated (was ≥5) — does not interrupt the main conversation.
-- **Idea → Architecture breakdown loop (ENH-061):** structured 8-step flow from free idea collection → scope lock → **Feature → Coverage mapping** (maps each Phase 1 feature to an architect page + UI screen, outputs `## Coverage` matrix in `notes.md`) → Architect Design → **`arch_to_ui_sync`** reverse sync (surfaces UI implications of architectural decisions; `/sync-ui` command) → UI Direction → **completeness gate** (CHECK 4: warns if any Phase 1 feature has no coverage in either mode, non-blocking). See `Recommended Breakdown Ordering` section in `workflows/brainstorm.md`.
+- **UX walkthrough (FEAT-010 + ENH-019 + ENH-020):** in **`--ui`** mode, proactively offered via AUQ when user mentions "research", "test UX", "walkthrough" — or when ≥1 UI signals accumulated. Runs 3 phases: simulates **end-user** (with **content stress pass** + **stress recipes by archetype** → **Stress findings**) → **UX designer + web research** → update `index.html` / `pages/*.html` / `style.css` and write **`## UX walkthrough log`** in `notes.md` (sync hub + **Pages inventory** for multi-page).
+- **Background UI extraction (ENH-026 + ENH-060):** automatically detects UI signal keywords in every brainstorm session (no `--ui` flag required). **Auto-suggests itself (ENH-060):** if the initial message contains ≥1 UI keyword, shows a proactive 🎨 banner immediately — mirrors Architect Design Mode's 🏗️ proactive activation. Accumulation starts at ≥1 signal (was ≥3); surfaces for confirmation when topic ends, user signals done, or **≥2 unique signals** accumulated (was ≥5) — does not interrupt the main conversation.
+- **Idea → Architecture breakdown loop (ENH-061):** structured 8-step flow from free idea collection → scope lock → **Feature → Coverage mapping** (maps each Phase 1 feature to an architect page + UI screen, outputs `## Coverage` matrix in `notes.md`) → Architect Design → **`arch_to_ui_sync`** reverse sync (surfaces UI implications of architectural decisions; proactively offered via AUQ after arch updates) → UI Direction → **completeness gate** (CHECK 4: warns if any Phase 1 feature has no coverage in either mode, non-blocking). See `Recommended Breakdown Ordering` section in `workflows/brainstorm.md`.
 - **Unified workspace mode selection (BUG-018):** after scope lock, before any design workspace is created, an AUQ prompt offers: Both / Architect only / UI Direction only / Neither. Architect auto-activate heuristic is deferred until after this selection; suppressed if user selects "Neither" or "UI Direction only".
 - **Admin & Governance coverage (ENH-063):** Topic 6 in brainstorm template; proactive 🔐 heuristic fires on admin/governance keywords; admin coverage gate before /save for multi-user/SaaS/compliance projects; `admin.html` added to Architect workspace when applicable; `notes.md ## admin` YAML exported via crystallize.
 - **Content Management coverage (ENH-065):** Topic 7 in brainstorm template; proactive 🗂️ heuristic fires on content-type/media/SEO keywords; content coverage gate before /save for projects with content layer; `content.html` added to Architect workspace; `notes.md ## content` YAML exported via crystallize.
 - **Admin Entity Management coverage (ENH-068):** Topic 7 in brainstorm template; proactive 🗄️ heuristic fires on CRUD/entity/admin panel keywords; entity management coverage gate before /save for projects with DB entities (cross-references ERD); `entity-mgmt.html` added to Architect workspace; `notes.md ## entity_mgmt` YAML exported via crystallize.
 - **User Data Management coverage (ENH-066):** Topic 9 in brainstorm template; proactive 👤 heuristic fires on user-account/privacy/auth keywords; user data coverage gate before /save for B2C/SaaS/GDPR projects; `user-data.html` added to Architect workspace; `notes.md ## user_data` YAML exported via crystallize.
-- **Architect Design Mode (FEAT-011):** `/vp-brainstorm --architect` or auto-activate when ≥3 components/services detected; generate HTML workspace (architecture, data-flow, decisions, tech-stack, tech-notes, feature-map) with Mermaid diagrams; incremental update per decision; `/review-arch` command; machine-readable `notes.md` YAML schema.
+- **Architect Design Mode (FEAT-011):** `/vp-brainstorm --architect` or auto-activate when ≥3 components/services detected; generate HTML workspace (architecture, data-flow, decisions, tech-stack, tech-notes, feature-map) with Mermaid diagrams; incremental update per decision; architecture review offered via AUQ when user asks to review decisions; machine-readable `notes.md` YAML schema.
 - **ERD page (ENH-027):** Architect workspace includes `erd.html` — Mermaid `erDiagram`, entity list table, relationship summary; triggered by DB/entity/table/relationship keywords; notes.md `## erd` YAML section exported to ARCHITECTURE.md `## Database Schema` via crystallize Step 1D.
 - **User Use Cases page (ENH-028):** Architect workspace includes `user-use-cases.html` — actor/use-case diagram (Mermaid flowchart), use case table; triggered by user/role/actor/story keywords; notes.md `## use_cases` YAML section exported to PROJECT-CONTEXT.md `## User Stories & Use Cases` via crystallize Step 1D.
 - **C4Context/Sequence/Deployment/APIs pages (ENH-029, 12-page workspace):** Architect workspace expanded to 12 pages — `sequence-diagram.html` (per-scenario sequenceDiagram), `deployment.html` (infra graph + environments + CI/CD pipeline), `apis.html` (endpoint tables with HTTP method badges); page boundary rules table; trigger keywords for sequence/deploy/API; notes.md `## apis` YAML section; deployment+APIs exported to ARCHITECTURE.md via crystallize Step 1D (sequence excluded — scenario docs are not architecture artifacts).

package/workflows/brainstorm.md

@@ -334,6 +334,70 @@ Store the pending gap list. Re-surface the same AUQ at `/save` before writing th
 Proceed normally. Do **not** set `upgrade_supplement_version` — gap will re-surface on next open.
 </step>
 
+<step name="brownfield_ui_signal_import">
+### Step 3C: Brownfield UI Signal Import (ENH-079)
+
+**Trigger:** When the loaded session is a brownfield import stub (contains `session-brownfield-import.md` or `IS_BROWNFIELD=true`) AND the session's embedded Scan Report contains a `ui_signals` field.
+
+**Check:** Read session file for `ui_signals` YAML block under `## Scan Report`.
+
+---
+
+**Case 1 — workspace already generated** (`ui_signals.workspace_generated: true`):
+
+Display notice (no AUQ required):
+```
+UI workspace already generated at .viepilot/ui-direction/{session-id}/
+Open index.html to review {ui_pages.count} pages and {ui_components.total} components.
+```
+Continue brainstorm normally. Do not re-generate workspace.
+
+---
+
+**Case 2 — Signal 13 data present, workspace NOT yet generated** (`ui_signals.triggered: true`, `workspace_generated: false` or absent):
+
+Import into session notes.md:
+- `ui_pages.routes[]` → populate `## pages_inventory` section
+- `ui_components` data → populate `## components_inventory` section
+- `ui_tokens` summary → populate `## design_tokens` section
+- Set notes.md front matter: `reverse_engineered: true`
+
+Display import summary:
+```
+Imported Signal 13 data: {ui_pages.count} pages, {ui_components.total} components,
+{ui_tokens.detected} tokens detected ({ui_tokens.assumed} assumed).
+```
+
+**Claude Code (terminal) — REQUIRED:** Offer workspace generation via AUQ:
+- question: "Signal 13 data imported. Generate full ui-direction workspace now?"
+- header: "UI Workspace"
+- options:
+  a. "Yes — generate workspace (Recommended)" → run workspace generation (Step 0-D logic from crystallize.md)
+  b. "Continue brainstorm first" → proceed; workspace generation remains available
+
+**Text fallback:**
+```
+Signal 13 data imported.
+  1. Generate ui-direction workspace now (Recommended)
+  2. Continue brainstorm first
+```
+
+---
+
+**Case 3 — `ui_signals` not present** (Signal 13 not triggered for this project):
+
+Skip this step entirely. Proceed to Step 4 normally.
+
+---
+
+**Reverse-engineered workspace handling:**
+
+When `notes.md` front matter contains `reverse_engineered: true`:
+- Display "(Reverse-engineered)" badge in session header instead of standard brainstorm banner
+- Skip "missing brainstorm" warnings in vp-audit and vp-crystallize
+- Do not treat session as an incomplete brainstorm — it is a valid documentation artifact
+</step>
+
 <step name="brainstorm_mode">
 ## 4. Brainstorm Mode
 
@@ -1178,7 +1242,7 @@ When the user mentions: `user story`, `use case`, `actor`, `persona`, `as a user
 
 1. After each **major decision** (tech stack, service boundary, data model) → update the related HTML section + update `notes.md`.
 2. When the user **changes a decision** → **incremental update**: only edit the related section; keep all other sections unchanged. Add `data-updated="true"` attribute + class `.updated` CSS highlight (yellow left border + "updated" badge) to the changed element.
-3. **`/review-arch`** command → ViePilot outputs a summary table of all `decisions` (from `notes.md`) + list of `open_questions` with status; ask the user to confirm before continuing.
+3. **Architecture review trigger** — when user asks to review decisions ("review", "check architecture", "summarize choices", "what did we decide", or equivalent intent): ViePilot proactively outputs a summary table of all `decisions` (from `notes.md`) + list of `open_questions` with status, then asks the user to confirm before continuing. **Claude Code (terminal) — REQUIRED:** use `AskUserQuestion` to offer the review; text fallback on other adapters.
 
 #### Incremental update rule
 
@@ -1457,8 +1521,8 @@ This mirrors **Architect Design Mode** which proactively banners when system arc
 
 #### Surface triggers (when to ask the user)
 Display a confirmation dialogue when any of the following conditions occur:
-- (a) **Topic ends** — user types `/topic` to switch to a new topic or says "next"
-- (b) **User types `/save` or `/review`**
+- (a) **Topic ends** — user says "next", "next topic", or switches subject
+- (b) **User signals session end** — says "save", "done", "xong", "finished", "ready", "crystallize", "ready for crystallize", or equivalent intent in any language
 - (c) **≥2 unique signals accumulated** in the buffer
 
 #### Confirmation dialogue template
@@ -1490,12 +1554,16 @@ mkdir -p .viepilot/ui-direction/{session-id}
 
 ### UI Direction — UX walkthrough & upgrade (FEAT-010)
 
-When inside **`/vp-brainstorm --ui`** or a `.viepilot/ui-direction/{session-id}/` already exists for the current session, the user can invoke:
+When inside **`/vp-brainstorm --ui`** or a `.viepilot/ui-direction/{session-id}/` already exists for the current session, the UX walkthrough pipeline is **proactively triggered via AUQ** (BUG-026) when:
+- User mentions "research", "test", "UX review", "walkthrough", "simulate user", or equivalent intent
+- OR: ≥1 UI signal accumulated AND user signals topic end
 
-- **`/research-ui`** — runs the full pipeline below
-- **`/research ui`** — **alias** of `/research-ui` (space after `research`; does not conflict with `/research {free topic}`)
+**Claude Code (terminal) — REQUIRED:** Call `AskUserQuestion`:
+- question: "Run UX walkthrough? (3-phase: simulate user → UX research → update HTML)"
+- header: "UX Walkthrough"
+- options: [{ label: "Yes — run full walkthrough (Recommended)", description: "Simulate end-user + content stress + research + update prototype" }, { label: "Skip for now", description: "Continue brainstorm; offer again at session end" }]
 
-The user can include one line of context (e.g., product name **Trips**, persona, priority flow) — entered in the same message as the command.
+The user can include one line of context (e.g., product name, persona, priority flow) — in the same message or as a follow-up after selecting "Yes".
 
 Apply **the phases sequentially** (assistant does not skip a phase unless the user explicitly says “phase 1 only”):
 
@@ -1623,6 +1691,23 @@ After intake is **completed** or a **valid skip** (META already has profile) →
 <step name="save_session">
 ## 6. Save Session
 
+### Save Trigger (BUG-026)
+
+The save step fires when the AI detects session-end intent — **no slash command required**.
+
+**Save intent signals** (any language):
+- "save", "done", "finished", "ready", "crystallize", "ready for crystallize", "let's save", "that's it", "wrap up"
+- Equivalent phrases in the session language (e.g. "xong", "luu", or any clear session-end signal)
+- Or: conversation reaches natural end (all topics covered, no new questions)
+
+**Claude Code (terminal) — REQUIRED:** Call `AskUserQuestion`:
+- question: "Save session and prepare for /vp-crystallize?"
+- header: "Save Session"
+- options: [{ label: "Save + prepare for crystallize (Recommended)", description: "Write session file, then offer /vp-crystallize handoff" }, { label: "Continue brainstorming", description: "Not done yet — keep going" }]
+
+On "Save + prepare": proceed to Pre-Save validation below, then write file, then offer crystallize handoff.
+On "Continue brainstorming": resume conversation.
+
 ### Pre-Save Phase Assignment Validation (ENH-052)
 
 Before writing the session file, validate phase assignment completeness:
@@ -1648,7 +1733,7 @@ CHECK 4 (ENH-061): If both Architect workspace AND UI Direction workspace are ac
     1. Assign all features to phases (## Phases section)
     2. Ensure Phase 1 has at least one feature
 
-  Return to the conversation to assign phases, then /save again.
+  Return to the conversation to assign phases, then signal done when ready (e.g. "save" or "xong").
   ```
 - If scope is **not** locked (exploratory session — no feature assignments):
   → **Allow save** with `Status: In Progress` and add advisory note to session file:
@@ -1660,7 +1745,7 @@ CHECK 4 (ENH-061): If both Architect workspace AND UI Direction workspace are ac
   ```
   ⚠️  Coverage gap detected — these Phase 1 features have no Architect or UI coverage:
   - {feature name}
-  Consider running /sync-ui or adding these features to a workspace before /vp-crystallize.
+  Consider asking to sync UI or adding these features to a workspace before /vp-crystallize.
   Proceed with save? (yes / skip coverage for now)
   ```
 - If brownfield stub session (`IS_BROWNFIELD=true`): **skip this gate** — brownfield stubs intentionally have no phases.

package/workflows/crystallize.md

@@ -54,10 +54,15 @@ If `~/.viepilot/config.json` is absent, use defaults (en/en) — do not fail.
 | v2.32.0 | `## Admin & Governance` in PROJECT-CONTEXT.md | section absent AND `admin_imported` not in HANDOFF.json |
 | v2.33.0 | `## Content Management` in PROJECT-CONTEXT.md | section absent AND `content_imported` not in HANDOFF.json |
 | v2.34.0 | `## User Data Management` in PROJECT-CONTEXT.md | section absent AND `user_data_imported` not in HANDOFF.json |
+| v2.46.0 | UI/Design scan not run (Signal Cat 13) | `ui_signals_imported` absent from HANDOFF.json AND any UI trigger condition met: `.css`/`.scss` files > 5 OR `tailwind.config.js`/`tailwind.config.ts` exists OR component files (`.jsx/.tsx/.vue/.svelte`) > 10 |
 
 Cross-check: confirm section is actually absent from current `PROJECT-CONTEXT.md` before listing
 as a gap — avoids false positives for projects that have the content already.
 
+UI trigger re-check note: backend-only projects (no CSS, no Tailwind, no UI components) must
+NOT see "UI scan gap" — the trigger condition re-check prevents false-positive upgrade noise
+for CLI tools, data pipelines, and other non-UI projects.
+
 ### Upgrade menu
 
 **Claude Code (terminal) — REQUIRED:**
@@ -89,6 +94,10 @@ For each missing section, run only the corresponding Step 1D export item:
 - `## Admin & Governance` → Step 1D item 7 (ENH-063)
 - `## Content Management` → Step 1D item 8 (ENH-065)
 - `## User Data Management` → Step 1D item 9 (ENH-066)
+- UI/Design scan (v2.46.0, ENH-079) → Re-run Signal Category 13 (Sub-scans A/B/C) then
+  proceed through Step 0-D (AUQ gate + workspace generation). AUQ gate is preserved — user
+  can still choose to skip. No brainstorm supplement check required (reads codebase directly).
+  After gate: writes `ui_signals_imported` to HANDOFF.json per Task 121.2 spec.
 
 For each item:
 1. Check if architect `notes.md` has the corresponding YAML section (`## admin`, `## content`,
@@ -269,7 +278,92 @@ When brownfield was triggered automatically (not via `--brownfield`), present th
 > - "Cancel" / "3" → exit without changes
 
 **When brownfield mode is active:**
-1. Run the full 12-category codebase scanner (Signal Categories 1–12 below).
+
+### Brownfield Scan Trace — Initialization (ENH-081)
+
+**Before running any signal category**, initialize the scan trace:
+
+1. Check if `.viepilot/BROWNFIELD-TRACE.md` exists.
+
+2. **If exists AND `Status: scan_complete`** — prior scan completed. Offer resume via AUQ:
+   ```
+   question: "Prior scan found (completed {date}). Re-scan or resume from gap-filling?"
+   header: "Brownfield Trace"
+   options:
+     a. "Resume — skip re-scan, go to gap-filling (Recommended)"
+     b. "Re-scan from scratch — overwrite trace"
+   ```
+   - On "Resume": skip to Interactive Gap-Filling (Step 0-B-ii), using data from prior trace.
+   - On "Re-scan": delete trace, continue to step 4 below.
+
+3. **If exists AND `Status: scanning`** — prior scan was interrupted. Read which category row
+   last shows `scanning` → identify interrupted category N. Offer via AUQ:
+   ```
+   question: "Prior scan interrupted at Signal Cat {N} — {Category Name}. How to proceed?"
+   header: "Interrupted Scan"
+   options:
+     a. "Resume from Signal Cat {N} (Recommended)"
+     b. "Re-scan from scratch"
+   ```
+   - On "Resume from Cat N": skip completed categories (1 through N-1), restart from Cat N.
+   - On "Re-scan": overwrite trace, continue to step 4 below.
+
+4. **If not exists (or user chose "Re-scan"):** create `.viepilot/BROWNFIELD-TRACE.md`:
+
+```markdown
+# Brownfield Scan Trace
+
+<!-- Generated by vp-crystallize --brownfield v{crystallize_version} -->
+
+## Session Info
+- **Started**: {ISO-8601 timestamp}
+- **Project**: {project_name or "unknown (pre-scan)"}
+- **crystallize_version**: {semver}
+- **Status**: scanning
+
+## Signal Coverage
+
+| # | Category | Status | Files Checked | Signals Found | Started | Duration |
+|---|----------|--------|---------------|---------------|---------|----------|
+| 1 | Build Manifest & Package Identity | planned | — | — | — | — |
+| 2 | Framework & Library Detection | planned | — | — | — | — |
+| 3 | Architecture Layer Inference | planned | — | — | — | — |
+| 4 | Database Schema Signals | planned | — | — | — | — |
+| 5 | API Contract Files | planned | — | — | — | — |
+| 6 | Infrastructure & Deployment Config | planned | — | — | — | — |
+| 7 | Environment & Configuration Shape | planned | — | — | — | — |
+| 8 | Test Coverage Signals | planned | — | — | — | — |
+| 9 | Code Quality & Tooling | planned | — | — | — | — |
+| 10 | Documentation Files | planned | — | — | — | — |
+| 11 | Git History & Version Signals | planned | — | — | — | — |
+| 12 | File Extension Language Survey | planned | — | — | — | — |
+| 13 | UI/Design System Signals | planned | — | — | — | — |
+
+## Files Read Log
+
+(Populated during scanning — one subsection per signal category)
+
+## Gap Filling Log
+
+| Field | Status | Source | Value |
+|-------|--------|--------|-------|
+
+(Populated during interactive gap-filling — Step 0-B-ii)
+
+## Step Completion
+
+| Step | Status | Completed At | Notes |
+|------|--------|-------------|-------|
+| 0-B Scanner | in_progress | {timestamp} | — |
+| 0-C Brainstorm Stub | pending | — | — |
+| 0-D UI Workspace | pending | — | N/A if not triggered |
+```
+
+**Write this file to disk immediately** — before any signal category scanning begins.
+
+---
+
+1. Run the full 13-category codebase scanner (Signal Categories 1–13 below).
 2. Produce a structured **Scan Report** (see schema at end of this step).
 3. Classify every field as DETECTED / ASSUMED / MISSING per Gap Detection Rules.
 4. Present Scan Report summary to user; interactively fill every MISSING MUST-DETECT field.
@@ -676,6 +770,179 @@ Rule: `secondary_languages[]` = languages with ≥5 files that are not `primary_
 
 ---
 
+### Signal Category 13 — UI/Design System Signals
+
+**Trigger condition (ANY of):**
+- `.css` or `.scss` files > 5 in the project
+- `tailwind.config.js` or `tailwind.config.ts` exists
+- Component files (`.jsx`, `.tsx`, `.vue`, `.svelte`) > 10
+- Route config files detected (see Sub-scan B sources below)
+
+**Runs after:** Signal Category 12.
+**Output stored in:** `ui_signals` Scan Report field.
+
+---
+
+#### Sub-scan A — Design Token Extraction
+
+**Sources (priority order):**
+
+1. `tailwind.config.js` / `tailwind.config.ts`
+   - Extract: `theme.extend.colors`, `theme.colors`, `theme.fontFamily`, `theme.spacing`, `theme.borderRadius`
+
+2. CSS custom properties in `*.css` / `globals.css` / `variables.css` / `_variables.scss`
+   - `--color-*`, `--primary-*`, `--bg-*`, `--text-*` → TOKEN_MAP.colors
+   - `--font-*`, `--text-size-*` → TOKEN_MAP.typography
+   - `--spacing-*`, `--gap-*`, `--padding-*` → TOKEN_MAP.spacing
+   - `--radius-*`, `--rounded-*` → TOKEN_MAP.rounded
+
+3. SCSS variables: `$color-primary`, `$font-size-base`, `$spacing-unit`, etc.
+
+4. Design token JSON files: `tokens.json`, `design-tokens.json`, `theme.json`
+
+**Output:** Populate TOKEN_MAP for workspace generation step.
+- ASSUMED prefix for any token not found in any source.
+- Track `source_files[]` — list of all files scanned.
+
+**Scan Report field:** `ui_tokens: { detected: N, assumed: M, source_files: [] }`
+
+---
+
+#### Sub-scan B — Page/Route Inventory
+
+| Framework | Detection method | Route extraction |
+|-----------|-----------------|-----------------|
+| Next.js 13+ App Router | `app/` directory with `page.tsx` or `page.jsx` | Directory structure → route paths |
+| Next.js Pages Router | `pages/` directory (exclude `api/` and `_` prefixes) | Directory structure → route paths |
+| React Router | `src/routes/*.{jsx,tsx}`, `src/App.{jsx,tsx}` | Parse `<Route path="...">` attrs |
+| Vue Router | `src/router/index.{js,ts}` | Parse `routes: [{ path, component }]` |
+| Angular | `src/app/app-routing.module.ts` | Parse `Routes` array |
+| Nuxt 3 | `pages/` directory | Directory structure → route paths |
+| Plain HTML | `*.html` at root, `src/`, `public/` | File names → page names |
+| SvelteKit | `src/routes/+page.svelte` | Directory structure |
+
+**Scan Report field:** `ui_pages: { count: N, routes: [], framework: string }`
+
+Framework values: `"next-app"` | `"next-pages"` | `"react-router"` | `"vue-router"` | `"angular"` | `"nuxt3"` | `"sveltekit"` | `"html"` | `"unknown"`
+
+---
+
+#### Sub-scan C — Component Inventory
+
+**Sources:**
+
+1. Component file globs:
+   - `src/components/**/*.{jsx,tsx,vue,svelte}`
+   - `components/**/*.{jsx,tsx,vue}`
+   - `app/components/**/*`
+
+2. UI library detection from `package.json` dependencies:
+   - `@mui/material` → Material UI
+   - `@chakra-ui/react` → Chakra UI
+   - `@shadcn/ui` or `components/ui/` directory → shadcn/ui
+   - `antd` → Ant Design
+   - `@headlessui/react` → Headless UI
+   - `react-bootstrap` → Bootstrap
+   - `@radix-ui/*` → Radix primitives
+
+3. Common component pattern detection (by filename):
+   - Button, Modal, Dialog, Card, Form, Input, Select, Table, Navbar, Sidebar, Footer, Header
+
+**Scan Report field:**
+```yaml
+ui_components:
+  total: N
+  ui_library: string    # "shadcn/ui" | "Material UI" | "Chakra UI" | "Ant Design" | "Headless UI" | "Bootstrap" | "Radix" | "none"
+  categories:
+    layout: N
+    forms: N
+    navigation: N
+    data-display: N
+    feedback: N
+```
+
+---
+
+### Brownfield Scan Trace — Per-Category Update Protocol (ENH-081)
+
+For each signal category (1–13), apply this update protocol to `BROWNFIELD-TRACE.md`:
+
+#### On category start
+
+Update the category's row in `## Signal Coverage`:
+- Status: `scanning`
+- Started: current ISO timestamp (time portion only: `HH:MM:SS`)
+
+#### On category complete
+
+Update the category's row:
+- **Status**: one of:
+  - `done` — evidence found, DETECTED tier (high confidence)
+  - `assumed` — evidence found, ASSUMED tier (low confidence / indirect signal)
+  - `skipped` — no relevant files found; category not applicable to this project
+- **Files Checked**: integer count of files actually read
+- **Signals Found**: comma-separated key results (e.g. `react, next.js`), or `none`
+- **Duration**: elapsed seconds since category started (e.g. `3s`)
+
+Append a new subsection to `## Files Read Log`:
+
+```markdown
+### Signal {N} — {Category Name}
+
+- [x] {relative/path/to/file}  → {signal or "none found"}
+- [x] {another/file.json}      → {result summary}
+- [ ] {expected/missing.yaml}  → not present
+```
+
+Legend:
+- `[x]` = file was read (exists on disk and was examined)
+- `[ ]` = file was expected per workflow probe list but not found on disk
+
+**Skipped category** (no files probed): append instead:
+```markdown
+### Signal {N} — {Category Name}
+
+(No files probed — category not applicable to this project)
+```
+
+#### Status transitions
+
+Flow: `planned → scanning → done` (full evidence) | `scanning → assumed` (low confidence) | `scanning → skipped` (no files)
+
+```
+planned  →  scanning  (category starts)
+scanning →  done      (evidence found — DETECTED)
+scanning →  assumed   (evidence found — ASSUMED, low confidence)
+scanning →  skipped   (no matching files found)
+```
+
+#### Example — Signal Category 5 (API Contract Files)
+
+Row after completion:
+```
+| 5 | API Contract Files | done | 3 | openapi.yaml, swagger.json (REST) | 14:23:05 | 2s |
+```
+
+Files Read Log append:
+```markdown
+### Signal 5 — API Contract Files
+
+- [x] openapi.yaml           → REST (OpenAPI 3.0)
+- [x] swagger.json           → REST (Swagger 2.0)
+- [ ] graphql/schema.graphql → not present
+- [x] src/routes/index.ts    → REST route patterns detected
+```
+
+#### Signal Category 13 special format
+
+Signal Category 13 (UI/Design) Signals Found field format:
+```
+tailwind ({N} colors), {M} routes ({framework}), {K} components ({ui_library})
+```
+Example: `tailwind (12 colors), 8 routes (next-app), 24 components (shadcn/ui)`
+
+---
+
 ### Scan Report Schema (finalized)
 
 After running all 12 signal categories, produce this structured Scan Report:
@@ -741,6 +1008,26 @@ top_contributors: []
 docs_extracted: []             # { file, summary, key_facts[] }
 language_distribution: {}      # { ts: 142, java: 38, ... }
 open_questions: []             # root-level open questions (includes rollup from modules)
+ui_signals:                    # present only when Signal Category 13 triggered
+  triggered: bool
+  workspace_generated: bool    # true after workspace generation step completes
+  ui_tokens:
+    detected: N                # tokens extracted from sources
+    assumed: M                 # tokens filled with ASSUMED values
+    source_files: []           # files scanned (tailwind.config.js, globals.css, etc.)
+  ui_pages:
+    count: N
+    routes: []                 # [ { path, name, source_file } ]
+    framework: string          # "next-app" | "next-pages" | "react-router" | "vue-router" | "angular" | "nuxt3" | "sveltekit" | "html" | "unknown"
+  ui_components:
+    total: N
+    ui_library: string         # "shadcn/ui" | "Material UI" | "Chakra UI" | "Ant Design" | "Headless UI" | "Bootstrap" | "Radix" | "none"
+    categories:
+      layout: N
+      forms: N
+      navigation: N
+      data-display: N
+      feedback: N
 ```
 
 ---
@@ -829,6 +1116,19 @@ Root gap tier: MISSING (worst across modules)
 
 After scanner completes:
 
+**Coverage gate (ENH-081):** Before presenting the Scan Report, verify the trace:
+
+1. Read `## Signal Coverage` table from `.viepilot/BROWNFIELD-TRACE.md`.
+2. Count rows still showing `planned` (never executed).
+3. If any `planned` rows found: display warning (non-blocking):
+   ```
+   ⚠️ Coverage incomplete — {N} signal categories not executed:
+     - Signal Cat {N}: {Category Name}
+   Proceeding with partial Scan Report. Uncovered gap fields will be MISSING.
+   ```
+4. Update trace `## Session Info` → `Status: scan_complete`.
+5. Update `## Step Completion` row "0-B Scanner" → `done` + current timestamp.
+
 1. Display Scan Report summary table to user (field | value | status).
 2. **Per-module MISSING fields** — for each module with `gap_tier: MISSING`, pause and ask per field:
    ```
@@ -843,6 +1143,14 @@ After scanner completes:
 5. Capture all user responses; update Scan Report fields accordingly.
 6. All remaining unresolved items → `open_questions[]` (roll up per-module `open_questions[]` into root).
 
+**Gap Filling Log (ENH-081):** For each field where the user provides or confirms a value, append a row to `## Gap Filling Log` in `.viepilot/BROWNFIELD-TRACE.md`. Write after each user response — do not batch:
+
+| Field | Status | Source | Value |
+|-------|--------|--------|-------|
+| {field_name} | MISSING → user-filled | user input | {value} |
+| {field_name} | ASSUMED → accepted | user accept | {assumed_value} |
+| {field_name} | DETECTED → user-confirmed | user confirm | {value} |
+
 ---
 
 ### Brownfield Brainstorm Stub Generation (Step 0-C)
@@ -869,6 +1177,120 @@ After gap-filling is complete, write:
 
 **Purpose:** This stub allows `vp-audit` and other ViePilot tools to not error on missing brainstorm session files. The presence of `session-brownfield-import.md` is treated as a valid brownfield import.
 
+**Trace update (ENH-081):** Update `.viepilot/BROWNFIELD-TRACE.md` `## Step Completion` row
+"0-C Brainstorm Stub" → `done` + current timestamp + `stub: docs/brainstorm/session-brownfield-import.md`.
+
+---
+
+### UI Workspace Generation Gate (Step 0-D)
+
+**Condition:** Run only when `ui_signals.triggered: true` in the Scan Report.
+
+#### AUQ Gate — Brownfield UI Reverse-Engineering
+
+**Claude Code (terminal) — REQUIRED:** Call AskUserQuestion:
+- question: "UI signals detected — generate ui-direction workspace from existing code?"
+- header: "Brownfield UI Reverse-Engineering"
+- options:
+  a. "Yes — generate now (Recommended)" → proceed to workspace generation below
+  b. "Skip — I will create ui-direction manually" → set `ui_signals.workspace_generated: false`; add note to `open_questions[]`; write to `.viepilot/HANDOFF.json`: `{ "ui_signals_imported": false, "ui_signals_skipped_at": "{ISO-8601 timestamp}" }` (merge — do not overwrite unrelated fields); continue
+
+**Text fallback (non-terminal adapters):**
+```
+UI signals detected. Options:
+  1. Yes — generate ui-direction workspace now (Recommended)
+  2. Skip — create ui-direction manually later
+```
+
+#### Workspace Generation
+
+When user selects "Yes — generate now":
+
+Generate session ID: `brownfield-{YYYY-MM-DD}` (or reuse existing if re-running).
+
+Create artifacts under `.viepilot/ui-direction/{session-id}/`:
+
+**`design.md`** (Design.MD v1 format):
+- Populate colors, typography, spacing, rounded from TOKEN_MAP (Sub-scan A)
+- Prefix ASSUMED for any token not extracted from source
+- Add `## Source` section listing all scanned files and extraction method
+
+**`notes.md`**:
+```markdown
+---
+reverse_engineered: true
+source_project: {project_name}
+scan_date: {ISO date}
+signal_category: 13
+---
+
+## pages_inventory
+
+| Route | Page Name | Source File | Status |
+|-------|-----------|-------------|--------|
+{one row per route from ui_pages.routes[]}
+
+## components_inventory
+
+| Component | Type | File | UI Library |
+|-----------|------|------|------------|
+{one row per component from ui_components scan}
+
+## design_tokens
+
+- Detected: {ui_tokens.detected} tokens
+- Assumed: {ui_tokens.assumed} tokens
+- Sources: {ui_tokens.source_files[]}
+```
+
+**`index.html`** hub page:
+- Header: project name + UI library badge (if `ui_library != "none"`)
+- Table of contents: one link per page stub
+- Each entry: route path + source file reference
+
+**`pages/{slug}.html`** stubs — one per discovered route:
+- Page title (from route name) + route path
+- "Reverse-engineered from: {source file}"
+- Component list (if detectable via import analysis)
+- Placeholder section for handover notes
+
+**Generated artifact tree:**
+```
+.viepilot/ui-direction/
+  brownfield-{YYYY-MM-DD}/
+    design.md          ← design tokens (Design.MD v1)
+    notes.md           ← pages_inventory + components_inventory + design_tokens
+    index.html         ← hub page with all discovered pages linked
+    pages/
+      {slug}.html      ← one per discovered route/page
+```
+
+After generation: set `ui_signals.workspace_generated: true` in Scan Report.
+
+Also write to `.viepilot/HANDOFF.json` (merge — do not overwrite unrelated fields):
+```json
+{
+  "ui_signals_imported": true,
+  "ui_signals_imported_at": "{ISO-8601 timestamp}",
+  "ui_signals_version": "2.46.0"
+}
+```
+This flag is used by Step 0-B upgrade re-scan (ENH-080) to detect whether Signal Cat 13 has
+been run for this project. A future `--upgrade` re-run can force re-evaluation by re-running
+Signal Cat 13 even when `ui_signals_imported: true` is present.
+
+**Reverse-engineered workspace notice:** The workspace is a documentation approximation
+from static code analysis — not a pixel-perfect rendering. `pages/*.html` stubs describe
+what exists based on file structure and imports. The `reverse_engineered: true` flag allows
+downstream tools (`vp-audit`, `vp-crystallize`) to adjust expectations (e.g., skip
+"missing brainstorm" warnings).
+
+**Trace update (ENH-081):** Update `.viepilot/BROWNFIELD-TRACE.md` `## Step Completion` row
+"0-D UI Workspace":
+- If workspace generated: `done` + timestamp + `workspace: .viepilot/ui-direction/{session-id}/`
+- If user skipped AUQ: `skipped` + timestamp + `reason: user skipped`
+- If Signal Category 13 did not trigger: `N/A` (update row to `N/A` + timestamp)
+
 ---
 
 ### Safety Rules