@oscaner-skills/cdd-engine 1.0.0 → 2.0.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 (99) hide show
  1. package/README.md +9 -8
  2. package/README.zh-CN.md +9 -8
  3. package/package.json +15 -22
  4. package/src-next/__tests__/bin.test.ts +128 -0
  5. package/src-next/__tests__/smoke.integration.test.ts +202 -0
  6. package/src-next/__tests__/zero-dep.test.ts +134 -0
  7. package/src-next/bin.ts +61 -0
  8. package/src-next/contract/__tests__/__snapshots__/project.schema.overall-spec.snap +238 -0
  9. package/src-next/contract/__tests__/__snapshots__/project.schema.phase-spec.snap +153 -0
  10. package/src-next/contract/__tests__/__snapshots__/project.schema.plan.snap +173 -0
  11. package/src-next/contract/__tests__/__snapshots__/project.schema.single-spec.snap +89 -0
  12. package/src-next/contract/__tests__/__snapshots__/project.shape.overall-spec.snap +225 -0
  13. package/src-next/contract/__tests__/__snapshots__/project.shape.phase-spec.snap +155 -0
  14. package/src-next/contract/__tests__/__snapshots__/project.shape.plan.snap +175 -0
  15. package/src-next/contract/__tests__/__snapshots__/project.shape.single-spec.snap +85 -0
  16. package/src-next/contract/__tests__/declare.test.ts +242 -0
  17. package/src-next/contract/__tests__/doc.test.ts +358 -0
  18. package/src-next/contract/__tests__/judge.test.ts +873 -0
  19. package/src-next/contract/__tests__/lint.test.ts +314 -0
  20. package/src-next/contract/__tests__/project.test.ts +419 -0
  21. package/src-next/contract/__tests__/translate.test.ts +96 -0
  22. package/src-next/contract/declare.ts +983 -0
  23. package/src-next/contract/doc.ts +753 -0
  24. package/src-next/contract/invariants.ts +1268 -0
  25. package/src-next/contract/judge.ts +142 -0
  26. package/src-next/contract/lint.ts +275 -0
  27. package/src-next/contract/project.ts +596 -0
  28. package/src-next/contract/skill-anatomy.ts +273 -0
  29. package/src-next/contract/translate.ts +113 -0
  30. package/src-next/face/__tests__/board-view.test.ts +948 -0
  31. package/src-next/face/__tests__/capsule.test.ts +276 -0
  32. package/src-next/face/__tests__/channel-closure.guard.test.ts +102 -0
  33. package/src-next/face/__tests__/cli.test.ts +4643 -0
  34. package/src-next/face/__tests__/face.test.ts +289 -0
  35. package/src-next/face/__tests__/graph-view.test.ts +61 -0
  36. package/src-next/face/__tests__/host.test.ts +24 -0
  37. package/src-next/face/__tests__/negation.ts +6 -0
  38. package/src-next/face/__tests__/projection.test.ts +301 -0
  39. package/src-next/face/__tests__/sync-runner.test.ts +70 -0
  40. package/src-next/face/__tests__/words.guard.test.ts +93 -0
  41. package/src-next/face/artifacts.ts +195 -0
  42. package/src-next/face/board-view.ts +662 -0
  43. package/src-next/face/capsule.ts +149 -0
  44. package/src-next/face/cli.ts +819 -0
  45. package/src-next/face/declare.ts +326 -0
  46. package/src-next/face/gate.ts +170 -0
  47. package/src-next/face/graph-view.ts +74 -0
  48. package/src-next/face/host.ts +326 -0
  49. package/src-next/face/lifecycle.ts +700 -0
  50. package/src-next/face/projection.ts +282 -0
  51. package/src-next/face/route-render.ts +160 -0
  52. package/src-next/face/words.ts +296 -0
  53. package/src-next/infra/__tests__/infra.test.ts +287 -0
  54. package/src-next/infra/config.ts +42 -0
  55. package/src-next/infra/git.ts +39 -0
  56. package/src-next/infra/process.ts +34 -0
  57. package/src-next/infra/runtime.ts +185 -0
  58. package/src-next/infra/workspace.ts +232 -0
  59. package/src-next/render/__tests__/render.test.ts +499 -0
  60. package/src-next/render/__tests__/skeleton.test.ts +466 -0
  61. package/src-next/render/brief.ts +121 -0
  62. package/src-next/render/issue-body.ts +159 -0
  63. package/src-next/render/skeleton.ts +437 -0
  64. package/src-next/render/templates.ts +650 -0
  65. package/src-next/session/__tests__/graph.test.ts +270 -0
  66. package/src-next/session/__tests__/handoff-plane.guard.test.ts +48 -0
  67. package/src-next/session/__tests__/handoff-schema.test.ts +310 -0
  68. package/src-next/session/__tests__/ledger.test.ts +744 -0
  69. package/src-next/session/__tests__/next.test.ts +368 -0
  70. package/src-next/session/__tests__/preflight.test.ts +491 -0
  71. package/src-next/session/__tests__/run.test.ts +1014 -0
  72. package/src-next/session/__tests__/wave-line-phase.guard.test.ts +49 -0
  73. package/src-next/session/__tests__/wave.test.ts +469 -0
  74. package/src-next/session/faces.ts +110 -0
  75. package/src-next/session/graph.ts +411 -0
  76. package/src-next/session/handoff-schema.ts +373 -0
  77. package/src-next/session/ledger.ts +1004 -0
  78. package/src-next/session/next.ts +192 -0
  79. package/src-next/session/preflight.ts +240 -0
  80. package/src-next/session/run.ts +606 -0
  81. package/src-next/session/state.ts +30 -0
  82. package/src-next/session/wave.ts +139 -0
  83. package/templates/report/issue-body.json +18 -20
  84. package/dist/chunks/branch.mjs +0 -480
  85. package/dist/chunks/docs.mjs +0 -253
  86. package/dist/chunks/task.mjs +0 -913
  87. package/dist/cli.mjs +0 -5457
  88. package/dist/documents/schema/add-phase-protocol.json +0 -126
  89. package/dist/documents/schema/overall.json +0 -361
  90. package/dist/documents/schema/phase-spec.json +0 -145
  91. package/dist/documents/schema/plan.json +0 -191
  92. package/dist/documents/schema/skill-anatomy.json +0 -233
  93. package/dist/resources/harness-registry.json +0 -49
  94. package/dist/shared/cdd-engine.liioziig.mjs +0 -184
  95. package/templates/engine-config.json +0 -302
  96. package/templates/schema/cache-profile-schema.json +0 -23
  97. package/templates/schema/docs-handoff-schema.json +0 -129
  98. package/templates/schema/task-handoff-schema.json +0 -332
  99. package/templates/template-contract.json +0 -231
