@xenonbyte/da-vinci-workflow 0.2.5 → 0.2.7

package/CHANGELOG.md

@@ -1,5 +1,37 @@
 # Changelog
 
+## v0.2.7 - 2026-04-05
+
+### Added
+- `bounded-worker-isolation-contract` OpenSpec change with six contract slices covering advisory bounded-parallel baseline, isolated workspace rules, worker handoff payloads, sequencing, evidence writeback, and downgrade safety
+- `lib/isolated-worker-handoff.js` plus phase 1-4 regression tests for worker handoff payload constraints and contract closeout checks
+
+### Changed
+- `task-execution`, `task-review`, and `workflow-state` now keep isolated-worker evidence aligned with the new contract, including explicit partial-progress handling, review-order enforcement, out-of-scope-write blocking, and bounded-parallel downgrade visibility
+- `quality:ci:contracts` now includes bounded worker isolation contract regressions instead of relying only on docs/asset consistency lanes
+- supervisor-review reviewer execution now invokes `codex exec` with an explicit prompt separator and closed stdin, matching the real bridge behavior used by the integration smoke
+
+### Fixed
+- reviewer bridge diagnostics now keep `stdout` / `stderr` context when Codex exits without writing the expected structured JSON output
+- supervisor-review CLI and integration smoke fixtures now attach valid exported PNG screenshots so real reviewer runs can execute end to end
+- release docs now reflect the current published version and release highlights
+
+## v0.2.6 - 2026-04-04
+
+### Added
+- shared planning gate-envelope helpers (`lib/gate-utils.js`, `lib/planning-quality-utils.js`, `lib/planning-signal-freshness.js`) to normalize gate serialization, status finalization, and signal freshness checks across lint/spec/scope/task surfaces
+- new regression coverage for bounded clarify visibility, stale-signal upstream derivation, analyze orphan/support detection hardening, and strict-promotion routing semantics
+
+### Changed
+- `scope-check` analyze gate now enforces stronger cross-artifact support checks: empty bindings page-traceability is treated as drift, orphan fallback matching is tightened, and unresolved planning-anchor coverage is explicitly downgraded to advisory
+- `lint-tasks` now derives upstream clarify/analyze context from current artifacts when planning signals are stale and merges derived evidence into task-checkpoint gate resolution
+- planning signal freshness for `lint-tasks` now tracks `proposal.md` and page-map surfaces to prevent stale upstream gate carry-forward
+- workflow-state now routes decisions from persisted gate/status truth with explicit stale-signal handling and bounded clarify note propagation
+
+### Fixed
+- integrity audit now keeps clarify bounded-context findings visible for `lint-spec` signals regardless of top-level PASS/WARN/BLOCK status
+- `lint-spec` gate findings attachment no longer carries an unreachable bounded-context branch for non-clarify gates
+
 ## v0.2.5 - 2026-04-02
 
 ### Added

package/README.md

@@ -24,19 +24,25 @@ This workflow is intended for:
 - large existing-product overhauls where flows and logic also change
 - scoped feature delivery on an existing product
 
+## Maintainer Entry
+
+If you are contributing to this repository itself, start with
+[docs/maintainer-bootstrap.md](./docs/maintainer-bootstrap.md).
+Use `da-vinci maintainer-readiness` as the canonical maintainer diagnosis surface after setup.
+
 ## Current release
 
 Latest published npm package:
 
-- `@xenonbyte/da-vinci-workflow@0.2.5`
+- `@xenonbyte/da-vinci-workflow@0.2.7`
 
-Release highlights for `0.2.5`:
+Release highlights for `0.2.7`:
 
