vibepro 0.1.0-alpha.0

package/skills/vibepro-diagnosis-packages/SKILL.md

@@ -0,0 +1,133 @@
+---
+name: vibepro-diagnosis-packages
+description: Use when the user asks VibePro to check UI, security, performance, architecture, PR readiness, launch readiness, or performance improvement evidence.
+---
+
+# VibePro Diagnosis Packages
+
+## Purpose
+
+Use VibePro purpose-level packages instead of guessing which low-level scanner or log to inspect. The package is the user-facing intent; the scanner set and evidence paths are VibePro's implementation detail.
+
+## Diagnosis Packages
+
+List packages first when the request is ambiguous:
+
+```bash
+vibepro check list
+```
+
+Use these mappings:
+
+- UI quality / user flow / API contract in UI calls / gesture UX: `vibepro check ui <repo> --story-id <story-id>`
+- Security / auth / exposed surface / API route contracts: `vibepro check security <repo> --story-id <story-id>`
+- Performance readiness / heavy dev / DB access risks: `vibepro check performance <repo> --story-id <story-id>`
+- Architecture / responsibility boundary: `vibepro check architecture <repo> --story-id <story-id>`
+- PR readiness: `vibepro check pr-readiness <repo> --story-id <story-id> --base <ref> --head <ref>`
+- Release or handoff readiness: `vibepro check launch-readiness <repo> --story-id <story-id>`
+- Broad inspection: `vibepro check all <repo> --story-id <story-id>`
+
+Package evidence is written to:
+
+```text
+.vibepro/checks/<pack>/<run-id>/check.json
+.vibepro/checks/<pack>/<run-id>/check.md
+```
+
+## Performance Evidence
+
+For a performance improvement claim, define Story-level metrics and record before/after runs. Do not rely only on ad hoc server logs or one-off E2E output.
+
+Define metrics:
+
+```bash
+vibepro performance define <repo> \
+  --id <story-id> \
+  --metric-id <metric-id> \
+  --user-story <text> \
+  --start-condition <text> \
+  --completion-condition <text> \
+  --intermediate-marker <marker-id> \
+  --timeout-ms <ms> \
+  --evidence-source <server_log|browser_e2e|api_log|client_marker|manual_observation> \
+  --readiness-kind <server_side|user_perceived|external_dependency|system_internal>
+```
+
+Record runs:
+
+```bash
+vibepro performance record <repo> \
+  --id <story-id> \
+  --metric-id <metric-id> \
+  --label before \
+  --status completed \
+  --duration-ms <ms> \
+  --marker <marker-id=ms> \
+  --evidence-source <type:ref:summary>
+
+vibepro performance record <repo> \
+  --id <story-id> \
+  --metric-id <metric-id> \
+  --label after \
+  --status completed \
+  --duration-ms <ms> \
+  --marker <marker-id=ms> \
+  --evidence-source <type:ref:summary>
+```
+
+Compare:
+
+```bash
+vibepro performance compare <repo> --id <story-id>
+```
+
+Run evidence is written to:
+
+```text
+.vibepro/pr/<story-id>/performance-runs/*.json
+```
+
+## Performance Guardrails
+
+- DB performance is included, but DB/server time and user-perceived time must be separate metrics.
+- `server_side` examples: DB query completed, API handler completed, tmux/server readiness.
+- `user_perceived` examples: button click to visible DOM, snapshot visible, input ready, interactive ready.
+- Do not claim user-perceived improvement from `server_log` alone.
+- Compare only runs with the same `metricId` and `completionCondition`.
+- Keep incomplete runs as evidence: `blocked`, `needs_review`, `timeout`, `auth_required`, `resource_unavailable`, `unknown`.
+- If comparison is not possible, report `改善率不明` and list the missing marker/evidence.
+
+## Network Contract Guardrails
+
+- When UI code introduces `fetch('/api/...')`, axios, or an API wrapper call, confirm the matching Next.js route exists.
+- App Router route example: `/api/foo/bar` -> `src/app/api/foo/bar/route.ts`.
+- Pages Router route example: `/api/foo/bar` -> `src/pages/api/foo/bar.ts`.
+- If a direct server function / Server Action call is replaced by an HTTP API call, treat it as a contract change requiring route, schema, auth/runtime, and network-aware E2E evidence.
+- In `vibepro verify flow`, API 4xx/5xx, API HTML responses, console/page errors, `Failed to fetch`, `Unexpected token '<'`, and visible loading failure text are Gate failures even when the UI appears to render.
+
+## UI Interactive Contract Guardrails
+
+- `vibepro check ui` must evaluate the screen at the level of visible interaction contracts, not only at the Story E2E level.
+- Clickable-looking UI must have one of these outcomes: save/mutate, visible state change, navigation, scroll/focus movement, explicit disabled state, or an explicit unfinished state such as `準備中` / `coming soon`.
+- Treat normal-looking placeholder buttons as findings when they only `console.log`, TODO, no-op, or have no `onClick` / `href` / submit / disabled / unfinished-state marker.
+- Story E2E coverage is not enough when the changed screen has additional clickable-looking controls. Require a screen-level clickable element inventory for UI-heavy changes.
+- For Playwright flow checks, click not only the main happy path but also controls that appear actionable: secondary buttons, detail links, icon buttons, tabs, menu triggers, AI/voice actions, and expandable rows.
+
+## Gesture Interaction Guardrails
+
+- For mobile-heavy UI, map UI, carousel UI, drag/drop, swipe, or touch changes, inspect the `Gesture Interaction` section from `vibepro check ui/all/launch-readiness`.
+- Treat these as review-required signals: ambiguous `touch-action`, map overlays without clear `pointer-events`, drag state not connected to click suppression, carousel surfaces without snap/threshold evidence, small gesture hit areas, and map markers without collision/zIndex/contrast/hit-area contract.
+- Static gesture findings are review candidates, not automatic proof of an app bug. Convert them to block-level evidence when Playwright/runtime probes show wrong navigation, no scroll/active-card movement, intercepted hit targets, or visible interaction failure.
+- In `vibepro verify flow`, add gesture probes for changed surfaces. Useful steps include `drag`, `touchDrag`, `expectUrlUnchanged`, `expectScrollLeftChanged`, active item change via `activeSelector` + `expectActiveChanged`, and `expectElementFromPoint`.
+- For “swipe becomes tap” regressions, verify that drag after a card/map interaction does not change URL and does update the expected scroll or active item state.
+
+## Review Checklist
+
+Before saying VibePro confirmed the result:
+
+- The package or performance command that produced the evidence is named.
+- The evidence artifact path is included.
+- The Story ID is correct.
+- p50, p90, max, sample count, and incomplete rate are shown for performance comparisons.
+- The answer separates internal readiness from user-perceived readiness.
+- UI findings include whether clickable-looking controls have an interaction contract or are explicitly disabled/unfinished.

