@openplanr/protocol 0.6.1 → 0.7.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 (58) hide show
  1. package/README.md +10 -0
  2. package/lib/dashboard/closed-json-contract.mjs +99 -109
  3. package/lib/dashboard/operate-experience-audit-display-contract.d.mts +128 -153
  4. package/lib/dashboard/operate-experience-audit-display-contract.mjs +530 -585
  5. package/lib/dashboard/operate-experience-display-contract.d.mts +415 -437
  6. package/lib/dashboard/operate-experience-display-contract.mjs +777 -831
  7. package/lib/dashboard/operate-experience-surface-contract.d.mts +143 -148
  8. package/lib/dashboard/operate-experience-surface-contract.mjs +72 -73
  9. package/lib/dashboard/operate-review-contract.d.mts +7 -14
  10. package/lib/dashboard/operate-review-contract.mjs +46 -42
  11. package/lib/dashboard/operate-review-display-workspace-contract.d.mts +2 -5
  12. package/lib/dashboard/operate-review-display-workspace-contract.mjs +158 -104
  13. package/lib/dashboard/operate-review-payload-safety.mjs +4 -2
  14. package/lib/dashboard/operate-review-workspace-projection-v2.d.mts +47 -33
  15. package/lib/protocol/index.d.ts +2647 -543
  16. package/package.json +1 -1
  17. package/registries/artifact-theme.json +64 -0
  18. package/registries/commands.json +40 -40
  19. package/registries/skills.json +5 -5
  20. package/schemas/v1.14.0/artifact-theme.schema.json +316 -0
  21. package/src/browser-contracts.d.mts +4 -1
  22. package/src/browser-contracts.mjs +16 -5
  23. package/src/canonical-json.d.mts +6 -1
  24. package/src/canonical-json.mjs +100 -22
  25. package/src/compat/live-evidence-v2.mjs +1611 -485
  26. package/src/compat/operate-experience-live-patch.mjs +67 -15
  27. package/src/compat/operating-planning-contracts.mjs +183 -51
  28. package/src/contracts.d.mts +54 -13
  29. package/src/contracts.mjs +635 -343
  30. package/src/design-contracts.mjs +58 -21
  31. package/src/design-handoff-contracts.d.mts +67 -11
  32. package/src/design-handoff-contracts.mjs +236 -119
  33. package/src/design-publication-contracts.mjs +98 -33
  34. package/src/diagram-authoring-contracts.d.mts +422 -78
  35. package/src/diagram-authoring-contracts.mjs +1715 -335
  36. package/src/diagram-contracts.d.mts +4 -1
  37. package/src/diagram-contracts.mjs +16 -4
  38. package/src/enterprise-contracts.d.mts +211 -46
  39. package/src/enterprise-contracts.mjs +738 -184
  40. package/src/errors.mjs +4 -0
  41. package/src/generated/canonical-registries.mjs +45 -45
  42. package/src/index.d.mts +8 -8
  43. package/src/index.mjs +36 -20
  44. package/src/json-schema.d.mts +21 -6
  45. package/src/json-schema.mjs +66 -18
  46. package/src/planning-contracts.d.mts +8 -2
  47. package/src/planning-contracts.mjs +33 -7
  48. package/src/registries.d.mts +11 -3
  49. package/src/registries.mjs +369 -87
  50. package/src/review-experience-contracts.d.mts +7 -2
  51. package/src/review-experience-contracts.mjs +198 -49
  52. package/src/semver.mjs +5 -1
  53. package/src/skill-source-contracts.d.mts +36 -16
  54. package/src/skill-source-contracts.mjs +25 -6
  55. package/src/task-contracts.d.mts +13 -3
  56. package/src/task-contracts.mjs +181 -40
  57. package/src/workspace-contracts.d.mts +38 -10
  58. package/src/workspace-contracts.mjs +147 -33
@@ -1,52 +1,140 @@
1
+ // @ts-check
1
2
  import { verifyDocumentDigest } from './canonical-json.mjs';
2
- import { CANONICAL_REGISTRIES } from './generated/canonical-registries.mjs';
3
3
  import { PROTOCOL_ERROR_CODES, ProtocolError } from './errors.mjs';
4
+ import { CANONICAL_REGISTRIES } from './generated/canonical-registries.mjs';
4
5
 
6
+ /** @returns {never} */
5
7
  const fail = (code, message, details) => {
6
8
  throw new ProtocolError(code, message, '', details);
7
9
  };
8
10
  const equal = (left, right) => JSON.stringify(left) === JSON.stringify(right);
9
11
 
