@openplanr/protocol 0.2.0

package/src/registries.mjs

@@ -0,0 +1,261 @@
+import { verifyDocumentDigest } from './canonical-json.mjs';
+import { CANONICAL_REGISTRIES } from './generated/canonical-registries.mjs';
+import { PROTOCOL_ERROR_CODES, ProtocolError } from './errors.mjs';
+
+const fail = (code, message, details) => {
+  throw new ProtocolError(code, message, '', details);
+};
+const equal = (left, right) => JSON.stringify(left) === JSON.stringify(right);
+
+function assertDocument(name, value, kind) {
+  if (!value || typeof value !== 'object' || Array.isArray(value) || value.kind !== kind
+    || value.protocolVersion !== '1.5.0' || value.digestAlgorithm !== 'sha256'
+    || value.canonicalization !== 'rfc8785' || !verifyDocumentDigest(value)) {
+    fail(PROTOCOL_ERROR_CODES.DOCUMENT_INVALID, `${name} is not a digest-bound Protocol 1.5 document.`, { name });
+  }
+}
+
+function assertSortedUnique(values, key, name) {
+  const keys = values.map((value) => value[key]);
+  if (new Set(keys).size !== keys.length) fail(PROTOCOL_ERROR_CODES.DUPLICATE_ID, `${name} contains duplicate ${key} values.`, { keys });
+  const sorted = [...keys].sort();
+  if (!equal(keys, sorted)) fail(PROTOCOL_ERROR_CODES.SORT_ORDER_INVALID, `${name} must be sorted by ${key}.`, { keys, sorted });
+}
+
+const EXPECTED_ROLES = Object.freeze({
+  'planr-backend': ['backend-agent', 'dev', 'conditional', 'implementation-high', 'implementation-result'],
+  'planr-database': ['db-agent', 'po-preflight', 'conditional', 'analysis-high', 'task-output-manifest'],
+  'planr-designer': ['designer-agent', 'po', 'conditional', 'analysis-high', 'designer-output'],
+  'planr-devops': ['devops-agent', 'post-build', 'conditional', 'analysis-high', 'task-output-manifest'],
+  'planr-documentation': ['doc-gen-agent', 'post-build', 'conditional', 'analysis-high', 'task-output-manifest'],
+  'planr-entity-scaffold': ['entity-scaffold-agent', 'po-preflight', 'manual', 'analysis-high', 'task-output-manifest'],
+  'planr-frontend': ['frontend-agent', 'dev', 'conditional', 'implementation-high', 'implementation-result'],
+  'planr-qa': ['qa-agent', 'qa', 'always', 'read-only-qa', 'task-output-manifest'],
+  'planr-specification': ['specification-agent', 'po', 'always', 'analysis-high', 'specification-output'],
+});
+
+const EXPECTED_TASK_KINDS = Object.freeze({
+  backend: 'planr-backend', database: 'planr-database', devops: 'planr-devops', documentation: 'planr-documentation',
+  'entity-scaffold': 'planr-entity-scaffold', frontend: 'planr-frontend', qa: 'planr-qa',
+});
+
+const EXPECTED_SKILLS = Object.freeze([
+  'planr-artifact', 'planr-browser-qa', 'planr-ceo-review', 'planr-chair-review', 'planr-challenger-review', 'planr-cmo-review',
+  'planr-coo-review', 'planr-cpo-review', 'planr-cto-review', 'planr-dashboard', 'planr-design', 'planr-design-loop',
+  'planr-design-review', 'planr-diagram', 'planr-doctor', 'planr-investigate', 'planr-land', 'planr-operate', 'planr-plan',
+  'planr-plan-review', 'planr-release', 'planr-ship', 'planr-spec', 'planr-status', 'planr-sync',
+]);
+
+export function validateCanonicalRegistries(registries = CANONICAL_REGISTRIES) {
+  const roles = registries['roles.json'];
+  const taskKinds = registries['task-kinds.json'];
+  const rules = registries['rules.json'];
+  const commands = registries['commands.json'];
+  const skills = registries['skills.json'];
+  const outputs = registries['outputs.json'];
+  const outputPaths = registries['output-paths.json'];
+  assertDocument('roles.json', roles, 'role-registry');
+  assertDocument('task-kinds.json', taskKinds, 'task-kind-registry');
+  assertDocument('rules.json', rules, 'rule-catalog');
+  assertDocument('commands.json', commands, 'command-catalog');
+  assertDocument('skills.json', skills, 'skill-catalog');
+  assertDocument('outputs.json', outputs, 'output-catalog');
+  assertDocument('output-paths.json', outputPaths, 'output-path-catalog');
+
+  if (roles.roles.length !== 9) fail(PROTOCOL_ERROR_CODES.REGISTRY_INVALID, 'Protocol 0.1 requires exactly nine canonical roles.');
+  assertSortedUnique(roles.roles, 'roleId', 'roles.json');
+  const aliases = new Set();
+  const canonicalRoleIds = new Set(roles.roles.map(({ roleId }) => roleId));
+  for (const role of roles.roles) {
+    if (role.legacyAliases.length !== 1 || aliases.has(role.legacyAliases[0].id) || canonicalRoleIds.has(role.legacyAliases[0].id)) {
+      fail(PROTOCOL_ERROR_CODES.DUPLICATE_ID, `Role alias collision for ${role.roleId}.`);
+    }
+    aliases.add(role.legacyAliases[0].id);
+    const expected = EXPECTED_ROLES[role.roleId];
+    if (!expected || !equal([
+      role.legacyAliases[0]?.id, role.phase, role.activation, role.capabilityTier, role.outputContracts[0]?.id,
+    ], expected)) {
+      fail(PROTOCOL_ERROR_CODES.REGISTRY_INVALID, `Role compatibility mapping drifted for ${role.roleId}.`);
+    }
+    if (role.adapterMappings.length < 3 || role.qaCoverage.length < 1) {
+      fail(PROTOCOL_ERROR_CODES.REGISTRY_INVALID, `Role ${role.roleId} lacks adapter parity or QA coverage.`);
+    }
+  }
+  const qa = roles.roles.find(({ roleId }) => roleId === 'planr-qa');
+  const database = roles.roles.find(({ roleId }) => roleId === 'planr-database');
+  const devops = roles.roles.find(({ roleId }) => roleId === 'planr-devops');
+  if (qa.writeBoundary.repositoryAccess !== 'read-only' || qa.writeBoundary.allowedOutputClasses.includes('C')) {
+    fail(PROTOCOL_ERROR_CODES.REGISTRY_INVALID, 'QA must remain read-only.');
+  }
+  if (database.writeBoundary.externalDataAccess !== 'read-only' || !database.writeBoundary.forbiddenEffects.includes('database-mutation')) {
+    fail(PROTOCOL_ERROR_CODES.REGISTRY_INVALID, 'Database inspection must remain externally read-only.');
+  }
+  if (!devops.writeBoundary.forbiddenEffects.includes('deploy')) {
+    fail(PROTOCOL_ERROR_CODES.REGISTRY_INVALID, 'DevOps configuration authority must forbid deploy.');
+  }
+
+  if (taskKinds.roleRegistryDigest !== roles.documentDigest || taskKinds.bindings.length !== 7) {
+    fail(PROTOCOL_ERROR_CODES.REFERENCE_INVALID, 'Task-kind registry is not bound to the exact role registry.');
+  }
+  assertSortedUnique(taskKinds.bindings, 'taskKind', 'task-kinds.json bindings');
+  for (const binding of taskKinds.bindings) {
+    if (EXPECTED_TASK_KINDS[binding.taskKind] !== binding.roleId || !canonicalRoleIds.has(binding.roleId)) {
+      fail(PROTOCOL_ERROR_CODES.REFERENCE_INVALID, `Task kind ${binding.taskKind} has a mismatched role binding.`);
+    }
+    const expectedOutput = ['backend', 'frontend'].includes(binding.taskKind)
+      ? 'implementation-result'
+      : 'task-output-manifest';
+    if (!equal(binding.outputContracts, [{ id: expectedOutput, version: '1.0.0' }])) {
+      fail(PROTOCOL_ERROR_CODES.REFERENCE_INVALID, `Task kind ${binding.taskKind} has a mismatched output contract.`);
+    }
+  }
+  if (!equal(taskKinds.legacyMappings.map(({ legacyType, legacyAgent, taskKind, precedence }) => [legacyType, legacyAgent, taskKind, precedence]), [
+    ['UI', 'frontend-agent', 'frontend', 1], ['Tech', 'db-agent', 'database', 2],
+    ['Tech', 'backend-agent', 'backend', 3], ['Tech', null, 'backend', 4],
+  ])) fail(PROTOCOL_ERROR_CODES.REGISTRY_INVALID, 'Legacy UI/Tech routing precedence drifted.');
+
+  assertSortedUnique(rules.rules, 'ruleId', 'rules.json');
+  if (!equal(rules.rules.map(({ ruleId }) => ruleId), ['R1', 'R10', 'R2', 'R3', 'R4', 'R5', 'R6', 'R7', 'R8', 'R9'].sort())) {
+    fail(PROTOCOL_ERROR_CODES.REGISTRY_INVALID, 'Rule catalog must contain exact R1-R10.');
+  }
+  if (rules.rules.some((rule) => !rule.enforcementPoints.length || !rule.testRefs.length || !rule.citedBy.length)) {
+    fail(PROTOCOL_ERROR_CODES.REGISTRY_INVALID, 'Every rule requires enforcement, tests, and citations.');
+  }
+
+  const inventory = commands.inventory;
+  if (inventory.rootCommandModules !== 39 || inventory.rootCommandSlugs.length !== 39
+    || inventory.pipelineMachineLeaves !== 31 || inventory.pipelineMachineGrammar.length !== 31
+    || inventory.frozenClaudeDocuments !== 8 || inventory.frozenClaudeSlugs.length !== 8) {
+    fail(PROTOCOL_ERROR_CODES.REGISTRY_INVALID, 'Command inventory floors drifted.');
+  }
+  assertSortedUnique(commands.commands, 'commandId', 'commands.json');
+  const grammar = commands.commands.map(({ argv }) => JSON.stringify(argv));
+  if (new Set(grammar).size !== grammar.length) fail(PROTOCOL_ERROR_CODES.DUPLICATE_ID, 'Command grammar contains duplicate argv entries.');
+  if (commands.commands.some(({ argv }) => argv[0] === 'pipeline' && argv[1] === 'operate')) {
+    fail(PROTOCOL_ERROR_CODES.REGISTRY_INVALID, 'Retired pipeline Operate grammar became callable.');
+  }
+  if (!commands.commands.some(({ argv, lifecycle }) => argv[0] === 'operate' && lifecycle === 'active')
+    || !commands.negativeContracts.some(({ forbiddenArgvPrefix }) => equal(forbiddenArgvPrefix, ['pipeline', 'operate']))) {
+    fail(PROTOCOL_ERROR_CODES.REGISTRY_INVALID, 'Operate facade/retirement negative contract drifted.');
+  }
+
+  assertSortedUnique(skills.skills, 'skillId', 'skills.json');
+  const skillIds = skills.skills.map(({ skillId }) => skillId);
+  if (!equal(skillIds, EXPECTED_SKILLS)) {
+    fail(PROTOCOL_ERROR_CODES.REGISTRY_INVALID, 'Canonical skill membership differs from the active source registry.');
+  }
+  if (skillIds.some((id) => canonicalRoleIds.has(id)) || skills.skills.some((skill) => skill.hosts.length < 3 || !skill.certificationRefs.length)) {
+    fail(PROTOCOL_ERROR_CODES.DUPLICATE_ID, 'Skill/role IDs collide or a skill lacks host/certification parity.');
+  }
+  const ship = skills.skills.find(({ skillId }) => skillId === 'planr-ship');
+  if (!equal(ship?.contracts?.outputs, [{ id: 'implementation-result', version: '1.0.0' }])) {
+    fail(PROTOCOL_ERROR_CODES.REFERENCE_INVALID, 'Planr Ship must produce the canonical implementation result.');
+  }
+  const aliasIds = skills.compatibilityAliases.map(({ aliasId }) => aliasId).sort();
+  if (aliasIds.length !== 0) {
+    fail(PROTOCOL_ERROR_CODES.REGISTRY_INVALID, 'Protocol 1.8 canonical skills must not expose compatibility aliases.');
+  }
+  for (const command of commands.commands.filter(({ surface }) => surface === 'frozen-host-alias')) {
+    if (!skillIds.includes(command.skillId)) fail(PROTOCOL_ERROR_CODES.REFERENCE_INVALID, `Frozen command ${command.commandId} has no canonical skill.`);
+  }
+
+  assertSortedUnique(outputs.outputs, 'outputId', 'outputs.json');
+  if (!['A', 'B', 'C', 'D'].every((outputClass) => outputs.outputs.some((output) => output.outputClass === outputClass))) {
+    fail(PROTOCOL_ERROR_CODES.REGISTRY_INVALID, 'Output catalog must cover Classes A-D.');
+  }
+  if (outputs.outputs.some((output) => !output.generator || !output.validator || !output.compatibilityReaders.length || !output.testRefs.length)) {
+    fail(PROTOCOL_ERROR_CODES.REGISTRY_INVALID, 'Every output requires generator, validator, reader, and test custody.');
+  }
+  const modeAwarePlanningIds = ['gherkin-feature', 'professional-specification', 'task', 'user-story'];
+  assertSortedUnique(outputPaths.outputs, 'outputId', 'output-paths.json');
+  if (outputPaths.outputCatalogDigest !== outputs.documentDigest
+    || !equal(outputPaths.outputs.map(({ outputId }) => outputId), modeAwarePlanningIds)) {
+    fail(PROTOCOL_ERROR_CODES.REFERENCE_INVALID, 'Project-mode paths must bind the exact output catalog and complete planning output set.');
+  }
+  for (const outputPath of outputPaths.outputs) {
+    const output = outputs.outputs.find(({ outputId }) => outputId === outputPath.outputId);
+    if (outputPath.pathTemplates.default !== output?.pathTemplate
+      || !outputPath.pathTemplates['spec-driven']) {
+      fail(PROTOCOL_ERROR_CODES.REGISTRY_INVALID, `Output ${outputPath.outputId} has an invalid project-mode path contract.`);
+    }
+  }
+  return true;
+}
+
+validateCanonicalRegistries();
+
+const roleIndex = new Map(CANONICAL_REGISTRIES['roles.json'].roles.map((role) => [role.roleId, role]));
+const aliasIndex = new Map(CANONICAL_REGISTRIES['roles.json'].roles.flatMap((role) => role.legacyAliases.map(({ id }) => [id, role])));
+const taskKindIndex = new Map(CANONICAL_REGISTRIES['task-kinds.json'].bindings.map((binding) => [binding.taskKind, binding]));
+
+export { CANONICAL_REGISTRIES };
+
+export function getCanonicalRegistry(name) {
+  const value = CANONICAL_REGISTRIES[name];
+  if (!value) fail(PROTOCOL_ERROR_CODES.ASSET_NOT_FOUND, `Unknown canonical registry: ${name}`);
+  return value;
+}
+
+export function getRole(roleId) {
+  const role = roleIndex.get(roleId);
+  if (!role) fail(PROTOCOL_ERROR_CODES.REFERENCE_INVALID, `Unknown canonical role: ${roleId}`);
+  return role;
+}
+
+export function resolveLegacyRoleAlias(alias) {
+  return aliasIndex.get(alias) ?? null;
+}
+
+export function resolveTaskKind(taskKind) {
+  const binding = taskKindIndex.get(taskKind);
+  if (!binding) fail(PROTOCOL_ERROR_CODES.REFERENCE_INVALID, `Unknown task kind: ${taskKind}`);
+  return binding;
+}
+
+/** Resolve one output definition from the canonical catalog or a compatible supplied catalog. */
+export function getOutput(outputId, registries = CANONICAL_REGISTRIES) {
+  const output = registries['outputs.json']?.outputs?.find((candidate) => candidate.outputId === outputId);
+  if (!output) fail(PROTOCOL_ERROR_CODES.REFERENCE_INVALID, `Unknown output: ${outputId}`);
+  return output;
+}
+
+/** Select the canonical template for one project mode while preserving legacy catalog fallback. */
+export function getOutputPathTemplate(outputId, projectMode = 'default', registries = CANONICAL_REGISTRIES) {
+  if (projectMode !== 'default' && projectMode !== 'spec-driven') {
+    fail(PROTOCOL_ERROR_CODES.REFERENCE_INVALID, `Unknown project mode: ${projectMode}`);
+  }
+  const output = getOutput(outputId, registries);
+  const outputPath = registries['output-paths.json']?.outputs?.find((candidate) => candidate.outputId === outputId);
+  return outputPath?.pathTemplates?.[projectMode] ?? output.pathTemplate;
+}
+
+const PATH_TOKEN = /\{([A-Za-z][A-Za-z0-9]*)\}/gu;
+const SAFE_RELATIVE_PATH = /^(?!\/)(?![A-Za-z]:)(?!.*\\)(?!.*(?:^|\/)\.{1,2}(?:\/|$))(?!.*\/\/).+$/u;
+const MAX_RELATIVE_PATH_LENGTH = 1024;
+
+/** Resolve one catalog path with explicit mode and named template arguments. */
+export function resolveOutputPath(outputId, options = {}, registries = CANONICAL_REGISTRIES) {
+  const { projectMode = 'default', pathArguments = {} } = options;
+  const template = getOutputPathTemplate(outputId, projectMode, registries);
+  const missing = [...new Set([...template.matchAll(PATH_TOKEN)].map((match) => match[1]))]
+    .filter((name) => typeof pathArguments[name] !== 'string' || pathArguments[name].length === 0);
+  if (missing.length > 0) {
+    fail(PROTOCOL_ERROR_CODES.REFERENCE_INVALID, `Output ${outputId} path is missing arguments: ${missing.join(', ')}.`, { outputId, projectMode, missing });
+  }
+  const resolved = template.replace(PATH_TOKEN, (_token, name) => pathArguments[name]);
+  if (resolved.length > MAX_RELATIVE_PATH_LENGTH
+    || !SAFE_RELATIVE_PATH.test(resolved)
+    || /[\u0000\r\n]/u.test(resolved)) {
+    fail(PROTOCOL_ERROR_CODES.REFERENCE_INVALID, `Output ${outputId} resolved to an invalid relative path.`, { outputId, projectMode });
+  }
+  return resolved;
+}
+
+/** Route only explicit legacy fields; prose, filenames, hosts, and models are never evidence. */
+export function routeLegacyTask({ legacyType, legacyAgent = null }) {
+  const mappings = CANONICAL_REGISTRIES['task-kinds.json'].legacyMappings;
+  const exact = mappings.find((mapping) => mapping.legacyType === legacyType && mapping.legacyAgent === legacyAgent);
+  if (exact) return resolveTaskKind(exact.taskKind);
+  if (legacyType === 'Tech' && legacyAgent === null) return resolveTaskKind('backend');
+  fail(PROTOCOL_ERROR_CODES.REFERENCE_INVALID, `Legacy routing requires an explicit reviewed mapping for ${legacyType}/${legacyAgent ?? '<none>'}.`);
+}