-- verify and lint command handling is now modularized (`lib/cli/verify-family.js`, `lib/cli/lint-family.js`, `lib/cli/helpers.js`) while preserving `--continue-on-error` semantics
-- verification surfaces now expose richer evidence metadata and incremental scan reporting for `--changed-files`
-- scaffold now supports framework-aware reviewable templates for Next.js, React, Vue, and Svelte, while preserving existing implementation landing shape precedence
-- `resolveImplementationLanding` now resolves `.vue`, `.svelte`, and SvelteKit `+page.svelte` route landings
-- verification hardening fixes now block regex-literal false positives, comment-only pseudo-markup structure passes, and symlink-escape changed-files paths
+- bounded worker isolation is now formalized as a contract-only OpenSpec change, with explicit task-group ownership, isolated workspace, handoff, sequencing, writeback, and downgrade rules
+- `task-execution`, `task-review`, and `workflow-state` now align with that contract by blocking out-of-scope writes, preserving review ordering, and rejecting `partial=true` + `DONE`
+- the reviewer bridge now runs `codex exec` with closed stdin plus explicit prompt separation, and preserves raw diagnostics when structured reviewer output is missing
+- contract CI now exercises bounded-worker-isolation phase 1-4 tests directly instead of relying only on docs/asset consistency checks
+- supervisor-review smoke fixtures now use valid exported screenshots, and the real reviewer bridge integration passes end to end
 
 ## Discipline And Orchestration Upgrade
 
@@ -57,7 +63,7 @@ Implemented capability set:
 This upgrade does **not** replace artifact truth, checkpoint truth, or completion audit authority.
 `workflow-status`, `next-step`, and orchestration outputs remain bounded by the existing contract.
 
-See [docs/discipline-and-orchestration-upgrade.md](/Users/xubo/x-skills/da-vinci/docs/discipline-and-orchestration-upgrade.md) for operator and maintainer guidance, and the OpenSpec change folder for implementation details.
+See [docs/discipline-and-orchestration-upgrade.md](./docs/discipline-and-orchestration-upgrade.md) for operator and maintainer guidance, and the OpenSpec change folder for implementation details.
 
 ## Supported workflow modes
 
@@ -134,7 +140,7 @@ If the growing CLI surface is the main usability problem, use the built-in termi
 - it supports English/Chinese chrome, light/dark theme auto-detection, and `t` as a manual fallback
 - `p` sets project context, `c` sets change context, `l` toggles language, `J` toggles `--json`, and `Enter` opens/runs the selected item
 
-Use [docs/skill-usage.md](/Users/xubo/x-skills/da-vinci/docs/skill-usage.md) for the operator-facing workflow, resume rules, and TUI guidance.
+Use [docs/skill-usage.md](./docs/skill-usage.md) for the operator-facing workflow, resume rules, and TUI guidance.
 
 ## Visual Assist Quick Start
 

package/README.zh-CN.md

@@ -26,19 +26,26 @@ Da Vinci 是一个把产品需求一路推进到结构化规格、Pencil 设计
 - 基于现有代码做流程、逻辑和 UI 一起变化的大改版
 - 在现有产品上做范围明确的 feature-change
 
+## 维护者入口
+
+如果你是在维护这个仓库本身（而不是在下游项目里使用 Da Vinci），请先看
+[docs/zh-CN/maintainer-bootstrap.md](./docs/zh-CN/maintainer-bootstrap.md)。
+
+完成 setup 后，用 `da-vinci maintainer-readiness` 作为维护者的 canonical 诊断/就绪命令。
+
 ## 当前发布状态
 
 最新已发布 npm 包：
 
-- `@xenonbyte/da-vinci-workflow@0.2.5`
+- `@xenonbyte/da-vinci-workflow@0.2.7`
 
-`0.2.5` 版本重点：
+`0.2.7` 版本重点：
 