package/skills/vibepro-human-review/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: vibepro-human-review
+description: Use when reviewing VibePro PR preparation artifacts, deciding whether to proceed, split, add evidence, waive with reason, or block.
+---
+
+# VibePro Human Review
+
+## Purpose
+
+Use this Skill when a human or AI reviewer needs to interpret VibePro PR artifacts. `pr-prepare.json` is the readiness source of truth; the review cockpit is the human control plane.
+
+## Review Order
+
+1. Read `.vibepro/pr/<story-id>/pr-prepare.json` `gate_status`.
+2. Confirm `gate_status.overall_status`, `ready_for_pr_create`, unresolved Gates, and critical unresolved Gates.
+3. If `gate_status.agent_review_instruction` is present, block human approval until the coordinator has authorization to use subagents and then has:
+   - run the listed `vibepro review prepare` commands,
+   - dispatched the generated `parallel-dispatch.md` requests to parallel subagents,
+   - closed/shutdown each review subagent after receiving its result,
+   - recorded each result with `vibepro review record` including Codex/Claude Code subagent provenance and `--agent-closed`,
+   - rerun `vibepro pr prepare` and cleared `gate:agent_review`.
+   If the coordinator runtime cannot spawn subagents, treat that as a blocker or require a human waiver decision. Do not accept manual review records as a substitute for required Codex/Claude Code subagent provenance.
+4. Open `.vibepro/pr/<story-id>/review-cockpit.html`.
+5. Read the recommended decision and reason.
+6. Check split lanes and Graphify investigation scope.
+7. For UI modernization PRs, read `.vibepro/design-modernize/<story-id>/derived-design-system.json`, `design-modernize.json`, and `ds-gate.json`. Confirm that current routes, information architecture, CTA priority, state behavior, and data dependencies are preserved unless the Story/Spec explicitly changes them.
+8. For performance-sensitive PRs, read the `Performance Evidence` section in `pr-body.md` and the JSON runs under `.vibepro/pr/<story-id>/performance-runs/`.
+9. Review next commands and confirm they use `vibepro pr create`.
+10. Copy `human-review.json`, fill the review record, and keep it as the human decision artifact.
+
+## Decision Rules
+
+- `proceed`: Use only when `gate_status.ready_for_pr_create=true`, `gate_status.overall_status=ready_for_review`, and the split-plan does not require separation.
+- `split_pr`: Use when scope is broad, repo-control files are mixed in, or split-plan recommends lanes.
+- `add_evidence`: Use when required Gates need test, typecheck, integration, E2E, or requirement evidence.
+- `waive_with_reason`: Use only with a specific reason for non-critical unresolved Gates. Critical unresolved Gates cannot be approved by reason alone.
+- `block`: Use when Story, Architecture, Spec, security, or Gate evidence is contradictory or insufficient.
+
+## Required Record
+
+Fill these fields in `human-review.json`:
+
+- `review_record.selected_decision`
+- `review_record.reviewer`
+- `review_record.reason`
+- `review_record.reviewed_at`
+- `review_record.comments` when needed
+
+## Guardrails
+
+- Do not treat `review-cockpit.html` as machine-readable truth; use the JSON sidecar.
+- Do not treat `scope.status=reviewable` as completion approval. It is PR size/scope guidance only.
+- Do not approve a PR only from the PR body. The cockpit and Gate DAG are the review control plane.
+- Do not use raw `gh pr create`; it bypasses VibePro Gate enforcement and waiver recording.
+- Do not approve with unresolved Agent Review Gate. Missing, stale, or blocking required roles mean the parallel subagent review workflow has not completed for the current git state.
+- Do not approve a `pass` review result that lacks Codex/Claude Code parallel subagent provenance and closed lifecycle evidence (`--agent-closed`) when `gate:agent_review` is required. It is a coordinator note, not verified subagent review evidence.
+- If a waiver is chosen, include the exact waiver reason in `vibepro pr create --allow-needs-verification --verification-waiver <reason>`.
+- Do not approve a performance claim when the comparison says `改善率不明` / `not_comparable`.
+- Do not accept server-side readiness as evidence for user-perceived readiness. User-perceived metrics need `browser_e2e`, `client_marker`, or `manual_observation`.
+- Check that snapshot visible, DOM visible, API completed, server ready, and interactive ready are not mixed into one completion condition.
+- Do not approve UI modernization when `ds-gate.json` is missing, has implicit fallback, or omits DS drift / component role / composition / anti-pattern checks.
+- Do not approve a generated visual direction just because it looks better. Require evidence that it preserves the existing product workflow and that the implementation follows VibePro-derived DS constraints.
+
+## Performance Evidence Review
+
+For a PR that claims speed improvement, require:
+
+- Metric definition exists in the Story `performanceMetrics[]`.
+- Runs exist under `.vibepro/pr/<story-id>/performance-runs/*.json`.
+- before and after use the same `metricId` and `completionCondition`.
+- p50, p90, max, sample count, and incomplete rate are visible.
+- `blocked`, `needs_review`, `timeout`, `auth_required`, `resource_unavailable`, or `unknown` runs are retained instead of silently dropped.
+- DB/server metrics and user-perceived metrics are separate when both matter.

