@oscaner-skills/cdd-engine 4.2.0 → 4.4.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 +38 -9
- package/README.zh-CN.md +44 -10
- package/dist/contract/completion-criterion.js +351 -0
- package/dist/contract/declare.js +181 -43
- package/dist/contract/doc.js +84 -271
- package/dist/contract/frontmatter.js +2 -1
- package/dist/contract/home-extractors.js +49 -316
- package/dist/contract/invariants.js +400 -296
- package/dist/contract/judge.js +74 -49
- package/dist/contract/lint.js +3 -2
- package/dist/contract/liveness-signal.js +103 -0
- package/dist/contract/markdown-document.js +410 -0
- package/dist/contract/markdown-tree-types.js +6 -0
- package/dist/contract/markdown-tree.js +137 -0
- package/dist/contract/project.js +1 -1
- package/dist/contract/rules.js +106 -0
- package/dist/contract/selector-engine.js +332 -0
- package/dist/contract/selector-spec.js +74 -0
- package/dist/contract/skill-anatomy.js +29 -1
- package/dist/contract/task-block-grammar.js +285 -0
- package/dist/contract/task-blocks.js +65 -0
- package/dist/contract/translate.js +21 -0
- package/dist/contract/wave-width.js +15 -0
- package/dist/face/board-view.js +382 -172
- package/dist/face/capsule.js +73 -88
- package/dist/face/cli.js +152 -38
- package/dist/face/declare.js +42 -19
- package/dist/face/gate.js +119 -40
- package/dist/face/init.js +84 -25
- package/dist/face/lifecycle.js +540 -123
- package/dist/face/plugins.js +70 -2
- package/dist/face/preview.js +69 -18
- package/dist/face/route-render.js +60 -21
- package/dist/face/termination.js +135 -261
- package/dist/face/words.js +139 -13
- package/dist/infra/atomic.js +15 -0
- package/dist/infra/git.js +25 -0
- package/dist/infra/proc.js +150 -0
- package/dist/infra/round-log.js +104 -0
- package/dist/infra/runtime.js +16 -4
- package/dist/infra/workspace.js +7 -2
- package/dist/render/brief.js +15 -17
- package/dist/render/skeleton.js +41 -28
- package/dist/render/templates.js +128 -84
- package/dist/session/faces.js +47 -20
- package/dist/session/graph.js +13 -37
- package/dist/session/handoff-schema.js +16 -8
- package/dist/session/inflight.js +282 -0
- package/dist/session/ledger.js +603 -145
- package/dist/session/line-identity.js +33 -0
- package/dist/session/next.js +140 -80
- package/dist/session/pipeline.js +247 -0
- package/dist/session/preflight.js +276 -68
- package/dist/session/reviewed-identity.js +54 -0
- package/dist/session/round-naming.js +56 -8
- package/dist/session/run.js +364 -80
- package/dist/session/wave.js +94 -14
- package/package.json +13 -3
package/README.md
CHANGED
|
@@ -2,15 +2,15 @@
|
|
|
2
2
|
|
|
3
3
|
[English](README.md) | [中文](README.zh-CN.md)
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
The `cdd` CLI — the task runner, document and branch reviewer, and harness dispatcher behind the kairos `cdd-dev` skill. Published standalone, so the engine can be installed and driven on its own.
|
|
6
6
|
|
|
7
7
|
## What this package is
|
|
8
8
|
|
|
9
|
-
The engine runs the implement / review / fix
|
|
9
|
+
The engine owns the mechanics a phase cannot be trusted to remember. It runs the implement / review / fix rounds of the CDD workflow against a plan, dispatches each round to the host harness CLI through its embedded harness registry, judges the round's terminal verdict, records it, and derives the next hop from the evidence rather than from the child's exit code. It also reads and writes the `base` artifact and renders the progress board. Consumed by the [kairos plugin](https://www.npmjs.com/package/@oscaner-skills/kairos)'s `cdd-dev` skill, and usable straight from a terminal.
|
|
10
10
|
|
|
11
11
|
## Installation
|
|
12
12
|
|
|
13
|
-
Requires Node.js `>= 24
|
|
13
|
+
Requires Node.js `>= 24` (the CLI runs its TypeScript entry through native type stripping).
|
|
14
14
|
|
|
15
15
|
```bash
|
|
16
16
|
# global CLI (provides the `cdd` binary)
|
|
@@ -22,21 +22,50 @@ npm install @oscaner-skills/cdd-engine
|
|
|
22
22
|
|
|
23
23
|
## CLI
|
|
24
24
|
|
|
25
|
-
Global option: `--dry-run` — preview the next dispatch step and
|
|
25
|
+
Global option: `--dry-run` — preview the next dispatch step and the artifacts it expects, with zero repo writes and no round consumed (implement / review / fix / init).
|
|
26
26
|
|
|
27
27
|
| Subcommand | Usage | Purpose |
|
|
28
28
|
|------------|-------|---------|
|
|
29
29
|
| `implement` | `cdd implement --tasks=<n> [--plan=<path>]` | Run the task implement phase |
|
|
30
|
-
| `review` | `cdd review --type=<
|
|
31
|
-
| `fix` | `cdd fix --type=<
|
|
30
|
+
| `review` | `cdd review --type=<wave\|branch\|phase-spec\|overall\|plan\|single-spec>` | Run a review — wave, branch, phase-spec, overall, plan, or single-spec |
|
|
31
|
+
| `fix` | `cdd fix --type=<wave\|branch\|phase-spec\|overall\|plan\|single-spec>` | Fix review findings — wave, branch, phase-spec, overall, plan, or single-spec |
|
|
32
32
|
| `base` | `cdd base set\|get` | Read/write the `base.json` artifact (single CDD `--plan` target) |
|
|
33
33
|
| `schema` | `cdd schema get <type>` | Print the canonical doc-structure schema (discovery-only, zero enforcement) |
|
|
34
34
|
| `issue` | `cdd issue render` | Render an aggregate issue body from stdin findings (pure rendering, zero enforcement) |
|
|
35
|
-
| `board` | `cdd board --plan <path> / --spec <path>` | Render the entry document's progress board (overall/spec/plan/wave/branch; pure read, zero enforcement) |
|
|
36
|
-
| `init` | `cdd init --harness=<claude\|pi> [--update]` | Install or update the kairos plugin set for a harness (repo-independent, streams inherited) |
|
|
35
|
+
| `board` | `cdd board --plan <path> / --spec <path>` | Render the entry document's progress board (overall/phase-spec/single-spec/plan/wave/branch; pure read, zero enforcement) |
|
|
36
|
+
| `init` | `cdd init --harness=<claude\|pi> [--update] [--include-recommends]` | Install or update the kairos plugin set for a harness (repo-independent, streams inherited) |
|
|
37
37
|
|
|
38
38
|
Use `cdd <command> --help` for a command's full option list (for example `cdd review --tasks` / `--spec` / `--plan` / `--round`).
|
|
39
39
|
|
|
40
|
+
### Review criteria
|
|
41
|
+
|
|
42
|
+
Each review target selects one criteria body:
|
|
43
|
+
|
|
44
|
+
| Target (`--type`) | Criteria body |
|
|
45
|
+
|-------------------|---------------|
|
|
46
|
+
| `wave`, `branch` (the node shapes) | the changed-surface axes — standards, spec, buildability, scope |
|
|
47
|
+
| `phase-spec`, `single-spec` (the spec-shaped documents) | the spec narrative body — URC, the writing-plans self-check, verification evidence, claim pins, program conformance |
|
|
48
|
+
| `plan` (the plan document) | the plan body — URC, spec conformance, verification evidence, claim pins |
|
|
49
|
+
| `overall` (the program charter) | the charter body — see below |
|
|
50
|
+
|
|
51
|
+
A charter is judged by charter criteria only: each phase's scope is a program increment, the Phase inventory and the dependency graph and the execution order agree, every acceptance cell is decidable when its phase closes, the Non-goals fence the program, the change record records decisions rather than work, and the inventory agrees with the tree. A charter review is never asked for implementation evidence — no typecheck or test-command run, no per-claim `path:line` pin. The two spec-shaped document targets share the one narrative body, so nothing is written twice.
|
|
52
|
+
|
|
53
|
+
### Fix dispositions
|
|
54
|
+
|
|
55
|
+
A fix round answers the requesting review handoff finding by finding: one disposition per finding, keyed by the finding's `summary` text verbatim and valued `{ "status": "fixed" | "rejected", "reason"?: "…" }` (`rejected` requires the reason). The map rides the round's own work carrier under `dispositions`. A missing slot, a key set that differs from the input set, a key outside it, an unreadable review handoff, or a `rejected` without a reason fails the round. The review handoff stays read-only apart from appending a ruling line to its `notes`; its `findings` are never rewritten.
|
|
56
|
+
|
|
57
|
+
### Wave width
|
|
58
|
+
|
|
59
|
+
A wave carries at most three tasks (`MAX_TASKS_PER_WAVE`), enforced as a hard gate with two named refusals: `wave-too-wide` when the derived open wave is wider than the ceiling, and `too-many-tasks` when `--tasks` names more than the ceiling. Both name the offending task ids. The engine never splits, truncates or reorders a wave — the repair is the plan's shape: chain the extra tasks through `DependsOn` so the dependency layers narrow. A plan review reports the same shape as `wave-width-at-most-three`, so the defect is visible before the first dispatch. A partially closed batch can widen the derived frontier across two layers; that shape meets the same `wave-too-wide` refusal, never a silent trim.
|
|
60
|
+
|
|
61
|
+
### Round logs
|
|
62
|
+
|
|
63
|
+
Every dispatched round (`implement` / `review` / `fix`) pipes the child's stdout and stderr into one append-only log file per round — `.kairos/cdd/<slug>/logs/<stem>.log` — and never echoes that output on the engine's own face. The name is the round's report stem, so a re-dispatch carries its `-a{attempt}` suffix and never overwrites the first attempt's log. `--dry-run` dispatches nothing, so it writes no log. When the round itself is rejected or cut short, its `CDD_BLOCKED` line on stderr names that round's log path: diagnosing one round is one file away instead of an outside `ps` read. A pre-flight refusal (dirty tree · in-flight · doc contract) names no log — no round was ever dispatched.
|
|
64
|
+
|
|
65
|
+
### Review-cycle soft cap
|
|
66
|
+
|
|
67
|
+
The soft cap is a budget, not a convergence rule: after `REVIEW_CYCLE_CAP` consecutive blocker cycles the engine stops suggesting the next hop and hands that decision to the user (`soft-cap`). Convergence itself is decided by the findings' grades alone — any blocker sends the line back to fix and then to a re-review, warn/nit-only findings are fixed and close without a re-review, and a review with zero findings approves.
|
|
68
|
+
|
|
40
69
|
## Migration
|
|
41
70
|
|
|
42
71
|
Document identity is the front-matter `slug:` key. This retired the file-name-derived identity: a **major breaking** change with **zero dual-read** — the retired keys are simply not read, and the retired entry form is not accepted.
|
|
@@ -55,7 +84,7 @@ pnpm --filter @oscaner-skills/cdd-engine test # run the engine test suite
|
|
|
55
84
|
pnpm --filter @oscaner-skills/cdd-engine build # tsc-emit the published dist/bin.js
|
|
56
85
|
```
|
|
57
86
|
|
|
58
|
-
During repository development the engine is invoked straight on the source entry (`node packages/cdd-engine/src-next/bin.ts`) — never through a global install or link, which can go stale.
|
|
87
|
+
During repository development the engine is invoked straight on the source entry (`node packages/cdd-engine/src-next/bin.ts`) — never through a global install or link, which can go stale. The repository's own conventions (gates, generated files, commit discipline) are in [`AGENTS.md`](../../AGENTS.md).
|
|
59
88
|
|
|
60
89
|
## License
|
|
61
90
|
|
package/README.zh-CN.md
CHANGED
|
@@ -1,18 +1,18 @@
|
|
|
1
1
|
# @oscaner-skills/cdd-engine
|
|
2
2
|
|
|
3
|
-
> 🔗 **Mirror 同步声明**:本文件(`README.zh-CN.md`)是英文源 [README.md](README.md) 的同步中文 **mirror**——顶层章节集合逐条一致,节点按位置一一对应;本文为对外宣讲面的中文口径,语义以英文源为准。**同步时间戳**:2026-
|
|
3
|
+
> 🔗 **Mirror 同步声明**:本文件(`README.zh-CN.md`)是英文源 [README.md](README.md) 的同步中文 **mirror**——顶层章节集合逐条一致,节点按位置一一对应;本文为对外宣讲面的中文口径,语义以英文源为准。**同步时间戳**:2026-11-03。
|
|
4
4
|
|
|
5
5
|
[English](README.md) | [中文](README.zh-CN.md)
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
`cdd` CLI——kairos `cdd-dev` 技能背后的任务运行器、文档与分支评审器、harness 派发器。以独立包发布,使引擎(`cdd`)可单独安装与驱动。
|
|
8
8
|
|
|
9
9
|
## 包定位
|
|
10
10
|
|
|
11
|
-
|
|
11
|
+
引擎掌管的是「一个阶段不该被指望记住」的那些机制:针对计划文件运行 CDD 工作流的 implement / review / fix 轮次,通过内嵌的 harness 注册表把每一轮派发给宿主 harness CLI,裁定该轮的终态判定、把它登记成记录,并依据证据而非子进程退出码推演下一个去向。它还读写 `base` 产物并渲染进度看板。它被 [kairos 插件](https://www.npmjs.com/package/@oscaner-skills/kairos)的 `cdd-dev` 技能消费,也可直接从终端使用。
|
|
12
12
|
|
|
13
13
|
## 安装
|
|
14
14
|
|
|
15
|
-
需要 Node.js `>= 24
|
|
15
|
+
需要 Node.js `>= 24`(CLI 通过原生类型擦除直接运行其 TypeScript 入口)。
|
|
16
16
|
|
|
17
17
|
```bash
|
|
18
18
|
# 全局 CLI(提供 `cdd` 二进制)
|
|
@@ -24,21 +24,55 @@ npm install @oscaner-skills/cdd-engine
|
|
|
24
24
|
|
|
25
25
|
## CLI
|
|
26
26
|
|
|
27
|
-
全局选项:`--dry-run
|
|
27
|
+
全局选项:`--dry-run`——预览下一步派发及其期望的产物,对 repo 零写入、不消耗轮次(implement / review / fix / init)。
|
|
28
28
|
|
|
29
29
|
| 子命令 | 用法 | 用途 |
|
|
30
30
|
|--------|------|------|
|
|
31
31
|
| `implement` | `cdd implement --tasks=<n> [--plan=<path>]` | 运行任务 implement 阶段 |
|
|
32
|
-
| `review` | `cdd review --type=<
|
|
33
|
-
| `fix` | `cdd fix --type=<
|
|
32
|
+
| `review` | `cdd review --type=<wave\|branch\|phase-spec\|overall\|plan\|single-spec>` | 运行评审——wave、branch、phase-spec、overall、plan 或 single-spec |
|
|
33
|
+
| `fix` | `cdd fix --type=<wave\|branch\|phase-spec\|overall\|plan\|single-spec>` | 修复评审发现——wave、branch、phase-spec、overall、plan 或 single-spec |
|
|
34
34
|
| `base` | `cdd base set\|get` | 读写 `base.json` 产物(单一 CDD `--plan` 目标) |
|
|
35
35
|
| `schema` | `cdd schema get <type>` | 打印 canonical 文档结构 schema(发现型、零执法) |
|
|
36
36
|
| `issue` | `cdd issue render` | 依据 stdin 发现渲染聚合 issue 正文(纯渲染、零执法) |
|
|
37
|
-
| `board` | `cdd board --plan <path> / --spec <path>` | 渲染入口文档的进度板(overall/spec/plan/wave/branch;纯读、零执法) |
|
|
38
|
-
| `init` | `cdd init --harness=<claude\|pi> [--update]` | 为指定 harness 安装或更新 kairos 插件集(与 repo 无关,三流继承) |
|
|
37
|
+
| `board` | `cdd board --plan <path> / --spec <path>` | 渲染入口文档的进度板(overall/phase-spec/single-spec/plan/wave/branch;纯读、零执法) |
|
|
38
|
+
| `init` | `cdd init --harness=<claude\|pi> [--update] [--include-recommends]` | 为指定 harness 安装或更新 kairos 插件集(与 repo 无关,三流继承) |
|
|
39
39
|
|
|
40
40
|
用 `cdd <command> --help` 查看某命令的完整选项列表(例如 `cdd review --tasks` / `--spec` / `--plan` / `--round`)。
|
|
41
41
|
|
|
42
|
+
### 评审判据
|
|
43
|
+
|
|
44
|
+
|
|
45
|
+
每个评审目标各选一份判据体:
|
|
46
|
+
|
|
47
|
+
| 目标(`--type`) | 判据体 |
|
|
48
|
+
|------------------|--------|
|
|
49
|
+
| `wave`、`branch`(节点形状) | 变更面四轴——standards、spec、buildability、scope |
|
|
50
|
+
| `phase-spec`、`single-spec`(spec 形状的文档) | spec 叙事判据体——URC、writing-plans 自查、验证证据、逐条 claim pin、程序一致性 |
|
|
51
|
+
| `plan`(计划文档) | 计划判据体——URC、spec 一致性、验证证据、claim pin |
|
|
52
|
+
| `overall`(程序章程) | 章程判据体——见下 |
|
|
53
|
+
|
|
54
|
+
章程只按章程判据判:每个 phase 的 scope 是程序增量 · Phase inventory 与依赖图与执行序三者一致 · 验收格在该相位收口时可判 · 非目标真把程序围住 · 变更记录是决策记录而非工作日志 · 台账与实况一致。章程评审不要求实现面证据——不跑 typecheck、不跑测试命令、不做逐条 `path:line` pin。两种 spec 形状的目标共用同一份叙事判据体,故不存在第二份散文。
|
|
55
|
+
|
|
56
|
+
### fix 的逐条处置
|
|
57
|
+
|
|
58
|
+
|
|
59
|
+
fix 轮逐条回答请求方 review 载体的 finding:每条 finding 一条处置,键为该 finding `summary` 的原文,值为 `{ "status": "fixed" | "rejected", "reason"?: "…" }`(`rejected` 必须带理由)。该映射走本轮 work 载体的 `dispositions` 槽。槽缺失、键集与输入集不等、键不属于输入集、请求方载体不可读、`rejected` 缺理由——任一即判该轮失败。请求方 review 载体除在其 `notes` 追加裁定行外保持只读;其 `findings` 永不改写。
|
|
60
|
+
|
|
61
|
+
### 波内任务上限
|
|
62
|
+
|
|
63
|
+
|
|
64
|
+
一波至多三个任务(`MAX_TASKS_PER_WAVE`),形态是硬门,带两条具名拒绝:派生出的开放波宽于上限即 `wave-too-wide`,`--tasks` 点名多于上限即 `too-many-tasks`;两者都点名越界的任务 id。引擎绝不切块、截断或重排波次——修法在计划的形状:把多出的任务用 `DependsOn` 串成链,依赖层自然变窄。计划评审会把同一形状报成 `wave-width-at-most-three`,故缺陷在首次派发之前就可见。部分闭合的批次可能让派生 frontier 跨两层变宽;该形状吃到同一条 `wave-too-wide` 拒绝,而不是被悄悄裁剪。
|
|
65
|
+
|
|
66
|
+
### 每轮日志
|
|
67
|
+
|
|
68
|
+
|
|
69
|
+
三个派发动词(`implement` / `review` / `fix`)一律把子进程的 stdout 与 stderr 落进该轮自己的 append 日志文件——`.kairos/cdd/<slug>/logs/<stem>.log`——且从不回显到引擎自身的输出面。文件名取该轮的 report stem,故重派带 `-a{attempt}` 后缀,绝不覆盖首次 attempt 的日志。`--dry-run` 不派发,故不落日志。一轮自身被拒或被杀时,stderr 上那条 `CDD_BLOCKED` 行点名该轮的日志路径:诊断一轮只需打开一个文件,而不必从外部读 `ps`。pre-flight 拒绝(dirty tree · in-flight · doc-contract)不点名日志——那一轮根本没派发。
|
|
70
|
+
|
|
71
|
+
### 复审软上限
|
|
72
|
+
|
|
73
|
+
|
|
74
|
+
软上限是预算,不是收敛机制:连续 `REVIEW_CYCLE_CAP` 个 blocker 周期之后,引擎不再建议下一跳,把该决定交给人裁(`soft-cap`)。收敛本身只由 findings 的档位决定——出现任一 blocker 就把线推回 fix 再重审,只有 warn/nit 则修完即收口、不进重审,零 findings 即通过。
|
|
75
|
+
|
|
42
76
|
## 迁移
|
|
43
77
|
|
|
44
78
|
文档身份即 front-matter 的 `slug:` 键。这退役了「按文件名推演文档身份」:属于 **major breaking** 变更,且**零双读**——旧键不再被读取,旧入口形也不再被接受。
|
|
@@ -57,7 +91,7 @@ pnpm --filter @oscaner-skills/cdd-engine test # 运行引擎测试套件
|
|
|
57
91
|
pnpm --filter @oscaner-skills/cdd-engine build # tsc 构建发布产物 dist/bin.js
|
|
58
92
|
```
|
|
59
93
|
|
|
60
|
-
仓库开发期间引擎须从源面直调(`node packages/cdd-engine/src-next/bin.ts
|
|
94
|
+
仓库开发期间引擎须从源面直调(`node packages/cdd-engine/src-next/bin.ts`)——绝不要经全局安装或链接,可能过期。仓库自身的约定(门禁、生成文件、提交纪律)见 [`AGENTS.md`](../../AGENTS.md)。
|
|
61
95
|
|
|
62
96
|
## 许可
|
|
63
97
|
|
|
@@ -0,0 +1,351 @@
|
|
|
1
|
+
// packages/cdd-engine/src-next/contract/completion-criterion.ts
|
|
2
|
+
// P22 T4/T6 — "is this round done?" as criteria behind ONE verb-keyed registry
|
|
3
|
+
// (design spec §8 · the completion-criterion row): `implement` is done when the
|
|
4
|
+
// group's baseline carries at least one commit, `review` (branch review included —
|
|
5
|
+
// branch-review folds to the review op) is done when its carrier is schema-shaped,
|
|
6
|
+
// and `fix` is done when its work carrier's `dispositions` cover every finding of
|
|
7
|
+
// the REQUESTING review carrier (design spec §3.4).
|
|
8
|
+
//
|
|
9
|
+
// The criterion judges a CompletionContext the dispatch side assembles (Task 7):
|
|
10
|
+
// the round's verdict-free identity, its ledger row, the row's in-register records,
|
|
11
|
+
// the persisted carrier bytes, the requester's review path, the git read face and the
|
|
12
|
+
// repoRoot path basis. The two cells with a provider seam (`records`, `reviewsPath`) are
|
|
13
|
+
// filled by `CliLifecycle` — this module pins the context SHAPE only and imports
|
|
14
|
+
// neither `face/` nor the lifecycle.
|
|
15
|
+
//
|
|
16
|
+
// The registry is deliberately PARTIAL while the verbs are ported one at a time: a
|
|
17
|
+
// verb with no criterion throws at lookup (`CompletionCriteria.of`), so a dispatch of
|
|
18
|
+
// an unported verb can never silently read as "done".
|
|
19
|
+
//
|
|
20
|
+
// judge() is async because the implement criterion reads git (`GitClient.commitsSince`).
|
|
21
|
+
//
|
|
22
|
+
// Module-level exports are types / the declared registry / the class — zero
|
|
23
|
+
// behavior-carrying bare functions.
|
|
24
|
+
var _a;
|
|
25
|
+
import { readFileSync } from "node:fs";
|
|
26
|
+
import path from "node:path";
|
|
27
|
+
import { RoundViolation, } from "../session/ledger.js";
|
|
28
|
+
/**
|
|
29
|
+
* CommitsSinceGroupBase — the implement criterion: the round is done when the GROUP
|
|
30
|
+
* has at least one commit since the group's baseline (design spec §8).
|
|
31
|
+
*
|
|
32
|
+
* The baseline is the EARLIEST record's `dispatchBase` of the group — not the round's
|
|
33
|
+
* own. A group re-dispatched after a failed attempt carries a newer per-attempt base,
|
|
34
|
+
* so comparing against the round's own base would read "attempt 1 committed, attempt 2
|
|
35
|
+
* committed nothing" as an empty round (the cross-attempt false negative the group
|
|
36
|
+
* baseline exists to prevent).
|
|
37
|
+
*/
|
|
38
|
+
export class CommitsSinceGroupBase {
|
|
39
|
+
/** The group baseline — the first record (ledger order = cycle/attempt order) that
|
|
40
|
+
* carries a `dispatchBase`. Records without one (legacy folds, a non-git tree) are
|
|
41
|
+
* skipped: they carry no present fact. Null when the group carries none. */
|
|
42
|
+
static groupBaseOf(records) {
|
|
43
|
+
for (const record of records) {
|
|
44
|
+
if (record.dispatchBase !== null)
|
|
45
|
+
return record.dispatchBase;
|
|
46
|
+
}
|
|
47
|
+
return null;
|
|
48
|
+
}
|
|
49
|
+
async judge(ctx) {
|
|
50
|
+
// The round under judgment is APPENDED to the group's recorded history: on a
|
|
51
|
+
// group's FIRST dispatch the ledger holds no record yet (the round is recorded at
|
|
52
|
+
// bookkeep, after this judgment), and the round's own `dispatchBase` IS the group
|
|
53
|
+
// baseline. An earlier record always wins — the group's start, never a retry's.
|
|
54
|
+
const base = CommitsSinceGroupBase.groupBaseOf([...ctx.records, ctx.record]);
|
|
55
|
+
if (base === null) {
|
|
56
|
+
return this.#hard("the round's group carries no dispatch baseline — a completion judgment needs the HEAD the group started from");
|
|
57
|
+
}
|
|
58
|
+
const commits = await ctx.git.commitsSince(ctx.repoRoot, base);
|
|
59
|
+
if (commits.length === 0) {
|
|
60
|
+
return this.#hard(`the group committed nothing since its baseline ${base}`);
|
|
61
|
+
}
|
|
62
|
+
// An implement round is judged by its COMMITS, never by its handoff draft: the
|
|
63
|
+
// absent carrier is a bookkeeping observation (design spec §3.3), so the round
|
|
64
|
+
// still concludes.
|
|
65
|
+
if (ctx.carrier === null) {
|
|
66
|
+
return { fulfilled: true, violation: null, observations: [this.#observation()] };
|
|
67
|
+
}
|
|
68
|
+
return { fulfilled: true, violation: null };
|
|
69
|
+
}
|
|
70
|
+
/** The hard verdict of this criterion — the ledger's existing `contract-violation`
|
|
71
|
+
* cause, never a new violation enum row. */
|
|
72
|
+
#hard(message) {
|
|
73
|
+
return { fulfilled: false, violation: RoundViolation.hard(message) };
|
|
74
|
+
}
|
|
75
|
+
/** The absent-carrier observation — bookkeeping only (the round's commits decided
|
|
76
|
+
* it); the same cause vocabulary, the soft grade. */
|
|
77
|
+
#observation() {
|
|
78
|
+
return RoundViolation.soft(IMPLEMENT_CARRIER_ABSENT);
|
|
79
|
+
}
|
|
80
|
+
}
|
|
81
|
+
/**
|
|
82
|
+
* JudgeCarrier — the review criterion: a review round is done exactly when its
|
|
83
|
+
* carrier is a schema-shaped judge payload — a JSON object whose `findings` is an
|
|
84
|
+
* array. An EMPTY findings array is a valid approval (`findings: []` → APPROVED), so
|
|
85
|
+
* emptiness is never a violation; an absent carrier or a non-array `findings` is.
|
|
86
|
+
*/
|
|
87
|
+
export class JudgeCarrier {
|
|
88
|
+
judge(ctx) {
|
|
89
|
+
const carrier = ctx.carrier;
|
|
90
|
+
if (carrier === null || typeof carrier !== "object" || Array.isArray(carrier)) {
|
|
91
|
+
return Promise.resolve(this.#hard("the review round persisted no judge carrier"));
|
|
92
|
+
}
|
|
93
|
+
const findings = carrier.findings;
|
|
94
|
+
if (!Array.isArray(findings)) {
|
|
95
|
+
return Promise.resolve(this.#hard("the review carrier declares no `findings` array — the judge plane requires it"));
|
|
96
|
+
}
|
|
97
|
+
return Promise.resolve({ fulfilled: true, violation: null });
|
|
98
|
+
}
|
|
99
|
+
/** The hard verdict of this criterion — same cause vocabulary as the ledger's. */
|
|
100
|
+
#hard(message) {
|
|
101
|
+
return { fulfilled: false, violation: RoundViolation.hard(message) };
|
|
102
|
+
}
|
|
103
|
+
}
|
|
104
|
+
/** The implement round's absent-carrier observation (design spec §3.3) — an implement
|
|
105
|
+
* round is judged by its COMMITS, so a round that committed its work but wrote no
|
|
106
|
+
* handoff draft still concludes; the missing carrier is booked, never gated. */
|
|
107
|
+
export const IMPLEMENT_CARRIER_ABSENT = "the implement round wrote no handoff carrier — the round is judged by its commits, not by its draft";
|
|
108
|
+
/** The zero-commit observation of a fix round — a NEW literal (the engine had no
|
|
109
|
+
* reusable zero-commit warning; `commitsSince` fed the crash postmortem alone).
|
|
110
|
+
* The yardstick is THIS round's own `dispatchBase`: the implement criterion asks
|
|
111
|
+
* "did the group produce any work?", this observation asks "did this round leave a
|
|
112
|
+
* commit?" — the group baseline would answer the first question and stay silent
|
|
113
|
+
* forever here (the group's implement round committed, or it never got here).
|
|
114
|
+
* Bookkeeping: a fix round is judged by its carrier, never by its diff. */
|
|
115
|
+
export const FIX_DISPOSITIONS_ZERO_COMMIT = "the fix round committed nothing since its dispatch base — the dispositions judged the round, not the diff";
|
|
116
|
+
/** The empty-input observation — an empty requesting carrier is legal input, so it
|
|
117
|
+
* is reported, never refused. */
|
|
118
|
+
export const FIX_DISPOSITIONS_EMPTY_INPUT = "the requesting review carrier carries no findings — the fix round owes no dispositions";
|
|
119
|
+
/** The legacy-record observation — no requesting carrier is locatable, so the
|
|
120
|
+
* judgment is skipped visibly (reading the gap as an empty input set would restore
|
|
121
|
+
* an always-passing criterion). */
|
|
122
|
+
export const FIX_DISPOSITIONS_UNRECORDED = "the requesting review round records no carrierPath and the route carried no --reviews path — the disposition judgment is skipped";
|
|
123
|
+
/**
|
|
124
|
+
* FixDispositions — the fix criterion: the round is done when its work carrier's
|
|
125
|
+
* `dispositions` cover every finding of the requesting review carrier (design spec
|
|
126
|
+
* §3.4). The input set is the REQUESTING side's carrier — the same-key same-cycle
|
|
127
|
+
* completed review record's `carrierPath`, falling back to the fix route's
|
|
128
|
+
* `--reviews` path; the round's own `carrierPath` is never the input set.
|
|
129
|
+
*
|
|
130
|
+
* Keys are the findings' `summary` strings VERBATIM (no normalization, no
|
|
131
|
+
* fingerprint); repeated summaries collapse to one key (one defect owes one
|
|
132
|
+
* disposition). Values are `{ status: "fixed" | "rejected", reason?: string }` —
|
|
133
|
+
* `rejected` without a reason is a shape violation, hard like the missing slot.
|
|
134
|
+
*
|
|
135
|
+
* The fix round's zero-commit fact is an OBSERVATION, not a refusal: this criterion
|
|
136
|
+
* answers from the carrier, never from the diff.
|
|
137
|
+
*/
|
|
138
|
+
export class FixDispositions {
|
|
139
|
+
/** The requesting carrier's path — the completed review record of the SAME key (the
|
|
140
|
+
* row's records are already the key's) and the SAME cycle as the fix round; a
|
|
141
|
+
* legacy record without `carrierPath` falls back to the route's `--reviews` path. */
|
|
142
|
+
static requesterPathOf(records, cycle, reviewsPath) {
|
|
143
|
+
for (const record of records) {
|
|
144
|
+
if (record.op !== "review" || record.cycle !== cycle)
|
|
145
|
+
continue;
|
|
146
|
+
if (!record.verdict.targetAction)
|
|
147
|
+
continue;
|
|
148
|
+
return record.carrierPath ?? reviewsPath;
|
|
149
|
+
}
|
|
150
|
+
return reviewsPath;
|
|
151
|
+
}
|
|
152
|
+
/** Read the requesting carrier's input set (the summaries, deduped in order). The
|
|
153
|
+
* read is synchronous on purpose: the input is ONE small carrier, and the dispatch
|
|
154
|
+
* face already reads its small inputs synchronously at the same seam.
|
|
155
|
+
*
|
|
156
|
+
* Every path resolves against `repoRoot`, never `process.cwd()`: the engine runs
|
|
157
|
+
* from a subdirectory too, `--reviews` arrives repoRoot-relative and a record's
|
|
158
|
+
* `carrierPath` arrives absolute — both must land on the one basis (`RepoRoot`'s
|
|
159
|
+
* rule). The reported `path` is the resolved one, so a failure names a real file. */
|
|
160
|
+
static requesterInputOf(records, cycle, reviewsPath, repoRoot) {
|
|
161
|
+
const declared = _a.requesterPathOf(records, cycle, reviewsPath);
|
|
162
|
+
if (declared === null)
|
|
163
|
+
return { kind: "unrecorded" };
|
|
164
|
+
const target = path.resolve(repoRoot, declared);
|
|
165
|
+
let carrier;
|
|
166
|
+
try {
|
|
167
|
+
carrier = JSON.parse(readFileSync(target, "utf8"));
|
|
168
|
+
}
|
|
169
|
+
catch {
|
|
170
|
+
return { kind: "unreadable", path: target, detail: "the file is absent or not JSON" };
|
|
171
|
+
}
|
|
172
|
+
const findings = carrier?.findings;
|
|
173
|
+
if (!Array.isArray(findings)) {
|
|
174
|
+
return {
|
|
175
|
+
kind: "unreadable",
|
|
176
|
+
path: target,
|
|
177
|
+
detail: "the carrier declares no `findings` array",
|
|
178
|
+
};
|
|
179
|
+
}
|
|
180
|
+
const set = _a.#summariesOf(findings);
|
|
181
|
+
if ("index" in set) {
|
|
182
|
+
return {
|
|
183
|
+
kind: "unreadable",
|
|
184
|
+
path: target,
|
|
185
|
+
detail: `finding #${set.index} carries no string \`summary\``,
|
|
186
|
+
};
|
|
187
|
+
}
|
|
188
|
+
return { kind: "read", path: target, summaries: set.summaries };
|
|
189
|
+
}
|
|
190
|
+
/** The carrier's `dispositions` map — null when the slot is absent or not an
|
|
191
|
+
* object (the criterion's own shape refusal; the schema only pins the slot type). */
|
|
192
|
+
static dispositionsOf(carrier) {
|
|
193
|
+
if (carrier === null || typeof carrier !== "object" || Array.isArray(carrier))
|
|
194
|
+
return null;
|
|
195
|
+
const dispositions = carrier.dispositions;
|
|
196
|
+
if (dispositions === null || typeof dispositions !== "object" || Array.isArray(dispositions))
|
|
197
|
+
return null;
|
|
198
|
+
return dispositions;
|
|
199
|
+
}
|
|
200
|
+
async judge(ctx) {
|
|
201
|
+
const own = this.#ownRefusal(ctx);
|
|
202
|
+
if (own !== null)
|
|
203
|
+
return own;
|
|
204
|
+
const requester = _a.requesterInputOf(ctx.records, ctx.record.cycle, ctx.reviewsPath, ctx.repoRoot);
|
|
205
|
+
if (requester.kind === "unrecorded")
|
|
206
|
+
return this.#complete([this.#soft(FIX_DISPOSITIONS_UNRECORDED)]);
|
|
207
|
+
if (requester.kind === "unreadable") {
|
|
208
|
+
return this.#hard(`the requesting review carrier is missing or unreadable at ${requester.path} — ${requester.detail}`);
|
|
209
|
+
}
|
|
210
|
+
const dispositions = _a.dispositionsOf(ctx.carrier) ?? {};
|
|
211
|
+
const refusal = _a.#keyRefusal(dispositions, requester.summaries);
|
|
212
|
+
if (refusal !== null)
|
|
213
|
+
return this.#hard(refusal);
|
|
214
|
+
const shape = _a.#valueRefusal(dispositions);
|
|
215
|
+
if (shape !== null)
|
|
216
|
+
return this.#hard(shape);
|
|
217
|
+
return this.#complete(await this.#observationsOf(ctx, requester.summaries));
|
|
218
|
+
}
|
|
219
|
+
/** The round's two summary counts — `fixed` / `rejected`, counted over the SAME
|
|
220
|
+
* pair the judgment reads (dispositions ∩ the input set). Counts only: the
|
|
221
|
+
* `fixed N · rejected M` line is rendered by the presentation plane
|
|
222
|
+
* (`face/words.ts` template). A face fact: never stored, never a capsule key,
|
|
223
|
+
* never a second read face. */
|
|
224
|
+
summaryOf(carrier, input) {
|
|
225
|
+
const wanted = new Set(input);
|
|
226
|
+
let fixed = 0;
|
|
227
|
+
let rejected = 0;
|
|
228
|
+
for (const [summary, value] of Object.entries(_a.dispositionsOf(carrier) ?? {})) {
|
|
229
|
+
if (!wanted.has(summary))
|
|
230
|
+
continue;
|
|
231
|
+
const status = value?.status;
|
|
232
|
+
if (status === "fixed")
|
|
233
|
+
fixed += 1;
|
|
234
|
+
else if (status === "rejected")
|
|
235
|
+
rejected += 1;
|
|
236
|
+
}
|
|
237
|
+
return { fixed, rejected };
|
|
238
|
+
}
|
|
239
|
+
/** The round's own carrier refusals (① missing carrier, ② missing slot). */
|
|
240
|
+
#ownRefusal(ctx) {
|
|
241
|
+
const carrier = ctx.carrier;
|
|
242
|
+
if (carrier === null || typeof carrier !== "object" || Array.isArray(carrier)) {
|
|
243
|
+
const at = ctx.record.carrierPath;
|
|
244
|
+
return this.#hard(at === null
|
|
245
|
+
? "the fix round persisted no work carrier and recorded no carrier path"
|
|
246
|
+
: `the fix round persisted no work carrier at ${at}`);
|
|
247
|
+
}
|
|
248
|
+
if (_a.dispositionsOf(carrier) === null) {
|
|
249
|
+
return this.#hard("the fix carrier declares no `dispositions` object — every requesting finding owes a fixed/rejected row");
|
|
250
|
+
}
|
|
251
|
+
return null;
|
|
252
|
+
}
|
|
253
|
+
/** The key-set refusals (③ missing entries, ④ unknown entries) — exact matching,
|
|
254
|
+
* one defect one disposition. */
|
|
255
|
+
static #keyRefusal(dispositions, input) {
|
|
256
|
+
const wanted = new Set(input);
|
|
257
|
+
const unknown = Object.keys(dispositions).filter((key) => !wanted.has(key));
|
|
258
|
+
if (unknown.length > 0) {
|
|
259
|
+
return `disposition(s) for finding(s) the requesting carrier never raised: ${unknown.join(", ")}`;
|
|
260
|
+
}
|
|
261
|
+
const missing = input.filter((summary) => !Object.hasOwn(dispositions, summary));
|
|
262
|
+
if (missing.length > 0) {
|
|
263
|
+
return `no disposition for finding(s) of the requesting carrier: ${missing.join(", ")}`;
|
|
264
|
+
}
|
|
265
|
+
return null;
|
|
266
|
+
}
|
|
267
|
+
/** The value-shape refusal (⑥ `rejected` without a reason; a status outside the
|
|
268
|
+
* two declared words is the same shape family). */
|
|
269
|
+
static #valueRefusal(dispositions) {
|
|
270
|
+
for (const [summary, value] of Object.entries(dispositions)) {
|
|
271
|
+
const status = value?.status;
|
|
272
|
+
if (status !== "fixed" && status !== "rejected") {
|
|
273
|
+
return `disposition "${summary}" declares status ${JSON.stringify(status)} — use \`fixed\` or \`rejected\``;
|
|
274
|
+
}
|
|
275
|
+
const reason = value?.reason;
|
|
276
|
+
if (status === "rejected" && (typeof reason !== "string" || reason.trim().length === 0)) {
|
|
277
|
+
return `disposition "${summary}" is rejected without a reason — a rejection must state why`;
|
|
278
|
+
}
|
|
279
|
+
}
|
|
280
|
+
return null;
|
|
281
|
+
}
|
|
282
|
+
/** The two soft observations of a completed fix round — the empty input set and the
|
|
283
|
+
* zero-commit round (both bookkeeping, neither a gate). */
|
|
284
|
+
async #observationsOf(ctx, input) {
|
|
285
|
+
const observations = [];
|
|
286
|
+
if (input.length === 0)
|
|
287
|
+
observations.push(this.#soft(FIX_DISPOSITIONS_EMPTY_INPUT));
|
|
288
|
+
// THIS round's own baseline — a null one (legacy fold, non-git tree) carries no
|
|
289
|
+
// present fact, so the observation is simply unmeasurable, never invented.
|
|
290
|
+
const base = ctx.record.dispatchBase;
|
|
291
|
+
if (base !== null) {
|
|
292
|
+
const commits = await ctx.git.commitsSince(ctx.repoRoot, base);
|
|
293
|
+
if (commits.length === 0)
|
|
294
|
+
observations.push(this.#soft(FIX_DISPOSITIONS_ZERO_COMMIT));
|
|
295
|
+
}
|
|
296
|
+
return observations;
|
|
297
|
+
}
|
|
298
|
+
/** The deduped input set — repeated summaries collapse to one key. A finding
|
|
299
|
+
* without a string `summary` is NOT skipped (a silently dropped finding owes no
|
|
300
|
+
* disposition and passes forever): the caller grades it `unreadable`.
|
|
301
|
+
* `index` is the first offending entry. */
|
|
302
|
+
static #summariesOf(findings) {
|
|
303
|
+
const summaries = [];
|
|
304
|
+
const seen = new Set();
|
|
305
|
+
for (const [index, finding] of findings.entries()) {
|
|
306
|
+
const summary = finding?.summary;
|
|
307
|
+
if (typeof summary !== "string")
|
|
308
|
+
return { index };
|
|
309
|
+
if (seen.has(summary))
|
|
310
|
+
continue;
|
|
311
|
+
seen.add(summary);
|
|
312
|
+
summaries.push(summary);
|
|
313
|
+
}
|
|
314
|
+
return { summaries };
|
|
315
|
+
}
|
|
316
|
+
#complete(observations) {
|
|
317
|
+
return { fulfilled: true, violation: null, observations };
|
|
318
|
+
}
|
|
319
|
+
/** The hard verdict of this criterion — the ledger's existing `contract-violation`
|
|
320
|
+
* cause, never a new violation enum row. */
|
|
321
|
+
#hard(message) {
|
|
322
|
+
return { fulfilled: false, violation: RoundViolation.hard(message) };
|
|
323
|
+
}
|
|
324
|
+
/** The soft row — bookkeeping only; `contract-violation` is the only cause
|
|
325
|
+
* vocabulary the ledger carries today. */
|
|
326
|
+
#soft(message) {
|
|
327
|
+
return RoundViolation.soft(message);
|
|
328
|
+
}
|
|
329
|
+
}
|
|
330
|
+
_a = FixDispositions;
|
|
331
|
+
/** The verb-keyed criterion registry — one criterion per op verb. A verb is
|
|
332
|
+
* registered when its criterion lands (branch review folds to `review`, so it needs
|
|
333
|
+
* no own row); an UNREGISTERED verb still throws at lookup, so a future verb can
|
|
334
|
+
* never silently read as done. */
|
|
335
|
+
export const COMPLETION_CRITERIA = {
|
|
336
|
+
implement: new CommitsSinceGroupBase(),
|
|
337
|
+
review: new JudgeCarrier(),
|
|
338
|
+
fix: new FixDispositions(),
|
|
339
|
+
};
|
|
340
|
+
/** The registry's lookup face — an unregistered verb throws at lookup, so a dispatch
|
|
341
|
+
* of an unported verb can never fall through to an invented "done". */
|
|
342
|
+
// biome-ignore lint/complexity/noStaticOnlyClass: the lookup single point — the registry's derivation surface, never a second free-floating predicate.
|
|
343
|
+
export class CompletionCriteria {
|
|
344
|
+
static of(op) {
|
|
345
|
+
const criterion = COMPLETION_CRITERIA[op];
|
|
346
|
+
if (criterion === undefined) {
|
|
347
|
+
throw new Error(`no completion criterion is registered for the "${op}" verb`);
|
|
348
|
+
}
|
|
349
|
+
return criterion;
|
|
350
|
+
}
|
|
351
|
+
}
|