@oscaner-skills/cdd-engine 4.2.0 → 4.3.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.
Files changed (55) hide show
  1. package/README.md +38 -9
  2. package/README.zh-CN.md +43 -9
  3. package/dist/contract/completion-criterion.js +351 -0
  4. package/dist/contract/declare.js +181 -43
  5. package/dist/contract/doc.js +84 -271
  6. package/dist/contract/frontmatter.js +2 -1
  7. package/dist/contract/home-extractors.js +49 -316
  8. package/dist/contract/invariants.js +400 -296
  9. package/dist/contract/judge.js +74 -49
  10. package/dist/contract/lint.js +3 -2
  11. package/dist/contract/liveness-signal.js +103 -0
  12. package/dist/contract/markdown-document.js +410 -0
  13. package/dist/contract/markdown-tree-types.js +6 -0
  14. package/dist/contract/markdown-tree.js +137 -0
  15. package/dist/contract/project.js +1 -1
  16. package/dist/contract/rules.js +106 -0
  17. package/dist/contract/selector-engine.js +332 -0
  18. package/dist/contract/selector-spec.js +74 -0
  19. package/dist/contract/skill-anatomy.js +29 -1
  20. package/dist/contract/task-block-grammar.js +285 -0
  21. package/dist/contract/task-blocks.js +65 -0
  22. package/dist/contract/translate.js +21 -0
  23. package/dist/contract/wave-width.js +15 -0
  24. package/dist/face/board-view.js +401 -131
  25. package/dist/face/capsule.js +66 -89
  26. package/dist/face/cli.js +116 -35
  27. package/dist/face/declare.js +36 -18
  28. package/dist/face/gate.js +117 -40
  29. package/dist/face/init.js +1 -1
  30. package/dist/face/lifecycle.js +540 -123
  31. package/dist/face/preview.js +43 -10
  32. package/dist/face/route-render.js +51 -21
  33. package/dist/face/termination.js +135 -261
  34. package/dist/face/words.js +134 -12
  35. package/dist/infra/atomic.js +15 -0
  36. package/dist/infra/git.js +25 -0
  37. package/dist/infra/proc.js +150 -0
  38. package/dist/infra/round-log.js +104 -0
  39. package/dist/infra/runtime.js +16 -4
  40. package/dist/infra/workspace.js +7 -2
  41. package/dist/render/brief.js +15 -17
  42. package/dist/render/skeleton.js +41 -28
  43. package/dist/render/templates.js +128 -84
  44. package/dist/session/faces.js +47 -20
  45. package/dist/session/graph.js +13 -37
  46. package/dist/session/handoff-schema.js +16 -8
  47. package/dist/session/inflight.js +282 -0
  48. package/dist/session/ledger.js +581 -136
  49. package/dist/session/line-identity.js +33 -0
  50. package/dist/session/next.js +138 -80
  51. package/dist/session/preflight.js +276 -68
  52. package/dist/session/round-naming.js +56 -8
  53. package/dist/session/run.js +317 -78
  54. package/dist/session/wave.js +94 -14
  55. package/package.json +13 -3
@@ -10,10 +10,11 @@
10
10
  import { Words } from "../face/words.js";
11
11
  import { declaredRegistries } from "./declare.js";
12
12
  import { docTypeParsers } from "./doc.js";
13
- import { FrontMatterExtractor } from "./frontmatter.js";
14
- import { ContinuityInvariant, CrossDocChainInvariant, CrosslinkInvariant, DomainInvariant, FileExistenceInvariant, HollowInvariant, LinkShapeInvariant, NodeFs, OrderInvariant, PresenceInvariant, ResidueInvariant, SectionScopedDomainInvariant, SelfBoundedInvariant, SiblingScanInvariant, SlugRefInvariant, UniquenessInvariant, } from "./invariants.js";
13
+ import { NodeFs } from "./invariants.js";
14
+ import { MarkdownTree } from "./markdown-tree.js";
15
15
  import { DOC_KEYS, Projector } from "./project.js";
