agentic-flow-kit 1.7.16 → 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 +11 -7
- package/modules/hosts/claude/commands/wf-build.md +1 -1
- package/modules/hosts/claude/commands/wf-maintain.md +1 -1
- package/modules/hosts/claude/commands/wf-new-task.md +9 -8
- package/modules/hosts/claude/commands/wf-plan.md +1 -1
- package/modules/hosts/claude/commands/wf-review.md +1 -1
- package/modules/hosts/claude/commands/wf-test.md +1 -1
- package/modules/hosts/codex/commands/wf-build.md +1 -1
- package/modules/hosts/codex/commands/wf-maintain.md +1 -1
- package/modules/hosts/codex/commands/wf-new-task.md +9 -8
- package/modules/hosts/codex/commands/wf-plan.md +1 -1
- package/modules/hosts/codex/commands/wf-review.md +1 -1
- package/modules/hosts/codex/commands/wf-test.md +1 -1
- package/modules/hosts/cursor/commands/wf-build.md +1 -1
- package/modules/hosts/cursor/commands/wf-maintain.md +1 -1
- package/modules/hosts/cursor/commands/wf-new-task.md +9 -8
- package/modules/hosts/cursor/commands/wf-plan.md +1 -1
- package/modules/hosts/cursor/commands/wf-review.md +1 -1
- package/modules/hosts/cursor/commands/wf-test.md +1 -1
- package/modules/hosts/opencode/commands/wf-build.md +1 -1
- package/modules/hosts/opencode/commands/wf-maintain.md +1 -1
- package/modules/hosts/opencode/commands/wf-new-task.md +9 -8
- package/modules/hosts/opencode/commands/wf-plan.md +1 -1
- package/modules/hosts/opencode/commands/wf-review.md +1 -1
- package/modules/hosts/opencode/commands/wf-test.md +1 -1
- package/modules/hosts/trae/commands/wf-build.md +1 -1
- package/modules/hosts/trae/commands/wf-maintain.md +1 -1
- package/modules/hosts/trae/commands/wf-new-task.md +9 -8
- package/modules/hosts/trae/commands/wf-plan.md +1 -1
- package/modules/hosts/trae/commands/wf-review.md +1 -1
- package/modules/hosts/trae/commands/wf-test.md +1 -1
- package/package.json +1 -1
- package/src/cli.mjs +6 -2
- package/src/doctor.mjs +11 -2
- package/src/executor.mjs +25 -8
- package/src/executor.test.mjs +4 -1
- package/src/fresh-init.test.mjs +1 -1
- package/src/init.mjs +20 -3
- package/src/profiles.mjs +7 -3
- package/src/rule-budget.test.mjs +2 -2
- package/src/stack-profile.test.mjs +6 -0
- package/src/validate.mjs +6 -1
- package/src/validate.test.mjs +1 -1
- package/templates/.gitattributes +4 -1
- package/templates/AGENTS.md +2 -2
- package/templates/_agents/commands/build.md +1 -1
- package/templates/_agents/commands/maintain.md +1 -1
- package/templates/_agents/commands/new-task.md +9 -8
- package/templates/_agents/commands/plan.md +1 -1
- package/templates/_agents/commands/review.md +1 -1
- package/templates/_agents/commands/test.md +1 -1
- package/templates/_agents/engine-lock.json +130 -42
- 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 +4 -1
- package/templates/_agents/level-hints.txt +1 -1
- 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-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 +4 -1
- 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 +2 -2
- package/templates/_agents/scripts/check-lane-surface.test.mjs +5 -5
- package/templates/_agents/scripts/check-ledger-invariant.mjs +403 -152
- package/templates/_agents/scripts/check-ledger-invariant.test.mjs +433 -3
- package/templates/_agents/scripts/check-loop-rev.test.mjs +8 -5
- package/templates/_agents/scripts/check-loop-unit.test.mjs +8 -0
- package/templates/_agents/scripts/check-loop.mjs +215 -34
- package/templates/_agents/scripts/check-loop.test.mjs +570 -49
- 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 +3 -3
- package/templates/_agents/scripts/confirm-doc.mjs +114 -38
- package/templates/_agents/scripts/confirm-doc.test.mjs +180 -4
- package/templates/_agents/scripts/edit-face-check.mjs +5 -3
- package/templates/_agents/scripts/fill-intent.mjs +5 -3
- 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 +2 -2
- package/templates/_agents/scripts/fixture-scripts.test.mjs +6 -1
- package/templates/_agents/scripts/gate-checklist.mjs +6 -0
- 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 +8 -3
- package/templates/_agents/scripts/gen-workflow-dashboard.test.mjs +2 -1
- package/templates/_agents/scripts/gen-workflow-metrics.mjs +3 -3
- package/templates/_agents/scripts/git-core.mjs +45 -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-shards.mjs +307 -0
- package/templates/_agents/scripts/ledger-shards.test.mjs +339 -0
- package/templates/_agents/scripts/level-criteria.mjs +9 -10
- package/templates/_agents/scripts/level-criteria.test.mjs +7 -5
- 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 +6 -22
- package/templates/_agents/scripts/pipeline-run.test.mjs +22 -42
- package/templates/_agents/scripts/policy.mjs +28 -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 +34 -12
- 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/workflow-board-server.test.mjs +2 -2
- package/templates/_agents/scripts/workflow-enums.test.mjs +14 -5
- 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/_githooks/pre-commit +110 -90
- package/templates/_githooks/pre-merge-commit +27 -23
- package/templates/_githooks/pre-push +4 -3
- package/templates/_github/workflows/kit-ci.yml +4 -3
- package/templates/workflow/README.md +14 -7
- 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/templates/_agents/hooks/check-pairing-incremental.sh +0 -43
- package/templates/_agents/hooks/check-wiki-ledger.sh +0 -18
- package/templates/_agents/scripts/rule-budget.sh +0 -74
|
@@ -35,16 +35,18 @@ flow-kit route --files <预计改动面…> --kind require|fix|verify|review|dep
|
|
|
35
35
|
**诚实边界**:机器**无法**发现你没跑 route——定级发生在改动面确定之前,没有可比对的记录面,
|
|
36
36
|
详见 [ARCHITECTURE §5](../ARCHITECTURE.md) 与 CHANGELOG 1.7.16 B3 条。
|
|
37
37
|
|
|
38
|
-
动工前按下表定风险级
|
|
38
|
+
动工前按下表定风险级 L1-L3(就高不就低;判据细则见下节「级别判断」,单源 level-criteria.mjs),级别即风险级,决定走哪条泳道——确认放事前,还是审计补事后:
|
|
39
39
|
|
|
40
40
|
| 泳道 | 级别 | 确认与审计口径 |
|
|
41
41
|
|------|------|---------------|
|
|
42
|
-
| **协作道**(敏捷优先,审计异步补) |
|
|
42
|
+
| **协作道**(敏捷优先,审计异步补) | L1 实现级 | 一份 plan 即入口(来源 / 目标 / 红线 / 改动 / 验证 / 验收),不另立 intent。独立复核不设同步前置,check-loop 与事后 review 兜底;确认/代录可 `--batch` 批量(仅 L1) |
|
|
43
43
|
| **防御道**(严谨优先,确认同步拦) | L2 规则/契约 / L3 数据与运行时结构 | 同步确认门:spec 确认通过方可起草 plan,plan 确认后方可动手;L3 加新会话独立复核,未确认不放行 |
|
|
44
44
|
|
|
45
|
-
>
|
|
45
|
+
> **两问定级**(2026-10-13 L0 退役,自源仓收敛系列 1 回灌):结构面(schema / 迁移 SQL / DI / 认证管线)→ L3;契约或共享口径 → L2;两者都没有 → L1。不要按严重程度从 L1 往上滑。
|
|
46
|
+
> **落位**: L1 写在 plan frontmatter `级别`;L2/L3 写在 intent(intent 另以 `risk_level`=级别双写,`fill-intent.mjs` 自动写入,机器选道用)。
|
|
47
|
+
> **判低拦截**: 入口勾触达红线 → check-loop「红线判低」hard 拦 → 升到 L2/L3 并补同名 spec。
|
|
46
48
|
>
|
|
47
|
-
>
|
|
49
|
+
> **L2/L3 起草期合并预览**:三件套起草按 [design.md §0](design.md) 一次呈现要点总览(逐件确认代录不变)。
|
|
48
50
|
|
|
49
51
|
## 3. 路由判断
|
|
50
52
|
|
|
@@ -55,7 +57,7 @@ flow-kit route --files <预计改动面…> --kind require|fix|verify|review|dep
|
|
|
55
57
|
- **自动化驱动(并列入口,可选)**:一句话全程走 [pipeline-run.md](pipeline-run.md)——状态机驱动+工单协议+原话代录,与下述手动路由二选一,同一任务不混用
|
|
56
58
|
- **新需求 / 功能**:从 `plan.md` 进,立 **intent**(`workflow/intents/`)
|
|
57
59
|
- **修复类任务 / 事故**:从 `maintain.md` 进,立 **incident**(`workflow/incidents/`);incident 在 L1+ 即 **intent 等价物**(check-loop 认 incident≡intent),不必另立 intent。先检索同类历史(`node .agents/scripts/kb-search.mjs "<关键词>" --scope workflow --type incidents,plans`),有同类先读其历史三件套;再按级别走:
|
|
58
|
-
-
|
|
60
|
+
- L1 → 立 incident 后进 `build.md` 起草并确认同名 Quick-Plan → `test.md`
|
|
59
61
|
- L2/L3 → 立 incident 后进 `design.md` 起草并确认同名 spec,再进 `build.md` 起草并确认同名 plan → `test.md`
|
|
60
62
|
- 仅当根因属系统性 / 门禁缺位(maintain.md 三件套「是否需要新 intent」选"是")才另立 `workflow/intents/` 同名 intent
|
|
61
63
|
- **改完代码要验证**:直接进 `test.md`(验证通过即关单;L1 到此结束)
|
|
@@ -80,8 +82,7 @@ flow-kit route --files <预计改动面…> --kind require|fix|verify|review|dep
|
|
|
80
82
|
|
|
81
83
|
| 级别 | 单源语义(摘要) | 流程 |
|
|
82
84
|
|------|-----------------|------|
|
|
83
|
-
|
|
|
84
|
-
| L1 | 实现级改动(未命中 L2/L3) | 快车道:液态草稿(.zcode/drafts) → 实现 → 固化(`solidify-task.mjs`)——用户确认后带 `--delegated "<原话>"` 执行;无确认来源只迁移不落账 |
|
|
85
|
+
| L1 | 实现级改动(未命中 L2/L3) | 快车道:液态草稿(.zcode/drafts) → 实现 → 固化(`solidify-task.mjs`)——用户确认后带 `--delegated "<原话>"` 执行;无确认来源只迁移不落账;亦可一份 plan 即入口(不另立 intent) |
|
|
85
86
|
| L2 | 规则 / 契约(一处改、多处依赖) | 入口文档(intent / incident) + spec + plan 三件套 |
|
|
86
87
|
| L3 | 数据与运行时结构(结构面闭集见单源 `L3_SURFACES`) | 同 L2 + spec 新会话独立复核 |
|
|
87
88
|
|
|
@@ -92,7 +93,7 @@ flow-kit route --files <预计改动面…> --kind require|fix|verify|review|dep
|
|
|
92
93
|
|
|
93
94
|
## 5. intent 豁免(避免小改动也走完整闭环)
|
|
94
95
|
|
|
95
|
-
- **
|
|
96
|
+
- **L1 新需求**:一份 plan 即入口,不另立 intent(不必 spec)
|
|
96
97
|
- **docs 级改动**(AGENTS.md / workflow/ 模板 / .agents/ 脚本与 commands / yaml):豁免 intent,走 Conventional Commits 直接 commit;若同时触及代码,按代码部分级别立 intent
|
|
97
98
|
- **bootstrap 类改动**(引入规则本身):豁免 intent,commit message 显式声明 `bootstrap`
|
|
98
99
|
|
|
@@ -14,7 +14,7 @@ description: Plan 阶段 · 立 intent(AI 起草、用户确认;本阶段不
|
|
|
14
14
|
1. 若 `workflow/intents/` 已有目标 intent 且状态为 approved → 按级别跳 next(L1 → `build.md`,L2/L3 → `design.md`)。
|
|
15
15
|
2. 否则起草新 intent:
|
|
16
16
|
- **先检索同类**:`node .agents/scripts/kb-search.mjs "<关键词>" --scope workflow --type intents,specs`——命中同类先读其结论与验收,新 intent 引用(防重复立项 / 重复踩坑)
|
|
17
|
-
- **填空工具先跑**:`node .agents/scripts/fill-intent.mjs --module <模块> --level <
|
|
17
|
+
- **填空工具先跑**:`node .agents/scripts/fill-intent.mjs --module <模块> --level <L1|L2|L3> --topic <主题> --output workflow/intents/<date>-<主题>.md --notes "<备注>"`——输出含 frontmatter 6 字段(含 risk_level)+ 9 节(背景与问题/历史教训防复发/目标/非目标/约束/影响面/触达红线/验收标准 8 节正文 + 确认与复核)的草稿;AI 据此填实,模板与节标题机器保证不出错
|
|
18
18
|
- 复制 `workflow/intents/_TEMPLATE.md` → `workflow/intents/YYYY-MM-DD-<主题>.md`
|
|
19
19
|
- frontmatter 填 `模块:`(词表见 `.agents/workflow-modules.txt`,新建文档必填,check-loop 会警告)
|
|
20
20
|
- 按 8 节填写:背景与问题 / 历史教训防复发 / 目标(可验证) / 非目标 / 约束 / 影响面 / 触达红线 / 验收标准(L1 微改动可省非目标/约束两节,不硬填)
|
|
@@ -46,5 +46,5 @@ description: Review · 代码评审(横切,合入前使用;P0/P1/P2 分级
|
|
|
46
46
|
|
|
47
47
|
- **机器兜底**(pre-commit / pre-push / test 自动拦,无需人守):门禁清单与判据以 `.githooks/`、`.agents/hooks/`、`check-loop.sh` 头部注释为准;`项目测试命令` 跑自动化用例。
|
|
48
48
|
- **AI 复核**:机器门禁完成后优先委派 `independent-reviewer`,聚焦 P0 hook 未覆盖项 + 全部 P1(P2 视精力)——产出分级问题清单 + 修复建议。复核方法参考 `code-review` 技能(Standards×Spec 双轴);每条 finding 报告前过 `review-verification-protocol` 防误报门(锚定 file:line、给出证据、校准严重级,不确定就降级为提问)。
|
|
49
|
-
- **独立性**:L2 / L3 必须用独立子智能体,宿主不支持时另开新会话,不得由原作者自查冒充;
|
|
49
|
+
- **独立性**:L2 / L3 必须用独立子智能体,宿主不支持时另开新会话,不得由原作者自查冒充;L1 且宿主不支持子智能体时可由主智能体按同一复核契约执行。
|
|
50
50
|
- **用户决策**:问题定性(误报驳回 / P0 成立必修 / P1、P2 处置裁量)+ 合入时机;git 历史即评审记录,追溯靠 commit 与 tag。
|
|
@@ -56,7 +56,7 @@ npx agentic-flow-kit doctor # §6.5 delegations + §6.6 o
|
|
|
56
56
|
|
|
57
57
|
- 输出测试报告(通过项 / 失败项);失败项已修复并复测通过。
|
|
58
58
|
- **关单**(日常闭环点,不依赖是否上 prod):
|
|
59
|
-
- 关单前一键过门:`node .agents/scripts/verify.mjs --doc workflow/intents/<本单>.md
|
|
59
|
+
- 关单前一键过门:`node .agents/scripts/verify.mjs --doc workflow/intents/<本单>.md`(七门编排:语法/测试/编排检查/预算/生效规则视图/闭环/台账不变量,fail-fast 失败行留痕,非绿不关单);**`--doc` 把绿凭证绑到本单**——不带它落下的绿行不给任何单背书,confirm-doc 前置与检查 8 只认带本单 `--doc` 的绿行(仅 v6+ 生效);**全绿尾部自动落凭证并重生成 `workflow/verify-evidence.md`**(`effective-policy.md` 同为生成物——两者勿手改,policy/台账变更后重生成随同提交);**装户仓**(当前目录无 `package.json`)测试门显式跳过且**不落测试绿凭证**(防假绿),按项目口径手工跑或带 `--test-cmd "<项目测试命令>"` 指定
|
|
60
60
|
- 新需求:逐条勾验入口 intent「验收标准」,每条补「证据:」(例如:粘贴 CI 运行结果、UI 截图路径、或具体的 commit SHA),intent → done;同名 spec/Quick-Plan(若有)仍 approved → done。**注意:勾选但缺证据会被 check-loop 拦截(hard-block)**
|
|
61
61
|
- **approved 留痕提交**:done 确认前确认**本次关单文档**的 approved 态已进 git 历史(越早越好——approved 后即应提交;若尚未,先补提交再 done;门为逐份校验,三件套均关单时逐份各自满足)——confirm-doc 的 done 前置门硬校验(历史未出现「状态: approved」→ 拒绝落账);done 后再提交 done 态与其余改动
|
|
62
62
|
- **确认落态**:唯一入口 `node .agents/scripts/confirm-doc.mjs <path>`(两形态 / 逐件代录(摘要可复用——分辨力由 scope+指纹承担)/ done 内容绑定(关单编辑先于 done 确认、confirm-doc 是最后一次写入)/ 台账对质全口径见根 `AGENTS.md` §1.3 确认门)。
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "agentic-flow-kit",
|
|
3
|
-
"version": "1.
|
|
3
|
+
"version": "1.8.0",
|
|
4
4
|
"description": "AI-Native 闭环工作流 + wiki 知识层脚手架——flow-kit init 一条命令为新项目装好 .agents 工作流引擎(阶段命令/角色契约/门禁钩子/kb 检索/看板/规则面预算)+ workflow 文档闭环 + wiki 知识库,装完本地可跑、零运行时依赖",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"scripts": {
|
package/src/cli.mjs
CHANGED
|
@@ -7,7 +7,7 @@ import { sync } from './sync.mjs';
|
|
|
7
7
|
import { syncHosts } from './sync-hosts.mjs';
|
|
8
8
|
import { addHost } from './add-host.mjs';
|
|
9
9
|
import { addGate } from './add-gate.mjs';
|
|
10
|
-
import { route, runPipeline } from './executor.mjs';
|
|
10
|
+
import { route, runPipeline, routeKindList } from './executor.mjs';
|
|
11
11
|
import { existsSync, readFileSync, readdirSync } from 'node:fs';
|
|
12
12
|
import { fileURLToPath } from 'node:url';
|
|
13
13
|
import path from 'node:path';
|
|
@@ -25,6 +25,10 @@ function gateNames(pkgRoot) {
|
|
|
25
25
|
|
|
26
26
|
const GATE_LIST = gateNames(PKG_ROOT).join(' | ') || '无';
|
|
27
27
|
|
|
28
|
+
// route 的 kind 值域从权威面派生(同 GATE_LIST 纪律):读包源 new-task.md 的 route-kinds 机器单源,
|
|
29
|
+
// 不手写第二份——否则装户改 kind 时本帮助文本与 route 判定面会双源漂移(B5 同一问题)。
|
|
30
|
+
const ROUTE_KIND_LIST = routeKindList(PKG_ROOT).join('|') || 'require|fix|verify|review|deploy';
|
|
31
|
+
|
|
28
32
|
export const HELP = `flow-kit — AI-Native 闭环工作流 + wiki 知识层脚手架(agentic-flow-kit)
|
|
29
33
|
|
|
30
34
|
用法:
|
|
@@ -56,7 +60,7 @@ export const HELP = `flow-kit — AI-Native 闭环工作流 + wiki 知识层脚
|
|
|
56
60
|
路径下限清单 = .agents/level-hints.txt(装户自持、内容项目私有,默认空)。
|
|
57
61
|
**诚实边界**:级别是意图面的语义判定(「一处定义、多处消费」),机器判不了语义;
|
|
58
62
|
未配 hints 时按 L1 起步并提示补配置,绝不假装判得出。
|
|
59
|
-
选项:--kind
|
|
63
|
+
选项:--kind ${ROUTE_KIND_LIST} | --level L1|L2|L3
|
|
60
64
|
--files "a,b"(改动文件,参与路径下限判定)| --dir <目录> | --json
|
|
61
65
|
flow-kit run <子命令> 自动流水线:薄壳转发装户 pipeline-run 状态机
|
|
62
66
|
(start / next / status / watch / abort),参数与退出码原样透传。
|
package/src/doctor.mjs
CHANGED
|
@@ -7,6 +7,9 @@ import { createHash } from 'node:crypto';
|
|
|
7
7
|
import { listTree, scriptTrusted } from './render.mjs';
|
|
8
8
|
import { isOwned, HOSTS, pickStackVars, srcTemplatePath, templateDriftOf, TEMPLATE_DRIFT_EXCLUDE } from './profiles.mjs';
|
|
9
9
|
import { bodySha } from './sync-hosts.mjs';
|
|
10
|
+
// 委派台账分片感知读(2026-10-13 ledger-shard-ledgers 回灌):快照新鲜度判读的台账文本
|
|
11
|
+
// = 主台账 ∪ delegations.d/*.md,读侧单源复用随包模板模块(§6.5 数据行迁入分片后仍可判陈旧)。
|
|
12
|
+
import { readLedgerText } from '../templates/_agents/scripts/ledger-shards.mjs';
|
|
10
13
|
|
|
11
14
|
// 宿主目录映射(与 src/profiles.mjs#HOSTS 同源:装副本目录名前缀带点)
|
|
12
15
|
const HOST_DIR = Object.fromEntries(Object.entries(HOSTS).map(([k, v]) => [k, v.dir]));
|
|
@@ -328,7 +331,11 @@ export function doctor(args, pkgRoot) {
|
|
|
328
331
|
if (!clGuard.ok) {
|
|
329
332
|
add('WARN', `check-loop 跳过——${clGuard.note}(供应链防线:目标侧脚本与包源渲染值不符,不执行不下结论)`);
|
|
330
333
|
} else {
|
|
331
|
-
|
|
334
|
+
// 判定流水守卫(2026-10-13 judgment-ledger 回灌 B4):doctor 是体检探针而非门裁决点,
|
|
335
|
+
// 不落 .agents/judgments.jsonl(同 validate.mjs 口径;裁决链 = CLI/pre-push/CI/verify 正常落账)
|
|
336
|
+
// --all 显式全量(2026-10-13 分道后裸跑=默认硬门):doctor 是体检面,advisory 计数沿分道前全量口径。
|
|
337
|
+
const cl = spawnSync(process.execPath, ['.agents/scripts/check-loop.mjs', '--all'],
|
|
338
|
+
{ cwd: target, encoding: 'utf8', env: { ...process.env, CHECK_LOOP_NO_LEDGER: '1' } });
|
|
332
339
|
if (cl.status === 0) {
|
|
333
340
|
const warnTxt = String(cl.stderr || '').trim();
|
|
334
341
|
add('PASS', `check-loop 干净${warnTxt ? `(${warnTxt.split('\n').filter((l) => l.includes('WARN')).length} 条 advisory 警告)` : ''}`);
|
|
@@ -591,7 +598,9 @@ export function checkDelegationSnapshotFreshness(target) {
|
|
|
591
598
|
const file = path.join(target, 'workflow', 'delegations.md');
|
|
592
599
|
if (!fs.existsSync(file)) return { stale: false, ledgerMonth: null, snapshotMonth: null, skipped: true, note: 'delegations.md 不存在' };
|
|
593
600
|
let text;
|
|
594
|
-
|
|
601
|
+
// 分片感知读(2026-10-13 ledger-shard-ledgers):text = 主台账 ∪ delegations.d/*.md——数据行迁入
|
|
602
|
+
// 分片后 ledgerMonth 仍取全量数据行最大月,快照陈旧判定不失效(读侧单源 = ledger-shards.readLedgerText)。
|
|
603
|
+
try { text = readLedgerText(target, 'delegations'); } catch { return { stale: false, ledgerMonth: null, snapshotMonth: null, skipped: true, note: 'delegations.md 不可读' }; }
|
|
595
604
|
const lines = text.split(/\r?\n/);
|
|
596
605
|
let ledgerMonth = null;
|
|
597
606
|
let snapshotMonth = null;
|
package/src/executor.mjs
CHANGED
|
@@ -67,23 +67,40 @@ const DEFAULT_ROUTE_TABLE = {
|
|
|
67
67
|
};
|
|
68
68
|
const ROUTE_TABLE_LINE = /<!--\s*route-kinds:\s*([^>]*?)-->/;
|
|
69
69
|
|
|
70
|
+
// route-kinds 行的**唯一解析器**——两个消费方共用:装户面 loadRouteTable(判定该读哪个 md)与
|
|
71
|
+
// 包源 help 的 routeKindList(列 kind 值域)。此前 help 自带第二份 kind 列表,装户改 kind 时
|
|
72
|
+
// help 与判定面会漂移(与 GATE_LIST 同纪律:列表一律从权威面派生,不手写第二份)。
|
|
73
|
+
function parseRouteTable(mdAbs) {
|
|
74
|
+
const m = fs.readFileSync(mdAbs, 'utf8').match(ROUTE_TABLE_LINE);
|
|
75
|
+
const table = {};
|
|
76
|
+
for (const part of String(m ? m[1] : '').split('|')) {
|
|
77
|
+
const kv = part.trim().match(/^([a-z]+)\s*=\s*([\w.-]+\.md)$/);
|
|
78
|
+
if (kv) table[kv[1]] = kv[2];
|
|
79
|
+
}
|
|
80
|
+
if (!Object.keys(table).length) throw new Error('route-kinds 行未解析出任何 kind');
|
|
81
|
+
return table;
|
|
82
|
+
}
|
|
83
|
+
|
|
70
84
|
function loadRouteTable(target, degradations) {
|
|
71
85
|
const p = path.join(target, '.agents', 'commands', 'new-task.md');
|
|
72
86
|
try {
|
|
73
|
-
|
|
74
|
-
const table = {};
|
|
75
|
-
for (const part of String(m ? m[1] : '').split('|')) {
|
|
76
|
-
const kv = part.trim().match(/^([a-z]+)\s*=\s*([\w.-]+\.md)$/);
|
|
77
|
-
if (kv) table[kv[1]] = kv[2];
|
|
78
|
-
}
|
|
79
|
-
if (!Object.keys(table).length) throw new Error('route-kinds 行未解析出任何 kind');
|
|
80
|
-
return { table, source: 'new-task.md' };
|
|
87
|
+
return { table: parseRouteTable(p), source: 'new-task.md' };
|
|
81
88
|
} catch (e) {
|
|
82
89
|
degradations.push({ code: 'route-table-fallback', detail: `读不到装户 .agents/commands/new-task.md 的 route-kinds 机器单源(${String(e?.message || e).split('\n')[0]})——kind→入口回落包内默认表,装户升级 flow-kit sync 后生效` });
|
|
83
90
|
return { table: { ...DEFAULT_ROUTE_TABLE }, source: 'fallback' };
|
|
84
91
|
}
|
|
85
92
|
}
|
|
86
93
|
|
|
94
|
+
// 包源 help 的 kind 值域:读包源权威 md(templates/_agents/commands/new-task.md)的 route-kinds 行,
|
|
95
|
+
// 与装户面 loadRouteTable 共用同一解析器。读不到(包源缺该行/文件)回落包内默认表,不阻断 help。
|
|
96
|
+
export function routeKindList(pkgRoot) {
|
|
97
|
+
try {
|
|
98
|
+
return Object.keys(parseRouteTable(path.join(pkgRoot, 'templates', '_agents', 'commands', 'new-task.md')));
|
|
99
|
+
} catch {
|
|
100
|
+
return Object.keys(DEFAULT_ROUTE_TABLE);
|
|
101
|
+
}
|
|
102
|
+
}
|
|
103
|
+
|
|
87
104
|
// laneOfDoc:调装户 stage-gates.mjs 的单源泳道取法。返回 { key, source, reason }
|
|
88
105
|
// source='stage-gates.mjs' → 真取到单源;source='fallback' → 装户缺该脚本或取不到,按档位直接回落
|
|
89
106
|
// (fail-soft,不阻断路由)。**reason 区分「文件不存在」与「存在但 import 失败」**(2026-10-13
|
package/src/executor.test.mjs
CHANGED
|
@@ -182,7 +182,10 @@ const run = (args, cwd) => runCli(['run', ...args], cwd);
|
|
|
182
182
|
check('S5 非法 kind exit=1', k.status === 1);
|
|
183
183
|
check('S5 非法 kind 报文列合法值', k.stderr.includes('require|fix|verify|review|deploy'), k.stderr);
|
|
184
184
|
const l = route(['--level', 'L9'], r);
|
|
185
|
-
check('S5 非法 level exit=1 且列闭集', l.status === 1 && l.stderr.includes('
|
|
185
|
+
check('S5 非法 level exit=1 且列闭集', l.status === 1 && l.stderr.includes('L1|L2|L3'), l.stderr);
|
|
186
|
+
// L0 已退役(2026-10-13 自源仓收敛系列 1 回灌):--level L0 按非法档 fail-loud(枚举 fixture 已收敛 L1-L3)
|
|
187
|
+
const l0 = route(['--level', 'L0'], r);
|
|
188
|
+
check('S5b 已退役的 L0 exit=1 且报文即闭集', l0.status === 1 && l0.stderr.includes('--level 须为 L1|L2|L3'), l0.stderr);
|
|
186
189
|
const nc = mkProject({ withCrit: false });
|
|
187
190
|
const n = route([], nc);
|
|
188
191
|
check('S5 缺判据单源 exit=1', n.status === 1);
|
package/src/fresh-init.test.mjs
CHANGED
|
@@ -24,7 +24,7 @@ const r = spawnSync(process.execPath, [
|
|
|
24
24
|
const out = `${r.stdout || ''}${r.stderr || ''}`;
|
|
25
25
|
check('fresh init exit 0', r.status === 0, `exit=${r.status}\n${out.split('\n').slice(-30).join('\n')}`);
|
|
26
26
|
const kit = JSON.parse(fs.readFileSync(path.join(dir, '.agents', 'kit.json'), 'utf8'));
|
|
27
|
-
check('新装 audit 为 false 且 policyVersion 为 2', kit.audit === false && kit.policyVersion ===
|
|
27
|
+
check('新装 audit 为 false 且 policyVersion 为 12(2026-10-13 B6b-2 回灌对齐源仓 v12:新装即带全锚——§21–26 六段 + §3x + 复核上下文;新装空台账零回溯)', kit.audit === false && kit.policyVersion === 12, JSON.stringify({ audit: kit.audit, policyVersion: kit.policyVersion }));
|
|
28
28
|
// 模板下发感知初始锚(2026-10-06 template-downstream):有包源模板对应的 owned 条目带 srcSha256=
|
|
29
29
|
// 包源模板原文 LF 归一 sha;生成器目标(INDEX.md 类)排除出感知面无该键
|
|
30
30
|
{
|
package/src/init.mjs
CHANGED
|
@@ -243,9 +243,11 @@ export async function init(args, pkgRoot) {
|
|
|
243
243
|
}
|
|
244
244
|
|
|
245
245
|
// 4) .gitignore 追加(缺哪条补哪条)。2026-10-05 起七个宿主一律 localOnly:false,
|
|
246
|
-
// 宿主目录不再自动进 .gitignore
|
|
246
|
+
// 宿主目录不再自动进 .gitignore——补 .agents/cache/ 运行时缓存与 .agents/judgments.jsonl
|
|
247
|
+
// 判定流水(2026-10-13 judgment-ledger 回灌 B4:check-loop 每次真实运行追加的本机运行判定,
|
|
248
|
+
// 各机各自产生不跨机共享,月度聚合经 agg-judgments.mjs)。
|
|
247
249
|
const giPath = path.join(target, '.gitignore');
|
|
248
|
-
const giNeed = ['.agents/cache/', ...(hosts.filter((h) => HOSTS[h].localOnly).map((h) => `${HOSTS[h].dir}/`))];
|
|
250
|
+
const giNeed = ['.agents/cache/', '.agents/judgments.jsonl', ...(hosts.filter((h) => HOSTS[h].localOnly).map((h) => `${HOSTS[h].dir}/`))];
|
|
249
251
|
let giText = fs.existsSync(giPath) ? fs.readFileSync(giPath, 'utf8') : '';
|
|
250
252
|
const giAdd = giNeed.filter((l) => !giText.split(/\r?\n/).some((x) => x.trim() === l));
|
|
251
253
|
if (giAdd.length) {
|
|
@@ -331,7 +333,11 @@ export async function init(args, pkgRoot) {
|
|
|
331
333
|
fs.writeFileSync(kitPath, `${JSON.stringify({
|
|
332
334
|
kit: 'agentic-flow-kit',
|
|
333
335
|
version: pkg.version,
|
|
334
|
-
policyVersion
|
|
336
|
+
// policyVersion 12(2026-10-13 B6b-2 回灌对齐源仓 v12):新装即带全锚——v9–v12 = incidentRegrSince /
|
|
337
|
+
// specVerifSince / attributionSince / convergenceSince / convergenceHardSince / reviewerSince
|
|
338
|
+
// (§21–26 六段 + §3x 防复发证据门 + 复核上下文子检)。新装空台账零回溯:各段锚前存量豁免、空仓零
|
|
339
|
+
// 噪声;v1–v11 存量装户不受影响(缺键 → 对应消费段整体跳过)。
|
|
340
|
+
policyVersion: 12,
|
|
335
341
|
// 新装默认只跑硬规则。缺省(旧台账无此字段)在 check-loop 里仍是全量,避免升级后卫生检查突然消失。
|
|
336
342
|
audit: false,
|
|
337
343
|
// 门禁信任档(2026-10-12 gate-trust-level):默认 'project' —— gate 安装锚失配只 WARN,
|
|
@@ -347,6 +353,17 @@ export async function init(args, pkgRoot) {
|
|
|
347
353
|
}, null, 2)}\n`);
|
|
348
354
|
console.log(` kit.json 台账:managed ${managed.length} 份 | owned ${ownedFinal.length} 份(版本 ${pkg.version})`);
|
|
349
355
|
|
|
356
|
+
// 生效规则视图种子(2026-10-13 verify-gates 回灌):verify.mjs `effective-policy` 门 --check 对缺文件
|
|
357
|
+
// 判漂移(红)——源仓等价物是该生成物随生成器同笔入库;kit 新装由 init 首跑种子,保证 fresh 装户
|
|
358
|
+
// 首个 verify 不被卡。**必须在 kit.json 落盘之后**:渲染读 loadKitPolicy(.agents/kit.json 的
|
|
359
|
+
// policyVersion),先跑会按回落 v1 种子、装完即与 v12 视图漂移(fresh 实测)。本文件不入 owned 台账
|
|
360
|
+
// (生成器重写面,非模板渲染件),不受 P1-2「先跑后记账」约束;视图日期 = 安装日,--check 按磁盘
|
|
361
|
+
// 视图日期重渲染,跨锚日字节稳定。
|
|
362
|
+
if (guardRun('.agents/scripts/gen-effective-policy.mjs')) {
|
|
363
|
+
const genPolicy = runNode(target, '.agents/scripts/gen-effective-policy.mjs');
|
|
364
|
+
console.log(genPolicy.ok ? ' 已生成 workflow/effective-policy.md(生效规则视图——policy 变更后重生成并随同提交)' : ` ⚠️ gen-effective-policy 失败:${genPolicy.out.split('\n')[0]}`);
|
|
365
|
+
}
|
|
366
|
+
|
|
350
367
|
// 8) 自检(kit.json 已按生成后盘面记账——doctor §6.6 应全绿,fresh init 以 exit 0 收场)
|
|
351
368
|
// 输出语义(p2-batch1 P2-4):doctor 打印在异步端口回调里、晚于本横幅——脚本化消费方按退出码判定
|
|
352
369
|
console.log('▶ flow-kit doctor(安装产物已就位;体检 FAIL 时本命令 exit 1,产物无损——按 FAIL 项处置)');
|
package/src/profiles.mjs
CHANGED
|
@@ -116,9 +116,13 @@ export function isOwned(rel) {
|
|
|
116
116
|
// level-hints.txt(2026-10-13 flow-kit-route):风险级别**路径下限**清单,内容项目私有(照抄别人的
|
|
117
117
|
// 清单等于没登记),故归装户自持、sync 永不覆盖——与 lane-surfaces.txt 同款性质。
|
|
118
118
|
|| rel === '.agents/level-hints.txt'
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
119
|
+
|| rel === '.agents/metric-claims.txt' || rel === '.agents/metric-derivers.cjs'
|
|
120
|
+
|| rel === '.agents/metric-derivers.mjs'
|
|
121
|
+
// mechanism-registry.md(2026-10-13 judgment-ledger 回灌 B4):机制使用量登记表——装户按月对账
|
|
122
|
+
// 自持运营(增删机制行 / 刷新计数 / 退役处置),若落 managed 则每次对账编辑都报「本地已改」漂移,
|
|
123
|
+
// 与 metric-claims.txt 同款性质,归 owned(随包附带示例行起步内容,此后归项目)。
|
|
124
|
+
|| rel === '.agents/mechanism-registry.md'
|
|
125
|
+
|| rel === '.agents/hooks/local-pre-commit'
|
|
122
126
|
|| rel.startsWith('.github/');
|
|
123
127
|
}
|
|
124
128
|
|
package/src/rule-budget.test.mjs
CHANGED
|
@@ -4,7 +4,7 @@
|
|
|
4
4
|
// 两处都不跑——bb69e19/418960a 重构净增 78B 把 .agents/commands/ 推到 65581B > 65536B,包源侧零暴露,
|
|
5
5
|
// 装户首提被硬拦才发现(2026-10-11 S1 冒烟)。本套件把同一张预算表映射到包源路径核对,npm test / CI
|
|
6
6
|
// 直接拦超限——模板增长不再静默入包。run-tests 盘面 glob 自动挂载本套件。
|
|
7
|
-
// 口径(对照 templates/_agents/scripts/rule-budget.
|
|
7
|
+
// 口径(对照 templates/_agents/scripts/rule-budget.mjs 单源,勿两处漂移):
|
|
8
8
|
// 字节 = LF 归一(工作树读入去 \r\n——等价 fsize 的 git cat-file 口径,core.autocrlf 检出形态无关);
|
|
9
9
|
// 目录合计 = 扁平 glob(直接子文件,不入子目录);pat=首空格前 / lim=末空格后;lim 非纯数字行跳过;
|
|
10
10
|
// # 注释与空行跳过。
|
|
@@ -36,7 +36,7 @@ if (!fs.existsSync(BUDGETS)) {
|
|
|
36
36
|
}
|
|
37
37
|
const rows = [];
|
|
38
38
|
for (const line of fs.readFileSync(BUDGETS, 'utf8').split('\n')) {
|
|
39
|
-
const t = line.replace(/\r/g, ''); // 表文件检出即 CRLF——显式去 \r(rule-budget.
|
|
39
|
+
const t = line.replace(/\r/g, ''); // 表文件检出即 CRLF——显式去 \r(rule-budget.mjs 读取同款容 \r)
|
|
40
40
|
if (!t || t.startsWith('#')) continue;
|
|
41
41
|
const i = t.indexOf(' ');
|
|
42
42
|
if (i < 0) continue;
|
|
@@ -8,6 +8,7 @@ import os from 'node:os';
|
|
|
8
8
|
import path from 'node:path';
|
|
9
9
|
import { fileURLToPath } from 'node:url';
|
|
10
10
|
import { HELP } from './cli.mjs';
|
|
11
|
+
import { routeKindList } from './executor.mjs';
|
|
11
12
|
import { commitCheckConfig, settingsJson } from './profiles.mjs';
|
|
12
13
|
|
|
13
14
|
const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
|
|
@@ -30,6 +31,11 @@ check('help 含四套已发布门禁',
|
|
|
30
31
|
check('help 不再把当前门禁写成只有 dotnet-ca',
|
|
31
32
|
!HELP.includes('当前:dotnet-ca;') && !HELP.includes('当前:dotnet-ca)'));
|
|
32
33
|
|
|
34
|
+
// route 的 kind 值域与 GATE_LIST 同纪律:从权威面(new-task.md 的 route-kinds 机器单源)派生,
|
|
35
|
+
// 不手写第二份——否则装户改 kind 时 help 与 route 判定面双源漂移。
|
|
36
|
+
const kindList = routeKindList(ROOT).join('|');
|
|
37
|
+
check('help route kind 列表等于 new-task.md route-kinds 单源', HELP.includes(`--kind ${kindList}`), kindList);
|
|
38
|
+
|
|
33
39
|
const nodeCfg = JSON.parse(commitCheckConfig('node'));
|
|
34
40
|
check('node 构建命令带 pkg:scripts.build',
|
|
35
41
|
nodeCfg.builds.some((b) => b.command === 'npm run build' && Array.isArray(b.when) && b.when.includes('pkg:scripts.build')));
|
package/src/validate.mjs
CHANGED
|
@@ -7,6 +7,8 @@
|
|
|
7
7
|
// 落在目标仓——tracked 过滤按目标仓 HEAD 算,与 git 钩子看到的提交面一致。
|
|
8
8
|
// 只读范围:check-loop 自身仅有的两处落盘都在 .agents/cache/ 运行时缓存(gate-stats 需 --gate-stats
|
|
9
9
|
// 才触发、added-dates 缓存 best-effort),且该目录已 gitignore——本命令不改任何文档与台账。
|
|
10
|
+
// 判定流水(2026-10-13 judgment-ledger 回灌 B4):check-loop 真实运行会追加 .agents/judgments.jsonl,
|
|
11
|
+
// validate 是探针而非门裁决点(init 装后自检同路径)——挂 CHECK_LOOP_NO_LEDGER 守卫保持只读契约。
|
|
10
12
|
// 不暴露 --rev:runCheckLoop 中 rev 与 root 互斥(提交时点判定属钩子链职责,validate 只看盘面现状)。
|
|
11
13
|
// 输出契约:check-loop 的 HARD-BLOCK/WARN 两段式原样走 stderr(稳定输出契约,消费者 .githooks/pre-push);
|
|
12
14
|
// stdout 只承载本命令的汇总行 / --json——机器消费者按 stdout 解析,人按 stderr 读明细。
|
|
@@ -49,7 +51,10 @@ export async function validate(args, pkgRoot) {
|
|
|
49
51
|
// 动态 import 包内置引擎:pkgRoot = npx 缓存 / 全局安装 / 仓内直跑三种形态下都指向包源模板
|
|
50
52
|
const engineUrl = pathToFileURL(path.join(pkgRoot, 'templates', '_agents', 'scripts', 'check-loop.mjs')).href;
|
|
51
53
|
const { runCheckLoop } = await import(engineUrl);
|
|
52
|
-
|
|
54
|
+
process.env.CHECK_LOOP_NO_LEDGER = '1'; // 探针不落判定流水(守卫开关见 judgment-ledger.mjs recordRun)
|
|
55
|
+
// mode:'all' 显式全量(2026-10-13 分道后裸跑=默认硬门)——validate 自述「全部 20 项检查」且 --strict
|
|
56
|
+
// 判红的是全量 warning 面,随分道保留原语义须显式声明,勿依赖缺省。
|
|
57
|
+
const result = runCheckLoop({ root: target, mode: 'all' });
|
|
53
58
|
const code = validateExit(result, strict);
|
|
54
59
|
|
|
55
60
|
if (json) {
|
package/src/validate.test.mjs
CHANGED
package/templates/.gitattributes
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
# agentic-flow-kit:钩子与 shell 脚本必须 LF(CRLF 会破坏 Git Bash/MSYS 执行);
|
|
2
|
-
# 预算表按 LF
|
|
2
|
+
# 预算表按 LF 计量(读取方 rule-budget.mjs 容 CRLF 行尾,此条为双保险)。已有自有 .gitattributes 的项目合并这几条即可。
|
|
3
3
|
*.sh text eol=lf
|
|
4
4
|
.githooks/* text eol=lf
|
|
5
5
|
.agents/hooks/local-pre-commit text eol=lf
|
|
@@ -12,3 +12,6 @@
|
|
|
12
12
|
# **故意不加 text eol=lf**:给既有 .jsonl 加 text 规则会让下次提交时 git 重新规范化换行 → 台账 blob 字节变化
|
|
13
13
|
# → check-ledger-invariant 的 append-only 前缀不变量判为「台账重写」而硬拦。台账换行归一由 driver 自身负责。
|
|
14
14
|
.agents/*.jsonl merge=jsonl-union
|
|
15
|
+
# 分片目录(2026-10-13 ledger-shard-default):上面的 glob 不跨目录层级,confirmations.d/ 下的分片
|
|
16
|
+
# 须单列——分片已是默认写入口径,漏配则并行分支合并分片时仍走文本冲突(整取一侧 = 静默丢确认行)。
|
|
17
|
+
.agents/confirmations.d/*.jsonl merge=jsonl-union
|
package/templates/AGENTS.md
CHANGED
|
@@ -11,7 +11,7 @@
|
|
|
11
11
|
|
|
12
12
|
1. **新需求 / 功能**:先立 `workflow/intents/` intent(复制 `_TEMPLATE.md`),对话内与用户确认后开工。
|
|
13
13
|
2. **修复类任务**:先查 `workflow/incidents/` 同类历史;L1 以上立 incident(修复中即 intent 等价入口,L2/L3 与 spec/plan 同名配对)。
|
|
14
|
-
3. **级别判断与风险泳道**(就高不就低):
|
|
14
|
+
3. **级别判断与风险泳道**(就高不就低):L1 实现级(一份 plan 即入口);L2 规则/契约;L3 数据与运行时结构。L1 协作道(轻确认+异步审计);L2/L3 防御道(同步确认门:spec/plan 确认后方可动手,L3 加独立复核)。见 `.agents/commands/new-task.md`。
|
|
15
15
|
|
|
16
16
|
### 阶段路由
|
|
17
17
|
|
|
@@ -28,7 +28,7 @@
|
|
|
28
28
|
- **`git commit` / `git merge` / `git push` 三处一律禁 `--no-verify`**——被拦说明产出不合规,按提示修完原路重试。
|
|
29
29
|
- 项目专属门禁挂 `.agents/hooks/local-pre-commit`。装户五条硬规则(配对、验收、确认留痕、敏感信息、双源台账)与 `audit` 档见 `workflow/README.md`「硬规则」。
|
|
30
30
|
- 提交遵循 Conventional Commits 中文(feat / fix / docs / style / refactor / perf)。L1+ 三段式闭环链:`docs(*)` approved 留痕 → 代码 → 关单 `docs(*)`,相邻提交即同一闭环(2026-10-04 修订)。
|
|
31
|
-
- **确认门(2026-09-27 起)**:intent/spec/plan 的 approved/done 与 incident 的 fixed/closed(两跳、无单跳)唯一入口 = `node .agents/scripts/confirm-doc.mjs <path>`,放弃态走显式 `--to superseded|cancelled`(合法前态见脚本提示;四终态同样内容绑定),两形态:① 用户终端亲手运行键入「可以」(TTY,AI 会话内被拒);② **对话委托代录**——用户在对话内明确确认后,AI 跑 `confirm-doc.mjs <path> --delegated "<授权摘要>"` 逐件代录(默认一次一份,多份并录被拒),台账如实记 `source: chat-delegated`,永不伪装 TTY 行(check-loop 15 指纹+台账对账拦截,与 source 无关);
|
|
31
|
+
- **确认门(2026-09-27 起)**:intent/spec/plan 的 approved/done 与 incident 的 fixed/closed(两跳、无单跳)唯一入口 = `node .agents/scripts/confirm-doc.mjs <path>`,放弃态走显式 `--to superseded|cancelled`(合法前态见脚本提示;四终态同样内容绑定),两形态:① 用户终端亲手运行键入「可以」(TTY,AI 会话内被拒);② **对话委托代录**——用户在对话内明确确认后,AI 跑 `confirm-doc.mjs <path> --delegated "<授权摘要>"` 逐件代录(默认一次一份,多份并录被拒),台账如实记 `source: chat-delegated`,永不伪装 TTY 行(check-loop 15 指纹+台账对账拦截,与 source 无关);L1 协作道可 `--batch` 多份一次代录(台账 `brief:true`,15 并录告警豁免;L2/L3 仍逐份)。
|
|
32
32
|
- **改动面 scope = 授权的机器事实(2026-10-09 起)**:confirm-doc 落账自动记 `scope{files,sha256}`(被确认文档 + `git status` 实测未提交改动集,机器派生、**AI 无输入面**)。分辨力由 scope + 指纹承担,`--delegated` 的摘要降级为人类可读留痕——**「每次换一句原话」纪律退役**,复用同一句摘要不再削弱任何判据。check-loop 15 校验受管行带 scope 且摘要自洽(`policyVersion ≥ 7` 起,旧版本与存量行零新增告警)。
|
|
33
33
|
|
|
34
34
|
### 检索、看板与量化
|
|
@@ -55,7 +55,7 @@ next: .agents/commands/test.md
|
|
|
55
55
|
### 1.3 实现
|
|
56
56
|
|
|
57
57
|
7. 确认后按 plan 顺序推进;每个任务对照判据自验。若任务满足 `.agents/roles/implementer.md` 的边界,主智能体可将单个工作包连同必读材料、授权文件和验收条件委派给 `implementer`;否则由主智能体执行。
|
|
58
|
-
8. 自验:按改动域跑 `项目构建命令` / `项目类型检查命令` / `项目测试命令`(对应编译 / 前端类型检查 / 自动化测试;静态门全集见 `test.md` §1)
|
|
58
|
+
8. 自验:按改动域跑 `项目构建命令` / `项目类型检查命令` / `项目测试命令`(对应编译 / 前端类型检查 / 自动化测试;静态门全集见 `test.md` §1);范围对账 `node .agents/scripts/check-scope.mjs workflow/plans/YYYY-MM-DD-<主题>.md`——越界件(改了未声明)即收口(回填 plan 或回滚),plan 不可读 exit 2;默认 advisory exit 0,`--strict` 供门禁化调用。
|
|
59
59
|
9. **项目架构红线**:数据访问模式、公共字段写入等以根与目录级 `AGENTS.md`(如有)红线为准,不自创旁路。
|
|
60
60
|
10. **L3 且含 schema 变更时**:schema 变更走项目约定的维护方式(人工 SQL / 迁移工具,以目录级 `AGENTS.md` 或 spec 约束为准),不得擅自引入项目未采用的迁移机制(仅运行时 / 管线类 L3 无此约束)。
|
|
61
61
|
11. 实现中若需偏离已确认的 plan(改公共接口 / 动 plan 未列文件 / 引新依赖 / 影响任务判据)→ 停下,向用户说明原因与影响,确认后再继续。
|
|
@@ -59,7 +59,7 @@ next: .agents/commands/plan.md(若复盘需要新 intent)
|
|
|
59
59
|
**3. 规范条目**(必须有可追溯落点)
|
|
60
60
|
- 落点优先级(取最前者可行即止):`workflow/regression-checklist.md` 回归条目 / `.agents/hooks/` 或 `tests/` 断言(机器门)→ `.agents/skills/`、`.agents/notes/` → `workflow/` 文档 → `.agents/commands/`
|
|
61
61
|
- **根 `AGENTS.md` 不再是落点**;**入册门槛**:已由机器门强制的内容只留一行指针,禁止在常驻面复述;**一进一出**:落点为常驻面时须在本 commit 内删除或下沉一条被取代条目
|
|
62
|
-
- 常驻面体积预算由 pre-commit 硬拦(`
|
|
62
|
+
- 常驻面体积预算由 pre-commit 硬拦(`node .agents/scripts/rule-budget.mjs --staged`,表 `.agents/rule-budgets.txt`)——超限先删再增
|
|
63
63
|
- 引用:commit <SHA> / 文件:<路径>#L<行>;若无新增条目,理由:<已有条目覆盖,说明条目位置>
|
|
64
64
|
|
|
65
65
|
### 1.4 起草后停下
|
|
@@ -42,16 +42,18 @@ flow-kit route --files <预计改动面…> --kind require|fix|verify|review|dep
|
|
|
42
42
|
**诚实边界**:机器**无法**发现你没跑 route——定级发生在改动面确定之前,没有可比对的记录面,
|
|
43
43
|
详见 [ARCHITECTURE §5](../ARCHITECTURE.md) 与 CHANGELOG 1.7.16 B3 条。
|
|
44
44
|
|
|
45
|
-
动工前按下表定风险级
|
|
45
|
+
动工前按下表定风险级 L1-L3(就高不就低;判据细则见下节「级别判断」,单源 level-criteria.mjs),级别即风险级,决定走哪条泳道——确认放事前,还是审计补事后:
|
|
46
46
|
|
|
47
47
|
| 泳道 | 级别 | 确认与审计口径 |
|
|
48
48
|
|------|------|---------------|
|
|
49
|
-
| **协作道**(敏捷优先,审计异步补) |
|
|
49
|
+
| **协作道**(敏捷优先,审计异步补) | L1 实现级 | 一份 plan 即入口(来源 / 目标 / 红线 / 改动 / 验证 / 验收),不另立 intent。独立复核不设同步前置,check-loop 与事后 review 兜底;确认/代录可 `--batch` 批量(仅 L1) |
|
|
50
50
|
| **防御道**(严谨优先,确认同步拦) | L2 规则/契约 / L3 数据与运行时结构 | 同步确认门:spec 确认通过方可起草 plan,plan 确认后方可动手;L3 加新会话独立复核,未确认不放行 |
|
|
51
51
|
|
|
52
|
-
>
|
|
52
|
+
> **两问定级**(2026-10-13 L0 退役,自源仓收敛系列 1 回灌):结构面(schema / 迁移 SQL / DI / 认证管线)→ L3;契约或共享口径 → L2;两者都没有 → L1。不要按严重程度从 L1 往上滑。
|
|
53
|
+
> **落位**: L1 写在 plan frontmatter `级别`;L2/L3 写在 intent(intent 另以 `risk_level`=级别双写,`fill-intent.mjs` 自动写入,机器选道用)。
|
|
54
|
+
> **判低拦截**: 入口勾触达红线 → check-loop「红线判低」hard 拦 → 升到 L2/L3 并补同名 spec。
|
|
53
55
|
>
|
|
54
|
-
>
|
|
56
|
+
> **L2/L3 起草期合并预览**:三件套起草按 [design.md §0](design.md) 一次呈现要点总览(逐件确认代录不变)。
|
|
55
57
|
|
|
56
58
|
## 3. 路由判断
|
|
57
59
|
|
|
@@ -62,7 +64,7 @@ flow-kit route --files <预计改动面…> --kind require|fix|verify|review|dep
|
|
|
62
64
|
- **自动化驱动(并列入口,可选)**:一句话全程走 [pipeline-run.md](pipeline-run.md)——状态机驱动+工单协议+原话代录,与下述手动路由二选一,同一任务不混用
|
|
63
65
|
- **新需求 / 功能**:从 `plan.md` 进,立 **intent**(`workflow/intents/`)
|
|
64
66
|
- **修复类任务 / 事故**:从 `maintain.md` 进,立 **incident**(`workflow/incidents/`);incident 在 L1+ 即 **intent 等价物**(check-loop 认 incident≡intent),不必另立 intent。先检索同类历史(`node .agents/scripts/kb-search.mjs "<关键词>" --scope workflow --type incidents,plans`),有同类先读其历史三件套;再按级别走:
|
|
65
|
-
-
|
|
67
|
+
- L1 → 立 incident 后进 `build.md` 起草并确认同名 Quick-Plan → `test.md`
|
|
66
68
|
- L2/L3 → 立 incident 后进 `design.md` 起草并确认同名 spec,再进 `build.md` 起草并确认同名 plan → `test.md`
|
|
67
69
|
- 仅当根因属系统性 / 门禁缺位(maintain.md 三件套「是否需要新 intent」选"是")才另立 `workflow/intents/` 同名 intent
|
|
68
70
|
- **改完代码要验证**:直接进 `test.md`(验证通过即关单;L1 到此结束)
|
|
@@ -87,8 +89,7 @@ flow-kit route --files <预计改动面…> --kind require|fix|verify|review|dep
|
|
|
87
89
|
|
|
88
90
|
| 级别 | 单源语义(摘要) | 流程 |
|
|
89
91
|
|------|-----------------|------|
|
|
90
|
-
|
|
|
91
|
-
| L1 | 实现级改动(未命中 L2/L3) | 快车道:液态草稿(.zcode/drafts) → 实现 → 固化(`solidify-task.mjs`)——用户确认后带 `--delegated "<原话>"` 执行;无确认来源只迁移不落账 |
|
|
92
|
+
| L1 | 实现级改动(未命中 L2/L3) | 快车道:液态草稿(.zcode/drafts) → 实现 → 固化(`solidify-task.mjs`)——用户确认后带 `--delegated "<原话>"` 执行;无确认来源只迁移不落账;亦可一份 plan 即入口(不另立 intent) |
|
|
92
93
|
| L2 | 规则 / 契约(一处改、多处依赖) | 入口文档(intent / incident) + spec + plan 三件套 |
|
|
93
94
|
| L3 | 数据与运行时结构(结构面闭集见单源 `L3_SURFACES`) | 同 L2 + spec 新会话独立复核 |
|
|
94
95
|
|
|
@@ -99,7 +100,7 @@ flow-kit route --files <预计改动面…> --kind require|fix|verify|review|dep
|
|
|
99
100
|
|
|
100
101
|
## 5. intent 豁免(避免小改动也走完整闭环)
|
|
101
102
|
|
|
102
|
-
- **
|
|
103
|
+
- **L1 新需求**:一份 plan 即入口,不另立 intent(不必 spec)
|
|
103
104
|
- **docs 级改动**(AGENTS.md / workflow/ 模板 / .agents/ 脚本与 commands / yaml):豁免 intent,走 Conventional Commits 直接 commit;若同时触及代码,按代码部分级别立 intent
|
|
104
105
|
- **bootstrap 类改动**(引入规则本身):豁免 intent,commit message 显式声明 `bootstrap`
|
|
105
106
|
|
|
@@ -21,7 +21,7 @@ next: L1 → .agents/commands/build.md (起草 Quick-Plan) ;L2/L3 → .agents/
|
|
|
21
21
|
1. 若 `workflow/intents/` 已有目标 intent 且状态为 approved → 按级别跳 next(L1 → `build.md`,L2/L3 → `design.md`)。
|
|
22
22
|
2. 否则起草新 intent:
|
|
23
23
|
- **先检索同类**:`node .agents/scripts/kb-search.mjs "<关键词>" --scope workflow --type intents,specs`——命中同类先读其结论与验收,新 intent 引用(防重复立项 / 重复踩坑)
|
|
24
|
-
- **填空工具先跑**:`node .agents/scripts/fill-intent.mjs --module <模块> --level <
|
|
24
|
+
- **填空工具先跑**:`node .agents/scripts/fill-intent.mjs --module <模块> --level <L1|L2|L3> --topic <主题> --output workflow/intents/<date>-<主题>.md --notes "<备注>"`——输出含 frontmatter 6 字段(含 risk_level)+ 9 节(背景与问题/历史教训防复发/目标/非目标/约束/影响面/触达红线/验收标准 8 节正文 + 确认与复核)的草稿;AI 据此填实,模板与节标题机器保证不出错
|
|
25
25
|
- 复制 `workflow/intents/_TEMPLATE.md` → `workflow/intents/YYYY-MM-DD-<主题>.md`
|
|
26
26
|
- frontmatter 填 `模块:`(词表见 `.agents/workflow-modules.txt`,新建文档必填,check-loop 会警告)
|
|
27
27
|
- 按 8 节填写:背景与问题 / 历史教训防复发 / 目标(可验证) / 非目标 / 约束 / 影响面 / 触达红线 / 验收标准(L1 微改动可省非目标/约束两节,不硬填)
|
|
@@ -58,5 +58,5 @@ next: .agents/commands/build.md(仅 P0 / P1 未清时;清零后经用户确
|
|
|
58
58
|
|
|
59
59
|
- **机器兜底**(pre-commit / pre-push / test 自动拦,无需人守):门禁清单与判据以 `.githooks/`、`.agents/hooks/`、`check-loop.sh` 头部注释为准;`项目测试命令` 跑自动化用例。
|
|
60
60
|
- **AI 复核**:机器门禁完成后优先委派 `independent-reviewer`,聚焦 P0 hook 未覆盖项 + 全部 P1(P2 视精力)——产出分级问题清单 + 修复建议。复核方法参考 `code-review` 技能(Standards×Spec 双轴);每条 finding 报告前过 `review-verification-protocol` 防误报门(锚定 file:line、给出证据、校准严重级,不确定就降级为提问)。
|
|
61
|
-
- **独立性**:L2 / L3 必须用独立子智能体,宿主不支持时另开新会话,不得由原作者自查冒充;
|
|
61
|
+
- **独立性**:L2 / L3 必须用独立子智能体,宿主不支持时另开新会话,不得由原作者自查冒充;L1 且宿主不支持子智能体时可由主智能体按同一复核契约执行。
|
|
62
62
|
- **用户决策**:问题定性(误报驳回 / P0 成立必修 / P1、P2 处置裁量)+ 合入时机;git 历史即评审记录,追溯靠 commit 与 tag。
|
|
@@ -74,7 +74,7 @@ npx agentic-flow-kit doctor # §6.5 delegations + §6.6 o
|
|
|
74
74
|
|
|
75
75
|
- 输出测试报告(通过项 / 失败项);失败项已修复并复测通过。
|
|
76
76
|
- **关单**(日常闭环点,不依赖是否上 prod):
|
|
77
|
-
- 关单前一键过门:`node .agents/scripts/verify.mjs --doc workflow/intents/<本单>.md
|
|
77
|
+
- 关单前一键过门:`node .agents/scripts/verify.mjs --doc workflow/intents/<本单>.md`(七门编排:语法/测试/编排检查/预算/生效规则视图/闭环/台账不变量,fail-fast 失败行留痕,非绿不关单);**`--doc` 把绿凭证绑到本单**——不带它落下的绿行不给任何单背书,confirm-doc 前置与检查 8 只认带本单 `--doc` 的绿行(仅 v6+ 生效);**全绿尾部自动落凭证并重生成 `workflow/verify-evidence.md`**(`effective-policy.md` 同为生成物——两者勿手改,policy/台账变更后重生成随同提交);**装户仓**(当前目录无 `package.json`)测试门显式跳过且**不落测试绿凭证**(防假绿),按项目口径手工跑或带 `--test-cmd "<项目测试命令>"` 指定
|
|
78
78
|
- 新需求:逐条勾验入口 intent「验收标准」,每条补「证据:」(例如:粘贴 CI 运行结果、UI 截图路径、或具体的 commit SHA),intent → done;同名 spec/Quick-Plan(若有)仍 approved → done。**注意:勾选但缺证据会被 check-loop 拦截(hard-block)**
|
|
79
79
|
- **approved 留痕提交**:done 确认前确认**本次关单文档**的 approved 态已进 git 历史(越早越好——approved 后即应提交;若尚未,先补提交再 done;门为逐份校验,三件套均关单时逐份各自满足)——confirm-doc 的 done 前置门硬校验(历史未出现「状态: approved」→ 拒绝落账);done 后再提交 done 态与其余改动
|
|
80
80
|
- **确认落态**:唯一入口 `node .agents/scripts/confirm-doc.mjs <path>`(两形态 / 逐件代录(摘要可复用——分辨力由 scope+指纹承担)/ done 内容绑定(关单编辑先于 done 确认、confirm-doc 是最后一次写入)/ 台账对质全口径见根 `AGENTS.md` §1.3 确认门)。
|