@openplanr/protocol 0.2.0

package/src/index.d.mts

@@ -0,0 +1,10 @@
+export * from './errors.mjs';
+export * from './canonical-json.mjs';
+export * from './json-schema.mjs';
+export * from './registries.mjs';
+export * from './browser-contracts.mjs';
+export * from './task-contracts.mjs';
+export * from './planning-contracts.mjs';
+export * from './diagram-contracts.mjs';
+export * from './enterprise-contracts.mjs';
+export * from './design-publication-contracts.mjs';

package/src/index.mjs

@@ -0,0 +1,40 @@
+export { ARTIFACT_ERROR_CODES, PIPELINE_ERROR_CODES, PROTOCOL_ERROR_CODES, PipelineError, ProtocolError } from './errors.mjs';
+export { canonicalizeJson, sha256Hex, sha256Jcs, verifyDocumentDigest, withDocumentDigest } from './canonical-json.mjs';
+export { validate, validateJson } from './json-schema.mjs';
+export {
+  CANONICAL_REGISTRIES,
+  getCanonicalRegistry,
+  getOutput,
+  getOutputPathTemplate,
+  getRole,
+  resolveOutputPath,
+  resolveLegacyRoleAlias,
+  resolveTaskKind,
+  routeLegacyTask,
+  validateCanonicalRegistries,
+} from './registries.mjs';
+export {
+  PROTOCOL_V15_CONTRACTS,
+  PROTOCOL_V16_CONTRACTS,
+  PROTOCOL_V17_CONTRACTS,
+  PROTOCOL_V18_CONTRACTS,
+  protocolAssetUrl,
+} from './browser-contracts.mjs';
+export { normalizePlanningTask, validatePlanningAcceptanceCoverage } from './planning-contracts.mjs';
+export {
+  DIAGRAM_CONTRACT_FILES,
+  DIAGRAM_GRAMMAR_REGISTRY,
+  DIAGRAM_SEMANTIC_PATTERN_REGISTRY,
+  diagramContractUrl,
+  getDiagramGrammar,
+} from './diagram-contracts.mjs';
+export {
+  assertTaskManifestSemantics,
+  assertTaskOutputSemantics,
+  countR2Tasks,
+  validateTaskGraph,
+  validateTaskManifestSemantics,
+  validateTaskOutputSemantics,
+} from './task-contracts.mjs';
+export * from './enterprise-contracts.mjs';
+export * from './design-publication-contracts.mjs';

package/src/json-schema.d.mts

@@ -0,0 +1,7 @@
+export interface JsonSchemaDiagnostic { path: string; rule: string; detail: string }
+export interface JsonSchemaResolverResult { schema: unknown; rootSchema?: unknown; base?: string }
+export declare function validateJson(value: unknown, schema: unknown, options?: {
+  base?: string | null;
+  resolveRef?: (reference: string, context: { base?: string | null }) => JsonSchemaResolverResult | unknown;
+}): JsonSchemaDiagnostic[];
+export { validateJson as validate };

package/src/json-schema.mjs

