@xenonbyte/da-vinci-workflow 0.2.4 → 0.2.6

package/docs/dv-command-reference.md

@@ -9,7 +9,10 @@ Use it when you need to know:
 - how the routes connect in normal delivery
 - what to do when `verify` finds drift
 
-Use [workflow-overview.md](/Users/xubo/x-skills/da-vinci/docs/workflow-overview.md) for the full end-to-end workflow and [pencil-rendering-workflow.md](/Users/xubo/x-skills/da-vinci/docs/pencil-rendering-workflow.md) for the dedicated Pencil rendering lifecycle.
+Use [workflow-overview.md](./workflow-overview.md) for the full end-to-end workflow and [pencil-rendering-workflow.md](./pencil-rendering-workflow.md) for the dedicated Pencil rendering lifecycle.
+If you are contributing to this repository itself, use
+[maintainer-bootstrap.md](./maintainer-bootstrap.md)
+as the canonical maintainer bootstrap path before choosing deeper command surfaces.
 
 ## Core Idea
 
@@ -41,24 +44,37 @@ These commands do not replace route selection, but they support design execution
   - opens a workflow-oriented terminal UI that groups commands by phase and lets you run them after previewing the generated CLI
   - use `da-vinci-tui` as the dedicated bin alias, or `npx -p @xenonbyte/da-vinci-workflow da-vinci tui` without a global install
   - useful when the command surface is harder to remember than the workflow itself
+- `da-vinci verify-install [--platform <value>] [--json]`
+  - checks install confidence for explicitly selected maintainer platforms (for example `codex` only)
+  - treats non-selected platforms as `out_of_scope` / degraded coverage instead of hard failure
+  - if `--platform` is omitted, scope is reported as unknown instead of guessed from missing assets
+- `da-vinci maintainer-readiness [--platform <value>] [--project <path>] [--json]`
+  - canonical repository-maintainer readiness surface (diagnosis), distinct from setup/bootstrap
+  - combines packaged-asset validation, verify-install confidence, and focused contracts lane (`npm run quality:ci:contracts`)
+  - reports actionable next steps and keeps deeper lanes (`quality:ci:e2e`, `quality:ci`) as optional escalation
+  - intentionally narrower than full CI; escalate to deeper lanes when risk is higher
 - `da-vinci workflow-status --project <path> [--change <id>] [--json]`
   - derives the current workflow stage from artifact and checkpoint truth
   - reports blockers, warnings, handoff-gate state, discipline markers, execution profile hints, and verification-evidence freshness
   - keep this distinct from `audit`: route guidance is not completion truth
 - `da-vinci next-step --project <path> [--change <id>] [--json]`
   - provides a route-first continuation summary from the same derived workflow state
-  - JSON output includes `nextStep`, `executionProfile`, `worktreePreflight`, and discipline/freshness metadata for orchestration consumers
+  - JSON output includes `nextStep`, `blockingGate`, `executionProfile`, `worktreePreflight`, and discipline/freshness metadata for orchestration consumers
   - use this as the first continuation signal before free-form artifact scanning
 - `da-vinci lint-spec --project <path> [--change <id>] [--strict] [--json]`
   - validates Da Vinci runtime `spec.md` schema sections (`Behavior`, `States`, `Inputs`, `Outputs`, `Acceptance`, `Edge Cases`)
+  - emits machine-readable planning gates in JSON: `gates.principleInheritance`, `gates.clarify`, `gates.scenarioQuality`
+  - bounded-only clarify findings remain visible in `gates.clarify.bounded` and notes, and are non-blocking by default when bounded metadata is complete
   - default behavior is advisory (`WARN` with zero exit); `--strict` upgrades findings to blocking
   - explicitly does not treat OpenSpec planning `ADDED Requirements` structure as runtime-spec validity
 - `da-vinci scope-check --project <path> [--change <id>] [--strict] [--json]`
   - checks proposal, page-map, runtime specs, pencil-design states, and tasks for scope propagation gaps
+  - emits machine-readable analyze gate output in JSON: `gates.analyze`
   - emits a machine-readable coverage matrix for pages and states
   - default behavior is advisory (`WARN` with zero exit); `--strict` upgrades findings to blocking
 - `da-vinci lint-tasks --project <path> [--change <id>] [--strict] [--json]`
   - validates top-level task groups, ordering, discipline markers, execution-mode hints, file targets, verification commands, and behavior-to-task coverage hints
+  - validates task-anchor syntax (`Planning anchors:` and `anchor:<ref>`) and emits machine-readable checkpoint gate output: `gates.taskCheckpoint`
   - default behavior is advisory (`WARN` with zero exit); `--strict` upgrades findings to blocking
 - `da-vinci lint-bindings --project <path> [--change <id>] [--strict] [--json]`
   - validates implementation-to-Pencil mappings for parseability, source shape, and implementation landings
@@ -66,9 +82,21 @@ These commands do not replace route selection, but they support design execution
 - `da-vinci generate-sidecars --project <path> [--change <id>] [--json]`
   - explicitly generates deterministic planning sidecars: `spec.index.json`, `tasks.index.json`, `page-map.index.json`, `bindings.index.json`
   - this is the only write surface for planning sidecars; lint/status/verify surfaces should not silently rewrite them
