agentic-flow-kit 1.7.15 → 1.8.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 +50 -8
- package/modules/hosts/claude/commands/wf-build.md +1 -1
- package/modules/hosts/claude/commands/wf-design.md +5 -4
- package/modules/hosts/claude/commands/wf-maintain.md +1 -1
- package/modules/hosts/claude/commands/wf-new-task.md +47 -25
- package/modules/hosts/claude/commands/wf-plan.md +1 -1
- package/modules/hosts/claude/commands/wf-review.md +2 -2
- package/modules/hosts/claude/commands/wf-sync-hosts.md +7 -13
- package/modules/hosts/claude/commands/wf-test.md +2 -2
- package/modules/hosts/codex/commands/wf-build.md +1 -1
- package/modules/hosts/codex/commands/wf-design.md +5 -4
- package/modules/hosts/codex/commands/wf-maintain.md +1 -1
- package/modules/hosts/codex/commands/wf-new-task.md +47 -25
- package/modules/hosts/codex/commands/wf-plan.md +1 -1
- package/modules/hosts/codex/commands/wf-review.md +2 -2
- package/modules/hosts/codex/commands/wf-sync-hosts.md +7 -13
- package/modules/hosts/codex/commands/wf-test.md +2 -2
- package/modules/hosts/cursor/commands/wf-build.md +1 -1
- package/modules/hosts/cursor/commands/wf-design.md +5 -4
- package/modules/hosts/cursor/commands/wf-maintain.md +1 -1
- package/modules/hosts/cursor/commands/wf-new-task.md +47 -25
- package/modules/hosts/cursor/commands/wf-plan.md +1 -1
- package/modules/hosts/cursor/commands/wf-review.md +2 -2
- package/modules/hosts/cursor/commands/wf-sync-hosts.md +7 -13
- package/modules/hosts/cursor/commands/wf-test.md +2 -2
- package/modules/hosts/opencode/commands/wf-build.md +1 -1
- package/modules/hosts/opencode/commands/wf-design.md +5 -4
- package/modules/hosts/opencode/commands/wf-maintain.md +1 -1
- package/modules/hosts/opencode/commands/wf-new-task.md +47 -25
- package/modules/hosts/opencode/commands/wf-plan.md +1 -1
- package/modules/hosts/opencode/commands/wf-review.md +2 -2
- package/modules/hosts/opencode/commands/wf-sync-hosts.md +7 -13
- package/modules/hosts/opencode/commands/wf-test.md +2 -2
- package/modules/hosts/trae/commands/wf-build.md +1 -1
- package/modules/hosts/trae/commands/wf-design.md +5 -4
- package/modules/hosts/trae/commands/wf-maintain.md +1 -1
- package/modules/hosts/trae/commands/wf-new-task.md +47 -25
- package/modules/hosts/trae/commands/wf-plan.md +1 -1
- package/modules/hosts/trae/commands/wf-review.md +2 -2
- package/modules/hosts/trae/commands/wf-sync-hosts.md +7 -13
- package/modules/hosts/trae/commands/wf-test.md +2 -2
- package/package.json +1 -1
- package/src/cli.mjs +47 -4
- package/src/doctor.mjs +48 -3
- package/src/executor.mjs +262 -0
- package/src/executor.test.mjs +295 -0
- package/src/fresh-init.test.mjs +1 -1
- package/src/init.mjs +27 -3
- package/src/profiles.mjs +10 -3
- package/src/render.mjs +3 -3
- package/src/rule-budget.test.mjs +2 -2
- package/src/stack-profile.test.mjs +6 -0
- package/src/sync-hosts.mjs +37 -43
- package/src/sync-hosts.test.mjs +67 -56
- package/src/validate.mjs +6 -1
- package/src/validate.test.mjs +1 -1
- package/templates/.gitattributes +12 -1
- package/templates/AGENTS.md +3 -3
- package/templates/_agents/commands/build.md +1 -1
- package/templates/_agents/commands/design.md +5 -4
- package/templates/_agents/commands/maintain.md +1 -1
- package/templates/_agents/commands/new-task.md +47 -25
- package/templates/_agents/commands/plan.md +1 -1
- package/templates/_agents/commands/review.md +2 -2
- package/templates/_agents/commands/sync-hosts.md +7 -13
- package/templates/_agents/commands/test.md +2 -2
- package/templates/_agents/control-surfaces.txt +1 -1
- package/templates/_agents/engine-lock.json +334 -0
- package/templates/_agents/hooks/check-index-incremental.mjs +48 -0
- package/templates/_agents/hooks/check-pairing-incremental.mjs +66 -0
- package/templates/_agents/hooks/check-wiki-ledger.mjs +30 -0
- package/templates/_agents/lane-surfaces.txt +5 -2
- package/templates/_agents/level-hints.txt +30 -0
- package/templates/_agents/loop/papercut-debt/DESIGN.md +112 -0
- package/templates/_agents/mechanism-registry.md +27 -0
- package/templates/_agents/rule-budgets.txt +2 -2
- package/templates/_agents/scripts/agg-delegations.cjs +21 -3
- package/templates/_agents/scripts/agg-delegations.test.mjs +5 -3
- package/templates/_agents/scripts/agg-gate-stats.mjs +3 -3
- package/templates/_agents/scripts/agg-judgments.mjs +80 -0
- package/templates/_agents/scripts/agg-judgments.test.mjs +45 -0
- package/templates/_agents/scripts/archive-sweep.mjs +233 -0
- package/templates/_agents/scripts/archive-sweep.test.mjs +129 -0
- package/templates/_agents/scripts/check-attribution.mjs +37 -0
- package/templates/_agents/scripts/check-convergence.mjs +119 -0
- package/templates/_agents/scripts/check-engine-integrity.mjs +59 -127
- package/templates/_agents/scripts/check-engine-integrity.test.mjs +33 -45
- package/templates/_agents/scripts/check-funnel.mjs +56 -0
- package/templates/_agents/scripts/check-hygiene.mjs +5 -5
- package/templates/_agents/scripts/check-index-incremental.test.mjs +73 -0
- package/templates/_agents/scripts/check-lane-surface.mjs +74 -25
- package/templates/_agents/scripts/check-lane-surface.test.mjs +71 -5
- package/templates/_agents/scripts/check-ledger-invariant.mjs +427 -78
- package/templates/_agents/scripts/check-ledger-invariant.test.mjs +438 -4
- package/templates/_agents/scripts/check-loop-rev.test.mjs +13 -8
- package/templates/_agents/scripts/check-loop-unit.test.mjs +8 -0
- package/templates/_agents/scripts/check-loop.mjs +264 -75
- package/templates/_agents/scripts/check-loop.test.mjs +587 -61
- package/templates/_agents/scripts/check-metric-claims.mjs +4 -2
- package/templates/_agents/scripts/check-prejudgment.mjs +59 -0
- package/templates/_agents/scripts/check-registry.mjs +45 -0
- package/templates/_agents/scripts/check-scope.mjs +96 -0
- package/templates/_agents/scripts/check-scope.test.mjs +96 -0
- package/templates/_agents/scripts/check-scripts-syntax.mjs +61 -0
- package/templates/_agents/scripts/check-scripts-syntax.test.mjs +72 -0
- package/templates/_agents/scripts/check-spec-verif.mjs +47 -0
- package/templates/_agents/scripts/compact-ledgers.mjs +97 -0
- package/templates/_agents/scripts/compact-ledgers.test.mjs +162 -0
- package/templates/_agents/scripts/confirm-doc.mjs +136 -31
- package/templates/_agents/scripts/confirm-doc.test.mjs +180 -4
- package/templates/_agents/scripts/doctor.test.mjs +44 -1
- package/templates/_agents/scripts/edit-face-check.mjs +5 -3
- package/templates/_agents/scripts/edit-face-check.test.mjs +5 -4
- package/templates/_agents/scripts/fill-intent.mjs +7 -5
- package/templates/_agents/scripts/fill-intent.test.mjs +19 -1
- package/templates/_agents/scripts/fill-plan.mjs +10 -6
- package/templates/_agents/scripts/fill-plan.test.mjs +19 -3
- package/templates/_agents/scripts/fill-spec.mjs +6 -3
- package/templates/_agents/scripts/fill-spec.test.mjs +12 -4
- package/templates/_agents/scripts/fixture-scripts.mjs +153 -0
- package/templates/_agents/scripts/fixture-scripts.test.mjs +112 -0
- package/templates/_agents/scripts/gate-checklist.mjs +10 -9
- package/templates/_agents/scripts/gate-checklist.test.mjs +2 -11
- package/templates/_agents/scripts/gate-seg.mjs +1 -1
- package/templates/_agents/scripts/gen-effective-policy.mjs +107 -0
- package/templates/_agents/scripts/gen-effective-policy.test.mjs +100 -0
- package/templates/_agents/scripts/gen-verify-evidence.mjs +107 -0
- package/templates/_agents/scripts/gen-verify-evidence.test.mjs +84 -0
- package/templates/_agents/scripts/gen-workflow-dashboard.mjs +16 -14
- package/templates/_agents/scripts/gen-workflow-dashboard.test.mjs +2 -1
- package/templates/_agents/scripts/gen-workflow-metrics.mjs +12 -36
- package/templates/_agents/scripts/git-core.mjs +45 -0
- package/templates/_agents/scripts/git-merge-jsonl.mjs +63 -0
- package/templates/_agents/scripts/git-merge-jsonl.test.mjs +125 -0
- package/templates/_agents/scripts/judgment-ledger.mjs +65 -0
- package/templates/_agents/scripts/judgment-ledger.test.mjs +129 -0
- package/templates/_agents/scripts/kb-search.mjs +19 -4
- package/templates/_agents/scripts/kb-search.test.mjs +33 -0
- package/templates/_agents/scripts/lane-surface-audit.mjs +143 -0
- package/templates/_agents/scripts/lane-surface-audit.test.mjs +93 -0
- package/templates/_agents/scripts/ledger-doc-chain.test.mjs +166 -0
- package/templates/_agents/scripts/ledger-loader.mjs +108 -0
- package/templates/_agents/scripts/ledger-loader.test.mjs +131 -0
- package/templates/_agents/scripts/ledger-prune.mjs +96 -0
- package/templates/_agents/scripts/ledger-prune.test.mjs +120 -0
- package/templates/_agents/scripts/ledger-shards.mjs +307 -0
- package/templates/_agents/scripts/ledger-shards.test.mjs +339 -0
- package/templates/_agents/scripts/ledger-ts-monotonic.test.mjs +135 -0
- package/templates/_agents/scripts/level-criteria.mjs +231 -0
- package/templates/_agents/scripts/level-criteria.test.mjs +281 -0
- package/templates/_agents/scripts/papercut-debt-controller.mjs +141 -0
- package/templates/_agents/scripts/papercut-debt-controller.test.mjs +127 -0
- package/templates/_agents/scripts/papercut-debt-sensor.mjs +170 -0
- package/templates/_agents/scripts/papercut-debt-sensor.test.mjs +146 -0
- package/templates/_agents/scripts/pipeline-run.mjs +10 -24
- package/templates/_agents/scripts/pipeline-run.test.mjs +22 -42
- package/templates/_agents/scripts/policy.mjs +75 -0
- package/templates/_agents/scripts/resolve-merge-conflicts.mjs +110 -0
- package/templates/_agents/scripts/resolve-merge-conflicts.test.mjs +87 -0
- package/templates/_agents/scripts/rewrite-file.mjs +133 -0
- package/templates/_agents/scripts/rewrite-file.test.mjs +148 -0
- package/templates/_agents/scripts/rule-budget.mjs +83 -0
- package/templates/_agents/scripts/run-tests.mjs +99 -0
- package/templates/_agents/scripts/run-tests.test.mjs +105 -0
- package/templates/_agents/scripts/solidify-task.test.mjs +1 -1
- package/templates/_agents/scripts/stage-gates.mjs +38 -21
- package/templates/_agents/scripts/trust-mode.mjs +4 -4
- package/templates/_agents/scripts/trust-mode.test.mjs +1 -1
- package/templates/_agents/scripts/verify.mjs +135 -58
- package/templates/_agents/scripts/verify.test.mjs +156 -47
- package/templates/_agents/scripts/wf-journal.mjs +8 -4
- package/templates/_agents/scripts/wf-journal.test.mjs +1 -1
- package/templates/_agents/scripts/wiki-search.test.mjs +5 -6
- package/templates/_agents/scripts/workflow-board-server.test.mjs +2 -2
- package/templates/_agents/scripts/workflow-enums.test.mjs +14 -5
- package/templates/_agents/scripts/workflows-check.mjs +1 -1
- package/templates/_agents/scripts-test-exempt.txt +1 -0
- package/templates/_agents/skills/papercut-fix/SKILL.md +60 -0
- package/templates/_agents/skills/papercut-fix/references/response-template.md +81 -0
- package/templates/_agents/workflow-enums.txt +8 -1
- package/templates/_agents/workflows/pipeline-closing.md +4 -5
- package/templates/_githooks/pre-commit +109 -120
- package/templates/_githooks/pre-merge-commit +27 -23
- package/templates/_githooks/pre-push +7 -6
- package/templates/_github/workflows/kit-ci.yml +4 -3
- package/templates/workflow/README.md +23 -5
- package/templates/workflow/incidents/_TEMPLATE.md +4 -1
- package/templates/workflow/intents/_TEMPLATE.md +4 -2
- package/templates/workflow/papercuts.md +2 -0
- package/templates/workflow/plans/_TEMPLATE.md +10 -5
- package/templates/workflow/regression-checklist.md +1 -0
- package/templates/workflow/specs/_TEMPLATE.md +17 -1
- package/modules/hosts/claude/commands/wf-source-sync-check.md +0 -89
- package/modules/hosts/codex/commands/wf-source-sync-check.md +0 -89
- package/modules/hosts/cursor/commands/wf-source-sync-check.md +0 -89
- package/modules/hosts/opencode/commands/wf-source-sync-check.md +0 -89
- package/modules/hosts/trae/commands/wf-source-sync-check.md +0 -90
- package/templates/_agents/commands/source-sync-check.md +0 -103
- package/templates/_agents/hooks/check-pairing-incremental.sh +0 -43
- package/templates/_agents/hooks/check-wiki-ledger.sh +0 -18
- package/templates/_agents/scripts/check-ledger.mjs +0 -109
- package/templates/_agents/scripts/check-ledger.test.mjs +0 -199
- package/templates/_agents/scripts/rule-budget.sh +0 -74
- package/templates/_agents/scripts/source-sync-check.mjs +0 -156
- package/templates/_agents/scripts/source-sync-check.test.mjs +0 -286
- package/templates/_agents/workflows/source-sync-repair.md +0 -30
|
@@ -50,6 +50,22 @@ THEN 行是机器对账断言:声明了场景却缺「- THEN <可观测结果>
|
|
|
50
50
|
| <示例:schema / 迁移路径约束> | <涉及路径与处理方式> |
|
|
51
51
|
| <示例:前端或客户端约定(如有)> | <本 spec 涉及哪些约定> |
|
|
52
52
|
|
|
53
|
+
## 验收判据
|
|
54
|
+
<!-- 判据级收敛对账的机器输入(check-loop 验收判据对账段,2026-10-13 自 Shipyard 回灌;B6b 落地后编号以 check-loop.mjs 头部清单为准):
|
|
55
|
+
每行一条判据,「证据」须机器可解析。路径:文件必须存在。机器不读正文,不判断它和判据是否相关(那一步留给新会话复核)。
|
|
56
|
+
命令:只认全量门跑过的 `npm test` / `node .agents/scripts/verify.mjs`(kit 全量门 = verify.mjs 七门编排;
|
|
57
|
+
装户项目测试命令各异,verify.mjs `--test-cmd` 注入的算 npm test 面)。
|
|
58
|
+
还须 workflow/verify-evidence.md 有一行时间不早于本 spec「日期」的全绿凭证;没有这行 = 未覆盖。
|
|
59
|
+
日期口径:frontmatter「日期」与全绿行时间同为 UTC(fill-spec 默认即此);手写勿用本地时区日期——
|
|
60
|
+
UTC+8 凌晨 0–8 点落的全绿行日期为前一日,会对不上(硬拦,08:00 后重跑门即解)。
|
|
61
|
+
不在全量门里的检查(UI 实测 / 回归冒烟等)改记证据文件路径。
|
|
62
|
+
「状态」写「覆盖」而证据无效仍判未覆盖。人工走查状态写「人工」,证据列留空(仅「人工+空证据」豁免机器对账;
|
|
63
|
+
截图等图片不在路径白名单,需留痕改存 .md 报告后引路径)。
|
|
64
|
+
无本节或表为空 → WARN;证据无效的 WARN / HARD-BLOCK 分档与生效锚随 B6b 对账段落地。 -->
|
|
65
|
+
| 判据(可观察行为) | 证据(测试文件 / 命令 / 证据文件) | 状态 |
|
|
66
|
+
|---|---|---|
|
|
67
|
+
| <行为 1> | <路径或命令> | <覆盖 / 未覆盖 / 人工> |
|
|
68
|
+
|
|
53
69
|
## 风险评估
|
|
54
70
|
- <风险点 1> | 应对:<测试 / hook / 评审>
|
|
55
71
|
- <风险点 2> | 应对:…
|
|
@@ -58,7 +74,7 @@ THEN 行是机器对账断言:声明了场景却缺「- THEN <可观测结果>
|
|
|
58
74
|
> 个人工作流:确认 = 用户在对话内一句话通过;无第二审批人,追溯靠 git(commit 记录确认时点)。
|
|
59
75
|
> 确认结果 / 确认时间写在文件头 frontmatter(L3 由 check-loop 强制校验);本节只留叙述性复核记录。
|
|
60
76
|
|
|
61
|
-
- 独立复核:<L3 强制:另开新会话由 AI 复核本 spec,记录复核会话与结论;L1 / L2
|
|
77
|
+
- 独立复核:<L3 强制:另开新会话由 AI 复核本 spec,记录复核会话与结论;L1 / L2 无则删除本行。复核行须落「复核上下文:<会话/子代理 id>」——隔离前提的机器事实,advisory>
|
|
62
78
|
- 复核结论:<无则删除本行>
|
|
63
79
|
- 返修意见:<无则删除本行>
|
|
64
80
|
- 确认通过后,方可起草 ../plans/YYYY-MM-DD-<主题>.md
|
|
@@ -1,89 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
description: 装户面同步一致性检查(包源 templates/_agents/ vs 装副本 .agents/ 三类差异:缺失 / 孤儿 / 漂移)
|
|
3
|
-
---
|
|
4
|
-
|
|
5
|
-
> **装户边界**:本文档中 `src/`、`bin/flow-kit.mjs`、`templates/_agents/`、`modules/hosts/` 为 kit 包源仓视角引用——装户仓(无 `templates/` 包源)对应命令不适用,本仓以 `.agents/` 装副本为准。
|
|
6
|
-
|
|
7
|
-
# Source-Sync-Check · 装户面同步一致性
|
|
8
|
-
|
|
9
|
-
> `templates/_agents/` 包源 vs `.agents/` 装副本——三类差异报告:缺失 / 孤儿 / 漂移。
|
|
10
|
-
> managed 文件由 `flow-kit sync` 跟踪;owned 文件由 `flow-kit doctor` §6.6 校验——本工具补"两者都没扫"的真空地带(结构级差异)。
|
|
11
|
-
|
|
12
|
-
## 1. 何时跑
|
|
13
|
-
|
|
14
|
-
- 改 `templates/_agents/*` 包源后
|
|
15
|
-
- 怀疑装副本未跟包源更新
|
|
16
|
-
- 体检装副本完整性(清理前 / 发版前)
|
|
17
|
-
- 不跑:仅改装副本 `.agents/*`(B-b 决策「只报告」+ 不反向同步)
|
|
18
|
-
|
|
19
|
-
## 2. 怎么跑
|
|
20
|
-
|
|
21
|
-
### 2.1 默认 `--diff`(仅报告)
|
|
22
|
-
|
|
23
|
-
```
|
|
24
|
-
node .agents/scripts/source-sync-check.mjs --diff
|
|
25
|
-
node .agents/scripts/source-sync-check.mjs --json # 机器可读
|
|
26
|
-
node .agents/scripts/source-sync-check.mjs --pkg-root <path> --target <path> # 自定义路径
|
|
27
|
-
```
|
|
28
|
-
|
|
29
|
-
输出三类:
|
|
30
|
-
- **缺失**(missing)——包源有 / 装副本无(如新增文件 init 未执行)
|
|
31
|
-
- **孤儿**(orphan)——包源无 / 装副本有(如历史残留 / 用户本地添加)
|
|
32
|
-
- **漂移**(drift)——两者都有但 sha 不一致(如包源改了装副本未跟)
|
|
33
|
-
|
|
34
|
-
**排除**:
|
|
35
|
-
- `templates/_agents/cache/`(运行时缓存,与 `flow-kit sync` 既有约定一致)
|
|
36
|
-
- `.agents/kit.json` / `.agents/settings.json`(init 渲染产物,不属双源)
|
|
37
|
-
|
|
38
|
-
### 2.2 输出示例
|
|
39
|
-
|
|
40
|
-
```
|
|
41
|
-
▶ flow-kit source-sync-check --diff
|
|
42
|
-
包源 (templates/_agents/) 49 份 | 装副本 (.agents/) 49 份
|
|
43
|
-
缺失(包源有 / 装副本 无)1:
|
|
44
|
-
- scripts/source-sync-check.mjs
|
|
45
|
-
孤儿(包源无 / 装副本 有)1:
|
|
46
|
-
- hooks/commit-check.config.json
|
|
47
|
-
漂移(包源装副本都有但 sha 不一致)3:
|
|
48
|
-
- commands/maintain.md pkg=3782b695… tgt=26203f7b…
|
|
49
|
-
- notes/runtime-env.md pkg=aedde1ba… tgt=ad08441e…
|
|
50
|
-
- scripts/ensure-board.mjs pkg=e66653b0… tgt=b6f3cc9b…
|
|
51
|
-
```
|
|
52
|
-
|
|
53
|
-
### 2.3 自验
|
|
54
|
-
|
|
55
|
-
```
|
|
56
|
-
node .agents/scripts/source-sync-check.test.mjs # 11 场景全过
|
|
57
|
-
npm test # 含 source-sync-check 套件
|
|
58
|
-
flow-kit doctor # 10/0/0
|
|
59
|
-
```
|
|
60
|
-
|
|
61
|
-
## 3. 边界(不要做)
|
|
62
|
-
|
|
63
|
-
- 不要自动化同步(B-b 决策「只报告不修复」——与 `gate-checklist` 同源)
|
|
64
|
-
- 不改 managed 台账跟踪逻辑(`sync.mjs` 不动)
|
|
65
|
-
- 不改 owned 漂移校验(`doctor.mjs` §6.6 不动)
|
|
66
|
-
- 不反向同步——装副本独自有文件(如 hooks/commit-check.config.json)可能是装户配置,不应被删
|
|
67
|
-
- 不检查注册表内宿主 `modules/hosts/` 薄适配漂移(那是 `flow-kit sync-hosts` 范围)
|
|
68
|
-
|
|
69
|
-
## 4. 当前已识别的真实漂点(首次实测,2026-09-25)
|
|
70
|
-
|
|
71
|
-
- **缺失**:本工具写完后未同步装副本(预期内——随本次 commit 解决)
|
|
72
|
-
- **孤儿**:`.agents/hooks/commit-check.config.json`(装副本独有,疑似装户配置)
|
|
73
|
-
- **漂移**:`commands/maintain.md` / `notes/runtime-env.md` / `scripts/ensure-board.mjs`
|
|
74
|
-
|
|
75
|
-
修复留后续 incident / intent 跟踪(不在本次范围)。
|
|
76
|
-
|
|
77
|
-
## 5. 与既有工具的关系
|
|
78
|
-
|
|
79
|
-
| 工具 | 作用域 | 算法 |
|
|
80
|
-
|---|---|---|
|
|
81
|
-
| `flow-kit sync` | managed 文件(kit.json 台账跟踪)| 三态覆盖 + 加新 + 报错缺 |
|
|
82
|
-
| `flow-kit doctor` §6.6 | owned 文件(kit.owned 哈希比对)| 盘面 sha vs 台账哈希 |
|
|
83
|
-
| **`flow-kit source-sync-check`** | **所有文件结构(包源 ↔ 装副本全集)** | **sha 全量比对 + 缺失/孤儿分类** |
|
|
84
|
-
|
|
85
|
-
三者互补,不重叠。
|
|
86
|
-
|
|
87
|
-
## 6. 相关留痕
|
|
88
|
-
|
|
89
|
-
- 立法出处:2026-09-25 source-sync-check(intent/plan;父事件 = 包源改了装副本未同步,本工具预防性体检)——留痕在包源仓 git 历史与 CHANGELOG,装户径不引实例路径
|
|
@@ -1,89 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
description: 装户面同步一致性检查(包源 templates/_agents/ vs 装副本 .agents/ 三类差异:缺失 / 孤儿 / 漂移)
|
|
3
|
-
---
|
|
4
|
-
|
|
5
|
-
> **装户边界**:本文档中 `src/`、`bin/flow-kit.mjs`、`templates/_agents/`、`modules/hosts/` 为 kit 包源仓视角引用——装户仓(无 `templates/` 包源)对应命令不适用,本仓以 `.agents/` 装副本为准。
|
|
6
|
-
|
|
7
|
-
# Source-Sync-Check · 装户面同步一致性
|
|
8
|
-
|
|
9
|
-
> `templates/_agents/` 包源 vs `.agents/` 装副本——三类差异报告:缺失 / 孤儿 / 漂移。
|
|
10
|
-
> managed 文件由 `flow-kit sync` 跟踪;owned 文件由 `flow-kit doctor` §6.6 校验——本工具补"两者都没扫"的真空地带(结构级差异)。
|
|
11
|
-
|
|
12
|
-
## 1. 何时跑
|
|
13
|
-
|
|
14
|
-
- 改 `templates/_agents/*` 包源后
|
|
15
|
-
- 怀疑装副本未跟包源更新
|
|
16
|
-
- 体检装副本完整性(清理前 / 发版前)
|
|
17
|
-
- 不跑:仅改装副本 `.agents/*`(B-b 决策「只报告」+ 不反向同步)
|
|
18
|
-
|
|
19
|
-
## 2. 怎么跑
|
|
20
|
-
|
|
21
|
-
### 2.1 默认 `--diff`(仅报告)
|
|
22
|
-
|
|
23
|
-
```
|
|
24
|
-
node .agents/scripts/source-sync-check.mjs --diff
|
|
25
|
-
node .agents/scripts/source-sync-check.mjs --json # 机器可读
|
|
26
|
-
node .agents/scripts/source-sync-check.mjs --pkg-root <path> --target <path> # 自定义路径
|
|
27
|
-
```
|
|
28
|
-
|
|
29
|
-
输出三类:
|
|
30
|
-
- **缺失**(missing)——包源有 / 装副本无(如新增文件 init 未执行)
|
|
31
|
-
- **孤儿**(orphan)——包源无 / 装副本有(如历史残留 / 用户本地添加)
|
|
32
|
-
- **漂移**(drift)——两者都有但 sha 不一致(如包源改了装副本未跟)
|
|
33
|
-
|
|
34
|
-
**排除**:
|
|
35
|
-
- `templates/_agents/cache/`(运行时缓存,与 `flow-kit sync` 既有约定一致)
|
|
36
|
-
- `.agents/kit.json` / `.agents/settings.json`(init 渲染产物,不属双源)
|
|
37
|
-
|
|
38
|
-
### 2.2 输出示例
|
|
39
|
-
|
|
40
|
-
```
|
|
41
|
-
▶ flow-kit source-sync-check --diff
|
|
42
|
-
包源 (templates/_agents/) 49 份 | 装副本 (.agents/) 49 份
|
|
43
|
-
缺失(包源有 / 装副本 无)1:
|
|
44
|
-
- scripts/source-sync-check.mjs
|
|
45
|
-
孤儿(包源无 / 装副本 有)1:
|
|
46
|
-
- hooks/commit-check.config.json
|
|
47
|
-
漂移(包源装副本都有但 sha 不一致)3:
|
|
48
|
-
- commands/maintain.md pkg=3782b695… tgt=26203f7b…
|
|
49
|
-
- notes/runtime-env.md pkg=aedde1ba… tgt=ad08441e…
|
|
50
|
-
- scripts/ensure-board.mjs pkg=e66653b0… tgt=b6f3cc9b…
|
|
51
|
-
```
|
|
52
|
-
|
|
53
|
-
### 2.3 自验
|
|
54
|
-
|
|
55
|
-
```
|
|
56
|
-
node .agents/scripts/source-sync-check.test.mjs # 11 场景全过
|
|
57
|
-
npm test # 含 source-sync-check 套件
|
|
58
|
-
flow-kit doctor # 10/0/0
|
|
59
|
-
```
|
|
60
|
-
|
|
61
|
-
## 3. 边界(不要做)
|
|
62
|
-
|
|
63
|
-
- 不要自动化同步(B-b 决策「只报告不修复」——与 `gate-checklist` 同源)
|
|
64
|
-
- 不改 managed 台账跟踪逻辑(`sync.mjs` 不动)
|
|
65
|
-
- 不改 owned 漂移校验(`doctor.mjs` §6.6 不动)
|
|
66
|
-
- 不反向同步——装副本独自有文件(如 hooks/commit-check.config.json)可能是装户配置,不应被删
|
|
67
|
-
- 不检查注册表内宿主 `modules/hosts/` 薄适配漂移(那是 `flow-kit sync-hosts` 范围)
|
|
68
|
-
|
|
69
|
-
## 4. 当前已识别的真实漂点(首次实测,2026-09-25)
|
|
70
|
-
|
|
71
|
-
- **缺失**:本工具写完后未同步装副本(预期内——随本次 commit 解决)
|
|
72
|
-
- **孤儿**:`.agents/hooks/commit-check.config.json`(装副本独有,疑似装户配置)
|
|
73
|
-
- **漂移**:`commands/maintain.md` / `notes/runtime-env.md` / `scripts/ensure-board.mjs`
|
|
74
|
-
|
|
75
|
-
修复留后续 incident / intent 跟踪(不在本次范围)。
|
|
76
|
-
|
|
77
|
-
## 5. 与既有工具的关系
|
|
78
|
-
|
|
79
|
-
| 工具 | 作用域 | 算法 |
|
|
80
|
-
|---|---|---|
|
|
81
|
-
| `flow-kit sync` | managed 文件(kit.json 台账跟踪)| 三态覆盖 + 加新 + 报错缺 |
|
|
82
|
-
| `flow-kit doctor` §6.6 | owned 文件(kit.owned 哈希比对)| 盘面 sha vs 台账哈希 |
|
|
83
|
-
| **`flow-kit source-sync-check`** | **所有文件结构(包源 ↔ 装副本全集)** | **sha 全量比对 + 缺失/孤儿分类** |
|
|
84
|
-
|
|
85
|
-
三者互补,不重叠。
|
|
86
|
-
|
|
87
|
-
## 6. 相关留痕
|
|
88
|
-
|
|
89
|
-
- 立法出处:2026-09-25 source-sync-check(intent/plan;父事件 = 包源改了装副本未同步,本工具预防性体检)——留痕在包源仓 git 历史与 CHANGELOG,装户径不引实例路径
|
|
@@ -1,89 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
description: 装户面同步一致性检查(包源 templates/_agents/ vs 装副本 .agents/ 三类差异:缺失 / 孤儿 / 漂移)
|
|
3
|
-
---
|
|
4
|
-
|
|
5
|
-
> **装户边界**:本文档中 `src/`、`bin/flow-kit.mjs`、`templates/_agents/`、`modules/hosts/` 为 kit 包源仓视角引用——装户仓(无 `templates/` 包源)对应命令不适用,本仓以 `.agents/` 装副本为准。
|
|
6
|
-
|
|
7
|
-
# Source-Sync-Check · 装户面同步一致性
|
|
8
|
-
|
|
9
|
-
> `templates/_agents/` 包源 vs `.agents/` 装副本——三类差异报告:缺失 / 孤儿 / 漂移。
|
|
10
|
-
> managed 文件由 `flow-kit sync` 跟踪;owned 文件由 `flow-kit doctor` §6.6 校验——本工具补"两者都没扫"的真空地带(结构级差异)。
|
|
11
|
-
|
|
12
|
-
## 1. 何时跑
|
|
13
|
-
|
|
14
|
-
- 改 `templates/_agents/*` 包源后
|
|
15
|
-
- 怀疑装副本未跟包源更新
|
|
16
|
-
- 体检装副本完整性(清理前 / 发版前)
|
|
17
|
-
- 不跑:仅改装副本 `.agents/*`(B-b 决策「只报告」+ 不反向同步)
|
|
18
|
-
|
|
19
|
-
## 2. 怎么跑
|
|
20
|
-
|
|
21
|
-
### 2.1 默认 `--diff`(仅报告)
|
|
22
|
-
|
|
23
|
-
```
|
|
24
|
-
node .agents/scripts/source-sync-check.mjs --diff
|
|
25
|
-
node .agents/scripts/source-sync-check.mjs --json # 机器可读
|
|
26
|
-
node .agents/scripts/source-sync-check.mjs --pkg-root <path> --target <path> # 自定义路径
|
|
27
|
-
```
|
|
28
|
-
|
|
29
|
-
输出三类:
|
|
30
|
-
- **缺失**(missing)——包源有 / 装副本无(如新增文件 init 未执行)
|
|
31
|
-
- **孤儿**(orphan)——包源无 / 装副本有(如历史残留 / 用户本地添加)
|
|
32
|
-
- **漂移**(drift)——两者都有但 sha 不一致(如包源改了装副本未跟)
|
|
33
|
-
|
|
34
|
-
**排除**:
|
|
35
|
-
- `templates/_agents/cache/`(运行时缓存,与 `flow-kit sync` 既有约定一致)
|
|
36
|
-
- `.agents/kit.json` / `.agents/settings.json`(init 渲染产物,不属双源)
|
|
37
|
-
|
|
38
|
-
### 2.2 输出示例
|
|
39
|
-
|
|
40
|
-
```
|
|
41
|
-
▶ flow-kit source-sync-check --diff
|
|
42
|
-
包源 (templates/_agents/) 49 份 | 装副本 (.agents/) 49 份
|
|
43
|
-
缺失(包源有 / 装副本 无)1:
|
|
44
|
-
- scripts/source-sync-check.mjs
|
|
45
|
-
孤儿(包源无 / 装副本 有)1:
|
|
46
|
-
- hooks/commit-check.config.json
|
|
47
|
-
漂移(包源装副本都有但 sha 不一致)3:
|
|
48
|
-
- commands/maintain.md pkg=3782b695… tgt=26203f7b…
|
|
49
|
-
- notes/runtime-env.md pkg=aedde1ba… tgt=ad08441e…
|
|
50
|
-
- scripts/ensure-board.mjs pkg=e66653b0… tgt=b6f3cc9b…
|
|
51
|
-
```
|
|
52
|
-
|
|
53
|
-
### 2.3 自验
|
|
54
|
-
|
|
55
|
-
```
|
|
56
|
-
node .agents/scripts/source-sync-check.test.mjs # 11 场景全过
|
|
57
|
-
npm test # 含 source-sync-check 套件
|
|
58
|
-
flow-kit doctor # 10/0/0
|
|
59
|
-
```
|
|
60
|
-
|
|
61
|
-
## 3. 边界(不要做)
|
|
62
|
-
|
|
63
|
-
- 不要自动化同步(B-b 决策「只报告不修复」——与 `gate-checklist` 同源)
|
|
64
|
-
- 不改 managed 台账跟踪逻辑(`sync.mjs` 不动)
|
|
65
|
-
- 不改 owned 漂移校验(`doctor.mjs` §6.6 不动)
|
|
66
|
-
- 不反向同步——装副本独自有文件(如 hooks/commit-check.config.json)可能是装户配置,不应被删
|
|
67
|
-
- 不检查注册表内宿主 `modules/hosts/` 薄适配漂移(那是 `flow-kit sync-hosts` 范围)
|
|
68
|
-
|
|
69
|
-
## 4. 当前已识别的真实漂点(首次实测,2026-09-25)
|
|
70
|
-
|
|
71
|
-
- **缺失**:本工具写完后未同步装副本(预期内——随本次 commit 解决)
|
|
72
|
-
- **孤儿**:`.agents/hooks/commit-check.config.json`(装副本独有,疑似装户配置)
|
|
73
|
-
- **漂移**:`commands/maintain.md` / `notes/runtime-env.md` / `scripts/ensure-board.mjs`
|
|
74
|
-
|
|
75
|
-
修复留后续 incident / intent 跟踪(不在本次范围)。
|
|
76
|
-
|
|
77
|
-
## 5. 与既有工具的关系
|
|
78
|
-
|
|
79
|
-
| 工具 | 作用域 | 算法 |
|
|
80
|
-
|---|---|---|
|
|
81
|
-
| `flow-kit sync` | managed 文件(kit.json 台账跟踪)| 三态覆盖 + 加新 + 报错缺 |
|
|
82
|
-
| `flow-kit doctor` §6.6 | owned 文件(kit.owned 哈希比对)| 盘面 sha vs 台账哈希 |
|
|
83
|
-
| **`flow-kit source-sync-check`** | **所有文件结构(包源 ↔ 装副本全集)** | **sha 全量比对 + 缺失/孤儿分类** |
|
|
84
|
-
|
|
85
|
-
三者互补,不重叠。
|
|
86
|
-
|
|
87
|
-
## 6. 相关留痕
|
|
88
|
-
|
|
89
|
-
- 立法出处:2026-09-25 source-sync-check(intent/plan;父事件 = 包源改了装副本未同步,本工具预防性体检)——留痕在包源仓 git 历史与 CHANGELOG,装户径不引实例路径
|
|
@@ -1,89 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
description: 装户面同步一致性检查(包源 templates/_agents/ vs 装副本 .agents/ 三类差异:缺失 / 孤儿 / 漂移;横向工具)
|
|
3
|
-
---
|
|
4
|
-
|
|
5
|
-
> **装户边界**:本文档中 `src/`、`bin/flow-kit.mjs`、`templates/_agents/`、`modules/hosts/` 为 kit 包源仓视角引用——装户仓(无 `templates/` 包源)对应命令不适用,本仓以 `.agents/` 装副本为准。
|
|
6
|
-
|
|
7
|
-
# Source-Sync-Check · 装户面同步一致性
|
|
8
|
-
|
|
9
|
-
> `templates/_agents/` 包源 vs `.agents/` 装副本——三类差异报告:缺失 / 孤儿 / 漂移。
|
|
10
|
-
> managed 文件由 `flow-kit sync` 跟踪;owned 文件由 `flow-kit doctor` §6.6 校验——本工具补"两者都没扫"的真空地带(结构级差异)。
|
|
11
|
-
|
|
12
|
-
## 1. 何时跑
|
|
13
|
-
|
|
14
|
-
- 改 `templates/_agents/*` 包源后
|
|
15
|
-
- 怀疑装副本未跟包源更新
|
|
16
|
-
- 体检装副本完整性(清理前 / 发版前)
|
|
17
|
-
- 不跑:仅改装副本 `.agents/*`(B-b 决策「只报告」+ 不反向同步)
|
|
18
|
-
|
|
19
|
-
## 2. 怎么跑
|
|
20
|
-
|
|
21
|
-
### 2.1 默认 `--diff`(仅报告)
|
|
22
|
-
|
|
23
|
-
```
|
|
24
|
-
node .agents/scripts/source-sync-check.mjs --diff
|
|
25
|
-
node .agents/scripts/source-sync-check.mjs --json # 机器可读
|
|
26
|
-
node .agents/scripts/source-sync-check.mjs --pkg-root <path> --target <path> # 自定义路径
|
|
27
|
-
```
|
|
28
|
-
|
|
29
|
-
输出三类:
|
|
30
|
-
- **缺失**(missing)——包源有 / 装副本无(如新增文件 init 未执行)
|
|
31
|
-
- **孤儿**(orphan)——包源无 / 装副本有(如历史残留 / 用户本地添加)
|
|
32
|
-
- **漂移**(drift)——两者都有但 sha 不一致(如包源改了装副本未跟)
|
|
33
|
-
|
|
34
|
-
**排除**:
|
|
35
|
-
- `templates/_agents/cache/`(运行时缓存,与 `flow-kit sync` 既有约定一致)
|
|
36
|
-
- `.agents/kit.json` / `.agents/settings.json`(init 渲染产物,不属双源)
|
|
37
|
-
|
|
38
|
-
### 2.2 输出示例
|
|
39
|
-
|
|
40
|
-
```
|
|
41
|
-
▶ flow-kit source-sync-check --diff
|
|
42
|
-
包源 (templates/_agents/) 49 份 | 装副本 (.agents/) 49 份
|
|
43
|
-
缺失(包源有 / 装副本 无)1:
|
|
44
|
-
- scripts/source-sync-check.mjs
|
|
45
|
-
孤儿(包源无 / 装副本 有)1:
|
|
46
|
-
- hooks/commit-check.config.json
|
|
47
|
-
漂移(包源装副本都有但 sha 不一致)3:
|
|
48
|
-
- commands/maintain.md pkg=3782b695… tgt=26203f7b…
|
|
49
|
-
- notes/runtime-env.md pkg=aedde1ba… tgt=ad08441e…
|
|
50
|
-
- scripts/ensure-board.mjs pkg=e66653b0… tgt=b6f3cc9b…
|
|
51
|
-
```
|
|
52
|
-
|
|
53
|
-
### 2.3 自验
|
|
54
|
-
|
|
55
|
-
```
|
|
56
|
-
node .agents/scripts/source-sync-check.test.mjs # 11 场景全过
|
|
57
|
-
npm test # 含 source-sync-check 套件
|
|
58
|
-
flow-kit doctor # 10/0/0
|
|
59
|
-
```
|
|
60
|
-
|
|
61
|
-
## 3. 边界(不要做)
|
|
62
|
-
|
|
63
|
-
- 不要自动化同步(B-b 决策「只报告不修复」——与 `gate-checklist` 同源)
|
|
64
|
-
- 不改 managed 台账跟踪逻辑(`sync.mjs` 不动)
|
|
65
|
-
- 不改 owned 漂移校验(`doctor.mjs` §6.6 不动)
|
|
66
|
-
- 不反向同步——装副本独自有文件(如 hooks/commit-check.config.json)可能是装户配置,不应被删
|
|
67
|
-
- 不检查注册表内宿主 `modules/hosts/` 薄适配漂移(那是 `flow-kit sync-hosts` 范围)
|
|
68
|
-
|
|
69
|
-
## 4. 当前已识别的真实漂点(首次实测,2026-09-25)
|
|
70
|
-
|
|
71
|
-
- **缺失**:本工具写完后未同步装副本(预期内——随本次 commit 解决)
|
|
72
|
-
- **孤儿**:`.agents/hooks/commit-check.config.json`(装副本独有,疑似装户配置)
|
|
73
|
-
- **漂移**:`commands/maintain.md` / `notes/runtime-env.md` / `scripts/ensure-board.mjs`
|
|
74
|
-
|
|
75
|
-
修复留后续 incident / intent 跟踪(不在本次范围)。
|
|
76
|
-
|
|
77
|
-
## 5. 与既有工具的关系
|
|
78
|
-
|
|
79
|
-
| 工具 | 作用域 | 算法 |
|
|
80
|
-
|---|---|---|
|
|
81
|
-
| `flow-kit sync` | managed 文件(kit.json 台账跟踪)| 三态覆盖 + 加新 + 报错缺 |
|
|
82
|
-
| `flow-kit doctor` §6.6 | owned 文件(kit.owned 哈希比对)| 盘面 sha vs 台账哈希 |
|
|
83
|
-
| **`flow-kit source-sync-check`** | **所有文件结构(包源 ↔ 装副本全集)** | **sha 全量比对 + 缺失/孤儿分类** |
|
|
84
|
-
|
|
85
|
-
三者互补,不重叠。
|
|
86
|
-
|
|
87
|
-
## 6. 相关留痕
|
|
88
|
-
|
|
89
|
-
- 立法出处:2026-09-25 source-sync-check(intent/plan;父事件 = 包源改了装副本未同步,本工具预防性体检)——留痕在包源仓 git 历史与 CHANGELOG,装户径不引实例路径
|
|
@@ -1,90 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: wf-source-sync-check
|
|
3
|
-
description: 装户面同步一致性检查(包源 templates/_agents/ vs 装副本 .agents/ 三类差异:缺失 / 孤儿 / 漂移;横向工具)
|
|
4
|
-
---
|
|
5
|
-
|
|
6
|
-
> **装户边界**:本文档中 `src/`、`bin/flow-kit.mjs`、`templates/_agents/`、`modules/hosts/` 为 kit 包源仓视角引用——装户仓(无 `templates/` 包源)对应命令不适用,本仓以 `.agents/` 装副本为准。
|
|
7
|
-
|
|
8
|
-
# Source-Sync-Check · 装户面同步一致性
|
|
9
|
-
|
|
10
|
-
> `templates/_agents/` 包源 vs `.agents/` 装副本——三类差异报告:缺失 / 孤儿 / 漂移。
|
|
11
|
-
> managed 文件由 `flow-kit sync` 跟踪;owned 文件由 `flow-kit doctor` §6.6 校验——本工具补"两者都没扫"的真空地带(结构级差异)。
|
|
12
|
-
|
|
13
|
-
## 1. 何时跑
|
|
14
|
-
|
|
15
|
-
- 改 `templates/_agents/*` 包源后
|
|
16
|
-
- 怀疑装副本未跟包源更新
|
|
17
|
-
- 体检装副本完整性(清理前 / 发版前)
|
|
18
|
-
- 不跑:仅改装副本 `.agents/*`(B-b 决策「只报告」+ 不反向同步)
|
|
19
|
-
|
|
20
|
-
## 2. 怎么跑
|
|
21
|
-
|
|
22
|
-
### 2.1 默认 `--diff`(仅报告)
|
|
23
|
-
|
|
24
|
-
```
|
|
25
|
-
node .agents/scripts/source-sync-check.mjs --diff
|
|
26
|
-
node .agents/scripts/source-sync-check.mjs --json # 机器可读
|
|
27
|
-
node .agents/scripts/source-sync-check.mjs --pkg-root <path> --target <path> # 自定义路径
|
|
28
|
-
```
|
|
29
|
-
|
|
30
|
-
输出三类:
|
|
31
|
-
- **缺失**(missing)——包源有 / 装副本无(如新增文件 init 未执行)
|
|
32
|
-
- **孤儿**(orphan)——包源无 / 装副本有(如历史残留 / 用户本地添加)
|
|
33
|
-
- **漂移**(drift)——两者都有但 sha 不一致(如包源改了装副本未跟)
|
|
34
|
-
|
|
35
|
-
**排除**:
|
|
36
|
-
- `templates/_agents/cache/`(运行时缓存,与 `flow-kit sync` 既有约定一致)
|
|
37
|
-
- `.agents/kit.json` / `.agents/settings.json`(init 渲染产物,不属双源)
|
|
38
|
-
|
|
39
|
-
### 2.2 输出示例
|
|
40
|
-
|
|
41
|
-
```
|
|
42
|
-
▶ flow-kit source-sync-check --diff
|
|
43
|
-
包源 (templates/_agents/) 49 份 | 装副本 (.agents/) 49 份
|
|
44
|
-
缺失(包源有 / 装副本 无)1:
|
|
45
|
-
- scripts/source-sync-check.mjs
|
|
46
|
-
孤儿(包源无 / 装副本 有)1:
|
|
47
|
-
- hooks/commit-check.config.json
|
|
48
|
-
漂移(包源装副本都有但 sha 不一致)3:
|
|
49
|
-
- commands/maintain.md pkg=3782b695… tgt=26203f7b…
|
|
50
|
-
- notes/runtime-env.md pkg=aedde1ba… tgt=ad08441e…
|
|
51
|
-
- scripts/ensure-board.mjs pkg=e66653b0… tgt=b6f3cc9b…
|
|
52
|
-
```
|
|
53
|
-
|
|
54
|
-
### 2.3 自验
|
|
55
|
-
|
|
56
|
-
```
|
|
57
|
-
node .agents/scripts/source-sync-check.test.mjs # 11 场景全过
|
|
58
|
-
npm test # 含 source-sync-check 套件
|
|
59
|
-
flow-kit doctor # 10/0/0
|
|
60
|
-
```
|
|
61
|
-
|
|
62
|
-
## 3. 边界(不要做)
|
|
63
|
-
|
|
64
|
-
- 不要自动化同步(B-b 决策「只报告不修复」——与 `gate-checklist` 同源)
|
|
65
|
-
- 不改 managed 台账跟踪逻辑(`sync.mjs` 不动)
|
|
66
|
-
- 不改 owned 漂移校验(`doctor.mjs` §6.6 不动)
|
|
67
|
-
- 不反向同步——装副本独自有文件(如 hooks/commit-check.config.json)可能是装户配置,不应被删
|
|
68
|
-
- 不检查注册表内宿主 `modules/hosts/` 薄适配漂移(那是 `flow-kit sync-hosts` 范围)
|
|
69
|
-
|
|
70
|
-
## 4. 当前已识别的真实漂点(首次实测,2026-09-25)
|
|
71
|
-
|
|
72
|
-
- **缺失**:本工具写完后未同步装副本(预期内——随本次 commit 解决)
|
|
73
|
-
- **孤儿**:`.agents/hooks/commit-check.config.json`(装副本独有,疑似装户配置)
|
|
74
|
-
- **漂移**:`commands/maintain.md` / `notes/runtime-env.md` / `scripts/ensure-board.mjs`
|
|
75
|
-
|
|
76
|
-
修复留后续 incident / intent 跟踪(不在本次范围)。
|
|
77
|
-
|
|
78
|
-
## 5. 与既有工具的关系
|
|
79
|
-
|
|
80
|
-
| 工具 | 作用域 | 算法 |
|
|
81
|
-
|---|---|---|
|
|
82
|
-
| `flow-kit sync` | managed 文件(kit.json 台账跟踪)| 三态覆盖 + 加新 + 报错缺 |
|
|
83
|
-
| `flow-kit doctor` §6.6 | owned 文件(kit.owned 哈希比对)| 盘面 sha vs 台账哈希 |
|
|
84
|
-
| **`flow-kit source-sync-check`** | **所有文件结构(包源 ↔ 装副本全集)** | **sha 全量比对 + 缺失/孤儿分类** |
|
|
85
|
-
|
|
86
|
-
三者互补,不重叠。
|
|
87
|
-
|
|
88
|
-
## 6. 相关留痕
|
|
89
|
-
|
|
90
|
-
- 立法出处:2026-09-25 source-sync-check(intent/plan;父事件 = 包源改了装副本未同步,本工具预防性体检)——留痕在包源仓 git 历史与 CHANGELOG,装户径不引实例路径
|
|
@@ -1,103 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
description: 装户面同步一致性检查(包源 templates/_agents/ vs 装副本 .agents/ 三类差异:缺失 / 孤儿 / 漂移)
|
|
3
|
-
stage: helper(横向工具,不占 6 阶段)
|
|
4
|
-
triggers:
|
|
5
|
-
- "改了包源同步了吗"
|
|
6
|
-
- "装了装副本同步了吗"
|
|
7
|
-
- "扫一下装户面漂移"
|
|
8
|
-
- "source-sync 跑一下"
|
|
9
|
-
delegation:
|
|
10
|
-
- role: implementer
|
|
11
|
-
instructions: .agents/roles/implementer.md
|
|
12
|
-
when: 用户已确认同步范围(发现漂移后修包源或装副本时)
|
|
13
|
-
required: false
|
|
14
|
-
fallback: main
|
|
15
|
-
approval_required: true
|
|
16
|
-
next: .agents/commands/build.md(漂移属 build 改包源未同步导致的,修复后回 build)
|
|
17
|
-
---
|
|
18
|
-
|
|
19
|
-
> **装户边界**:本文档中 `src/`、`bin/flow-kit.mjs`、`templates/_agents/`、`modules/hosts/` 为 kit 包源仓视角引用——装户仓(无 `templates/` 包源)对应命令不适用,本仓以 `.agents/` 装副本为准。
|
|
20
|
-
|
|
21
|
-
# Source-Sync-Check · 装户面同步一致性
|
|
22
|
-
|
|
23
|
-
> `templates/_agents/` 包源 vs `.agents/` 装副本——三类差异报告:缺失 / 孤儿 / 漂移。
|
|
24
|
-
> managed 文件由 `flow-kit sync` 跟踪;owned 文件由 `flow-kit doctor` §6.6 校验——本工具补"两者都没扫"的真空地带(结构级差异)。
|
|
25
|
-
|
|
26
|
-
## 1. 何时跑
|
|
27
|
-
|
|
28
|
-
- 改 `templates/_agents/*` 包源后
|
|
29
|
-
- 怀疑装副本未跟包源更新
|
|
30
|
-
- 体检装副本完整性(清理前 / 发版前)
|
|
31
|
-
- 不跑:仅改装副本 `.agents/*`(B-b 决策「只报告」+ 不反向同步)
|
|
32
|
-
|
|
33
|
-
## 2. 怎么跑
|
|
34
|
-
|
|
35
|
-
### 2.1 默认 `--diff`(仅报告)
|
|
36
|
-
|
|
37
|
-
```
|
|
38
|
-
node .agents/scripts/source-sync-check.mjs --diff
|
|
39
|
-
node .agents/scripts/source-sync-check.mjs --json # 机器可读
|
|
40
|
-
node .agents/scripts/source-sync-check.mjs --pkg-root <path> --target <path> # 自定义路径
|
|
41
|
-
```
|
|
42
|
-
|
|
43
|
-
输出三类:
|
|
44
|
-
- **缺失**(missing)——包源有 / 装副本无(如新增文件 init 未执行)
|
|
45
|
-
- **孤儿**(orphan)——包源无 / 装副本有(如历史残留 / 用户本地添加)
|
|
46
|
-
- **漂移**(drift)——两者都有但 sha 不一致(如包源改了装副本未跟)
|
|
47
|
-
|
|
48
|
-
**排除**:
|
|
49
|
-
- `templates/_agents/cache/`(运行时缓存,与 `flow-kit sync` 既有约定一致)
|
|
50
|
-
- `.agents/kit.json` / `.agents/settings.json`(init 渲染产物,不属双源)
|
|
51
|
-
|
|
52
|
-
### 2.2 输出示例
|
|
53
|
-
|
|
54
|
-
```
|
|
55
|
-
▶ flow-kit source-sync-check --diff
|
|
56
|
-
包源 (templates/_agents/) 49 份 | 装副本 (.agents/) 49 份
|
|
57
|
-
缺失(包源有 / 装副本 无)1:
|
|
58
|
-
- scripts/source-sync-check.mjs
|
|
59
|
-
孤儿(包源无 / 装副本 有)1:
|
|
60
|
-
- hooks/commit-check.config.json
|
|
61
|
-
漂移(包源装副本都有但 sha 不一致)3:
|
|
62
|
-
- commands/maintain.md pkg=3782b695… tgt=26203f7b…
|
|
63
|
-
- notes/runtime-env.md pkg=aedde1ba… tgt=ad08441e…
|
|
64
|
-
- scripts/ensure-board.mjs pkg=e66653b0… tgt=b6f3cc9b…
|
|
65
|
-
```
|
|
66
|
-
|
|
67
|
-
### 2.3 自验
|
|
68
|
-
|
|
69
|
-
```
|
|
70
|
-
node .agents/scripts/source-sync-check.test.mjs # 11 场景全过
|
|
71
|
-
npm test # 含 source-sync-check 套件
|
|
72
|
-
flow-kit doctor # 10/0/0
|
|
73
|
-
```
|
|
74
|
-
|
|
75
|
-
## 3. 边界(不要做)
|
|
76
|
-
|
|
77
|
-
- 不要自动化同步(B-b 决策「只报告不修复」——与 `gate-checklist` 同源)
|
|
78
|
-
- 不改 managed 台账跟踪逻辑(`sync.mjs` 不动)
|
|
79
|
-
- 不改 owned 漂移校验(`doctor.mjs` §6.6 不动)
|
|
80
|
-
- 不反向同步——装副本独自有文件(如 hooks/commit-check.config.json)可能是装户配置,不应被删
|
|
81
|
-
- 不检查注册表内宿主 `modules/hosts/` 薄适配漂移(那是 `flow-kit sync-hosts` 范围)
|
|
82
|
-
|
|
83
|
-
## 4. 当前已识别的真实漂点(首次实测,2026-09-25)
|
|
84
|
-
|
|
85
|
-
- **缺失**:本工具写完后未同步装副本(预期内——随本次 commit 解决)
|
|
86
|
-
- **孤儿**:`.agents/hooks/commit-check.config.json`(装副本独有,疑似装户配置)
|
|
87
|
-
- **漂移**:`commands/maintain.md` / `notes/runtime-env.md` / `scripts/ensure-board.mjs`
|
|
88
|
-
|
|
89
|
-
修复留后续 incident / intent 跟踪(不在本次范围)。
|
|
90
|
-
|
|
91
|
-
## 5. 与既有工具的关系
|
|
92
|
-
|
|
93
|
-
| 工具 | 作用域 | 算法 |
|
|
94
|
-
|---|---|---|
|
|
95
|
-
| `flow-kit sync` | managed 文件(kit.json 台账跟踪)| 三态覆盖 + 加新 + 报错缺 |
|
|
96
|
-
| `flow-kit doctor` §6.6 | owned 文件(kit.owned 哈希比对)| 盘面 sha vs 台账哈希 |
|
|
97
|
-
| **`flow-kit source-sync-check`** | **所有文件结构(包源 ↔ 装副本全集)** | **sha 全量比对 + 缺失/孤儿分类** |
|
|
98
|
-
|
|
99
|
-
三者互补,不重叠。
|
|
100
|
-
|
|
101
|
-
## 6. 相关留痕
|
|
102
|
-
|
|
103
|
-
- 立法出处:2026-09-25 source-sync-check(intent/plan;父事件 = 包源改了装副本未同步,本工具预防性体检)——留痕在包源仓 git 历史与 CHANGELOG,装户径不引实例路径
|
|
@@ -1,43 +0,0 @@
|
|
|
1
|
-
#!/bin/sh
|
|
2
|
-
# 闭环配对(增量版):本次暂存的 intents/ incidents/ 入口文档必须已有同名 plan(L2/L3 另须同名 spec)
|
|
3
|
-
# 目的:把 check-loop.sh「配对断裂」hard-block 的发现时机从 pre-push 提前到 commit
|
|
4
|
-
# (papercut 2026-09-15:maintain.md 只写「incident≡intent 免另立 intent」,未把配 plan 写成显式步骤,
|
|
5
|
-
# 按文档字面执行三次 commit 全绿、push 才爆红,只能后补;
|
|
6
|
-
# 2026-09-27 audit-gate-hardening 补齐 spec 档——此前只查 plan,L2/L3 缺 spec 仍要拖到 push 才爆红)
|
|
7
|
-
# 口径与 check-loop.sh 对齐:入口文档(intents/ incidents/ 直下 .md)↔ workflow/plans/ 同名,
|
|
8
|
-
# L2/L3 级别另须 workflow/specs/ 同名(check-loop 检查 1 同款分档);
|
|
9
|
-
# 同 commit 携带 plan/spec 合法(检查的是工作区文件存在,staged 新建同样命中)。
|
|
10
|
-
# 已知边界:legacy 豁免与级别读取均基于工作区文件而非暂存 blob——add 后又改工作区时可能误豁免/误拦(逐文件取 blob 的 fork 成本大于收益,接受)。
|
|
11
|
-
|
|
12
|
-
cd "$(git rev-parse --show-toplevel)" || exit 1
|
|
13
|
-
|
|
14
|
-
fail=0
|
|
15
|
-
# -c core.quotepath=off:quotepath 默认 true 时非 ASCII 路径被引号转义("workflow/\346..."),
|
|
16
|
-
# ^workflow/ 前缀匹配失配 → 门禁静默跳过——教训与修法同 check-wiki-ledger.sh(2026-09-27 gate-coverage)
|
|
17
|
-
for f in $(git -c core.quotepath=off diff --cached --name-only --diff-filter=ACMR | grep -E '^workflow/(intents|incidents)/[^/]+\.md$' | grep -v '_TEMPLATE\.md$'); do
|
|
18
|
-
# 闭环引擎启用前的回填件带「流程: legacy」豁免配对检查(与 check-loop 同口径)
|
|
19
|
-
if grep -q '^流程: legacy' "$f"; then
|
|
20
|
-
continue
|
|
21
|
-
fi
|
|
22
|
-
base=$(basename "$f" .md)
|
|
23
|
-
if [ ! -f "workflow/plans/$base.md" ]; then
|
|
24
|
-
echo "闭环配对(增量)— BLOCK:"
|
|
25
|
-
echo " 入口缺同名 plan: $f(应在 workflow/plans/$base.md)"
|
|
26
|
-
echo " L1 极简 plan 只需「改动面 + 验证方式」两节(复制 workflow/plans/_TEMPLATE.md)"
|
|
27
|
-
fail=1
|
|
28
|
-
fi
|
|
29
|
-
lvl=$(sed -n 's/^级别:[[:space:]]*//p' "$f" | head -1)
|
|
30
|
-
if [ "$lvl" = "L2" ] || [ "$lvl" = "L3" ]; then
|
|
31
|
-
if [ ! -f "workflow/specs/$base.md" ]; then
|
|
32
|
-
echo "闭环配对(增量)— BLOCK:"
|
|
33
|
-
echo " 入口缺同名 spec: $f(级别 $lvl 须三件套,应在 workflow/specs/$base.md)"
|
|
34
|
-
echo " 与 pre-push check-loop 检查 1 同口径——先起草 spec 走 design.md,再提交"
|
|
35
|
-
fail=1
|
|
36
|
-
fi
|
|
37
|
-
fi
|
|
38
|
-
done
|
|
39
|
-
|
|
40
|
-
if [ $fail -ne 0 ]; then
|
|
41
|
-
echo "pre-commit: 入口文档配对不全(plan / L2-L3 spec),提交已阻止(与 pre-push check-loop 同口径,发现时机提前到 commit)" >&2
|
|
42
|
-
fi
|
|
43
|
-
exit $fail
|
|
@@ -1,18 +0,0 @@
|
|
|
1
|
-
#!/bin/sh
|
|
2
|
-
# wiki 台账一致性(增量版):本次暂存触及 wiki/ 时跑 verify 三方校验(磁盘 ↔ INDEX ↔ 看板 DATA)
|
|
3
|
-
# 目的:给「登记动作」装触发点——verify 此前无任何钩子调用,只能靠「触及 wiki 时手跑」的文字纪律
|
|
4
|
-
# (incident 2026-09-16-wiki-drift-and-verifier-gaps 认定的根因);本脚本把发现时机提前到 commit。
|
|
5
|
-
# 口径与 .agents/scripts/verify-wiki-consistency.mjs 一致:活层新增/删除/移动未登记、数据维护批次目录未入台账即拦。
|
|
6
|
-
# 注意 `-c core.quotepath=off`:core.quotepath 为 git 默认 true 时中文路径被转义加引号——实测输出
|
|
7
|
-
# `"wiki/\346\265\213\350\257\225..."`,`^wiki/` 前缀匹配失配 → 门禁静默跳过(本机 .gitconfig 恰好设 false,本地不复现)。
|
|
8
|
-
|
|
9
|
-
cd "$(git rev-parse --show-toplevel)" || exit 1
|
|
10
|
-
|
|
11
|
-
git -c core.quotepath=off diff --cached --name-only | grep -q '^wiki/' || exit 0
|
|
12
|
-
|
|
13
|
-
if ! node .agents/scripts/verify-wiki-consistency.mjs; then
|
|
14
|
-
echo "wiki 台账(增量)— BLOCK:"
|
|
15
|
-
echo " 先跑 node .agents/scripts/gen-wiki-board.mjs 补 INDEX/看板(或补 wiki/数据维护/README.md 登记行),再原路重试提交"
|
|
16
|
-
exit 1
|
|
17
|
-
fi
|
|
18
|
-
exit 0
|