package/src/review-experience-contracts.d.mts

@@ -0,0 +1,11 @@
+export declare const DESIGN_REVIEW_CONTEXT_SCHEMA: Readonly<Record<string, unknown>>;
+export declare const DESIGN_FINGERPRINT_SCHEMA: Readonly<Record<string, unknown>>;
+export declare const DESIGN_REVIEW_BUNDLE_V11_SCHEMA: Readonly<Record<string, unknown>>;
+export declare const DESIGN_HANDOFF_CONTENT_SCHEMA: Readonly<Record<string, unknown>>;
+export declare const DESIGN_HANDOFF_SCHEMA: Readonly<Record<string, unknown>>;
+export declare const DESIGN_REVIEW_METADATA_PAYLOAD_SCHEMA: Readonly<Record<string, unknown>>;
+export declare const DESIGN_REVIEW_METADATA_PAYLOAD_V11_SCHEMA: Readonly<Record<string, unknown>>;
+export declare const REVIEW_EXPERIENCE_SCHEMAS: Readonly<Record<string, Readonly<Record<string, unknown>>>>;
+export declare function assertReviewExperience<T>(value: T, contract: Readonly<Record<string, unknown>>): T;
+export declare function assertDesignReviewBundle<T>(value: T): T;
+export declare function assertDesignReviewMetadata<T>(value: T): T;