-- `da-vinci verify-bindings|verify-implementation|verify-structure|verify-coverage --project <path> [--change <id>] [--strict] [--json]`
-  - verifies code landings, planned-state implementation evidence, and structural consistency against bindings
-  - `verify-structure` reports whether checks used markup-backed analysis or heuristic fallback and exposes confidence
+- `da-vinci verify-bindings --project <path> [--change <id>] [--strict] [--json]`
+  - validates implementation landing resolution from `pencil-bindings.md`
+- `da-vinci verify-implementation --project <path> [--change <id>] [--changed-files <csv>] [--strict] [--json]`
+  - verifies planned-state/task-group implementation evidence with per-check `mode` + `confidence` metadata
+  - JS/TS checks are syntax-aware and do not count comment-only or string-literal-only matches as normal coverage
+  - when `--changed-files` is used, the run is explicit incremental scope (partial semantics) and reports selected/scanned/filtered file counts
+- `da-vinci verify-structure --project <path> [--change <id>] [--changed-files <csv>] [--strict] [--json]`
+  - verifies structural consistency against bindings and reports `markup` vs `heuristic` confidence surfaces
+  - when `--changed-files` is used, unmatched or irrelevant entries stay visible instead of silently widening to full scan
+- `da-vinci verify-coverage --project <path> [--change <id>] [--changed-files <csv>] [--strict] [--json]`
+  - aggregates upstream verification surfaces and marks incremental upstream results as partial freshness
+- `da-vinci scaffold --project <path> [--change <id>] [--output <path>] [--json]`
+  - generates reviewable TODO scaffold templates with framework-aware shape (`next`/`react`/`vue`/`svelte`/`html`)
+  - keeps known implementation landing extension/route shape when a concrete landing already exists
+  - unknown/ambiguous framework detection falls back to HTML with explicit warning; traversal/output-root safety remains enforced
 - `da-vinci task-execution --project <path> --change <id> --task-group <id> --status <DONE|DONE_WITH_CONCERNS|NEEDS_CONTEXT|BLOCKED> --summary <text> [--changed-files <csv>] [--test-evidence <csv>] [--concerns <csv>] [--blockers <csv>] [--json]`
   - persists normalized implementer-status envelopes into execution signals
   - use this to keep resume routing machine-readable when implementation is blocked or concerns remain

package/docs/execution-chain-migration.md

@@ -30,10 +30,21 @@ Audit integration:
 
 - state schema version is supported
 - change entry exists
-- state timestamp is fresh
-- fingerprint matches current artifact truth
+- governing artifact content digests match current artifact truth
 
-If any check fails, Da Vinci falls back to derived state from artifacts and records reconciliation notes.
+Task-group ownership is now split cleanly:
+
+- `.da-vinci/state/workflow.json` is the route-cache snapshot
+- `.da-vinci/state/task-groups/<change>.json` is the canonical persisted task-group runtime-state file
+- `workflow.json` references the canonical task-group file by path and digest instead of embedding a normal-copy `taskGroups` array
+
+If persisted route trust fails, Da Vinci falls back to derived state from artifacts and records reconciliation notes.
+If the canonical task-group file is missing, unreadable, or digest-mismatched, Da Vinci keeps the persisted route snapshot eligible but rebuilds task-group runtime state from artifacts for that read.
+
+Snapshot age is now advisory only:
+
+- an old snapshot remains usable when governing artifact digests still match
+- age alone no longer invalidates persisted route truth
 
 ## 4. Scaffold Constraints
 

package/docs/maintainer-bootstrap.md

