@openplanr/protocol 0.3.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.
- package/package.json +5 -1
- package/registries/commands.json +12 -12
- package/registries/skills.json +74 -12
- package/schemas/v1.11.0/design-handoff-readiness.schema.json +398 -0
- package/schemas/v1.11.0/design-implementation-handoff.schema.json +518 -0
- package/schemas/v1.11.0/design-planning-lineage.schema.json +106 -0
- package/src/browser-contracts.d.mts +2 -1
- package/src/browser-contracts.mjs +7 -1
- package/src/contracts.mjs +2 -0
- package/src/design-handoff-contracts.d.mts +92 -0
- package/src/design-handoff-contracts.mjs +338 -0
- package/src/generated/canonical-registries.mjs +86 -24
- package/src/index.d.mts +1 -0
- package/src/index.mjs +2 -0
- package/src/registries.mjs +1 -1
|
@@ -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
|
+
}
|