@oscaner-skills/cdd-engine 1.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.
@@ -0,0 +1,126 @@
1
+ {
2
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
3
+ "$id": "https://oscaner.dev/schemas/cdd/add-phase-protocol.json",
4
+ "title": "Add-phase protocol document structure",
5
+ "description": "Canonical structure of the add-phase protocol — a methodology-doc for registering a new phase in a multi-phase program: every addition, split or re-assignment lands in the parent overall's four tables FIRST, and that registration is what the design session reads (register before grill). This schema is the single structure fact for the add-phase-protocol facet: the four-table sync checklist (row shapes for Issue inventory / Phase inventory / Dependency graph / Change history), the issue-reference syntax levels (anchored form machine-checked), and the pre-`sync-overall` consistency checks. The overall spec is the single source of truth (SOT); the four-table names are shared vocabulary between this protocol and the canonical schema (doc word = code word = engine token) — the enforcement position is the engine lifecycle (docContractValidate + the closeout audit at dispatch), not a repo-local script.",
6
+ "type": "object",
7
+ "properties": {
8
+ "fourTableSyncChecklist": {
9
+ "type": "object",
10
+ "description": "Section 1 — Four-table sync checklist: update all four tables in the parent overall and verify consistency when registration runs.",
11
+ "properties": {
12
+ "issueInventoryRow": {
13
+ "type": "object",
14
+ "description": "Issue inventory — append a row per new issue; a re-owned issue updates its Phase column instead of adding a row.",
15
+ "properties": {
16
+ "row": {
17
+ "type": "string",
18
+ "pattern": "^\\| P\\d+(\\.\\d+)* \\(?[^ ]*\\| #\\d+ \\| .+ \\|$",
19
+ "description": "Row shape `| P<new> | #NNN | one-line summary |` — canonical phase id (`P<digits>(.digits)*`, e.g. `P2.1`), anchored/none issue ref, one-line summary."
20
+ },
21
+ "reassign": {
22
+ "type": "string",
23
+ "const": "update the Phase column",
24
+ "description": "Existing-issue re-owning updates the Phase column instead of adding a row."
25
+ }
26
+ }
27
+ },
28
+ "phaseInventoryRow": {
29
+ "type": "object",
30
+ "description": "Phase inventory — append a row; Design-spec / plan cells fill as the phase progresses.",
31
+ "properties": {
32
+ "row": {
33
+ "type": "string",
34
+ "pattern": "^\\| P\\d+(\\.\\d+)* \\(?[^ ]*\\|",
35
+ "description": "Row shape `| P<new> | [scope] | [Pending]/link | [Pending]/link | [verifiable acceptance] | [hard or soft, ref graph] |` — canonical phase id (`P<digits>(.digits)*`, e.g. `P2.1`)."
36
+ },
37
+ "cellVocabulary": {
38
+ "type": "object",
39
+ "description": "Cell value vocabulary for the design-spec / plan / acceptance / dependency columns.",
40
+ "properties": {
41
+ "unstarted": { "type": "string", "const": "[Pending]", "description": "Unstarted cell placeholder." },
42
+ "link": { "type": "string", "pattern": "^\\[.*\\]\\([^)]*\\)$", "description": "Cell carrying a markdown doc link once the artifact exists." },
43
+ "acceptance": { "type": "string", "description": "Verifiable completion condition cell — the phase's verifiable acceptance." },
44
+ "dependency": { "type": "string", "pattern": "^P\\d+(\\.\\d+)*\\s*->", "description": "Hard (`->`) or soft (`-> (soft)`) dependency edge referencing a canonical phase id (`P<digits>(.digits)*`, e.g. `P2.1`)." }
45
+ }
46
+ }
47
+ }
48
+ },
49
+ "dependencyEdge": {
50
+ "type": "object",
51
+ "description": "Dependency graph — add the edge(s).",
52
+ "properties": {
53
+ "hard": {
54
+ "type": "string",
55
+ "pattern": "^P\\d+(\\.\\d+)*\\s*->\\s*P\\d+(\\.\\d+)*$",
56
+ "description": "Hard-block edge `P<pred> -> P<new>` (canonical ids `P<digits>(.digits)*`, e.g. `P2.1 -> P2.2`); successors depending on the new phase get `P<new> -> P<succ>`."
57
+ },
58
+ "soft": {
59
+ "type": "string",
60
+ "pattern": "^P\\d+(\\.\\d+)*\\s*->\\s*\\(?\\s*soft\\s*\\)?\\s*P\\d+(\\.\\d+)*$",
61
+ "description": "`-> (soft)` only for non-blocking ordering convenience (canonical ids `P<digits>(.digits)*` on both ends)."
62
+ }
63
+ }
64
+ },
65
+ "changeHistoryRow": {
66
+ "type": "object",
67
+ "description": "Change history — append one row per registration.",
68
+ "properties": {
69
+ "row": {
70
+ "type": "string",
71
+ "pattern": "^v\\d+\\.\\d+ · \\d{4}-\\d{2}-\\d{2} — ",
72
+ "description": "Row shape `vX.Y · YYYY-MM-DD — <reason: user decision + scope boundary>`."
73
+ }
74
+ }
75
+ }
76
+ }
77
+ },
78
+ "consistencyChecks": {
79
+ "type": "object",
80
+ "description": "Consistency check — must all hold before `sync-overall` exits (engine lifecycle enforcement — docContractValidate / closeout audit — not intention).",
81
+ "properties": {
82
+ "anchorsRegistered": {
83
+ "type": "string",
84
+ "const": "every #NNN referenced by the new phase spec / plan exists in the Issue inventory",
85
+ "description": "Check 1 — every issue reference exists in the Issue inventory."
86
+ },
87
+ "depPhasesRegistered": {
88
+ "type": "string",
89
+ "const": "every phase referenced by the Dependency graph exists in the Phase inventory",
90
+ "description": "Check 2 — every dependency-graph node exists in the Phase inventory."
91
+ },
92
+ "hardPredsShipped": {
93
+ "type": "string",
94
+ "const": "every hard-dependency predecessor has its Design spec column = Done",
95
+ "description": "Check 3 — hard-dependency predecessors must be shipped (not shipped → hard BLOCKED)."
96
+ }
97
+ }
98
+ },
99
+ "issueReferenceSyntax": {
100
+ "type": "object",
101
+ "description": "Section 2 — Issue-reference syntax levels (registration domain). The engine lifecycle scans only anchored-form issue references.",
102
+ "properties": {
103
+ "anchoredForm": {
104
+ "type": "string",
105
+ "pattern": "^#\\d+#issuecomment-\\d+$",
106
+ "description": "Anchored form `#NNN#issuecomment-<digits>` — canonical machine-checkable reference: whenever any document (overall / phase spec / plan) contains an anchor, `#NNN` must be registered in the Issue inventory (or the guard exits 1)."
107
+ },
108
+ "bareForm": {
109
+ "type": "string",
110
+ "pattern": "^#\\d+$",
111
+ "description": "Bare `#NNN` — ambiguous token (AC numbers / PR numbers / legacy references share `#`), not machine-disambiguable — membership judged by hand."
112
+ },
113
+ "registrationDomain": {
114
+ "type": "string",
115
+ "const": "Issue inventory",
116
+ "description": "The registration domain: every issue the program touches (owned finding + related/follow-up + pre-consume + re-assign destination) appears in the table."
117
+ },
118
+ "triggers": {
119
+ "type": "array",
120
+ "items": { "type": "string", "enum": ["new issue discovered during phase execution → declare ownership + add a row", "pre-consume → add a row + mark pre-consumed + note the actual fixing phase", "re-assign → update the Phase column"], "description": "One registration-trigger scenario." },
121
+ "description": "The three registration-trigger scenarios: new-discovery, pre-consume, re-assign."
122
+ }
123
+ }
124
+ }
125
+ }
126
+ }
@@ -0,0 +1,361 @@
1
+ {
2
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
3
+ "$id": "https://oscaner.dev/schemas/cdd/overall.json",
4
+ "title": "Overall program spec (charter) document structure",
5
+ "description": "Canonical structure of an osuperpowers overall (program charter) document — charter only, zero implementation detail. The overall is the program's single source of truth: every mid-phase change returns here (backfill-as-version) before implementation continues. The four enforcement tables — Issue inventory, Phase inventory, Dependency graph, Change history — are the engine-side audit vocabulary (doc word = code word = engine token): rename a heading and you rename the validator with it. This schema is the single structure fact for the overall doc type: authoring agents read the properties below + their descriptions to draft conforming documents, docContractValidate consumes the same patterns (the enforcement position is the engine lifecycle, not a repo-local script). Section-numbered facets below are written under their literal `## ` heading (validator-keyed); the `Section N` numbers in the retired template were frame indices only.",
6
+ "type": "object",
7
+ "properties": {
8
+ "header": {
9
+ "type": "object",
10
+ "description": "Artifact header block — metadata at the top of the artifact, a bullet block, not a `##` section.",
11
+ "properties": {
12
+ "version": {
13
+ "type": "object",
14
+ "description": "Current program version line (`- **Version**: vX.Y · YYYY-MM-DD`).",
15
+ "properties": {
16
+ "marker": {
17
+ "type": "string",
18
+ "const": "**Version**",
19
+ "description": "The canonical `**Version**` marker — the engine derives its version-line assertion token (VERSION_HEADER_RE family, tokens.ts) from this const plus the line pattern."
20
+ },
21
+ "line": {
22
+ "type": "string",
23
+ "pattern": "^\\s*-?\\s*\\*\\*Version\\*\\*:\\s*v\\d+\\.\\d+",
24
+ "description": "Version line shape; the `v\\d+\\.\\d+` token is the current version in the lineage (the file itself is the lineage source of truth — frozen docs legitimately pin the version in force at authoring time, fabricated / future tokens fail)."
25
+ }
26
+ }
27
+ },
28
+ "status": {
29
+ "type": "object",
30
+ "description": "Status line — `- **Status**: Draft | Approved | In progress | Complete`.",
31
+ "properties": {
32
+ "states": {
33
+ "type": "array",
34
+ "enum": ["Draft", "Approved", "In progress", "Complete"],
35
+ "description": "The overall status vocabulary."
36
+ }
37
+ }
38
+ },
39
+ "author": {
40
+ "type": "object",
41
+ "description": "Author line — `- **Author**: [human] · [harness + model at writing time]`.",
42
+ "properties": {
43
+ "form": {
44
+ "type": "string",
45
+ "description": "Author is a free-text contributor line; pronouns and names carry no structural rule."
46
+ }
47
+ }
48
+ },
49
+ "constraints": {
50
+ "type": "object",
51
+ "description": "Constraints block — `- **Constraints**:` with project-level constraints, one per line; a strategy shift / lock-in decision is recorded here before implementation proceeds.",
52
+ "properties": {
53
+ "marker": {
54
+ "type": "string",
55
+ "const": "**Constraints**:",
56
+ "description": "The literal constraint-block opening marker."
57
+ }
58
+ }
59
+ }
60
+ }
61
+ },
62
+ "sectionHeadings": {
63
+ "type": "object",
64
+ "description": "The four enforcement table headings — the literal validator-keyed vocabularies of the four-table audit (the '四表' of the closeout discipline).",
65
+ "properties": {
66
+ "issueInventory": {
67
+ "type": "string",
68
+ "const": "## Issue inventory",
69
+ "description": "Literal heading `## Issue inventory` (validator-keyed — the guard counts rows under this literal heading). Canonical even where an older artifact says `Requirement inventory`; do not copy the drift into new artifacts."
70
+ },
71
+ "phaseInventory": {
72
+ "type": "string",
73
+ "const": "## Phase inventory",
74
+ "description": "Literal heading `## Phase inventory` — carries the canonical-form marker (`Implementation plan` column)."
75
+ },
76
+ "dependencyGraph": {
77
+ "type": "string",
78
+ "pattern": "^## Dependency graph( \\(ASCII\\))?$",
79
+ "description": "Literal heading `## Dependency graph`; a `(ASCII)` suffix is tolerated by the guard."
80
+ },
81
+ "changeHistory": {
82
+ "type": "string",
83
+ "const": "## Change history",
84
+ "description": "Literal heading `## Change history` (validator-keyed — versions strictly ascending `v<major>.<minor>`, no duplicates)."
85
+ }
86
+ }
87
+ },
88
+ "issueInventory": {
89
+ "type": "object",
90
+ "description": "Section 4 — Issue inventory: every known issue / discovered requirement mapped to the phase that resolves it. Anchored forms (`#NNN#issuecomment-<digits>`) are machine-checkable; bare `#NNN` is ambiguous (AC numbers / PR numbers share `#`) and judged by hand. The table is the registration domain for anchors — an anchor referenced anywhere in the program must be registered here.",
91
+ "properties": {
92
+ "header": {
93
+ "type": "object",
94
+ "description": "Issue inventory header (columns).",
95
+ "properties": {
96
+ "columns": {
97
+ "type": "array",
98
+ "items": { "type": "string", "enum": ["Phase", "Issue (ref)", "Title summary"], "description": "One Issue-inventory column name." },
99
+ "description": "Three content columns — `Phase | Issue (ref) | Title summary`."
100
+ }
101
+ }
102
+ },
103
+ "row": {
104
+ "type": "object",
105
+ "description": "Issue inventory row shape: `| P<n> | <issue ref> | one-line summary |`.",
106
+ "properties": {
107
+ "phaseId": {
108
+ "type": "string",
109
+ "pattern": "^P\\d+(\\.\\d+)*$",
110
+ "description": "Phase id token — the canonical `P<digits>(.digits)*` form (`P1`, `P2.1`, `P2.2.3`): `P` plus a digit run and dot-digit segments after it. Dotted digits mark sub-phase hierarchy — `P2.1` is the sub-phase of `P2`; the phase id is the registration unit of split/merge operations. Letter suffixes (`P2a`) and hyphens (`P2-1`) are not valid ids; ordering is the natural (major, segments…) order."
111
+ },
112
+ "issueRef": {
113
+ "type": "string",
114
+ "description": "Issue reference — one of the five legal forms the doc-contract gate accepts: the literal `none`; a bare number ref `#NNN`; a bracket-wrapped `[#NNN]`; the anchored form `#NNN#issuecomment-<digits>` (canonical, machine-checkable — the registration-domain form); or a whole-cell parenthetical note (the ENTIRE cell wrapped in `(…)`/`(…)`, shape `^[((][^))]*[))]$`). Anything not matching one of these forms fails the doc-contract gate (`unrecognized issue ref`, or `malformed anchor ref` when `#issuecomment-` is followed by non-digits)."
115
+ },
116
+ "titleSummary": {
117
+ "type": "string",
118
+ "description": "One-line title summary — a single cell, no newline."
119
+ },
120
+ "anchorForm": {
121
+ "type": "string",
122
+ "pattern": "^#\\d+#issuecomment-\\d+$",
123
+ "description": "Anchored issue-reference syntax — the canonical machine-checkable form the registration domain counts."
124
+ }
125
+ }
126
+ }
127
+ }
128
+ },
129
+ "phaseInventory": {
130
+ "type": "object",
131
+ "description": "Section 5 — Phase inventory: the canonical phase row ledger the four-table audit keys on — every phase row, its scope, its doc links, its acceptance condition and its dependency edge. Each row is position-read over six content cells (`columnNames.count` == `rowShape.cellCount` − 2), never keyed by header names.",
132
+ "properties": {
133
+ "columnNames": {
134
+ "type": "object",
135
+ "description": "The Phase-inventory table header — the inspection row the engine keys on via its `| # | Phase |` open (`headerOpen`) plus the canonical-form marker column (`canonicalColumnToken`). The header names themselves are not the read map: content rows are position-read over six cells (`count` == `rowShape.cellCount` − 2).",
136
+ "properties": {
137
+ "count": {
138
+ "type": "integer",
139
+ "const": 6,
140
+ "description": "Number of content columns in a Phase-inventory row — six cells, position-read by the engine: `c1` = phase id, `c3` = Design spec, `c4` = Implementation plan, `c6` = Dependency — the row-shape guard's split count (`rowShape.cellCount`) minus the two edge empties."
141
+ },
142
+ "header": {
143
+ "type": "string",
144
+ "const": "| # | Phase | Scope | Design spec | Implementation plan | Acceptance criteria | Dependency |",
145
+ "description": "The Phase-inventory table header as written in conforming artifacts — a conventional inspection row only: the enforcement keys on its `| # | Phase |` open (`headerOpen`) and the `Implementation plan` marker column (`canonicalColumnToken`), and reads rows by position over the six content cells, never by this column list."
146
+ },
147
+ "headerOpen": {
148
+ "type": "string",
149
+ "pattern": "^\\|\\s*#\\s*\\|\\s*Phase\\s*\\|",
150
+ "description": "Header open token — `| # | Phase |` — the kernel the engine keys the Phase-inventory section on."
151
+ },
152
+ "canonicalColumnToken": {
153
+ "type": "string",
154
+ "const": "Implementation plan",
155
+ "description": "Canonical-form marker column — the engine's 'canonical file' test is the presence of this column name."
156
+ }
157
+ }
158
+ },
159
+ "rowShape": {
160
+ "type": "object",
161
+ "description": "Phase-inventory row shape (the row-shape guard — every `| P… |` row must carry the file-norm cell count; a merged/split cell shifts design/plan/dependency by a column and only detonates at closeout).",
162
+ "properties": {
163
+ "idFormat": {
164
+ "type": "string",
165
+ "pattern": "^P\\d+(\\.\\d+)*$",
166
+ "description": "Phase id token — the canonical `P<digits>(.digits)*` form (`P1`, `P2.1`, `P2.2.3`): `P` plus a digit run and dot-digit segments; dotted digits mark sub-phase hierarchy (`P2.1` is the sub-phase of `P2`), letter suffixes (`P2a`) and hyphens (`P2-1`) are invalid, ordering natural over (major, segments…). The identifier the dependency graph and the change-history claims reference."
167
+ },
168
+ "cellCount": {
169
+ "type": "integer",
170
+ "const": 8,
171
+ "description": "Split-cell count for one Phase row — the 6 content columns (`c1` = phase id, `c2` = scope, `c3` = Design spec, `c4` = Implementation plan, `c5` = acceptance criteria, `c6` = Dependency) plus the leading/trailing empties of the `|`-delineated row. The audit reads four of the content cells by position: id from `c1`, Design spec from `c3`, Implementation plan from `c4`, Dependency from `c6`."
172
+ },
173
+ "rowOpen": {
174
+ "type": "string",
175
+ "pattern": "^\\|\\s*P",
176
+ "description": "A Phase-inventory row opens with the leading pipe followed by the phase id."
177
+ }
178
+ }
179
+ },
180
+ "cells": {
181
+ "type": "object",
182
+ "description": "Per-column cell semantics (Scope / Design spec / Implementation plan / Acceptance criteria / Dependency).",
183
+ "properties": {
184
+ "pending": {
185
+ "type": "string",
186
+ "enum": ["Pending", "[Pending]"],
187
+ "description": "Unstarted plan-cell placeholder (未开工) — the first state of the three-state Implementation plan column (`[Pending]` → `[In-flight]` → shipped): carries NO plan-doc obligation and no claim. `Pending`/`[Pending]` is the same token in backfill claims."
188
+ },
189
+ "inflight": {
190
+ "type": "string",
191
+ "enum": ["In-flight", "[In-flight]"],
192
+ "description": "Started-but-not-complete plan cell (已开工) — mid-dispatch rows land here (P4.3 Task 8 #274): the plan-doc existence glob still applies (a non-missing cell) but the phase owes NO closeout claim (reverse-claim carve-out) and is never counted as a mismatch against one."
193
+ },
194
+ "linkCell": {
195
+ "type": "string",
196
+ "pattern": "^\\[.*\\]\\([^)]*\\)$",
197
+ "description": "A completed column carries a markdown link to the phase document (e.g. `[p1-design v1.1](2026-09-21-consumer-parity-p1-design.md)`). A link-form plan cell satisfies its backfill claim via OWN-DOCUMENT href identity (the href resolves to the phase's own `*-<slug>-<id>.md` / `*-<slug>-<id>-plan.md` file — the same design-column ownDesignToken alignment), never a per-character target match."
198
+ },
199
+ "done": {
200
+ "type": "string",
201
+ "const": "Done",
202
+ "description": "Shipped completion marker for the plan cell — the closeout state: requires a matching change-history backfill claim (`Pending` -> `Done`-style), the bidirectional check keys on it. A shipped plan cell may alternatively be a link-cell (`[label](href)`) whose href is the phase's own plan document — the equivalence is own-document identity, not a literal target token."
203
+ },
204
+ "dependency": {
205
+ "type": "string",
206
+ "pattern": "^P\\d+(\\.\\d+)*\\s*->|^P\\d+(\\.\\d+)*\\s*->\\s*\\(?\\s*soft\\s*\\)?",
207
+ "description": "Dependency cell cites the graph node with a hard (`->`) or soft (`-> (soft)`) edge — the edge token is a canonical phase id (`P<digits>(.digits)*`, e.g. `P2.1 ->`), the token the dependency-graph membership audit reads."
208
+ }
209
+ }
210
+ }
211
+ }
212
+ },
213
+ "dependencyGraph": {
214
+ "type": "object",
215
+ "description": "Section 6 — Dependency graph (ASCII): the phase dependency edges. Every `P<n>` token here must exist in the Phase inventory (membership audit) — add / split / reorder syncs the four tables together.",
216
+ "properties": {
217
+ "hardEdge": {
218
+ "type": "string",
219
+ "pattern": "^P\\d+(\\.\\d+)*\\s*->\\s*P\\d+(\\.\\d+)*$",
220
+ "description": "Hard-block edge: `P1 -> P2` — canonical phase ids (`P<digits>(.digits)*`) on both ends (e.g. `P2.1 -> P2.2`); the dependent must not start until the predecessor ships."
221
+ },
222
+ "softEdge": {
223
+ "type": "string",
224
+ "pattern": "^P\\d+(\\.\\d+)*\\s*->\\s*\\(?\\s*soft\\s*\\)?\\s*P\\d+(\\.\\d+)*$",
225
+ "description": "Soft-suggestion edge: `P1 -> (soft) P5` — canonical phase ids (`P<digits>(.digits)*`) on both ends (e.g. `P2.1 -> (soft) P2.2`); non-blocking ordering convenience."
226
+ },
227
+ "legendHard": {
228
+ "type": "string",
229
+ "const": "-> = hard block",
230
+ "description": "Legend line defining the hard edge."
231
+ },
232
+ "legendSoft": {
233
+ "type": "string",
234
+ "const": "-> (soft) = suggestion only",
235
+ "description": "Legend line defining the soft edge."
236
+ }
237
+ }
238
+ },
239
+ "changeHistory": {
240
+ "type": "object",
241
+ "description": "Section 9 — Change history: append-only backfill record (version bump + date + summary + author per row). Every backfill claim lives here as a clause; the file itself is the version-lineage source.",
242
+ "properties": {
243
+ "header": {
244
+ "type": "object",
245
+ "description": "Change-history header.",
246
+ "properties": {
247
+ "columns": {
248
+ "type": "array",
249
+ "items": { "type": "string", "enum": ["Version", "date", "summary", "author"], "description": "One conventional Change-history header column name — the engine never reads the header's names." },
250
+ "description": "Conventional header cell names only — the engine determines the version cell by POSITION, never by these names: the row's first content cell must carry the `v<major>.<minor>` version token (`row.versionCell`), with the non-empty date and the summary following. A `Version | date | summary` heading (or a leading `version`-named first cell) is skipped as a header row."
251
+ }
252
+ }
253
+ },
254
+ "row": {
255
+ "type": "object",
256
+ "description": "Change-history row shape.",
257
+ "properties": {
258
+ "versionCell": {
259
+ "type": "string",
260
+ "pattern": "^\\s*\\|\\s*v\\d+\\.\\d+\\s*\\|",
261
+ "description": "Version cell token — `| v<major>.<minor> |` as the row's first content cell (the lineage cell the version tokens are checked against)."
262
+ },
263
+ "versionToken": {
264
+ "type": "string",
265
+ "pattern": "^v\\d+\\.\\d+$",
266
+ "description": "Version token shape — `v<major>.<minor>`, strictly ascending and unique across the table (duplicates / out-of-order fail), date cell non-empty."
267
+ },
268
+ "date": {
269
+ "type": "string",
270
+ "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
271
+ "description": "Date cell — ISO `YYYY-MM-DD`, must be non-empty."
272
+ }
273
+ }
274
+ },
275
+ "backfillClause": {
276
+ "type": "object",
277
+ "description": "A change-history summary row may carry a backfill claim — a sentence whose keywords (`plan`/`计划`, `Design spec`) select which phase columns the `Pending -> <target>` clause backfills (the bidirectional backfill declaration ↔ column audit). Claim phases come from the EXPLICIT claim structure only (P4.3 Task 8 #274); same-clause prose that merely mentions a phase never backfills it — such mentions surface as a diagnosis hint, not a target.",
278
+ "properties": {
279
+ "clauseSeparator": {
280
+ "type": "string",
281
+ "const": ";",
282
+ "description": "Claim-clause boundary — `;`/`;` split a change-history sentence into clauses; a claim only attaches the phases of its own clause."
283
+ }
284
+ }
285
+ }
286
+ }
287
+ },
288
+ "claimPatterns": {
289
+ "type": "object",
290
+ "description": "The CLAIM_RE family — the canonical claim pattern + the plan/design link words that select which columns a change-history claim backfills.",
291
+ "properties": {
292
+ "claimClause": {
293
+ "type": "object",
294
+ "description": "Claim clause — the explicit claim structure `Pending`/`[Pending]` followed by an arrow to a target token (P4.3 Task 8 #274): ONLY the explicit structure is recognized — a claim attributes only the phases in its claim window (the span from after the previous claim's target to this claim match), never prose phase mentions bound with the same `;`-clause; a same-clause prose-mentioned phase rides as a diagnosis hint, never a target.",
295
+ "properties": {
296
+ "pattern": {
297
+ "type": "string",
298
+ "description": "CLAIM_RE — the canonical single source: `(Pending|[Pending])` + optional `→`/`->` + a target that stops at whitespace / CJK punctuation / brackets so `→ **Done**(PR …` or `→ P4-design v1.0)` do not over-capture. An ASCII full stop is NOT a boundary — the canonical sub-phase grammar (`P2.1`, `P2.1-design`) embeds literal periods — so a trailing sentence period binds to the target and is normalized away by the claim-key stripper in the audit. Unanchored search (pattern-keyword semantics): the stop-set bounds the target token and trailing clause content (e.g. `(PR #1)`) is left unconsumed — the anchors must not be reintroduced.",
299
+ "pattern": "(?:Pending|\\[Pending\\])\\s*(?:→|->)\\s*[^\\s;;,,、()()【】\\[\\]】。—…]+"
300
+ },
301
+ "target": {
302
+ "type": "string",
303
+ "description": "Claim target — a `Done`-style completion token (plan claims) or a `P<n>-design` token (design claims), with trailing closing brackets stripped. A link-form plan cell satisfies its claim via OWN-DOCUMENT href identity (`*-<slug>-<id>.md` / `*-<slug>-<id>-plan.md`), never a literal token match (P4.3 Task 8 #274)."
304
+ }
305
+ }
306
+ },
307
+ "planLinkWord": {
308
+ "type": "string",
309
+ "pattern": "^(?:plan|计划)$",
310
+ "description": "Plan link word — a clause mentioning `plan`/`计划` carries a plan backfill claim (forward: claim ⇒ shipped plan column; reverse: a SHIPPED plan column — `Done`-style or a link-cell, never `[In-flight]`, which is carved out — ⇒ a matching claim exists)."
311
+ },
312
+ "designLinkWord": {
313
+ "type": "string",
314
+ "pattern": "^Design\\s?-?\\s?spec$",
315
+ "description": "Design link word — a clause mentioning `Design spec` carries a design backfill claim (target must be a `P<n>-design` token)."
316
+ },
317
+ "designToken": {
318
+ "type": "string",
319
+ "pattern": "^P\\d+(\\.\\d+)*-design$",
320
+ "description": "Design-spec token — the canonical `P<digits>(.digits)*-design` token a Design spec column carries as its own completion marker and a design claim's target (`P2.1-design` registers under the sub-phase P2.1, never its base P2)."
321
+ },
322
+ "phaseReference": {
323
+ "type": "object",
324
+ "description": "Phase references inside a claim clause — single or ranged (endpoints included), scanned within the EXPLICIT claim window (the span from after the previous claim's target to this claim match), never the whole clause (P4.3 Task 8 #274 — a prose-mentioned phase in the same `;`-clause is a diagnosis hint, not a target).",
325
+ "properties": {
326
+ "single": {
327
+ "type": "string",
328
+ "pattern": "^P\\d+(\\.\\d+)*$",
329
+ "description": "Single phase reference — the canonical `P<digits>(.digits)*` form (`P1`, `P2.1`)."
330
+ },
331
+ "range": {
332
+ "type": "string",
333
+ "pattern": "^P\\d+(\\.\\d+)*\\s*[-–—]\\s*P\\d+(\\.\\d+)*$",
334
+ "description": "Ranged reference over canonical phase ids (`P<digits>(.digits)*`, e.g. `P1–P4` / `P2.1–P2.3` / `P1-P4` / `P1—P4`) joined by `-`/`–`/`—` — expanded to all phases including the endpoints."
335
+ }
336
+ }
337
+ }
338
+ }
339
+ },
340
+ "programCharter": {
341
+ "type": "object",
342
+ "description": "Section 3 — Program charter: goal (1–3 sentences), non-goals, cross-cutting constraints; acceptance criteria / API shapes / tasks excluded (charter only). Claims shrink, they do not inflate — what the program cannot prove it will not claim."
343
+ },
344
+ "documentScope": {
345
+ "type": "object",
346
+ "description": "Section 1 — Document scope: charter discipline — overall approval is not equivalent to any phase started (GATE); deviations update here first (backfill-as-version), then sync to overall."
347
+ },
348
+ "filePaths": {
349
+ "type": "object",
350
+ "description": "Section 2 — File paths table: one program date + feature slug under `docs/osuperpowers/` — overall `specs/YYYY-MM-DD-<feature>-overall.md`, phase spec `specs/YYYY-MM-DD-<feature>-<phase-id>-design.md`, phase plan `plans/YYYY-MM-DD-<feature>-<phase-id>.md` (lowercase phase ids)."
351
+ },
352
+ "boundaryRules": {
353
+ "type": "object",
354
+ "description": "Section 7 — Boundary rules: each phase full brainstorm → plan → dev, shipped before dependents start; requirement changes discovered during a phase MUST feed back to this overall before implementation proceeds (version bump + change-history entry + sync affected phase acceptance/dependency)."
355
+ },
356
+ "maintenance": {
357
+ "type": "object",
358
+ "description": "Section 8 — Maintenance: four tables backfilled per phase; charter only, no task lists — the phase spec carries the detail; strategy shifts / splits feed back immediately."
359
+ }
360
+ }
361
+ }
@@ -0,0 +1,145 @@
1
+ {
2
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
3
+ "$id": "https://oscaner.dev/schemas/cdd/phase-spec.json",
4
+ "title": "Phase design spec document structure",
5
+ "description": "Canonical structure of an osuperpowers phase design spec — one phase's increment of a program; the program-level charter lives in the parent overall (whole-program conventions win on conflict). This schema is the single structure fact for the phase-spec doc type: the artifact header block, the fixed Section 0–5 skeleton (skeleton isomorphism — do not insert sections mid-sequence, each number is one semantic), the unique `### Acceptance criteria` subsection inside Section 2, and the deviations table whose `Overall updated?` column must be `Yes` before review. Authoring agents read the properties + descriptions to draft conforming specs; docContractValidate consumes the same patterns (`**Version**` strictly required, Class-B parent-program lineage).",
6
+ "type": "object",
7
+ "properties": {
8
+ "header": {
9
+ "type": "object",
10
+ "description": "Artifact header block — metadata at the top of the artifact, a bullet block, not a `##` section. The `**Version**` line is STRICTLY required here (the phase-spec Version check); every remaining field is part of the block.",
11
+ "properties": {
12
+ "version": {
13
+ "type": "object",
14
+ "description": "`**Version**` — strictly required line; `- **Version**: vX.Y · YYYY-MM-DD`.",
15
+ "properties": {
16
+ "marker": {
17
+ "type": "string",
18
+ "const": "**Version**",
19
+ "description": "The canonical `**Version**` marker (shared token with the overall; the engine derives its phase-spec version assertion from the same single source)."
20
+ },
21
+ "line": {
22
+ "type": "string",
23
+ "pattern": "^\\s*-?\\s*\\*\\*Version\\*\\*:\\s*v\\d+\\.\\d+",
24
+ "description": "The strictly-required version line; the `v\\d+\\.\\d+` token follows the version-lineage rule (must reference a version the parent overall actually carries when the spec pins one)."
25
+ }
26
+ }
27
+ },
28
+ "status": {
29
+ "type": "object",
30
+ "description": "`**Status**` — the phase-spec status vocabulary.",
31
+ "properties": {
32
+ "states": {
33
+ "type": "array",
34
+ "enum": ["Draft", "Approved", "Plan pending", "Shipped"],
35
+ "description": "Phase-spec status states — Draft / Approved / Plan pending / Shipped."
36
+ }
37
+ }
38
+ },
39
+ "author": {
40
+ "type": "object",
41
+ "description": "`**Author**` — contributor line (`[human] · [harness + model]`); free text, no structural rule."
42
+ },
43
+ "parentProgram": {
44
+ "type": "object",
45
+ "description": "`**Parent program**` — link + version to the parent overall; Class-B lineage check resolves it to an existing `*-overall.md` and requires every `vX.Y` token on the line to be in the parent's lineage (current `**Version:**` ∪ change-history cells).",
46
+ "properties": {
47
+ "linkForm": {
48
+ "type": "string",
49
+ "pattern": "^-?(\\s*)\\*\\*Parent program\\*\\*:?\\s+\\[[^\\]]+\\]\\([^)]+\\)",
50
+ "description": "`- **Parent program**: [<name>-overall.md vX.Y](<path>)` — markdown link to the parent overall doc (`*-overall.md`)."
51
+ }
52
+ }
53
+ },
54
+ "dependsOn": {
55
+ "type": "object",
56
+ "description": "`**Depends on**` — upstream phases + tags (e.g. `P1(shipped · [p1-design v1.1](…))`; informational."
57
+ }
58
+ }
59
+ },
60
+ "sections": {
61
+ "type": "object",
62
+ "description": "The fixed Section 0–5 skeleton — Section 0–5 artifact body, each number one semantic, fixed order (skeleton isomorphism — no mid-sequence insertion; the 'Section N' labels belong to the family skeleton, each artifact section is authored under its literal `## Section N: <name>` heading).",
63
+ "properties": {
64
+ "section0": {
65
+ "type": "object",
66
+ "description": "Section 0 — Incremental warning: the spec commits to exactly one phase; splitting / reordering a phase's work is not a local edit — phase-inventory rows, dependency edges and a change-history row land in the parent overall first (backfill-as-version).",
67
+ "properties": {
68
+ "heading": { "type": "string", "pattern": "^## Section 0: Incremental warning$", "description": "Literal heading `## Section 0: Incremental warning`." }
69
+ }
70
+ },
71
+ "section1": {
72
+ "type": "object",
73
+ "description": "Section 1 — Constraints pointer: does not repeat overall conventions; cross-phase rules belong in the overall (overall wins on conflict).",
74
+ "properties": {
75
+ "heading": { "type": "string", "pattern": "^## Section 1: Constraints pointer$", "description": "Literal heading `## Section 1: Constraints pointer`." }
76
+ }
77
+ },
78
+ "section2": {
79
+ "type": "object",
80
+ "description": "Section 2 — Design body: this phase's increment (approaches, architecture, components, data flow, errors, testing) AND the `### Acceptance criteria` subsection (see acceptanceCriteria).",
81
+ "properties": {
82
+ "heading": { "type": "string", "pattern": "^## Section 2: Design body$", "description": "Literal heading `## Section 2: Design body`." }
83
+ }
84
+ },
85
+ "section3": {
86
+ "type": "object",
87
+ "description": "Section 3 — Deviations from overall: the deviations table (`Overall assumption | Phase decision | Overall updated?`); required when the phase diverges on a cross-phase matter.",
88
+ "properties": {
89
+ "heading": { "type": "string", "pattern": "^## Section 3: Deviations from overall$", "description": "Literal heading `## Section 3: Deviations from overall`." },
90
+ "columns": {
91
+ "type": "array",
92
+ "items": { "type": "string", "enum": ["Overall assumption", "Phase decision", "Overall updated?"], "description": "One deviation-table column name." },
93
+ "description": "Three deviation-table columns; `Overall updated?` must be `Yes` (with version + date, e.g. `Yes — vX.Y · YYYY-MM-DD`) before review — a divergence not fed back to the overall is a backfill violation."
94
+ }
95
+ }
96
+ },
97
+ "section4": {
98
+ "type": "object",
99
+ "description": "Section 4 — Notes for downstream: later-phase scope shifts; a 'later phases will handle this' note that stays here alone is a dead end — downstream writers read the overall, record the shift in the overall's issue / phase / dependency tables and history, keep the note as a pointer.",
100
+ "properties": {
101
+ "heading": { "type": "string", "pattern": "^## Section 4: Notes for downstream$", "description": "Literal heading `## Section 4: Notes for downstream`." }
102
+ }
103
+ },
104
+ "section5": {
105
+ "type": "object",
106
+ "description": "Section 5 — Review: fresh-subagent review passes before user review and writing-plans — baseline = committed tree, Review Convergence (blocker > 0 → fix all findings → re-review; blocker = 0 → fix all findings → done, no re-review).",
107
+ "properties": {
108
+ "heading": { "type": "string", "pattern": "^## Section 5: Review$", "description": "Literal heading `## Section 5: Review`." }
109
+ }
110
+ }
111
+ }
112
+ },
113
+ "acceptanceCriteria": {
114
+ "type": "object",
115
+ "description": "`### Acceptance criteria` — the ONLY subsection, and it lives inside Section 2 (Design body): verifiable completion conditions, each independently testable. An acceptance criterion is a claim: a claim that cannot be mechanically verified on the shipped tree is a paper claim.",
116
+ "properties": {
117
+ "heading": {
118
+ "type": "string",
119
+ "const": "### Acceptance criteria",
120
+ "description": "Literal subsection heading `### Acceptance criteria` — unique: no other subsection exists anywhere in the doc."
121
+ },
122
+ "location": {
123
+ "type": "object",
124
+ "description": "Location rule — the subsection sits inside Section 2 (Design body).",
125
+ "properties": {
126
+ "parent": {
127
+ "type": "string",
128
+ "const": "Section 2 (Design body)",
129
+ "description": "`### Acceptance criteria` is nested directly under `## Section 2: Design body`."
130
+ }
131
+ }
132
+ },
133
+ "entry": {
134
+ "type": "string",
135
+ "pattern": "^- `",
136
+ "description": "Acceptance entries — `- ` code-span-prefixed bullets, each an independently testable condition (e.g. `- artifact X exists at path Y with property Z`)."
137
+ }
138
+ }
139
+ },
140
+ "language": {
141
+ "type": "object",
142
+ "description": "Repo authoring policy applies to the spec prose — specs at docs/osuperpowers/specs/ are internal program docs in the working language (Strategy B), value tokens (phase ids / tags / SHAs / paths) stay locale-neutral."
143
+ }
144
+ }
145
+ }