@oscaner-skills/cdd-engine 4.11.0 → 4.13.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 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`)。
@@ -83,6 +83,30 @@ export class MarkdownPrimitives {
83
83
  // ---------------------------------------------------------------------------
84
84
  // the DocType base — parse + projection consumption + chain root
85
85
  // ---------------------------------------------------------------------------
86
+ /**
87
+ * The document-syntax rejection — a structural break of a document's OWN grammar
88
+ * (a reserved task section declared twice today), thrown by the parse face and
89
+ * materialized as a `Finding` by the judgment face. It carries the three faces a
90
+ * finding needs (the anchored field, the one-line message and the actionable
91
+ * fix), so the consumer never re-derives them from a message string. It sits
92
+ * beside the `DocType` base because the parse face is its only thrower: a
93
+ * doc-type's grammar break is a value, never a bare `Error`.
94
+ */
95
+ export class DocSyntaxError extends Error {
96
+ /** The anchored field the break sits on (an anchor token or a section name). */
97
+ field;
98
+ /** The one-line finding message — what is structurally wrong. */
99
+ message;
100
+ /** The actionable fix. */
101
+ fix;
102
+ constructor(field, message, fix) {
103
+ super(message);
104
+ this.name = "DocSyntaxError";
105
+ this.field = field;
106
+ this.message = message;
107
+ this.fix = fix;
108
+ }
109
+ }
86
110
  /**
87
111
  * The abstract doc-type base. Each subclass binds its registry-derived projection
88
112
  * face (slices + shape) and implements parse — pure structural extraction into a
@@ -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
- if (this.#identityDocOf(ctx, slug) !== null)
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);
@@ -7,9 +7,10 @@
7
7
  // index over the declared strategy set — zero switch-case, zero hand-written
8
8
  // judgment branches in this module (the plan's coordinator semantics: the
9
9
  // polymorphic strategy family judges, the coordinator assembles).
10
+ var _a;
10
11
  import { Words } from "../face/words.js";
11
12
  import { declaredRegistries } from "./declare.js";
12
- import { docTypeParsers } from "./doc.js";
13
+ import { DocSyntaxError, docTypeParsers } from "./doc.js";
13
14
  import { NodeFs } from "./invariants.js";
14
15
  import { MarkdownTree } from "./markdown-tree.js";
15
16
  import { DOC_KEYS, Projector } from "./project.js";
@@ -53,7 +54,7 @@ export class Contract {
53
54
  /** The row source — the ONE canonicalize seam (split + canonicalize once). */
54
55
  #rowSource;
55
56
  constructor() {
56
- this.#strategies = Contract.policy();
57
+ this.#strategies = _a.policy();
57
58
  this.#projector = new Projector(declaredRegistries);
58
59
  this.#translator = new Translator(new Words());
59
60
  this.#rowSource = new RowSource(this.#translator);
@@ -83,7 +84,18 @@ export class Contract {
83
84
  * and JudgeContext.head (§2.2's delivery seam — the chain facts the head carries
84
85
  * are the same record the invariants judge). The source stays intact. */
85
86
  validate(input) {
86
- const context = this.#contextOf(input);
87
+ return this.#docFindings(input);
88
+ }
89
+ /** The doc-scope judgment body — the context construction (the ONLY caught step)
90
+ * plus every declared strategy of the input's doc key. */
91
+ #docFindings(input) {
92
+ let context;
93
+ try {
94
+ context = this.#contextOf(input);
95
+ }
96
+ catch (error) {
97
+ return [_a.#syntaxFinding(input, error)];
98
+ }
87
99
  const findings = [];
88
100
  for (const strategy of this.#strategies[input.docKey]) {
89
101
  findings.push(...strategy.evaluate(context));
@@ -95,7 +107,18 @@ export class Contract {
95
107
  * `scope: "ledger"` declaration applicable to the input's doc key. Two arguments,
96
108
  * one judgment — the doc-scope rules never run here (and vice versa). */
97
109
  validateLedger(input, ledger) {
98
- const context = this.#contextOf(input);
110
+ return this.#ledgerFindings(input, ledger);
111
+ }
112
+ /** The ledger-scope judgment body — the context construction (the ONLY caught
113
+ * step) plus every declared `scope: "ledger"` rule of the input's doc key. */
114
+ #ledgerFindings(input, ledger) {
115
+ let context;
116
+ try {
117
+ context = this.#contextOf(input);
118
+ }
119
+ catch (error) {
120
+ return [_a.#syntaxFinding(input, error)];
121
+ }
99
122
  const findings = [];
100
123
  for (const declaration of RULE_REGISTRY) {
101
124
  if (declaration.scope !== "ledger")
@@ -107,6 +130,23 @@ export class Contract {
107
130
  }
108
131
  return findings;
109
132
  }
133
+ /** The document-syntax face of a judgment — the parse face throws a typed
134
+ * `DocSyntaxError`, the judgment materializes exactly ONE Finding bound to the
135
+ * contract path (never a registered rule, never a new gate). The catch wraps the
136
+ * `#contextOf` call ALONE (spec §2.2's seam): it never catches the strategy loop,
137
+ * so a `DocSyntaxError` from a strategy is a programming break that rethrows
138
+ * instead of discarding the findings this judgment already collected. */
139
+ static #syntaxFinding(input, error) {
140
+ if (!(error instanceof DocSyntaxError))
141
+ throw error;
142
+ return {
143
+ path: input.path,
144
+ field: error.field,
145
+ message: error.message,
146
+ fix: error.fix,
147
+ kind: "doc-syntax",
148
+ };
149
+ }
110
150
  /** The assembled judgment context — the shared split/parse/translate seam of both
111
151
  * entries (one context construction, one canonicalize pass). */