@@ -0,0 +1,283 @@
+/**
+ * Minimal JSON Schema (draft 2020-12) subset extracted from conformance/runner.mjs.
+ * Supports the constructs used by packaged Protocol schemas, including local
+ * JSON-pointer and caller-resolved external `$ref` references.
+ *
+ * Zero third-party deps. Safe to import from node:test suites.
+ */
+
+// ── minimal JSON Schema validator (draft 2020-12 subset) ────────────────
+
+const typeOf = (v) => {
+  if (v === null) return 'null';
+  if (Array.isArray(v)) return 'array';
+  if (Number.isInteger(v)) return 'integer';
+  if (typeof v === 'number') return 'number';
+  return typeof v;
+};
+
+const matchesType = (v, t) => {
+  if (t === 'integer') return Number.isInteger(v);
+  if (t === 'number') return typeof v === 'number';
+  if (t === 'string') return typeof v === 'string';
+  if (t === 'boolean') return typeof v === 'boolean';
+  if (t === 'null') return v === null;
+  if (t === 'array') return Array.isArray(v);
+  if (t === 'object') return v !== null && typeof v === 'object' && !Array.isArray(v);
+  return false;
+};
+
+const FORMAT_DATE = /^\d{4}-\d{2}-\d{2}$/;
+const FORMAT_DATETIME = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$/;
+
+function resolveJsonPointer(root, reference) {
+  if (reference === '#') return root;
+  if (!reference.startsWith('#/')) return null;
+  return reference
+    .slice(2)
+    .split('/')
+    .map((part) => part.replaceAll('~1', '/').replaceAll('~0', '~'))
+    .reduce((value, part) => value?.[part], root);
+}
+
+const validateNode = (value, schema, path, errs, context) => {
+  if (schema === true) return;
+  if (schema === false) {
+    errs.push({ path, rule: 'schema:false', detail: 'value not allowed' });
+    return;
+  }
+
+  if (typeof schema?.$ref === 'string') {
+    const reference = schema.$ref;
+    let resolved;
+    let nextRoot = context.rootSchema;
+    let resolvedBase = context.base;
+    if (reference.startsWith('#')) {
+      resolved = resolveJsonPointer(context.rootSchema, reference);
+    } else if (typeof context.resolveRef === 'function') {
+      const result = context.resolveRef(reference, { base: context.base });
+      resolved = result?.schema ?? result;
+      nextRoot = result?.rootSchema ?? resolved;
+      resolvedBase = result?.base ?? resolved?.$id ?? context.base;
+    }
+    if (!resolved) {
+      errs.push({ path, rule: '$ref', detail: `could not resolve schema reference ${reference}` });
+      return;
+    }
+    const referenceKey = `${context.base ?? '<root>'}:${reference}`;
+    if (context.referenceStack.includes(referenceKey)) {
+      errs.push({ path, rule: '$ref', detail: `circular schema reference ${reference}` });
+      return;
+    }
+    validateNode(value, resolved, path, errs, {
+      ...context,
+      rootSchema: nextRoot,
+      base: resolvedBase,
+      referenceStack: [...context.referenceStack, referenceKey],
+    });
+  }
+
+  if (schema.type !== undefined) {
+    const types = Array.isArray(schema.type) ? schema.type : [schema.type];
+    if (!types.some((t) => matchesType(value, t))) {
+      errs.push({ path, rule: 'type', detail: `expected ${types.join('|')}, got ${typeOf(value)}` });
+      return;
+    }
+  }
+
+  if (schema.const !== undefined) {
+    if (value !== schema.const) {
+      errs.push({ path, rule: 'const', detail: `expected ${JSON.stringify(schema.const)}, got ${JSON.stringify(value)}` });
+    }
+  }
+
+  if (Array.isArray(schema.enum)) {
+    if (!schema.enum.includes(value)) {
+      errs.push({
+        path,
+        rule: 'enum',
+        detail: `value ${JSON.stringify(value)} not in enum [${schema.enum.map((x) => JSON.stringify(x)).join(', ')}]`,
+      });
+    }
+  }
+
+  if (typeof value === 'string') {
+    if (typeof schema.minLength === 'number' && value.length < schema.minLength) {
+      errs.push({ path, rule: 'minLength', detail: `length ${value.length} < ${schema.minLength}` });
+    }
+    if (typeof schema.maxLength === 'number' && value.length > schema.maxLength) {
+      errs.push({ path, rule: 'maxLength', detail: `length ${value.length} > ${schema.maxLength}` });
+    }
+    if (typeof schema.pattern === 'string') {
+      try {
+        if (!new RegExp(schema.pattern).test(value)) {
+          errs.push({ path, rule: 'pattern', detail: `value ${JSON.stringify(value)} does not match /${schema.pattern}/` });
+        }
+      } catch (e) {
+        errs.push({ path, rule: 'pattern', detail: `invalid regex /${schema.pattern}/: ${e.message}` });
+      }
+    }
+    if (typeof schema.format === 'string') {
+      if (schema.format === 'date' && !FORMAT_DATE.test(value)) {
+        errs.push({ path, rule: 'format:date', detail: `value ${JSON.stringify(value)} is not YYYY-MM-DD` });
+      } else if (schema.format === 'date-time' && !FORMAT_DATETIME.test(value)) {
+        errs.push({ path, rule: 'format:date-time', detail: `value ${JSON.stringify(value)} is not ISO 8601 date-time` });
+      }
+    }
+  }
+
+  if (typeof value === 'number') {
+    if (typeof schema.minimum === 'number' && value < schema.minimum) {
+      errs.push({ path, rule: 'minimum', detail: `value ${value} < ${schema.minimum}` });
+    }
+    if (typeof schema.maximum === 'number' && value > schema.maximum) {
+      errs.push({ path, rule: 'maximum', detail: `value ${value} > ${schema.maximum}` });
+    }
+  }
+
+  if (Array.isArray(value)) {
+    if (typeof schema.minItems === 'number' && value.length < schema.minItems) {
+      errs.push({ path, rule: 'minItems', detail: `length ${value.length} < ${schema.minItems}` });
+    }
+    if (typeof schema.maxItems === 'number' && value.length > schema.maxItems) {
+      errs.push({ path, rule: 'maxItems', detail: `length ${value.length} > ${schema.maxItems}` });
+    }
+    const prefixLength = Array.isArray(schema.prefixItems) ? schema.prefixItems.length : 0;
+    if (prefixLength > 0) {
+      for (let i = 0; i < Math.min(value.length, prefixLength); i++) {
+        validateNode(value[i], schema.prefixItems[i], `${path}[${i}]`, errs, context);
+      }
+    }
+    if (schema.items !== undefined) {
+      for (let i = prefixLength; i < value.length; i++) {
+        validateNode(value[i], schema.items, `${path}[${i}]`, errs, context);
+      }
+    }
+    if (schema.uniqueItems === true) {
+      const seen = new Set();
+      for (const item of value) {
+        const key = JSON.stringify(item);
+        if (seen.has(key)) {
+          errs.push({ path, rule: 'uniqueItems', detail: `duplicate item ${key}` });
+          break;
+        }
+        seen.add(key);
+      }
+    }
+    if (schema.contains !== undefined) {
+      let matches = 0;
+      for (let index = 0; index < value.length; index += 1) {
+        const containedErrors = [];
+        validateNode(value[index], schema.contains, `${path}[${index}]`, containedErrors, context);
+        if (containedErrors.length === 0) matches += 1;
+      }
+      const minimum = Number.isSafeInteger(schema.minContains) ? schema.minContains : 1;
+      const maximum = Number.isSafeInteger(schema.maxContains) ? schema.maxContains : null;
+      if (matches < minimum) {
+        errs.push({ path, rule: 'contains', detail: `matched ${matches} contained items; expected at least ${minimum}` });
+      }
+      if (maximum !== null && matches > maximum) {
+        errs.push({ path, rule: 'contains', detail: `matched ${matches} contained items; expected at most ${maximum}` });
+      }
+    }
+  }
+
+  if (value !== null && typeof value === 'object' && !Array.isArray(value)) {
+    if (Array.isArray(schema.required)) {
+      for (const req of schema.required) {
+        if (!Object.hasOwn(value, req)) {
+          errs.push({ path, rule: 'required', detail: `missing required property '${req}'` });
+        }
+      }
+    }
+    const props = schema.properties || {};
+    for (const [k, v] of Object.entries(value)) {
+      if (!Object.hasOwn(props, k)) {
+        if (schema.additionalProperties === false) {
+          errs.push({ path, rule: 'additionalProperties', detail: `unknown property '${k}'` });
+        } else if (
+          schema.additionalProperties === true
+          || (schema.additionalProperties !== null && typeof schema.additionalProperties === 'object')
+        ) {
+          validateNode(v, schema.additionalProperties, `${path}.${k}`, errs, context);
+        }
+      }
+    }
+    for (const [k, v] of Object.entries(value)) {
+      if (Object.hasOwn(props, k)) validateNode(v, props[k], `${path}.${k}`, errs, context);
+    }
+  }
+
+  if (Array.isArray(schema.oneOf)) {
+    let matched = 0;
+    for (const sub of schema.oneOf) {
+      const e = [];
+      validateNode(value, sub, path, e, context);
+      if (e.length === 0) matched++;
+    }
+    if (matched !== 1) {
+      const titles = schema.oneOf.map((s) => s.title || '(unnamed)').join(' | ');
+      errs.push({
+        path,
+        rule: 'oneOf',
+        detail: `matched ${matched}/${schema.oneOf.length} branches (expected exactly 1). Branches: ${titles}`,
+      });
+    }
+  }
+
+  if (Array.isArray(schema.anyOf)) {
+    let matched = 0;
+    for (const sub of schema.anyOf) {
+      const candidateErrors = [];
+      validateNode(value, sub, path, candidateErrors, context);
+      if (candidateErrors.length === 0) matched += 1;
+    }
+    if (matched === 0) {
+      const titles = schema.anyOf.map((sub) => sub.title || '(unnamed)').join(' | ');
+      errs.push({
+        path,
+        rule: 'anyOf',
+        detail: `matched 0/${schema.anyOf.length} branches (expected at least 1). Branches: ${titles}`,
+      });
+    }
+  }
+
+  if (Array.isArray(schema.allOf)) {
+    for (const sub of schema.allOf) {
+      validateNode(value, sub, path, errs, context);
+    }
+  }
+
+  if (schema.if !== undefined) {
+    const conditionErrors = [];
+    validateNode(value, schema.if, path, conditionErrors, context);
+    const branch = conditionErrors.length === 0 ? schema.then : schema.else;
+    if (branch !== undefined) validateNode(value, branch, path, errs, context);
+  }
+
+  if (schema.not !== undefined) {
+    const e = [];
+    validateNode(value, schema.not, path, e, context);
+    if (e.length === 0) {
+      errs.push({ path, rule: 'not', detail: 'value matched a forbidden subschema' });
+    }
+  }
+};
+
+/** @returns {{ path: string, rule: string, detail: string }[]} */
+export const validateJson = (value, schema, {
+  resolveRef = null,
+  base = schema?.$id ?? null,
+} = {}) => {
+  const errs = [];
+  validateNode(value, schema, '$', errs, {
+    rootSchema: schema,
+    resolveRef,
+    base,
+    referenceStack: [],
+  });
+  return errs;
+};
+
+/** Alias matching legacy runner export name. */
+export const validate = validateJson;

