viepilot 2.45.6 → 2.47.0

package/CHANGELOG.md

@@ -7,6 +7,67 @@ 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "viepilot",
-  "version": "2.45.6",
+  "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/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
 

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