dv-design

name	dv-design
description	Da Vinci design direct route skill for Codex.

Da Vinci Design

Use this direct $dv-design skill for the request.

Action: design

Shared hook and lifecycle boundary:

• treat da-vinci workflow-status --project <path> [--change <id>] --json and da-vinci next-step --project <path> [--change <id>] as the single routing brain; do not invent a separate routing or readiness engine
• treat .da-vinci/state/change-state.json, .da-vinci/state/change-seq.json, and .da-vinci/state/change-lifecycle.lock as command-owned lifecycle surfaces, not prompt-owned heuristics
• after those route checks confirm $dv-design, use da-vinci design-recommendation --project <path> --change <id> --refresh --json while .da-vinci/DESIGN.md is still missing; run the full da-vinci hook-bridge --project <path> [--change <id>] --trigger-kind stage:start --stage design --json preparation chain only after design-confirm --confirm has materialized canonical design truth
• hook-bridge is bounded to stage:start preflight only; it must not replace manual promotion, route selection, or lifecycle commands
• treat hook requires as same-trigger dependencies only; required consumers block when a dependency is missing, disabled, stale, failed, returns WARN, or is ordered after the consumer, and optional consumers warn and skip execution
• preserve policy order as execution order; do not topologically sort or auto-reorder hook bindings
• treat da-vinci hook-status and workflow-status as read-only hook diagnostics for local binding identity, project declaration/default provenance, snapshot status, role metadata, latest-versus-effective run interpretation, and hookRecovery; they must never become route authority or a second workflow engine
• if .da-vinci/changes/<change-id>/hook-policy.system.json is missing, keep the story hook-local: surface hookRecovery.status = recovery_required with hookRecovery.reason = system_snapshot_missing instead of inventing an empty-policy fallback or lifecycle repair
• treat .da-vinci/changes/<change-id>/project-profile.system.json as a separate frozen change-local platform/locale/app-technology contract; hook or route diagnostics may reference it, but active changes must not live-read .da-vinci/project-profile.json
• treat system.project-profile.ensure as a check-only stage:start:breakdown validation seam: it may refresh .da-vinci/changes/<change-id>/project-profile.system.json only after canonical .da-vinci/project-profile.json is confirmed; profile collection remains owned by da-vinci dv-change-new [change title] / $dv-change-new before lifecycle creation
• treat .da-vinci/design-source-profile.json as the canonical project-level design-source selector; repo-owned .da-vinci/design-sources/awesome-design-md/*/DESIGN.md snapshots stay bounded advisory reference input and sibling tokens.system.json stays derived import evidence rather than route truth
• treat .da-vinci/changes/<change-id>/candidates/product-prototype.md and .da-vinci/changes/<change-id>/candidates/copy-catalog.json as generated promotion inputs; the requirement export hook may refresh them, but candidates alone never satisfy design entry
• treat .da-vinci/changes/<change-id>/requirement-truth-promotion.system.json as read-only paired-promotion evidence for accepted breakdown_to_design
• treat .da-vinci/changes/<change-id>/product-prototype.md and .da-vinci/changes/<change-id>/copy-catalog.json as promoted canonical change-local requirement-side design-entry companions; hook or route diagnostics may reference them, but only paired promotion may update them
• treat .da-vinci/changes/<change-id>/page-design-contracts.json and .da-vinci/changes/<change-id>/icon-map.json as canonical change-local design-entry contracts; hook or route diagnostics may reference them, but they are not hook-owned artifacts
• keep one canonical consumer chain for design-entry consumers: promoted product/copy truth -> page design contracts -> icon map
• when .da-vinci/design-source-profile.json is missing, treat confirmed .da-vinci/DESIGN.md as the project-local design-source baseline only when it stays rich and complete
• during breakdown, .da-vinci/DESIGN.md is read-only advisory if it already exists; do not create .da-vinci/DESIGN.md during breakdown, and leave .da-vinci/DESIGN.md missing until the design route materializes it through design-confirm --confirm
• treat .da-vinci/changes/<change-id>/source-digests.system.json as design-entry source freshness evidence; stale canonical artifacts block design entry instead of being auto-regenerated as recovery
• treat .da-vinci/changes/<change-id>/icon-supply.system.json as derived change-local icon-catalog readiness evidence; hook or route diagnostics may reference it, but it is not editable route truth
• when the shared design_to_tasks gate is rendered, keep design-entry readiness plus parallel Design Review, Icon Verification, and Copy Verification on the same fail-closed seam; WARN remains pending until explicit dv-handoff acceptance
• keep structured UI quality checks on that same seam: uiQualityScore, first-screen structured .dvp metadata, the density linter, anti-AI-look issue ids, visible text copyKey / locale, and icon iconId / qualifiedName bindings must not create a new route or workflow stage
• keep the task/build/conformance spine on existing seams: build-packet.system.json artifactSpine, derived tasks.index.json contractRefs, and implementation-conformance.system.json are replay evidence for task, build, and verify promotion, not new workflow stages or canonical source truth
• when build_to_verify replay sees missing, stale, or BLOCK implementation conformance, keep verification promotion blocked instead of treating the gap as advisory guidance
• treat .da-vinci/changes/<change-id>/quality-profile.system.json as a separate frozen change-local quality contract; hook or route diagnostics may reference it, but active changes must not live-read .da-vinci/quality-profile.json or .da-vinci/quality-profiles/*.json
• treat .da-vinci/changes/<change-id>/prd.md as a read-only derived summary owned by system stage:start:design; do not promote it to requirement truth or regenerate it from requirement handoff
• if hook-status --json is missing or invalid, keep recovery bounded to hook_status_payload_invalid or hook_status_payload_missing; hook policy mutation must wait until payload trust returns
• keep lifecycle commands explicit: da-vinci dv-change-new [change title], da-vinci dv-change-close, and da-vinci dv-change-recover <change-id> [--confirm]
• if lifecycle repair is required, do not invent a switch-change route; point the operator to $dv-repair as the maintained repair surface for abnormal lifecycle recovery

Reply contract:

• after route work, rerun da-vinci workflow-status --project <path> [--change <id>] --json and da-vinci next-step --project <path> [--change <id>] --json so the final report reflects current truth
• keep the reply in the standard Da Vinci operator format instead of a plain work log
• summarize current truth first: active change id, title, lifecycle status, derived stage, pending handoff, and blocker or repair status
• when blocked, surface Root cause: ... before any maintained next command
• include Execution detail: ... only when the underlying CLI result or gate clarifies the blocker without replacing the maintained route
• keep Evidence refs: ... high-signal on terminal-style output; richer JSON payloads may keep fuller ref lists
• preserve Failures:, Warnings:, and Notes: when present
• for $dv-design before canonical .da-vinci/DESIGN.md exists: after design-recommendation returns candidates, treat missing .da-vinci/DESIGN.md, .da-vinci/design-source-profile.json, .da-vinci/brand-assets.json, page contracts, icon supply/map, empty .dvp, screenshots, and review evidence as expected pre-confirm materialization gaps; summarize them as Awaiting candidate confirmation instead of abnormal Failures, ask the user for one candidate id, and do not continue to broad rendering until explicit user confirmation
• when the user provides a legal candidate id in the current design turn, preview with da-vinci design-confirm --project <path> --change <id> --candidate <id> --refresh --json, then materialize with --confirm --refresh unless preview, brand, or visual gates block; do not treat the agent's recommendation or default candidate as user confirmation; only after successful confirmation run da-vinci hook-bridge --project <path> [--change <id>] --trigger-kind stage:start --stage design --json
• if exactly one legal next action exists, emit Next command: ...
• if pendingHandoff.command or the top recommended legal next command is $dv-handoff because review is still missing or WARN needs explicit acceptance, emit Next command: $dv-handoff instead of skipping directly to the downstream stage route
• if multiple legal next actions exist, group them as Recommended, Also valid, Mandatory rollback, and Rollback
• when the legal next action is another maintained Da Vinci surface, restate it using this platform's wrapper names: $dv-continue, $dv-code-context, $dv-change-new, $dv-change-close, $dv-change-recover, $dv-breakdown, $dv-handoff, $dv-design, $dv-tasks, $dv-build, $dv-verify, $dv-repair, $dv-illustration-list, $dv-illustration-prompt, $dv-illustration-add
• do not recommend raw CLI or /prompts:* actions as the next command; mention raw CLI only as execution detail inside the current maintained surface
• do not auto-invoke the next command from inside $dv-design

Output should move the work toward:

• .da-vinci/changes/<change-id>/design.md
• .da-vinci/changes/<change-id>/visual-assets.json
• .da-vinci/changes/<change-id>/ui-design.md
• .da-vinci/changes/<change-id>/ui-bindings.json

Contract inputs for this route:

• .da-vinci/DESIGN.md is the canonical project-level design truth and new materialized baselines should include Design Provenance, Brand Assets, Visual Assets, and Iconography; Brand Assets and Visual Assets are generated design context, not unconditional gates, but configured required assets can block design entry when inspection proves they are missing or invalid.
• .da-vinci/brand-assets.json is the optional canonical project-level brand asset manifest. $dv-design owns its concise interaction and writes; brand-owned complex artwork such as store listing art and social share covers may carry generation metadata there, stage:start:design hooks must not ask brand questions, and missing or unconfirmed manifests are enforced by the confirmation-time CLI hard gate rather than by stage-start hooks.
• .da-vinci/changes/<change-id>/visual-assets.json is the optional canonical change-local manifest for complex raster/bitmap visuals that .dvp canvas primitives and icon libraries should not fake: activity/campaign art, hero illustrations, onboarding or empty-state illustrations, store/social artwork, mascots, photo-like scenes, textures, 3D/isometric scenes, and other multi-object narrative graphics. Store generated files under .da-vinci/changes/<change-id>/assets/visual/ and prompt drafts under .da-vinci/changes/<change-id>/assets/visual/prompts/; each pending asset should carry category/template/style tags/subject tags/promptPath/promptDigest so another runtime can continue it.
• .da-vinci/DA-VINCI.md is optional narrow project config; the only approved machine-parsed section is ## User Hook Bindings.
• project-level hook declarations/defaults under .da-vinci/hooks/handlers/*.json and .da-vinci/hooks/defaults/*.json stay bounded to shipped cli / agent handlers and freeze into .da-vinci/changes/<change-id>/hook-policy.system.json when the change is created.
• ordinary dv-design is non-destructive for canonical project truth; system.design.recommend remains advisory until the operator inspects da-vinci design-recommendation --project <path> --change <id>
• when .da-vinci/DESIGN.md is missing, inspect current approved requirement truth (proposal.md, specs/*/spec.md, frozen .da-vinci/changes/<change-id>/project-profile.system.json, canonical .da-vinci/changes/<change-id>/product-prototype.md, canonical .da-vinci/changes/<change-id>/copy-catalog.json, canonical .da-vinci/brand-assets.json when present, canonical .da-vinci/changes/<change-id>/visual-assets.json when present, canonical .da-vinci/design-source-profile.json when present, design-brief.md, and regenerated prd.md when present) plus project-level advisory code context (.da-vinci/code-context/index.json` when present, otherwise targeted live code scans) before broad runtime rendering
• before design-confirm --confirm, before design-session begin, and before broad rendering, if .da-vinci/brand-assets.json is missing, draft, unconfirmed, invalid, or materially incomplete, run a concise brand-assets pass in this route through da-vinci brand-assets-prepare --project <path> --change <id> [--confirm] --json: scan common repo roots such as prd/assets/brand, assets/brand, public/brand, and src/assets/brand; ask only for sourceMode, selected asset families, expression mode, required variants, and priority generation families when the default scan is not acceptable. Do not handwrite .da-vinci/brand-assets.json; the CLI must write it through writeBrandAssets() so assetFamilies stays a string array and entries stay under assets. Do not start broad rendering with missing, draft, unconfirmed, invalid, or platform-incomplete brand assets. design-confirm --confirm and design-rebaseline --confirm are CLI hard gates and block with brand_assets_collection_required until the manifest is explicitly confirmed, or confirmed contract-only when no brand assets are needed. For packaged app targets such as Android, do not confirm an empty contract-only manifest: select or generate the platform brand families required by the frozen project profile, including app-launcher-icon, splash-opening-mark, and store-listing-art when applicable.
• .da-vinci/brand-assets.json must obey the Da Vinci brand-assets schema: sourceMode is only use-existing-assets, generate-missing-assets, or contract-only; assetFamilies / entry family values are only wordmark-logo, logo-mark, app-launcher-icon, splash-opening-mark, store-listing-art, favicon-web-icon, social-share-cover, partner-integration-badge, or other; BRAND_ASSET_VARIANTS are only light, dark, monochrome, horizontal, vertical, and square; BRAND_ASSET_ENTRY_STATUSES are only existing, planned, missing, needs-provider, needs-user-asset, placeholder-allowed, generating, generated, approved, rejected, and not-needed; entry source is only repo-scan, user-confirmed, or manual-entry; asset entries use id, family, variants, status, source, path, description, generation, placeholder, surfaceScopes, usageRole, and needsGeneration. Put generated outputs in generation.outputPath; use wordmark-logo or logo-mark for logos instead of inventing brand-logo; do not invent mixed, existing, derive, or generate as source values, Android density variants such as mdpi/xhdpi, placeholder fields such as sourceAssetId/method, or statuses such as required.
• before final candidate confirmation, run a concise visual-assets pass when requirements or page contracts mention complex visuals. Write .da-vinci/changes/<change-id>/visual-assets.json with the Da Vinci manifest schema: top-level status is draft or confirmed, and asset entries live under assets (not visualAssetRequirements) with assetId, surfaceKey, kind (hero-illustration, empty-state-illustration, onboarding-illustration, store-listing-art, social-share-cover, brand-illustration, background-artwork, decorative-artwork, product-scene, mascot, or other), category, required, sourceMode, status, promptPath, promptDigest, negativePrompt, and generation.promptReviewStatus when generation is intended. placeholder-allowed is preview-only for required with-complex-visual slots and cannot satisfy design_to_tasks; required generated/imported complex visuals must become approved with an output path before handoff. design-confirm --confirm and design-rebaseline --confirm enforce detected or configured required complex visual assets as a CLI hard gate with visual_assets_collection_required. Persist only asset need/status/output/prompt metadata in .da-vinci/changes/<change-id>/visual-assets.json; runtime provider availability is checked at command time and never persisted.
• when .da-vinci/DESIGN.md is missing, surface 2-3 candidate archetypes through da-vinci design-recommendation --project <path> --change <id>, ask only the smallest clarification set that materially changes the visual result, and wait for explicit user confirmation before materializing canonical design truth
• design-recommendation-snapshot is the bounded Design Engine v2 packet: qualityProfileId, upstreamCorpusRefs, antiPatterns, responsiveRules, stateSurfaceRequirements, chartSystem, contentTone, trustModules, proofModules, designChecklist, importedCandidateArchetypes, paletteCandidates, typographyPairs, layoutPatterns, and bounded importedCorpus stay additive on the advisory artifact
• repo-owned compiled imported corpus assets under lib/design-corpus/*/compiled/*.json feed that packet through a local adapter only; markdown design-reference catalogs remain separate advisory inputs, canonical source selection lives in .da-vinci/design-source-profile.json, repo-owned .da-vinci/design-sources/awesome-design-md/<source-id>/DESIGN.md snapshots stay bounded advisory input, sibling tokens.system.json stays read-only derived import evidence, and runtime must not live-fetch upstream repos or plugin installs
• keep anti-clone boundaries explicit: absorb pacing, density, and token cues from imported references, but do not copy logos, trademarks, or direct brand identifiers into canonical project truth
• the normal write path after any brand-assets or visual-assets manifest write is da-vinci design-confirm --project <path> --change <id> --candidate <id> --refresh for preview plus --confirm --refresh to Confirm and materialize
• if .da-vinci/DESIGN.md is already complete, do not overwrite it from ordinary design work; route to da-vinci design-rebaseline --project <path> --change <id> --candidate <id> [--confirm] instead
• after design-confirm --confirm, let the fixed stage:start:design preparation chain refresh .da-vinci/changes/<change-id>/prd.md, .da-vinci/changes/<change-id>/icon-supply.system.json, .da-vinci/changes/<change-id>/page-design-contracts.json, and .da-vinci/changes/<change-id>/icon-map.json
• before broad rendering, read the full stack in order: project-profile.system.json, product-prototype.md, copy-catalog.json, .da-vinci/DESIGN.md, .da-vinci/brand-assets.json, visual-assets.json, .da-vinci/design-source-profile.json, page-design-contracts.json, icon-supply.system.json, icon-map.json
• emit one Surface Design Brief per surface with Product Intent, Information Hierarchy, Layout Contract, Visual System Constraints, Icon Contract, and Copy Contract; include Brand Asset Contract only when .da-vinci/brand-assets.json is actionable and Visual Asset Contract when visual assets declare required assets or complex visual assets are required
• design-confirm / design-rebaseline keep .da-vinci/DESIGN.md confirm-only by materializing selected provenance such as qualityProfileId, upstreamCorpusRefs, designChecklist refs, Recommendation rationale, Reference corpus, project-profile context, selected brand-assets summary, selected visual-assets summary, and selected design-source cues into token-rich design-system sections, not the full advisory packet or raw imported corpus bundle payload
• use lucide for UI icons and simple-icons for third-party brand/logo icons; do not use icon libraries or .dvp canvas primitives as substitutes for complex artwork that belongs in visual-assets.json or brand-assets.json
• do not start broad da-vinci-pencli page rendering until one candidate is explicitly confirmed and materialized into .da-vinci/DESIGN.md

Before broad design work when shell access is available:

• if the primary recommended route is not $dv-design, stop and continue from that route instead of forcing design

Use the registered .dvp structure as the design source when available. If design reveals a new behavior, acceptance condition, state, or case that is not already approved in requirements, stop broad design work and route back to $dv-breakdown so .da-vinci/changes/<change-id>/proposal.md and .da-vinci/changes/<change-id>/specs/<capability>/spec.md are updated first. If design only adds more approved state or variant surfaces, stay in design, record the new mappings in .da-vinci/changes/<change-id>/ui-design.md / .da-vinci/changes/<change-id>/ui-bindings.json, and require explicit requirement page plus state/variant back-references before handoff. Before non-trivial batch_design calls, preflight the da-vinci-pencli operations when shell access is available. If the same anchor surface rolls back twice, switch to micro-batches of 6 or fewer operations until a clean schema-safe pass succeeds. Require the current da-vinci-pencli design runtime sequence on autonomous runs:

1. Confirm da-vinci workflow-status --project <path> [--change <id>] --json and da-vinci next-step --project <path> [--change <id>] --json still route to $dv-design.
2. Run da-vinci design-runtime-check --project <path> --change <id> --json.
3. Run da-vinci design-source-ensure --project <path> --json.
4. If .da-vinci/DESIGN.md is missing, run da-vinci design-recommendation --project <path> --change <id> --refresh --json, complete the brand-assets and visual-assets passes above, preview with da-vinci design-confirm --project <path> --change <id> --candidate <id> --refresh --json, then materialize with --confirm --refresh.
5. After .da-vinci/DESIGN.md exists, run da-vinci icon-sync --project <path> --json so project icon catalogs exist before icon supply and icon map hooks.
6. Run da-vinci hook-bridge --project <path> --change <id> --trigger-kind stage:start --stage design --json to refresh PRD, icon supply, page contracts, and icon map.
7. Run da-vinci design-session begin --project <path> --change <id> --json.
8. Run da-vinci design-direction-apply --project <path> --change <id> --surface <key> --json for each required surface to apply the selected PenCLI direction from designDirection.
9. Run da-vinci design-system-materialize --project <path> --change <id> --json.
10. Run da-vinci design-composition-materialize --project <path> --change <id> --surface <key> --json for each required surface; it must delegate PenCLI composition plan plus either dvpui materialize for supported structured recipes or composition apply for uncovered recipes, and write .da-vinci/changes/<change-id>/composition-plan.<surface>.json.
11. Run da-vinci design-layout-audit --project <path> --root-id <rootNodeId> --json for each required surface root after the skeleton exists.
12. If the layout audit returns BLOCK on deterministic spacing/alignment/overflow issues, run da-vinci design-layout-fix --project <path> --root-id <rootNodeId> --json, then rerun layout audit.
13. Run da-vinci brand-assets-materialize --project <path> --json.
14. Run da-vinci icon-system-materialize --project <path> --change <id> --json.
15. Run da-vinci visual-assets-status --project <path> --change <id> --json.
16. Run da-vinci visual-assets-verify-requirements --project <path> --change <id> --surface <key> --json for each required surface.
17. Run da-vinci design-craft-audit --project <path> --root-id <rootNodeId> --kit <kit> --json before export.
18. Run da-vinci design-export --project <path> --change <id> --surface <key> --root-id <rootNodeId> --json for each required surface after the actual non-empty surface root exists; it must produce PNG, metadata, and visual review evidence.
19. Run da-vinci design-artifacts-materialize --project <path> --change <id> --surface <key> --root-id <rootNodeId> --json for each exported surface to refresh .da-vinci/changes/<change-id>/design.md, .da-vinci/changes/<change-id>/ui-bindings.json, and .da-vinci/changes/<change-id>/ui-design.md. The command may create a missing/bootstrap .da-vinci/page-map.md, but it must preserve an existing requirement page map so design materialization does not invalidate an accepted breakdown handoff. ui-bindings.json must use the da-vinci-pencli schema: top-level sourceHash, and per-surface rootNodeId, exportPath, and metadataPath; do not use opRootId.
20. Run da-vinci design-runtime-gate --project <path> --change <id> --json.
21. Run da-vinci design-session persist --project <path> --change <id> --json and da-vinci design-session end --project <path> --change <id> --json.
22. Stop and tell the operator to run $dv-handoff manually. Before the first runtime edit, require da-vinci design-session begin --project <path> --change <id> --json so the registered project-local .dvp is seeded and locked before editing starts. When multiple .dvp sources exist (for example an external backup), choose or update the canonical registry/source outside legacy source flags, then run da-vinci design-source-sync-check --project <path> --json before design-session begin. If hashes diverge, resolve the canonical source first and rerun the sync check before continuing edits. If a registered project-local .dvp already exists, reopen it for continuity, persist the updated .dvp through da-vinci design-session persist --project <path> --change <change-id> --json, run da-vinci design-runtime-gate --project <path> --change <change-id> --json, and finish with da-vinci design-session end --project <path> --change <change-id> --json. The MVP guarantee is bound source-path safety: the registered .dvp, design session source path, and active editor path must converge before broad rendering continues. After the first successful runtime write, run da-vinci audit --mode integrity <path> before broad expansion continues. If da-vinci-pencli MCP is active, run da-vinci design-runtime-gate --project <path> --change <change-id> --json after the first successful runtime write and record it in .da-vinci/changes/<change-id>/ui-design.md. Screenshot review must record an explicit PASS, WARN, or BLOCK plus the issue list and revision outcome; "looks good" is not a valid review record. First-screen runtime metadata must be node-level and gate-readable. For each approved surface, mark real above-fold nodes with metadata.daVinci.aboveFold: true; include one metadata.daVinci.priority: "P0" + metadata.daVinci.uiRole: "value_proposition" node, exactly one metadata.daVinci.uiRole: "primary_cta" node, and one metadata.daVinci.uiRole: "trust_evidence" or proof node. Do not store first-screen proof as an object under aboveFold; the gate reads individual nodes, not summary objects. Keep the design gate provider-free. system.design.review is the fixed internal review binding on handoff-start:design_to_tasks, and $dv-handoff renders it as parallel Design Review, Icon Verification, and Copy Verification sections instead of reviewer-selection flow. Keep canonical icon policy in .da-vinci/DESIGN.md under ## Iconography, including any explicit surface-scoped exceptions with reason. WARN on that shared gate never auto-passes; the operator must make the explicit manual decision in $dv-handoff, while BLOCK means follow-up design work is still required. If system.icons.ensure-catalog reports an unsupported family, fail closed, repair icon bundle/import support, and rerun the same stage:start:design preflight instead of drawing UI with a guessed icon source. Final .dvp icon nodes must stay explicit and renderable: use type: "path" with role: "icon", non-empty SVG d, qualifiedName (or exact setId + name metadata), and metadata.daVinci.iconId when bound to icon-map.json; do not use free-text icon descriptions, empty path placeholders, emoji as structural icons, or mixed undeclared icon families. After every full .dvp rewrite or write_document call, reconcile icons before export: if the design added UI icons not already declared in .da-vinci/changes/<change-id>/icon-map.json, write .da-vinci/changes/<change-id>/overrides/icon-map.override.json with explicit surfaces[].icons[] overrides (selectionStatus: "ok", selectionSource: "override", qualifiedName, family, name, semantic, purpose, placement, size, and stable iconId), then rerun da-vinci icon-system-materialize --project <path> --change <change-id> --json. Do not continue while any *Icon/icon-button placeholder lacks d, qualifiedName, and metadata.daVinci.iconId. When design work is ready for review, stop this route and tell the user to run $dv-handoff manually; do not invoke $dv-handoff automatically from inside $dv-design. Before claiming design complete or workflow complete, run da-vinci audit --mode completion --change <change-id> <project-path> and treat any failure as blocking.