package/src/planning-contracts.d.mts

@@ -0,0 +1,10 @@
+export interface PlanningIssue { path: string; rule: string; detail: string }
+export declare function normalizePlanningTask<T extends Record<string, unknown>>(value: T): T & {
+  reviewRisks: string[];
+  browserSurfaces: string[];
+  acceptanceRefs: string[];
+};
+export declare function validatePlanningAcceptanceCoverage(
+  stories: ReadonlyArray<Record<string, unknown>>,
+  tasks: ReadonlyArray<Record<string, unknown>>,
+): PlanningIssue[];

package/src/planning-contracts.mjs

@@ -0,0 +1,53 @@
+const LEGACY_TASK_FIELDS = Object.freeze({
+  review_risks: 'reviewRisks',
+  browser_surfaces: 'browserSurfaces',
+  acceptance_refs: 'acceptanceRefs',
+});
+
+/** Translate released snake-case task metadata into the canonical 1.7 names. */
+export function normalizePlanningTask(value) {
+  const task = structuredClone(value ?? {});
+  for (const [legacy, canonical] of Object.entries(LEGACY_TASK_FIELDS)) {
+    if (task[canonical] === undefined && task[legacy] !== undefined) task[canonical] = task[legacy];
+    delete task[legacy];
+  }
+  task.reviewRisks ??= [];
+  task.browserSurfaces ??= [];
+  task.acceptanceRefs ??= [];
+  return task;
+}
+
+/** Validate that every story criterion is assigned and named in task verification. */
+export function validatePlanningAcceptanceCoverage(stories, tasks) {
+  const issues = [];
+  const tasksByStory = new Map();
+  for (const rawTask of tasks ?? []) {
+    const task = normalizePlanningTask(rawTask);
+    const bucket = tasksByStory.get(task.storyId) ?? [];
+    bucket.push(task);
+    tasksByStory.set(task.storyId, bucket);
+  }
+  for (const story of stories ?? []) {
+    const criteria = story.acceptanceCriteria ?? [];
+    const ids = new Set(criteria.map((criterion) => criterion.id));
+    if (ids.size !== criteria.length) {
+      issues.push({ path: `${story.id}.acceptanceCriteria`, rule: 'unique', detail: 'Acceptance IDs must be unique within the story.' });
+    }
+    for (const criterion of criteria) {
+      const mapped = (tasksByStory.get(story.id) ?? []).filter((task) => task.acceptanceRefs.includes(criterion.id));
+      if (mapped.length === 0) {
+        issues.push({ path: `${story.id}.${criterion.id}`, rule: 'coverage', detail: 'Acceptance criterion is not mapped to a task.' });
+        continue;
+      }
+      if (mapped.every((task) => !String(task.testRequirements ?? '').includes(criterion.id))) {
+        issues.push({ path: `${story.id}.${criterion.id}`, rule: 'verification', detail: 'A mapped task must name the acceptance ID in Test Requirements.' });
+      }
+    }
+    for (const task of tasksByStory.get(story.id) ?? []) {
+      for (const reference of task.acceptanceRefs) {
+        if (!ids.has(reference)) issues.push({ path: `${task.id}.acceptanceRefs`, rule: 'reference', detail: `${reference} is not declared by ${story.id}.` });
+      }
+    }
+  }
+  return issues;
+}

