flower-trellis 0.6.6 → 0.6.8-beta.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +16 -6
- package/enhancements/0.6/.agents/skills/trellis-check-all/SKILL.md +6 -39
- package/enhancements/0.6/.agents/skills/trellis-check-all/references/document-drift-auto-remediation.md +2 -0
- package/enhancements/0.6/.agents/skills/trellis-check-all/references/full-profile.md +10 -49
- package/enhancements/0.6/.agents/skills/trellis-check-all/references/light-profile.md +9 -28
- package/enhancements/0.6/.agents/skills/trellis-check-all/references/maven-evidence.md +14 -0
- package/enhancements/0.6/.agents/skills/trellis-check-all/references/reporting-and-disposition.md +18 -13
- package/enhancements/0.6/.agents/skills/trellis-check-all/references/verification.md +29 -0
- package/enhancements/0.6/.agents/skills/trellis-flower-update/SKILL.md +8 -5
- package/enhancements/0.6/.agents/skills/trellis-push/SKILL.md +3 -1
- package/enhancements/0.6/.agents/skills/trellis-push/references/output-templates.md +8 -9
- package/enhancements/0.6/.agents/skills/trellis-route/SKILL.md +1 -1
- package/enhancements/0.6/.agents/skills/trellis-worktree/SKILL.md +20 -8
- package/enhancements/0.6/.claude/skills/trellis-check-all/SKILL.md +6 -39
- package/enhancements/0.6/.claude/skills/trellis-check-all/references/document-drift-auto-remediation.md +2 -0
- package/enhancements/0.6/.claude/skills/trellis-check-all/references/full-profile.md +10 -49
- package/enhancements/0.6/.claude/skills/trellis-check-all/references/light-profile.md +9 -28
- package/enhancements/0.6/.claude/skills/trellis-check-all/references/maven-evidence.md +14 -0
- package/enhancements/0.6/.claude/skills/trellis-check-all/references/reporting-and-disposition.md +18 -13
- package/enhancements/0.6/.claude/skills/trellis-check-all/references/verification.md +29 -0
- package/enhancements/0.6/.claude/skills/trellis-flower-update/SKILL.md +8 -5
- package/enhancements/0.6/.claude/skills/trellis-push/SKILL.md +3 -1
- package/enhancements/0.6/.claude/skills/trellis-push/references/output-templates.md +8 -9
- package/enhancements/0.6/.claude/skills/trellis-route/SKILL.md +1 -1
- package/enhancements/0.6/.claude/skills/trellis-worktree/SKILL.md +20 -8
- package/enhancements/0.6/scripts/worktree_setup.py +119 -17
- package/enhancements/MANIFEST.json +2 -2
- package/package.json +3 -3
- package/src/assets/flower_update_hook.py +135 -14
- package/src/builtin-plugins/skill-garden/content-adapter.js +4 -0
- package/src/builtin-plugins/skill-garden/project-metadata.js +41 -0
- package/src/commands/self-check.js +3 -1
- package/src/commands/self-update.js +3 -1
- package/src/commands/update-check.js +3 -3
- package/src/commands/worktree.js +36 -5
- package/src/lib/apply-enhancements.js +1 -1
- package/src/lib/manifest.js +46 -43
- package/src/lib/self-check.js +8 -4
- package/src/lib/skill-catalog.js +35 -25
- package/src/lib/worktree-flower-state.js +347 -0
- package/src/plugin/application-service.js +1 -44
- package/src/plugin/install/state-validation.js +47 -0
- package/src/plugin/install/transaction-writer.js +23 -2
- package/src/plugin/state/ignore-rules.js +40 -0
- package/src/plugin/state/project-store.js +3 -25
package/README.md
CHANGED
|
@@ -172,7 +172,7 @@ flower-trellis plugin
|
|
|
172
172
|
|
|
173
173
|
交互管理器采用 `发现 / 已安装 / 来源 / 问题` 四个页签。Trellis 项目的 `发现` 页会展示 `flower/skill-garden` 内置入口,按 Enter 直接管理工作流强化与可选通用技能;原 `flower-trellis skill` 命令继续保留为高级兼容入口。`发现` 同时合并全部已启用来源的 Plugin,并保留来源标签和即时搜索;未登录 GitLab 来源会直接进入 Device Flow,GitHub 公共来源无需登录。`来源` 页的“新增来源”可选择 GitHub 公共仓库或 GitLab Marketplace;GitHub 会先在临时缓存中下载固定快照、检测格式、展示可导入与忽略组件,确认后才保存。ref 留空时使用仓库默认分支;出现多个格式入口时会要求选择,公开 GitHub 跨仓 Marketplace 条目和 `plugins/*` 多 Plugin 仓库也可识别。
|
|
174
174
|
|
|
175
|
-
可选通用技能包含 `aliyun-
|
|
175
|
+
可选通用技能包含 `aliyun-ops`,统一提供阿里云 DMS、SLS 与 MSE 查询和排障能力,DMS 写操作通过数据变更工单进入审批流。通用技能需手动选择启用,不会复制用户私有 AK/SK 配置。Codex 通用技能安装到 `.agents/skills`,Claude 安装到 `.claude/skills`;已有 `.codex` 或 `.agents` 时使用共享目标,已有 `.claude` 时使用 Claude 目标,三个目录都不存在时默认同时安装两份。空目录也可通过 Skill Garden 入口管理通用技能,无需初始化 Trellis。
|
|
176
176
|
|
|
177
177
|
安装、更新和卸载都会先展示 dry-run、依赖、capability 和目标文件变化,确认后才写入项目。Plugin 作者使用的 `plugin init`、`plugin validate` 继续保留在高级命令中,不占用普通用户的管理器首页。
|
|
178
178
|
|
|
@@ -184,9 +184,13 @@ flower-trellis plugin
|
|
|
184
184
|
|------|------|
|
|
185
185
|
| `.flower/plugins.json` | 可提交;只记录用户直接声明的 Plugin |
|
|
186
186
|
| `.flower/plugin-lock.json` | 可提交;记录固定版本、完整依赖图、来源与完整性摘要 |
|
|
187
|
+
| `.flower/.gitignore` | 可提交;保护本机数据并放开共享记录 |
|
|
187
188
|
| `.flower/state.json` | 本机;记录实际平台、生成路径、ownership 与 Patch provenance |
|
|
189
|
+
| `.flower/settings.json` | 本机;保存个人更新偏好 |
|
|
188
190
|
| `.flower/cache/`、`.flower/transactions/` | 本机;可清理缓存与事务恢复证据 |
|
|
189
191
|
|
|
192
|
+
安装或升级内置 Skill-Garden 时,已有根 `.gitignore` 会幂等维护 Flower 共享规则,允许正常提交上述声明、锁和局部忽略文件;重复升级不会重复添加。状态、个人设置和缓存仍被忽略,不会自动暂存或提交。根 `.gitignore` 不存在时不额外创建它。
|
|
193
|
+
|
|
190
194
|
`rd-guide` 是随包预注册、默认启用但惰性访问的 GitLab Marketplace。它的 GitLab 地址、项目和 ref 随 Flower 包升级,用户配置只保存启用或停用偏好,避免旧的用户级完整副本静默遮蔽包内修复;需要其它地址或分支时应新增独立 source ID。打开管理器后,`发现` 页会在已有凭据时读取远程目录;未登录时只展示授权入口,不会尝试读取仓库内容。普通交互默认使用 Device Flow,PKCE 浏览器登录保留为来源详情中的高级选项。OAuth 只申请 `read_api read_repository`,Application Secret 和 token 都不会写入项目文件。
|
|
191
195
|
|
|
192
196
|
GitHub 首版只支持 `github.com` 公共仓库和匿名 REST,不保存 PAT 或其它凭据。来源会固定确认后的格式入口;安装 lock 固定完整 commit 与 canonical digest,通过 Marketplace 发现时还会固定索引仓库和索引 commit。匿名 API 可能受每小时 60 次/IP 的主要限额影响,限流会显示为 GitHub 诊断,不会转成登录提示。
|
|
@@ -218,7 +222,7 @@ flower-trellis plugin validate .flower-plugin --subject plugin --json
|
|
|
218
222
|
flower-trellis plugin add flower/flower-plugin-author --platform codex --json
|
|
219
223
|
```
|
|
220
224
|
|
|
221
|
-
旧 `.trellis/.flower-manifest.json`
|
|
225
|
+
旧 `.trellis/.flower-manifest.json` 在下一次增强安装或升级时完成一次迁移:保留必要的更新策略和缓存,写入现代记录后事务性删除旧文件,失败恢复。现代配置优先;显式 `--no-enhance` 不提前删除未经迁移的旧记录。普通 `flower-trellis update` 重放已锁定版本,只有显式 `plugin update` 才解析外部 Plugin 新版本。
|
|
222
226
|
|
|
223
227
|
### 升级备份保留
|
|
224
228
|
|
|
@@ -251,12 +255,16 @@ flower-trellis plugin add flower/flower-plugin-author --platform codex --json
|
|
|
251
255
|
- Codex:向 `.codex/hooks.json` 的 `SessionStart` 追加 `.trellis/scripts/flower_update_hook.py`。
|
|
252
256
|
- Claude Code:只向 `.claude/settings.json` 的 `SessionStart` `startup` matcher 追加该 hook,不挂 `clear` / `compact`。
|
|
253
257
|
|
|
254
|
-
启动 hook 不会直接安装 npm
|
|
258
|
+
启动 hook 不会直接安装 npm 包,也不会直接改项目文件。它先检查本机 CLI;CLI 可用时继续调用:
|
|
255
259
|
|
|
256
260
|
```bash
|
|
257
261
|
flower-trellis self-check --json --target .
|
|
258
262
|
```
|
|
259
263
|
|
|
264
|
+
团队成员克隆已提交升级文件的项目后,即使没装 Flower CLI,同一 Python hook 也会读取项目锁并注入 `<flower-cli-bootstrap>`。助手先展示锁定版本和 `npm install -g flower-trellis@<版本>`,成员确认后才安装,验证 CLI 后继续原请求。全局安装沿用现有的本机 Trellis 命令同步,不隐式升级项目内容。版本未知、缺少 Node/npm 或安装失败时会说明原因,不猜 latest、不自动提权、不循环安装。
|
|
265
|
+
|
|
266
|
+
自动入口需要 Python 可用且 Codex/Claude 启用 hooks;其他平台可通过 `trellis-flower-update` 调用同一检测脚本的 `--bootstrap-only` 模式。成员拒绝安装后,本次对话不重复追问。
|
|
267
|
+
|
|
260
268
|
发现可更新或项目已铺版本不一致时,向 AI 注入 `<flower-update>` 上下文。无更新、离线、关闭检查、npx 临时运行时默认不打扰;同一更新提示会按本机提示节流状态降噪。
|
|
261
269
|
|
|
262
270
|
检查分两层:
|
|
@@ -296,7 +304,7 @@ tmp 中保存本地运行缓存:
|
|
|
296
304
|
}
|
|
297
305
|
```
|
|
298
306
|
|
|
299
|
-
|
|
307
|
+
旧项目 manifest 的 `updateCheck` 在升级前仍可兼容读取;增强迁移成功后必要配置转入现代位置,旧 manifest 文件删除。
|
|
300
308
|
|
|
301
309
|
`policy` 可选:
|
|
302
310
|
|
|
@@ -353,7 +361,7 @@ flower banner → 平台多选菜单 → Trellis 原生交互(模板 / monorepo
|
|
|
353
361
|
|
|
354
362
|
- **统一品牌头部**:Trellis 子进程在伪终端(`node-pty`)中运行,其原生的模板 / monorepo / 冲突等交互完整保留,但重复打印的启动 banner 被过滤,全程只呈现一个 flower banner。
|
|
355
363
|
- **按平台铺设技能**:Claude 铺到 `.claude/skills`,Codex / Gemini 等铺到 `.agents/skills`;并做平台后处理:Codex 兼容清理旧 `config.toml` 的 `[features.multi_agent_v2]`,在保留上游 hooks 的基础上补全 `SessionStart`;Claude Code 只在 `startup` SessionStart 挂载启动更新检查。
|
|
356
|
-
- **幂等执行**:0.6 Patch 使用受管 marker 原位升级,完整预检通过后只写 changed
|
|
364
|
+
- **幂等执行**:0.6 Patch 使用受管 marker 原位升级,完整预检通过后只写 changed 文件;技能资产和现代 `.flower/state.json` 记录进入同一插件事务,通过路径 ownership 与摘要精确清理淘汰内容。0.5/old 继续使用兼容注入路径,旧 manifest 只用于迁移识别。
|
|
357
365
|
- **结构化 Patch**:Trellis 0.6 的 workflow、skill、hook 与平台配置统一通过 `insert / replace / remove` 预检后应用;selector/baseline 或已知最终协议冲突时在写入前停止。
|
|
358
366
|
- **上线事项账本**:强化包通过 Finish-Work Patch 在归档前智能识别 SQL、配置、批处理 / 部署脚本 / 数据修复、外部系统 / 依赖平台等上线事项,必要时写入任务 `release.md`;`trellis-release` 可在正式上线前核对任务文档、`release.md` 和 git 证据,生成 `YYYY-MM-DD-<release-slug>.md` 格式的版本 / 批次操作单。
|
|
359
367
|
- **安全中止**:`Ctrl+C` 取消后不会继续叠加。
|
|
@@ -373,7 +381,9 @@ flower banner → 平台多选菜单 → Trellis 原生交互(模板 / monorepo
|
|
|
373
381
|
|
|
374
382
|
- **通用技能**:`flower-trellis update` 会用新版快照覆盖仓库中已经启用的 common skill,
|
|
375
383
|
未启用项不会自动安装;若某个已安装 common skill 已从新版快照移除,更新会精确删除其
|
|
376
|
-
`.
|
|
384
|
+
`.agents/skills` / `.claude/skills` 或历史 `.codex/skills` 副本。安装或更新对应技能时,
|
|
385
|
+
旧 `.codex/skills` 会迁移到 `.agents/skills`,兼容旧技能名称;新副本写入成功后才清理旧目录。
|
|
386
|
+
新旧同名技能仍按随包快照替换,不合并自定义内容;停用会清理该技能的新旧精确目录。
|
|
377
387
|
|
|
378
388
|
## 开发
|
|
379
389
|
|
|
@@ -10,18 +10,6 @@ description: "统一 Check-All:按 requested/effective depth 路由 light/full
|
|
|
10
10
|
|
|
11
11
|
---
|
|
12
12
|
|
|
13
|
-
## 入口职责
|
|
14
|
-
|
|
15
|
-
1. 确认本轮检查范围、task artifacts 或 untracked state、项目规范和运行上下文。
|
|
16
|
-
2. 解析 `requested_depth`,生成 `check_profile`,决定 `effective_depth=light|full`。
|
|
17
|
-
3. 按有效深度读取并执行对应 profile。
|
|
18
|
-
4. 按根因把发现分为 `CHK-*`、`FBK-*`、`DOC-*`,再为前两类分配 P0/P1/P2。
|
|
19
|
-
5. 报告前处理允许自修的事实漂移并展示结果。
|
|
20
|
-
6. 按 interactive / validated auto-loop 边界输出下一步或执行 `record + next`。
|
|
21
|
-
7. untracked helper 只存游标:findings 或新编辑回 `implement`;通过且 disposition 继续时才 `advance --stage spec`。
|
|
22
|
-
|
|
23
|
-
---
|
|
24
|
-
|
|
25
13
|
## 必读引用
|
|
26
14
|
|
|
27
15
|
按需加载引用文件,不要提前读取未命中的 profile:
|
|
@@ -43,7 +31,7 @@ description: "统一 Check-All:按 requested/effective depth 路由 light/full
|
|
|
43
31
|
2. **唯一自修例外**:低风险事实漂移进入 `DOC-*` 通道,按 `references/document-drift-auto-remediation.md` 的白名单、黑名单和写入时机处理。
|
|
44
32
|
3. **分类先于严重度**:读取 `references/fallback-findings.md`;主路径错误和非兜底契约违背进入 `CHK-*`,fail-closed、异常输入、失败降级和防御性保护缺口进入 `FBK-*`。契约证据影响严重度,不改变兜底根因归属。
|
|
45
33
|
4. **处置只确认一次**:统一报告后选择 `CHK-*` / `FBK-*` 修复范围或接受风险;`修复全部` 覆盖两类,接受风险不得隐藏发现。
|
|
46
|
-
5.
|
|
34
|
+
5. **共享验证**:两个 profile 共用 `references/verification.md`;同一追踪与有效验证证据跨维度复用,检查保持只读。
|
|
47
35
|
6. **真正阻塞才中途暂停**:业务规划冲突、前提失效,或当前结论必需验证涉及未授权生产/外部/破坏性副作用时暂停;发布后验收只记 `[上线后验证]`,不执行、不阻断。
|
|
48
36
|
|
|
49
37
|
中途停止时也要使用统一问题模型,报告已完成范围和阻塞原因;只询问解除阻塞所需的业务或安全决策。
|
|
@@ -74,18 +62,11 @@ description: "统一 Check-All:按 requested/effective depth 路由 light/full
|
|
|
74
62
|
|
|
75
63
|
## 顶层流程
|
|
76
64
|
|
|
77
|
-
|
|
65
|
+
untracked helper 只存游标:findings 或新编辑回 `implement`;通过且 disposition 继续时才 `advance --stage spec`。
|
|
78
66
|
|
|
79
|
-
|
|
67
|
+
### Step 0:范围、上下文与深度画像
|
|
80
68
|
|
|
81
|
-
|
|
82
|
-
check_profile:
|
|
83
|
-
context: interactive | auto-loop
|
|
84
|
-
requested_depth: auto | light | full
|
|
85
|
-
effective_depth: light | full
|
|
86
|
-
confidence: high | fallback-full | escalated
|
|
87
|
-
reasons: [string]
|
|
88
|
-
```
|
|
69
|
+
执行 `references/depth-routing.md` 的完整 Step 0,按其格式生成 `check_profile`。
|
|
89
70
|
|
|
90
71
|
### Step 1:读取对应 profile
|
|
91
72
|
|
|
@@ -98,37 +79,23 @@ check_profile:
|
|
|
98
79
|
|
|
99
80
|
### Step 3:处理事实漂移自修
|
|
100
81
|
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
- inline:主会话应用允许的 `DOC-*` 修复并做定向验证。
|
|
104
|
-
- subagent:主会话审阅 subagent 返回的 `DOC-*` 候选,只应用满足白名单且无歧义的修复。
|
|
105
|
-
- auto-loop:主会话应用允许的 `DOC-*` 修复后再 `record`;若只存在已修复事实漂移且无剩余 `CHK-*` / `FBK-*`,结果可为 `ok`,摘要必须包含自动修复说明。
|
|
82
|
+
按 `references/document-drift-auto-remediation.md` 的白名单和证据规则,由主会话处理允许的 DOC 并定向验证;subagent 仅返回候选。完成后再报告或交给 reporting reference 的 auto-loop 分流。
|
|
106
83
|
|
|
107
84
|
不满足自动修复条件的文档问题根据根因转为 `CHK-*`、`FBK-*` 或剩余风险,按普通修复范围处理。
|
|
108
85
|
|
|
109
86
|
### Step 4:统一报告与分流
|
|
110
87
|
|
|
111
|
-
读取 `references/reporting-and-disposition.md
|
|
112
|
-
|
|
113
|
-
- `check_profile`;
|
|
114
|
-
- 三个维度状态;
|
|
115
|
-
- 自动修复的 `DOC-*` 内容;
|
|
116
|
-
- 剩余 `CHK-*` 主路径问题与 `FBK-*` 兜底问题;
|
|
117
|
-
- 每个剩余问题的未处置或已接受风险状态;
|
|
118
|
-
- 已执行验证、未覆盖风险和 `[上线后验证]`;
|
|
119
|
-
- 与当前结论匹配的唯一下一步。
|
|
88
|
+
读取 `references/reporting-and-disposition.md`,按其完整模板与分流规则在对话中输出报告;默认不新建报告文件,落盘例外由该 reference 定义。
|
|
120
89
|
|
|
121
90
|
---
|
|
122
91
|
|
|
123
92
|
## 反模式
|
|
124
93
|
|
|
125
94
|
- 入口默认加载 full profile,导致 `auto` 被 full 语气带偏。
|
|
126
|
-
- 发现一个普通问题就暂停询问一次。
|
|
127
95
|
- 把 `trellis-check` 的自动修复指令带入普通 `CHK-*`。
|
|
128
96
|
- 先按严重度决定 `CHK-*` / `FBK-*` 通道,混淆根因性质与影响等级。
|
|
129
97
|
- 把纯偏好、无具体场景或无法验证收益的“更健壮”建议记录为 `FBK-*`。
|
|
130
98
|
- 因兜底行为已写入契约就把保护路径根因改列为 `CHK-*`。
|
|
131
|
-
- subagent 直接修改工作区。
|
|
132
99
|
- 把需求变更、验收标准、产品语义或设计取舍伪装成文档漂移自动修复。
|
|
133
100
|
- light 未命中完整穷举条件仍继续 light。
|
|
134
101
|
- 无环境证据却把维度标记为通过。
|
|
@@ -34,6 +34,8 @@
|
|
|
34
34
|
- 不改操作步骤、责任边界、安全提示、协议字段或对外承诺,且可由重读或静态检查验证;
|
|
35
35
|
- 用户没有明确要求本轮绝对只读。
|
|
36
36
|
|
|
37
|
+
任务状态同步只更新已有文档中的过期事实;不得借 `task-status`、`check-record` 或 `mechanical-link` 新建检查报告并追加引用。报告落盘条件见 `references/reporting-and-disposition.md`。
|
|
38
|
+
|
|
37
39
|
典型例子:
|
|
38
40
|
|
|
39
41
|
- `brief.md` 漏掉 diff 已证明的实现范围,或 `implement.md` 状态机械过期;
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Full Profile
|
|
2
2
|
|
|
3
|
-
Full 是完整验收映射和全影响面审查。只有 `check_profile.effective_depth=full`
|
|
3
|
+
Full 是完整验收映射和全影响面审查。只有 `check_profile.effective_depth=full` 时读取本文件;共享验证规则见 `references/verification.md`。
|
|
4
4
|
|
|
5
5
|
---
|
|
6
6
|
|
|
@@ -12,9 +12,9 @@ untracked 上下文没有 task artifacts,本 Step 标记 `N/A`;不得把 sum
|
|
|
12
12
|
|
|
13
13
|
- PRD Requirement / Acceptance Criteria:行为基线。
|
|
14
14
|
- Design API、数据模型、数据流、关键决策和 rollback:技术基线。
|
|
15
|
-
- Implement
|
|
15
|
+
- Implement 中未被前两者覆盖的产物、review gate 和 rollback point:补充基线。
|
|
16
16
|
|
|
17
|
-
full
|
|
17
|
+
full 提取所有适用条目。同一行为在多份文档中重复出现时合并验收,保留全部来源位置;不同约束、边界场景或相互冲突的要求不得合并丢失。实际阅读对应代码后再判断。
|
|
18
18
|
|
|
19
19
|
### 1.2 必查类型
|
|
20
20
|
|
|
@@ -22,7 +22,7 @@ full 提取所有适用条目。每条记录来源位置,实际阅读对应代
|
|
|
22
22
|
| --- | --- |
|
|
23
23
|
| `prd.md` | AC、需求、业务规则、UI 文案、边界和异常场景 |
|
|
24
24
|
| `design.md` | API 路径/方法/字段、数据模型、数据流、关键 tradeoff、rollout/rollback |
|
|
25
|
-
| `implement.md` |
|
|
25
|
+
| `implement.md` | 补充产物是否落地、review gate 是否满足、rollback point 是否可用;不重复核对已覆盖的实现步骤 |
|
|
26
26
|
|
|
27
27
|
`implement.md` 中的 validation command 在本步骤只做静态前提核对;真实运行归 Step 3。
|
|
28
28
|
|
|
@@ -41,6 +41,8 @@ full 提取所有适用条目。每条记录来源位置,实际阅读对应代
|
|
|
41
41
|
|
|
42
42
|
文案要求逐字一致时,对照最终有效文案来源;不要强制要求文案必须直接写在组件字面量中。
|
|
43
43
|
|
|
44
|
+
同一条调用链只追踪一次,记录实现位置和关键边界证据,供 Step 2 与 Step 3 复用。后续只补尚未覆盖的约束、调用方、异常分支或失效证据;不得因复用而跳过独立的验收判断。
|
|
45
|
+
|
|
44
46
|
### 1.4 记录结果
|
|
45
47
|
|
|
46
48
|
发现偏差、缺失、部分实现或文案不一致时,写入统一问题集合并继续。不要在此步骤询问“先修还是继续检查”。
|
|
@@ -49,14 +51,14 @@ full 提取所有适用条目。每条记录来源位置,实际阅读对应代
|
|
|
49
51
|
|
|
50
52
|
## Step 2:实现假设验证
|
|
51
53
|
|
|
52
|
-
根据实际变更选择适用 Dimension。每个适用 Dimension
|
|
54
|
+
根据实际变更选择适用 Dimension。每个适用 Dimension 都要确认源码或真实契约证据,不能凭记忆通过。先复用 Step 1 的追踪结果,再核对本维度新增的约束;验证命令需求统一交给 Step 3,不在各 Dimension 分别运行。
|
|
53
55
|
|
|
54
56
|
### Dimension A:API Contract
|
|
55
57
|
|
|
56
58
|
**Trigger**:新增或修改已有 API 调用、请求参数或响应解析。
|
|
57
59
|
|
|
58
60
|
- 读取 Controller/Handler 和 DTO/Schema,确认实际请求、响应结构。
|
|
59
|
-
-
|
|
61
|
+
- 契约仍有歧义时,补查项目内同 API 或同模式调用。
|
|
60
62
|
- 确认参数名、类型、默认值、分页字段和起始页码。
|
|
61
63
|
- 覆盖正常、空值、零值和错误响应。
|
|
62
64
|
|
|
@@ -67,7 +69,7 @@ full 提取所有适用条目。每条记录来源位置,实际阅读对应代
|
|
|
67
69
|
- 确认容器关闭或切换时是否销毁子组件。
|
|
68
70
|
- 确认受控值、初始化值和外部状态绑定。
|
|
69
71
|
- 确认状态保持/重置行为符合规划。
|
|
70
|
-
-
|
|
72
|
+
- 状态约定仍不明确时,补查项目内相同容器的既有用法。
|
|
71
73
|
|
|
72
74
|
### Dimension C:Data History
|
|
73
75
|
|
|
@@ -87,54 +89,13 @@ full 提取所有适用条目。每条记录来源位置,实际阅读对应代
|
|
|
87
89
|
- 覆盖缺省、空值、零值、特殊字符和错误传播。
|
|
88
90
|
- 分层代码分别正确不等于整条链路正确,必须连起来核对。
|
|
89
91
|
|
|
90
|
-
### Dimension E:Verification Tests
|
|
91
|
-
|
|
92
|
-
**Trigger**:Dimension A-D 任一适用。
|
|
93
|
-
|
|
94
|
-
- 自动化测试优先;可重复的手动步骤、静态检查或定向命令也可作为验证证据。
|
|
95
|
-
- 优先覆盖最脆弱的参数名、嵌套结构、历史数据和空值路径。
|
|
96
|
-
- 测试存在时实际运行;未运行不能报告通过。
|
|
97
|
-
- 仅缺少自动化测试文件不得生成 `CHK-*`;项目 spec、风险等级或回归概率明确要求自动化覆盖时,缺失测试仍记录问题。
|
|
98
|
-
- 缺少完成当前结论所必需的充分证据时记录 `CHK-*`,等待用户确认修复范围后再补充验证或测试。
|
|
99
|
-
|
|
100
92
|
发现假设错误时写入统一问题集合并继续其它可执行检查。只有该错误让后续检查前提失效时,才按“真正阻塞”规则暂停。
|
|
101
93
|
|
|
102
94
|
---
|
|
103
95
|
|
|
104
96
|
## Step 3:完整性、规范与项目验证
|
|
105
97
|
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
- 适用 spec 的读取方法;
|
|
109
|
-
- lint、typecheck、测试等项目验证命令;
|
|
110
|
-
- 测试覆盖、跨层数据流、复用、依赖和同层一致性检查;
|
|
111
|
-
- debug logging、warning suppression 和类型安全绕过检查。
|
|
112
|
-
|
|
113
|
-
### Audit-Only 覆盖规则
|
|
114
|
-
|
|
115
|
-
在 Check-All 内执行时,下列 `trellis-check` 指令一律失效:
|
|
116
|
-
|
|
117
|
-
- “Fix any failures before proceeding”;
|
|
118
|
-
- “fix them directly”;
|
|
119
|
-
- “Report and Fix”;
|
|
120
|
-
- 任何要求检查 agent 直接编辑、补测试或反复修到通过的语句。
|
|
121
|
-
|
|
122
|
-
验证失败时记录命令、退出状态和关键错误到统一问题集合,继续其它独立验证。可能写业务数据或外部系统的验证不直接运行:当前结论所必需且提交前原则上可完成时标记阻断型 `部分验证` 或 `阻塞`;本质依赖部署后、生产环境或真实外部状态时登记 `[上线后验证]`,不得自动执行。
|
|
123
|
-
|
|
124
|
-
### Maven Evidence 复用
|
|
125
|
-
|
|
126
|
-
实际变更位于 Maven reactor 时,按 `maven_verify.py` 的 evidence schema 只读执行:
|
|
127
|
-
|
|
128
|
-
```bash
|
|
129
|
-
python3 ./.trellis/scripts/maven_verify.py check --latest --require-plan <final-plan.json>
|
|
130
|
-
```
|
|
131
|
-
|
|
132
|
-
- `reusable`:核对 lifecycle、模块、消费者、测试、附属制品和 skip 项后纳入验证证据。
|
|
133
|
-
- `partial`:记录未覆盖的 module/consumer/test/artifact 或更高 lifecycle 要求。
|
|
134
|
-
- `stale`:记录源码、测试、POM、外部父 POM、Git 或工具链失效原因。
|
|
135
|
-
- `failed` / `blocked`:保留命令退出或证据损坏事实,不把未执行验证写成通过。
|
|
136
|
-
|
|
137
|
-
Check-All 与 dedicated subagent 都是 audit-only:不得调用 `maven_verify.py plan/run`,不得运行任何会写 `target/`、本地仓库或缓存的 Maven goal。缺少可复用 evidence 时,输出由主会话或 implement 路径执行的精确重跑计划需求;不得默认 `clean package/install`、`-amd` 或全 reactor。
|
|
98
|
+
执行 `references/verification.md` 的共享清单,汇总 Step 1/2 和项目 spec 的验证需求,复用有效证据并只执行未覆盖的必要命令。数据流沿用前两步证据,不重新完整追踪。
|
|
138
99
|
|
|
139
100
|
所有发现候选按 `references/fallback-findings.md` 先判定 `CHK-*` / `FBK-*`,再分配严重度。严重度不得反向决定通道;不满足三项硬准入的泛化建议不报告,保护收益或验证环境不完整则保留 FBK 并标记报告缺口。
|
|
140
101
|
|
|
@@ -1,18 +1,14 @@
|
|
|
1
1
|
# Light Profile
|
|
2
2
|
|
|
3
|
-
Light 是局部且可穷举的检查,不是“少看一点”的检查。只在 `check_profile.effective_depth=light`
|
|
3
|
+
Light 是局部且可穷举的检查,不是“少看一点”的检查。只在 `check_profile.effective_depth=light` 时读取本文件;共享验证规则见 `references/verification.md`。
|
|
4
4
|
|
|
5
5
|
---
|
|
6
6
|
|
|
7
7
|
## 适用边界
|
|
8
8
|
|
|
9
|
-
|
|
9
|
+
沿用 depth-routing 的 light 准入:闭合的语义范围、可穷举的规划与引用/状态/回归路径、无行为性 hard-full;载体名称不得单独触发升级。有定向验证,或变更确定不改变行为。
|
|
10
10
|
|
|
11
|
-
|
|
12
|
-
- 受影响规划条目、直接引用点、状态传播和回归路径能完整列出;
|
|
13
|
-
- 没有行为性 hard-full 信号,载体名称不得单独触发升级;
|
|
14
|
-
- 有定向验证,或变更确定不改变行为;
|
|
15
|
-
- 承接既有 full 报告的局部修复时,原 finding、修复路径、直接引用点和回归路径均可闭合,且定向验证足以覆盖后续 diff。
|
|
11
|
+
承接既有 full 报告的局部修复时,原 finding、修复路径和回归范围须闭合,定向证据须覆盖后续 diff。
|
|
16
12
|
|
|
17
13
|
执行中发现任一边界不成立,记录升级原因,切换到 `references/full-profile.md`。
|
|
18
14
|
|
|
@@ -22,15 +18,17 @@ Light 是局部且可穷举的检查,不是“少看一点”的检查。只
|
|
|
22
18
|
|
|
23
19
|
untracked 上下文没有 task artifacts,本维度标记 `N/A`,不得根据事项摘要伪造验收条目;直接进入实现假设和完整性/规范检查。
|
|
24
20
|
|
|
25
|
-
只提取受影响的 PRD / design / implement
|
|
21
|
+
只提取受影响的 PRD / design / implement 条目。同一行为合并验收并保留全部来源位置;不同约束、边界场景或冲突要求不得合并丢失。阅读对应实现后判断:
|
|
26
22
|
|
|
27
23
|
- 需求、AC、业务规则是否被本次局部变更影响;
|
|
28
24
|
- design 中相关 API、字段、数据流、rollback 是否仍成立;
|
|
29
|
-
- implement 中与本次 diff
|
|
25
|
+
- implement 中与本次 diff 直接相关、且前两者未覆盖的产物、review gate 和 rollback point 是否落地;
|
|
30
26
|
- UI 文案要求逐字一致时,对照最终有效文案来源。
|
|
31
27
|
|
|
32
28
|
未被本次变更触达且无直接依赖的规划条目标记 `N/A`,不得伪装为 full 已验证。
|
|
33
29
|
|
|
30
|
+
同一条调用链只追踪一次,后续维度复用实现位置和边界证据,只补未覆盖项或失效证据;复用不省略独立的验收判断。
|
|
31
|
+
|
|
34
32
|
---
|
|
35
33
|
|
|
36
34
|
## 维度 2:实现假设
|
|
@@ -43,31 +41,14 @@ untracked 上下文没有 task artifacts,本维度标记 `N/A`,不得根据
|
|
|
43
41
|
| Component Context | Modal、Drawer、Tab 或条件渲染容器内修改有状态组件 | 确认销毁/保留、受控值、初始化值和重置行为 |
|
|
44
42
|
| Data History | 新增、修改或重新解释持久化字段 | 确认 null/零值/历史记录降级;按验证阶段区分阻断型 `部分验证` 与 `[上线后验证]` |
|
|
45
43
|
| Data Flow Trace | 变更跨越 UI/API/Service/Storage 中两个或更多边界 | 连起来核对参数名、类型、嵌套层级和错误传播 |
|
|
46
|
-
| Verification Tests | A-D 任一适用 | 自动化测试优先;也可使用可重复的手动步骤、静态检查或定向命令覆盖关键假设 |
|
|
47
|
-
|
|
48
|
-
未触发的 Dimension 标记 `N/A`。
|
|
49
44
|
|
|
50
|
-
|
|
45
|
+
未触发的 Dimension 标记 `N/A`。触发维度先复用已有追踪结果,再补其新增约束;验证命令需求统一交给维度 3,不在各 Dimension 分别运行。
|
|
51
46
|
|
|
52
47
|
---
|
|
53
48
|
|
|
54
49
|
## 维度 3:完整性、规范与项目验证
|
|
55
50
|
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
- 适用 spec 的读取方法;
|
|
59
|
-
- 定向 lint、typecheck、测试或格式检查命令;
|
|
60
|
-
- 复用、依赖、同层一致性、debug logging、warning suppression 和类型安全绕过检查。
|
|
61
|
-
|
|
62
|
-
在 Check-All 内执行时,`trellis-check` 中任何直接修复、补测试、反复修到通过的指令一律失效。验证失败记录为 `CHK-*` 并继续其它独立验证。
|
|
63
|
-
|
|
64
|
-
实际变更位于 Maven reactor 时,按 `maven_verify.py` 的 evidence schema 只调用:
|
|
65
|
-
|
|
66
|
-
```bash
|
|
67
|
-
python3 ./.trellis/scripts/maven_verify.py check --latest --require-plan <final-plan.json>
|
|
68
|
-
```
|
|
69
|
-
|
|
70
|
-
`reusable` 计入定向验证;`partial` / `stale` / `failed` / `blocked` 记录精确验证缺口、原因和所需计划。Check-All 是 audit-only,不得调用 `plan` / `run` 或任何 Maven goal;Maven model/goal 可能写 `target/`、本地仓库或缓存。没有 Maven evidence 时不得无条件全仓构建,报告由主会话或 implement 路径执行的精确重跑需求。
|
|
51
|
+
执行 `references/verification.md` 中本次局部变更触发的检查,统一复用有效证据并执行未覆盖的定向验证。数据流沿用前两维证据,不重新完整追踪。
|
|
71
52
|
|
|
72
53
|
所有发现候选按 `references/fallback-findings.md` 先判定 `CHK-*` / `FBK-*`,再分配严重度。不得因场景极端、修复困难或影响较低改变根因通道;不满足三项硬准入的泛化建议不报告,保护收益或验证环境不完整则保留 FBK 并标记报告缺口。
|
|
73
54
|
|
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
# Maven Evidence
|
|
2
|
+
|
|
3
|
+
仅 Maven 变更加载本文件,按既有 evidence schema 只读核对 final evidence:
|
|
4
|
+
|
|
5
|
+
```bash
|
|
6
|
+
python3 ./.trellis/scripts/maven_verify.py check --latest --require-plan <final-plan.json>
|
|
7
|
+
```
|
|
8
|
+
|
|
9
|
+
- `reusable`:核对 lifecycle、模块、消费者、测试、附属制品和 skip 项后计入证据。
|
|
10
|
+
- `partial`:记录未覆盖的 module/consumer/test/artifact 或更高 lifecycle 要求。
|
|
11
|
+
- `stale`:记录源码、测试、POM、外部父 POM、Git 或工具链失效原因。
|
|
12
|
+
- `failed` / `blocked`:保留失败或证据损坏事实,不把未执行验证写成通过。
|
|
13
|
+
|
|
14
|
+
主会话和 dedicated subagent 都不得调用 `plan` / `run` 或任何 Maven goal,也不得运行会写 `target/`、本地仓库或缓存的构建。缺少可复用证据时报告由 implement 路径执行的精确重跑需求,不默认 `clean package/install`、`-amd` 或全 reactor。
|
package/enhancements/0.6/.agents/skills/trellis-check-all/references/reporting-and-disposition.md
CHANGED
|
@@ -56,7 +56,7 @@
|
|
|
56
56
|
4. 已接受问题继续完整展示证据、影响、建议和验证,标题行末尾追加 `` `[已接受风险]` `` 标签;不得删除条目、改列 `DOC-*` 或伪报已修复。
|
|
57
57
|
5. `strict pass` 只用于剩余 `CHK-*` / `FBK-*` 均为 0。所有剩余问题均已被有效接受,且无 blocked、无阻断型部分验证、无未接受的实质剩余风险时,结论为 `通过·已接受风险`。
|
|
58
58
|
6. blocked、阻断型部分验证和无法唯一对应当前报告范围的实质剩余风险不是 `CHK-*` / `FBK-*` 处置状态,不能借风险接受绕过;`[上线后验证]` 不属于风险接受对象。
|
|
59
|
-
7. `仅保留报告`
|
|
59
|
+
7. `仅保留报告` 表示停止处置并等待,不等于接受风险,也不授权写文件;只有带明确接受语义的用户回复才改变问题处置状态。
|
|
60
60
|
|
|
61
61
|
## 验证阶段
|
|
62
62
|
|
|
@@ -68,11 +68,22 @@
|
|
|
68
68
|
|
|
69
69
|
## 输出:统一检查报告
|
|
70
70
|
|
|
71
|
-
|
|
71
|
+
报告默认在对话中完整展示,不得为了缩短回复、提供链接、留存结论或同步任务状态新建 `check-report.md` 等附件,也不得用附件链接代替应展示的内容。
|
|
72
|
+
|
|
73
|
+
仅用户明确要求导出或已确认的交付约定要求文件时,由主会话保存,不得自行补写约定。Maven、auto-loop 沿用各自机器证据契约,不额外生成 Markdown。已有报告不自动删除或复制。
|
|
74
|
+
|
|
75
|
+
interactive 完成检查与允许的 DOC 修复后,先自然说明实际改动、行为影响和结论,再展示证据与问题:
|
|
76
|
+
|
|
77
|
+
- 依据当前审查范围的最终 diff 和已读实现,覆盖 staged、unstaged、未跟踪文件及必要的子仓;复用检查时收集的材料,不额外启动 Diff Brief 流程或重复扫描。
|
|
78
|
+
- 按行为说明改前后的差异,只有证据支持时才描述旧行为;无行为变化时说明文档、测试或生成物调整,不罗列文件。
|
|
79
|
+
- 区分已实现、已验证和仍未解决的内容;计划中的功能不得写成已经交付,未归属本次范围的 dirty 不得混入。阻塞或重大问题在开头说明,不能被改动介绍掩盖。
|
|
80
|
+
- 自然段不另设固定字段或空项,按复杂度展开。重检只解释本轮修复及其影响。随后保留完整问题、风险和下一步。
|
|
72
81
|
|
|
73
82
|
```markdown
|
|
74
83
|
## Trellis Check-All 结果
|
|
75
84
|
|
|
85
|
+
<用自然语言说明实际改动、行为影响和检查结论;不逐文件罗列,不复述规划>
|
|
86
|
+
|
|
76
87
|
[<通过/通过·已接受风险/未通过/阻塞>] <N> 个维度 · CHK <N>(接受 <N>)· FBK <N>(接受 <N>)· 自动修复 DOC <N> · P0 <N> / P1 <N> / P2 <N> · 验证 <通过>/<总数>
|
|
77
88
|
|
|
78
89
|
- **工作**:<任务名称 | Untracked work: work-id | 无活动工作>
|
|
@@ -143,6 +154,7 @@ interactive 模式完成所有可继续检查和允许的 `DOC-*` 自动修复
|
|
|
143
154
|
|
|
144
155
|
展示规则:
|
|
145
156
|
|
|
157
|
+
- strict pass 且无剩余问题时可紧凑表述,保留模板顺序、画像、维度、实际验证、DOC(如有)、风险和下一步,省略空区块;不得缩减实际检查范围。有问题或已接受风险时完整展示问题字段与处置。
|
|
146
158
|
- 报告头部“工作/范围/画像/结论”和“修复批次”必须使用 `- ` 列表项,不得改为裸行或依赖行尾空格。
|
|
147
159
|
- 每个问题必须由一个四级标题承载,固定顺序为 `` #### `<ID>` `<严重度>` `<来源>` <标题> ``。仅 `已接受风险` 的问题在标题末尾追加 `` `[已接受风险]` ``;待处理不加标签。`来源` 与 `处置` 都不再单独占行。
|
|
148
160
|
- 不得改用 `- [ ]` / `- [x]` 列表项承载问题条目。终端渲染器会把松散列表压平,相邻条目会糊成一段无法分辨;只有标题这类块级元素才能稳定产生视觉分隔。修复状态由“修复结果”表格表达,不靠 checkbox。
|
|
@@ -154,7 +166,6 @@ interactive 模式完成所有可继续检查和允许的 `DOC-*` 自动修复
|
|
|
154
166
|
- 存在未处置 `CHK-*` 或 `FBK-*` 时展示“修复批次”,并只在报告末尾提供一次处置选择,不再逐项提问。
|
|
155
167
|
- `修复全部` 始终覆盖全部 `CHK-*` 与 `FBK-*`;精确修复可以混合两类 ID。
|
|
156
168
|
- 风险接受可混合两类 ID;“接受当前报告全部风险”覆盖全部剩余问题,包括 P0,无固定句式。全部有效接受后才形成“通过·已接受风险”。
|
|
157
|
-
- `仅保留报告` 只表示停止处置,不改变未通过结论或剩余风险。
|
|
158
169
|
- interactive 标准报告必须以“下一步”段结束;停止等待不等于省略引导。
|
|
159
170
|
- 独立 `CHK-*` 或 `FBK-*` 不得因数量多而静默省略;先合并同根因重复项,再完整列出剩余项。
|
|
160
171
|
- 报告不得包含 commit message、拟提交/暂存文件、commit-only 决策或提交确认。
|
|
@@ -177,6 +188,8 @@ interactive 模式完成所有可继续检查和允许的 `DOC-*` 自动修复
|
|
|
177
188
|
```markdown
|
|
178
189
|
## Trellis Check-All 修复结果
|
|
179
190
|
|
|
191
|
+
<用自然语言说明本轮实际修复、修复后的行为和重检结论>
|
|
192
|
+
|
|
180
193
|
[<完成/部分完成/失败>] CHK 修复 <完成>/<计划> · FBK 修复 <完成>/<计划> · DOC 自动修复 <N> · 验证 <通过>/<总数> · 剩余 CHK <N> · 剩余 FBK <N>
|
|
181
194
|
|
|
182
195
|
| 问题 | 修复 | 验证 |
|
|
@@ -196,7 +209,7 @@ interactive 模式完成所有可继续检查和允许的 `DOC-*` 自动修复
|
|
|
196
209
|
<按下方 `Interactive Post-Check Stop Gate` 输出一个明确、可执行的主动作>
|
|
197
210
|
```
|
|
198
211
|
|
|
199
|
-
|
|
212
|
+
重检后按下方 `Interactive Post-Check Stop Gate` 分流;仍有未处置 `CHK-*` 或 `FBK-*` 时停留在处置/重检循环。
|
|
200
213
|
|
|
201
214
|
untracked helper 不存检查证据或风险接受。普通通过后保持 `stage=check`;direct Git 同轮继续或用户明确继续才 `advance --stage spec`。未处置 `CHK-*` / `FBK-*`、阻断型部分验证、阻塞或新编辑先 `advance --stage implement`;仅 `[上线后验证]` 不回退。
|
|
202
215
|
|
|
@@ -237,14 +250,6 @@ subagent 只返回结构化 `CHK-*`、`FBK-*`、`DOC-*` 候选、报告和 `chec
|
|
|
237
250
|
|
|
238
251
|
停止边界只控制是否自动推进,不能让报告在没有下一步提示的情况下结束。
|
|
239
252
|
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
- 各维度状态、问题数和问题清单;
|
|
243
|
-
- `CHK-*` 主路径问题和 `FBK-*` 兜底问题的证据、影响与验证;
|
|
244
|
-
- `DOC-*` 自动修复内容和验证;
|
|
245
|
-
- 已执行验证及结果;
|
|
246
|
-
- 未覆盖验证、`[上线后验证]` 和剩余风险;
|
|
247
|
-
- 总体结论;
|
|
248
|
-
- 与当前结论匹配的唯一主动作引导;有未处置 `CHK-*` 或 `FBK-*` 时是一次修复或风险接受选择,部分验证/阻塞时是补充决策或验证,通过时是 Phase 3.3 / Phase 3.4 指向。
|
|
253
|
+
标准报告仅包含上方统一模板定义的检查内容和本 Gate 的唯一主动作。
|
|
249
254
|
|
|
250
255
|
Check-All 不新增 direct Git 摘要或 Git 计划;这些仍由 Update-Spec 与 Push 所有。`[上线后验证]` 交给 Push 风险摘要和既有 `trellis-release` / `release.md`。
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
# Verification
|
|
2
|
+
|
|
3
|
+
Light / Full 共用本清单,检查范围由当前 profile 决定。复用 Step 0 已读规范和前两维的源码证据,不再加载 `trellis-check` 或继承其自修复流程。
|
|
4
|
+
|
|
5
|
+
## 完整性与规范
|
|
6
|
+
|
|
7
|
+
- 按受影响包的 spec Quality Check 核对本次变更;已读且未变化的规范直接复用。
|
|
8
|
+
- 核对漏改的调用方、批量修改遗漏、生成或分发产物、导入路径、循环依赖和同概念的行为一致性;数据流复用前两维追踪,仅补未覆盖边界。
|
|
9
|
+
- 检查遗留 debug logging、warning suppression、类型安全绕过及项目明确禁止的模式。
|
|
10
|
+
- 格式、语法和静态类型由已覆盖当前范围的工具结果证明;人工只补工具未覆盖的语义风险。
|
|
11
|
+
- 不因新增函数就要求一份对应单测,也不因两处值相同就要求抽公共常量。只有真实的回归或一致性风险、错误抽象、遗漏同步或项目明确约定才构成检查依据;不得要求与本次任务无关的重构。
|
|
12
|
+
|
|
13
|
+
## 统一验证与证据复用
|
|
14
|
+
|
|
15
|
+
1. 汇总验收、假设维度和项目 spec 的验证需求。自动化测试优先;可重复的手动步骤、静态检查或定向命令也可作为证据,覆盖关键参数、历史数据、空值和错误路径。
|
|
16
|
+
2. 优先核对已有实际命令输出,包括实现阶段和先前检查的结果:命令、工作目录、覆盖范围、退出状态明确,且相关源码、测试、配置和工具链未变化才可复用。只写“测试通过”的摘要、测试文件存在或无法确认适用范围均不足以复用。
|
|
17
|
+
3. 相同工作目录、命令参数、环境与被测内容的验证只执行一次;覆盖关系明确时复用较完整的结果,多个维度引用同一证据。不同条件不得去重,测试过滤范围、跳过项和未执行项不能算作已覆盖。
|
|
18
|
+
4. 缺失、失败或失效的证据按当前范围补跑必要命令;未变化且已覆盖的检查不重复运行。失败保留退出状态和关键错误,继续其它独立验证;无法完成必需验证时如实标记 `部分验证` 或 `阻塞`。
|
|
19
|
+
5. 仅缺少自动化测试文件不得生成 `CHK-*`;项目 spec、风险等级或回归概率明确要求自动化覆盖时,缺失测试仍记录问题。缺少完成当前结论所必需的充分证据时记录 `CHK-*`;不得用证据复用跳过必需回归或伪报已运行。
|
|
20
|
+
|
|
21
|
+
同一证据可以支持多个维度,报告中的验证次数按实际独立验证统计,不按引用次数累加。新编辑或 DOC 修复后重新判断受影响证据,仅复查变化及其依赖;影响面不闭合时按 depth-routing 升级。
|
|
22
|
+
|
|
23
|
+
## 只读边界
|
|
24
|
+
|
|
25
|
+
Check-All 不直接修复代码、配置或测试。只执行无业务写入副作用的验证;可能写业务数据或外部系统的命令不运行,按 reporting reference 区分阻断型部分验证与 `[上线后验证]`。专用 subagent 还必须遵守其宿主的只读工具限制。
|
|
26
|
+
|
|
27
|
+
### Maven Evidence
|
|
28
|
+
|
|
29
|
+
实际变更位于 Maven reactor 时才读取 `references/maven-evidence.md`。主会话和 dedicated subagent 都不得调用 `plan` / `run` 或任何 Maven goal,只读核对现有 final evidence。
|
|
@@ -12,26 +12,29 @@ description: "手动检查和执行已安装 Flower/Trellis 强化包升级。
|
|
|
12
12
|
## Workflow
|
|
13
13
|
|
|
14
14
|
1. 确认目标项目。用户给出路径时使用该路径,否则使用当前工作目录。
|
|
15
|
-
2.
|
|
15
|
+
2. 检查 `flower-trellis` 是否可执行。缺失或入口异常且目标项目存在 `.trellis/scripts/flower_update_hook.py` 时,先运行目标项目的检测脚本:`python3 <target>/.trellis/scripts/flower_update_hook.py --bootstrap-only --target <target>`(路径按当前 shell 引用,Python 命令沿用项目配置)。遵循返回的 `<flower-cli-bootstrap>`:先征得当前成员确认,再安装锁定版本并验证;当前对话已授权这次安装时不重复确认。脚本不存在时说明项目缺少安装引导入口,不猜版本安装。未安装成功则停止依赖 CLI 的步骤,不循环追问或安装。
|
|
16
|
+
3. CLI 可用后运行人工检查,默认强制刷新远端版本证据:
|
|
16
17
|
|
|
17
18
|
```bash
|
|
18
19
|
flower-trellis self-check --json --manual --force-remote --target <target>
|
|
19
20
|
```
|
|
20
21
|
|
|
21
|
-
|
|
22
|
+
4. 解析 JSON:
|
|
22
23
|
- `update_available`:展示当前版本、推荐版本、release notes 摘要和 `commands.recommended`。
|
|
23
24
|
- `project_out_of_sync`:展示当前 Flower/Trellis 与项目记录的差异,并展示 `commands.recommended`。
|
|
24
|
-
- `up_to_date
|
|
25
|
+
- `up_to_date`:说明 CLI 与项目版本记录一致;版本记录不等于受管内容完整性验证。
|
|
26
|
+
- `project_unknown`:说明 CLI 未发现新版,但项目 Flower 版本无法确认。linked worktree 进入 `trellis-worktree` 的 Flower Preparation,通过 `prepare --inherit-flower --source <source>` 补齐可验证记录后重新检查;来源缺失或冲突时如实报告,不推定需要重装。
|
|
25
27
|
- `disabled` / `offline` / `skipped`:说明原因;不要靠重置缓存伪造可执行状态。
|
|
26
|
-
|
|
28
|
+
5. 写入前遵守确认和安全门槛:
|
|
27
29
|
- 用户当前消息已经明确要求执行升级时,可以执行 `commands.recommended`。
|
|
28
30
|
- 用户只是询问、查看或比较版本时,只展示结果并等待确认。
|
|
29
31
|
- `safety.reasons` 非空时,先说明风险,再等待用户明确确认。
|
|
30
|
-
|
|
32
|
+
6. 执行推荐命令后读取 `<flower-update-result>`。如果结果要求 `run_trellis_push_confirmation`,进入 `trellis-push`,展示文件和 commit message 后等待确认。
|
|
31
33
|
|
|
32
34
|
## Rules
|
|
33
35
|
|
|
34
36
|
- 不直接读写 `.flower/update-check.tmp`。
|
|
37
|
+
- 无论远端查询结果如何,都单独说明 `project.flowerVersionStatus=unknown`;不得用本机 CLI 版本替代项目安装证据。
|
|
35
38
|
- 不使用 `update-check reset`、`snooze` 或 `skip` 作为升级绕过手段。
|
|
36
39
|
- 不运行 `npm run release`、不打 tag、不 publish,也不修改 `package.json` 版本号。
|
|
37
40
|
- 不把 `self-check --manual` 用在 SessionStart 自动 hook;自动路径必须继续尊重提示节流。
|
|
@@ -118,7 +118,9 @@ git log @{u}..HEAD --oneline 2>/dev/null || true
|
|
|
118
118
|
|
|
119
119
|
命令必须是受版本控制的稳定入口,并且本地、确定性、可重复、无外部副作用。工作目录和预期影响路径必须可审计;只有名称相似、mtime、目录邻近或惯例不足以执行。禁止任意 shell 字符串、管道、重定向、命令替换、push、release、deploy、archive、凭证和生产数据操作;证据不足时失败关闭。
|
|
120
120
|
|
|
121
|
-
`retained` 只是内部集合名。用户可见输出统一写“保留未提交的变更(dirty
|
|
121
|
+
`retained` 只是内部集合名。用户可见输出统一写“保留未提交的变更(dirty)”,按输出 reference 的阈值展示;内部始终保留 exact paths 和 Git 状态,分组摘要不得用于 pathspec 或替代校验。unknown ahead、branch/upstream 异常、归属不确定等真正需要处理的事项单独进入“风险”区;普通 retained dirty 不默认视为阻塞。
|
|
122
|
+
|
|
123
|
+
普通模式和用户 `commit-only` 的计划与校验基线默认保存在当前执行上下文。仅跨进程校验或中断恢复确需落盘时,才在 Git 忽略的 runtime 目录保存一份必要的临时 JSON;已有可复用记录时不另建副本。不得仅为缩短对话、提供链接或展示完整清单生成 `retained.md` 等清单附件,也不把临时计划写入任务产物或提交范围。auto-loop 沿用 runner 的既有持久化契约,不增加额外清单。
|
|
122
124
|
|
|
123
125
|
普通模式允许 `retained` 存在。执行前记录计划外 staged set,提交后确认这些 staged 文件仍保持原状。用户明确要求新增文件时,重新生成计划并确认,不能在执行中静默扩大范围。
|
|
124
126
|
|
|
@@ -30,9 +30,8 @@
|
|
|
30
30
|
[生成(多仓需要时显示):前置仓成功后,在 `<working-directory>` 运行 `<exact local command>`;预计只影响 <后续仓 exact files 或分组摘要>]
|
|
31
31
|
|
|
32
32
|
### 保留未提交的变更(dirty,仅数量大于 0 时显示)
|
|
33
|
-
-
|
|
34
|
-
- [
|
|
35
|
-
- [staged] <path>
|
|
33
|
+
- <按共用规则逐项展示或按仓库、目录、Git 状态汇总数量>
|
|
34
|
+
- [staged] <repository/path>(仅存在时逐项显示,兼有未暂存修改时同时标注 [unstaged])
|
|
36
35
|
|
|
37
36
|
### 风险(仅数量大于 0 时显示)
|
|
38
37
|
- <Check-All / Update-Spec 风险,或 unknown ahead / branch-upstream / attribution risk>
|
|
@@ -45,7 +44,7 @@
|
|
|
45
44
|
- **进度**:completed=<...> | partial=<...> | next=<...>
|
|
46
45
|
- **执行**:<business commit/push -> `task_progress.py write --complete` -> task-record commit -> task-record push>
|
|
47
46
|
|
|
48
|
-
确认执行请回复 `确认`。可调整:`只提交`、`修改 message
|
|
47
|
+
确认执行请回复 `确认`。可调整:`只提交`、`修改 message`、`展开文件`、`展开保留变更`。
|
|
49
48
|
```
|
|
50
49
|
|
|
51
50
|
## 共用展示规则
|
|
@@ -55,7 +54,9 @@
|
|
|
55
54
|
- 单仓 `planned` 不超过 8 个文件时完整列出。
|
|
56
55
|
- 超过 8 个时按目录归组,最多 12 行;用户要求展开时展示同一 exact set。
|
|
57
56
|
- 顶部仓库/commit/file 总数包含独立任务记录提交所在 Git root、该提交及其 exact files;任务记录文件使用相同的 8 文件展示阈值和展开规则。
|
|
58
|
-
-
|
|
57
|
+
- 计划中的保留变更按仓库计数:不超过 8 项时逐项标注 `[untracked]`、`[unstaged]`、`[staged]`;超过 8 项时将非 staged 项按目录与 Git 状态汇总数量,每仓最多 12 行,必要时合并到上级目录。同一路径计数一次,兼有 staged/unstaged 时同时标注。
|
|
58
|
+
- 计划外 staged 项始终逐项单列,不计入分组摘要;真正风险在独立“风险”区逐项展示,两者均不受行数限制。分组、展开均只改变展示,不改变 exact set 或确认范围。
|
|
59
|
+
- 用户要求“展开保留变更”时在对话中列出同一 exact set 与 Git 状态,不生成清单附件;“展开文件”仍指 planned files。
|
|
59
60
|
- 完成链证据始终显示当前状态,但不重复 Check-All 报告或 Spec review 正文;`未运行`、`已失效`、任一未处置 `CHK-*` / `FBK-*`、blocked、部分验证或 `needs-review` 同时计入风险区。已接受风险的问题也必须按 ID、严重度和影响进入风险区,但不得改标为阻断 finding。`[上线后验证]` 作为非阻断风险逐项保留动作、环境/责任边界和预期结果,不改变 Check-All 状态,并注明由既有 `trellis-release` / `release.md` 流程承接。
|
|
60
61
|
- 无活动 task、untracked 或 `commit-only` 时省略进度动作。
|
|
61
62
|
- 不重复展示检查结果、规范复核、归档或其他阶段的详细信息。
|
|
@@ -85,15 +86,13 @@
|
|
|
85
86
|
- **失败原因**:<原因和恢复动作>(仅失败时显示)
|
|
86
87
|
|
|
87
88
|
### 保留未提交的变更(dirty,仅存在时显示)
|
|
88
|
-
-
|
|
89
|
-
- [unstaged] <path>
|
|
90
|
-
- [staged] <path>
|
|
89
|
+
- <按仓库报告保留数量与实际核对结论;异常或未核验项逐项说明>
|
|
91
90
|
```
|
|
92
91
|
|
|
93
92
|
## 结果补充规则
|
|
94
93
|
|
|
95
94
|
- untracked 结果用“无任务状态”替代“任务进度”,展示 work id 与 `<已清理/保留待恢复>`;不生成或暗示 task progress commit。
|
|
96
95
|
- 部分完成时必须明确列出已成功仓库、失败仓库/步骤、当前分支和下一恢复动作。业务结果与 progress sync 状态不得合并成一个模糊结论。
|
|
97
|
-
- 普通成功结果必须确认本任务产生的当前任务目录变更 clean
|
|
96
|
+
- 普通成功结果必须确认本任务产生的当前任务目录变更 clean。其它 retained dirty 已核对保持原状时,每仓只报告数量与结论,不重复清单;计划外 staged 项仍逐项确认保留状态。异常或未核验项列出路径、实际状态和处理情况,不得笼统声称全部保持原状;用户要求展开时沿用共用规则。
|
|
98
97
|
- helper 成功但任务记录 commit 失败时,结果写“任务记录 commit 待恢复”,说明本地 `completed` 与 exact task dirty 已保留;任务记录 commit 成功但 push 失败时写“任务记录 push 待恢复”,说明 clean ahead commit 已保留。两种情况都不得暗示需要重复业务提交或 helper 写入。
|
|
99
98
|
- validated auto-loop local completion 不渲染本模板,也不得被普通结果文案描述为任务记录 push 待恢复。
|