16
- import { Translator } from "./translate.js";
16
+ import { RULE_REGISTRY } from "./rules.js";
17
+ import { RowSource, Translator } from "./translate.js";
17
18
  /**
18
19
  * The contract coordinator — the interpreter's single face. One instance; the
19
20
  * strategy set is stateless (each strategy reads its judgment data from the
@@ -21,24 +22,26 @@ import { Translator } from "./translate.js";
21
22
  *
22
23
  * The P7 structure-plane canonicalize seam (design spec §2.1) + the T6 front-matter
23
24
  * delivery seam (§2.2): the Contract self-holds a Translator, and validate()
24
- * canonicalizes EVERY body line once at the row source — the normalized view
25
- * shared by parse and JudgeContext.lines. The split order is RAW-first: the raw
25
+ * canonicalizes EVERY body line once at the row source — the normalized view the
26
+ * parse face and the tree both read. The split order is RAW-first: the raw
26
27
  * content resolves its front-matter head BEFORE any canonicalize (front matter is
27
28
  * data — the canonicalize view would silently rewrite registered Chinese aliases
28
29
  * inside header values), then the post-fence body lines canonicalize and the SAME
29
- * typed head rides into parse(lines, head) and JudgeContext.head. Every
30
- * valuePattern judgment face (presence occurrenceLines · domain carrierLines ·
31
- * section-scoped · crosslink) matches the view, so the legacy Chinese charter
30
+ * typed head rides into parse(lines, head). Every valuePattern judgment face
31
+ * (presence occurrenceNodes · domain carrierNodes · section-scoped · crosslink)
32
+ * matches the view, so the legacy Chinese charter
32
33
  * markers (the doc-arch decision-group / upstream-endorsements leaves) match their
33
34
  * English canonical element patterns through the recognition face — never a second
34
35
  * hand-written zh pattern. The view is never written back: the source document
35
36
  * stays byte-identical and the original lines remain in input.content.
37
+ *
38
+ * The strategy composition is DECLARED, not hard-coded (P21 §3.1): `policy()` walks
39
+ * the rule declaration surface's doc-scope rows and instantiates each row's factory,
40
+ * and `ruleRows()` returns the same rows for the `checked` list — one list, one
41
+ * source, zero declaration re-copy.
36
42
  */