package/src/registries.d.mts

@@ -0,0 +1,40 @@
+export interface CanonicalRegistries {
+  readonly 'roles.json': Record<string, unknown>;
+  readonly 'task-kinds.json': Record<string, unknown>;
+  readonly 'rules.json': Record<string, unknown>;
+  readonly 'commands.json': Record<string, unknown>;
+  readonly 'skills.json': Record<string, unknown>;
+  readonly 'outputs.json': Record<string, unknown>;
+  readonly 'output-paths.json'?: Record<string, unknown>;
+}
+export type OutputProjectMode = 'default' | 'spec-driven';
+export interface ProjectModePathTemplates {
+  readonly default: string;
+  readonly 'spec-driven': string;
+}
+export interface OutputCatalogEntry extends Record<string, unknown> {
+  readonly outputId: string;
+  readonly pathTemplate: string;
+}
+export interface ResolveOutputPathOptions {
+  readonly projectMode?: OutputProjectMode;
+  readonly pathArguments?: Readonly<Record<string, string>>;
+}
+export declare const CANONICAL_REGISTRIES: CanonicalRegistries;
+export declare function getCanonicalRegistry(name: keyof CanonicalRegistries): Record<string, unknown>;
+export declare function validateCanonicalRegistries(registries?: CanonicalRegistries): true;
+export declare function getRole(roleId: string): Record<string, unknown>;
+export declare function resolveLegacyRoleAlias(alias: string): Record<string, unknown> | null;
+export declare function resolveTaskKind(taskKind: string): Record<string, unknown>;
+export declare function getOutput(outputId: string, registries?: CanonicalRegistries): OutputCatalogEntry;
+export declare function getOutputPathTemplate(
+  outputId: string,
+  projectMode?: OutputProjectMode,
+  registries?: CanonicalRegistries,
+): string;
+export declare function resolveOutputPath(
+  outputId: string,
+  options?: ResolveOutputPathOptions,
+  registries?: CanonicalRegistries,
+): string;
+export declare function routeLegacyTask(value: { legacyType: 'UI' | 'Tech'; legacyAgent?: string | null }): Record<string, unknown>;