@xenonbyte/da-vinci-workflow 0.2.3 → 0.2.5

package/CHANGELOG.md

@@ -1,5 +1,37 @@
 # Changelog
 
+## v0.2.5 - 2026-04-02
+
+### Added
+- modular CLI command-family handlers for verify/lint surfaces via `lib/cli/verify-family.js`, `lib/cli/lint-family.js`, and shared helpers in `lib/cli/helpers.js`
+- framework-aware scaffold template coverage for React/Next.js/Vue/Svelte with explicit fallback metadata and expanded verify/scaffold regression tests
+- skill-contract split guardrails with `references/skill-workflow-detail.md`, `docs/skill-contract-maintenance.md`, and `scripts/test-skill-contract-core.js`
+
+### Changed
+- `verify-implementation` and `verify-structure` now emit richer evidence and incremental scan metadata (mode, confidence, boundaries, filtered input stats)
+- core `SKILL.md` was reduced to invariant workflow contract plus on-demand reference map; stage-specific procedures now live in owner references
+- shared path helpers (`normalizeRelativePath`, `pathWithinRoot`) moved into `lib/utils.js` to avoid duplicated logic drift
+
+### Fixed
+- `resolveImplementationLanding` now resolves `.vue`, `.svelte`, and SvelteKit `src/routes/<route>/+page.svelte` landings
+- `verify-implementation` no longer treats regex literal bodies as syntax-aware high-confidence coverage evidence
+- `verify-structure` no longer treats comment-only pseudo markup as real structural evidence
+- `--changed-files` now blocks symlink-based root-escape paths via realpath boundary checks
+- framework detection no longer reports definitive `unknown` when probe scans hit file-count limits; now marked ambiguous with warning context
+
+## v0.2.4 - 2026-04-02
+
+### Changed
+- design-approval freshness gates now compare approval markers against `design.md`, `pencil-design.md`, and `pencil-bindings.md` modification times
+- planning parser verification command extraction now accepts template-standard `da-vinci verify-*` commands in `tasks.md`
+- worktree preflight now degrades to advisory warning and recommends isolation when `git status` is unavailable (including non-git directories)
+- supervisor-review retry normalization now preserves explicit `0` retry configuration instead of silently falling back to defaults
+- Chinese README now includes missing parity sections for checkpoint policy, execution policy, spec granularity, design input collection, repo-local forward-test reference, and current status
+
+### Fixed
+- resolve-change failure envelopes in `task-execution` and `task-review` no longer emit `undefined` when failure arrays are empty
+- `.kongming/` workspace output is now ignored by repository git tracking
+
 ## v0.2.3 - 2026-04-02
 
 ### Added

package/README.md

@@ -28,15 +28,36 @@ This workflow is intended for:
 
 Latest published npm package:
 
-- `@xenonbyte/da-vinci-workflow@0.2.3`
+- `@xenonbyte/da-vinci-workflow@0.2.5`
 
-Release highlights for `0.2.3`:
+Release highlights for `0.2.5`:
 
-- added scene-first `Design Ops` actions for managed `Save Current Design`, icon sync progress, and Visual Assist platform+quality presets
-- tightened `Current Status` route mapping so `/dv:tasks`, `/dv:build`, and bootstrap routes are no longer forced into unrelated scene actions
-- removed stale hidden Advanced-command UI branches and aligned reachable keyboard/help behavior with scene-only navigation
-- simplified install/uninstall operations to one-click all-platform actions (`Codex`, `Claude Code`, `Gemini`) from the TUI
-- expanded regression coverage for TUI scene order, route mapping, and environment-stable `save-current-design` CLI behavior
+- 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
+
+## Discipline And Orchestration Upgrade
+
+The upgrade specification is tracked by:
+
+- `openspec/changes/discipline-and-orchestration-upgrade/`
+
+Implemented capability set:
+
+- design-approval discipline before implementation handoff
+- stronger `lint-tasks` quality checks for execution readiness
+- bounded orchestration hints (roles, concurrency, review order) derived from workflow state
+- structured implementer and two-stage task-review evidence
+- completion wording discipline backed by fresh verification evidence
+- optional worktree preflight for isolation-sensitive execution
+- structured `task-execution` and `task-review` command surfaces for per-task evidence
+
+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.
 
 ## Supported workflow modes
 
@@ -84,7 +105,11 @@ Route discipline:
 - when shell access is available, run `da-vinci workflow-status --project <path> [--change <id>] --json` and `da-vinci next-step --project <path> [--change <id>]` before selecting continuation route text
 - run `da-vinci lint-spec --project <path> [--change <id>]` before implementation when runtime spec quality is uncertain
 - run `da-vinci scope-check --project <path> [--change <id>]` before implementation when page/state propagation across planning artifacts is uncertain
+- run `da-vinci worktree-preflight --project <path> [--change <id>]` before bounded-parallel execution to decide whether isolation is recommended
+- use `da-vinci task-execution --project <path> --change <id> --task-group <id> ...` to persist implementer result envelopes (`DONE`, `DONE_WITH_CONCERNS`, `NEEDS_CONTEXT`, `BLOCKED`)
+- use `da-vinci task-review --project <path> --change <id> --task-group <id> --stage <spec|quality> ...` to persist ordered two-stage review evidence
 - run `da-vinci verify-bindings` / `verify-implementation` / `verify-structure` / `verify-coverage` before terminal completion claims