package/skills/vibepro-story-refactor/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: vibepro-story-refactor
+description: Use when refactoring with VibePro so the agent follows Story -> Architecture -> Spec -> Task -> Code -> Gate -> PR instead of editing code first.
+---
+
+# VibePro Story Refactor
+
+## Purpose
+
+Use this Skill when VibePro is driving a refactor. The goal is to find and fix code defects, security risks, DRY gaps, and responsibility-boundary problems while preserving Story / Architecture / Spec consistency.
+
+## Required Workflow
+
+1. Start from a Story. If no Story exists, run `vibepro story derive` and inspect the Story map before implementing.
+2. Resolve the output language from `.vibepro/config.json` `output.language` or the explicit CLI `--language` override before manually adding or editing human-facing Story, Architecture, Spec, Task, Review, Diagnosis, Journey, or PR artifacts.
+3. Check Architecture. If the boundary, dependency direction, or responsibility split is missing, restore or add Architecture docs before changing code.
+4. Check Spec. If behavior, invariant, API, or data-flow expectations are missing, restore or add Spec docs before changing code.
+5. Use VibePro task context:
+   - `vibepro story plan <repo>`
+   - `vibepro task create <repo> --from-plan --id <story-id>`
+   - `vibepro task brief|plan|handoff <repo> --task <task-id> --id <story-id>`
+6. Use a diagnosis package when the refactor has a clear purpose:
+   - UI behavior: `vibepro check ui <repo> --story-id <story-id>`
+   - Security boundary: `vibepro check security <repo> --story-id <story-id>`
+   - Performance readiness: `vibepro check performance <repo> --story-id <story-id>`
+   - Architecture boundary: `vibepro check architecture <repo> --story-id <story-id>`
+   - Launch readiness: `vibepro check launch-readiness <repo> --story-id <story-id>`
+7. For performance refactors, define Story-level metrics before claiming improvement. Separate DB/server readiness from user-perceived readiness.
+8. For UI/UX modernization refactors, derive design constraints before changing components:
+   - run `vibepro design-modernize derive-system <repo> --id <story-id> ...`,
+   - run `vibepro design-modernize plan <repo> --id <story-id> ...`,
+   - preserve current routes, information architecture, CTA priority, state behavior, and data dependencies,
+   - treat image-generated or external design proposals as visual hypotheses, not implementation authority.
+9. Implement with focused tests. Prefer small changes tied to the task target files.
+10. Run project verification and then `vibepro pr prepare`.
+11. Read `pr-prepare.json` `gate_status` before treating the work as PR-ready.
+12. If Agent Review Gate is unresolved, it must be cleared before finalizing. Treat the generated review plan as an instruction to dispatch Codex/Claude Code subagents when the coordinator runtime provides subagent capability. Do not convert it into a user-permission wait or silently skip it.
+13. Run the VibePro parallel subagent review workflow:
+   - `vibepro review prepare <repo> --id <story-id> --stage <stage>`
+   - dispatch each role in `parallel-dispatch.md` as a separate parallel subagent review,
+   - close/shutdown each review subagent after receiving its result,
+   - `vibepro review record` each result with Codex/Claude Code provenance and lifecycle evidence (`--agent-system codex|claude_code --execution-mode parallel_subagent --agent-id <id> --agent-closed` plus thread/session/call/transcript evidence),
+   - rerun `vibepro pr prepare`.
+   If the runtime cannot spawn subagents, block or record a human waiver decision; manual review records do not satisfy required Agent Review Gate.
+14. Use the review cockpit to decide whether to proceed, split, add evidence, waive with reason, or block.
+
+## Refactor Target Criteria
+
+Prioritize candidates that VibePro surfaces as:
+
+- security boundary or authorization risk
+- duplicated query, validation, or policy shape
+- responsibility split failure
+- Story / Architecture / Spec contradiction
+- Graphify-related impact beyond changed files
+- Gate evidence missing for changed behavior
+
+## Guardrails
+
+- Do not refactor only because code looks untidy. Tie the work to Story value and evidence.
+- Do not widen scope after `task handoff` unless `pr prepare` confirms the scope remains reviewable.
+- Do not mix repo-control changes, requirement SSOT recovery, runtime behavior, and E2E gate fixes unless the split-plan allows it.
+- Do not treat `scope.status=reviewable` as completion approval. It is PR size/scope guidance only.
+- Do not merge or create a PR unless `gate_status.ready_for_pr_create=true` and `gate_status.overall_status=ready_for_review`.
+- Do not waive critical unresolved Gates with a reason alone. Critical Gates require evidence closure or a split/block decision.
+- Do not call a VibePro refactor complete while `gate:agent_review` is `needs_review`, `missing`, `stale`, `block`, or `failed`; complete the parallel subagent reviews first.
+- Do not satisfy Agent Review Gate with a manual `pass`. A passing review must include Codex or Claude Code parallel subagent provenance and closed lifecycle evidence (`--agent-closed`) so later audits can distinguish real subagent review from coordinator self-approval and closed review threads.
+- Do not treat visual redesign as a refactor unless the unchanged UX contracts are explicit. Current route, layout information hierarchy, CTA priority, state behavior, data dependencies, and accessibility expectations must be preserved or intentionally changed in Story/Spec.
+- Do not use color-token substitution as a substitute for a Design System. VibePro-derived DS should include semantic colors, state colors, component roles, CTA hierarchy, composition rules, anti-patterns, and visual hypothesis policy.
+- Do not translate machine-facing identifiers while localizing human-facing artifacts. Keep JSON keys, schema names, enums, Story IDs, Gate IDs, DAG node IDs, task IDs, role IDs, commands, file paths, package names, and external tool names unchanged.
+- Do not claim VibePro managed worktree execution exists just because Story / Spec / Architecture documents describe the planned DAG. Until `vibepro execute start` actually creates or reuses a worktree and records that state, use a normal git worktree manually when isolation is needed.
+- Do not clean dirty repository worktrees by reflexively stashing. First inspect `git status --short --branch`, unstaged diff, cached diff, and branch/HEAD reflog.
+- If a branch was advanced by external sync, merge, rebase, or another worktree, check whether the dirty state is a stale reverse diff from the previous branch commit to `HEAD`. Compare `git diff --stat <old> HEAD` with `git diff --cached --stat` / `git diff --stat` before deciding.
+- Only classify dirty state as safe to clean after proving it is already represented in `HEAD` and contains no extra user hunks. Otherwise report the exact files and keep the work intact.
+
+## Completion Check
+
+Before calling the work done:
+
+- Story / Architecture / Spec relationship is clear.
+- Tests or verification evidence exists for changed behavior.
+- Purpose-level diagnosis package evidence exists when UI, security, performance, architecture, or launch readiness was the stated goal.
+- UI modernization has `derived-design-system.json`, `design-modernize.json`, and `ds-gate.json` evidence when the Story changes design/UX.
+- Performance improvements have comparable before/after evidence, or the PR explicitly says improvement rate is unknown and why.
+- `pr-prepare.json` `gate_status.ready_for_pr_create` is true.
+- `gate:agent_review` has passed when VibePro required parallel subagent review.
+- `review-cockpit.html` has a clear recommended decision.
+- `human-review.json` can record the human decision.
+- `vibepro pr create` is the PR creation path.

