@openplanr/protocol 0.4.0 → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,92 @@
1
+ export type DesignHandoffDigest = `sha256:${string}`;
2
+ export type DesignHandoffStatus = 'ready' | 'attention' | 'blocked' | 'stale';
3
+ export type DesignHandoffCheckStatus = 'pass' | 'attention' | 'blocked' | 'stale';
4
+ export type DesignHandoffSchema = Readonly<Record<string, unknown>>;
5
+
6
+ export interface DesignHandoffAction { id: string; label: string }
7
+ export interface DesignHandoffEvidenceReference {
8
+ id: string;
9
+ kind: 'design-revision' | 'selected-direction' | 'design-specification' | 'rendered-verification' | 'review-context' | 'review-feedback' | 'review-metadata' | 'review-handoff' | 'screen' | 'frame' | 'component' | 'state' | 'flow' | 'token' | 'review-decision' | 'element-anchor';
10
+ path: string;
11
+ revision?: DesignHandoffDigest;
12
+ digest?: DesignHandoffDigest;
13
+ anchor?: { section: string } | { screenId: string; elementId?: string } | { reviewId: string; pinId: string };
14
+ }
15
+ export interface DesignHandoffReadinessCheck {
16
+ id: string;
17
+ status: DesignHandoffCheckStatus;
18
+ message: string;
19
+ evidenceRefs: string[];
20
+ recoveryAction?: DesignHandoffAction;
21
+ }
22
+ export interface DesignHandoffReadiness {
23
+ kind: 'openplanr-design-handoff-readiness';
24
+ schemaVersion: '1.0.0';
25
+ scope: 'design-originated';
26
+ authority: 'none';
27
+ designId: string;
28
+ sourceRevision: DesignHandoffDigest | null;
29
+ selectedVariant: string | null;
30
+ status: DesignHandoffStatus;
31
+ continuation: { action: 'prepare-plan'; available: boolean };
32
+ checks: DesignHandoffReadinessCheck[];
33
+ evidence: DesignHandoffEvidenceReference[];
34
+ blockers: string[];
35
+ nextActions: DesignHandoffAction[];
36
+ }
37
+ export interface DesignHandoffReadinessAbsence {
38
+ kind: 'openplanr-design-handoff-readiness-absence';
39
+ schemaVersion: '1.0.0';
40
+ status: 'absent';
41
+ reason: 'not-computed' | 'not-applicable' | 'unavailable';
42
+ message: string;
43
+ nextAction: DesignHandoffAction;
44
+ }
45
+ export interface DesignImplementationHandoff {
46
+ kind: 'openplanr-design-implementation-handoff';
47
+ schemaVersion: '1.0.0';
48
+ id: string;
49
+ version: number;
50
+ status: 'draft' | 'approved' | 'superseded' | 'revoked';
51
+ authority: 'prepare-plan';
52
+ title: string;
53
+ basis: {
54
+ designId: string;
55
+ sourceRevision: DesignHandoffDigest;
56
+ selectedVariant: string;
57
+ readiness: { status: DesignHandoffStatus; digest: DesignHandoffDigest };
58
+ reviewHandoff: { version: number; contentDigest: DesignHandoffDigest };
59
+ };
60
+ sources: DesignHandoffEvidenceReference[];
61
+ requirements: Array<{ id: string; kind: 'behavior' | 'visual-state' | 'responsive' | 'accessibility' | 'content-data-assumption' | 'constraint' | 'verification-intent'; statement: string; sourceRefs: string[]; verification: string[] }>;
62
+ contentDigest: DesignHandoffDigest;
63
+ markdown: string;
64
+ approval?: { actorId: string; approvedAt: string; contentDigest: DesignHandoffDigest; authority: 'prepare-plan' };
65
+ supersededBy?: { id: string; version: number; contentDigest: DesignHandoffDigest };
66
+ revocation?: { actorId: string; revokedAt: string; reason: string };
67
+ }
68
+ export interface DesignPlanningLineage {
69
+ kind: 'openplanr-design-planning-lineage';
70
+ schemaVersion: '1.0.0';
71
+ handoff: { id: string; version: number; contentDigest: DesignHandoffDigest };
72
+ specId: string;
73
+ mappings: Array<{ requirementId: string; acceptanceRefs: Array<{ storyId: string; acceptanceId: string }>; taskIds: string[] }>;
74
+ }
75
+
76
+ export declare const DESIGN_HANDOFF_PROTOCOL_VERSION: '1.11.0';
77
+ export declare const DESIGN_HANDOFF_CONTRACT_VERSION: '1.0.0';
78
+ export declare const DESIGN_HANDOFF_AUTHORITY: 'prepare-plan';
79
+ export declare const DESIGN_HANDOFF_CHECK_IDS: readonly string[];
80
+ export declare const DESIGN_HANDOFF_SOURCE_KINDS: readonly string[];
81
+ export declare const DESIGN_HANDOFF_REQUIREMENT_KINDS: readonly string[];
82
+ export declare const DESIGN_HANDOFF_CONTRACT_FILES: Readonly<Record<string, string>>;
83
+ export declare const DESIGN_HANDOFF_READINESS_SCHEMA: DesignHandoffSchema;
84
+ export declare const DESIGN_IMPLEMENTATION_HANDOFF_SCHEMA: DesignHandoffSchema;
85
+ export declare const DESIGN_PLANNING_LINEAGE_SCHEMA: DesignHandoffSchema;
86
+ export declare const DESIGN_HANDOFF_SCHEMAS: Readonly<Record<string, DesignHandoffSchema>>;
87
+ export declare function isDesignHandoffRelativePath(value: unknown): value is string;
88
+ export declare function assertDesignHandoffContract<T>(value: T, schemaOrName: DesignHandoffSchema | keyof typeof DESIGN_HANDOFF_SCHEMAS): T;
89
+ export declare function assertDesignHandoffReadiness<T extends DesignHandoffReadiness | DesignHandoffReadinessAbsence>(value: T): T;
90
+ export declare function designImplementationHandoffDigest(value: DesignImplementationHandoff): DesignHandoffDigest;
91
+ export declare function assertDesignImplementationHandoff<T extends DesignImplementationHandoff>(value: T): T;
92
+ export declare function assertDesignPlanningLineage<T extends DesignPlanningLineage>(value: T, handoff?: DesignImplementationHandoff): T;
@@ -0,0 +1,338 @@
1
+ import { canonicalizeJson, sha256Hex } from './canonical-json.mjs';
2
+ import { validateJson } from './json-schema.mjs';
3
+
4
+ export const DESIGN_HANDOFF_PROTOCOL_VERSION = '1.11.0';
5
+ export const DESIGN_HANDOFF_CONTRACT_VERSION = '1.0.0';
6
+ export const DESIGN_HANDOFF_AUTHORITY = 'prepare-plan';
7
+
8
+ export const DESIGN_HANDOFF_CHECK_IDS = Object.freeze([
9
+ 'current-revision',
10
+ 'selected-direction',
11
+ 'design-specification',
12
+ 'rendered-verification',
13
+ 'review-freshness',
14
+ 'review-dispositions',
15
+ 'unresolved-blockers',
16
+ 'approved-review-handoff',
17
+ ]);
18
+
19
+ export const DESIGN_HANDOFF_SOURCE_KINDS = Object.freeze([
20
+ 'design-revision',
21
+ 'selected-direction',
22
+ 'design-specification',
23
+ 'rendered-verification',
24
+ 'review-context',
25
+ 'review-feedback',
26
+ 'review-metadata',
27
+ 'review-handoff',
28
+ 'screen',
29
+ 'frame',
30
+ 'component',
31
+ 'state',
32
+ 'flow',
33
+ 'token',
34
+ 'review-decision',
35
+ 'element-anchor',
36
+ ]);
37
+
38
+ export const DESIGN_HANDOFF_REQUIREMENT_KINDS = Object.freeze([
39
+ 'behavior',
40
+ 'visual-state',
41
+ 'responsive',
42
+ 'accessibility',
43
+ 'content-data-assumption',
44
+ 'constraint',
45
+ 'verification-intent',
46
+ ]);
47
+
48
+ export const DESIGN_HANDOFF_CONTRACT_FILES = Object.freeze({
49
+ 'design-handoff-readiness': 'design-handoff-readiness.schema.json',
50
+ 'design-implementation-handoff': 'design-implementation-handoff.schema.json',
51
+ 'design-planning-lineage': 'design-planning-lineage.schema.json',
52
+ });
53
+
54
+ const text = { type: 'string', minLength: 1, maxLength: 16384 };
55
+ const title = { ...text, maxLength: 240 };
56
+ const id = { type: 'string', minLength: 1, maxLength: 160, pattern: '^[A-Za-z0-9][A-Za-z0-9._:-]*$' };
57
+ const digest = { type: 'string', pattern: '^sha256:[a-f0-9]{64}$' };
58
+ const relativePath = { type: 'string', minLength: 1, maxLength: 4096 };
59
+ const timestamp = { type: 'string', format: 'date-time' };
60
+ const list = (items, maxItems = 1000) => ({ type: 'array', items, maxItems });
61
+ const closed = (properties, required = Object.keys(properties)) => ({
62
+ type: 'object', additionalProperties: false, properties, required,
63
+ });
64
+ const contract = (name, body) => ({
65
+ $schema: 'https://json-schema.org/draft/2020-12/schema',
66
+ $id: `https://openplanr.dev/schemas/v1.11.0/${name}.schema.json`,
67
+ 'x-openplanr-contract': { id: name, version: DESIGN_HANDOFF_PROTOCOL_VERSION },
68
+ ...body,
69
+ });
70
+
71
+ const action = closed({ id, label: title });
72
+ const anchor = {
73
+ oneOf: [
74
+ closed({ section: id }),
75
+ closed({ screenId: id }),
76
+ closed({ screenId: id, elementId: id }),
77
+ closed({ reviewId: id, pinId: id }),
78
+ ],
79
+ };
80
+ const evidenceReference = closed({
81
+ id,
82
+ kind: { enum: DESIGN_HANDOFF_SOURCE_KINDS },
83
+ path: relativePath,
84
+ revision: digest,
85
+ digest,
86
+ anchor,
87
+ }, ['id', 'kind', 'path']);
88
+
89
+ const readinessCheck = closed({
90
+ id: { enum: DESIGN_HANDOFF_CHECK_IDS },
91
+ status: { enum: ['pass', 'attention', 'blocked', 'stale'] },
92
+ message: title,
93
+ evidenceRefs: list(id, 64),
94
+ recoveryAction: action,
95
+ }, ['id', 'status', 'message', 'evidenceRefs']);
96
+
97
+ const readinessRecord = closed({
98
+ kind: { const: 'openplanr-design-handoff-readiness' },
99
+ schemaVersion: { const: DESIGN_HANDOFF_CONTRACT_VERSION },
100
+ scope: { const: 'design-originated' },
101
+ authority: { const: 'none' },
102
+ designId: id,
103
+ sourceRevision: { anyOf: [digest, { type: 'null' }] },
104
+ selectedVariant: { anyOf: [id, { type: 'null' }] },
105
+ status: { enum: ['ready', 'attention', 'blocked', 'stale'] },
106
+ continuation: closed({ action: { const: DESIGN_HANDOFF_AUTHORITY }, available: { type: 'boolean' } }),
107
+ checks: list(readinessCheck, DESIGN_HANDOFF_CHECK_IDS.length),
108
+ evidence: list(evidenceReference, 10000),
109
+ blockers: list({ enum: DESIGN_HANDOFF_CHECK_IDS }, DESIGN_HANDOFF_CHECK_IDS.length),
110
+ nextActions: list(action, DESIGN_HANDOFF_CHECK_IDS.length),
111
+ });
112
+
113
+ const readinessAbsence = closed({
114
+ kind: { const: 'openplanr-design-handoff-readiness-absence' },
115
+ schemaVersion: { const: DESIGN_HANDOFF_CONTRACT_VERSION },
116
+ status: { const: 'absent' },
117
+ reason: { enum: ['not-computed', 'not-applicable', 'unavailable'] },
118
+ message: title,
119
+ nextAction: action,
120
+ });
121
+
122
+ export const DESIGN_HANDOFF_READINESS_SCHEMA = contract('design-handoff-readiness', {
123
+ oneOf: [readinessRecord, readinessAbsence],
124
+ });
125
+
126
+ const requirement = closed({
127
+ id: { type: 'string', pattern: '^REQ-[0-9]{3,}$' },
128
+ kind: { enum: DESIGN_HANDOFF_REQUIREMENT_KINDS },
129
+ statement: text,
130
+ sourceRefs: { ...list(id, 256), minItems: 1 },
131
+ verification: { ...list(text, 256), minItems: 1 },
132
+ });
133
+
134
+ const implementationHandoff = closed({
135
+ kind: { const: 'openplanr-design-implementation-handoff' },
136
+ schemaVersion: { const: DESIGN_HANDOFF_CONTRACT_VERSION },
137
+ id,
138
+ version: { type: 'integer', minimum: 1 },
139
+ status: { enum: ['draft', 'approved', 'superseded', 'revoked'] },
140
+ authority: { const: DESIGN_HANDOFF_AUTHORITY },
141
+ title,
142
+ basis: closed({
143
+ designId: id,
144
+ sourceRevision: digest,
145
+ selectedVariant: id,
146
+ readiness: closed({ status: { enum: ['ready', 'attention', 'blocked', 'stale'] }, digest }),
147
+ reviewHandoff: closed({ version: { type: 'integer', minimum: 1 }, contentDigest: digest }),
148
+ }),
149
+ sources: list(evidenceReference, 10000),
150
+ requirements: { ...list(requirement, 10000), minItems: 1 },
151
+ contentDigest: digest,
152
+ markdown: { type: 'string', maxLength: 2097152 },
153
+ approval: closed({ actorId: id, approvedAt: timestamp, contentDigest: digest, authority: { const: DESIGN_HANDOFF_AUTHORITY } }),
154
+ supersededBy: closed({ id, version: { type: 'integer', minimum: 1 }, contentDigest: digest }),
155
+ revocation: closed({ actorId: id, revokedAt: timestamp, reason: text }),
156
+ }, ['kind', 'schemaVersion', 'id', 'version', 'status', 'authority', 'title', 'basis', 'sources', 'requirements', 'contentDigest', 'markdown']);
157
+
158
+ implementationHandoff.allOf = [
159
+ {
160
+ if: { properties: { status: { const: 'approved' } }, required: ['status'] },
161
+ then: { required: ['approval'], not: { anyOf: [{ required: ['supersededBy'] }, { required: ['revocation'] }] } },
162
+ },
163
+ {
164
+ if: { properties: { status: { const: 'superseded' } }, required: ['status'] },
165
+ then: { required: ['approval', 'supersededBy'], not: { required: ['revocation'] } },
166
+ },
167
+ {
168
+ if: { properties: { status: { const: 'revoked' } }, required: ['status'] },
169
+ then: { required: ['approval', 'revocation'], not: { required: ['supersededBy'] } },
170
+ },
171
+ {
172
+ if: { properties: { status: { const: 'draft' } }, required: ['status'] },
173
+ then: { not: { anyOf: [{ required: ['approval'] }, { required: ['supersededBy'] }, { required: ['revocation'] }] } },
174
+ },
175
+ ];
176
+
177
+ export const DESIGN_IMPLEMENTATION_HANDOFF_SCHEMA = contract(
178
+ 'design-implementation-handoff',
179
+ implementationHandoff,
180
+ );
181
+
182
+ const lineageMapping = closed({
183
+ requirementId: { type: 'string', pattern: '^REQ-[0-9]{3,}$' },
184
+ acceptanceRefs: { ...list(closed({
185
+ storyId: { type: 'string', pattern: '^US-[0-9]{3,}$' },
186
+ acceptanceId: { type: 'string', pattern: '^AC-[0-9]{3,}$' },
187
+ }), 256), minItems: 1 },
188
+ taskIds: { ...list({ type: 'string', pattern: '^T-[0-9]{3,}$' }, 256), minItems: 1 },
189
+ });
190
+
191
+ export const DESIGN_PLANNING_LINEAGE_SCHEMA = contract('design-planning-lineage', closed({
192
+ kind: { const: 'openplanr-design-planning-lineage' },
193
+ schemaVersion: { const: DESIGN_HANDOFF_CONTRACT_VERSION },
194
+ handoff: closed({ id, version: { type: 'integer', minimum: 1 }, contentDigest: digest }),
195
+ specId: { type: 'string', pattern: '^SPEC-[0-9]{3,}$' },
196
+ mappings: { ...list(lineageMapping, 10000), minItems: 1 },
197
+ }));
198
+
199
+ export const DESIGN_HANDOFF_SCHEMAS = deepFreeze({
200
+ 'design-handoff-readiness': DESIGN_HANDOFF_READINESS_SCHEMA,
201
+ 'design-implementation-handoff': DESIGN_IMPLEMENTATION_HANDOFF_SCHEMA,
202
+ 'design-planning-lineage': DESIGN_PLANNING_LINEAGE_SCHEMA,
203
+ });
204
+
205
+ function deepFreeze(value) {
206
+ if (value && typeof value === 'object' && !Object.isFrozen(value)) {
207
+ for (const nested of Object.values(value)) deepFreeze(nested);
208
+ Object.freeze(value);
209
+ }
210
+ return value;
211
+ }
212
+
213
+ function assertPlainData(value, depth = 0, seen = new Set()) {
214
+ if (depth > 64) throw new TypeError('Design handoff data exceeds the maximum nesting depth.');
215
+ if (value === null || ['string', 'boolean'].includes(typeof value)) return;
216
+ if (typeof value === 'number' && Number.isFinite(value)) return;
217
+ if (typeof value !== 'object' || seen.has(value)) throw new TypeError('Design handoff data must be finite, acyclic JSON.');
218
+ if (!Array.isArray(value) && ![Object.prototype, null].includes(Object.getPrototypeOf(value))) throw new TypeError('Design handoff data must contain only plain JSON objects.');
219
+ seen.add(value);
220
+ for (const [key, descriptor] of Object.entries(Object.getOwnPropertyDescriptors(value))) {
221
+ if (['__proto__', 'prototype', 'constructor'].includes(key) || !Object.hasOwn(descriptor, 'value')) throw new TypeError('Design handoff data contains a forbidden property.');
222
+ assertPlainData(descriptor.value, depth + 1, seen);
223
+ }
224
+ seen.delete(value);
225
+ }
226
+
227
+ function distinct(items, select, label) {
228
+ const values = items.map(select);
229
+ if (new Set(values).size !== values.length) throw new TypeError(`Duplicate ${label}.`);
230
+ }
231
+
232
+ export function isDesignHandoffRelativePath(value) {
233
+ return typeof value === 'string'
234
+ && value.length > 0
235
+ && value.length <= 4096
236
+ && !/^(?:[A-Za-z]:|\/|[A-Za-z][A-Za-z0-9+.-]*:)|[\\?#%\u0000-\u001f\u007f]/u.test(value)
237
+ && value.split('/').every(part => part && part !== '.' && part !== '..' && !['__proto__', 'prototype', 'constructor'].includes(part));
238
+ }
239
+
240
+ export function assertDesignHandoffContract(value, schemaOrName) {
241
+ const schema = typeof schemaOrName === 'string' ? DESIGN_HANDOFF_SCHEMAS[schemaOrName] : schemaOrName;
242
+ if (!schema) throw new TypeError('Unknown design handoff contract.');
243
+ assertPlainData(value);
244
+ canonicalizeJson(value);
245
+ const errors = validateJson(value, schema);
246
+ if (errors.length) throw new TypeError(`Invalid ${schema['x-openplanr-contract']?.id ?? 'design handoff data'}: ${errors.slice(0, 5).map(error => `${error.path} (${error.rule})`).join('; ')}`);
247
+ return value;
248
+ }
249
+
250
+ function assertEvidenceReferences(evidence) {
251
+ distinct(evidence, item => item.id, 'evidence reference identity');
252
+ for (const item of evidence) if (!isDesignHandoffRelativePath(item.path)) throw new TypeError('Design handoff evidence requires a repository-relative logical path.');
253
+ }
254
+
255
+ function assertProductCopy(value) {
256
+ if (/\b(?:hash|digest|checksum|sha[- ]?256|canonical(?:ize|ization)?)\b/iu.test(value)) throw new TypeError('Design readiness guidance must use product language.');
257
+ }
258
+
259
+ export function assertDesignHandoffReadiness(value) {
260
+ assertDesignHandoffContract(value, DESIGN_HANDOFF_READINESS_SCHEMA);
261
+ if (value.kind.endsWith('-absence')) {
262
+ assertProductCopy(`${value.message} ${value.nextAction.label}`);
263
+ return value;
264
+ }
265
+ assertEvidenceReferences(value.evidence);
266
+ distinct(value.checks, item => item.id, 'readiness check identity');
267
+ const expected = DESIGN_HANDOFF_CHECK_IDS.join('\n');
268
+ if (value.checks.map(item => item.id).join('\n') !== expected) throw new TypeError('Design readiness must contain every stable check in canonical order.');
269
+ const evidenceIds = new Set(value.evidence.map(item => item.id));
270
+ for (const check of value.checks) {
271
+ distinct(check.evidenceRefs, item => item, 'readiness evidence reference');
272
+ if (check.evidenceRefs.some(reference => !evidenceIds.has(reference))) throw new TypeError('Design readiness references missing evidence.');
273
+ assertProductCopy(`${check.message} ${check.recoveryAction?.label ?? ''}`);
274
+ }
275
+ const priority = { pass: 0, attention: 1, blocked: 2, stale: 3 };
276
+ const worst = value.checks.reduce((current, check) => priority[check.status] > priority[current] ? check.status : current, 'pass');
277
+ const expectedStatus = worst === 'pass' ? 'ready' : worst;
278
+ if (value.status !== expectedStatus) throw new TypeError('Design readiness summary does not match its checks.');
279
+ const blockingIds = value.checks.filter(check => ['blocked', 'stale'].includes(check.status)).map(check => check.id);
280
+ if (value.blockers.join('\n') !== blockingIds.join('\n')) throw new TypeError('Design readiness blockers do not match its blocking checks.');
281
+ const actionable = value.checks.filter(check => check.status !== 'pass');
282
+ if (value.nextActions.length !== actionable.length || value.nextActions.some((actionValue, index) => {
283
+ const recoveryAction = actionable[index].recoveryAction;
284
+ return actionValue.id !== recoveryAction?.id || actionValue.label !== recoveryAction?.label;
285
+ })) throw new TypeError('Design readiness next actions do not match its checks.');
286
+ if (value.continuation.available !== ['ready', 'attention'].includes(value.status)) throw new TypeError('Design readiness continuation availability does not match its status.');
287
+ return value;
288
+ }
289
+
290
+ export function designImplementationHandoffDigest(value) {
291
+ const projection = {
292
+ kind: value.kind,
293
+ schemaVersion: value.schemaVersion,
294
+ id: value.id,
295
+ version: value.version,
296
+ authority: value.authority,
297
+ title: value.title,
298
+ basis: value.basis,
299
+ sources: value.sources,
300
+ requirements: value.requirements,
301
+ markdown: value.markdown,
302
+ };
303
+ return `sha256:${sha256Hex(canonicalizeJson(projection))}`;
304
+ }
305
+
306
+ export function assertDesignImplementationHandoff(value) {
307
+ assertDesignHandoffContract(value, DESIGN_IMPLEMENTATION_HANDOFF_SCHEMA);
308
+ assertEvidenceReferences(value.sources);
309
+ distinct(value.requirements, item => item.id, 'implementation requirement identity');
310
+ const sourceIds = new Set(value.sources.map(item => item.id));
311
+ for (const item of value.requirements) {
312
+ distinct(item.sourceRefs, reference => reference, 'requirement source reference');
313
+ if (item.sourceRefs.some(reference => !sourceIds.has(reference))) throw new TypeError('Implementation requirement references missing evidence.');
314
+ }
315
+ if (value.contentDigest !== designImplementationHandoffDigest(value)) throw new TypeError('Implementation handoff content does not match its recorded integrity value.');
316
+ if (value.approval?.contentDigest !== undefined && value.approval.contentDigest !== value.contentDigest) throw new TypeError('Implementation handoff approval does not match its content.');
317
+ if (value.status !== 'draft' && value.basis.readiness.status !== 'ready') throw new TypeError('Only a ready implementation handoff can be approved or retained as approved history.');
318
+ if (value.supersededBy && value.supersededBy.id === value.id && value.supersededBy.version <= value.version) throw new TypeError('A superseding handoff must identify a newer package version.');
319
+ return value;
320
+ }
321
+
322
+ export function assertDesignPlanningLineage(value, handoff) {
323
+ assertDesignHandoffContract(value, DESIGN_PLANNING_LINEAGE_SCHEMA);
324
+ distinct(value.mappings, item => item.requirementId, 'lineage requirement identity');
325
+ for (const mapping of value.mappings) {
326
+ distinct(mapping.acceptanceRefs, item => `${item.storyId}:${item.acceptanceId}`, 'lineage acceptance identity');
327
+ distinct(mapping.taskIds, item => item, 'lineage task identity');
328
+ }
329
+ if (handoff) {
330
+ assertDesignImplementationHandoff(handoff);
331
+ if (handoff.status !== 'approved') throw new TypeError('Planning lineage requires an approved handoff.');
332
+ if (value.handoff.id !== handoff.id || value.handoff.version !== handoff.version || value.handoff.contentDigest !== handoff.contentDigest) throw new TypeError('Planning lineage identifies a different handoff package.');
333
+ const expected = handoff.requirements.map(item => item.id).sort();
334
+ const actual = value.mappings.map(item => item.requirementId).sort();
335
+ if (actual.join('\n') !== expected.join('\n')) throw new TypeError('Planning lineage must map every implementation requirement exactly once.');
336
+ }
337
+ return value;
338
+ }
@@ -1507,7 +1507,7 @@ export const CANONICAL_REGISTRIES = deepFreeze({
1507
1507
  "ownerPackage": "openplanr",
1508
1508
  "source": {
1509
1509
  "path": "skills/planr-plan/SKILL.md",
1510
- "digest": "sha256:7cfff1b795f68e07c2fcd852c2acea0956aa4bef0d96e15a6a595aeb030cbe30"
1510
+ "digest": "sha256:eb92df1829191cc3423bf6063f36247126838f7098ccc593ddae20692651e94d"
1511
1511
  },
1512
1512
  "authorityClass": "workflow",
1513
1513
  "machineJson": false,
@@ -1738,7 +1738,7 @@ export const CANONICAL_REGISTRIES = deepFreeze({
1738
1738
  "ownerPackage": "openplanr",
1739
1739
  "source": {
1740
1740
  "path": "skills/planr-plan/SKILL.md",
1741
- "digest": "sha256:7cfff1b795f68e07c2fcd852c2acea0956aa4bef0d96e15a6a595aeb030cbe30"
1741
+ "digest": "sha256:eb92df1829191cc3423bf6063f36247126838f7098ccc593ddae20692651e94d"
1742
1742
  },
1743
1743
  "authorityClass": "workflow",
1744
1744
  "machineJson": false,
@@ -1948,7 +1948,7 @@ export const CANONICAL_REGISTRIES = deepFreeze({
1948
1948
  "ownerPackage": "openplanr",
1949
1949
  "source": {
1950
1950
  "path": "packages/cli/src/cli/commands/spec.ts",
1951
- "digest": "sha256:4176ac9497403e7077d465a6843427e110c3ba6cdf07fcd21ce667f1c2dce6f5"
1951
+ "digest": "sha256:44d37d296459ce05273e3c0cdba32a6a03288c020074e447d2bc4d0ea0deebae"
1952
1952
  },
1953
1953
  "authorityClass": "workflow",
1954
1954
  "machineJson": false,
@@ -2179,7 +2179,7 @@ export const CANONICAL_REGISTRIES = deepFreeze({
2179
2179
  "ownerPackage": "planr-pipeline",
2180
2180
  "source": {
2181
2181
  "path": "skills/planr-design/SKILL.md",
2182
- "digest": "sha256:e21e82a8f216c3a06a938965cdbeac5786e3b74776e821260b2630919106ae4d"
2182
+ "digest": "sha256:a8554f6ac7fcbe6760153f34ab18d533ff4ff36d3556dad55687b3c3b6d33aab"
2183
2183
  },
2184
2184
  "authorityClass": "compatibility-router",
2185
2185
  "machineJson": false,
@@ -2221,7 +2221,7 @@ export const CANONICAL_REGISTRIES = deepFreeze({
2221
2221
  "ownerPackage": "planr-pipeline",
2222
2222
  "source": {
2223
2223
  "path": "skills/planr-design-review/SKILL.md",
2224
- "digest": "sha256:a018e9a80e104cd444a6475514e7ac4231ca460d7a1ecbec604b0e173de608d0"
2224
+ "digest": "sha256:1c4e6e8dcb750bb20c04b2b05fb433fe6866bc4fb5554cb82fa357077d27c242"
2225
2225
  },
2226
2226
  "authorityClass": "compatibility-router",
2227
2227
  "machineJson": false,
@@ -2242,7 +2242,7 @@ export const CANONICAL_REGISTRIES = deepFreeze({
2242
2242
  "ownerPackage": "planr-pipeline",
2243
2243
  "source": {
2244
2244
  "path": "skills/planr-plan/SKILL.md",
2245
- "digest": "sha256:7cfff1b795f68e07c2fcd852c2acea0956aa4bef0d96e15a6a595aeb030cbe30"
2245
+ "digest": "sha256:eb92df1829191cc3423bf6063f36247126838f7098ccc593ddae20692651e94d"
2246
2246
  },
2247
2247
  "authorityClass": "compatibility-router",
2248
2248
  "machineJson": false,
@@ -2263,7 +2263,7 @@ export const CANONICAL_REGISTRIES = deepFreeze({
2263
2263
  "ownerPackage": "planr-pipeline",
2264
2264
  "source": {
2265
2265
  "path": "skills/planr-ship/SKILL.md",
2266
- "digest": "sha256:b0b1dcedcfa936432c5c4dcb672310ecbaa8d958159b6fcb81586692500bbb3d"
2266
+ "digest": "sha256:649272ea8cad3096012acaa9ec16a3ce6288f557e404fedbe9646aefb3b2c8ba"
2267
2267
  },
2268
2268
  "authorityClass": "compatibility-router",
2269
2269
  "machineJson": false,
@@ -3099,7 +3099,7 @@ export const CANONICAL_REGISTRIES = deepFreeze({
3099
3099
  ]
3100
3100
  }
3101
3101
  ],
3102
- "documentDigest": "sha256:7ffb9b909de9618cbace6cfad748408d97e773dd20e0b439f2795da99c985ace"
3102
+ "documentDigest": "sha256:ae3955232bf3a97fd1cae7ca01deec957232a64c0c2c3c2fb25a14963c93e310"
3103
3103
  },
3104
3104
  "skills.json": {
3105
3105
  "kind": "skill-catalog",
@@ -3722,12 +3722,12 @@ export const CANONICAL_REGISTRIES = deepFreeze({
3722
3722
  },
3723
3723
  {
3724
3724
  "skillId": "planr-design",
3725
- "skillVersion": "2.0.0",
3725
+ "skillVersion": "2.1.0",
3726
3726
  "description": "Design a polished product interface through adaptive consultation, a shared canvas/prototype/walkthrough studio, and an implementation-ready specification. Use for a new design or an existing interface that needs a coherent direction.",
3727
3727
  "lifecycle": "active",
3728
3728
  "authorityClass": "planning-write",
3729
3729
  "source": "skills/planr-design/openplanr.skill.json",
3730
- "sourceDigest": "sha256:208206addf0dc8337f1914256ba6b655edf570d7cdfb7ebd62c73b29299fba95",
3730
+ "sourceDigest": "sha256:83457207042925d16148dd28054ef69f00c4358136da7eaadc286f01bc6a0797",
3731
3731
  "triggerPolicy": {
3732
3732
  "include": [
3733
3733
  "Create an initial product design direction",
@@ -3788,7 +3788,7 @@ export const CANONICAL_REGISTRIES = deepFreeze({
3788
3788
  "lifecycle": "active",
3789
3789
  "authorityClass": "planning-write",
3790
3790
  "source": "skills/planr-design-loop/openplanr.skill.json",
3791
- "sourceDigest": "sha256:8e4eeb36590194963d6e8f6448e8d991658bf93a2070b0cb446b45ad793e3a49",
3791
+ "sourceDigest": "sha256:cecdbd16879f58de70d1158b776fb47ac5520e22c2d6c0d01b3c6b8c4c843ced",
3792
3792
  "triggerPolicy": {
3793
3793
  "include": [
3794
3794
  "Explore multiple design directions or variants",
@@ -3844,12 +3844,12 @@ export const CANONICAL_REGISTRIES = deepFreeze({
3844
3844
  },
3845
3845
  {
3846
3846
  "skillId": "planr-design-review",
3847
- "skillVersion": "2.0.0",
3847
+ "skillVersion": "2.1.0",
3848
3848
  "description": "Review and revise an existing product design using stable board pins and scoped browser-verified changes. Use for focused improvements while preserving unrelated screens and feedback.",
3849
3849
  "lifecycle": "active",
3850
3850
  "authorityClass": "review-evidence",
3851
3851
  "source": "skills/planr-design-review/openplanr.skill.json",
3852
- "sourceDigest": "sha256:11c7f60feaba70cb6bc439244164ec946ae76c68c4bf46bd4d1d8c916d80ee90",
3852
+ "sourceDigest": "sha256:6ac49ca8fd2f709aff25f192f55e9c530b95715a626af01afef2ed1d2170e340",
3853
3853
  "triggerPolicy": {
3854
3854
  "include": [
3855
3855
  "Review or critique an existing OpenPlanr design",
@@ -3905,12 +3905,12 @@ export const CANONICAL_REGISTRIES = deepFreeze({
3905
3905
  },
3906
3906
  {
3907
3907
  "skillId": "planr-diagram",
3908
- "skillVersion": "1.0.0",
3908
+ "skillVersion": "1.1.0",
3909
3909
  "description": "Create, inspect, verify, or rerender professional offline diagrams. Use for architecture, process, sequence, data, state, or relationship visuals from intent or source.",
3910
3910
  "lifecycle": "active",
3911
3911
  "authorityClass": "artifact-authoring",
3912
3912
  "source": "skills/planr-diagram/openplanr.skill.json",
3913
- "sourceDigest": "sha256:e66b2adbd7c1621d056fbd77ff24973eac57ffdc6aca04fbd6c013afc9c71b1c",
3913
+ "sourceDigest": "sha256:1d8b8127914dd7a637ea475257c109a72544f860ddf5ec40c3a78563831a9906",
3914
3914
  "triggerPolicy": {
3915
3915
  "include": [
3916
3916
  "Create a professional diagram from English intent or Mermaid",
@@ -4277,12 +4277,12 @@ export const CANONICAL_REGISTRIES = deepFreeze({
4277
4277
  },
4278
4278
  {
4279
4279
  "skillId": "planr-plan",
4280
- "skillVersion": "1.1.1",
4280
+ "skillVersion": "1.2.0",
4281
4281
  "description": "Turn a Protocol-compatible specification or product intent into schema-compatible OpenPlanr stories and implementation tasks. Use for planning and decomposition, not implementation.",
4282
4282
  "lifecycle": "active",
4283
4283
  "authorityClass": "planning-write",
4284
4284
  "source": "skills/planr-plan/openplanr.skill.json",
4285
- "sourceDigest": "sha256:18ed9de64dccee4d48bb9e94074cade3c6cda46e3c5eb9957eb96f4d319695a8",
4285
+ "sourceDigest": "sha256:a1e090540db3a4edc2694e1a24c6fc0af85838eb7ee3138cdc53f4be69803479",
4286
4286
  "triggerPolicy": {
4287
4287
  "include": [
4288
4288
  "Decompose a specification into user stories and implementation tasks",
@@ -4459,12 +4459,12 @@ export const CANONICAL_REGISTRIES = deepFreeze({
4459
4459
  },
4460
4460
  {
4461
4461
  "skillId": "planr-ship",
4462
- "skillVersion": "1.1.0",
4462
+ "skillVersion": "1.2.0",
4463
4463
  "description": "Implement an OpenPlanr plan, specification, task, or clearly stated request end to end in the current repository. Use when the user asks to build, implement, fix, finish, or ship local work.",
4464
4464
  "lifecycle": "active",
4465
4465
  "authorityClass": "implementation",
4466
4466
  "source": "skills/planr-ship/openplanr.skill.json",
4467
- "sourceDigest": "sha256:1a2c6b2f7c69b364bbf6f2e7cc90abfcf75eaac4e8d10f4d4fd60af7d101e3a8",
4467
+ "sourceDigest": "sha256:4ad07e8b30a574bd7f12f87fe3852103c20241dd1e73dfcdb25e250c6b7d28f4",
4468
4468
  "triggerPolicy": {
4469
4469
  "include": [
4470
4470
  "Implement a plan, specification, task, fix, or clearly stated local request",
@@ -4767,7 +4767,7 @@ export const CANONICAL_REGISTRIES = deepFreeze({
4767
4767
  }
4768
4768
  ],
4769
4769
  "compatibilityAliases": [],
4770
- "documentDigest": "sha256:f4110fb706b84192deaef1ee5238cc10477b1d91f0003040a33221e490312cc7"
4770
+ "documentDigest": "sha256:afe78935afba9b34e9a5cfe15f4821a424334c90213292252b1b068ba66db958"
4771
4771
  },
4772
4772
  "outputs.json": {
4773
4773
  "kind": "output-catalog",
package/src/index.d.mts CHANGED
@@ -8,3 +8,4 @@ export * from './planning-contracts.mjs';
8
8
  export * from './diagram-contracts.mjs';
9
9
  export * from './enterprise-contracts.mjs';
10
10
  export * from './design-publication-contracts.mjs';
11
+ export * from './design-handoff-contracts.mjs';
package/src/index.mjs CHANGED
@@ -18,6 +18,7 @@ export {
18
18
  PROTOCOL_V16_CONTRACTS,
19
19
  PROTOCOL_V17_CONTRACTS,
20
20
  PROTOCOL_V18_CONTRACTS,
21
+ PROTOCOL_V111_CONTRACTS,
21
22
  protocolAssetUrl,
22
23
  } from './browser-contracts.mjs';
23
24
  export { normalizePlanningTask, validatePlanningAcceptanceCoverage } from './planning-contracts.mjs';
@@ -38,3 +39,4 @@ export {
38
39
  } from './task-contracts.mjs';
39
40
  export * from './enterprise-contracts.mjs';
40
41
  export * from './design-publication-contracts.mjs';
42
+ export * from './design-handoff-contracts.mjs';