package/src/review-experience-contracts.mjs

@@ -0,0 +1,103 @@
+import { validateJson } from './json-schema.mjs';
+import { DESIGN_REVIEW_BUNDLE_SCHEMA } from './workspace-contracts.mjs';
+import { canonicalizeJson, sha256Hex } from './canonical-json.mjs';
+
+const text = { type: 'string', maxLength: 16384 };
+const id = { type: 'string', minLength: 1, maxLength: 128 };
+const digest = { type: 'string', pattern: '^[a-f0-9]{64}$' };
+const texts = { type: 'array', maxItems: 256, items: text };
+const closed = (properties, required = Object.keys(properties)) => ({ type: 'object', additionalProperties: false, properties, required });
+const list = (items, maxItems = 256) => ({ type: 'array', maxItems, items });
+const schema = (name, properties, required) => ({
+  $schema: 'https://json-schema.org/draft/2020-12/schema',
+  $id: `https://openplanr.dev/schemas/v1.10.0/${name}.schema.json`,
+  'x-openplanr-contract': { id: name, version: '1.10.0' },
+  ...closed(properties, required),
+});
+
+export const DESIGN_REVIEW_CONTEXT_SCHEMA = schema('design-review-context', {
+  kind: { const: 'openplanr-design-review-context' }, schemaVersion: { const: '1.0.0' }, designId: id,
+  brief: closed({ purpose: text, requests: { ...texts, maxItems: 3 }, audience: text }, ['purpose', 'requests']),
+  revisionSummary: text,
+  implementation: closed({
+    tokens: list(closed({ name: id, value: text, description: text }, ['name', 'value']), 512),
+    components: list(closed({ id, name: text, screenIds: list(id), anchorIds: list(id), states: list(closed({ name: id, description: text })), notes: text, responsive: text, accessibility: text }, ['id', 'name'])),
+    responsive: texts, accessibility: texts,
+  }),
+}, ['kind', 'schemaVersion', 'designId', 'brief', 'implementation']);
+
+export const DESIGN_FINGERPRINT_SCHEMA = closed({ screenId: id, variantId: id, frameId: id, contentDigest: digest, guidanceDigest: digest });
+export const DESIGN_REVIEW_BUNDLE_V11_SCHEMA = {
+  ...structuredClone(DESIGN_REVIEW_BUNDLE_SCHEMA),
+  $id: 'https://openplanr.dev/schemas/v1.10.0/design-review-bundle.schema.json',
+  'x-openplanr-contract': { id: 'design-review-bundle', version: '1.10.0' },
+};
+Object.assign(DESIGN_REVIEW_BUNDLE_V11_SCHEMA.properties, {
+  schemaVersion: { const: '1.1.0' }, reviewContext: DESIGN_REVIEW_CONTEXT_SCHEMA,
+  contextDigest: digest, fingerprints: list(DESIGN_FINGERPRINT_SCHEMA),
+});
+DESIGN_REVIEW_BUNDLE_V11_SCHEMA.required.push('reviewContext', 'contextDigest', 'fingerprints');
+
+const item = closed({ pinId: id, reviewId: id, screenId: id, revisionId: id, text, refinement: text, stale: { type: 'boolean' }, author: text, reviewOf: digest, source: text }, ['pinId', 'text']);
+export const DESIGN_HANDOFF_CONTENT_SCHEMA = closed({ summary: text, agreedChanges: list(item, 10000), openQuestions: list(item, 10000), deferred: list(item, 10000), rejected: list(item, 10000) });
+export const DESIGN_HANDOFF_SCHEMA = schema('design-review-handoff', {
+  kind: { const: 'openplanr-design-review-handoff' }, schemaVersion: { const: '1.0.0' },
+  title: text, version: { type: 'integer', minimum: 1 }, status: { enum: ['draft', 'approved'] },
+  basis: closed({ designId: id, sourceRevision: digest, contextDigest: digest, reviewOf: digest, selectedVariant: id, feedbackDigest: digest, verificationDigest: digest, feedbackWatermark: { type: 'integer', minimum: 0 } }),
+  content: DESIGN_HANDOFF_CONTENT_SCHEMA, contentHash: digest, markdown: { type: 'string', maxLength: 2097152 },
+  affectedScreens: list(id), verificationGaps: texts, reviewNotes: list(closed({reviewId:id,text}),10000),
+  approval: closed({ contentHash: digest, at: { type: 'string', format: 'date-time' } }),
+}, ['kind', 'schemaVersion', 'title', 'version', 'status', 'basis', 'content', 'contentHash', 'markdown', 'affectedScreens', 'verificationGaps', 'reviewNotes']);
+
+export const DESIGN_REVIEW_METADATA_PAYLOAD_SCHEMA = schema('design-review-metadata-payload', {
+  schemaVersion: { const: '1.0.0' }, kind: { enum: ['category', 'disposition'] }, author: { ...text, minLength: 1, maxLength: 160 },
+  reviewOf: digest, pinId: id, category: { enum: ['question', 'suggestion', 'blocker'] },
+  disposition: { enum: ['accepted', 'deferred', 'rejected'] }, reason: text,
+  updatedAt: { type: 'string', format: 'date-time' },
+}, ['schemaVersion', 'kind', 'author', 'reviewOf', 'pinId', 'updatedAt']);
+DESIGN_REVIEW_METADATA_PAYLOAD_SCHEMA.allOf = [
+  { if: { properties: { kind: { const: 'category' } } }, then: { required: ['category'], not: { required: ['disposition'] } } },
+  { if: { properties: { kind: { const: 'disposition' } } }, then: { required: ['disposition', 'reason'], not: { required: ['category'] } } },
+];
+
+// A request to change the product is distinct from a suggestion or a blocker.
+// Keep the closed 1.0.0 payload intact for existing signed review history.
+export const DESIGN_REVIEW_METADATA_PAYLOAD_V11_SCHEMA = {
+  ...structuredClone(DESIGN_REVIEW_METADATA_PAYLOAD_SCHEMA),
+  $id: 'https://openplanr.dev/schemas/v1.11.0/design-review-metadata-payload.schema.json',
+  'x-openplanr-contract': { id: 'design-review-metadata-payload', version: '1.11.0' },
+};
+Object.assign(DESIGN_REVIEW_METADATA_PAYLOAD_V11_SCHEMA.properties, {
+  schemaVersion: { const: '1.1.0' },
+  category: { enum: ['question', 'suggestion', 'change-request', 'blocker'] },
+});
+
+export function assertReviewExperience(value, contract) {
+  const errors = validateJson(value, contract);
+  if (errors.length) throw new TypeError(`Invalid ${contract['x-openplanr-contract']?.id ?? 'review data'}: ${errors.slice(0, 4).map(item => `${item.path} ${item.detail}`).join('; ')}`);
+  return value;
+}
+export function assertDesignReviewMetadata(value) {
+  return assertReviewExperience(value, value?.schemaVersion === '1.1.0' ? DESIGN_REVIEW_METADATA_PAYLOAD_V11_SCHEMA : DESIGN_REVIEW_METADATA_PAYLOAD_SCHEMA);
+}
+export function assertDesignReviewBundle(value) {
+  assertReviewExperience(value, value?.schemaVersion === '1.1.0' ? DESIGN_REVIEW_BUNDLE_V11_SCHEMA : DESIGN_REVIEW_BUNDLE_SCHEMA);
+  if (value.schemaVersion === '1.1.0') {
+    if (value.reviewContext.designId !== value.design.id || value.contextDigest !== sha256Hex(canonicalizeJson(value.reviewContext))) throw new TypeError('Review context identity or digest does not match its published design.');
+    const entries = new Set(value.entries.map(entry => `${entry.screenId}:${entry.variantId}:${entry.frameId}`));
+    const seen = new Set();
+    for (const item of value.fingerprints) {
+      const key = `${item.screenId}:${item.variantId}:${item.frameId}`;
+      if (!entries.has(key) || seen.has(key)) throw new TypeError('Review fingerprints must identify distinct published artboards.');
+      seen.add(key);
+    }
+    if (seen.size && seen.size !== entries.size) throw new TypeError('Review fingerprints must cover every published artboard.');
+  }
+  return value;
+}
+export const REVIEW_EXPERIENCE_SCHEMAS = Object.freeze({
+  'design-review-context': DESIGN_REVIEW_CONTEXT_SCHEMA,
+  'design-review-bundle': DESIGN_REVIEW_BUNDLE_V11_SCHEMA,
+  'design-review-handoff': DESIGN_HANDOFF_SCHEMA,
+  'design-review-metadata-payload': DESIGN_REVIEW_METADATA_PAYLOAD_SCHEMA,
+});