+- require fresh verification evidence plus `da-vinci audit --mode completion --change <id> <project-path>` before any terminal completion claim
 - run `da-vinci generate-sidecars --project <path> [--change <id>]` and `da-vinci diff-spec --project <path> [--change <id>]` when planning deltas must be tracked explicitly
 - `continue` should determine route selection from artifact and checkpoint truth first
 - contextual checkpoint deltas are auxiliary recovery notes only and must not override routing

package/README.zh-CN.md

@@ -30,15 +30,36 @@ Da Vinci 是一个把产品需求一路推进到结构化规格、Pencil 设计
 
 最新已发布 npm 包：
 
-- `@xenonbyte/da-vinci-workflow@0.2.3`
+- `@xenonbyte/da-vinci-workflow@0.2.5`
 
-`0.2.3` 版本重点：
+`0.2.5` 版本重点：
 
-- 新增场景化 `设计操作`：支持托管 `保存当前设计稿`、图标库同步进度反馈，以及 Visual Assist 平台+质量预设写入
-- 收紧 `当前状态` 场景映射：`/dv:tasks`、`/dv:build`、bootstrap 不再被错误导向到无关场景
-- 清理已下线的 Advanced 命令路径残留，TUI 键位与帮助文本统一为可达的场景交互
-- `安装与卸载` 统一为一键全平台动作（`Codex`、`Claude Code`、`Gemini`）
-- 补强回归测试：覆盖 TUI 场景顺序、路由映射，以及 `save-current-design` 的环境隔离稳定性
+- 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` 根目录限制
+
+## Discipline And Orchestration 升级
+
+该升级的规格与追踪在：
+
+- `openspec/changes/discipline-and-orchestration-upgrade/`
+
+当前已实现能力：
+
+- 在实现交接前增加设计批准纪律闸门
+- 强化 `lint-tasks` 的执行就绪质量检查
+- 基于 workflow state 给出有边界的编排提示（角色、并发、审查顺序）
+- 增加结构化 implementer 结果与两阶段 task review 证据
+- 用 fresh verification evidence 约束 completion 表述
+- 为隔离敏感的执行场景提供可选 worktree preflight
+- 提供结构化 `task-execution` / `task-review` 命令面用于任务级证据落盘
+
+该升级**不会**替代现有 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 目录查看具体实现拆分。
 
 ## 支持的工作流模式
 
@@ -89,7 +110,11 @@ Da Vinci 当前支持五种模式：
 - 有 shell 能力时，优先先跑 `da-vinci workflow-status --project <path> [--change <id>] --json` 与 `da-vinci next-step --project <path> [--change <id>]` 再决定 continue 的路由文本
 - 如果运行时 spec 质量不确定，进入实现前先跑 `da-vinci lint-spec --project <path> [--change <id>]`
 - 如果页面/状态在规划工件之间的传播关系不确定，进入实现前先跑 `da-vinci scope-check --project <path> [--change <id>]`
+- 计划走并行执行前，先跑 `da-vinci worktree-preflight --project <path> [--change <id>]` 评估是否应启用隔离
+- 用 `da-vinci task-execution --project <path> --change <id> --task-group <id> ...` 记录 implementer 结果包（`DONE`、`DONE_WITH_CONCERNS`、`NEEDS_CONTEXT`、`BLOCKED`）
+- 用 `da-vinci task-review --project <path> --change <id> --task-group <id> --stage <spec|quality> ...` 记录两阶段有序 review 证据
 - 终态前先跑 `da-vinci verify-bindings` / `verify-implementation` / `verify-structure` / `verify-coverage`
+- 任何终态 completion 表述前，必须同时具备 fresh verification evidence 与 `da-vinci audit --mode completion --change <id> <project-path>` 通过
 - 需要显式追踪规划变更时，先 `da-vinci generate-sidecars --project <path> [--change <id>]`，再 `da-vinci diff-spec --project <path> [--change <id>]`
 - `continue` 的选路应先看工件和 checkpoint 真相，再看上下文补充信息
 - Context Delta 只用于恢复上下文，不是阶段判定真相源
@@ -238,6 +263,14 @@ Da Vinci 的默认顺序是：
 - `tasks.md`：任务分组和实施顺序
 - `verification.md`：覆盖度和漂移检查
 
+### Spec 粒度规则
+
+spec 应按能力边界或重设计切片来拆分，不要按“页面数量”机械拆分。
+
+对于范围较大的 `redesign-from-code`，优先拆成多个 `specs/<slice>/spec.md`，不要堆成一个超大的 `ui-refresh/spec.md`。
+
+对于范围较大的 `overhaul-from-code`，优先使用多个 `specs/<slice>/spec.md` + 一个 `migration-contract.md`，不要把“保留行为”和“废弃行为”混在单一重写 spec 里。
+
 ## 工件放置建议
 
 推荐结构：
@@ -282,6 +315,54 @@ da-vinci bootstrap-project --project /abs/path/to/project --change <change-id>
 
 这个命令会先生成项目级 `.da-vinci/` 工件、默认项目内 `.pen`，以及当前工作流所要求的最小 change 级设计工件。
 
+## Checkpoints
+
+Da Vinci 使用以下检查点：
+
+1. `discovery checkpoint`
+2. `spec checkpoint`
+3. `design checkpoint`
+4. `design-source checkpoint`
+5. `mapping checkpoint`
+6. `task checkpoint`
+7. `execution checkpoint`
+
+检查结果：
+
+- `PASS`
+- `WARN`
+- `BLOCK`
+
+Context Delta 记录约束：
+
+- 在已有 change 工件里维护简洁 `Context Delta`（常见是 `pencil-design.md`、`tasks.md`、`verification.md`）
+- Context Delta 仅用于恢复上下文，不是阶段真相源
+
+## Execution Policy
+
+Da Vinci 默认是 `autonomous-by-default`。
+
+这意味着：
+
+- 不会在每个阶段都停下来等待用户确认
+- checkpoint 是内部质量门禁，不是审批门禁
+- 只有遇到真实阻塞才停
+
+默认行为：
+
+- `PASS` -> 继续
+- `WARN` -> 记录并继续
+- `BLOCK` -> 仅在无法从现有工件或本地上下文消解时停止
+- Context Delta 缺失或状态不一致 -> 告警并继续
+
+常见停止条件：
+
+- 用户明确要求暂停
+- 缺失输入会实质改变设计或实现结果
+- 需要外部授权或认证
+- 多个真相源冲突到无法可靠判断
+- 即将执行破坏性、会改变基线的动作
+
 ## 设计源规则
 
 - `DA-VINCI.md` 是跨页面视觉一致性的项目级视觉契约
@@ -341,6 +422,23 @@ da-vinci bootstrap-project --project /abs/path/to/project --change <change-id>
 - 默认把它当成非阻塞增强层
 - 只有用户明确要求必须使用某个 adapter 时，缺失才应阻塞工作流
 
+## 设计输入收集
+
+在 greenfield 项目开始 Pencil 设计前，Da Vinci 应先收集或推断：
+
+- 项目是否已有 `DA-VINCI.md`
+- 目标平台与设备形态（mobile / tablet / desktop / web）
+- 品牌方向、字体方向、色彩风格和密度预期
+- 是否存在必须遵守的设计约束（设计系统、交互约束、无障碍约束）
+- 是否存在外部参考素材（截图、竞品、风格板、历史设计稿）
+- 设计输出是否只交付设计，还是会继续进入实现与验收
+
+如果输入不足以稳定方向：
+
+- 先在 `design-brief.md` 记录待确认项与临时假设
+- 用最小可验证设计面推进，不直接铺开全量页面
+- 在下一轮 checkpoint 明确补齐缺失输入
+
 ## 安装
 
 安装 npm 包：
@@ -506,6 +604,38 @@ $da-vinci use continue for <existing workflow state>
 /dv:continue
 ```
 
