viepilot 2.23.0 → 2.45.2

package/workflows/audit.md

@@ -454,6 +454,137 @@ fi
 ```
 </step>
 
+<step name="autolog_gate">
+## 5b. Auto-Log Gate (ENH-070)
+
+**Skip condition**: if `--no-autolog` flag is set → skip this entire step; proceed to Step 6.
+
+After the audit report is shown (Step 5), automatically log each detected issue as a request file — no manual `/vp-request` call needed.
+
+### Tier → Request Type Mapping
+
+| Tier | Issue category | Request type | Priority |
+|------|----------------|-------------|----------|
+| 1 | State inconsistency / HANDOFF drift / git tag missing | BUG | medium |
+| 1 | Execute-first ordering risk (BUG-001 heuristic) | BUG | medium |
+| 2 | Doc drift (README/CHANGELOG version mismatch) | BUG | low |
+| 2 | Missing docs / placeholder URLs | ENH | low |
+| 3 | Stack violation / correctness anti-pattern | BUG | high |
+| 3 | Stack improvement / best-practice gap | ENH | medium |
+| 4 | Framework integrity gap (count drift, missing docs) | ENH | high |
+
+### Duplicate Detection (before creating any file)
+
+For each finding, before writing a new request file:
+1. List `.viepilot/requests/*.md` (only files with `Status: new | triaged | in_progress`)
+2. For each open request, check:
+   - Title match: case-insensitive substring ≥ 70% overlap with the finding text
+   - File overlap: any file path from the finding appears in the request's `## Related → Files`
+3. If duplicate found:
+   - Append to the existing file under `## Discussion`:
+     `Re-detected by vp-audit {date}: {finding_text}`
+   - Mark as `auto_logged_deduped` (do NOT create a new file)
+4. If no duplicate: create new request file → mark as `auto_logged_new`
+
+### Create Request File
+
+Path: `.viepilot/requests/{TYPE}-{next_available_N}.md`
+
+```markdown
+# {TYPE}: {title from audit finding}
+
+## Meta
+- **ID**: {TYPE}-{N}
+- **Type**: Bug | Enhancement
+- **Status**: new
+- **Priority**: {priority from tier table above}
+- **Created**: {today}
+- **Reporter**: vp-audit (auto-logged)
+- **Assignee**: AI
+- **Source**: auto-logged by vp-audit Tier {tier}
+
+## Summary
+{audit finding text verbatim}
+
+## Details
+- **Tier**: {tier}
+- **Audit date**: {today}
+- **Affected files**: {files from finding, if any}
+
+## Acceptance Criteria
+- [ ] Fix the detected issue
+- [ ] Re-run vp-audit: this finding no longer appears
+
+## Related
+- Files: {affected files}
+- Dependencies: —
+
+## Resolution
+—
+```
+
+### Update TRACKER.md
+
+After creating all new request files, append each new ID to the TRACKER.md Decision Log:
+```
+| {today} | {TYPE}-{N} auto-logged by vp-audit Tier {tier}: {short title} | `vp-audit` | Backlog |
+```
+
+### Summary counters
+Track across all tiers:
+- `auto_logged_new`: count of new `.viepilot/requests/` files created
+- `auto_logged_deduped`: count of existing request files updated (re-detected note appended)
+
+If `auto_logged_new == 0` AND `auto_logged_deduped == 0` (no issues found): skip banner — proceed to Step 6 silently.
+
+### Post-Audit Routing Banner (ENH-070)
+
+After auto-logging completes (and `auto_logged_new > 0` OR `auto_logged_deduped > 0`), display:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ VP-AUDIT: {TOTAL_ISSUES} issue(s) found
+ Requests logged: {auto_logged_new} new, {auto_logged_deduped} updated
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+ Logged:
+   {TYPE}-{N}: {short title}     [Tier {T}]
+   {TYPE}-{N}: {short title}     [Tier {T}]
+   ...
+
+ (Re-detected on existing requests: {list IDs, or "none"})
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+**Claude Code (terminal) — REQUIRED:** Call `AskUserQuestion`:
+```
+question: "{N} gap(s) logged. What would you like to do?"
+options:
+  - label: "Plan fix phase → /vp-evolve (Recommended)"
+    description: "Create ROADMAP entry + task files for logged requests now"
+  - label: "Auto-fix now → /vp-auto --fix"
+    description: "Apply auto-fixable issues immediately (Tier 1/2 only)"
+  - label: "Skip — review later"
+    description: "Requests are saved in .viepilot/requests/ — plan when ready"
+```
+
+On selection:
+- **"Plan fix phase → /vp-evolve"**: invoke `/vp-evolve {logged-request-IDs}`
+- **"Auto-fix now → /vp-auto --fix"**: proceed to Step 6 (auto-fix mode)
+- **"Skip — review later"**: print `"Requests saved. Run /vp-evolve {IDs} when ready."` and exit
+
+**Text fallback (other adapters):**
+```
+Next actions:
+  /vp-evolve {IDs}     Plan fix phase (Recommended)
+  /vp-auto --fix       Auto-fix Tier 1/2 issues
+  skip                 Review later
+```
+
+**If `--no-autolog` was set**: skip this banner entirely; show only the plain audit report from Step 5 and proceed to Step 6.
+
+</step>
+
 <step name="fix">
 ## 6. Auto-Fix (if requested)
 

package/workflows/autonomous.md

@@ -61,6 +61,40 @@ cat .viepilot/ROADMAP.md
 Read `~/.viepilot/config.json` → `COMMUNICATION_LANG` (default: `en`).
 Use `COMMUNICATION_LANG` for all banners, control-point messages, and user-facing output in this session.
 
+### Persona Context (ENH-073)
+After loading AI-GUIDE.md and TRACKER.md, run:
+```bash
+node "$HOME/.claude/viepilot/bin/vp-tools.cjs" persona auto-switch
+node "$HOME/.claude/viepilot/bin/vp-tools.cjs" persona context
+```
+Inject output as `## User Persona` block into each task's execution context.
+Use `persona.stacks` for stack preflight matching (prefer persona stacks over generic detection).
+Silent if command unavailable or errors — do not fail the phase.
+
+### Skill Context Load (FEAT-020)
+
+After loading context files, load the project's skill decisions:
+
+```bash
+# Read PROJECT-CONTEXT.md ## Skills section
+SKILL_CONTEXT=$(grep -A 100 "^## Skills" .viepilot/PROJECT-CONTEXT.md 2>/dev/null | \
+  head -n $(grep -n "^## " .viepilot/PROJECT-CONTEXT.md | awk -F: 'NR==2{print $1}'))
+```
+
+Build `SKILL_CONTEXT_MAP` in session memory:
+- Parse `## Skills` table rows
+- For each row: extract `id`, `source`, `required` (yes/no), `phases` (comma list)
+- Load best_practices[] for each skill from global registry:
+  ```bash
+  node ~/.claude/viepilot/bin/vp-tools.cjs get-registry --id {skill-id} 2>/dev/null \
+    || node ~/.cursor/viepilot/bin/vp-tools.cjs get-registry --id {skill-id} 2>/dev/null
+  ```
+- Parse JSON output → extract `best_practices[]`
+- If command absent or returns null: `best_practices = []` — silent no-op
+- Structure: `{ required: [{id, phases: [1,2], best_practices: [...]}], optional: [...] }`
+
+**If `## Skills` section absent or empty**: silent no-op — `SKILL_CONTEXT_MAP = { required: [], optional: [] }`.
+
 ### Tag Prefix Resolution (ENH-050)
 Resolve the enriched git tag prefix once at session start. All task/phase tags use `${TAG_PREFIX}`.
 
@@ -211,6 +245,28 @@ Architecture context rule (ENH-018):
   - `N/A`: respect rationale; do not force diagram regeneration.
 - If matrix is missing, continue with explicit assumption notes in task logs.
 
+#### Skill Context Injection (FEAT-020)
+
+Before executing the task, check `SKILL_CONTEXT_MAP`:
+
+1. Extract the current task's phase number
+2. For each skill in `required`: check if current phase is in `skill.phases[]`
+3. If match: prepend `skill.best_practices[]` to the task execution context as a silent checklist:
+
+```
+[Skill context: {skill-id}]
+Best practices to apply:
+- {practice 1}
+- {practice 2}
+```
+
+4. Record in task output: `skills_applied: [{id}@{version}]`
+
+**Rules:**
+- **Never prompt the user** — decisions were locked at crystallize
+- Optional skills: included only if task file explicitly mentions matching capability keywords
+- No skill context available (empty map): continue normally — no warning
+
 #### Validate Task Contract (required before code)
 Task must include execution-grade details:
 - Objective (specific outcome)
@@ -254,6 +310,126 @@ If stack cache is missing:
 - warn and optionally run quick research
 - then continue with explicit assumptions noted in task logs
 
+#### Preflight 5.5 — Design.MD Token Injection (ENH-076)
+
+After Stack Preflight, if `design.md` exists at project root (or nearest parent directory):
+
+**Step A — Build TOKEN_MAP** (parse YAML front matter):
+- `TOKEN_MAP.colors.*` — primary, surface, accent, error, success, warning
+- `TOKEN_MAP.typography.*` — fontFamily, fontSize, fontWeight, lineHeight
+- `TOKEN_MAP.spacing.*` — base, scale
+- `TOKEN_MAP.rounded.*` — sm, md, lg, full
+
+**Step B — UI task detection** (check task title + file paths + objective text):
+```
+UI_KEYWORDS = [
+  html, css, style, component, tailwind, layout, button, card,
+  form, page, ui, frontend, color, font, typography, responsive, design
+]
+```
+If NO UI_KEYWORDS matched → skip Design.MD injection entirely for this task.
+
+**Step C — Injection levels (when UI task detected):**
+
+- **Level 1 — Silent context injection (always):**
+  Token map injected as implicit constraint in execution context.
+  AI naturally applies brand tokens when generating HTML/CSS.
+  No output shown to user.
+
+- **Level 2 — Checklist items (when task has explicit UI acceptance criteria):**
+  Auto-append to task checklist:
+  ```
+  - [ ] Primary color uses TOKEN_MAP.colors.primary (or var(--color-primary))
+  - [ ] Font family matches TOKEN_MAP.typography.fontFamily
+  - [ ] Spacing follows TOKEN_MAP.spacing.base unit
+  ```
+
+- **Level 3 — Post-task design audit (when task output includes .html or .css files):**
+  After generating output: scan for token deviations.
+  Auto-fix: obvious wrong fonts or exact hex mismatches.
+  AUQ on Claude Code terminal when judgment call required.
+  Report:
+  ```
+  🎨 Design.MD check: ✅ Colors  ✅ Typography  ⚠️ 1 spacing deviation (auto-fixed)
+  ```
+
+**Edge cases:**
+- Backend-only task (no UI_KEYWORDS) → skip entirely
+- design.md missing a token → inject only present tokens, no fail
+- Monorepo → nearest `design.md` wins (task dir → parent → project root)
+- Token conflict with Tailwind config → AUQ: Use design.md / Use Tailwind config / Update both
+
+#### Scaffold-First Gate (BUG-020)
+
+When the stack preflight identifies a **framework stack** AND the current task is a **project setup / init task** (keywords in title or objective: "set up", "initialize", "create project", "scaffold", "bootstrap", "new project", "install Laravel/Next/Nest/Rails/Django"):
+
+**Step 1 — Check for existing scaffold**: look for a framework marker file in the project root:
+
+| Framework | Marker file |
+|-----------|-------------|
+| Laravel | `artisan` |
+| Next.js | `next.config.js` or `next.config.ts` |
+| NestJS | `nest-cli.json` |
+| Rails | `config/application.rb` |
+| Django | `manage.py` |
+| Spring Boot | `pom.xml` or `build.gradle` |
+| Nuxt / Vue | `nuxt.config.ts` or `nuxt.config.js` |
+| React (CRA) | `src/index.js` or `src/index.tsx` |
+| Electron | `electron-builder.yml` |
+
+**Step 2 — If marker NOT found (fresh project)**:
+
+a. Read `## Scaffold` section from `~/.viepilot/stacks/{stack}/SUMMARY.md` — use `init_command:` and `marker_file:` fields if present (optional, takes priority over built-in table).
+
+b. If SUMMARY.md has no `## Scaffold` section, use the built-in heuristic table:
+
+| Stack | Scaffold command |
+|-------|-----------------|
+| laravel / laravel-php84 | `composer create-project laravel/laravel {name}` |
+| nextjs / nextjs-* | `npx create-next-app@latest {name}` |
+| nestjs | `npx @nestjs/cli new {name}` |
+| rails | `rails new {name}` |
+| django | `django-admin startproject {name} .` |
+| spring-boot* | `spring init --dependencies=web,data-jpa,validation {name}` |
+| nuxt / vuejs* | `npx nuxi@latest init {name}` |
+| react | `npx create-react-app {name}` |
+| electron | `npx create-electron-app {name}` |
+
+c. **Run the scaffold command** — if it exits non-zero: stop, report the error, and offer user: (a) fix environment then retry, (b) confirm project already exists, (c) skip scaffold with explicit reason logged.
+
+d. After scaffold succeeds: continue with configuration and customization tasks normally.
+
+**Step 3 — If marker IS found** (project already scaffolded): skip scaffold entirely, proceed with the task.
+
+**Never-handcraft block list** — NEVER create these files from scratch in a setup task without prior scaffold:
+- `artisan`, `composer.json` (in a Laravel/PHP context)
+- `next.config.js`, `next.config.ts`, `pages/_app.*`, `app/layout.*`
+- `nest-cli.json`, combined `tsconfig.json` + `src/main.ts` in NestJS context
+- `manage.py`, `wsgi.py`, `asgi.py`
+- `config/application.rb`, `config/routes.rb`, `Gemfile`
+- `pom.xml` or `build.gradle` with Spring Boot starters
+
+If the task's `## Paths` block contains one of these AND no scaffold has run:
+→ **⛔ Scaffold-First Gate**: "Cannot create `{file}` — run scaffold command first (BUG-020). See `docs/user/features/scaffold-first.md`."
+→ Offer: (a) run scaffold then retry, (b) confirm project already scaffolded, (c) skip gate with explicit reason in task log.
+
+#### UI Prototype Reference — populate for frontend tasks (ENH-069 Gap 3)
+
+After contract validation and **before** execution, check if the task implements a frontend component:
+
+1. Read `.viepilot/PROJECT-CONTEXT.md → ## UI Pages → Component Map` (written by crystallize Step 7)
+2. If a row exists whose `Target component` matches the task's target file:
+   - Populate the task file's `## UI Prototype Reference` section:
+     ```markdown
+     ## UI Prototype Reference
+     - Prototype: .viepilot/ui-direction/{session-id}/pages/{slug}.html
+     - Key sections: {sections extracted from the prototype during crystallize Step 1A}
+     - Component target: {target_component_path}
+     ```
+   - Log: `"UI Prototype Reference populated from UI Pages → Component Map"`
+3. During implementation: **READ the referenced prototype file BEFORE writing any component code**. The prototype is the design source — do not implement from task description alone when a prototype is bound.
+4. If no binding found in the component map: leave `## UI Prototype Reference` blank (implement from task description).
+
 #### Task start checkpoint (after doc-first gate + preflight)
 
 Only after **Validate Task Contract**, **Pre-execution documentation gate**, and **Stack Preflight** (or explicit waiver logged in the task file with reason):
@@ -407,6 +583,29 @@ Rule:
 
 When all tasks in phase are done/skipped:
 
+#### UI Coverage Gate (ENH-069 Gap 4)
+
+Before phase-level verification, run a UI stub check:
+
+1. Read `.viepilot/PROJECT-CONTEXT.md → ## UI Pages → Component Map`
+2. Filter rows where `Phase` = current phase AND `Source` is not `design_staleness` alone (i.e., rows with a real prototype file binding)
+3. For each filtered row:
+   - Check if the `Target component` file exists on disk
+   - If the file exists, apply the stub heuristic:
+     - File has fewer than 20 lines **AND** contains only routing/title markup (no real layout components, no template sections, no data fetching) → **STUB detected**
+   - If file is **missing** OR **stub detected**:
+     ```
+     ⚠️ UI Coverage Warning: "{prototype}" → "{component}" is still a stub or missing.
+     Phase cannot receive ✅ PASS with unimplemented prototype-bound components.
+     Options:
+       (a) Implement now from prototype (Recommended — continue in this phase)
+       (b) Defer to next phase (update component map row status to "deferred-phase-{N+1}" + log reason)
+       (c) Mark as design-only — no implementation required (update row status to "design-only" + log reason)
+     ```
+4. Phase PASS is **blocked** until all warnings are resolved via options (a), (b), or (c).
+   - Option (a): implement the component, then re-run stub check
+   - Option (b) or (c): clears the warning; phase may proceed to PASS
+
 1. Run phase-level verification
 2. Check phase quality gate
 3. Write SUMMARY.md using `templates/phase/SUMMARY.md` as base.