@elvis1513/auto-coding-skill 2.1.0 → 2.1.1
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 +88 -35
- package/cli/assets/agents/explorer.toml +1 -1
- package/cli/assets/agents/fixer.toml +1 -1
- package/cli/assets/agents/reviewer.toml +7 -6
- package/cli/assets/skill/SKILL.md +37 -24
- package/cli/assets/skill/data/templates/ENGINEERING.md +67 -36
- package/cli/assets/skill/data/templates/bridges/{CLAUDE.md → AGENTS.md} +3 -2
- package/cli/assets/skill/data/templates/docs/architecture/structure-standard.md +8 -0
- package/cli/assets/skill/data/templates/docs/deployment/deploy-records/_TEMPLATE-DEPLOY-RECORD.md +1 -1
- package/cli/assets/skill/data/templates/docs/deployment/deploy-runbook.md +1 -1
- package/cli/assets/skill/data/templates/docs/reviews/_TEMPLATE-REVIEW.md +4 -4
- package/cli/assets/skill/data/templates/docs/reviews/optimization-backlog.md +1 -0
- package/cli/assets/skill/data/templates/docs/reviews/project-health-baseline.md +4 -1
- package/cli/assets/skill/data/templates/docs/tasks/closure-log.md +6 -6
- package/cli/assets/skill/data/templates/docs/tasks/summaries/_TEMPLATE-TASK-SUMMARY.md +2 -2
- package/cli/assets/skill/data/templates/docs/tasks/taskbook.md +6 -6
- package/cli/assets/skill/scripts/ap.py +743 -91
- package/cli/src/index.js +137 -74
- package/cli/tests/index.test.js +146 -0
- package/package.json +7 -7
- package/cli/assets/skill/data/templates/bridges/CODEX.md +0 -11
|
@@ -5,7 +5,7 @@ workflow:
|
|
|
5
5
|
project:
|
|
6
6
|
name: ""
|
|
7
7
|
repo_root: "."
|
|
8
|
-
stack: "
|
|
8
|
+
stack: "generic"
|
|
9
9
|
backend_dir: ""
|
|
10
10
|
frontend_dir: ""
|
|
11
11
|
go_main: ""
|
|
@@ -66,7 +66,6 @@ structure:
|
|
|
66
66
|
block_new_responsibility_in_large_file: true
|
|
67
67
|
allow_large_files:
|
|
68
68
|
- ".agents/skills/**"
|
|
69
|
-
- ".claude/skills/**"
|
|
70
69
|
- "docs/tools/autopipeline/**"
|
|
71
70
|
- "generated/**"
|
|
72
71
|
- "**/generated/**"
|
|
@@ -160,6 +159,10 @@ runtime:
|
|
|
160
159
|
env_file: ""
|
|
161
160
|
startup_timeout_sec: 120
|
|
162
161
|
|
|
162
|
+
verification:
|
|
163
|
+
target_env_required: true
|
|
164
|
+
jenkins_required: true
|
|
165
|
+
|
|
163
166
|
target_env:
|
|
164
167
|
name: ""
|
|
165
168
|
frontend_base_url: ""
|
|
@@ -191,6 +194,14 @@ docs:
|
|
|
191
194
|
closure_log: "docs/tasks/closure-log.md"
|
|
192
195
|
evidence_log: "docs/tasks/evidence.jsonl"
|
|
193
196
|
design_dir: "docs/design"
|
|
197
|
+
task_archive_dir: "docs/tasks/archives"
|
|
198
|
+
design_archive_dir: "docs/archive/design"
|
|
199
|
+
archive_index: "docs/tasks/archive-index.md"
|
|
200
|
+
ledger_check_enabled: true
|
|
201
|
+
ledger_block_on_exceed: true
|
|
202
|
+
active_taskbook_max_lines: 1200
|
|
203
|
+
active_closure_log_max_lines: 800
|
|
204
|
+
active_design_max_files: 120
|
|
194
205
|
review_dir: "docs/reviews"
|
|
195
206
|
health_baseline: "docs/reviews/project-health-baseline.md"
|
|
196
207
|
optimization_backlog: "docs/reviews/optimization-backlog.md"
|
|
@@ -207,8 +218,8 @@ docs:
|
|
|
207
218
|
|
|
208
219
|
目标:默认采用高效率开发闭环,并通过 `workflow.mode` 控制流程长度。
|
|
209
220
|
|
|
210
|
-
- `dev`:开发模式,最快闭环。轻量门禁通过后,提前写 `DEV-CLOSED` 闭环,commit + push
|
|
211
|
-
- `verify`:验证模式,完整闭环。轻量门禁、commit + push
|
|
221
|
+
- `dev`:开发模式,最快闭环。轻量门禁通过后,提前写 `DEV-CLOSED` 闭环,commit + push 后结束。
|
|
222
|
+
- `verify`:验证模式,完整闭环。轻量门禁、commit + push、已启用的 CI/Jenkins 构建验证和目标环境验证全部完成后,写 `PASS` 闭环。
|
|
212
223
|
|
|
213
224
|
默认原则:
|
|
214
225
|
- 默认不要求本地 Docker Compose 启动。
|
|
@@ -217,13 +228,14 @@ docs:
|
|
|
217
228
|
- 默认不要求每个小改动生成长 summary。
|
|
218
229
|
- 默认不要求 regression matrix 全 PASS。
|
|
219
230
|
- 默认不要求 deployment record。
|
|
220
|
-
- Jenkins 构建结果和目标环境真实验证,比本地模拟更重要。
|
|
231
|
+
- 已启用的 CI/Jenkins 构建结果和目标环境真实验证,比本地模拟更重要。
|
|
221
232
|
|
|
222
233
|
补充规则:
|
|
223
234
|
- 每次任务闭环后,必须清理临时文件、临时目录、日志、截图、构建缓存等非必要产物;仅明确需要保留的本地诊断目录允许保留。
|
|
224
235
|
- 所有手工填写信息,只维护在本文件 frontmatter 中,其他文档不得重复配置。
|
|
225
236
|
- `docs/ENGINEERING.md` 必须提交到 Git 管理,不允许写入 `.gitignore`。
|
|
226
237
|
- 目标环境和 Jenkins 密码默认通过 `*_password_env` 指向当前 shell 中的环境变量;确需兼容旧项目时才使用明文 `*_password` 字段。
|
|
238
|
+
- 非 Jenkins 或本地-only 项目可以把 `verification.jenkins_required` / `verification.target_env_required` 设为 `false`,让 `doctor` 只检查通用门禁、文档和结构配置。
|
|
227
239
|
- 未参与默认流程的环境项不要保留占位;模板中未保留的字段视为已清理,不再额外配置。
|
|
228
240
|
|
|
229
241
|
---
|
|
@@ -238,10 +250,13 @@ docs:
|
|
|
238
250
|
- `structure.*`:通用工程结构阈值、允许的大文件模式、复用搜索目录
|
|
239
251
|
- `structure.layer_rules`:通用分层 import 边界检查;项目可按技术栈细化路径
|
|
240
252
|
- `optimization.*`:健康基线感知的优化闭环口径,避免重复把已接受债务判定为当前未完成
|
|
253
|
+
- `verification.target_env_required` / `verification.jenkins_required`:控制 `doctor` 是否强校验目标环境和 Jenkins 配置
|
|
241
254
|
- `docs.evidence_log`:结构化证据 JSONL,记录 doctor / gate / verify / closure 等实际执行结果
|
|
255
|
+
- `docs.task_archive_dir` / `docs.design_archive_dir` / `docs.archive_index`:文档账本物理归档目录和导航索引;索引不能替代归档
|
|
256
|
+
- `docs.active_taskbook_max_lines` / `docs.active_closure_log_max_lines` / `docs.active_design_max_files`:活跃账本预算,超过后必须归档瘦身
|
|
242
257
|
- `docs.health_baseline` / `docs.optimization_backlog` / `docs.structure_standard` / `docs.adr_dir`:项目结构治理文档位置
|
|
243
|
-
- `target_env
|
|
244
|
-
- `jenkins
|
|
258
|
+
- `target_env.*`:当 `verification.target_env_required: true` 时,目标环境前端 / 后端地址、用户名、密码引用必须全部填写且真实可用
|
|
259
|
+
- `jenkins.*`:当 `verification.jenkins_required: true` 时,Jenkins UI/API 用户名、密码引用、Job、分支、镜像、部署环境必须全部填写且真实可用
|
|
245
260
|
|
|
246
261
|
字段说明:
|
|
247
262
|
- `target_env.backend_username` + `target_env.backend_password_env` 或 `target_env.backend_password`:目标环境后台账号
|
|
@@ -254,6 +269,10 @@ docs:
|
|
|
254
269
|
- `workflow.mode`
|
|
255
270
|
- `project.name`
|
|
256
271
|
- `commands.gate_changed` / `commands.gate_standard` / `commands.gate_full`,或 `commands.light_gate` / `commands.quick_test` / `commands.test` / `commands.build`
|
|
272
|
+
- `verification.target_env_required`
|
|
273
|
+
- `verification.jenkins_required`
|
|
274
|
+
|
|
275
|
+
当 `verification.target_env_required: true` 时必填:
|
|
257
276
|
- `target_env.name`
|
|
258
277
|
- `target_env.frontend_base_url`
|
|
259
278
|
- `target_env.frontend_username`
|
|
@@ -265,6 +284,8 @@ docs:
|
|
|
265
284
|
- `target_env.backend_root_password` 或 `target_env.backend_root_password_env`
|
|
266
285
|
- `target_env.health_base_url`
|
|
267
286
|
- `target_env.health_path`
|
|
287
|
+
|
|
288
|
+
当 `verification.jenkins_required: true` 时必填:
|
|
268
289
|
- `jenkins.base_url`
|
|
269
290
|
- `jenkins.ui_username`
|
|
270
291
|
- `jenkins.ui_password` 或 `jenkins.ui_password_env`
|
|
@@ -287,6 +308,8 @@ docs:
|
|
|
287
308
|
- `structure.allow_large_files`:生成物、供应商代码、构建产物等允许超长或跳过结构检查的路径
|
|
288
309
|
- `structure.accepted_debt_paths`:已记录为接受债务的历史大文件;只豁免历史体量,不豁免继续大幅新增
|
|
289
310
|
- `optimization.completion_policy`:默认 `baseline-aware`,表示“优化完成”按本轮范围和已记录基线判断,不等于仓库没有任何可优化点
|
|
311
|
+
- `docs.ledger_check_enabled`:默认启用文档账本健康检查
|
|
312
|
+
- `docs.ledger_block_on_exceed`:默认阻塞超过预算的活跃账本;仅迁移期才允许临时关闭
|
|
290
313
|
- `runtime.*`:仅在本地运行诊断时使用
|
|
291
314
|
- `commands.build` / `commands.test` / `commands.quick_test` / `commands.lint` / `commands.typecheck` / `commands.format`:按项目实际情况保留
|
|
292
315
|
|
|
@@ -296,24 +319,28 @@ docs:
|
|
|
296
319
|
|
|
297
320
|
1) `docs/ENGINEERING.md`
|
|
298
321
|
2) `docs/tasks/taskbook.md`
|
|
299
|
-
3) `docs/
|
|
300
|
-
4) `docs/
|
|
301
|
-
5) `docs/
|
|
302
|
-
6) `docs/
|
|
303
|
-
7) `docs/
|
|
304
|
-
8) `docs/
|
|
305
|
-
9) `docs/
|
|
306
|
-
10) `docs/
|
|
307
|
-
11)
|
|
322
|
+
3) `docs/tasks/archives/**`
|
|
323
|
+
4) `docs/design/**`
|
|
324
|
+
5) `docs/archive/design/**`
|
|
325
|
+
6) `docs/interfaces/api.md`
|
|
326
|
+
7) `docs/interfaces/api-change-log.md`
|
|
327
|
+
8) `docs/testing/regression-matrix.md`
|
|
328
|
+
9) `docs/bugs/bug-list.md`
|
|
329
|
+
10) `docs/tasks/closure-log.md`
|
|
330
|
+
11) `docs/tasks/summaries/**`
|
|
331
|
+
12) `docs/deployment/**`
|
|
332
|
+
13) 代码实现
|
|
308
333
|
|
|
309
334
|
说明:
|
|
310
335
|
- `closure-log.md` 是每个任务默认必须留下的轻量闭环记录。
|
|
336
|
+
- `taskbook.md`、`closure-log.md` 和顶层 `docs/design/T*.md` 是活跃账本,不是永久历史仓库。超过预算时必须把已关闭历史内容物理归档到 `docs/tasks/archives/**` 和 `docs/archive/design/**`。
|
|
337
|
+
- `docs/tasks/archive-index.md` 只用于导航归档位置;只有索引、没有物理归档,不算完成账本瘦身。
|
|
311
338
|
- `summaries/**` 只用于跨模块、高风险、阶段性里程碑、需要完整复盘的任务。
|
|
312
339
|
- `deployment/**` 只用于真实部署记录、手工发布或高风险发布场景。
|
|
313
340
|
|
|
314
341
|
---
|
|
315
342
|
|
|
316
|
-
## 1.5
|
|
343
|
+
## 1.5 工具使用策略(通用 .agents 默认)
|
|
317
344
|
|
|
318
345
|
任务开始时先做能力盘点:当前可用的 MCP servers、已安装 skills、plugins / apps / connectors、浏览器控制能力、repo 脚本。能直接读取权威状态、当前文档或真实 UI 的能力,优先于手写推测。
|
|
319
346
|
|
|
@@ -356,7 +383,7 @@ docs:
|
|
|
356
383
|
|
|
357
384
|
---
|
|
358
385
|
|
|
359
|
-
## 1.6 多 Agent
|
|
386
|
+
## 1.6 多 Agent 协作策略(通用 .agents 默认)
|
|
360
387
|
|
|
361
388
|
默认使用 `.agents/agents` 中的角色模型来拆解任务;只有在当前客户端明确提供并允许子代理/多代理工具时,才实际并行派发。若运行时策略不允许子代理,则由主 agent 按同一角色顺序串行完成,不假装并行。
|
|
362
389
|
|
|
@@ -380,7 +407,7 @@ docs:
|
|
|
380
407
|
主 agent 始终负责:
|
|
381
408
|
- 任务定义、范围裁决、方案取舍
|
|
382
409
|
- 代码集成和冲突处理
|
|
383
|
-
-
|
|
410
|
+
- 轻量门禁、已启用的 CI/Jenkins/目标环境闭环
|
|
384
411
|
- 文档闭环、Git 状态、最终交付
|
|
385
412
|
|
|
386
413
|
任务边界不清、需要强一致裁决或涉及架构取舍时,由主 agent 保持控制,不机械拆分。
|
|
@@ -416,7 +443,11 @@ docs:
|
|
|
416
443
|
- 发布、跨模块重构、架构调整默认执行:`python3 docs/tools/autopipeline/ap.py structure-check --scope full`
|
|
417
444
|
- 首次落基线:`python3 docs/tools/autopipeline/ap.py baseline init --write --update-config`
|
|
418
445
|
- 项目升级预检:`python3 docs/tools/autopipeline/ap.py upgrade --dry-run`
|
|
446
|
+
- 文档账本健康检查:`python3 docs/tools/autopipeline/ap.py docs-ledger-check`
|
|
447
|
+
- 文档账本归档预览:`python3 docs/tools/autopipeline/ap.py docs-ledger-archive --plan`
|
|
448
|
+
- 文档账本归档执行:`python3 docs/tools/autopipeline/ap.py docs-ledger-archive --write`
|
|
419
449
|
- 门禁耗时画像:`python3 docs/tools/autopipeline/ap.py gate-profile`
|
|
450
|
+
- `doctor` 默认纳入文档账本健康检查;`light-gate` 会先跑 `doctor`,因此活跃账本超预算会阻塞后续任务,避免“只建索引、不归档瘦身”的状态长期存在。
|
|
420
451
|
- `light-gate` 在 `structure.enabled: true` 时会自动纳入结构检查;如项目需要更强规则,可配置 `commands.structure_check` 覆盖内置实现。
|
|
421
452
|
|
|
422
453
|
---
|
|
@@ -431,21 +462,21 @@ docs:
|
|
|
431
462
|
|
|
432
463
|
规则:
|
|
433
464
|
- 只跑最轻量门禁。
|
|
434
|
-
- push
|
|
465
|
+
- push 后不等待、不轮询、不验证目标环境。
|
|
435
466
|
- `closure-log.md` 必须提前写入本次提交。
|
|
436
467
|
- 闭环结果写 `DEV-CLOSED`,不要伪装成完整 `PASS`。
|
|
437
|
-
- Jenkins Build 写 `triggered by push, not verified in dev mode
|
|
468
|
+
- CI/Jenkins Build 写 `triggered by push, not verified in dev mode` 或项目等价表述。
|
|
438
469
|
- Target Env 写 `not verified in dev mode`。
|
|
439
470
|
|
|
440
471
|
### 2.2 验证模式:`workflow.mode: "verify"`
|
|
441
472
|
|
|
442
473
|
用于发布前、验收、高风险变更或需要完整证据的任务。默认闭环:
|
|
443
474
|
|
|
444
|
-
需求确认 → 最小设计 / 必要 DD → 开发实现 → 本地轻量校验 → commit + push → Jenkins 构建验证 →
|
|
475
|
+
需求确认 → 最小设计 / 必要 DD → 开发实现 → 本地轻量校验 → commit + push → 已启用的 CI/Jenkins 构建验证 → 已启用的目标环境验证 → 写 `PASS` 闭环
|
|
445
476
|
|
|
446
477
|
规则:
|
|
447
|
-
- Jenkins 构建必须成功。
|
|
448
|
-
-
|
|
478
|
+
- 若 `verification.jenkins_required: true`,CI/Jenkins 构建必须成功。
|
|
479
|
+
- 若 `verification.target_env_required: true`,目标环境健康检查必须通过。
|
|
449
480
|
- 关键接口 / 页面路径按任务需要补充验证。
|
|
450
481
|
- 只有真实验证完成后,闭环结果才允许写 `PASS`。
|
|
451
482
|
- 回归矩阵只有真实执行并有证据时才允许标 `PASS`。
|
|
@@ -453,10 +484,10 @@ docs:
|
|
|
453
484
|
### 2.3 任务步骤
|
|
454
485
|
|
|
455
486
|
1. 需求确认
|
|
456
|
-
明确任务范围、影响服务、是否涉及 API/数据库/部署/Jenkins/前端页面。
|
|
487
|
+
明确任务范围、影响服务、是否涉及 API/数据库/部署/CI/Jenkins/前端页面。
|
|
457
488
|
|
|
458
489
|
2. 最小设计记录
|
|
459
|
-
普通小改动只更新 `taskbook` 或设计文档中的最小必要段落;跨模块、接口、数据库、部署、Jenkins、关键页面流程变更才补 DD。
|
|
490
|
+
普通小改动只更新 `taskbook` 或设计文档中的最小必要段落;跨模块、接口、数据库、部署、CI/Jenkins、关键页面流程变更才补 DD。
|
|
460
491
|
|
|
461
492
|
3. 开发实现
|
|
462
493
|
只修改本次任务必要文件,不做无关重构。
|
|
@@ -467,25 +498,25 @@ docs:
|
|
|
467
498
|
- 若未配置,则执行 `quick_test` / `test` / `build` 中最先配置的一项
|
|
468
499
|
- `git diff --check`
|
|
469
500
|
- API 文档检查
|
|
470
|
-
- Jenkins 配置检查
|
|
501
|
+
- 已启用的 CI/Jenkins 配置检查
|
|
471
502
|
|
|
472
503
|
5. 提交推送
|
|
473
|
-
`dev` 模式先写开发闭环再 commit + push;`verify` 模式 commit + push
|
|
504
|
+
`dev` 模式先写开发闭环再 commit + push;`verify` 模式 commit + push 后继续验证已启用的 CI/Jenkins 和目标环境。
|
|
474
505
|
|
|
475
|
-
6. Jenkins 验证
|
|
476
|
-
仅 `verify`
|
|
506
|
+
6. CI/Jenkins 验证
|
|
507
|
+
仅 `verify` 模式且 `verification.jenkins_required: true` 时默认执行。查看 CI/Jenkins 构建、镜像、部署结果;失败则根据日志修复,再次提交推送。
|
|
477
508
|
|
|
478
509
|
7. 目标环境验证
|
|
479
|
-
仅 `verify`
|
|
510
|
+
仅 `verify` 模式且 `verification.target_env_required: true` 时默认执行。在真实目标环境做健康检查、关键接口、关键页面或业务路径验证。
|
|
480
511
|
|
|
481
512
|
8. 回归与证据记录
|
|
482
|
-
|
|
513
|
+
只有真实执行过已启用的 CI/Jenkins / 目标环境验证,或显式要求本地运行验证时,才允许把 `regression-matrix.md` 标为 `PASS`。
|
|
483
514
|
|
|
484
515
|
9. 闭环记录
|
|
485
516
|
每个任务必须留下轻量闭环记录。`dev` 模式用 `DEV-CLOSED`,`verify` 模式用 `PASS` / `FAIL` / `PARTIAL`。
|
|
486
517
|
|
|
487
518
|
10. 配置入库
|
|
488
|
-
`docs/ENGINEERING.md`
|
|
519
|
+
`docs/ENGINEERING.md` 中保留下来的已启用环境信息、前端/后端账号、Jenkins 账号与密码必须 100% 填写、正确填写,并提交 Git 作为项目权威配置持续维护。
|
|
489
520
|
|
|
490
521
|
---
|
|
491
522
|
|
|
@@ -495,14 +526,14 @@ docs:
|
|
|
495
526
|
- 数据库迁移
|
|
496
527
|
- 鉴权 / 权限
|
|
497
528
|
- 支付 / 订单
|
|
498
|
-
- 部署 / Jenkins
|
|
529
|
+
- 部署 / CI / Jenkins
|
|
499
530
|
- Nginx / 网关
|
|
500
531
|
- 文件上传 / 下载
|
|
501
532
|
- 生产配置
|
|
502
533
|
|
|
503
534
|
高风险变更至少额外要求:
|
|
504
535
|
- 明确 DD
|
|
505
|
-
- 使用 `workflow.mode: "verify"`,或在 `dev`
|
|
536
|
+
- 使用 `workflow.mode: "verify"`,或在 `dev` 快速闭环后显式补已启用的目标环境真实验证
|
|
506
537
|
- 闭环记录写清楚验证路径和结果
|
|
507
538
|
- 必要时补 summary / deployment record / regression matrix
|
|
508
539
|
|
|
@@ -510,7 +541,7 @@ docs:
|
|
|
510
541
|
|
|
511
542
|
## 4. 本地 Docker 与完整回归(按需,不默认)
|
|
512
543
|
|
|
513
|
-
以下能力保留,但仅用于显式要求、问题复现、Jenkins/目标环境问题前置诊断:
|
|
544
|
+
以下能力保留,但仅用于显式要求、问题复现、CI/Jenkins/目标环境问题前置诊断:
|
|
514
545
|
- `runtime-up`
|
|
515
546
|
- `runtime-down`
|
|
516
547
|
- 本地 health check
|
|
@@ -5,7 +5,8 @@ Obey `structure.layer_rules` import boundaries unless a DD/ADR explicitly record
|
|
|
5
5
|
Before optimization reviews, read the project health baseline and optimization backlog, and report only new, worsened, unrecorded P0/P1, or upgraded-priority items.
|
|
6
6
|
Route work through already available MCP servers, installed skills, plugins, and app connectors when they provide current docs, design context, browser evidence, GitHub/CI state, security review, or artifact rendering.
|
|
7
7
|
Use the `.agents/agents` role model when available: explorer, docs_researcher, browser_debugger, fixer, reviewer. If the client cannot run subagents, execute the same roles sequentially in the main agent.
|
|
8
|
-
Default to the lightweight local gate first; when `structure.enabled` is true
|
|
8
|
+
Default to the lightweight local gate first; `doctor` includes `docs-ledger-check`, and when `structure.enabled` is true the gate includes `structure-check`.
|
|
9
|
+
Keep active docs ledgers small: `taskbook.md`, `closure-log.md`, and top-level `docs/design/T*.md` must be physically archived when over budget. Use `docs-ledger-archive --plan` before `--write`; `archive-index.md` is only navigation.
|
|
9
10
|
Keep `docs/tasks/evidence.jsonl` and closure Markdown aligned with actual executed checks.
|
|
10
|
-
Use Jenkins build verification and real target-environment verification as the primary completion gate in verify mode.
|
|
11
|
+
Use configured CI/Jenkins build verification and real target-environment verification as the primary completion gate in verify mode when their `verification.*_required` switches are enabled.
|
|
11
12
|
Local Docker Compose and full local regression are on-demand diagnostic tools, not the default gate for every small change.
|
|
@@ -81,3 +81,11 @@
|
|
|
81
81
|
- `docs/tasks/evidence.jsonl` 记录 doctor、classify、structure-check、light-gate、verify、closure 等结构化证据。
|
|
82
82
|
- `.local/auto-coding-skill/gate-profile.jsonl` 记录门禁命令耗时和失败率,用于优化小步快跑的 gate 范围。
|
|
83
83
|
- Markdown 记录面向人读,JSONL 记录面向工具复盘;两者不互相替代。
|
|
84
|
+
|
|
85
|
+
## 8. Docs Ledger Health
|
|
86
|
+
|
|
87
|
+
- `docs/tasks/taskbook.md`、`docs/tasks/closure-log.md` 和顶层 `docs/design/T*.md` 是活跃工作账本,不是永久历史仓库。
|
|
88
|
+
- 超过 `docs.active_taskbook_max_lines`、`docs.active_closure_log_max_lines` 或 `docs.active_design_max_files` 后,必须把已关闭历史内容物理归档到 `docs.task_archive_dir` / `docs.design_archive_dir`。
|
|
89
|
+
- 归档必须先运行 `docs-ledger-archive --plan` 并确认只包含已关闭任务、无 active task 冲突的闭环记录和对应顶层 DD,再运行 `docs-ledger-archive --write`。补历史月份时才加 `--period 2026-06`。
|
|
90
|
+
- `docs.archive_index` 只能做导航和检索入口。只有索引、没有物理归档,仍然是不合格的账本瘦身。
|
|
91
|
+
- `doctor` 默认执行 `docs-ledger-check`。迁移期可以临时调高预算或关闭阻塞,但必须在 backlog 中记录恢复条件。
|
|
@@ -3,7 +3,7 @@
|
|
|
3
3
|
> 仅在任务需要独立 review 记录时使用;不是每个小改动的默认强制文档。
|
|
4
4
|
|
|
5
5
|
## 1. 静态分析结果
|
|
6
|
-
- Command:structure-check / light_gate / diff_check / verify_api_docs / verify_jenkins
|
|
6
|
+
- Command:structure-check / light_gate / diff_check / verify_api_docs / verify_jenkins / verify_jenkins_skipped
|
|
7
7
|
- Summary:
|
|
8
8
|
- Issues:
|
|
9
9
|
|
|
@@ -21,13 +21,13 @@
|
|
|
21
21
|
- gate-profile:`.local/auto-coding-skill/gate-profile.jsonl`
|
|
22
22
|
- evidence-log:`docs/tasks/evidence.jsonl`
|
|
23
23
|
- api docs:
|
|
24
|
-
- jenkins:
|
|
24
|
+
- ci/jenkins:
|
|
25
25
|
|
|
26
26
|
## 4. 按需本地运行验证(如果有)
|
|
27
27
|
- runtime-up / health:
|
|
28
28
|
|
|
29
|
-
## 5. Jenkins 与目标环境
|
|
30
|
-
- Jenkins readiness:
|
|
29
|
+
## 5. CI/Jenkins 与目标环境
|
|
30
|
+
- CI/Jenkins readiness:
|
|
31
31
|
- Target env verification:
|
|
32
32
|
|
|
33
33
|
## 6. 风险与结论
|
|
@@ -15,6 +15,7 @@
|
|
|
15
15
|
| ID | Priority | Status | Scope | Item | Reason | Acceptance | Last reviewed |
|
|
16
16
|
| --- | --- | --- | --- | --- | --- | --- | --- |
|
|
17
17
|
| OPT-000 | P2 | open | `<path/module>` | | | | YYYY-MM-DD |
|
|
18
|
+
| LEDGER-000 | P2 | open | `docs/tasks`, `docs/design` | Archive active ledgers when they exceed `docs.active_*` budgets | Keeps project context searchable and prevents giant task/closure/DD files | `ap.py docs-ledger-archive --plan` reviewed, `--write` applied when safe, then `ap.py docs-ledger-check` passes | YYYY-MM-DD |
|
|
18
19
|
|
|
19
20
|
## Review Rules
|
|
20
21
|
|
|
@@ -15,6 +15,9 @@
|
|
|
15
15
|
| Area | Current state | Accepted because | Review date |
|
|
16
16
|
| --- | --- | --- | --- |
|
|
17
17
|
| <module/path> | | | |
|
|
18
|
+
| `docs/tasks/taskbook.md` | active ledger, <= configured line budget | History is archived under `docs/tasks/archives/**` | YYYY-MM-DD |
|
|
19
|
+
| `docs/tasks/closure-log.md` | active closure ledger, <= configured line budget | History is archived under `docs/tasks/archives/**` | YYYY-MM-DD |
|
|
20
|
+
| `docs/design/` | active DDs only, <= configured file budget | Historical DDs are archived under `docs/archive/design/**` | YYYY-MM-DD |
|
|
18
21
|
|
|
19
22
|
## 2. Closed Optimization Scope
|
|
20
23
|
|
|
@@ -44,7 +47,7 @@
|
|
|
44
47
|
An optimization task is complete when all are true:
|
|
45
48
|
|
|
46
49
|
- The scoped P0/P1/P2 items listed for this task are closed.
|
|
47
|
-
- Local gate passed, including structure
|
|
50
|
+
- Local gate passed, including docs ledger and structure checks when enabled.
|
|
48
51
|
- No new unclassified P0/P1 was introduced.
|
|
49
52
|
- Remaining P2/P3 items are either in `docs/reviews/optimization-backlog.md` or accepted debt above.
|
|
50
53
|
- Review output says explicitly whether the project meets this baseline.
|
|
@@ -2,9 +2,9 @@
|
|
|
2
2
|
|
|
3
3
|
规则:
|
|
4
4
|
1) 每个任务完成后,至少追加一条闭环记录
|
|
5
|
-
2) `dev`
|
|
6
|
-
3) `verify`
|
|
7
|
-
4) Jenkins 失败后再修复的任务,应补充失败原因和修复提交
|
|
5
|
+
2) `dev` 模式记录开发闭环:轻量门禁通过、已提交推送,CI/Jenkins/目标环境默认不等待验证
|
|
6
|
+
3) `verify` 模式记录完整闭环:真实提交、已启用的 CI/Jenkins 构建、已启用的目标环境验证结果
|
|
7
|
+
4) CI/Jenkins 失败后再修复的任务,应补充失败原因和修复提交
|
|
8
8
|
5) 这里是默认闭环文档;长 summary 只用于高风险或复盘任务
|
|
9
9
|
|
|
10
10
|
---
|
|
@@ -12,14 +12,14 @@
|
|
|
12
12
|
## <TASK_ID> — <Title> — YYYY-MM-DD HH:MM
|
|
13
13
|
- Task: <TASK_ID>
|
|
14
14
|
- Commit: <commit sha>
|
|
15
|
-
- Jenkins Build: <build url>
|
|
16
|
-
- Target Env: <env name / health url / page path>
|
|
15
|
+
- CI/Jenkins Build: <build url or skipped by verification.jenkins_required=false>
|
|
16
|
+
- Target Env: <env name / health url / page path or skipped by verification.target_env_required=false>
|
|
17
17
|
- Verification: <health / key api / key page / business path>
|
|
18
18
|
- Structure Check: <passed / blocked / skipped with reason>
|
|
19
19
|
- Evidence Log: `docs/tasks/evidence.jsonl`
|
|
20
20
|
- Result: DEV-CLOSED / PASS / FAIL / PARTIAL
|
|
21
21
|
- Follow-up: <none or todo>
|
|
22
|
-
- Jenkins Failure: <optional>
|
|
22
|
+
- CI/Jenkins Failure: <optional>
|
|
23
23
|
- Fix Commit: <optional>
|
|
24
24
|
|
|
25
25
|
---
|
|
@@ -19,11 +19,11 @@
|
|
|
19
19
|
- 兼容性影响:
|
|
20
20
|
|
|
21
21
|
## 3. 质量证据
|
|
22
|
-
- 本地轻量校验:light_gate or quick_test/test/build / api docs / jenkins / diff-check
|
|
22
|
+
- 本地轻量校验:light_gate or quick_test/test/build / api docs / ci/jenkins / diff-check
|
|
23
23
|
- 结构检查:structure-check
|
|
24
24
|
- 结构化证据:`docs/tasks/evidence.jsonl`
|
|
25
25
|
- 门禁画像:`.local/auto-coding-skill/gate-profile.jsonl`
|
|
26
|
-
- Jenkins Build:
|
|
26
|
+
- CI/Jenkins Build:
|
|
27
27
|
- 目标环境验证:
|
|
28
28
|
- 闭环记录:`docs/tasks/closure-log.md`
|
|
29
29
|
|
|
@@ -2,8 +2,8 @@
|
|
|
2
2
|
|
|
3
3
|
规则:
|
|
4
4
|
1) 所有任务都写在本文件(持续续写,不另起零散任务文件)
|
|
5
|
-
2) 普通小改动只要求最小设计记录;跨模块、接口、数据库、部署、Jenkins、关键页面流程变更才补 DD
|
|
6
|
-
3)
|
|
5
|
+
2) 普通小改动只要求最小设计记录;跨模块、接口、数据库、部署、CI/Jenkins、关键页面流程变更才补 DD
|
|
6
|
+
3) 每个任务最终必须有闭环证据:提交、已启用的 CI/Jenkins 状态、已启用的目标环境验证、结果、遗留问题
|
|
7
7
|
4) 长 summary 不是默认强制产物;只有高风险或需要完整复盘时再补
|
|
8
8
|
|
|
9
9
|
---
|
|
@@ -13,8 +13,8 @@
|
|
|
13
13
|
- 范围(In scope):
|
|
14
14
|
- 非目标(Out of scope):
|
|
15
15
|
- 是否高风险(Yes/No):
|
|
16
|
-
- 高风险分类(如有):DB / Auth / Payment / Jenkins / Gateway / Upload / Prod Config
|
|
17
|
-
- 影响面(API / DB / Jenkins / Page / Config / Deploy):
|
|
16
|
+
- 高风险分类(如有):DB / Auth / Payment / CI / Jenkins / Gateway / Upload / Prod Config
|
|
17
|
+
- 影响面(API / DB / CI / Jenkins / Page / Config / Deploy):
|
|
18
18
|
- 分类结果(`ap.py classify --scope auto`:risk / gate / needs):
|
|
19
19
|
- 结构落位(Domain / Application / Infrastructure / Interface / Shared / Tooling / N/A):
|
|
20
20
|
- 复用检查(已有 helper / 组件 / 脚本 / 库):
|
|
@@ -27,8 +27,8 @@
|
|
|
27
27
|
### 默认证据(完成后填写)
|
|
28
28
|
- 项目配置:`docs/ENGINEERING.md`
|
|
29
29
|
- 提交:<commit sha>
|
|
30
|
-
- Jenkins Build:<build url>
|
|
31
|
-
- 目标环境验证:<health/api/page/business path>
|
|
30
|
+
- CI/Jenkins Build:<build url or skipped by verification.jenkins_required=false>
|
|
31
|
+
- 目标环境验证:<health/api/page/business path or skipped by verification.target_env_required=false>
|
|
32
32
|
- 闭环记录:`docs/tasks/closure-log.md`
|
|
33
33
|
|
|
34
34
|
### 按需补充证据(仅在需要时填写)
|