@@ -0,0 +1,102 @@
+# Maintainer Bootstrap Guide
+
+This guide is the canonical entry for contributors working on Da Vinci itself.
+
+## Audience Boundary
+
+- Repository maintainer bootstrap: preparing to change this repository.
+- Target-project bootstrap: `da-vinci bootstrap-project` scaffolds `.da-vinci/` artifacts for another project.
+- Package install status: `da-vinci status` / `da-vinci verify-install` checks install confidence only, not full repo readiness.
+- Operator workflow execution: use operator docs for downstream project flow, not for repository bootstrap.
+
+## First 10 Minutes After Clone
+
+1. Install dependencies: `npm install`
+2. Validate packaged assets: `npm run validate-assets`
+3. Verify install scope explicitly (recommended): `da-vinci verify-install --platform codex`
+4. Run canonical repo readiness check: `da-vinci maintainer-readiness --platform codex`
+
+Run these from the repository root checkout you are maintaining. If needed, pass
+`--project <path>` to target a different checkout explicitly.
+
+If you use multiple environments, pass all selected ones:
+
+- `da-vinci verify-install --platform codex,claude`
+- `da-vinci maintainer-readiness --platform codex,claude`
+
+## Entry Surface Taxonomy
+
+- Canonical entry:
+  - this guide + `da-vinci maintainer-readiness`
+- Secondary/advanced maintainer surfaces:
+  - `npm run quality:ci:contracts`
+  - `npm run quality:ci:e2e`
+  - `npm run quality:ci`
+  - targeted `scripts/test-*.js` runs when narrowing a regression
+- Downstream-project surfaces (not repo bootstrap):
+  - `da-vinci bootstrap-project`
+  - project `.da-vinci/` artifact workflows
+- Bootstrap-adjacent install surfaces:
+  - `da-vinci status`
+  - `da-vinci verify-install`
+
+## Bootstrap vs Diagnosis
+
+- Bootstrap/setup answers: "How do I get ready to work here?"
+- Diagnosis/readiness answers: "Is this repo + local environment healthy enough for my change?"
+
+Canonical diagnosis surface:
+
+- `da-vinci maintainer-readiness`
+
+It is intentionally narrower than full CI and gives actionable next steps. It runs:
+
+- packaged asset validation
+- selected-platform verify-install confidence
+- focused quality lane: `npm run quality:ci:contracts`
+
+## Selected Platform Semantics
+
+- Explicit `--platform` means only selected platforms are blocking.
+- Non-selected platforms remain visible as `out_of_scope` / degraded coverage.
+- If no `--platform` is provided, scope is treated as unknown and reported as degraded coverage instead of hard failure.
+
+## Use This / Do Not Use This
+
+- Use this:
+  - `da-vinci verify-install --platform codex` then `da-vinci maintainer-readiness --platform codex`
+- Do not use this:
+  - `da-vinci status` alone as proof of repo readiness
+- Use this:
+  - this maintainer guide for repository contribution setup
+- Do not use this:
+  - `da-vinci bootstrap-project` as maintainer bootstrap for this repository
+- Use this:
+  - operator docs only when you are running Da Vinci on another target project
+- Do not use this:
+  - operator workflow docs as the first maintainer entry surface
+
+## Troubleshooting
+
+- Symptom: `verify-install` is WARN with unknown scope.
+  - Action: rerun with explicit `--platform <value>` so selected scope is explicit.
+- Symptom: `maintainer-readiness` is BLOCK on verify-install.
+  - Action: fix selected-platform install issues first, then rerun readiness.
+- Symptom: install checks pass but change confidence is still low.
+  - Action: run deeper lanes (`quality:ci:e2e` or `quality:ci`) and targeted tests for the changed surfaces.
+- Symptom: confusion between repo bootstrap and downstream project bootstrap.
+  - Action: keep repo bootstrap in this guide; use `bootstrap-project` only for downstream repositories.
+
+## Deeper Validation Lanes
+
+Run these before broader or higher-risk changes:
+
+- `npm run quality:ci:e2e`
+- `npm run quality:ci`
+
+## Operator Workflow References
+
+Operator-facing workflow docs remain separate:
+
+- [skill-usage.md](./skill-usage.md)
+- [workflow-overview.md](./workflow-overview.md)

package/docs/pencil-rendering-workflow.md

@@ -10,7 +10,7 @@ Use it when you need the exact rules for:
 - screenshot review
 - runtime gates and filesystem audits
 
-Use [dv-command-reference.md](/Users/xubo/x-skills/da-vinci/docs/dv-command-reference.md) when you need the route-level `dv:` command sequence and rollback behavior across `design`, `tasks`, `build`, and `verify`.
+Use [dv-command-reference.md](./dv-command-reference.md) when you need the route-level `dv:` command sequence and rollback behavior across `design`, `tasks`, `build`, and `verify`.
 
 ## Rendering Truth Model
 

package/docs/prompt-entrypoints.md

@@ -71,6 +71,7 @@ Continuation precedence:
 - run `da-vinci scope-check --project <path> [--change <id>]` when page or state propagation across planning artifacts is uncertain
 - run `da-vinci lint-tasks --project <path> [--change <id>]` before routing into `build` when task metadata quality is uncertain
 - run `da-vinci verify-bindings --project <path> [--change <id>]` and `da-vinci verify-coverage --project <path> [--change <id>]` before terminal completion routing
+- if using `--changed-files` with `verify-implementation`/`verify-structure`/`verify-coverage`, treat results as explicit incremental partial evidence, not full-project freshness
 - run `da-vinci diff-spec --project <path> [--change <id>]` after planning edits when continuation must reason about changed requirement slices
 - determine routing from artifact and checkpoint truth first
 - use contextual checkpoint deltas only as auxiliary recovery context

package/docs/skill-contract-maintenance.md

@@ -0,0 +1,14 @@
+# SKILL Contract Maintenance
+
+Use this policy when editing workflow guidance:
+
+1. Keep invariant route/execution truth in `SKILL.md` only.
+2. Keep stage-specific procedure in one owned reference file.
+3. Ensure `SKILL.md` `Load References On Demand` map points to that owner.
+4. Avoid duplicate prose across `SKILL.md`, `references/`, and generated command assets unless tests explicitly require duplication.
+5. Update `references/skill-workflow-detail.md` move map when relocating sections.
+
+Boundary rule:
+
+- If a rule changes workflow truth, route semantics, or execution policy, edit core.
+- If a rule is tactical for one stage (design/build/review/scaffold), edit reference docs.