-- verify/lint 命令分层模块化（`lib/cli/verify-family.js`、`lib/cli/lint-family.js`、`lib/cli/helpers.js`），并保持 `--continue-on-error` 语义不变
-- verification 系列命令增加更细粒度 evidence 元数据与 `--changed-files` 增量扫描报告
-- scaffold 增加 Next.js / React / Vue / Svelte 框架感知模板，并保持“已有 landing 形态优先”
-- `resolveImplementationLanding` 现已支持 `.vue`、`.svelte`，以及 SvelteKit 的 `+page.svelte` 路由 landing
-- verification 加固修复：阻断 regex 字面量误判、注释伪 markup 误判通过、以及 symlink 绕过 `--changed-files` 根目录限制
+- `bounded-worker-isolation-contract` 现已作为 contract-only OpenSpec 变更落地，明确 task-group ownership、isolated workspace、handoff、sequencing、writeback 与 downgrade 规则
+- `task-execution`、`task-review`、`workflow-state` 现已与该 contract 对齐：会阻断 out-of-scope writes，保持 review 顺序，并拒绝 `partial=true` 与 `DONE` 组合
+- reviewer bridge 现在会以显式 prompt 分隔并关闭 stdin 的方式运行 `codex exec`，同时在 reviewer 缺失结构化输出时保留原始诊断
+- contract CI 现在会直接跑 bounded-worker-isolation phase 1-4 回归，不再只依赖文档/命令资产一致性检查
+- supervisor-review smoke fixture 现在使用有效截图，真实 reviewer bridge integration 已能端到端通过
 
 ## Discipline And Orchestration 升级
 
@@ -59,7 +66,7 @@ Da Vinci 是一个把产品需求一路推进到结构化规格、Pencil 设计
 该升级**不会**替代现有 artifact truth、checkpoint truth 和 completion audit 权威。
 `workflow-status`、`next-step` 与 orchestration 输出仍然受现有契约约束。
 
-可先阅读 [docs/discipline-and-orchestration-upgrade.md](/Users/xubo/x-skills/da-vinci/docs/discipline-and-orchestration-upgrade.md) 了解说明，再结合 OpenSpec 目录查看具体实现拆分。
+可先阅读 [docs/discipline-and-orchestration-upgrade.md](./docs/discipline-and-orchestration-upgrade.md) 了解说明，再结合 OpenSpec 目录查看具体实现拆分。
 
 ## 支持的工作流模式
 
@@ -140,7 +147,7 @@ Da Vinci 当前支持五种模式：
 - 支持中英文界面与浅色/深色自动识别，`t` 可手动切换主题
 - `p` 设置项目上下文，`c` 设置 change 上下文，`l` 切语言，`J` 切 `--json`，`Enter` 进入/执行
 
-如果你想看“人到底怎么用这个 skill、暂停后怎么续跑、TUI 怎么配合”的完整说明，直接看 [docs/zh-CN/skill-usage.md](/Users/xubo/x-skills/da-vinci/docs/zh-CN/skill-usage.md)。
+如果你想看“人到底怎么用这个 skill、暂停后怎么续跑、TUI 怎么配合”的完整说明，直接看 [docs/zh-CN/skill-usage.md](./docs/zh-CN/skill-usage.md)。
 
 ## Visual Assist 快速上手
 

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
@@ -81,8 +97,10 @@ These commands do not replace route selection, but they support design execution
   - 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]`
+- `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> --confirm-test-evidence-executed] [--pending-test-evidence <csv>] [--concerns <csv>] [--blockers <csv>] [--out-of-scope-writes <csv>] [--partial] [--json]`
   - persists normalized implementer-status envelopes into execution signals
+  - `--pending-test-evidence` and `--partial` keep the envelope explicitly non-final; `DONE` is invalid when either is present
+  - `--out-of-scope-writes` keeps write-scope drift visible to workflow safety handling
   - use this to keep resume routing machine-readable when implementation is blocked or concerns remain
 - `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]`
   - persists ordered two-stage task review evidence (`spec` before `quality`)

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/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 形态是否合理、实现落点是否可定位
@@ -83,8 +97,10 @@ Da Vinci 期望它们遵循工作流状态。
   - 生成 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]`
+- `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> --confirm-test-evidence-executed] [--pending-test-evidence <csv>] [--concerns <csv>] [--blockers <csv>] [--out-of-scope-writes <csv>] [--partial] [--json]`
   - 持久化结构化 implementer 执行结果包，作为 task 级执行证据
+  - `--pending-test-evidence` 与 `--partial` 会将结果明确标记为非终态；此时不得使用 `DONE`
+  - `--out-of-scope-writes` 会把写范围漂移显式暴露给 workflow safety 处理
 - `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]`
   - 持久化有序两阶段 task review 证据（`spec` 在前，`quality` 在后）
 - `da-vinci worktree-preflight --project <path> [--change <id>] [--json]`