@@ -1,191 +0,0 @@
1
- {
2
- "$schema": "https://json-schema.org/draft/2020-12/schema",
3
- "$id": "https://oscaner.dev/schemas/cdd/plan.json",
4
- "title": "Phase implementation plan document structure",
5
- "description": "Canonical structure of an osuperpowers phase implementation plan — the per-phase executable breakdown of one design spec. This schema is the single structure fact for the plan doc type: the header fields, the `### Task N:` colon-form task headings the brief extractor slices on, the per-task acceptance bullets, the Constraints source the dispatcher materializes plan-constraints.md from (canonical Form A literal `## Constraints` or legacy Form B prose pointers), and the `taskGroups` dispatch-group declaration the plan author writes (empty default ⇒ every task its own per-task group). Authoring agents read the properties + descriptions to draft conforming plans; docContractValidate / brief extraction consume the same patterns.",
6
- "type": "object",
7
- "properties": {
8
- "header": {
9
- "type": "object",
10
- "description": "Plan header block — the first lines after the `# Title`; metadata fields, not `##` sections.",
11
- "properties": {
12
- "specRef": {
13
- "type": "object",
14
- "description": "`**Spec:**` reference — the plan's approved design link, the same source as `plan-review`'s `--spec` pointer and report-issues' program attribution chain (plan record → `**Spec:**` → overall).",
15
- "properties": {
16
- "marker": {
17
- "type": "string",
18
- "const": "**Spec:**",
19
- "description": "The literal marker. Parsing semantics keep the engine contract (resolveSpecFromPlan): the marker is located by ANY-line findIndex — it may sit anywhere in the header. Line 2 (immediately after `# Title`) is the writing-plans template/example convention, NOT a schema required-position: a plan is valid wherever the `**Spec:**` line lives."
20
- },
21
- "linkForm": {
22
- "type": "string",
23
- "pattern": "^\\*\\*Spec:\\*\\*\\s+\\[[^\\]]+\\]\\([^)]+\\)$",
24
- "description": "Link form: `**Spec:** [<name>-design.md](docs/osuperpowers/specs/<name>-design.md)` — targets an existing spec file (repo-root form primary, file-relative fallback)."
25
- },
26
- "labelEqualsBasename": {
27
- "type": "object",
28
- "description": "Class-A label rule — the link label must equal the resolved file's basename.",
29
- "properties": {
30
- "rule": {
31
- "type": "string",
32
- "const": "label == basename",
33
- "description": "`[<label>](<target>)` — the label must equal the basename of the resolved target (drift fails)."
34
- }
35
- }
36
- }
37
- }
38
- },
39
- "parentProgram": {
40
- "type": "object",
41
- "description": "`**Parent program**` — link to the phase's parent overall (Class B lineage anchor).",
42
- "properties": {
43
- "marker": {
44
- "type": "string",
45
- "const": "**Parent program**",
46
- "description": "The literal marker."
47
- },
48
- "linkForm": {
49
- "type": "string",
50
- "pattern": "^-?(\\s*)\\*\\*Parent program\\*\\*:?\\s+\\[[^\\]]+\\]\\([^)]+\\)",
51
- "description": "Link form: `- **Parent program**: [<name>-overall.md vX.Y](<path>)` — resolves to an existing `*-overall.md`, and the version tokens on the line must belong to the parent overall's lineage (its `**Version:**` header ∪ change-history cells)."
52
- }
53
- }
54
- },
55
- "version": {
56
- "type": "object",
57
- "description": "`**Version**` — EXAMPLE field for a plan: only the phase-spec strictly requires a `**Version**` line; a plan header MAY carry one but no enforcing check reads it (the value has no lineage role at plan level). The example/template convention places it in the header block."
58
- },
59
- "dependsOn": {
60
- "type": "object",
61
- "description": "`**Depends on**` — upstream phase / spec pointers (e.g. `P1 design v1.1 Approved (sha)`); informational."
62
- },
63
- "base": {
64
- "type": "object",
65
- "description": "`**Base**` — the finishing read-base data source (e.g. `develop`); informational."
66
- }
67
- }
68
- },
69
- "constraints": {
70
- "type": "object",
71
- "description": "The plan's constraint surface — what `cdd implement` materializes plan-constraints.md from. Two declared sources (Form A or Form B); declaring neither is a plan-constraints-source-undeclared block (no silent fallback).",
72
- "properties": {
73
- "formACanonical": {
74
- "type": "object",
75
- "description": "Form A (canonical, preferred): a literal top-level `## Constraints` section with the constraint body as `###` sub-sections under it.",
76
- "properties": {
77
- "heading": {
78
- "type": "string",
79
- "pattern": "^## Constraints\\s*$",
80
- "description": "The literal `## Constraints` heading (the section is bounded by the next `##`/`#` heading, a `### Task` heading, or a `---` rule; `###` sub-sections stay inside)."
81
- }
82
- }
83
- },
84
- "formBProseAnchors": {
85
- "type": "object",
86
- "description": "Form B (legacy): prose-pointer bold paragraphs in the preamble — the four canonical anchor names, each with a bold label + full-width colon.",
87
- "properties": {
88
- "anchors": {
89
- "type": "array",
90
- "items": { "type": "string", "enum": ["**口径**:", "**commit 边界机制**:", "**Flow Atomicity**:", "**顺序原则**:"], "description": "One prose-anchor label token — bold name + full-width colon." },
91
- "description": "The four prose anchors (`口径` / `commit 边界机制` / `Flow Atomicity` / `顺序原则`), each a bold paragraph label followed by a full-width-colon block. A qualifier like `**commit 边界机制(本 program 全 phase 生效)**:` still occupies the anchor's slot; adding a suffix (`**commit 边界机制 补充**:`) makes it a different token and never fills the anchor requirement."
92
- }
93
- }
94
- }
95
- }
96
- },
97
- "taskHeadings": {
98
- "type": "object",
99
- "description": "Task headings — the brief extractor's slice surface (`/^### Task \\d+:/`).",
100
- "properties": {
101
- "format": {
102
- "type": "string",
103
- "const": "### Task N:",
104
- "description": "Colon format — `### Task N:` with an ASCII colon. A title after the colon is permitted and parse-tolerated (the extractor's slice surface `/^### Task \\d+:/` ignores everything after the colon); only a non-`:` delimiter after the number (em dash, Chinese colon, bare space) fails brief extraction at dispatch time."
105
- },
106
- "pattern": {
107
- "type": "string",
108
- "pattern": "^### Task \\d+:",
109
- "description": "Task heading pattern — 1-indexed tasks from `### Task 1:` through `### Task N:`, an optional title after the colon is parse-tolerated."
110
- },
111
- "continuity": {
112
- "type": "object",
113
- "description": "Continuity rule — task numbers must be 1-indexed and contiguous (every number 1..max present exactly once; duplicates and gaps fail).",
114
- "properties": {
115
- "rule": {
116
- "type": "string",
117
- "const": "contiguous from 1",
118
- "description": "extractTaskNumbers reads every `### Task N:` heading; the plan contract requires the extracted sequence to be exactly 1..N."
119
- }
120
- }
121
- }
122
- }
123
- },
124
- "taskBlock": {
125
- "type": "object",
126
- "description": "A per-task block under its `### Task N:` heading — the bullets the brief slices and the acceptance the plan carries.",
127
- "properties": {
128
- "do": {
129
- "type": "string",
130
- "pattern": "^- \\*\\*Do\\*\\*:",
131
- "description": "`- **Do**:` — the do-brief for the task (what to implement)."
132
- },
133
- "acceptance": {
134
- "type": "string",
135
- "pattern": "^- \\*\\*验收\\*\\*:",
136
- "description": "`- **验收**:` — the acceptance lines for the task; the brief extractor carries every acceptance line into the task brief verbatim."
137
- },
138
- "note": {
139
- "type": "string",
140
- "pattern": "^- \\*\\*注\\*\\*:",
141
- "description": "`- **注**:` — optional task note."
142
- }
143
- }
144
- },
145
- "taskGroups": {
146
- "type": "array",
147
- "default": [],
148
- "$defs": {
149
- "section": {
150
- "type": "object",
151
- "description": "The `## Task Groups` section layout — the dispatch-group declaration's plan surface: the section heading const + the one-line entry form per merged group. Written to the plan ONLY when a non-trivial merged group exists (the plan-authoring judgment: a length-1 group never lands on disk — the single-task state exists only as the empty default below).",
152
- "properties": {
153
- "heading": {
154
- "type": "string",
155
- "const": "## Task Groups",
156
- "description": "The section's top-level `##` heading (bounded like `## Constraints`: the next `#`/`##` heading, a `### Task N:` heading, or a `---` rule)."
157
- },
158
- "entry": {
159
- "type": "string",
160
- "pattern": "^- \\*\\*Task (?:\\d+(?:, \\d+)*)\\*\\*:",
161
- "description": "One merged-group line — `- **Task 1, 2**: <note>` — the task numbers comma-space separated (the `--tasks <a>,<b>` join form)."
162
- }
163
- }
164
- }
165
- },
166
- "items": {
167
- "type": "object",
168
- "required": ["tasks"],
169
- "description": "One declared dispatch group — the plan record of a merged `--tasks <a>,<b>` dispatch. Declared only when 2+ tasks merge; a length-1 group is redundant (the single-group state exists only as the empty default).",
170
- "properties": {
171
- "tasks": {
172
- "type": "array",
173
- "items": {
174
- "type": "integer",
175
- "minimum": 1,
176
- "description": "One task number of the merged group (a `### Task N:` id)."
177
- },
178
- "minItems": 2,
179
- "uniqueItems": true,
180
- "description": "The merged group's task numbers — unique and ascending (the deterministic group iteration order). minItems >= 2: a length-1 group is never declared."
181
- }
182
- }
183
- },
184
- "description": "Dispatch-group declaration — the plan author's dispatch-grouping decision in `author-plan` (its sole writer), carried by the plan's `## Task Groups` section; every dispatch iteration under `implement-group` reads it. Empty default: `[]` / an absent section ⇒ every `### Task N:` is its own singleton group — effectiveGroups = [[1],[2],…,[N]], exactly the pre-group per-task dispatch (zero migration); non-empty ⇒ effectiveGroups = the declared merged groups ∪ implicit single-task groups for any task a partial declaration leaves uncovered (the union is always the full plan task set). Section-persist rule: the section lands only when a non-trivial merged group exists — no groups → no section → empty default (zero plan churn)."
185
- },
186
- "language": {
187
- "type": "object",
188
- "description": "Repo authoring policy applies to the plan's prose — the plan at docs/osuperpowers/plans/ is an internal program doc written in the working language (Strategy B), value tokens (ids / tags / SHAs / paths) stay locale-neutral."
189
- }
190
- }
191
- }
@@ -1,233 +0,0 @@
1
- {
2
- "$schema": "https://json-schema.org/draft/2020-12/schema",
3
- "$id": "https://oscaner.dev/schemas/cdd/skill-anatomy.json",
4
- "title": "Node-anchored skill (SKILL.md) document structure",
5
- "description": "Canonical structure of an osuperpowers skill's SKILL.md — the node-anchored anatomy every consumer-facing skill document follows. The digraph is the sole control-flow source of truth; prose sections map one-to-one to graph nodes. This schema is the single structure fact for the skill-anatomy doc type: the section-heading registry (a STRICT allowlist the machine check enforces — a registry-external heading is a BLOCK because an undefined section is uncertainty on the consumer's real entry surface), the `## Flow Digraph` mermaid section (mermaid-only, zero trailing prose), the `### `node`` node-definition headings, the per-node four-element contract (Do / Read / Exit / Fail), the `## Invariants` and `## Failure Modes` tables, the BLOCKED terminal convention, the conditional `## Skeleton deltas` table (the writing-* spec-writer trio MUST carry it; the deltas table is the validation input for the skeleton-isomorphism assertion), the growth boundary (15 nodes / 17 edges — crossing requires a rationale registered in this schema's registry), and the consumer-surface purity rule (SKILL.md carries zero growth/refactor narrative headings in any form). Authoring agents read the properties below + their descriptions to draft conforming SKILL.md files; the machine check (packages/osuperpowers/tests/digraph-consistency.test.mjs) consumes the same patterns against every skill under packages/osuperpowers/skills/.",
6
- "type": "object",
7
- "properties": {
8
- "sectionRegistry": {
9
- "type": "object",
10
- "description": "The section-heading registry — the literal `## ` headings a SKILL.md may carry and the `### ` heading kinds a SKILL.md may use. STRICT allowlist, machine-enforced: four PUBLIC sections every skill carries (Flow Digraph · Node Definitions · Invariants · Failure Modes) plus one CONDITIONAL section (Skeleton deltas — mandatory for the writing-* spec-writer trio). Every live `## ` heading must be one of these five literals; every live `### ` heading must be the backticked node-name heading kind. Any heading outside the registry BLOCKS validation — an undefined section/heading is uncertainty on a consumer real entry surface that this schema has never defined (for example the evolution-narration sections `## Flow size note` / `## Full Flow Refactor Rationale` never appear).",
11
- "properties": {
12
- "public": {
13
- "type": "array",
14
- "items": {
15
- "type": "string",
16
- "enum": ["flowDigraph", "nodeDefinitions", "invariants", "failureModes"],
17
- "description": "One public section key — all four are mandatory on every SKILL.md (the section ORDER is free; only presence and registry membership are enforced)."
18
- },
19
- "description": "The four public sections — Flow Digraph · Node Definitions · Invariants · Failure Modes — every SKILL.md carries, whatever its node set."
20
- },
21
- "conditional": {
22
- "type": "array",
23
- "items": {
24
- "type": "string",
25
- "enum": ["skeletonDeltas"],
26
- "description": "One conditional section key — carried only by its required carriers."
27
- },
28
- "description": "The conditional section — Skeleton deltas (the writing-* spec-writer trio) — with its requiredCarriers below."
29
- },
30
- "sections": {
31
- "type": "object",
32
- "description": "Per-section canonical facts — the literal heading each section carries (the same const the allowlist matches) and, for the conditional sections, the required-carrier skill list (the skills the machine check demands the section from).",
33
- "properties": {
34
- "flowDigraph": {
35
- "type": "object",
36
- "description": "The `## Flow Digraph` section — control-flow source of truth (see the digraph facet for its content rule).",
37
- "properties": {
38
- "heading": { "type": "string", "const": "## Flow Digraph", "description": "The literal heading — the mermaid section's const." }
39
- }
40
- },
41
- "nodeDefinitions": {
42
- "type": "object",
43
- "description": "The `## Node Definitions` section — the `### `-headed per-node definitions.",
44
- "properties": {
45
- "heading": { "type": "string", "const": "## Node Definitions", "description": "The literal heading." }
46
- }
47
- },
48
- "invariants": {
49
- "type": "object",
50
- "description": "The `## Invariants` section — cross-node invariants declared centrally in a markdown table.",
51
- "properties": {
52
- "heading": { "type": "string", "const": "## Invariants", "description": "The literal heading." }
53
- }
54
- },
55
- "failureModes": {
56
- "type": "object",
57
- "description": "The `## Failure Modes` section — cross-node failure-to-behavior mappings in a markdown table (complements node Fail fields: Fail handles node-local failures, this table handles cross-node ones).",
58
- "properties": {
59
- "heading": { "type": "string", "const": "## Failure Modes", "description": "The literal heading." }
60
- }
61
- },
62
- "skeletonDeltas": {
63
- "type": "object",
64
- "description": "The conditional `## Skeleton deltas` section — a per-row record of how a skill's review-loop / commit / handoff skeleton diverges from the spec-writer-trio shared skeleton. The deltas table IS the validation input for the skeleton-isomorphism assertion: a skill's handoff node must match the value its table declares, and any divergence between siblings that the tables do not register fails; membership is self-describing — any skill carrying the table joins the family and must carry the canonical rows.",
65
- "properties": {
66
- "heading": { "type": "string", "const": "## Skeleton deltas", "description": "The literal heading." },
67
- "requiredCarriers": {
68
- "type": "array",
69
- "items": {
70
- "type": "string",
71
- "enum": ["writing-single-spec", "writing-phase-spec", "writing-overall-spec"],
72
- "description": "One spec-writer-trio skill — the shared review-loop/commit/handoff skeleton's owner; MUST carry the Skeleton deltas table."
73
- },
74
- "description": "The writing-* spec-writer trio (single / phase-spec / overall) — each MUST carry the `## Skeleton deltas` table; a trio member without the table fails the family guard."
75
- },
76
- "rows": {
77
- "type": "object",
78
- "description": "The deltas-table row vocabulary — the rows the machine check reads as validation input.",
79
- "properties": {
80
- "handoff": { "type": "string", "const": "handoff", "description": "The handoff row (key containing `handoff`) declares the skill's handoff-* node name in backticks — must equal the node the digraph actually draws." },
81
- "reviewLoop": { "type": "string", "pattern": "review loop", "description": "The review-loop row (key matching `review loop`) declares the shared shape (`shared shape — no delta`, or the registered divergence)." }
82
- }
83
- }
84
- }
85
- }
86
- }
87
- },
88
- "headingKinds": {
89
- "type": "object",
90
- "description": "The `### ` heading grammar — every live `### ` heading is a backticked node name (a node-definitions entry, mapped one-to-one to a digraph operator node). A `### ` heading of any other form (narrative, numbered phase, plain prose title) is registry-external → BLOCK.",
91
- "properties": {
92
- "nodeName": { "type": "string", "pattern": "^### `[^`]+`$", "description": "Backticked node-definition heading — the `### `node-name`` form; assertion 1's defined universe." }
93
- }
94
- }
95
- }
96
- },
97
- "digraph": {
98
- "type": "object",
99
- "description": "The Flow Digraph — the skill's control-flow graph embedded in a mermaid code block under `## Flow Digraph`. The section carries EXACTLY ONE mermaid block and ZERO trailing prose: the lines after the mermaid block are blank/whitespace until the next `## `/`# ` heading — a flow intro line below the mermaid (`7 process steps / 9 nodes: …`, any restatement) is redundant narration (Node Definitions already carry the detail) and forbidden on the consumer surface.",
100
- "properties": {
101
- "sectionHeading": { "type": "string", "const": "## Flow Digraph", "description": "The literal digraph section heading." },
102
- "mermaidOnly": { "type": "boolean", "const": true, "description": "Content rule — the section under the heading is exactly one ``````mermaid `````` fence; everything after the closing fence to the next `## ` heading is whitespace-only. Zero prose after the mermaid block." },
103
- "mermaidFence": { "type": "string", "const": "```mermaid", "description": "The opening fence — graphs are embedded in mermaid (broadest consumer rendering support)." },
104
- "nodeTypes": {
105
- "type": "object",
106
- "description": "The three mermaid node types.",
107
- "properties": {
108
- "operator": { "type": "string", "pattern": "^\\w+\\[.*\\]$", "description": "Operator node `A[do-thing]` — executes an action, has a defined exit; the node set that must map one-to-one to `### ` definitions (assertion 1)." },
109
- "decision": { "type": "string", "pattern": "^\\w+\\{.*\\}$", "description": "Decision node `B{condition?}` — conditional branch (diamond), flow-routing; exempt from the required-definition side unless it also defines a node." },
110
- "terminal": { "type": "string", "pattern": "^\\w+\\(\\(.*\\)\\)$", "description": "Terminal node `C((APPROVED))` / `D((BLOCKED: …))` — flow terminates (rounded)." }
111
- }
112
- },
113
- "terminalStates": {
114
- "type": "object",
115
- "description": "The three terminal states.",
116
- "properties": {
117
- "blocked": { "type": "string", "const": "BLOCKED", "description": "BLOCKED — flow terminates, requires user intervention (see the blockedTerminal facet for the convention)." },
118
- "approved": { "type": "string", "const": "APPROVED", "description": "APPROVED — flow completes normally." },
119
- "handoff": { "type": "string", "const": "HANDOFF", "description": "HANDOFF — hand the flow to the next skill/tool." }
120
- }
121
- },
122
- "edges": {
123
- "type": "object",
124
- "description": "The edge vocabulary — a digraph's edges connect nodes with the `-->` arrow.",
125
- "properties": {
126
- "unconditional": { "type": "string", "const": "A --> B", "description": "Unconditional edge — mandatory transition (no label)." },
127
- "conditional": { "type": "string", "const": "A -->|label| B", "description": "Conditional edge — the label describes the branch condition (`A -->|no| G`)." },
128
- "backEdge": { "type": "string", "const": "A -->|retry| B", "description": "Back-edge — an explicitly annotated loop (review loop / fix loop), e.g. `fix-spec --entered via blocker>0--> spec-review`." }
129
- }
130
- }
131
- }
132
- },
133
- "nodeDefinitions": {
134
- "type": "object",
135
- "description": "The Node Definitions section — the per-node prose definitions. Every digraph operator node has a definition heading and every definition heading names a digraph operator node (bidirectional completeness, assertion 1): orphans and dangling nodes fail with named diagnostics.",
136
- "properties": {
137
- "sectionHeading": { "type": "string", "const": "## Node Definitions", "description": "The literal section heading." },
138
- "headingKind": { "type": "string", "pattern": "^### `[^`]+`$", "description": "The `### `node-name`` heading form — a node definition's title (the same backticked form the heading-kind registry allows)." },
139
- "extensionRule": { "type": "string", "const": "prose sections map one-to-one to graph nodes", "description": "The core anatomy mapping — the digraph is the sole control-flow source of truth and each node's prose is the definition of one graph node." }
140
- }
141
- },
142
- "nodeElements": {
143
- "type": "object",
144
- "description": "The per-node four-element contract — every node definition's prose carries four bullet fields: Do / Read / Exit / Fail. A node missing any of the four elements is structurally incomplete (the four-element break is intercepted by the machine check).",
145
- "properties": {
146
- "do": { "type": "string", "pattern": "^- \\*\\*Do\\*\\*:", "description": "**Do** — what the node does: the executable action, including the explicit CLI invocation (tool + args) when the node dispatches a command, and numbered self-checks for critical constraints." },
147
- "read": { "type": "string", "pattern": "^- \\*\\*Read\\*\\*:", "description": "**Read** — the node's inputs: file paths, environment variables, context (a path list)." },
148
- "exit": { "type": "string", "pattern": "^- \\*\\*Exit\\*\\*:", "description": "**Exit** — routing on success (the next node / decision-branch criteria), aligned with the digraph's edges." },
149
- "fail": { "type": "string", "pattern": "^- \\*\\*Fail\\*\\*:", "description": "**Fail** — the node's failure mode → behavior (error / BLOCKED / retry / fail-open); complements the Failure Modes table (node-local vs cross-node split)." }
150
- }
151
- },
152
- "invariants": {
153
- "type": "object",
154
- "description": "The `## Invariants` section — cross-node invariants declared centrally in a markdown table. An invariant expressible inside a node belongs in that node's Do/Exit/Fail (the cross-node / node-local split decides placement; a cross-node rule lives here, a node-local rule never rides the central table).",
155
- "properties": {
156
- "sectionHeading": { "type": "string", "const": "## Invariants", "description": "The literal section heading." },
157
- "table": {
158
- "type": "object",
159
- "description": "The invariants table — a markdown table of numbered invariant rows.",
160
- "properties": {
161
- "row": { "type": "string", "pattern": "^\\|\\s*[A-Z]+\\d+\\s*\\|", "description": "An invariant row `| IN | <invariant text> |` — the number names the invariant (I1..IN); row content is free-form cross-node rule text." }
162
- }
163
- }
164
- }
165
- },
166
- "failureModes": {
167
- "type": "object",
168
- "description": "The `## Failure Modes` section — cross-node failure-to-behavior mappings in a markdown table. Complements node Fail fields (Fail = node-local failures; this table = cross-node failures); every failure maps to at least one graph edge or terminal node.",
169
- "properties": {
170
- "sectionHeading": { "type": "string", "const": "## Failure Modes", "description": "The literal section heading." },
171
- "table": {
172
- "type": "object",
173
- "description": "The failure-modes table — a markdown table mapping failures to behavior.",
174
- "properties": {
175
- "row": { "type": "string", "pattern": "^\\|[^\\n]+\\|$", "description": "A table row — the failure cell, behavior cell, and (where carried) reason/recovery cells." }
176
- }
177
- }
178
- }
179
- },
180
- "blockedTerminal": {
181
- "type": "object",
182
- "description": "The BLOCKED terminal convention — a flow that terminates BLOCKED requires user intervention to recover. BLOCKED-node prose carries a blocking reason (one sentence explaining why execution is stuck), a recovery action (concrete install instructions or manual user steps), and the no-silent-fallback statement (degradation and skipping are prohibited). The block policy: delegated skills treat a failed upstream import (`A -->|missing| Z((BLOCKED: install <plugin>))` terminal) as an explicit BLOCKED node with install instructions.",
183
- "properties": {
184
- "stateToken": { "type": "string", "const": "BLOCKED", "description": "The terminal-state token — terminal labels carry `BLOCKED`, optionally with a concrete reason (`((BLOCKED: <reason>))`)." },
185
- "labelShape": { "type": "string", "pattern": "^BLOCKED(?:\\s*:\\s*[^)\\n]+)?$", "description": "A BLOCKED terminal label — `BLOCKED` or `BLOCKED: <one-line reason>` (e.g. `BLOCKED: cdd-engine-not-installed`)." },
186
- "requires": {
187
- "type": "array",
188
- "items": {
189
- "type": "string",
190
- "enum": ["blocking reason", "recovery action", "no silent fallback"],
191
- "description": "One BLOCKED-prose requirement — the reason, the recovery, and the explicit no-silent-fallback statement."
192
- },
193
- "description": "The three BLOCKED-prose requirements — reason, recovery action, and the no-silent-fallback statement."
194
- }
195
- }
196
- },
197
- "growthBoundary": {
198
- "type": "object",
199
- "description": "The growth boundary — a skill whose digraph carries MORE than the node limit or MORE than the edge limit (all node types counted, re-declarations deduplicated) has crossed the boundary. Crossing is permitted only for a documented reason registered in this schema's registry below — NEVER inside the consumer-shipped SKILL.md in any form (consumer-surface purity): the growth-signal assertion reports every skill's node/edge counts on every validate run and fails a crossed skill whose rationale is not registered here. Flow-change discipline: a change that lands and gets justified afterwards is an unregistered delta on the next validate run.",
200
- "properties": {
201
- "nodeLimit": { "type": "integer", "const": 15, "description": "The node-count limit — crossing means MORE than 15 nodes (all node types counted, re-declarations deduplicated)." },
202
- "edgeLimit": { "type": "integer", "const": 17, "description": "The edge-count limit — crossing means MORE than 17 edges." },
203
- "registry": {
204
- "type": "object",
205
- "description": "The registered-rationale registry — every crossing skill names itself here, with what the crossing gained and why subdivision / a rewrite / the sibling-uniform option were rejected. The rationale never ships.",
206
- "properties": {
207
- "crossings": {
208
- "type": "object",
209
- "description": "The registered crossings — a per-skill map (crossing skill name → rationale object): a skill whose digraph crosses the growth boundary must name itself as a property here or the check fails; the registry currently carries zero entries. A future crossing adds its skill name + rationale as a property.",
210
- "properties": {}
211
- }
212
- }
213
- }
214
- }
215
- },
216
- "consumerPurity": {
217
- "type": "object",
218
- "description": "Consumer-surface purity (iron rule) — SKILL.md is an instruction document: its sections are executable direction or self-describing structure, never program narrative. Growth/refactor narrative headings are forbidden in ANY form (`## Flow size note` fails as hard as `## Full Flow Refactor Rationale`); design-history narration, mechanism explanation, internal-program references, and rationale/commentary on design decisions never ride the consumer surface. The whole rationale surface lives here (this schema) and the consumer skill carries zero trace of it — no one-line pointer or neutral note substitutes for removal; a removed flow step is edited out of the digraph, never annotated.",
219
- "properties": {
220
- "forbiddenNarrativeHeads": {
221
- "type": "array",
222
- "items": {
223
- "type": "string",
224
- "enum": ["## Flow size note", "## Full Flow Refactor Rationale"],
225
- "description": "One canonical growth/refactor narrative heading — the machine check fails any SKILL.md carrying it (and the section-heading allowlist blocks any other form of narrative heading)."
226
- },
227
- "description": "The canonical forbidden narrative headings — growth/refactor narration in any form (these are the regression pins; the allowlist blocks every other unregistered narrative heading too)."
228
- },
229
- "zeroTraceRule": { "type": "string", "const": "zero trace in the consumer skill", "description": "The purity rule's hard form — the rationale lives only in this schema's growthBoundary registry; the consumer SKILL.md carries zero trace of the crossing." }
230
- }
231
- }
232
- }
233
- }
@@ -1,49 +0,0 @@
1
- {
2
- "claude": {
3
- "cli": "claude",
4
- "invoke": "-p --output-format text --dangerously-skip-permissions",
5
- "output": "text",
6
- "ship": "full",
7
- "prefix": {
8
- "implement": "/mattpocock-skills:tdd",
9
- "review": {
10
- "task": "/mattpocock-skills:code-review — single agent, dual axis (standards + spec); parallel sub-agents forbidden",
11
- "branch": "/mattpocock-skills:code-review — single agent, dual axis (standards + spec); parallel sub-agents forbidden",
12
- "spec": "Follow URC: single-cycle, lens-tagged findings (completeness/consistency/clarity)",
13
- "plan": "Follow URC: single-cycle, lens-tagged findings (completeness/decomposition/buildability)"
14
- },
15
- "fix": "/mattpocock-skills:tdd"
16
- },
17
- "suffix": {},
18
- "cache": {
19
- "mechanism": "explicit",
20
- "minTokens": 512,
21
- "readMultiplier": 0.1,
22
- "writeMultiplier": 1.25,
23
- "ttlMinutes": 5,
24
- "observable": true
25
- }
26
- },
27
- "cursor-agent": {
28
- "cli": "cursor-agent",
29
- "invoke": "--print --output-format text --force",
30
- "output": "text",
31
- "ship": "full",
32
- "cache": {
33
- "mechanism": "auto-prefix",
34
- "minTokens": "pending",
35
- "observable": false
36
- },
37
- "prefix": {
38
- "implement": "/mattpocock-skills:tdd",
39
- "review": {
40
- "task": "/mattpocock-skills:code-review — single agent, dual axis (standards + spec); parallel sub-agents forbidden",
41
- "branch": "/mattpocock-skills:code-review — single agent, dual axis (standards + spec); parallel sub-agents forbidden",
42
- "spec": "Follow URC: single-cycle, lens-tagged findings (completeness/consistency/clarity)",
43
- "plan": "Follow URC: single-cycle, lens-tagged findings (completeness/decomposition/buildability)"
44
- },
45
- "fix": "/mattpocock-skills:tdd"
46
- },
47
- "suffix": {}
48
- }
49
- }