+## 仓库内 forward-test 参考
+
+仓库里有一个“文档优先”的 forward-test 参考样例：
+
+- `examples/greenfield-spec-markupflow/`
+
+该样例记录了 `greenfield-spec` 场景从以下阶段推进的完整链路：
+
+1. design brief
+2. proposal 与 spec
+3. page map
+4. Pencil 设计源登记
+5. Pencil 页面绑定
+6. implementation tasks
+7. 静态 HTML 交付
+8. verification
+
+它不是可直接喂给 `da-vinci audit` 的完整 fixture。样例为了可读性把工件放在仓库根；而当前 audit 期望的是完整 `.da-vinci/` 树和持久化状态元数据。
+
+如果你要把样例形态转换成可执行审计的项目骨架，请先运行：
+
+```bash
+da-vinci bootstrap-project --project <project-path> --change <change-id>
+```
+
+reviewer bridge 覆盖策略：
+
+- 默认 CI 始终运行本地核心门禁（`npm run quality:ci:core`）
+- 仅在仓库集成变量可用时，主 CI 才追加真实 reviewer bridge smoke 任务
+- 真实 `codex exec` reviewer smoke 仍是显式 opt-in：`DA_VINCI_RUN_SUPERVISOR_INTEGRATION=1 npm run test:supervisor-review-integration`
+- `.github/workflows/reviewer-bridge-smoke.yml` 提供手动/定时 smoke；启用后会把集成缺线视为失败，而不是静默 `SKIP`
+
 ## 示例请求
 
 ### Greenfield spec
@@ -615,3 +745,17 @@ da-vinci/
 │   └── zh-CN/
 └── references/
 ```
+
+## 当前状态
+
+当前仓库包含：
+
+- Da Vinci skill 本体
+- 三平台命令适配（Codex / Claude / Gemini）
+- 工作流参考文档
+- 可执行示例
+
+下一阶段自然演进方向：
+
+1. 持续补强 install / uninstall / status 的回归覆盖
+2. 在真实项目上做带提交历史的 forward-test（含项目内 `.pen` 设计源）