package/docs/skill-usage.md

@@ -2,6 +2,10 @@
 
 Use this document when you want the operator-facing workflow rather than the lower-level command reference.
 
+If you are contributing to Da Vinci itself, start with
+[maintainer-bootstrap.md](./maintainer-bootstrap.md)
+instead of this operator workflow guide.
+
 This guide focuses on:
 
 - how to enter the Da Vinci workflow the first time
@@ -18,6 +22,7 @@ That means:
 - `spec.md` and related requirement artifacts stay the behavior truth
 - the project-local `.pen` stays the design truth
 - `tasks.md`, `verification.md`, and execution signals explain what has or has not been implemented yet
+- workflow memory is artifact-backed local state under `.da-vinci/state/`, not cross-chat memory
 
 ## First Entry
 
@@ -79,14 +84,20 @@ When design is mostly ready and implementation is next, use these checks:
 
 - `da-vinci workflow-status`
   - confirm the active stage and blockers first
+  - task-group focus comes from checklist progress plus the latest `task-execution` / `task-review` evidence
 - `da-vinci next-step`
   - confirm whether the next move should still be `design`, `tasks`, or `build`
+  - use this when you need the first runtime-aware task-group focus, not just the next unchecked checklist item
 - `da-vinci lint-spec`
   - use this when runtime spec quality is still uncertain
+  - check `gates.principleInheritance`, `gates.clarify`, and `gates.scenarioQuality` in `--json` output
+  - treat `gates.clarify.bounded` as visible planning context: bounded-only clarify is non-blocking by default when bounded metadata is complete
 - `da-vinci scope-check`
   - use this when page/state propagation across planning artifacts looks ambiguous
+  - check `gates.analyze` in `--json` output for cross-artifact coherence blockers
 - `da-vinci lint-tasks`
   - confirm task groups have discipline markers, exact ownership targets, execution intent, and verification commands
+  - check `gates.taskCheckpoint` in `--json` output for anchor and checkpoint readiness
 - `da-vinci lint-bindings`
   - run this when `pencil-design.md` and `pencil-bindings.md` both exist so implementation landing evidence stays parseable
 - `da-vinci worktree-preflight`
@@ -112,6 +123,13 @@ During implementation, persist machine-readable task evidence instead of relying
 
 `quality` review is valid only after `spec` review has a `PASS` record for the same task group.
 
+Compatibility note:
+
+- flat task-group fields such as `status`, `completion`, `nextAction`, and `resumeCursor` remain available in `workflow-status --json`
+- `completion` stays checklist-derived progress percentage
+- `status`, `nextAction`, and `resumeCursor` may shift to runtime-aware values when implementer or review evidence is fresher than checklist state
+- `workflow-status --json` and `next-step --json` expose `blockingGate` when planning-gate promotion is blocked
+
 ## After Pausing Midway
 
 The safest resume order is:
@@ -124,12 +142,25 @@ The safest resume order is:
 6. before terminal completion, run `da-vinci verify-bindings` and `da-vinci verify-coverage`
 7. if completion wording is needed, confirm `verify-coverage` freshness is current and run `da-vinci audit --mode completion --change <id> <project-path>`
 
+Strictness control:
+
+- command lint strictness: use `--strict`
+- workflow promotion strictness: use `DA_VINCI_DISCIPLINE_STRICT_PROMOTION`
+- no separate strict controls are introduced for clarify/analyze/task-checkpoint gates
+- integrity audit keeps bounded-only clarify context visible from planning signals even when `lint-spec` signal status is `PASS`
+
 Resume should follow the artifacts, not old conversation state:
 
 - if design artifacts exist but `tasks.md` does not, resume into `tasks`
 - if `tasks.md` exists but design gates are still unresolved, resume into design cleanup rather than `build`
 - only resume into `build` when implementation readiness is already clear
 
+When task execution or review evidence conflicts with checklist progress:
+
+- trust the route recommendation from `workflow-status` / `next-step`
+- use task-group `nextAction` as the effective resume focus
+- treat checklist `completion` as progress visibility, not as proof that blockers or review debt are cleared
+
 ## How `change-id` Works
 
 `change-id` is the directory name under `.da-vinci/changes/<change-id>/`.

package/docs/workflow-overview.md

@@ -10,11 +10,14 @@ Use it when you need the high-level delivery chain:
 - page-to-design mapping
 - implementation and verification
 