10
12
  function assertDocument(name, value, kind) {
11
- if (!value || typeof value !== 'object' || Array.isArray(value) || value.kind !== kind
12
- || value.protocolVersion !== '1.5.0' || value.digestAlgorithm !== 'sha256'
13
- || value.canonicalization !== 'rfc8785' || !verifyDocumentDigest(value)) {
14
- fail(PROTOCOL_ERROR_CODES.DOCUMENT_INVALID, `${name} is not a digest-bound Protocol 1.5 document.`, { name });
13
+ if (
14
+ !value ||
15
+ typeof value !== 'object' ||
16
+ Array.isArray(value) ||
17
+ value.kind !== kind ||
18
+ value.protocolVersion !== '1.5.0' ||
19
+ value.digestAlgorithm !== 'sha256' ||
20
+ value.canonicalization !== 'rfc8785' ||
21
+ !verifyDocumentDigest(value)
22
+ ) {
23
+ fail(
24
+ PROTOCOL_ERROR_CODES.DOCUMENT_INVALID,
25
+ `${name} is not a digest-bound Protocol 1.5 document.`,
26
+ { name },
27
+ );
15
28
  }
16
29
  }
17
30
 
18
31
  function assertSortedUnique(values, key, name) {
19
32
  const keys = values.map((value) => value[key]);
20
- if (new Set(keys).size !== keys.length) fail(PROTOCOL_ERROR_CODES.DUPLICATE_ID, `${name} contains duplicate ${key} values.`, { keys });
33
+ if (new Set(keys).size !== keys.length)
34
+ fail(PROTOCOL_ERROR_CODES.DUPLICATE_ID, `${name} contains duplicate ${key} values.`, { keys });
21
35
  const sorted = [...keys].sort();
22
- if (!equal(keys, sorted)) fail(PROTOCOL_ERROR_CODES.SORT_ORDER_INVALID, `${name} must be sorted by ${key}.`, { keys, sorted });
36
+ if (!equal(keys, sorted))
37
+ fail(PROTOCOL_ERROR_CODES.SORT_ORDER_INVALID, `${name} must be sorted by ${key}.`, {
38
+ keys,
39
+ sorted,
40
+ });
23
41
  }
24
42
 
25
43
  const EXPECTED_ROLES = Object.freeze({
26
- 'planr-backend': ['backend-agent', 'dev', 'conditional', 'implementation-high', 'implementation-result'],
27
- 'planr-database': ['db-agent', 'po-preflight', 'conditional', 'analysis-high', 'task-output-manifest'],
44
+ 'planr-backend': [
45
+ 'backend-agent',
46
+ 'dev',
47
+ 'conditional',
48
+ 'implementation-high',
49
+ 'implementation-result',
50
+ ],
51
+ 'planr-database': [
52
+ 'db-agent',
53
+ 'po-preflight',
54
+ 'conditional',
55
+ 'analysis-high',
56
+ 'task-output-manifest',
57
+ ],
28
58
  'planr-designer': ['designer-agent', 'po', 'conditional', 'analysis-high', 'designer-output'],
29
- 'planr-devops': ['devops-agent', 'post-build', 'conditional', 'analysis-high', 'task-output-manifest'],
30
- 'planr-documentation': ['doc-gen-agent', 'post-build', 'conditional', 'analysis-high', 'task-output-manifest'],
31
- 'planr-entity-scaffold': ['entity-scaffold-agent', 'po-preflight', 'manual', 'analysis-high', 'task-output-manifest'],
32
- 'planr-frontend': ['frontend-agent', 'dev', 'conditional', 'implementation-high', 'implementation-result'],
59
+ 'planr-devops': [
60
+ 'devops-agent',
61
+ 'post-build',
62
+ 'conditional',
63
+ 'analysis-high',
64
+ 'task-output-manifest',
65
+ ],
66
+ 'planr-documentation': [
67
+ 'doc-gen-agent',
68
+ 'post-build',
69
+ 'conditional',
70
+ 'analysis-high',
71
+ 'task-output-manifest',
72
+ ],
73
+ 'planr-entity-scaffold': [
74
+ 'entity-scaffold-agent',
75
+ 'po-preflight',
76
+ 'manual',
77
+ 'analysis-high',
78
+ 'task-output-manifest',
79
+ ],
80
+ 'planr-frontend': [
81
+ 'frontend-agent',
82
+ 'dev',
83
+ 'conditional',
84
+ 'implementation-high',
85
+ 'implementation-result',
86
+ ],
33
87
  'planr-qa': ['qa-agent', 'qa', 'always', 'read-only-qa', 'task-output-manifest'],
34
- 'planr-specification': ['specification-agent', 'po', 'always', 'analysis-high', 'specification-output'],
88
+ 'planr-specification': [
89
+ 'specification-agent',
90
+ 'po',
91
+ 'always',
92
+ 'analysis-high',
93
+ 'specification-output',
94
+ ],
35
95
  });
36
96
 
37
97
  const EXPECTED_TASK_KINDS = Object.freeze({
38
- backend: 'planr-backend', database: 'planr-database', devops: 'planr-devops', documentation: 'planr-documentation',
39
- 'entity-scaffold': 'planr-entity-scaffold', frontend: 'planr-frontend', qa: 'planr-qa',
98
+ backend: 'planr-backend',
99
+ database: 'planr-database',
100
+ devops: 'planr-devops',
101
+ documentation: 'planr-documentation',
102
+ 'entity-scaffold': 'planr-entity-scaffold',
103
+ frontend: 'planr-frontend',
104
+ qa: 'planr-qa',
40
105
  });
41
106
 
42
107
  const EXPECTED_SKILLS = Object.freeze([
43
- 'planr-artifact', 'planr-browser-qa', 'planr-ceo-review', 'planr-chair-review', 'planr-challenger-review', 'planr-cmo-review',
44
- 'planr-coo-review', 'planr-cpo-review', 'planr-cto-review', 'planr-dashboard', 'planr-design', 'planr-design-loop',
45
- 'planr-design-review', 'planr-diagram', 'planr-doctor', 'planr-investigate', 'planr-land', 'planr-openplanr', 'planr-operate',
108
+ 'planr-artifact',
109
+ 'planr-browser-qa',
110
+ 'planr-ceo-review',
111
+ 'planr-chair-review',
112
+ 'planr-challenger-review',
113
+ 'planr-cmo-review',
114
+ 'planr-coo-review',
115
+ 'planr-cpo-review',
116
+ 'planr-cto-review',
117
+ 'planr-dashboard',
118
+ 'planr-design',
119
+ 'planr-design-loop',
120
+ 'planr-design-review',
121
+ 'planr-diagram',
122
+ 'planr-doctor',
123
+ 'planr-investigate',
124
+ 'planr-land',
125
+ 'planr-openplanr',
126
+ 'planr-operate',
46
127
  'planr-plan',
47
- 'planr-plan-review', 'planr-release', 'planr-ship', 'planr-spec', 'planr-sprint', 'planr-status', 'planr-sync',
128
+ 'planr-plan-review',
129
+ 'planr-release',
130
+ 'planr-ship',
131
+ 'planr-spec',
132
+ 'planr-sprint',
133
+ 'planr-status',
134
+ 'planr-sync',
48
135
  ]);
49
136
 
137
+ /** @returns {ReturnType<typeof import('./registries.d.mts').validateCanonicalRegistries>} */
50
138
  export function validateCanonicalRegistries(registries = CANONICAL_REGISTRIES) {
51
139
  const roles = registries['roles.json'];
52
140
  const taskKinds = registries['task-kinds.json'];
@@ -63,121 +151,266 @@ export function validateCanonicalRegistries(registries = CANONICAL_REGISTRIES) {
63
151
  assertDocument('outputs.json', outputs, 'output-catalog');
64
152
  assertDocument('output-paths.json', outputPaths, 'output-path-catalog');
65
153
 
66
- if (roles.roles.length !== 9) fail(PROTOCOL_ERROR_CODES.REGISTRY_INVALID, 'Protocol 0.1 requires exactly nine canonical roles.');
154
+ if (roles.roles.length !== 9)
155
+ fail(
156
+ PROTOCOL_ERROR_CODES.REGISTRY_INVALID,
157
+ 'Protocol 0.1 requires exactly nine canonical roles.',
158
+ );
67
159
  assertSortedUnique(roles.roles, 'roleId', 'roles.json');
68
160
  const aliases = new Set();
69
161
  const canonicalRoleIds = new Set(roles.roles.map(({ roleId }) => roleId));
70
162
  for (const role of roles.roles) {
71
- if (role.legacyAliases.length !== 1 || aliases.has(role.legacyAliases[0].id) || canonicalRoleIds.has(role.legacyAliases[0].id)) {
163
+ if (
164
+ role.legacyAliases.length !== 1 ||
165
+ aliases.has(role.legacyAliases[0].id) ||
166
+ canonicalRoleIds.has(role.legacyAliases[0].id)
167
+ ) {
72
168
  fail(PROTOCOL_ERROR_CODES.DUPLICATE_ID, `Role alias collision for ${role.roleId}.`);
73
169
  }
74
170
  aliases.add(role.legacyAliases[0].id);
75
171
  const expected = EXPECTED_ROLES[role.roleId];
76
- if (!expected || !equal([
77
- role.legacyAliases[0]?.id, role.phase, role.activation, role.capabilityTier, role.outputContracts[0]?.id,
78
- ], expected)) {
79
- fail(PROTOCOL_ERROR_CODES.REGISTRY_INVALID, `Role compatibility mapping drifted for ${role.roleId}.`);
172
+ if (
173
+ !expected ||
174
+ !equal(
175
+ [
176
+ role.legacyAliases[0]?.id,
177
+ role.phase,
178
+ role.activation,
179
+ role.capabilityTier,
180
+ role.outputContracts[0]?.id,
181
+ ],
182
+ expected,
183
+ )
184
+ ) {
185
+ fail(
186
+ PROTOCOL_ERROR_CODES.REGISTRY_INVALID,
187
+ `Role compatibility mapping drifted for ${role.roleId}.`,
188
+ );
80
189
  }
81
190
  if (role.adapterMappings.length < 3 || role.qaCoverage.length < 1) {
82
- fail(PROTOCOL_ERROR_CODES.REGISTRY_INVALID, `Role ${role.roleId} lacks adapter parity or QA coverage.`);
191
+ fail(
192
+ PROTOCOL_ERROR_CODES.REGISTRY_INVALID,
193
+ `Role ${role.roleId} lacks adapter parity or QA coverage.`,
194
+ );
83
195
  }
84
196
  }
85
197
  const qa = roles.roles.find(({ roleId }) => roleId === 'planr-qa');
86
198
  const database = roles.roles.find(({ roleId }) => roleId === 'planr-database');
87
199
  const devops = roles.roles.find(({ roleId }) => roleId === 'planr-devops');
88
- if (qa.writeBoundary.repositoryAccess !== 'read-only' || qa.writeBoundary.allowedOutputClasses.includes('C')) {
200
+ if (
201
+ qa.writeBoundary.repositoryAccess !== 'read-only' ||
202
+ qa.writeBoundary.allowedOutputClasses.includes('C')
203
+ ) {
89
204
  fail(PROTOCOL_ERROR_CODES.REGISTRY_INVALID, 'QA must remain read-only.');
90
205
  }
91
- if (database.writeBoundary.externalDataAccess !== 'read-only' || !database.writeBoundary.forbiddenEffects.includes('database-mutation')) {
92
- fail(PROTOCOL_ERROR_CODES.REGISTRY_INVALID, 'Database inspection must remain externally read-only.');
206
+ if (
207
+ database.writeBoundary.externalDataAccess !== 'read-only' ||
208
+ !database.writeBoundary.forbiddenEffects.includes('database-mutation')
209
+ ) {
210
+ fail(
211
+ PROTOCOL_ERROR_CODES.REGISTRY_INVALID,
212
+ 'Database inspection must remain externally read-only.',
213
+ );
93
214
  }
94
215
  if (!devops.writeBoundary.forbiddenEffects.includes('deploy')) {
95
- fail(PROTOCOL_ERROR_CODES.REGISTRY_INVALID, 'DevOps configuration authority must forbid deploy.');
216
+ fail(
217
+ PROTOCOL_ERROR_CODES.REGISTRY_INVALID,
218
+ 'DevOps configuration authority must forbid deploy.',
219
+ );
96
220
  }
97
221
 
98
222
  if (taskKinds.roleRegistryDigest !== roles.documentDigest || taskKinds.bindings.length !== 7) {
99
- fail(PROTOCOL_ERROR_CODES.REFERENCE_INVALID, 'Task-kind registry is not bound to the exact role registry.');
223
+ fail(
224
+ PROTOCOL_ERROR_CODES.REFERENCE_INVALID,
225
+ 'Task-kind registry is not bound to the exact role registry.',
226
+ );
100
227
  }
101
228
  assertSortedUnique(taskKinds.bindings, 'taskKind', 'task-kinds.json bindings');
102
229
  for (const binding of taskKinds.bindings) {
103
- if (EXPECTED_TASK_KINDS[binding.taskKind] !== binding.roleId || !canonicalRoleIds.has(binding.roleId)) {
104
- fail(PROTOCOL_ERROR_CODES.REFERENCE_INVALID, `Task kind ${binding.taskKind} has a mismatched role binding.`);
230
+ if (
231
+ EXPECTED_TASK_KINDS[binding.taskKind] !== binding.roleId ||
232
+ !canonicalRoleIds.has(binding.roleId)
233
+ ) {
234
+ fail(
235
+ PROTOCOL_ERROR_CODES.REFERENCE_INVALID,
236
+ `Task kind ${binding.taskKind} has a mismatched role binding.`,
237
+ );
105
238
  }
106
239
  const expectedOutput = ['backend', 'frontend'].includes(binding.taskKind)
107
240
  ? 'implementation-result'
108
241
  : 'task-output-manifest';
109
242
  if (!equal(binding.outputContracts, [{ id: expectedOutput, version: '1.0.0' }])) {
110
- fail(PROTOCOL_ERROR_CODES.REFERENCE_INVALID, `Task kind ${binding.taskKind} has a mismatched output contract.`);
243
+ fail(
244
+ PROTOCOL_ERROR_CODES.REFERENCE_INVALID,
245
+ `Task kind ${binding.taskKind} has a mismatched output contract.`,
246
+ );
111
247
  }
112
248
  }
113
- if (!equal(taskKinds.legacyMappings.map(({ legacyType, legacyAgent, taskKind, precedence }) => [legacyType, legacyAgent, taskKind, precedence]), [
114
- ['UI', 'frontend-agent', 'frontend', 1], ['Tech', 'db-agent', 'database', 2],
115
- ['Tech', 'backend-agent', 'backend', 3], ['Tech', null, 'backend', 4],
116
- ])) fail(PROTOCOL_ERROR_CODES.REGISTRY_INVALID, 'Legacy UI/Tech routing precedence drifted.');
249
+ if (
250
+ !equal(
251
+ taskKinds.legacyMappings.map(({ legacyType, legacyAgent, taskKind, precedence }) => [
252
+ legacyType,
253
+ legacyAgent,
254
+ taskKind,
255
+ precedence,
256
+ ]),
257
+ [
258
+ ['UI', 'frontend-agent', 'frontend', 1],
259
+ ['Tech', 'db-agent', 'database', 2],
260
+ ['Tech', 'backend-agent', 'backend', 3],
261
+ ['Tech', null, 'backend', 4],
262
+ ],
263
+ )
264
+ )
265
+ fail(PROTOCOL_ERROR_CODES.REGISTRY_INVALID, 'Legacy UI/Tech routing precedence drifted.');
117
266
 
118
267
  assertSortedUnique(rules.rules, 'ruleId', 'rules.json');
119
- if (!equal(rules.rules.map(({ ruleId }) => ruleId), ['R1', 'R10', 'R2', 'R3', 'R4', 'R5', 'R6', 'R7', 'R8', 'R9'].sort())) {
268
+ if (
269
+ !equal(
270
+ rules.rules.map(({ ruleId }) => ruleId),
271
+ ['R1', 'R10', 'R2', 'R3', 'R4', 'R5', 'R6', 'R7', 'R8', 'R9'].sort(),
272
+ )
273
+ ) {
120
274
  fail(PROTOCOL_ERROR_CODES.REGISTRY_INVALID, 'Rule catalog must contain exact R1-R10.');
121
275
  }
122
- if (rules.rules.some((rule) => !rule.enforcementPoints.length || !rule.testRefs.length || !rule.citedBy.length)) {
123
- fail(PROTOCOL_ERROR_CODES.REGISTRY_INVALID, 'Every rule requires enforcement, tests, and citations.');
276
+ if (
277
+ rules.rules.some(
278
+ (rule) => !rule.enforcementPoints.length || !rule.testRefs.length || !rule.citedBy.length,
279
+ )
280
+ ) {
281
+ fail(
282
+ PROTOCOL_ERROR_CODES.REGISTRY_INVALID,
283
+ 'Every rule requires enforcement, tests, and citations.',
284
+ );
124
285
  }
125
286
 
126
287
  const inventory = commands.inventory;
127
- if (inventory.rootCommandModules !== 39 || inventory.rootCommandSlugs.length !== 39
128
- || inventory.pipelineMachineLeaves !== 31 || inventory.pipelineMachineGrammar.length !== 31
129
- || inventory.frozenClaudeDocuments !== 8 || inventory.frozenClaudeSlugs.length !== 8) {
288
+ if (
289
+ inventory.rootCommandModules !== 39 ||
290
+ inventory.rootCommandSlugs.length !== 39 ||
291
+ inventory.pipelineMachineLeaves !== 31 ||
292
+ inventory.pipelineMachineGrammar.length !== 31 ||
293
+ inventory.frozenClaudeDocuments !== 8 ||
294
+ inventory.frozenClaudeSlugs.length !== 8
295
+ ) {
130
296
  fail(PROTOCOL_ERROR_CODES.REGISTRY_INVALID, 'Command inventory floors drifted.');
131
297
  }
132
298
  assertSortedUnique(commands.commands, 'commandId', 'commands.json');
133
299
  const grammar = commands.commands.map(({ argv }) => JSON.stringify(argv));
134
- if (new Set(grammar).size !== grammar.length) fail(PROTOCOL_ERROR_CODES.DUPLICATE_ID, 'Command grammar contains duplicate argv entries.');
300
+ if (new Set(grammar).size !== grammar.length)
301
+ fail(PROTOCOL_ERROR_CODES.DUPLICATE_ID, 'Command grammar contains duplicate argv entries.');
135
302
  if (commands.commands.some(({ argv }) => argv[0] === 'pipeline' && argv[1] === 'operate')) {
136
- fail(PROTOCOL_ERROR_CODES.REGISTRY_INVALID, 'Retired pipeline Operate grammar became callable.');
303
+ fail(
304
+ PROTOCOL_ERROR_CODES.REGISTRY_INVALID,
305
+ 'Retired pipeline Operate grammar became callable.',
306
+ );
137
307
  }
138
- if (!commands.commands.some(({ argv, lifecycle }) => argv[0] === 'operate' && lifecycle === 'active')
139
- || !commands.negativeContracts.some(({ forbiddenArgvPrefix }) => equal(forbiddenArgvPrefix, ['pipeline', 'operate']))) {
140
- fail(PROTOCOL_ERROR_CODES.REGISTRY_INVALID, 'Operate facade/retirement negative contract drifted.');
308
+ if (
309
+ !commands.commands.some(
310
+ ({ argv, lifecycle }) => argv[0] === 'operate' && lifecycle === 'active',
311
+ ) ||
312
+ !commands.negativeContracts.some(({ forbiddenArgvPrefix }) =>
313
+ equal(forbiddenArgvPrefix, ['pipeline', 'operate']),
314
+ )
315
+ ) {
316
+ fail(
317
+ PROTOCOL_ERROR_CODES.REGISTRY_INVALID,
318
+ 'Operate facade/retirement negative contract drifted.',
319
+ );
141
320
  }
142
321
 
143
322
  assertSortedUnique(skills.skills, 'skillId', 'skills.json');
144
323
  const skillIds = skills.skills.map(({ skillId }) => skillId);
145
324
  if (!equal(skillIds, EXPECTED_SKILLS)) {
146
- fail(PROTOCOL_ERROR_CODES.REGISTRY_INVALID, 'Canonical skill membership differs from the active source registry.');
325
+ fail(
326
+ PROTOCOL_ERROR_CODES.REGISTRY_INVALID,
327
+ 'Canonical skill membership differs from the active source registry.',
328
+ );
147
329
  }
148
- if (skillIds.some((id) => canonicalRoleIds.has(id)) || skills.skills.some((skill) => skill.hosts.length < 3 || !skill.certificationRefs.length)) {
149
- fail(PROTOCOL_ERROR_CODES.DUPLICATE_ID, 'Skill/role IDs collide or a skill lacks host/certification parity.');
330
+ if (
331
+ skillIds.some((id) => canonicalRoleIds.has(id)) ||
332
+ skills.skills.some((skill) => skill.hosts.length < 3 || !skill.certificationRefs.length)
333
+ ) {
334
+ fail(
335
+ PROTOCOL_ERROR_CODES.DUPLICATE_ID,
336
+ 'Skill/role IDs collide or a skill lacks host/certification parity.',
337
+ );
150
338
  }
151
339
  const ship = skills.skills.find(({ skillId }) => skillId === 'planr-ship');
152
340
  if (!equal(ship?.contracts?.outputs, [{ id: 'implementation-result', version: '1.0.0' }])) {
153
- fail(PROTOCOL_ERROR_CODES.REFERENCE_INVALID, 'Planr Ship must produce the canonical implementation result.');
341
+ fail(
342
+ PROTOCOL_ERROR_CODES.REFERENCE_INVALID,
343
+ 'Planr Ship must produce the canonical implementation result.',
344
+ );
154
345
  }
155
346
  const aliasIds = skills.compatibilityAliases.map(({ aliasId }) => aliasId).sort();
156
347
  if (aliasIds.length !== 0) {
157
- fail(PROTOCOL_ERROR_CODES.REGISTRY_INVALID, 'Protocol 1.8 canonical skills must not expose compatibility aliases.');
348
+ fail(
349
+ PROTOCOL_ERROR_CODES.REGISTRY_INVALID,
350
+ 'Protocol 1.8 canonical skills must not expose compatibility aliases.',
351
+ );
158
352
  }
159
- for (const command of commands.commands.filter(({ surface }) => surface === 'frozen-host-alias')) {
160
- if (!skillIds.includes(command.skillId)) fail(PROTOCOL_ERROR_CODES.REFERENCE_INVALID, `Frozen command ${command.commandId} has no canonical skill.`);
353
+ for (const command of commands.commands.filter(
354
+ ({ surface }) => surface === 'frozen-host-alias',
355
+ )) {
356
+ if (!skillIds.includes(command.skillId))
357
+ fail(
358
+ PROTOCOL_ERROR_CODES.REFERENCE_INVALID,
359
+ `Frozen command ${command.commandId} has no canonical skill.`,
360
+ );
161
361
  }
162
362
 
163
363
  assertSortedUnique(outputs.outputs, 'outputId', 'outputs.json');
164
- if (!['A', 'B', 'C', 'D'].every((outputClass) => outputs.outputs.some((output) => output.outputClass === outputClass))) {
364
+ if (
365
+ !['A', 'B', 'C', 'D'].every((outputClass) =>
366
+ outputs.outputs.some((output) => output.outputClass === outputClass),
367
+ )
368
+ ) {
165
369
  fail(PROTOCOL_ERROR_CODES.REGISTRY_INVALID, 'Output catalog must cover Classes A-D.');
166
370
  }
167
- if (outputs.outputs.some((output) => !output.generator || !output.validator || !output.compatibilityReaders.length || !output.testRefs.length)) {
168
- fail(PROTOCOL_ERROR_CODES.REGISTRY_INVALID, 'Every output requires generator, validator, reader, and test custody.');
371
+ if (
372
+ outputs.outputs.some(
373
+ (output) =>
374
+ !output.generator ||
375
+ !output.validator ||
376
+ !output.compatibilityReaders.length ||
377
+ !output.testRefs.length,
378
+ )
379
+ ) {
380
+ fail(
381
+ PROTOCOL_ERROR_CODES.REGISTRY_INVALID,
382
+ 'Every output requires generator, validator, reader, and test custody.',
383
+ );
169
384
  }
170
- const modeAwarePlanningIds = ['gherkin-feature', 'professional-specification', 'task', 'user-story'];
385
+ const modeAwarePlanningIds = [
386
+ 'gherkin-feature',
387
+ 'professional-specification',
388
+ 'task',
389
+ 'user-story',
390
+ ];
171
391
  assertSortedUnique(outputPaths.outputs, 'outputId', 'output-paths.json');
172
- if (outputPaths.outputCatalogDigest !== outputs.documentDigest
173
- || !equal(outputPaths.outputs.map(({ outputId }) => outputId), modeAwarePlanningIds)) {
174
- fail(PROTOCOL_ERROR_CODES.REFERENCE_INVALID, 'Project-mode paths must bind the exact output catalog and complete planning output set.');
392
+ if (
393
+ outputPaths.outputCatalogDigest !== outputs.documentDigest ||
394
+ !equal(
395
+ outputPaths.outputs.map(({ outputId }) => outputId),
396
+ modeAwarePlanningIds,
397
+ )
398
+ ) {
399
+ fail(
400
+ PROTOCOL_ERROR_CODES.REFERENCE_INVALID,
401
+ 'Project-mode paths must bind the exact output catalog and complete planning output set.',
402
+ );
175
403
  }
176
404
  for (const outputPath of outputPaths.outputs) {
177
405
  const output = outputs.outputs.find(({ outputId }) => outputId === outputPath.outputId);
178
- if (outputPath.pathTemplates.default !== output?.pathTemplate
179
- || !outputPath.pathTemplates['spec-driven']) {
180
- fail(PROTOCOL_ERROR_CODES.REGISTRY_INVALID, `Output ${outputPath.outputId} has an invalid project-mode path contract.`);
406
+ if (
407
+ outputPath.pathTemplates.default !== output?.pathTemplate ||
408
+ !outputPath.pathTemplates['spec-driven']
409
+ ) {
410
+ fail(
411
+ PROTOCOL_ERROR_CODES.REGISTRY_INVALID,
412
+ `Output ${outputPath.outputId} has an invalid project-mode path contract.`,
413
+ );
181
414
  }
182
415
  }
183
416
  return true;
@@ -185,78 +418,127 @@ export function validateCanonicalRegistries(registries = CANONICAL_REGISTRIES) {
185
418
 
186
419
  validateCanonicalRegistries();
187
420
 
188
- const roleIndex = new Map(CANONICAL_REGISTRIES['roles.json'].roles.map((role) => [role.roleId, role]));
189
- const aliasIndex = new Map(CANONICAL_REGISTRIES['roles.json'].roles.flatMap((role) => role.legacyAliases.map(({ id }) => [id, role])));
190
- const taskKindIndex = new Map(CANONICAL_REGISTRIES['task-kinds.json'].bindings.map((binding) => [binding.taskKind, binding]));
421
+ const roleIndex = new Map(
422
+ CANONICAL_REGISTRIES['roles.json'].roles.map((role) => [role.roleId, role]),
423
+ );
424
+ const aliasIndex = new Map(
425
+ CANONICAL_REGISTRIES['roles.json'].roles.flatMap((role) =>
426
+ role.legacyAliases.map(({ id }) => [id, role]),
427
+ ),
428
+ );
429
+ const taskKindIndex = new Map(
430
+ CANONICAL_REGISTRIES['task-kinds.json'].bindings.map((binding) => [binding.taskKind, binding]),
431
+ );
191
432
 
192
433
  export { CANONICAL_REGISTRIES };
193
434
 
435
+ /** @type {typeof import('./registries.d.mts').getCanonicalRegistry} */
194
436
  export function getCanonicalRegistry(name) {
195
437
  const value = CANONICAL_REGISTRIES[name];
196
438
  if (!value) fail(PROTOCOL_ERROR_CODES.ASSET_NOT_FOUND, `Unknown canonical registry: ${name}`);
197
439
  return value;
198
440
  }
199
441
 
442
+ /** @type {typeof import('./registries.d.mts').getRole} */
200
443
  export function getRole(roleId) {
201
444
  const role = roleIndex.get(roleId);
202
445
  if (!role) fail(PROTOCOL_ERROR_CODES.REFERENCE_INVALID, `Unknown canonical role: ${roleId}`);
203
446
  return role;
204
447
  }
205
448
 
449
+ /** @type {typeof import('./registries.d.mts').resolveLegacyRoleAlias} */
206
450
  export function resolveLegacyRoleAlias(alias) {
207
451
  return aliasIndex.get(alias) ?? null;
208
452
  }
209
453
 
454
+ /** @type {typeof import('./registries.d.mts').resolveTaskKind} */
210
455
  export function resolveTaskKind(taskKind) {
211
456
  const binding = taskKindIndex.get(taskKind);
212
457
  if (!binding) fail(PROTOCOL_ERROR_CODES.REFERENCE_INVALID, `Unknown task kind: ${taskKind}`);
213
458
  return binding;
214
459
  }
215
460
 
216
- /** Resolve one output definition from the canonical catalog or a compatible supplied catalog. */
461
+ /**
462
+ * Resolve one output definition from the canonical catalog or a compatible supplied catalog.
463
+ * @returns {ReturnType<typeof import('./registries.d.mts').getOutput>}
464
+ */
217
465
  export function getOutput(outputId, registries = CANONICAL_REGISTRIES) {
218
- const output = registries['outputs.json']?.outputs?.find((candidate) => candidate.outputId === outputId);
466
+ const output = registries['outputs.json']?.outputs?.find(
467
+ (candidate) => candidate.outputId === outputId,
468
+ );
219
469
  if (!output) fail(PROTOCOL_ERROR_CODES.REFERENCE_INVALID, `Unknown output: ${outputId}`);
220
470
  return output;
221
471
  }
222
472
 
223
- /** Select the canonical template for one project mode while preserving legacy catalog fallback. */
224
- export function getOutputPathTemplate(outputId, projectMode = 'default', registries = CANONICAL_REGISTRIES) {
473
+ /**
474
+ * Select the canonical template for one project mode while preserving legacy catalog fallback.
475
+ * @returns {ReturnType<typeof import('./registries.d.mts').getOutputPathTemplate>}
476
+ */
477
+ export function getOutputPathTemplate(
478
+ outputId,
479
+ projectMode = 'default',
480
+ registries = CANONICAL_REGISTRIES,
481
+ ) {
225
482
  if (projectMode !== 'default' && projectMode !== 'spec-driven') {
226
483
  fail(PROTOCOL_ERROR_CODES.REFERENCE_INVALID, `Unknown project mode: ${projectMode}`);
227
484
  }
228
485
  const output = getOutput(outputId, registries);
229
- const outputPath = registries['output-paths.json']?.outputs?.find((candidate) => candidate.outputId === outputId);
486
+ const outputPath = registries['output-paths.json']?.outputs?.find(
487
+ (candidate) => candidate.outputId === outputId,
488
+ );
230
489
  return outputPath?.pathTemplates?.[projectMode] ?? output.pathTemplate;
231
490
  }
232
491
 
233
492
  const PATH_TOKEN = /\{([A-Za-z][A-Za-z0-9]*)\}/gu;
234
- const SAFE_RELATIVE_PATH = /^(?!\/)(?![A-Za-z]:)(?!.*\\)(?!.*(?:^|\/)\.{1,2}(?:\/|$))(?!.*\/\/).+$/u;
493
+ const SAFE_RELATIVE_PATH =
494
+ /^(?!\/)(?![A-Za-z]:)(?!.*\\)(?!.*(?:^|\/)\.{1,2}(?:\/|$))(?!.*\/\/).+$/u;
235
495
  const MAX_RELATIVE_PATH_LENGTH = 1024;
236
496
 
237
- /** Resolve one catalog path with explicit mode and named template arguments. */
497
+ /**
498
+ * Resolve one catalog path with explicit mode and named template arguments.
499
+ * @returns {ReturnType<typeof import('./registries.d.mts').resolveOutputPath>}
500
+ */
238
501
  export function resolveOutputPath(outputId, options = {}, registries = CANONICAL_REGISTRIES) {
239
502
  const { projectMode = 'default', pathArguments = {} } = options;
240
503
  const template = getOutputPathTemplate(outputId, projectMode, registries);
241
- const missing = [...new Set([...template.matchAll(PATH_TOKEN)].map((match) => match[1]))]
242
- .filter((name) => typeof pathArguments[name] !== 'string' || pathArguments[name].length === 0);
504
+ const missing = [...new Set([...template.matchAll(PATH_TOKEN)].map((match) => match[1]))].filter(
505
+ (name) => typeof pathArguments[name] !== 'string' || pathArguments[name].length === 0,
506
+ );
243
507
  if (missing.length > 0) {
244
- fail(PROTOCOL_ERROR_CODES.REFERENCE_INVALID, `Output ${outputId} path is missing arguments: ${missing.join(', ')}.`, { outputId, projectMode, missing });
508
+ fail(
509
+ PROTOCOL_ERROR_CODES.REFERENCE_INVALID,
510
+ `Output ${outputId} path is missing arguments: ${missing.join(', ')}.`,
511
+ { outputId, projectMode, missing },
512
+ );
245
513
  }
246
514
  const resolved = template.replace(PATH_TOKEN, (_token, name) => pathArguments[name]);
247
- if (resolved.length > MAX_RELATIVE_PATH_LENGTH
248
- || !SAFE_RELATIVE_PATH.test(resolved)
249
- || /[\u0000\r\n]/u.test(resolved)) {
250
- fail(PROTOCOL_ERROR_CODES.REFERENCE_INVALID, `Output ${outputId} resolved to an invalid relative path.`, { outputId, projectMode });
515
+ if (
516
+ resolved.length > MAX_RELATIVE_PATH_LENGTH ||
517
+ !SAFE_RELATIVE_PATH.test(resolved) ||
518
+ /[\u0000\r\n]/u.test(resolved)
519
+ ) {
520
+ fail(
521
+ PROTOCOL_ERROR_CODES.REFERENCE_INVALID,
522
+ `Output ${outputId} resolved to an invalid relative path.`,
523
+ { outputId, projectMode },
524
+ );
251
525
  }
252
526
  return resolved;
253
527
  }
254
528
 
255
- /** Route only explicit legacy fields; prose, filenames, hosts, and models are never evidence. */
529
+ /**
530
+ * Route only explicit legacy fields; prose, filenames, hosts, and models are never evidence.
531
+ * @type {typeof import('./registries.d.mts').routeLegacyTask}
532
+ */
256
533
  export function routeLegacyTask({ legacyType, legacyAgent = null }) {
257
534
  const mappings = CANONICAL_REGISTRIES['task-kinds.json'].legacyMappings;
258
- const exact = mappings.find((mapping) => mapping.legacyType === legacyType && mapping.legacyAgent === legacyAgent);
535
+ const exact = mappings.find(
536
+ (mapping) => mapping.legacyType === legacyType && mapping.legacyAgent === legacyAgent,
537
+ );
259
538
  if (exact) return resolveTaskKind(exact.taskKind);
260
539
  if (legacyType === 'Tech' && legacyAgent === null) return resolveTaskKind('backend');
261
- fail(PROTOCOL_ERROR_CODES.REFERENCE_INVALID, `Legacy routing requires an explicit reviewed mapping for ${legacyType}/${legacyAgent ?? '<none>'}.`);
540
+ fail(
541
+ PROTOCOL_ERROR_CODES.REFERENCE_INVALID,
542
+ `Legacy routing requires an explicit reviewed mapping for ${legacyType}/${legacyAgent ?? '<none>'}.`,
543
+ );
262
544
  }
@@ -5,7 +5,12 @@ export declare const DESIGN_HANDOFF_CONTENT_SCHEMA: Readonly<Record<string, unkn
5
5
  export declare const DESIGN_HANDOFF_SCHEMA: Readonly<Record<string, unknown>>;
6
6
  export declare const DESIGN_REVIEW_METADATA_PAYLOAD_SCHEMA: Readonly<Record<string, unknown>>;
7
7
  export declare const DESIGN_REVIEW_METADATA_PAYLOAD_V11_SCHEMA: Readonly<Record<string, unknown>>;
8
- export declare const REVIEW_EXPERIENCE_SCHEMAS: Readonly<Record<string, Readonly<Record<string, unknown>>>>;
9
- export declare function assertReviewExperience<T>(value: T, contract: Readonly<Record<string, unknown>>): T;
8
+ export declare const REVIEW_EXPERIENCE_SCHEMAS: Readonly<
9
+ Record<string, Readonly<Record<string, unknown>>>
10
+ >;
11
+ export declare function assertReviewExperience<T>(
12
+ value: T,
13
+ contract: Readonly<Record<string, unknown>>,
14
+ ): T;
10
15
  export declare function assertDesignReviewBundle<T>(value: T): T;
11
16
  export declare function assertDesignReviewMetadata<T>(value: T): T;