package/skills/vibepro-workflow/SKILL.md

@@ -0,0 +1,139 @@
+---
+name: vibepro-workflow
+description: Use when working with VibePro CLI, Graphify, Story diagnosis, task planning, PR preparation, Gate evidence, or VibePro review artifacts.
+---
+
+# VibePro Workflow
+
+## Purpose
+
+Use VibePro as a Story / Architecture / Spec / Graphify / Gate control plane. The CLI creates evidence; this Skill tells the agent how to use that evidence without skipping the intended order.
+
+## Operating Order
+
+1. Confirm the target repository and current branch.
+2. Initialize only when needed: `vibepro init <repo> --language ja`.
+3. Before manually adding or editing human-facing VibePro artifacts, resolve the output language from `.vibepro/config.json` `output.language` or the explicit CLI `--language` override.
+4. Select or create the Story before diagnosing or changing code.
+5. Import Graphify context before impact-sensitive work: `vibepro graph <repo> --run-graphify`.
+6. Diagnose and derive the repo context:
+   - `vibepro story diagnose <repo> --id <story-id> --run-graphify`
+   - `vibepro story derive <repo> --run-graphify`
+   - `vibepro story map <repo>`
+7. When the user asks for a purpose-level check, use diagnosis packages instead of guessing the scanner set:
+   - `vibepro check list`
+   - `vibepro check ui <repo>`
+   - `vibepro check security <repo>`
+   - `vibepro check performance <repo>`
+   - `vibepro check architecture <repo>`
+   - `vibepro check pr-readiness <repo> --base <ref> --head <ref>`
+   - `vibepro check launch-readiness <repo>`
+8. For performance improvement stories, define and record Story-level performance evidence before claiming speedups:
+   - `vibepro performance define <repo> --id <story-id> --metric-id <id> --user-story <text> --start-condition <text> --completion-condition <text> --evidence-source <type>`
+   - `vibepro performance record <repo> --id <story-id> --metric-id <id> --label before|after --status completed --duration-ms <ms> --evidence-source <type:ref:summary>`
+   - `vibepro performance compare <repo> --id <story-id>`
+9. For existing UI modernization, derive the product-local Design System before screen implementation:
+   - Run Graphify first when available: `vibepro graph <repo> --run-graphify`.
+   - Run `vibepro design-system derive <repo> --id <ds-id> --product <name> --routes <csv> --brief <text> --from-code`.
+   - Review `.vibepro/design-system/<ds-id>/evidence-coverage.json` and `ds-gate.json` before accepting the DS as an implementation constraint.
+   - Treat `.vibepro/design-system/<ds-id>/design-system.json`, `semantic-tokens.json`, `component-roles.json`, `component-states.json`, `screen-patterns.json`, `cta-policy.json`, `density-policy.json`, `navigation-policy.json`, `anti-patterns.json`, and `implementation-mapping.json` as product-local DS evidence.
+10. For screen-level UI modernization, create the story-specific design decision space before screen implementation:
+   - `vibepro design-modernize derive-system <repo> --id <story-id> --product <name> --routes <csv> --brief <text>`
+   - `vibepro design-modernize plan <repo> --id <story-id> --product <name> --routes <csv> --base-url <url>`
+   - Treat `.vibepro/design-modernize/<story-id>/derived-design-system.json`, `design-modernize.json`, and `ds-gate.json` as implementation constraints.
+   - External Design System bundles, screenshots, and image-generated ideas are visual hypotheses. The VibePro-derived Design System, current UI evidence, Story/Spec, and Gate DAG remain authoritative.
+11. Plan work from VibePro evidence: `vibepro story plan <repo>`.
+12. Create task context before implementation: `vibepro task create <repo> --from-plan --id <story-id>`.
+13. After code changes, run `vibepro pr prepare <repo> --story-id <story-id>`.
+14. Read `.vibepro/pr/<story-id>/pr-prepare.json` `gate_status` before treating work as PR-ready.
+15. If `gate_status.agent_review_instruction` is present, Agent Review is mandatory. Treat the generated review plan as an instruction to dispatch Codex/Claude Code subagents when the coordinator runtime provides subagent capability. Do not convert it into a user-permission wait or silently skip it.
+16. Run parallel subagent review:
+   - Run each listed `vibepro review prepare <repo> --id <story-id> --stage <stage>`.
+   - Open the generated `.vibepro/reviews/<story-id>/<stage>/parallel-dispatch.md`.
+   - Start the listed Codex/Claude Code subagents in parallel, one role per subagent.
+   - After each subagent returns, close/shutdown that review subagent before recording the result. Do not leave review subagents running.
+   - Record every result with `vibepro review record` and include subagent provenance plus closed lifecycle evidence:
+     - Codex: `--agent-system codex --execution-mode parallel_subagent --agent-id <spawned-agent-id> --agent-closed` plus `--agent-thread-id` or `--agent-call-id` when available.
+     - Claude Code: `--agent-system claude_code --execution-mode parallel_subagent --agent-id <task-or-subagent-id> --agent-closed` plus `--agent-session-id` or `--agent-transcript` when available.
+   - Rerun `vibepro pr prepare` and continue only after `gate:agent_review` passes.
+   - If the runtime cannot spawn subagents, block or record a human waiver decision; manual review records do not satisfy required Agent Review Gate.
+17. Open `review-cockpit.html` first, then deep-dive into `gate-dag.html`, `split-plan.html`, and `pr-body.md`.
+18. Use `vibepro pr create`; do not bypass VibePro with raw `gh pr create`.
+
+## Human Artifact Language
+
+- Human-facing Story, Journey, Architecture, Spec, Task, Review, Diagnosis, and PR artifacts should be written in the resolved output language.
+- Preserve machine-facing identifiers exactly: JSON keys, schema names, enums, Story IDs, Gate IDs, DAG node IDs, task IDs, role IDs, commands, file paths, package names, and external tool names.
+- Preserve user-provided text and external evidence text unless the artifact explicitly asks for translation or localization.
+- When CLI-generated artifacts are incomplete and the agent fills them manually, match the repository language policy instead of defaulting to English.
+
+## Managed Worktree Status
+
+- Recent VibePro Story / Spec / Architecture documents define a future managed worktree Execution DAG, but this is not evidence that the installed CLI already creates, reuses, or enforces managed worktrees.
+- Do not claim VibePro created a worktree unless a real command result records that state.
+- Until `vibepro execute start` actually reports managed worktree creation or reuse, create normal git worktrees manually when isolation is needed, and keep implementation, verification, review, PR preparation, and PR creation in that isolated worktree.
+- When a future VibePro CLI reports managed worktree state, prefer that state and run the rest of the VibePro flow from the reported worktree.
+
+## Guardrails
+
+- Do not treat VibePro diagnosis as truth by itself. Verify with code, tests, runtime logs, or product behavior.
+- Do not patch graph-sensitive runtime, auth, data, or UI state-machine code before checking Graphify impact.
+- Do not skip Story -> Architecture -> Spec ordering when the task is a refactor.
+- Do not treat `scope.status=reviewable` as completion approval. It is PR size/scope guidance only.
+- Do not ignore unresolved Gates. Add evidence, split the PR, block, or record a waiver reason.
+- Do not waive critical unresolved Gates with a reason alone. Critical Gates require evidence closure or a split/block decision.
+- Do not treat Agent Review Gate as optional. When it is unresolved, the coordinator must prepare, dispatch, record, and rerun the VibePro review flow before calling the work complete.
+- Do not record a passing Agent Review result without Codex/Claude Code parallel subagent provenance and closed lifecycle evidence (`--agent-closed`). Manual `pass` records are audit notes, not enough to satisfy `gate:agent_review`.
+- Keep JSON artifacts as the machine-readable source of truth. HTML is the human control plane.
+- Do not claim user-perceived performance improvement from server logs alone. Use a separate `user_perceived` metric backed by `browser_e2e`, `client_marker`, or `manual_observation`.
+- Do not mix server readiness, API completion, DOM visibility, snapshot visibility, and interactive readiness as the same completion condition. Define them as separate metrics.
+- Do not treat type-check or a superficially rendered UI as enough when UI code introduces `/api/...` calls. Network Contract Gate requires matching Next.js routes and network-aware flow evidence for API 4xx/5xx.
+- Do not treat Story-level E2E existence as enough for UI-heavy changes. Clickable-looking controls on the changed screen need an interaction contract: save/mutate, visible state change, navigation, scroll/focus, disabled, or explicit unfinished state.
+- Do not skip `design-system derive` for existing products that need a reusable DS. Screen-level modernization should not invent product semantics when current routes, CTAs, states, style tokens, or Graphify evidence can define them.
+- Do not treat `.vibepro/design-system/<ds-id>/design-system.json` as complete unless `evidence-coverage.json` and `ds-gate.json` are reviewed. Missing Graphify/style evidence may be a warning; missing semantic roles or implicit fallback is a design gate problem.
+- Do not implement a generated design proposal directly. For UI modernization, first verify the current route, information architecture, CTA priority, state behavior, and data dependencies against the Derived Design System and `ds-gate.json`.
+- Do not let `ds-gate.json` fall back implicitly. If DS drift, component role, composition, visual hypothesis, or anti-pattern clauses are missing, treat the design-modernize evidence as incomplete.
+
+## Git / Worktree Dirty Guardrails
+
+- Do not use `git stash`, `git restore`, `git reset`, or checkout changes as the first response to a dirty repository worktree. First classify the dirty state.
+- Before cleaning dirty state, record:
+  - `git status --short --branch`
+  - `git diff --name-status`
+  - `git diff --cached --name-status`
+  - `git diff --stat`
+  - `git diff --cached --stat`
+  - `git reflog --date=iso -8 HEAD`
+  - `git reflog --date=iso -8 <current-branch>`
+- If a checked-out branch moved via an external sync, merge, rebase, or another worktree, verify whether the dirty diff is a stale reverse diff before treating it as user work.
+- A stale reverse diff is likely when the branch reflog advanced from an old commit to `HEAD`, while `git diff --cached` or `git diff` is exactly the inverse of the commits between that old commit and `HEAD`.
+- Prove this before cleanup by comparing the dirty diff with the commit range, for example:
+  - `git diff --stat <old-commit> HEAD`
+  - `git diff --stat HEAD <old-commit>`
+  - `git diff --name-status <old-commit> HEAD`
+  - `git diff --name-status HEAD <old-commit>`
+- If the dirty state is a proven stale reverse diff, say so explicitly and then synchronize the worktree/index to `HEAD` with the least destructive command that resolves the observed state. Do not preserve it as a stash unless the user asks for archival.
+- If the dirty state contains files or hunks that do not match the stale reverse diff, treat them as possible user work and do not clean them without reporting the exact files and asking for direction when needed.
+
+## Key Artifacts
+
+- `.vibepro/stories/story-map.md`: repo Story map for human review.
+- `.vibepro/stories/story-plan.md`: candidate work items.
+- `.vibepro/pr/<story-id>/pr-prepare.json`: PR readiness source of truth; check `gate_status`.
+- `.vibepro/pr/<story-id>/review-cockpit.html`: first screen for human decision.
+- `.vibepro/pr/<story-id>/human-review.json`: machine-readable human decision template.
+- `.vibepro/pr/<story-id>/gate-dag.html`: Gate dependency view.
+- `.vibepro/pr/<story-id>/split-plan.html`: split lanes and Graphify investigation scope.
+- `.vibepro/reviews/<story-id>/<stage>/parallel-dispatch.md`: required parallel subagent dispatch instructions when Agent Review Gate is unresolved.
+- `.vibepro/checks/<pack>/<run-id>/check.json`: purpose-level diagnosis package evidence.
+- `.vibepro/checks/<pack>/<run-id>/check.md`: human-readable diagnosis package report.
+- `.vibepro/checks/ui/<run-id>/check.json`: UI check evidence, including `flow_design.interactive_contract_hits`.
+- `.vibepro/pr/<story-id>/performance-runs/*.json`: Story-level performance evidence runs.
+- `.vibepro/design-system/<ds-id>/design-system.json`: product-local Design System derived from current evidence.
+- `.vibepro/design-system/<ds-id>/evidence-coverage.json`: route/style/Graphify/semantic coverage findings for the native DS.
+- `.vibepro/design-system/<ds-id>/ds-gate.json`: explicit DS gate with fallback disabled.
+- `.vibepro/design-system/<ds-id>/implementation-mapping.json`: route/component/file mapping for implementation handoff.
+- `.vibepro/design-modernize/<story-id>/design-system-derivation.json`: product semantics and Derived Design System derivation.
+- `.vibepro/design-modernize/<story-id>/derived-design-system.json`: semantic tokens, component roles, CTA hierarchy, anti-patterns, and visual hypothesis policy.
+- `.vibepro/design-modernize/<story-id>/design-modernize.json`: screen modernization plan and Design Quality DAG.
+- `.vibepro/design-modernize/<story-id>/ds-gate.json`: explicit DS drift and UX regression gate clauses.