-Use [pencil-rendering-workflow.md](/Users/xubo/x-skills/da-vinci/docs/pencil-rendering-workflow.md) when you need the lower-level Pencil session, persistence, gate, and audit details.
-Use [dv-command-reference.md](/Users/xubo/x-skills/da-vinci/docs/dv-command-reference.md) when you need route-by-route `dv:` command behavior, next-step recommendations, and verify rollback handling.
-Use [constraint-files.md](/Users/xubo/x-skills/da-vinci/docs/constraint-files.md) when you need a single map for project constraint files, hard-gate fields, and advisory guidance sections.
-Use [execution-chain-migration.md](/Users/xubo/x-skills/da-vinci/docs/execution-chain-migration.md) for sidecar, enforcement, persisted-state fallback, and scaffold migration guidance.
-Use [skill-usage.md](/Users/xubo/x-skills/da-vinci/docs/skill-usage.md) for an operator-facing guide to starting, pausing, resuming, and using the TUI.
+Use [pencil-rendering-workflow.md](./pencil-rendering-workflow.md) when you need the lower-level Pencil session, persistence, gate, and audit details.
+Use [dv-command-reference.md](./dv-command-reference.md) when you need route-by-route `dv:` command behavior, next-step recommendations, and verify rollback handling.
+Use [constraint-files.md](./constraint-files.md) when you need a single map for project constraint files, hard-gate fields, and advisory guidance sections.
+Use [execution-chain-migration.md](./execution-chain-migration.md) for sidecar, enforcement, persisted-state fallback, and scaffold migration guidance.
+Use [skill-usage.md](./skill-usage.md) for an operator-facing guide to starting, pausing, resuming, and using the TUI.
+If you are bootstrapping as a repository maintainer, start with
+[maintainer-bootstrap.md](./maintainer-bootstrap.md)
+as the canonical maintainer entry.
 
 ## Core Contract
 
@@ -33,6 +36,9 @@ This means:
 Truth-versus-orchestration boundary:
 
 - route and completion truth comes from artifacts, checkpoints, execution signals, and `audit`
+- workflow memory is artifact-backed local state, not chat-derived memory
+- `.da-vinci/state/workflow.json` is a persisted route cache, not the canonical owner of task-group runtime state
+- `.da-vinci/state/task-groups/<change>.json` is the canonical persisted task-group runtime-state owner when workflow snapshots are written
 - orchestration hints such as execution profiles and worktree preflight remain advisory guidance
 - orchestration hints must never override explicit `BLOCK` truth from artifacts, checkpoints, or completion audit
 
@@ -54,14 +60,23 @@ Use these command surfaces to inspect route readiness before selecting the next
 
 - `da-vinci workflow-status --project <path> [--change <id>] [--json]`
   - summarizes current stage, blockers, handoff gates, and route recommendation from artifact truth plus selected audit-visible evidence
+  - emits canonical task-group runtime state with compatibility fields plus layered planned / implementer / review / effective views
 - `da-vinci next-step --project <path> [--change <id>] [--json]`
   - emits the first continuation action from the same derived workflow-state model
+  - uses the same task-group runtime-state model as `workflow-status` instead of a separate checklist-only interpretation
+  - JSON output includes `blockingGate` when clarify/analyze/task-checkpoint promotion is blocked
 - `da-vinci lint-spec --project <path> [--change <id>] [--strict] [--json]`
   - validates runtime `spec.md` schema quality before implementation planning or execution
+  - emits machine-readable gates under `gates.principleInheritance`, `gates.clarify`, and `gates.scenarioQuality`
+  - clarify bounded ambiguity with complete metadata stays visible under `gates.clarify.bounded` and notes, and is non-blocking by default
   - default behavior is advisory; `--strict` is explicit opt-in for blocking behavior
 - `da-vinci scope-check --project <path> [--change <id>] [--strict] [--json]`
   - validates page and state propagation across proposal, page-map, runtime specs, pencil-design, and tasks
+  - emits machine-readable coherence gate output under `gates.analyze`
   - emits a machine-readable page/state coverage matrix for later verify and status consumers
+- `da-vinci lint-tasks --project <path> [--change <id>] [--strict] [--json]`
+  - validates task-group planning discipline plus anchor traceability to upstream planning evidence
+  - emits machine-readable gate output under `gates.taskCheckpoint`
 - `da-vinci generate-sidecars --project <path> [--change <id>] [--json]`
   - explicitly generates deterministic planning sidecars used by diff and downstream tooling
 - `da-vinci verify-bindings|verify-implementation|verify-structure|verify-coverage --project <path> [--change <id>] [--strict] [--json]`
@@ -77,6 +92,24 @@ Use these command surfaces to inspect route readiness before selecting the next
 
 These surfaces do not replace `da-vinci audit --mode integrity|completion`.
 `audit` remains the formal integrity and completion truth surface.
+- in integrity mode, planning-signal notes keep bounded clarify context visible even when `lint-spec` top-level signal status is `PASS`
+
+Persisted-state trust rules:
+
+- persisted workflow snapshots remain usable when governing artifact content digests still match, even if the snapshot is old
+- age alone is advisory and no longer invalidates persisted route truth
+- live overlays such as execution signals, audits, discipline, and verification freshness are recomputed on every read
+
+Planning-gate strictness control plane:
+
+- command-level lint strictness uses existing `--strict`
+- workflow promotion strictness uses `DA_VINCI_DISCIPLINE_STRICT_PROMOTION`
+- planning gates do not introduce a separate strict-flag family
+
+Spec-kit borrowing boundary:
+
+- Da Vinci borrows clarify/analyze/gate-method ideas only.
+- Da Vinci does not adopt spec-kit constitution/init/branch/toolchain workflow.
 
 ## Standard Artifact Spine
 