112
152
  #contextOf(input) {
@@ -135,3 +175,4 @@ export class Contract {
135
175
  };
136
176
  }
137
177
  }
178
+ _a = Contract;
@@ -43,6 +43,17 @@ import { DOC_TYPE_VALUES } from "./declare.js";
43
43
  * The judge's policy composition and the board's declaration domain read THIS
44
44
  * tuple; a value drift is impossible (one array). */
45
45
  export const DOC_KEYS = DOC_TYPE_VALUES;
46
+ /** The task-heading accessor — a module-scope `this`-typed function expression, so
47
+ * every projection carries the SAME function instance (the projection-identity
48
+ * assertion compares two independent projections with `toEqual`, which compares
49
+ * function values by identity) while each call still reads that projection's own
50
+ * `slices` (the registry slice table stays the one fact source). An arrow would
51
+ * bind no `this`; a hand-written `RegExp` here would declare a second copy.
52
+ * `check:no-bare-functions` only matches line-leading `function`, so the const
53
+ * binding is inside the discipline. */
54
+ const taskHeadingPatternOf = function () {
55
+ return this.slices.find((slice) => slice.anchor === "### Task N:")?.valuePattern;
56
+ };
46
57
  /**
47
58
  * The projection carrier — the registered registries' single derivation surface.
48
59
  * Constructed on the declared registries (the domain's `declaredRegistries`),
@@ -195,7 +206,7 @@ export class Projector {
195
206
  : new RegExp(element.valuePattern),
196
207
  });
197
208
  }
198
- return { docType: registry.docType, slices };
209
+ return { docType: registry.docType, slices, taskHeadingPattern: taskHeadingPatternOf };
199
210
  }
200
211
  /** Project one registry onto its anchor-lexicon face. */
201
212
  #projectDocTokens(registry) {
@@ -8,6 +8,7 @@
8
8
  // The parse is split out of the tree facade (markdown-tree.ts) so the block
9
9
  // grammar, the document index and the selector engine each own one concern.
10
10
  import { TASK_ID_VALUE_PATTERN } from "./declare.js";
