@oscaner-skills/cdd-engine 4.3.0 → 4.5.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
@@ -33,7 +33,7 @@ Global option: `--dry-run` — preview the next dispatch step and the artifacts
33
33
  | `schema` | `cdd schema get <type>` | Print the canonical doc-structure schema (discovery-only, zero enforcement) |
34
34
  | `issue` | `cdd issue render` | Render an aggregate issue body from stdin findings (pure rendering, zero enforcement) |
35
35
  | `board` | `cdd board --plan <path> / --spec <path>` | Render the entry document's progress board (overall/phase-spec/single-spec/plan/wave/branch; pure read, zero enforcement) |
36
- | `init` | `cdd init --harness=<claude\|pi> [--update]` | Install or update the kairos plugin set for a harness (repo-independent, streams inherited) |
36
+ | `init` | `cdd init --harness=<claude\|pi> [--update] [--include-recommends]` | Install or update the kairos plugin set for a harness (repo-independent, streams inherited) |
37
37
 
38
38
  Use `cdd <command> --help` for a command's full option list (for example `cdd review --tasks` / `--spec` / `--plan` / `--round`).
39
39
 
@@ -88,4 +88,4 @@ During repository development the engine is invoked straight on the source entry
88
88
 
89
89
  ## License
90
90
 
91
- MIT
91
+ MIT
package/README.zh-CN.md CHANGED
@@ -35,7 +35,7 @@ npm install @oscaner-skills/cdd-engine
35
35
  | `schema` | `cdd schema get <type>` | 打印 canonical 文档结构 schema(发现型、零执法) |
36
36
  | `issue` | `cdd issue render` | 依据 stdin 发现渲染聚合 issue 正文(纯渲染、零执法) |
37
37
  | `board` | `cdd board --plan <path> / --spec <path>` | 渲染入口文档的进度板(overall/phase-spec/single-spec/plan/wave/branch;纯读、零执法) |
38
- | `init` | `cdd init --harness=<claude\|pi> [--update]` | 为指定 harness 安装或更新 kairos 插件集(与 repo 无关,三流继承) |
38
+ | `init` | `cdd init --harness=<claude\|pi> [--update] [--include-recommends]` | 为指定 harness 安装或更新 kairos 插件集(与 repo 无关,三流继承) |
39
39
 
40
40
  用 `cdd <command> --help` 查看某命令的完整选项列表(例如 `cdd review --tasks` / `--spec` / `--plan` / `--round`)。
41
41
 
@@ -0,0 +1,77 @@
1
+ // packages/cdd-engine/src-next/contract/doc-body.ts
2
+ // P26 T1 (spec §1.2/§1.3) — the doc-body projection: the ONE slice every
3
+ // `doc-revision` hashes. A reviewed document's identity is its BODY, never its
4
+ // bookkeeping: the front-matter head (`version:`, `date:`, …) and the
5
+ // `## Change history` register are closed-out registrations, so a write to either
6
+ // must not reopen a reviewed line, while a substantive body edit still drifts.
7
+ //
8
+ // The projection strips exactly two faces and nothing else:
9
+ // · the opening YAML block — the first `---` fence through the next `---` fence
10
+ // (fence recognition only: no YAML parse, and a `---` later in the body is
11
+ // body, not a fence);
12
+ // · the rank-2 `## Change history` section — located through
13
+ // `MarkdownTree.sections()` (the tree's rank-2 read), never a bare regex over
14
+ // the whole text, so a fenced sample of that heading inside the body stays.
15
+ // With neither face present the projection returns the input verbatim — the
16
+ // mapping is byte-identical there by construction, never an empty document.
17
+ var _a;
18
+ import { FrontMatterExtractor } from "./frontmatter.js";
19
+ import { MarkdownTree } from "./markdown-tree.js";
20
+ /**
21
+ * DocBodyProjection — the reviewed-body slice: `project(content)` returns the
22
+ * document with its bookkeeping faces removed. One stateless read; the hash
23
+ * itself stays at the single caller (`ReviewRefs#docRevision`), so this class
24
+ * answers WHAT the body is and never HOW it is digested.
25
+ */
26
+ export class DocBodyProjection {
27
+ /** The normalized rank-2 heading of the registration section — the one section
28
+ * name the projection strips (compared after heading normalization). */
29
+ static CHANGE_HISTORY = "change history";
30
+ /** Project a document onto its reviewed body: front matter and the change-history
31
+ * section removed, every other line kept in order. Returns the input unchanged
32
+ * when neither face is present (byte-identical, never an empty string). */
33
+ project(content) {
34
+ const lines = FrontMatterExtractor.lineSplit(content);
35
+ const bodyStart = this.#bodyStart(lines);
36
+ const dropped = this.#changeHistoryLines(lines.slice(bodyStart));
37
+ if (bodyStart === 0 && dropped.size === 0)
38
+ return content;
39
+ const kept = lines.filter((_, index) => index >= bodyStart && !dropped.has(index - bodyStart));
40
+ return FrontMatterExtractor.lineJoin(kept);
41
+ }
42
+ /** The first body line's index — past the closing fence when the document opens
43
+ * with one, 0 otherwise (a `---` deeper in the body is body, not a fence). */
44
+ #bodyStart(lines) {
45
+ if (lines[0]?.trim() !== "---")
46
+ return 0;
47
+ const closing = lines.findIndex((line, index) => index > 0 && line.trim() === "---");
48
+ return closing === -1 ? 0 : closing + 1;
49
+ }
50
+ /** The body-relative line indices of every `## Change history` section — the
51
+ * heading line plus its section body, read from the tree's rank-2 sections. */
52
+ #changeHistoryLines(body) {
53
+ const dropped = new Set();
54
+ const tree = MarkdownTree.parse(FrontMatterExtractor.lineJoin(body));
55
+ for (const section of tree.sections()) {
56
+ if (!_a.#isChangeHistory(section.text))
57
+ continue;
58
+ // `section.line` is 1-based: the heading sits at index line-1 and the section
59
+ // body runs `section.lines.length` lines further.
60
+ for (let index = section.line - 1; index < section.line + section.lines.length; index++) {
61
+ dropped.add(index);
62
+ }
63
+ }
64
+ return dropped;
65
+ }
66
+ /** Whether a heading text normalizes to the change-history name — fence markers
67
+ * and surrounding whitespace dropped, case folded. */
68
+ static #isChangeHistory(heading) {
69
+ const name = heading
70
+ .trim()
71
+ .replace(/^#+\s*/, "")
72
+ .trim()
73
+ .toLowerCase();
74
+ return name === _a.CHANGE_HISTORY;
75
+ }
76
+ }
77
+ _a = DocBodyProjection;
@@ -6,7 +6,8 @@
6
6
  // doc scope — presence (with the registration-uniqueness leg) · domain ·
