@oscaner-skills/cdd-engine 4.12.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`)。
@@ -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);
@@ -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;