11
+ import { DocSyntaxError } from "./doc.js";
11
12
  /**
12
13
  * TaskBlockGrammar — the task-block structural constants. They live with the ONE
13
14
  * block parse, so the grammar has exactly one home.
@@ -276,8 +277,9 @@ export class TaskBlocksParser {
276
277
  for (const field of block.fields) {
277
278
  if (!TaskBlockGrammar.RESERVED.includes(field.key))
278
279
  continue;
280
+ const anchor = `#### ${field.key}`;
279
281
  if (seen.has(field.key)) {
280
- throw new Error(`task ${block.id} carries the reserved section "#### ${field.key}" more than once`);
282
+ throw new DocSyntaxError(anchor, `task ${block.id} carries the reserved section "${anchor}" more than once`, `keep one "${anchor}" section per task block — merge the duplicate bodies into the first one`);
281
283
  }
282
284
  seen.add(field.key);
283
285
  }
@@ -31,6 +31,9 @@ export class CliArtifacts {
31
31
  #projector;
32
32
  #issue;
33
33
  #stdinRead;
34
+ /** The composition root's artifact matrix — the ONE home of the `base` row's
35
+ * spelling; every read/write in this class asks it, never a memoized literal. */
36
+ #matrix;
34
37
  /** The composition-root usage throw — commander's OWN CommanderError (the root's
35
38
  * exit-normalization face; the split never re-implements the usage byte). */
36
39
  #usage;
@@ -42,6 +45,7 @@ export class CliArtifacts {
42
45
  this.#projector = opts.projector ?? new Projector(declaredRegistries);
43
46
  this.#issue = opts.issue;
44
47
  this.#stdinRead = opts.stdinRead;
48
+ this.#matrix = opts.matrix;
45
49
  this.#usage = opts.usage;
46
50
  }
47
51
  /** `cdd schema get <type> --output skeleton <target>` — the derived doc skeleton
@@ -114,8 +118,8 @@ export class CliArtifacts {
114
118
  plan: planPath,
115
119
  recordedAt: new Date().toISOString(),
116
120
  };
117
- workspace.writeJson("base.json", artifact);
118
- this.#io.stdout(`${root.relativize(workspace.resolve("base.json"))}\n`);
121
+ workspace.writeJson(this.#baseName(), artifact);
122
+ this.#io.stdout(`${root.relativize(workspace.resolve(this.#baseName()))}\n`);
119
123
  return 0;
120
124
  }
121
125
  /** The `get` body — read + validate + print the artifact JSON (exit 2 when the
@@ -126,7 +130,7 @@ export class CliArtifacts {
126
130
  baseGet(workspace, root) {
127
131
  const artifact = this.#readBase(workspace);
128
132
  if (artifact === null) {
129
- const path = root.relativize(workspace.resolve("base.json"));
133
+ const path = root.relativize(workspace.resolve(this.#baseName()));
130
134
  this.#io.stderr(`cdd base get: missing or corrupt base artifact at ${path}\n`);
131
135
  return 2;
132
136
  }
@@ -157,6 +161,11 @@ export class CliArtifacts {
157
161
  const day = String(now.getDate()).padStart(2, "0");
158
162
  return `${now.getFullYear()}-${month}-${day}`;
159
163
  }
164
+ /** The base artifact's workspace-relative name — the matrix's `base` row renders it
165
+ * (one spelling, one home; this class never carries a copy). */
166
+ #baseName() {
167
+ return this.#matrix.render({ domain: "workspace", tasks: null }, "base");
168
+ }
160
169
  /** Read + validate the base artifact; null when missing or malformed — a total
161
170
  * read (never a throw). The read rides `Workspace.readJson` (P11 · §4.2) — the
162
171
  * read/write single normalization path, so a legacy absolute `plan` field reads
@@ -166,7 +175,7 @@ export class CliArtifacts {
166
175
  * narrowed to the declared enum domain (a value outside the four-value set is a
167
176
  * schema-invalid artifact → null, never a fabricated source). */
168
177
  #readBase(workspace) {
169
- const read = workspace.readJson("base.json");
178
+ const read = workspace.readJson(this.#baseName());
170
179
  if (read.kind !== "ok")
171
180
  return null;
172
181
  const parsed = read.value;