37
43
  export class Contract {
38
- /** The per-doc-key policy sets — the declared composition of the strategy family.
39
- * All fifteen strategies are registry-driven and judge every doc type, so the
40
- * per-key sets are the same ordered family; the record keying is what a future
41
- * per-type ordering/selection change would carry. */
44
+ /** The per-doc-key policy sets — the declaration-derived doc-scope strategy family. */
42
45
  #strategies;
43
46
  /** The projection carrier — the derived parse/skeleton faces the judgment reads. */
44
47
  #projector;
@@ -47,26 +50,77 @@ export class Contract {
47
50
  * of the P7 translation layer); embedded like the projector, so the production
48
51
  * construction points (`new Contract()`) stay argument-free. */
49
52
  #translator;
53
+ /** The row source — the ONE canonicalize seam (split + canonicalize once). */
54
+ #rowSource;
50
55
  constructor() {
51
- this.#strategies = Contract.#buildPolicy();
56
+ this.#strategies = Contract.policy();
52
57
  this.#projector = new Projector(declaredRegistries);
53
58
  this.#translator = new Translator(new Words());
59
+ this.#rowSource = new RowSource(this.#translator);
60
+ }
61
+ /** The declared doc-scope strategy composition — derived from `RULE_REGISTRY`
62
+ * (only `scope: "doc"` rows; a doc judgment never runs a ledger rule). One
63
+ * strategy instance per row per construction. */
64
+ static policy() {
65
+ const declarations = RULE_REGISTRY.filter((declaration) => declaration.scope === "doc");
66
+ const policy = {};
67
+ for (const key of DOC_KEYS) {
68
+ policy[key] = declarations
69
+ .filter((declaration) => declaration.docKeys === "all" || declaration.docKeys.includes(key))
70
+ .map((declaration) => declaration.create());
71
+ }
72
+ return policy;
73
+ }
74
+ /** The checked-list data face — every declaration row (both scopes), in registry
75
+ * order. The pre-flight renders these rows; it never writes a second list. */
76
+ static ruleRows() {
77
+ return RULE_REGISTRY;
54
78
  }
55
- /** validate(doc) — split, parse, compose, run, aggregate. The single judgment entry.
79
+ /** validate(doc) — split, parse, compose, run, aggregate. The single doc judgment entry.
56
80
  * The RAW content resolves its front-matter head first (the data plane — never
57
81
  * canonicalized); the post-fence body lines canonicalize ONCE at the row source
58
82
  * (the normalized view), and the SAME typed head rides into parse(lines, head)
59
83
  * and JudgeContext.head (§2.2's delivery seam — the chain facts the head carries
60
84
  * are the same record the invariants judge). The source stays intact. */
61
85
  validate(input) {
62
- const { head, body } = FrontMatterExtractor.split(input.content);
63
- const lines = body.split("\n").map((line) => this.#translator.canonicalize(line));
64
- const parsed = docTypeParsers[input.docKey].parse(lines, head);
65
- const context = {
86
+ const context = this.#contextOf(input);
87
+ const findings = [];
88
+ for (const strategy of this.#strategies[input.docKey]) {
89
+ findings.push(...strategy.evaluate(context));
90
+ }
91
+ return findings;
92
+ }
93
+ /** validateLedger(input, ledger) — the ledger-scope judgment entry (P21 §3.1): the
94
+ * plan document under judgment plus the ledger fact bundle, judged by every
95
+ * `scope: "ledger"` declaration applicable to the input's doc key. Two arguments,
96
+ * one judgment — the doc-scope rules never run here (and vice versa). */
97
+ validateLedger(input, ledger) {
98
+ const context = this.#contextOf(input);
99
+ const findings = [];
100
+ for (const declaration of RULE_REGISTRY) {
101
+ if (declaration.scope !== "ledger")
102
+ continue;
103
+ if (declaration.docKeys !== "all" && !declaration.docKeys.includes(input.docKey))
104
+ continue;
105
+ const rule = declaration.create();
106
+ findings.push(...rule.evaluate(context, ledger));
107
+ }
108
+ return findings;
109
+ }
110
+ /** The assembled judgment context — the shared split/parse/translate seam of both
111
+ * entries (one context construction, one canonicalize pass). */
112
+ #contextOf(input) {
113
+ // The row source resolves the raw front-matter head, then canonicalizes the
114
+ // body ONCE (never a per-line translator API): the line face, the tree face and
115
+ // the parse face all read the same normalized bytes.
116
+ const { head, text, lines } = this.#rowSource.read(input.content);
117
+ const tree = MarkdownTree.parse(text);
118
+ const parsed = docTypeParsers[input.docKey].parse(lines, head, tree);
119
+ return {
66
120
  docKey: input.docKey,
67
121
  parsed,
68
122
  head,
69
- lines,
123
+ tree,
70
124
  path: input.path,
71
125
  root: input.root,
72
126
  slices: this.#projector.slices()[input.docKey],
@@ -77,36 +131,7 @@ export class Contract {
77
131
  translator: this.#translator,
78
132
  slugIndex: input.slugIndex,
79
133
  fs: input.fs ?? new NodeFs(),
134
+ taskLayers: input.taskLayers,
80
135
  };
81
- const findings = [];
82
- for (const strategy of this.#strategies[input.docKey]) {
83
- findings.push(...strategy.evaluate(context));
84
- }
85
- return findings;
86
- }
87
- /** The declared strategy composition — one ordered family set per doc key. */
88
- static #buildPolicy() {
89
- const family = [
90
- new PresenceInvariant(),
91
- new UniquenessInvariant(),
92
- new DomainInvariant(),
93
- new CrosslinkInvariant(),
94
- new OrderInvariant(),
95
- new ContinuityInvariant(),
96
- new ResidueInvariant(),
97
- new HollowInvariant(),
98
- new SelfBoundedInvariant(),
99
- new LinkShapeInvariant(),
100
- new FileExistenceInvariant(),
101
- new SiblingScanInvariant(),
102
- new SlugRefInvariant(),
103
- new CrossDocChainInvariant(),
104
- new SectionScopedDomainInvariant(),
105
- ];
106
- const policy = {};
107
- for (const key of DOC_KEYS) {
108
- policy[key] = family;
109
- }
110
- return policy;
111
136
  }
112
137
  }
@@ -41,7 +41,8 @@ export class LintPass extends MarkdownPrimitives {
41
41
  #proseToken;
42
42
  /** The derived `DependsOn id` value pattern (whole-token — the declared-edge values). */
43
43
  #depIdToken;
44
- /** The prose-owning task fields of the plan — the scanning-semantics surface. */
44
+ /** The prose-owning task sections of the plan — the scanning-semantics surface (the
45
+ * reader's field keys; the declared anchors are the `#### Key` headings). */
45
46
  #proseFieldKeys = ["Objective", "Acceptance"];
46
47
  constructor() {
47
48
  super();
@@ -50,7 +51,7 @@ export class LintPass extends MarkdownPrimitives {
50
51
  this.#proseToken = new RegExp(this.#valuePatternOf(planEntries, "Task prose reference"), "g");
51
52
  this.#depIdToken = new RegExp(this.#valuePatternOf(planEntries, "DependsOn id"));
52
53
  for (const key of this.#proseFieldKeys) {
53
- this.#valuePatternOf(planEntries, `**${key}**`);
54
+ this.#valuePatternOf(planEntries, `#### ${key}`);
54
55
  }
55
56
  }
56
57
  /** run — the single observation entry: one Warn per offending surface. */
@@ -0,0 +1,103 @@
1
+ // packages/cdd-engine/src-next/contract/liveness-signal.ts
2
+ // P22 T5 — the liveness signal contract + the four-state judge (design spec §4.2/§4.3).
3
+ // Both legs are evidence the CHILD itself produces, and nothing else can move them:
4
+ // · `LogGrowth` — the round log file's size (bytes arriving; zero parsing);
5
+ // · `CpuAdvance` — the process group's cumulative CPU (the additional leg).
6
+ // The retired workspace-mtime leg is GONE: a third party's writes into the tree could
7
+ // self-certify progress, which is exactly the false "still working" reading the phase
8
+ // removes. Its exclusion plane (`Sampler.excludesFor`, the tree walk) died with it, so
9
+ // "the engine's own writes never certify progress" is now structural rather than a
10
+ // declared exclusion.
11
+ //
12
+ // `LIVENESS_SIGNALS` is a PER-ROUND factory, never a module-level instance array: the
13
+ // sampler builds this round's signals from this round's context, so the self-held
14
+ // `readableAt` state cannot leak across rounds (a previous round's "was readable" must
15
+ // never testify for the next one). Each entry NAMES its leg, so the postmortem cells
16
+ // (`logSize` / `cpuMs`) address their leg by name, never by array position.
17
+ //
18
+ // `readableAt` is the tick at which the leg was last READ, retained across unreadable
19
+ // ticks — so "readable somewhere inside the window" is a judgeable present fact instead
20
+ // of a lost past.
21
+ //
22
+ // Module-level exports are types / the declared registry / the classes — zero
23
+ // behavior-carrying bare functions.
24
+ import { ProcessFacts } from "../infra/proc.js";
25
+ import { RoundLog } from "../infra/round-log.js";
26
+ /**
27
+ * LogGrowth — the round log's size. The file is created before the spawn (zero bytes)
28
+ * and only ever appended to, so it is readable and flat from the first tick: a child
29
+ * that never writes a byte reaches `stalled` instead of sitting in `unknown` until the
30
+ * wall-clock ceiling. A vanished / unreadable file is a null reading, not a throw.
31
+ */
32
+ export class LogGrowth {
33
+ #path;
34
+ #clock;
35
+ #readableAt = null;
36
+ constructor(path, clock = Date.now) {
37
+ this.#path = path;
38
+ this.#clock = clock;
39
+ }
40
+ sample() {
41
+ const now = this.#clock();
42
+ const value = RoundLog.sizeOf(this.#path);
43
+ if (value !== null)
44
+ this.#readableAt = now;
45
+ return { value, readableAt: this.#readableAt };
46
+ }
47
+ }
48
+ /**
49
+ * CpuAdvance — the process group's cumulative CPU through the ONE OS read face
50
+ * (`ProcessFacts.groupCpuMs`; `ps` stays inside `infra/proc.ts`). An unreadable `ps`
51
+ * (no such group, no `ps` at all) is a null reading: it contributes neither progress,
52
+ * nor unknown, nor a blocked stall.
53
+ */
54
+ export class CpuAdvance {
55
+ #pgid;
56
+ #clock;
57
+ #readableAt = null;
58
+ constructor(pgid, clock = Date.now) {
59
+ this.#pgid = pgid;
60
+ this.#clock = clock;
61
+ }
62
+ sample() {
63
+ const now = this.#clock();
64
+ const value = ProcessFacts.groupCpuMs(this.#pgid);
65
+ if (value !== null)
66
+ this.#readableAt = now;
67
+ return { value, readableAt: this.#readableAt };
68
+ }
69
+ }
70
+ /** The per-round signal registry — the log leg and the additional CPU leg. Factories,
71
+ * not instances: one round's self-held state is built for that round alone. */
72
+ export const LIVENESS_SIGNALS = [
73
+ { leg: "log", create: (context) => new LogGrowth(context.logPath) },
74
+ { leg: "cpu", create: (context) => new CpuAdvance(context.pgid) },
75
+ ];
76
+ /**
77
+ * LivenessJudge — the four-state truth table of design spec §4.2, pure logic:
78
+ * · any leg advanced over its previous reading → `progress`;
79
+ * · otherwise, at least one leg was readable inside `[now - windowMs, now]` →
80
+ * `idled` while the idle window is open, `stalled` (the group kill) once it is
81
+ * spent;
82
+ * · otherwise (no leg readable anywhere in the window) → `unknown`, which never
83
+ * kills (fail-open).
84
+ * An unreadable leg (`value === null`) is neutral: it neither advances, nor conjures
85
+ * `unknown`, nor blocks a stall. A leg that was readable earlier in the window and has
86
+ * since gone unreadable keeps that `readableAt`, so it still authorizes the stall.
87
+ */
88
+ export class LivenessJudge {
89
+ verdict(input) {
90
+ const advanced = input.readings.some((reading, index) => {
91
+ const previous = input.previous[index] ?? null;
92
+ return reading.value !== null && previous !== null && reading.value > previous;
93
+ });
94
+ if (advanced)
95
+ return "progress";
96
+ const readableInWindow = input.readings.some((reading) => reading.readableAt !== null &&
97
+ reading.readableAt >= input.now - input.windowMs &&
98
+ reading.readableAt <= input.now);
99
+ if (!readableInWindow)
100
+ return "unknown";
101
+ return input.idleMs < input.windowMs ? "idled" : "stalled";
102
+ }
103
+ }