@@ -202,6 +235,8 @@ After mapping passes:
 - inspect `executionProfile` from `workflow-status` or `next-step --json` before broad implementation
 - if bounded parallelism is suggested, run `da-vinci worktree-preflight --project <path> [--change <id>]` and downgrade to serial when isolation is not ready
 - persist per-task implementer and review evidence via `task-execution` and ordered `task-review` records
+- read task-group `nextAction` and `resumeCursor` as runtime-aware focus when live evidence is fresher than checklist state
+- keep reading flat task-group `completion` as checklist-derived progress percentage rather than runtime health
 - verify requirement drift and design drift
 
 ### 8. Terminal Completion

package/docs/zh-CN/dv-command-reference.md

@@ -11,7 +11,8 @@
 - 正常推进时这些命令怎么衔接
 - `verify` 出问题后应该退回哪一层
 
-大流程请看 [workflow-overview.md](/Users/xubo/x-skills/da-vinci/docs/zh-CN/workflow-overview.md)，Pencil 渲染和门禁请看 [pencil-rendering-workflow.md](/Users/xubo/x-skills/da-vinci/docs/zh-CN/pencil-rendering-workflow.md)。
+大流程请看 [workflow-overview.md](./workflow-overview.md)，Pencil 渲染和门禁请看 [pencil-rendering-workflow.md](./pencil-rendering-workflow.md)。
+如果你是在维护这个仓库本身，请先看 [maintainer-bootstrap.md](./maintainer-bootstrap.md) 再进入更深命令面。
 
 ## 核心理解
 
@@ -43,24 +44,37 @@ Da Vinci 期望它们遵循工作流状态。
   - 打开面向工作流的终端 UI，按阶段组织命令，并在执行前先展示生成出的 CLI 预览
   - 也可以用独立 bin `da-vinci-tui`，或在没全局安装时用 `npx -p @xenonbyte/da-vinci-workflow da-vinci tui`
   - 当真正难记的是命令面而不是流程本身时，优先用它
+- `da-vinci verify-install [--platform <value>] [--json]`
+  - 校验显式选中的维护者平台安装置信度（例如只校验 `codex`）
+  - 未选平台会以 `out_of_scope` / degraded coverage 展示，不会直接判定失败
+  - 未传 `--platform` 时会报告 unknown scope，不会根据缺失资产猜测维护者意图
+- `da-vinci maintainer-readiness [--platform <value>] [--project <path>] [--json]`
+  - 仓库维护者的 canonical 诊断/就绪面（diagnosis），与 bootstrap/setup 分离
+  - 组合 packaged-asset 校验、verify-install 置信度和聚焦 contracts lane（`npm run quality:ci:contracts`）
+  - 输出可执行下一步，并把更深层 lane（`quality:ci:e2e`、`quality:ci`）作为可选升级路径
+  - 明确比 full CI 更窄；高风险改动再升级到更深校验
 - `da-vinci workflow-status --project <path> [--change <id>] [--json]`
   - 从工件和 checkpoint 真相推导当前 workflow 阶段
   - 报告 blocker、warning、handoff gate、discipline marker、execution profile 提示与 verification freshness
   - 它和 `audit` 职责不同：它负责选路，不是终态审计真相
 - `da-vinci next-step --project <path> [--change <id>] [--json]`
   - 基于同一套 workflow-state 推导，给出 route-first 的续跑建议
-  - JSON 输出包含 `nextStep`、`executionProfile`、`worktreePreflight` 与 discipline/freshness 元数据
+  - JSON 输出包含 `nextStep`、`blockingGate`、`executionProfile`、`worktreePreflight` 与 discipline/freshness 元数据
   - 在自由扫描工件之前，优先把它作为第一路由信号
 - `da-vinci lint-spec --project <path> [--change <id>] [--strict] [--json]`
   - 校验 Da Vinci 运行时 `spec.md` 的核心章节（`Behavior`、`States`、`Inputs`、`Outputs`、`Acceptance`、`Edge Cases`）
+  - JSON 输出机器可读 planning gate：`gates.principleInheritance`、`gates.clarify`、`gates.scenarioQuality`
+  - 当 bounded 元数据完整时，bounded-only clarify 会保留在 `gates.clarify.bounded` 与 notes 中，默认不阻断
   - 默认 advisory（有发现给 `WARN` 且不阻断）；显式 `--strict` 才升级为阻断
   - 不会把 OpenSpec 规划用的 `ADDED Requirements` 结构当成运行时 spec 合法结构
 - `da-vinci scope-check --project <path> [--change <id>] [--strict] [--json]`
   - 检查 proposal、page-map、运行时 spec、pencil-design 状态和 tasks 之间的 scope 传播一致性
