viepilot 2.22.0 → 2.41.0

package/templates/project/PROJECT-CONTEXT.md

@@ -90,3 +90,79 @@
 |---------|---------|---------|
 {{LIBRARIES}}
 </external_dependencies>
+
+## Skills
+
+> Skills registered for this project (locked at /vp-crystallize, applied by /vp-auto).
+> Populated by crystallize Step 1E when brainstorm session has ## skills_used.
+
+| Skill | Source | Required | Phases | Rationale |
+|-------|--------|----------|--------|-----------|
+| *(none yet)* | — | — | — | — |
+
+## Admin & Governance
+
+> Generated by crystallize from architect notes.md ## admin (ENH-063).
+> Update manually or re-run /vp-crystallize after updating brainstorm artifacts.
+
+| Capability | Required | Phase | Notes |
+|-----------|----------|-------|-------|
+| User management UI | — | — | — |
+| Monitoring dashboard | — | — | — |
+| Audit log | — | — | — |
+| Billing management | — | — | — |
+
+### Admin Personas
+| Persona | Key Capabilities |
+|---------|-----------------|
+| — | — |
+
+## Content Management
+
+> Generated by crystallize from architect notes.md ## content (ENH-065).
+> Update manually or re-run /vp-crystallize after updating brainstorm artifacts.
+
+| Content Type | Created By | Lifecycle | Key Fields | Phase |
+|-------------|-----------|-----------|-----------|-------|
+| — | — | — | — | — |
+
+### Media & Storage
+| Storage | CDN | Types | Max Size |
+|---------|-----|-------|----------|
+| — | — | — | — |
+
+### Localization
+| Locales | Fallback |
+|---------|---------|
+| — | — |
+
+## Admin Entity Management
+
+> Generated by crystallize from architect notes.md ## entity_mgmt (ENH-068).
+> Update manually or re-run /vp-crystallize after updating brainstorm artifacts.
+
+| Entity | CRUD Ops | Soft Delete | Bulk Actions | Audit Trail | Scope |
+|--------|----------|-------------|--------------|-------------|-------|
+| — | — | — | — | — | — |
+
+### Import / Export
+| Direction | Entities |
+|-----------|----------|
+| CSV Import | — |
+| CSV Export | — |
+
+## User Data Management
+
+> Generated by crystallize from architect notes.md ## user_data (ENH-066).
+> Update manually or re-run /vp-crystallize after updating brainstorm artifacts.
+
+| Capability | Supported | Notes |
+|-----------|-----------|-------|
+| Profile editing | — | — |
+| Notification preferences | — | — |
+| Privacy settings | — | — |
+| Data export (GDPR) | — | — |
+| Right to erasure | — | — |
+| Connected accounts | — | — |
+| Session management | — | — |
+| Two-factor authentication | — | — |

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

@@ -39,6 +39,8 @@ See `agents/` directory for full agent specifications.
 
 <process>
 
+> **AUQ preload — Claude Code adapter (ENH-059):** At session start, before any interactive prompt, call `ToolSearch` with `query: "select:AskUserQuestion"` to load the deferred schema. Required on Claude Code (terminal). Skip only if `ToolSearch` returns an error → use text fallback for that session.
+
 <step name="initialize">
 ## 1. Initialize
 
@@ -59,6 +61,30 @@ 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.
 
+### 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}`.
 
@@ -209,6 +235,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)
@@ -252,6 +300,77 @@ If stack cache is missing:
 - warn and optionally run quick research
 - then continue with explicit assumptions noted in task logs
 
+#### 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):
@@ -405,6 +524,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.