package/src/semver.d.mts

@@ -0,0 +1,2 @@
+export declare const SEMVER_PATTERN: string;
+export declare const SEMVER_REGEX: RegExp;

package/src/semver.mjs

@@ -0,0 +1,7 @@
+// Canonical SemVer 2.0.0 grammar (semver.org BNF). One source of truth so the
+// skill-source JSON Schema and the compiler graph share a single definition of
+// "exact version" and can never drift. Rejects empty dot-separated identifiers,
+// leading-zero numeric identifiers, and empty prerelease/build segments.
+export const SEMVER_PATTERN = '^(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)(?:-((?:0|[1-9][0-9]*|[0-9]*[A-Za-z-][0-9A-Za-z-]*)(?:\\.(?:0|[1-9][0-9]*|[0-9]*[A-Za-z-][0-9A-Za-z-]*))*))?(?:\\+([0-9A-Za-z-]+(?:\\.[0-9A-Za-z-]+)*))?$';
+
+export const SEMVER_REGEX = new RegExp(SEMVER_PATTERN, 'u');

package/src/skill-source-contracts.d.mts

@@ -0,0 +1,25 @@
+export declare const SKILL_SOURCE_V16_CONTRACT_FILES: Readonly<Record<string, string>>;
+export declare const DIAGRAM_V16_CONTRACT_FILES: Readonly<Record<string, string>>;
+export declare const PROTOCOL_V16_CONTRACT_FILES: Readonly<Record<string, string>>;
+export declare const SKILL_SOURCE_V17_CONTRACT_FILES: Readonly<Record<string, string>>;
+export declare const PLANNING_V17_CONTRACT_FILES: Readonly<Record<string, string>>;
+export declare const PROTOCOL_V17_CONTRACT_FILES: Readonly<Record<string, string>>;
+export declare const SKILL_PACKAGE_V18_CONTRACT_FILES: Readonly<Record<string, string>>;
+export declare const PROTOCOL_V18_CONTRACT_FILES: Readonly<Record<string, string>>;
+export declare const SKILL_SOURCE_V16_REGISTRIES: Readonly<Record<string, Readonly<{
+  kind: string;
+  protocolVersion: '1.6.0';
+}>>>;
+export declare const DIAGRAM_V16_REGISTRIES: Readonly<Record<string, Readonly<{
+  kind: string;
+  protocolVersion: '1.6.0';
+}>>>;
+export declare const PROTOCOL_V16_REGISTRIES: Readonly<Record<string, Readonly<{
+  kind: string;
+  protocolVersion: '1.6.0';
+}>>>;
+export declare const SKILL_SOURCE_V17_REGISTRIES: Readonly<Record<string, Readonly<{
+  kind: string;
+  protocolVersion: '1.7.0';
+}>>>;
+export declare const PROTOCOL_V17_REGISTRIES: typeof SKILL_SOURCE_V17_REGISTRIES;