7
7
  // crosslink · section-order · continuity · residue · hollow ·
8
8
  // file-existence · sibling-scan · link-shape · slug-ref ·
9
- // cross-doc-chain · section-scoped-domain;
9
+ // cross-doc-chain · section-scoped-domain ·
10
+ // phase-design-spec-is-phase-spec;
10
11
  // the change-history family — change-history-version-unique ·
11
12
  // front-matter-version-in-lineage ·
12
13
  // change-history-row-not-in-other-table · list-marker-not-doubled;
@@ -25,6 +26,7 @@ import path from "node:path";
25
26
  import { ENGINE_DOC_ROOTS } from "../infra/doc-roots.js";
26
27
  import { SlugIndex } from "../infra/slug-index.js";
27
28
  import { docTypeParsers, MarkdownPrimitives } from "./doc.js";
29
+ import { FrontMatterExtractor } from "./frontmatter.js";
28
30
  import { RowSource } from "./translate.js";
29
31
  import { MAX_TASKS_PER_WAVE } from "./wave-width.js";
30
32
  // ---------------------------------------------------------------------------
@@ -984,6 +986,61 @@ export class SiblingScanInvariant extends FileExistenceInvariant {
984
986
  ];
985
987
  }
986
988
  }
989
+ /** phase-design-spec-is-phase-spec — a Phase-inventory row's Design-spec cell must
990
+ * point at a document declaring `doc-type: phase-spec` (§4.4: the belonging judgment
991
+ * made executable). A phase row registered in a program's ledger cannot borrow a
992
+ * bespoke `single-spec` as its design: either the design belongs to the program (and
993
+ * is therefore a phase-spec) or it belongs nowhere and the row must leave the
994
+ * inventory. The cell's link target resolves through the ONE link-space reading
995
+ * (`FileExistenceInvariant.targetPath`); the target document's front-matter
996
+ * `doc-type:` is the judged fact — a document declaring no doc-type at all fails
997
+ * the same "must declare phase-spec" shape. Present facts only: a cell with no
998
+ * single bare link target, a placeholder, or a target the seam cannot read is NOT
999
+ * judged — a missing file is `file-existence`'s call, never a doc-type
1000
+ * contradiction. */
1001
+ export class PhaseDesignSpecIsPhaseSpecInvariant extends Invariant {
1002
+ name = "phase-design-spec-is-phase-spec";
1003
+ evaluate(ctx) {
1004
+ if (ctx.docKey !== "overall")
1005
+ return [];
1006
+ const data = this.record(ctx, "overall");
1007
+ if (data === null)
1008
+ return [];
1009
+ const findings = [];
1010
+ for (const phase of data.chain.phases) {
1011
+ const docType = this.#targetDocType(ctx, phase.designCell);
1012
+ // `undefined` = not judged (no judgeable target); `null` = the target declares
1013
+ // no doc-type, which is red — the cell must point at a phase-spec.
1014
+ if (docType === undefined || docType === "phase-spec")
1015
+ continue;
1016
+ findings.push(this.finding(ctx, `Phase inventory · ${phase.id}`, PhaseDesignSpecIsPhaseSpecInvariant.#messageOf(phase.id, docType), "either register this design as a phase document (doc-type: phase-spec, with program: and parent-version: naming this program) or drop the row from the Phase inventory"));
1017
+ }
1018
+ return findings;
1019
+ }
1020
+ /** The one-line message — the row, the doc-type the target actually declares.
1021
+ * A target declaring no doc-type reads as that absence, never as an empty value. */
1022
+ static #messageOf(phaseId, docType) {
1023
+ const declared = docType === null ? "declares no doc-type" : `declares doc-type: ${docType}`;
1024
+ return `the Phase inventory row ${phaseId} points its Design spec at a document that ${declared} — a registered phase's design spec must be a phase-spec`;
1025
+ }
1026
+ /** The `doc-type:` the cell's single link target declares — `undefined` when the
1027
+ * cell carries no judgeable target (no single link, a placeholder, a malformed
1028
+ * target shape, or an unreadable document), null when the readable target
1029
+ * declares no doc-type. */
1030
+ #targetDocType(ctx, cell) {
1031
+ const links = this.linksOnLine(cell);
1032
+ if (links.length !== 1)
1033
+ return undefined;
1034
+ const shape = LinkTargetShape.of(links[0].target);
1035
+ if (shape.target === null || this.isPlaceholder(shape.target))
1036
+ return undefined;
1037
+ const resolved = FileExistenceInvariant.targetPath(ctx.root, ctx.path, shape.target, (p) => ctx.fs.exists(p));
1038
+ const content = ctx.fs.read(resolved);
1039
+ if (content === null)
1040
+ return undefined;
1041
+ return FrontMatterExtractor.split(content).head.docType;
1042
+ }
1043
+ }
987
1044
  /** slug-ref — a `slug-ref` value names an on-disk identity document by `slug:`
988
1045
  * (the phase-spec's `program:` → an overall). The value is a SLUG, never a path,
989
1046
  * so this face judges it by identity lookup alone (zero path resolution, zero
@@ -23,8 +23,8 @@
23
23
  //
24
24
  // Module-level exports are types / the declared data — zero behavior-carrying bare
25
25
  // functions.
26
- import { ChangeHistoryVersionUniqueInvariant, ContinuityInvariant, CrossDocChainInvariant, CrosslinkInvariant, DomainInvariant, FileExistenceInvariant, FrontMatterVersionInLineageInvariant, HollowInvariant, LedgerLayeringRule, LedgerTaskSetRule, LinkShapeInvariant, ListMarkerInvariant, PhaseIdUniqueInvariant, PresenceInvariant, ResidueInvariant, RowHomeInvariant, SectionOrderInvariant, SectionScopedDomainInvariant, SiblingScanInvariant, SlugRefInvariant, TaskIdUniqueInvariant, WaveWidthInvariant, } from "./invariants.js";
27
- /** The rule registry — doc scope 20 rows + ledger scope 2 rows = 22. */
26
+ import { ChangeHistoryVersionUniqueInvariant, ContinuityInvariant, CrossDocChainInvariant, CrosslinkInvariant, DomainInvariant, FileExistenceInvariant, FrontMatterVersionInLineageInvariant, HollowInvariant, LedgerLayeringRule, LedgerTaskSetRule, LinkShapeInvariant, ListMarkerInvariant, PhaseDesignSpecIsPhaseSpecInvariant, PhaseIdUniqueInvariant, PresenceInvariant, ResidueInvariant, RowHomeInvariant, SectionOrderInvariant, SectionScopedDomainInvariant, SiblingScanInvariant, SlugRefInvariant, TaskIdUniqueInvariant, WaveWidthInvariant, } from "./invariants.js";
27
+ /** The rule registry — doc scope 21 rows + ledger scope 2 rows = 23. */
28
28
  export const RULE_REGISTRY = [
29
29
  { scope: "doc", id: "presence", docKeys: "all", create: () => new PresenceInvariant() },
30
30
  {
@@ -91,6 +91,12 @@ export const RULE_REGISTRY = [
91
91
  docKeys: ["plan"],
92
92
  create: () => new WaveWidthInvariant(),
93
93
  },
94
+ {
95
+ scope: "doc",
96
+ id: "phase-design-spec-is-phase-spec",
97
+ docKeys: ["overall"],
98
+ create: () => new PhaseDesignSpecIsPhaseSpecInvariant(),
99
+ },
94
100
  {
95
101
  scope: "ledger",
96
102
  id: "closed-wave-fits-depends-on-layers",