+  - JSON 输出机器可读 analyze gate：`gates.analyze`
   - 输出页面与状态两条线的机器可读覆盖矩阵
   - 默认 advisory（有发现给 `WARN` 且不阻断）；显式 `--strict` 才升级为阻断
 - `da-vinci lint-tasks --project <path> [--change <id>] [--strict] [--json]`
   - 校验顶层 task groups、编号顺序、discipline markers、执行模式提示、文件目标、verification 命令与 behavior 覆盖提示
+  - 校验 task-anchor 语法（`Planning anchors:` 与 `anchor:<ref>`）并输出机器可读 checkpoint gate：`gates.taskCheckpoint`
   - 默认 advisory（有发现给 `WARN` 且不阻断）；显式 `--strict` 才升级为阻断
 - `da-vinci lint-bindings --project <path> [--change <id>] [--strict] [--json]`
   - 校验实现到 Pencil 的映射是否可解析、source 形态是否合理、实现落点是否可定位
@@ -68,9 +82,21 @@ Da Vinci 期望它们遵循工作流状态。
 - `da-vinci generate-sidecars --project <path> [--change <id>] [--json]`
   - 显式生成确定性的 planning sidecars：`spec.index.json`、`tasks.index.json`、`page-map.index.json`、`bindings.index.json`
   - sidecar 只允许通过这个命令写入；lint/status/verify 不应静默重写
-- `da-vinci verify-bindings|verify-implementation|verify-structure|verify-coverage --project <path> [--change <id>] [--strict] [--json]`
-  - 校验代码落点、计划状态实现证据、以及绑定驱动的结构一致性
-  - `verify-structure` 会明确报告是 markup-backed 还是 heuristic fallback，并给出置信度
+- `da-vinci verify-bindings --project <path> [--change <id>] [--strict] [--json]`
+  - 校验 `pencil-bindings.md` 的实现落点能否被正确解析
+- `da-vinci verify-implementation --project <path> [--change <id>] [--changed-files <csv>] [--strict] [--json]`
+  - 以每个检查项的 `mode` + `confidence` 证据模型校验状态/任务组实现覆盖
+  - JS/TS 会走语法感知检查，不把“仅注释命中”或“仅字符串字面量命中”当作正常覆盖
+  - 使用 `--changed-files` 时会进入显式增量模式（partial 语义），并输出 selected/scanned/filtered 统计
+- `da-vinci verify-structure --project <path> [--change <id>] [--changed-files <csv>] [--strict] [--json]`
+  - 校验 bindings 驱动的结构一致性，并显式报告 `markup`/`heuristic` 置信度
+  - 使用 `--changed-files` 时，不相关条目会被显式报告，不会静默扩展成全量扫描
+- `da-vinci verify-coverage --project <path> [--change <id>] [--changed-files <csv>] [--strict] [--json]`
+  - 聚合上游 verify surface，并在上游是增量验证时明确标记 partial freshness
+- `da-vinci scaffold --project <path> [--change <id>] [--output <path>] [--json]`
+  - 生成 framework-aware 的 TODO 可审查骨架（`next`/`react`/`vue`/`svelte`/`html`）
+  - 若已存在明确实现落点，会优先保留该落点的扩展名与路由形状
+  - 框架未知或冲突时显式告警并回退 HTML；同时继续严格执行 traversal/output-root 安全约束
 - `da-vinci task-execution --project <path> --change <id> --task-group <id> --status <DONE|DONE_WITH_CONCERNS|NEEDS_CONTEXT|BLOCKED> --summary <text> [--changed-files <csv>] [--test-evidence <csv>] [--concerns <csv>] [--blockers <csv>] [--json]`
   - 持久化结构化 implementer 执行结果包，作为 task 级执行证据
 - `da-vinci task-review --project <path> --change <id> --task-group <id> --stage <spec|quality> --status <PASS|WARN|BLOCK> --summary <text> [--issues <csv>] [--reviewer <name>] [--write-verification] [--json]`

package/docs/zh-CN/maintainer-bootstrap.md