package/src/skill-source-contracts.mjs

@@ -0,0 +1,105 @@
+// Protocol 1.6 grows by additive contract families. Keep each family explicit,
+// then expose one aggregate map to schema resolvers and browser consumers.
+export const SKILL_SOURCE_V16_CONTRACT_FILES = Object.freeze({
+  'generated-asset-manifest': 'generated-asset-manifest.schema.json',
+  'skill-catalog': 'skill-catalog.schema.json',
+  'skill-completion-receipt': 'skill-completion-receipt.schema.json',
+  'skill-consent-record': 'skill-consent-record.schema.json',
+  'skill-host-profile-registry': 'skill-host-profile-registry.schema.json',
+  'skill-learning-record': 'skill-learning-record.schema.json',
+  'skill-module-registry': 'skill-module-registry.schema.json',
+  'skill-routing-registry': 'skill-routing-registry.schema.json',
+  'skill-session': 'skill-session.schema.json',
+  'skill-source': 'skill-source.schema.json',
+});
+
+export const DIAGRAM_V16_CONTRACT_FILES = Object.freeze({
+  'diagram-consumer-reference': 'diagram-consumer-reference.schema.json',
+  'diagram-document': 'diagram-document.schema.json',
+  'diagram-fidelity-report': 'diagram-fidelity-report.schema.json',
+  'diagram-manifest': 'diagram-manifest.schema.json',
+  'diagram-quality-report': 'diagram-quality-report.schema.json',
+  'diagram-review-binding': 'diagram-review-binding.schema.json',
+  'diagram-semantic-pattern-registry': 'diagram-semantic-pattern-registry.schema.json',
+  'diagram-type-registry': 'diagram-type-registry.schema.json',
+});
+
+export const PROTOCOL_V16_CONTRACT_FILES = Object.freeze({
+  ...SKILL_SOURCE_V16_CONTRACT_FILES,
+  ...DIAGRAM_V16_CONTRACT_FILES,
+});
+
+export const SKILL_SOURCE_V17_CONTRACT_FILES = SKILL_SOURCE_V16_CONTRACT_FILES;
+
+export const PLANNING_V17_CONTRACT_FILES = Object.freeze({
+  'planning-id-sequence': 'planning-id-sequence.schema.json',
+  'request-authority': 'request-authority.schema.json',
+  spec: 'spec.schema.json',
+  story: 'story.schema.json',
+  task: 'task.schema.json',
+});
+
+export const PROTOCOL_V17_CONTRACT_FILES = Object.freeze({
+  ...SKILL_SOURCE_V17_CONTRACT_FILES,
+  ...PLANNING_V17_CONTRACT_FILES,
+});
+
+export const SKILL_PACKAGE_V18_CONTRACT_FILES = Object.freeze({
+  'skill-package': 'skill-package.schema.json',
+  'utility-command-catalog': 'utility-command-catalog.schema.json',
+});
+
+export const PROTOCOL_V18_CONTRACT_FILES = SKILL_PACKAGE_V18_CONTRACT_FILES;
+
+// Canonical classification for the additive registries stored in the shared
+// registries/ directory. Projection, preservation, and ecosystem generators
+// derive version custody from this descriptor instead of owning filename lists.
+export const SKILL_SOURCE_V16_REGISTRIES = Object.freeze({
+  'skill-host-profiles.json': Object.freeze({
+    kind: 'skill-host-profile-registry',
+    protocolVersion: '1.6.0',
+    schemaVersion: '1.1.0',
+    documentVersion: '1.1.0',
+  }),
+  'skill-modules.json': Object.freeze({
+    kind: 'skill-module-registry',
+    protocolVersion: '1.6.0',
+    schemaVersion: '1.0.0',
+    documentVersion: '1.0.0',
+  }),
+  'skill-routing.json': Object.freeze({
+    kind: 'skill-routing-registry',
+    protocolVersion: '1.6.0',
+    schemaVersion: '1.0.0',
+    documentVersion: '1.0.0',
+  }),
+});
+
+export const DIAGRAM_V16_REGISTRIES = Object.freeze({
+  'diagram-grammars.json': Object.freeze({
+    kind: 'diagram-type-registry',
+    protocolVersion: '1.6.0',
+    schemaVersion: '1.0.0',
+    documentVersion: '1.0.0',
+  }),
+  'diagram-semantic-patterns.json': Object.freeze({
+    kind: 'diagram-semantic-pattern-registry',
+    protocolVersion: '1.6.0',
+    schemaVersion: '1.0.0',
+    documentVersion: '1.0.0',
+  }),
+});
+
+export const PROTOCOL_V16_REGISTRIES = Object.freeze({
+  ...SKILL_SOURCE_V16_REGISTRIES,
+  ...DIAGRAM_V16_REGISTRIES,
+});
+
+export const SKILL_SOURCE_V17_REGISTRIES = Object.freeze(Object.fromEntries(
+  Object.entries(SKILL_SOURCE_V16_REGISTRIES).map(([file, descriptor]) => [file, Object.freeze({
+    ...descriptor,
+    protocolVersion: '1.7.0',
+  })]),
+));
+
+export const PROTOCOL_V17_REGISTRIES = SKILL_SOURCE_V17_REGISTRIES;

package/src/task-contracts.d.mts

@@ -0,0 +1,7 @@
+export interface ProtocolSemanticDiagnostic { code: string; path: string; message: string }
+export declare function validateTaskManifestSemantics(value: unknown, options?: object): ProtocolSemanticDiagnostic[];
+export declare function assertTaskManifestSemantics<T>(value: T, options?: object): T;
+export declare function validateTaskGraph(values: unknown[]): ProtocolSemanticDiagnostic[];
+export declare function countR2Tasks(values: unknown[]): number;
+export declare function validateTaskOutputSemantics(value: unknown, options?: { taskManifest?: any }): ProtocolSemanticDiagnostic[];
+export declare function assertTaskOutputSemantics<T>(value: T, options?: { taskManifest?: any }): T;