@oscaner-skills/cdd-engine 4.12.0 → 4.14.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 +22 -0
- package/README.zh-CN.md +22 -0
- package/dist/contract/census.js +134 -0
- package/dist/contract/invariants.js +11 -6
- package/dist/contract/pins.js +893 -0
- package/dist/contract/review-criteria.js +332 -0
- package/dist/face/artifacts.js +13 -4
- package/dist/face/board-view.js +414 -71
- package/dist/face/capsule.js +7 -5
- package/dist/face/cli.js +192 -63
- package/dist/face/declare.js +10 -6
- package/dist/face/lifecycle.js +303 -114
- package/dist/face/preview.js +9 -0
- package/dist/face/route-render.js +23 -7
- package/dist/face/words.js +53 -7
- package/dist/infra/carrier-seal.js +47 -24
- package/dist/infra/plan-source.js +180 -78
- package/dist/infra/slug-index.js +58 -27
- package/dist/infra/workspace.js +19 -1
- package/dist/render/templates.js +84 -16
- package/dist/session/artifact-reads.js +108 -0
- package/dist/session/carrier-rulings.js +98 -45
- package/dist/session/dispatch-authority.js +2 -3
- package/dist/session/handoff-schema.js +137 -5
- package/dist/session/inflight.js +5 -2
- package/dist/session/ledger.js +178 -248
- package/dist/session/next.js +62 -15
- package/dist/session/round-artifacts.js +645 -0
- package/dist/session/round-naming.js +16 -81
- package/dist/session/run.js +19 -16
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -74,6 +74,28 @@ Document identity is the front-matter `slug:` key. This retired the file-name-de
|
|
|
74
74
|
- **Identity is declared, not derived.** A document is keyed by the `slug:` its front matter carries — the file name carries no identity meaning at all. The retired path keys are no longer read (leaving one in place is inert, not an error); a plan's program chain resolves through the identity document sharing its `slug:` — a phase-spec's `program:` names its overall, while an overall or single-spec is its own chain root.
|
|
75
75
|
- **Per-run workspaces follow the key.** The `.kairos/cdd/<slug>/` directory is keyed by the plan document's `slug:`. A directory left under a retired file-name-derived key is **not reused** by any run — no run resumes or migrates it. A reporting session's ledger scan still reads its records, so delete it by hand once you no longer need that history.
|
|
76
76
|
|
|
77
|
+
### Rulings sidecars written before this release
|
|
78
|
+
|
|
79
|
+
A fix dispatch reads the orchestrator's rulings from one sidecar whose name carries the reviewed round's cycle: `<line>-<op>-<n>.c<N>.rulings.json`, in the directory of the review carrier it answers. A sidecar written under the retired spelling — `<line>-<op>-<n>.rulings.json` — sits off that path, so the first dispatch after upgrading stops with `CDD_BLOCKED: artifact-identity` and prints both paths. The engine never moves and never rewrites an artifact, so the rename is a one-time action you run by hand:
|
|
80
|
+
|
|
81
|
+
```sh
|
|
82
|
+
# For every <line>-<op>-<n>.rulings.json whose directory also holds the final carrier
|
|
83
|
+
# <line>-<op>-<n>.c<N>.json, rename it to <line>-<op>-<n>.c<N>.rulings.json.
|
|
84
|
+
for side in .kairos/cdd/*/*.rulings.json; do
|
|
85
|
+
[ -e "$side" ] || continue
|
|
86
|
+
stem=${side%.rulings.json}
|
|
87
|
+
case "$stem" in *.c[0-9]*) continue ;; esac # already names its reviewed cycle
|
|
88
|
+
for final in "$stem".c[0-9]*.json; do
|
|
89
|
+
case "$final" in *.rulings.json) continue ;; esac
|
|
90
|
+
[ -e "$final" ] || continue
|
|
91
|
+
mv -n "$side" "${final%.json}.rulings.json" # -n: never clobber an already-renamed sidecar
|
|
92
|
+
break
|
|
93
|
+
done
|
|
94
|
+
done
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
**Re-judge after the rename.** Run the same dispatch with `--dry-run` and compare what it reads back with the sidecar: a mismatch that survives the rename means the entries deviate beyond the name, and the orchestrator repairs the content — the engine only refuses.
|
|
98
|
+
|
|
77
99
|
## Development
|
|
78
100
|
|
|
79
101
|
The package lives in the [Oscaner/skills](https://github.com/Oscaner/skills) monorepo at `packages/cdd-engine` (TypeScript, emitted with `tsc -p tsconfig.build.json`, tested with vitest; tests are colocated at `src-next/**/__tests__/**/*.test.ts`).
|
package/README.zh-CN.md
CHANGED
|
@@ -81,6 +81,28 @@ fix 轮逐条回答请求方 review 载体的 finding:每条 finding 一条处
|
|
|
81
81
|
- **身份是声明出来的,不是推演出来的**:文档由 front-matter 所写的 `slug:` 定位,文件名不承载任何身份含义。旧路径键不再被读取(留着是惰性的,不报错);plan 的程序链经「与它同 slug 的身份文档」解析——phase-spec 的 `program:` 指向其 overall,而 overall / single-spec 自身即链根。
|
|
82
82
|
- **按 run 的工作区随键走**:`.kairos/cdd/<slug>/` 目录以 plan 文档的 `slug:` 为键。遗留在旧键命名下的目录**不复用**——没有 run 会续用或迁移它。但报告会话的台账扫描仍会读其记录,故在不再需要那段历史时手动删除。
|
|
83
83
|
|
|
84
|
+
### 旧拼写的裁定 sidecar
|
|
85
|
+
|
|
86
|
+
fix 派发只从一个 sidecar 读编排者的裁定,其名字携带被评审那一轮的 cycle:`<line>-<op>-<n>.c<N>.rulings.json`,与被它回答的 review 载体同目录。按退役拼写写下的 sidecar——`<line>-<op>-<n>.rulings.json`——落在该路径之外,升级后的首次派发会以 `CDD_BLOCKED: artifact-identity` 停下,并同时印出两条路径。引擎从不移动、也不改写产物,故改名是你手工执行的一次性动作:
|
|
87
|
+
|
|
88
|
+
```sh
|
|
89
|
+
# 对每个 <line>-<op>-<n>.rulings.json,若同目录存在终稿载体 <line>-<op>-<n>.c<N>.json,
|
|
90
|
+
# 改名为 <line>-<op>-<n>.c<N>.rulings.json。
|
|
91
|
+
for side in .kairos/cdd/*/*.rulings.json; do
|
|
92
|
+
[ -e "$side" ] || continue
|
|
93
|
+
stem=${side%.rulings.json}
|
|
94
|
+
case "$stem" in *.c[0-9]*) continue ;; esac # already names its reviewed cycle
|
|
95
|
+
for final in "$stem".c[0-9]*.json; do
|
|
96
|
+
case "$final" in *.rulings.json) continue ;; esac
|
|
97
|
+
[ -e "$final" ] || continue
|
|
98
|
+
mv -n "$side" "${final%.json}.rulings.json" # -n: never clobber an already-renamed sidecar
|
|
99
|
+
break
|
|
100
|
+
done
|
|
101
|
+
done
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
**改名后必须复判。** 用 `--dry-run` 跑同一条派发,把它读回的内容与 sidecar 比对:改名后仍然不一致,说明条目除名字之外还有偏差——内容归编排器修,引擎只拒不改。
|
|
105
|
+
|
|
84
106
|
## 开发说明
|
|
85
107
|
|
|
86
108
|
包位于 [Oscaner/skills](https://github.com/Oscaner/skills) monorepo 的 `packages/cdd-engine`(TypeScript,`tsc -p tsconfig.build.json` 发布构建,vitest 测试;测试与源码同地放置于 `src-next/**/__tests__/**/*.test.ts`)。
|
|
@@ -0,0 +1,134 @@
|
|
|
1
|
+
// packages/cdd-engine/src-next/contract/census.ts
|
|
2
|
+
// P37 T8 — the census execution face (design spec §8). A count claim is allowed in a
|
|
3
|
+
// document, but a MEASURED number must carry a `census:<id>` reference, and this module
|
|
4
|
+
// is what makes that reference checkable: the registry supplies one number per row, and
|
|
5
|
+
// the gate compares the number a `census:<id> = <n>` reference declares with the row's
|
|
6
|
+
// export.
|
|
7
|
+
//
|
|
8
|
+
// ONE ROW, ONE NUMBER (§8.2). `measure(): number` is deliberately not a record: the gate
|
|
9
|
+
// compares the single `<n>` the reference writes, so a row measuring a record would leave
|
|
10
|
+
// that comparison without a meaning — which is why the type, not a runtime check, refuses
|
|
11
|
+
// it. A measurement surface that exposes several numbers registers several rows; the id is
|
|
12
|
+
// the key, and there is no sub-key syntax.
|
|
13
|
+
//
|
|
14
|
+
// The registry is NOT a module singleton and must not become one: the four `pin.*` rows
|
|
15
|
+
// measure a corpus, so the table is built at the composition point that already resolved a
|
|
16
|
+
// root (`face/cli.ts#rootOf()` if a command ever reads it; the guard test here), handing
|
|
17
|
+
// the SAME `PinAudit` and the SAME `corpusOf(root)` the scan uses. The corpus declaration
|
|
18
|
+
// therefore still lives in exactly one module, and no module-scope file-system read rides
|
|
19
|
+
// the import graph of every `cdd` command.
|
|
20
|
+
//
|
|
21
|
+
// The gate judges ONE thing (§8.3): does each `<n>` a reference declares equal its row's
|
|
22
|
+
// export. `<n>` is read only from the right-hand side of the fixed form; unequal is red,
|
|
23
|
+
// and an unknown id throws (the same "unregistered lookup throws" shape the criteria and
|
|
24
|
+
// completion-criterion registries use). The reference GRAMMAR is half of the judgment
|
|
25
|
+
// (§8.3): only `census:<id> = <n>` whose id is dotted lowercase and whose `<n>` is a
|
|
26
|
+
// decimal integer is a reference at all. A `census:` word that fails that grammar is prose
|
|
27
|
+
// about the form — the placeholder `census:<id> = <n>` sits inside this very corpus — so it
|
|
28
|
+
// is neither parsed nor compared nor thrown on. That is a grammar, not a filter: a
|
|
29
|
+
// well-formed but unregistered id still throws, so §8.3's floor cannot be weakened by
|
|
30
|
+
// skipping everything that carries a metacharacter.
|
|
31
|
+
//
|
|
32
|
+
// Module-level exports are types / one declared grammar / the factory / the classes — zero
|
|
33
|
+
// behavior-carrying bare functions.
|
|
34
|
+
import { CRITERIA_ROWS, LENS_QUESTION_ROWS } from "./review-criteria.js";
|
|
35
|
+
/** The reference grammar (§8.3) — a dotted lowercase id and a decimal integer on the
|
|
36
|
+
* right of the fixed `=` form. A `census:` word outside it is prose about the form.
|
|
37
|
+
* The value's terminator says the whole number must be digits: guarding only the next
|
|
38
|
+
* digit would truncate `3.5` to `3` and judge a form (§8.3's `^\d+$`) the grammar puts
|
|
39
|
+
* outside the gate — a false red for `3.5`, a false green for `0.5`. */
|
|
40
|
+
const REFERENCE = /census:(?<id>[a-z][a-z0-9]*(?:\.[a-z][a-z0-9]*)+)\s*=\s*(?<n>\d+)(?![0-9A-Za-z.])/g;
|
|
41
|
+
/** The census registry — `of(id)` throws for a row nobody registered. */
|
|
42
|
+
export class CensusTable {
|
|
43
|
+
#rows;
|
|
44
|
+
constructor(rows) {
|
|
45
|
+
const byId = new Map();
|
|
46
|
+
for (const row of rows) {
|
|
47
|
+
if (byId.has(row.id))
|
|
48
|
+
throw new Error(`census row \`${row.id}\` is registered twice`);
|
|
49
|
+
byId.set(row.id, row);
|
|
50
|
+
}
|
|
51
|
+
this.#rows = byId;
|
|
52
|
+
}
|
|
53
|
+
/** The registered rows, in declaration order. */
|
|
54
|
+
rows() {
|
|
55
|
+
return [...this.#rows.values()];
|
|
56
|
+
}
|
|
57
|
+
/** The one row registered under `id`; an unregistered id throws (§8.2). */
|
|
58
|
+
of(id) {
|
|
59
|
+
const row = this.#rows.get(id);
|
|
60
|
+
if (row === undefined)
|
|
61
|
+
throw new Error(`no census row is registered for \`${id}\``);
|
|
62
|
+
return row;
|
|
63
|
+
}
|
|
64
|
+
}
|
|
65
|
+
/** Build the declared table at the composition point (§8.2): the four pin readings come
|
|
66
|
+
* off ONE `PinAudit.census(corpus)` call, so the four rows are readings of one scan
|
|
67
|
+
* rather than four computations, and the three registry rows read the shipped tables
|
|
68
|
+
* directly instead of copying their length into a literal. */
|
|
69
|
+
export const censusTableOf = (deps) => {
|
|
70
|
+
const pins = deps.audit.census(deps.corpus);
|
|
71
|
+
const cells = LENS_QUESTION_ROWS.reduce((sum, row) => sum + row.reviewKinds.length, 0);
|
|
72
|
+
return new CensusTable([
|
|
73
|
+
{ id: "pin.symbol", measure: () => pins.symbol },
|
|
74
|
+
{ id: "pin.path", measure: () => pins.path },
|
|
75
|
+
{ id: "pin.total", measure: () => pins.total },
|
|
76
|
+
{ id: "pin.files", measure: () => pins.files },
|
|
77
|
+
{ id: "criteria.rows", measure: () => CRITERIA_ROWS.length },
|
|
78
|
+
{ id: "questions.rows", measure: () => LENS_QUESTION_ROWS.length },
|
|
79
|
+
{ id: "questions.cells", measure: () => cells },
|
|
80
|
+
]);
|
|
81
|
+
};
|
|
82
|
+
/** The gate (§8.3) — it compares what the corpus declares with what the registry
|
|
83
|
+
* measures, and it judges nothing else: no prose semantics, no "does this number look
|
|
84
|
+
* reasonable", no undeclared counts. */
|
|
85
|
+
export class CensusGate {
|
|
86
|
+
#table;
|
|
87
|
+
#audit;
|
|
88
|
+
#corpus;
|
|
89
|
+
constructor(deps) {
|
|
90
|
+
this.#table = deps.table;
|
|
91
|
+
this.#audit = deps.audit;
|
|
92
|
+
this.#corpus = deps.corpus;
|
|
93
|
+
}
|
|
94
|
+
/** Every reference one text writes, in document order — the grammar, nothing else.
|
|
95
|
+
* A `census:` word that fails the grammar is prose about the form. */
|
|
96
|
+
static referencesOf(text, source) {
|
|
97
|
+
const references = [];
|
|
98
|
+
text.split("\n").forEach((line, index) => {
|
|
99
|
+
for (const match of line.matchAll(REFERENCE)) {
|
|
100
|
+
const id = match.groups?.id;
|
|
101
|
+
const declared = match.groups?.n;
|
|
102
|
+
if (id === undefined || declared === undefined)
|
|
103
|
+
continue;
|
|
104
|
+
references.push({
|
|
105
|
+
id,
|
|
106
|
+
declared: Number(declared),
|
|
107
|
+
source,
|
|
108
|
+
line: index + 1,
|
|
109
|
+
text: match[0],
|
|
110
|
+
});
|
|
111
|
+
}
|
|
112
|
+
});
|
|
113
|
+
return references;
|
|
114
|
+
}
|
|
115
|
+
/** Judge the whole corpus: every reference is resolved through the registry (an
|
|
116
|
+
* unregistered id throws) and its declared number is compared with the export. */
|
|
117
|
+
report() {
|
|
118
|
+
const mismatches = [];
|
|
119
|
+
let compared = 0;
|
|
120
|
+
for (const file of this.#audit.filesOf(this.#corpus)) {
|
|
121
|
+
const text = this.#audit.textOf(file);
|
|
122
|
+
if (text === null)
|
|
123
|
+
continue;
|
|
124
|
+
for (const reference of CensusGate.referencesOf(text, file)) {
|
|
125
|
+
const measured = this.#table.of(reference.id).measure();
|
|
126
|
+
compared += 1;
|
|
127
|
+
if (measured === reference.declared)
|
|
128
|
+
continue;
|
|
129
|
+
mismatches.push({ ...reference, measured });
|
|
130
|
+
}
|
|
131
|
+
}
|
|
132
|
+
return { compared, mismatches };
|
|
133
|
+
}
|
|
134
|
+
}
|
|
@@ -1218,7 +1218,17 @@ export class CrossDocChainInvariant extends Invariant {
|
|
|
1218
1218
|
// A placeholder or missing slug is presence's surface, never this arm's.
|
|
1219
1219
|
if (slug === null || this.isPlaceholder(slug))
|
|
1220
1220
|
return [];
|
|
1221
|
-
|
|
1221
|
+
const index = this.indexOf(ctx);
|
|
1222
|
+
// An identity question, never a first pick: n ≥ 1 is an identity (two of them are
|
|
1223
|
+
// `duplicate-identity`'s judgment), so the chain never claims "no identity document"
|
|
1224
|
+
// over an ambiguous set.
|
|
1225
|
+
if (index.hasIdentity(slug))
|
|
1226
|
+
return [];
|
|
1227
|
+
// The SAME discarded-candidate counts the plan read's tri-state reads (§2.7): a doc
|
|
1228
|
+
// root that dropped a candidate, or indexed one without a registered doc type,
|
|
1229
|
+
// cannot answer an absence — the index's silence is not the disk's. This is the
|
|
1230
|
+
// undecided arm, and it produces ZERO findings (zero refusal, like §2.7 (c)).
|
|
1231
|
+
if (!index.docRootsClean())
|
|
1222
1232
|
return [];
|
|
1223
1233
|
return [
|
|
1224
1234
|
this.finding(ctx, "slug", `the plan carries no identity document with the same slug: ${slug}`, `add a spec document declaring slug: ${slug} (its doc-type is overall / phase-spec / single-spec)`),
|
|
@@ -1249,11 +1259,6 @@ export class CrossDocChainInvariant extends Invariant {
|
|
|
1249
1259
|
}
|
|
1250
1260
|
return findings;
|
|
1251
1261
|
}
|
|
1252
|
-
/** The identity document carrying the slug, or null — resolved through the one
|
|
1253
|
-
* identity index the board and the pre-flight read (zero second scan). */
|
|
1254
|
-
#identityDocOf(ctx, slug) {
|
|
1255
|
-
return this.indexOf(ctx).identityDoc(slug);
|
|
1256
|
-
}
|
|
1257
1262
|
/** The overall document carrying the program slug, or null. */
|
|
1258
1263
|
#overallOf(ctx, slug) {
|
|
1259
1264
|
return this.indexOf(ctx).overallOf(slug);
|