@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
|
@@ -18,7 +18,7 @@
|
|
|
18
18
|
// The route-borne prose (the fix readback suffix · the soft-cap message) rides
|
|
19
19
|
// declared constants from session/next.ts, rendered by reference, never restated.
|
|
20
20
|
// Module-level exports are the class — zero behavior-carrying bare functions.
|
|
21
|
-
import { FIX_READBACK_SUFFIX, NEXT_HOP_REASON } from "../session/next.js";
|
|
21
|
+
import { FIX_READBACK_SLOT, FIX_READBACK_SUFFIX, NEXT_HOP_REASON, } from "../session/next.js";
|
|
22
22
|
import { REFS } from "./host.js";
|
|
23
23
|
/**
|
|
24
24
|
* RouteRenderer — the single route → `next:` literal face (D40). One instance holds
|
|
@@ -153,7 +153,13 @@ export class RouteRenderer {
|
|
|
153
153
|
* <readback>` (the readback suffix the declared constant, rendered by reference).
|
|
154
154
|
* Every embedded path value (the doc-id for the doc shapes · `--reviews`)
|
|
155
155
|
* is normalized to the repoRoot-relative shape (D47); the wave face's `<type-arg>`
|
|
156
|
-
* is a task key, not a path — passed through as-is.
|
|
156
|
+
* is a task key, not a path — passed through as-is.
|
|
157
|
+
*
|
|
158
|
+
* The readback sentence's PATH is a value the route carries (`Route.rulings`, rendered
|
|
159
|
+
* by the router from the carrier's own round identity): this face fills the declared
|
|
160
|
+
* slot and derives nothing. A route with no `rulings` value — a carrier the matrix
|
|
161
|
+
* cannot place — omits the sentence whole, so the line never prints an empty slot nor
|
|
162
|
+
* falls back to the naming rule the sentence used to teach. */
|
|
157
163
|
#fixText(route, target) {
|
|
158
164
|
if (route.reviews === undefined)
|
|
159
165
|
return this.#words.routeWord("fix");
|
|
@@ -161,22 +167,32 @@ export class RouteRenderer {
|
|
|
161
167
|
const type = target?.type ?? null;
|
|
162
168
|
const id = target?.id ?? "";
|
|
163
169
|
const reviews = this.#rel(route.reviews);
|
|
170
|
+
const readback = this.#readbackOf(route);
|
|
164
171
|
if (type === "wave") {
|
|
165
|
-
return `${verb} ${this.#flag("type")} wave ${this.#flag("tasks")} ${id} ${this.#flag("plan")} ${this.#planOf(target)} ${this.#flag("reviews")} ${reviews}
|
|
172
|
+
return `${verb} ${this.#flag("type")} wave ${this.#flag("tasks")} ${id} ${this.#flag("plan")} ${this.#planOf(target)} ${this.#flag("reviews")} ${reviews}${readback}`;
|
|
166
173
|
}
|
|
167
174
|
if (type === "plan") {
|
|
168
|
-
return `${verb} ${this.#flag("type")} plan ${this.#flag("plan")} ${this.#rel(id)} ${this.#flag("reviews")} ${reviews}
|
|
175
|
+
return `${verb} ${this.#flag("type")} plan ${this.#flag("plan")} ${this.#rel(id)} ${this.#flag("reviews")} ${reviews}${readback}`;
|
|
169
176
|
}
|
|
170
177
|
if (type === "branch") {
|
|
171
178
|
// The branch fix literal carries the workspace-identity `--plan` (isomorphic
|
|
172
179
|
// with the wave fix branch — a plan-less target resolves to the empty
|
|
173
180
|
// ref.short() directory, the workspace double identity).
|
|
174
|
-
return `${verb} ${this.#flag("type")} branch ${this.#flag("plan")} ${this.#planOf(target)} ${this.#flag("reviews")} ${reviews}
|
|
181
|
+
return `${verb} ${this.#flag("type")} branch ${this.#flag("plan")} ${this.#planOf(target)} ${this.#flag("reviews")} ${reviews}${readback}`;
|
|
175
182
|
}
|
|
176
183
|
if (type === null)
|
|
177
|
-
return `${verb} ${this.#flag("reviews")} ${reviews}
|
|
184
|
+
return `${verb} ${this.#flag("reviews")} ${reviews}${readback}`;
|
|
178
185
|
// phase-spec · overall · single-spec — the declared shapes ride `--spec`.
|
|
179
|
-
return `${verb} ${this.#flag("type")} ${type} ${this.#flag("spec")} ${this.#rel(id)} ${this.#flag("reviews")} ${reviews}
|
|
186
|
+
return `${verb} ${this.#flag("type")} ${type} ${this.#flag("spec")} ${this.#rel(id)} ${this.#flag("reviews")} ${reviews}${readback}`;
|
|
187
|
+
}
|
|
188
|
+
/** The fix readback sentence with the route's sidecar path in its value slot — the
|
|
189
|
+
* empty string when the route carries none (zero slot, zero sentence). The path is
|
|
190
|
+
* normalized through the ONE basis, exactly as the gate's `derived:` row is, so the
|
|
191
|
+
* two faces print one path byte for byte. */
|
|
192
|
+
#readbackOf(route) {
|
|
193
|
+
if (route.rulings === undefined)
|
|
194
|
+
return "";
|
|
195
|
+
return ` ${FIX_READBACK_SUFFIX.replace(FIX_READBACK_SLOT, this.#rel(route.rulings))}`;
|
|
180
196
|
}
|
|
181
197
|
/** The face-to-face handoff render — the pipeline entry: a `ref` fills the declared
|
|
182
198
|
* instruction phrase (`route to {ref} skill`, the word table's `handoffRef` row)
|
package/dist/face/words.js
CHANGED
|
@@ -129,6 +129,20 @@ export const CAPSULE_WORDS = {
|
|
|
129
129
|
* spec §3.3): the round still concludes, and this line names what was booked.
|
|
130
130
|
* Fill slot: {message}. */
|
|
131
131
|
softViolation: "round soft violation: {message}",
|
|
132
|
+
/** The `misplaced = block` report (spec §2.4) — the reason word plus the four
|
|
133
|
+
* sections: the rendered name, every name found in its place, the identity itself
|
|
134
|
+
* and the repair the orchestrator owns. Fill slots: {kind} / {derived} /
|
|
135
|
+
* {found} / {identity}; the repair sentence is fixed (the engine only refuses). */
|
|
136
|
+
artifactIdentity: {
|
|
137
|
+
reason: "artifact-identity · the round's `{kind}` sidecar sits off its rendered name",
|
|
138
|
+
derived: " derived: {derived}",
|
|
139
|
+
found: " found: {found}",
|
|
140
|
+
identity: " identity: {identity}",
|
|
141
|
+
repair: [
|
|
142
|
+
" repair: rename the found file to the derived name — the engine never moves,",
|
|
143
|
+
" rewrites or deletes an artifact; the workspace is yours",
|
|
144
|
+
],
|
|
145
|
+
},
|
|
132
146
|
/** The in-flight rows (P21 §2.2) — the held report, the takeover hint, the two
|
|
133
147
|
* corrupt shapes and the three canonical recovery sentences. */
|
|
134
148
|
inFlight: {
|
|
@@ -156,8 +170,9 @@ export const CAPSULE_WORDS = {
|
|
|
156
170
|
syntax: "! unparseable",
|
|
157
171
|
empty: "(empty plan)",
|
|
158
172
|
orphan: "! no-spec",
|
|
159
|
-
orphanSpec: "the
|
|
173
|
+
orphanSpec: "the slug names no identity document (index clean miss): {slug} — no overall / phase-spec / single-spec declares it (every plan is written for one phase; add that document or fix the plan's `slug:`)",
|
|
160
174
|
slugMissing: "the plan declares no `slug:` key — add `slug: <workspace-key>` to the plan's front-matter and re-run",
|
|
175
|
+
discarded: "{roots} — {count} discarded candidate(s): the index cannot answer an absence from this surface — check those files (an unreadable or unregistered document hides an identity)",
|
|
161
176
|
cellEmpty: "",
|
|
162
177
|
},
|
|
163
178
|
/** The cut-short round's late-landing hint — every kill / timeout / crash message
|
|
@@ -339,6 +354,32 @@ export class Words {
|
|
|
339
354
|
softViolation(message) {
|
|
340
355
|
return CAPSULE_WORDS.softViolation.replace("{message}", message);
|
|
341
356
|
}
|
|
357
|
+
/** The `misplaced = block` report (spec §2.4) — the reason word over the four
|
|
358
|
+
* fact sections. Every candidate is printed (never a first pick) and the identity
|
|
359
|
+
* section is the SAME identity the rendered name came from, so `derived:` and
|
|
360
|
+
* `identity:` can never name two different coordinates. */
|
|
361
|
+
artifactIdentity(facts) {
|
|
362
|
+
const row = CAPSULE_WORDS.artifactIdentity;
|
|
363
|
+
return [
|
|
364
|
+
row.reason.replace("{kind}", facts.kind),
|
|
365
|
+
row.derived.replace("{derived}", facts.derived),
|
|
366
|
+
row.found.replace("{found}", facts.found.length === 0 ? "(none)" : facts.found.join(" · ")),
|
|
367
|
+
row.identity.replace("{identity}", this.#identityWords(facts.identity)),
|
|
368
|
+
...row.repair,
|
|
369
|
+
].join("\n");
|
|
370
|
+
}
|
|
371
|
+
/** One identity as the report's `identity:` value — the round coordinates with the
|
|
372
|
+
* renderer's own attempt default (a missing attempt is attempt 1, so the printed
|
|
373
|
+
* coordinate never contradicts the rendered name). */
|
|
374
|
+
#identityWords(identity) {
|
|
375
|
+
if (identity.domain === "round") {
|
|
376
|
+
const cycle = identity.cycle === undefined ? "" : ` · cycle=${identity.cycle}`;
|
|
377
|
+
return `line=${identity.line} · op=${identity.op}${cycle} · attempt=${identity.attempt ?? 1}`;
|
|
378
|
+
}
|
|
379
|
+
if (identity.domain === "doc")
|
|
380
|
+
return `slug=${identity.slug} · doc-type=${identity.docType}`;
|
|
381
|
+
return `tasks=${identity.tasks ?? "(none)"}`;
|
|
382
|
+
}
|
|
342
383
|
/** The in-flight wording rows — the held report, the takeover hint, the two corrupt
|
|
343
384
|
* shapes and the canonical recovery sentences (one source; the CLI fills the held
|
|
344
385
|
* slots, never re-types a row). */
|
|
@@ -406,12 +447,17 @@ export class Words {
|
|
|
406
447
|
planOrphanWord() {
|
|
407
448
|
return CAPSULE_WORDS.planRead.orphan;
|
|
408
449
|
}
|
|
409
|
-
/** The `spec-absent` orphan diagnostic — the plan's slug
|
|
410
|
-
*
|
|
411
|
-
planOrphanSpec(slug
|
|
412
|
-
return CAPSULE_WORDS.planRead.orphanSpec
|
|
413
|
-
|
|
414
|
-
|
|
450
|
+
/** The `spec-absent` orphan diagnostic — the plan's slug alone (the identity is the
|
|
451
|
+
* slug; the retired derived path has no consumer left). */
|
|
452
|
+
planOrphanSpec(slug) {
|
|
453
|
+
return CAPSULE_WORDS.planRead.orphanSpec.replace("{slug}", slug);
|
|
454
|
+
}
|
|
455
|
+
/** The undecided-scan diagnostic — the dirty doc roots and the count of candidates
|
|
456
|
+
* they dropped (the fact that forbids answering "no plan" / "no identity"). */
|
|
457
|
+
planDiscardedWord(roots, discarded) {
|
|
458
|
+
return CAPSULE_WORDS.planRead.discarded
|
|
459
|
+
.replace("{roots}", roots.join(" · "))
|
|
460
|
+
.replace("{count}", String(discarded));
|
|
415
461
|
}
|
|
416
462
|
/** The `slug-absent` diagnostic — the plan parses but declares no identity key. */
|
|
417
463
|
planSlugMissing() {
|
|
@@ -7,19 +7,18 @@
|
|
|
7
7
|
//
|
|
8
8
|
// The sweep is the recovery leg of the invariant: a carrier left writable by a process
|
|
9
9
|
// killed outside the engine is sealed by the NEXT dispatch's preflight. Its scope is
|
|
10
|
-
// the
|
|
11
|
-
//
|
|
12
|
-
// records
|
|
10
|
+
// the matrix's `sealed` column, never a tail spelled here: a name the matrix attributes
|
|
11
|
+
// to a row marked `sealed` is sweepable, and every neighbour (`progress.json` ·
|
|
12
|
+
// `base.json` · `*-test-evidence.json` · the crash records · the orchestrator's rulings
|
|
13
|
+
// sidecar) answers `sealed: false` from its own row. A name no row attributes is not a
|
|
14
|
+
// carrier — the naming predicate that used to answer that fallback is retired, because
|
|
15
|
+
// a second name grammar beside the matrix is exactly the double expression this matrix
|
|
16
|
+
// exists to retire. With no matrix at all the sweep seals NOTHING: "no attribution"
|
|
17
|
+
// has no second answer.
|
|
13
18
|
//
|
|
14
19
|
// Module-level exports are the class — zero behavior-carrying bare functions.
|
|
15
20
|
import { chmodSync, readdirSync, statSync } from "node:fs";
|
|
16
21
|
import path from "node:path";
|
|
17
|
-
import { RoundNaming } from "../session/round-naming.js";
|
|
18
|
-
/** The ruling sidecar's suffix — a sidecar is written AFTER its carrier is sealed and
|
|
19
|
-
* is never sealed itself (spec §2.1). The name rule lives with `CarrierRulings`; this
|
|
20
|
-
* is the sweep's own belt-and-braces skip, so a future widening of the carrier
|
|
21
|
-
* predicate can never sweep a sidecar. */
|
|
22
|
-
const RULINGS_SUFFIX = ".rulings.json";
|
|
23
22
|
/**
|
|
24
23
|
* CarrierSeal — the permission-bit face of the engine's carriers. Stateless by
|
|
25
24
|
* construction (every method is a judgment over a path), so the whole surface is
|
|
@@ -44,39 +43,46 @@ export class CarrierSeal {
|
|
|
44
43
|
CarrierSeal.#chmod(target, CarrierSeal.WRITABLE);
|
|
45
44
|
}
|
|
46
45
|
/** Seal every ORPHAN carrier of one directory and return the names actually sealed.
|
|
47
|
-
* An orphan is
|
|
48
|
-
*
|
|
49
|
-
*
|
|
50
|
-
*
|
|
46
|
+
* An orphan is a name the matrix attributes to a `sealed` row that is still
|
|
47
|
+
* writable — left behind by a process killed outside the engine. `keep` names files
|
|
48
|
+
* the caller holds open itself (this round's own paths); a `.rulings.json` sidecar is
|
|
49
|
+
* never touched (its row is `sealed: false`). Everything else in the directory is
|
|
51
50
|
* invisible to the sweep, and an already-sealed carrier is zero churn: not returned,
|
|
52
|
-
* not rewritten, so an empty array means there was nothing to recover.
|
|
53
|
-
|
|
54
|
-
|
|
51
|
+
* not rewritten, so an empty array means there was nothing to recover.
|
|
52
|
+
*
|
|
53
|
+
* `artifacts` is REQUIRED and nullable on purpose: `null` means "this caller holds no
|
|
54
|
+
* matrix", and the sweep then seals nothing — the retired naming predicate is not
|
|
55
|
+
* re-minted here as a fallback, because that would be a second name grammar beside
|
|
56
|
+
* the matrix (the very defect P36 retires). */
|
|
57
|
+
static sweep(directory, keep, artifacts) {
|
|
58
|
+
const strays = CarrierSeal.#strays(directory, keep, artifacts);
|
|
55
59
|
for (const name of strays)
|
|
56
60
|
CarrierSeal.seal(path.join(directory, name));
|
|
57
61
|
return strays;
|
|
58
62
|
}
|
|
59
63
|
/** The directory's orphan carrier NAMES — the sweep's judgment, before any chmod. */
|
|
60
|
-
static #strays(directory, keep) {
|
|
64
|
+
static #strays(directory, keep, artifacts) {
|
|
61
65
|
const strays = [];
|
|
62
66
|
for (const entry of CarrierSeal.#entries(directory)) {
|
|
63
67
|
if (!entry.isFile())
|
|
64
68
|
continue;
|
|
65
69
|
const target = path.join(directory, entry.name);
|
|
66
|
-
if (!CarrierSeal.#isStray(target, entry.name, keep))
|
|
70
|
+
if (!CarrierSeal.#isStray(target, entry.name, keep, artifacts))
|
|
67
71
|
continue;
|
|
68
72
|
strays.push(entry.name);
|
|
69
73
|
}
|
|
70
74
|
return strays;
|
|
71
75
|
}
|
|
72
76
|
/** Whether one directory entry is an orphan carrier the sweep must recover: a minted
|
|
73
|
-
* carrier name, not held open by the caller, not
|
|
74
|
-
* sealed. An unreadable entry (a vanished race) is not a stray — the
|
|
75
|
-
* invents a recovery it did not make. */
|
|
76
|
-
static #isStray(target, name, keep) {
|
|
77
|
-
if (
|
|
77
|
+
* carrier name, not held open by the caller, not the orchestrator's rulings sidecar,
|
|
78
|
+
* and NOT already sealed. An unreadable entry (a vanished race) is not a stray — the
|
|
79
|
+
* sweep never invents a recovery it did not make. */
|
|
80
|
+
static #isStray(target, name, keep, artifacts) {
|
|
81
|
+
if (CarrierSeal.#isSidecar(name, artifacts))
|
|
78
82
|
return false;
|
|
79
|
-
if (
|
|
83
|
+
if (!CarrierSeal.#isSealedName(name, artifacts))
|
|
84
|
+
return false;
|
|
85
|
+
if (keep.includes(name))
|
|
80
86
|
return false;
|
|
81
87
|
try {
|
|
82
88
|
return (statSync(target).mode & 0o777) !== CarrierSeal.SEALED;
|
|
@@ -85,6 +91,23 @@ export class CarrierSeal {
|
|
|
85
91
|
return false;
|
|
86
92
|
}
|
|
87
93
|
}
|
|
94
|
+
/** Whether one name is the orchestrator's rulings sidecar — asked of the matrix
|
|
95
|
+
* (`attribute` answers the `rulings` kind for every spelling that attributes), so the
|
|
96
|
+
* sidecar tail has ONE spelling home and the sweep holds no second copy of it. */
|
|
97
|
+
static #isSidecar(name, artifacts) {
|
|
98
|
+
return artifacts?.attribute(name)?.kind === "rulings";
|
|
99
|
+
}
|
|
100
|
+
/** Whether one name belongs to a row the matrix marks `sealed`. The matrix's
|
|
101
|
+
* `sealed` column is the ONE answer for every kind a domain registers — the round
|
|
102
|
+
* rows included, which is what makes `draft` / `final` sweepable and the sidecar
|
|
103
|
+
* not. A name no row attributes is not a carrier, and a caller with no matrix has no
|
|
104
|
+
* attribution at all: both answer "not sealed", never a fallback grammar. */
|
|
105
|
+
static #isSealedName(name, artifacts) {
|
|
106
|
+
const attributed = artifacts?.attribute(name) ?? null;
|
|
107
|
+
if (attributed === null)
|
|
108
|
+
return false;
|
|
109
|
+
return artifacts?.rowOf(attributed.kind)?.sealed === true;
|
|
110
|
+
}
|
|
88
111
|
/** The directory's entries — an unreadable directory (never created) holds no
|
|
89
112
|
* orphans, so the sweep is a no-op rather than a failure. */
|
|
90
113
|
static #entries(directory) {
|