viepilot 2.45.6 → 2.48.0

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