@@ -0,0 +1,101 @@
+# Maintainer Bootstrap 指南
+
+这份文档是“维护 Da Vinci 仓库本身”的 canonical 入口。
+
+## 先划边界
+
+- 仓库维护者 bootstrap：准备修改这个仓库。
+- 下游项目 bootstrap：`da-vinci bootstrap-project` 用于给其他项目初始化 `.da-vinci/` 工件。
+- 安装状态：`da-vinci status` / `da-vinci verify-install` 只校验安装置信度，不等于仓库就绪度。
+- operator 工作流执行：下游项目操作请看 operator 文档，不要把它当维护者 bootstrap 入口。
+
+## Clone 后前 10 分钟
+
+1. 安装依赖：`npm install`
+2. 校验打包资产：`npm run validate-assets`
+3. 显式校验安装范围（推荐）：`da-vinci verify-install --platform codex`
+4. 运行维护者 canonical 就绪检查：`da-vinci maintainer-readiness --platform codex`
+
+如果你维护多个环境，请显式传入多个平台：
+
+- `da-vinci verify-install --platform codex,claude`
+- `da-vinci maintainer-readiness --platform codex,claude`
+
+这些命令应在你要维护的仓库根目录执行。需要时可用 `--project <path>` 显式指定目标仓库。
+
+## 入口面分层
+
+- Canonical 入口：
+  - 本文档 + `da-vinci maintainer-readiness`
+- Secondary/advanced 维护者面：
+  - `npm run quality:ci:contracts`
+  - `npm run quality:ci:e2e`
+  - `npm run quality:ci`
+  - 针对回归的 `scripts/test-*.js`
+- 下游项目面（非仓库维护 bootstrap）：
+  - `da-vinci bootstrap-project`
+  - 项目 `.da-vinci/` 工件工作流
+- bootstrap 相邻的安装面：
+  - `da-vinci status`
+  - `da-vinci verify-install`
+
+## Bootstrap 与 Diagnosis
+
+- Bootstrap/setup 回答的是：“我如何准备好在这里工作？”
+- Diagnosis/readiness 回答的是：“当前仓库 + 本地环境是否足够健康以推进本次改动？”
+
+Canonical diagnosis 面：
+
+- `da-vinci maintainer-readiness`
+
+该命令刻意比 full CI 更窄，并提供可执行的下一步。默认包含：
+
+- 打包资产校验
+- selected-platform 的 verify-install 置信度
+- 聚焦质量 lane：`npm run quality:ci:contracts`
+
+## Selected Platform 语义
+
+- 显式 `--platform`：只有选中的平台是阻断项。
+- 未选平台仍可见，但会标为 `out_of_scope` / degraded coverage。
+- 未传 `--platform`：按 unknown scope 报告 degraded coverage，不会硬失败。
+
+## Use This / Do Not Use This
+
+- Use this：
+  - `da-vinci verify-install --platform codex`，然后 `da-vinci maintainer-readiness --platform codex`
+- Do not use this：
+  - 只跑 `da-vinci status` 就判断仓库就绪
+- Use this：
+  - 用本指南做仓库维护者入门
+- Do not use this：
+  - 把 `da-vinci bootstrap-project` 当成这个仓库的维护者 bootstrap
+- Use this：
+  - 只有在下游项目操作时才看 operator 文档
+- Do not use this：
+  - 把 operator 工作流文档当成维护者首入口
+
+## 常见排错
+
+- 现象：`verify-install` 是 WARN 且 scope unknown。
+  - 处理：补 `--platform <value>` 显式声明 selected scope。
+- 现象：`maintainer-readiness` 在 verify-install 上 BLOCK。
+  - 处理：先修 selected-platform 安装问题，再重跑 readiness。
+- 现象：安装检查都通过，但对改动仍缺乏信心。
+  - 处理：升级跑更深的 lanes（`quality:ci:e2e` 或 `quality:ci`）和目标脚本。
+- 现象：混淆仓库 bootstrap 与下游项目 bootstrap。
+  - 处理：仓库维护按本指南，下游仓库才使用 `bootstrap-project`。
+
+## 更深层验证 Lane
+
+高风险或范围较大的改动前建议执行：
+
+- `npm run quality:ci:e2e`
+- `npm run quality:ci`
+
+## Operator 工作流参考
+
+operator 文档与维护者 bootstrap 保持分离：
+
+- [skill-usage.md](./skill-usage.md)
+- [workflow-overview.md](./workflow-overview.md)

package/docs/zh-CN/pencil-rendering-workflow.md

@@ -12,7 +12,7 @@
 - screenshot review
 - runtime gate 和 filesystem audit
 
-如果你想看 `design`、`tasks`、`build`、`verify` 这些 `dv:` 路由之间怎么衔接，以及 `verify` 出问题后退回哪一层，请看 [dv-command-reference.md](/Users/xubo/x-skills/da-vinci/docs/zh-CN/dv-command-reference.md)。
+如果你想看 `design`、`tasks`、`build`、`verify` 这些 `dv:` 路由之间怎么衔接，以及 `verify` 出问题后退回哪一层，请看 [dv-command-reference.md](./dv-command-reference.md)。
 
 ## 渲染真相模型
 

package/docs/zh-CN/prompt-entrypoints.md

@@ -72,6 +72,7 @@
 - 如果页面或状态在规划工件中的传播关系不确定，进入 `build` 前先运行 `da-vinci scope-check --project <path> [--change <id>]`
 - 如果任务拆解质量不确定，进入 `build` 前先运行 `da-vinci lint-tasks --project <path> [--change <id>]`
 - 进入终态前先运行 `da-vinci verify-bindings --project <path> [--change <id>]` 与 `da-vinci verify-coverage --project <path> [--change <id>]`
+- 若在 `verify-implementation`/`verify-structure`/`verify-coverage` 使用 `--changed-files`，要把结果视为显式增量 partial 证据，而不是全量 fresh 验证
 - 当规划切片有改动且需要恢复判断时，运行 `da-vinci diff-spec --project <path> [--change <id>]`
 - 先根据工件和 checkpoint 真相决定路由
 - Context Delta 只用于恢复和解释，不用于覆盖选路