@open-agent-toolkit/cli 0.2.26 → 0.2.28

package/assets/skills/explainer-kit/scripts/lib/contracts.mjs

@@ -2,6 +2,10 @@ import { createHash } from 'node:crypto';
 import { readFileSync } from 'node:fs';
 
 import { validatePortablePath } from './safe-paths.mjs';
+import {
+  parseCanonicalGithubBlobUrl,
+  validateCanonicalGithubBlobTuple,
+} from './source-backlinks.mjs';
 
 const SCHEMA_FILES = {
   'run-request': 'run-request.schema.json',
@@ -14,6 +18,9 @@ const SCHEMA_FILES = {
   'publish-receipt': 'publish-receipt.schema.json',
   'author-request/v2': 'author-request.v2.schema.json',
   'author-result/v2': 'author-result.v2.schema.json',
+  'set-plan': 'set-plan.v1.schema.json',
+  'visual-review-request': 'visual-review-request.v1.schema.json',
+  'visual-review-result': 'visual-review-result.v1.schema.json',
 };
 const DEFAULT_SCHEMA_KEYS = {
   'author-request': 'author-request/v2',
@@ -47,6 +54,13 @@ const RAW_SECRET_KEYS = new Set([
 ]);
 const DATE_TIME_PATTERN =
   /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$/;
+const SET_PLAN_RECORD_PATHS = [
+  'source/set-plan/request.json',
+  'source/set-plan/result.json',
+  'source/set-plan/ledger.json',
+  'source/set-plan/portfolio.json',
+  'source/set-plan/drafts.json',
+];
 
 export function validateContract(kind, value, context = {}) {
   const schema = resolveContractSchema(kind, value);
@@ -68,9 +82,51 @@ export function validateContract(kind, value, context = {}) {
   validateSchema(schema, value, '$', schema, errors);
   validateContractPaths(kind, value, errors);
   validateCrossRecord(kind, value, context, errors);
+  validateSourceBacklinks(kind, value, errors);
   return { valid: errors.length === 0, errors };
 }
 
+function validateSourceBacklinks(kind, value, errors) {
+  if (kind === 'fact-base' || kind === 'explainer-kit.fact-base/v1') {
+    const tuples = [
+      ...(value.sources ?? []),
+      ...(value.claims ?? []).flatMap((claim) => claim.citations ?? []),
+      ...(value.unresolvedClaims ?? []).flatMap(
+        (claim) => claim.citations ?? [],
+      ),
+    ];
+    tuples.forEach((tuple, index) => {
+      const declaresBacklink = ['repository', 'path', 'lineRange', 'url'].some(
+        (field) => tuple[field] !== undefined,
+      );
+      if (declaresBacklink && !validateCanonicalGithubBlobTuple(tuple)) {
+        add(
+          errors,
+          `$.sourceBacklinks[${index}]`,
+          'source-backlink',
+          'Must declare one complete canonical GitHub blob backlink tuple.',
+        );
+      }
+    });
+    return;
+  }
+  if (kind !== 'manifest' && kind !== 'explainer-kit.manifest/v1') return;
+  (value.source?.backlinks ?? []).forEach((entry, index) => {
+    try {
+      parseCanonicalGithubBlobUrl(entry.url);
+    } catch (error) {
+      add(
+        errors,
+        `$.source.backlinks[${index}].url`,
+        'source-backlink',
+        error instanceof Error
+          ? error.message
+          : 'Must be a canonical GitHub blob backlink.',
+      );
+    }
+  });
+}
+
 function resolveContractSchema(kind, value) {
   if (SCHEMAS[kind]) {
     return SCHEMAS[kind];
@@ -475,6 +531,260 @@ function validateCrossRecord(kind, value, context, errors) {
         'Retaining raw art direction requires theme.artDirection.',
       );
     }
+
+    if (value.recapMode !== undefined && value.recipe?.id !== 'project-recap') {
+      add(
+        errors,
+        '$.recapMode',
+        'recap-mode-recipe',
+        'recapMode is allowed only for the project-recap recipe.',
+      );
+    }
+  }
+
+  if (kind === 'set-plan') {
+    validateSetPlan(value, errors);
+  }
+
+  if (
+    ['author-request', 'author-request/v2'].includes(kind) ||
+    value.schemaVersion === 'explainer-kit.author-request/v2'
+  ) {
+    validateAuthorSetContext(value, errors);
+    validateVisualAuthoringGuidance(value, errors);
+    validateAuthorGraphSemantics(value, errors);
+  }
+
+  if (kind === 'visual-review-request') {
+    if (
+      typeof value.requestHash === 'string' &&
+      value.requestHash !== canonicalHash(visualReviewRequestPayload(value))
+    ) {
+      add(
+        errors,
+        '$.requestHash',
+        'request-hash-mismatch',
+        'Visual review request hash does not match its canonical evidence payload.',
+      );
+    }
+    if (
+      typeof value.requestHash === 'string' &&
+      typeof value.requestId === 'string' &&
+      value.requestId !== visualReviewRequestId(value.requestHash)
+    ) {
+      add(
+        errors,
+        '$.requestId',
+        'request-id-mismatch',
+        'Visual review request identity does not match its canonical request hash.',
+      );
+    }
+    const plannedArtifactIds = Array.isArray(value.plan?.portfolio)
+      ? value.plan.portfolio.map(({ artifactId }) => artifactId)
+      : [];
+    const plannedIds = new Set(plannedArtifactIds);
+    const renderedIds = new Set();
+    const requiresObservedCohesion = value.plan?.recipe?.id === 'project-recap';
+    const expectedCohesion = expectedLedgerClaims(value.plan?.ledger);
+    const observedCohesion = new Set();
+    if (
+      requiresObservedCohesion &&
+      ['terminology', 'statuses', 'numericClaims'].some(
+        (group) => expectedCohesion[group].size === 0,
+      )
+    ) {
+      add(
+        errors,
+        '$.plan.ledger',
+        'cohesion-ledger-empty',
+        'Adaptive recap review requires non-empty terminology, status, and numeric ledger entries.',
+      );
+    }
+    for (const [index, artifact] of (Array.isArray(value.renderedArtifacts)
+      ? value.renderedArtifacts
+      : []
+    ).entries()) {
+      for (const [evidenceIndex, evidence] of (Array.isArray(artifact?.evidence)
+        ? artifact.evidence
+        : []
+      ).entries()) {
+        if (evidence?.captureIdentity !== value.captureIdentity) {
+          add(
+            errors,
+            `$.renderedArtifacts[${index}].evidence[${evidenceIndex}].captureIdentity`,
+            'browser-runtime-mismatch',
+            'Every visual-review evidence record must bind the request browser capture identity.',
+          );
+        }
+      }
+      if (!plannedIds.has(artifact?.artifactId)) {
+        add(
+          errors,
+          `$.renderedArtifacts[${index}].artifactId`,
+          'unknown-artifact',
+          'Rendered artifact is not present in the shared set plan.',
+        );
+      }
+      if (renderedIds.has(artifact?.artifactId)) {
+        add(
+          errors,
+          `$.renderedArtifacts[${index}].artifactId`,
+          'duplicate-artifact',
+          'Rendered artifact IDs must be unique.',
+        );
+      }
+      renderedIds.add(artifact?.artifactId);
+      const observations = Array.isArray(artifact?.cohesionObservations)
+        ? artifact.cohesionObservations
+        : [];
+      if (requiresObservedCohesion && observations.length === 0) {
+        add(
+          errors,
+          `$.renderedArtifacts[${index}].cohesionObservations`,
+          'cohesion-observations-empty',
+          'Every adaptive recap artifact must expose observed shared-ledger evidence.',
+        );
+      }
+      for (const [observationIndex, observation] of observations.entries()) {
+        if (
+          observation?.artifactId !== artifact?.artifactId ||
+          observation?.contentHash !== artifact?.renderedHash
+        ) {
+          add(
+            errors,
+            `$.renderedArtifacts[${index}].cohesionObservations[${observationIndex}]`,
+            'cohesion-binding-mismatch',
+            'Cohesion observations must bind to their artifact and exact rendered content hash.',
+          );
+          continue;
+        }
+        const expected = expectedCohesion[observation.group]?.get(
+          observation.claim,
+        );
+        if (
+          expected === undefined ||
+          normalizeComparable(expected) !==
+            normalizeComparable(observation.value)
+        ) {
+          add(
+            errors,
+            `$.renderedArtifacts[${index}].cohesionObservations[${observationIndex}]`,
+            'cohesion-contradiction',
+            'Observed cohesion evidence must match an applicable shared-ledger value.',
+          );
+          continue;
+        }
+        observedCohesion.add(`${observation.group}:${observation.claim}`);
+      }
+    }
+    for (const artifactId of plannedArtifactIds) {
+      if (!renderedIds.has(artifactId)) {
+        add(
+          errors,
+          '$.renderedArtifacts',
+          'missing-artifact',
+          `Rendered review set is missing planned artifact ${artifactId}.`,
+        );
+      }
+    }
+    if (requiresObservedCohesion) {
+      for (const [group, claims] of Object.entries(expectedCohesion)) {
+        for (const claim of claims.keys()) {
+          if (!observedCohesion.has(`${group}:${claim}`)) {
+            add(
+              errors,
+              '$.renderedArtifacts',
+              'cohesion-claim-unobserved',
+              `Shared-ledger claim ${group}.${claim} is not observable in the rendered set.`,
+            );
+          }
+        }
+      }
+    }
+  }
+
+  if (kind === 'visual-review-result') {
+    const reviewRequest = context.visualReviewRequest;
+    if (!isObject(reviewRequest)) {
+      add(
+        errors,
+        '$',
+        'review-request-required',
+        'Visual review results must be validated with their reviewed request.',
+      );
+      return;
+    }
+
+    const requestValidation = validateContract(
+      'visual-review-request',
+      reviewRequest,
+    );
+    if (!requestValidation.valid) {
+      add(
+        errors,
+        '$',
+        'invalid-review-request',
+        'Visual review result cannot bind to an invalid reviewed request.',
+      );
+    }
+    if (
+      value.requestId !== reviewRequest.requestId ||
+      value.requestHash !== reviewRequest.requestHash
+    ) {
+      add(
+        errors,
+        '$.requestHash',
+        'review-binding-mismatch',
+        'Visual review result must echo the exact reviewed request identity and hash.',
+      );
+    }
+
+    const reviewedArtifactIds = Array.isArray(reviewRequest.renderedArtifacts)
+      ? reviewRequest.renderedArtifacts.map(({ artifactId }) => artifactId)
+      : [];
+    const reviewedIds = new Set(reviewedArtifactIds);
+    const resultArtifactIds = Array.isArray(value.artifactIds)
+      ? value.artifactIds
+      : [];
+    const resultIds = new Set(resultArtifactIds);
+    if (
+      resultIds.size !== reviewedIds.size ||
+      reviewedArtifactIds.some((artifactId) => !resultIds.has(artifactId))
+    ) {
+      add(
+        errors,
+        '$.artifactIds',
+        'review-set-mismatch',
+        'Visual review result artifact IDs must equal the complete reviewed request set.',
+      );
+    }
+    for (const [index, finding] of (Array.isArray(value.findings)
+      ? value.findings
+      : []
+    ).entries()) {
+      if (!reviewedIds.has(finding?.artifactId)) {
+        add(
+          errors,
+          `$.findings[${index}].artifactId`,
+          'detached-finding',
+          'Visual review findings must reference an artifact in the reviewed request.',
+        );
+      }
+    }
+    const findingCount = Array.isArray(value.findings)
+      ? value.findings.length
+      : 0;
+    if (
+      (value.disposition === 'pass' && findingCount > 0) ||
+      (['correct', 'fail'].includes(value.disposition) && findingCount === 0)
+    ) {
+      add(
+        errors,
+        '$.disposition',
+        'disposition-findings-mismatch',
+        'Pass requires no findings; correct and fail require at least one correction finding.',
+      );
+    }
   }
 
   if (kind === 'manifest') {
@@ -533,10 +843,17 @@ function validateCrossRecord(kind, value, context, errors) {
       'run-request.json',
       'source/content-approval.json',
     ];
+    const recordedImmutable = isObject(value.immutableHashes)
+      ? new Set(Object.keys(value.immutableHashes))
+      : new Set();
+    const retainsSetPlan =
+      value.recipe?.id === 'project-recap' ||
+      SET_PLAN_RECORD_PATHS.some((path) => recordedImmutable.has(path));
     const expectedImmutable = new Set([
       ...requiredProvenance,
       value.source?.factBasePath,
       'source/fact-base.md',
+      ...(retainsSetPlan ? SET_PLAN_RECORD_PATHS : []),
       ...(Array.isArray(value.source?.authorResultPaths)
         ? value.source.authorResultPaths
         : []),
@@ -552,9 +869,6 @@ function validateCrossRecord(kind, value, context, errors) {
         : []),
     ]);
     expectedImmutable.delete(undefined);
-    const recordedImmutable = isObject(value.immutableHashes)
-      ? new Set(Object.keys(value.immutableHashes))
-      : new Set();
     const missingLegacyPaths = requiredProvenance.filter(
       (path) => !recordedImmutable.has(path),
     );
@@ -566,17 +880,46 @@ function validateCrossRecord(kind, value, context, errors) {
         `Legacy manifest is missing immutable coverage for ${missingLegacyPaths.join(', ')}; regenerate the recap package before archival.`,
       );
     }
+    if ([...expectedImmutable].some((path) => !recordedImmutable.has(path))) {
+      add(
+        errors,
+        '$.immutableHashes',
+        'immutable-package-incomplete',
+        'Manifest immutable hashes must cover the complete retained fact-base, set plan, content, theme, and required built artifact package.',
+      );
+    }
+    const hasVisualEvidence = [...recordedImmutable].some((path) =>
+      path.startsWith('qa/visual-review/'),
+    );
     if (
-      expectedImmutable.size !== recordedImmutable.size ||
-      [...expectedImmutable].some((path) => !recordedImmutable.has(path))
+      hasVisualEvidence &&
+      [
+        'qa/visual-review/attempt-1/request.json',
+        'qa/visual-review/attempt-1/result.json',
+      ].some((path) => !recordedImmutable.has(path))
     ) {
       add(
         errors,
         '$.immutableHashes',
-        'immutable-package-incomplete',
-        'Manifest immutable hashes must cover the complete retained fact-base, content, theme, and required built artifact package.',
+        'visual-review-chain-incomplete',
+        'Retained visual review evidence requires its bound attempt request and result.',
       );
     }
+    for (const path of recordedImmutable) {
+      if (
+        (path.startsWith('qa/browser/') ||
+          path.includes('/visual-review/attempt-')) &&
+        path.endsWith('.png') &&
+        !recordedImmutable.has(path.replace(/\.png$/, '.json'))
+      ) {
+        add(
+          errors,
+          '$.immutableHashes',
+          'visual-review-chain-incomplete',
+          `Screenshot evidence ${path} is missing its immutable metrics record.`,
+        );
+      }
+    }
 
     const record = context.buildRecord;
     if (isObject(record)) {
@@ -636,10 +979,24 @@ function validateCrossRecord(kind, value, context, errors) {
   ) {
     const expected = new Map();
     for (const artifact of context.manifest.artifacts ?? []) {
-      if (isObject(artifact) && typeof artifact.renderedPath === 'string') {
+      if (
+        isObject(artifact) &&
+        artifact.status === 'built' &&
+        typeof artifact.renderedPath === 'string'
+      ) {
         expected.set(artifact.renderedPath, artifact.hash);
       }
     }
+    if (
+      isObject(context.catalogArtifact) &&
+      typeof context.catalogArtifact.relativePath === 'string'
+    ) {
+      expected.set(
+        context.catalogArtifact.relativePath,
+        context.catalogArtifact.hash,
+      );
+    }
+    const received = new Set();
     for (const artifact of value.artifacts) {
       if (
         isObject(artifact) &&
@@ -652,6 +1009,227 @@ function validateCrossRecord(kind, value, context, errors) {
           'Publish receipt artifact does not match the manifest.',
         );
       }
+      if (received.has(artifact?.relativePath)) {
+        add(
+          errors,
+          '$.artifacts',
+          'receipt-artifact-parity',
+          'Publish receipt artifact paths must be unique.',
+        );
+      }
+      received.add(artifact?.relativePath);
+    }
+    if (
+      received.size !== expected.size ||
+      [...expected.keys()].some((path) => !received.has(path))
+    ) {
+      add(
+        errors,
+        '$.artifacts',
+        'receipt-artifact-parity',
+        'Publish receipt must exactly cover every manifest artifact and the generated catalog.',
+      );
+    }
+  }
+}
+
+export function visualReviewRequestPayload(request) {
+  const {
+    requestId: _requestId,
+    requestHash: _requestHash,
+    ...payload
+  } = request;
+  return payload;
+}
+
+export function visualReviewRequestId(requestHash) {
+  return `visual-review-${String(requestHash).replace(/^sha256:/, '')}`;
+}
+
+function expectedLedgerClaims(ledger) {
+  return {
+    terminology: new Map(
+      (ledger?.terminology ?? []).map(({ term }) => [term, term]),
+    ),
+    statuses: new Map(
+      (ledger?.statuses ?? []).map(({ subject, value }) => [subject, value]),
+    ),
+    numericClaims: new Map(
+      (ledger?.numbers ?? []).map(({ subject, value }) => [subject, value]),
+    ),
+  };
+}
+
+function normalizeComparable(value) {
+  return String(value).trim().toLocaleLowerCase();
+}
+
+function validateSetPlan(value, errors) {
+  const sourceIds = new Set(
+    Array.isArray(value.sourceIds) ? value.sourceIds : [],
+  );
+  const artifactIds = new Set();
+  for (const [index, artifact] of (Array.isArray(value.portfolio)
+    ? value.portfolio
+    : []
+  ).entries()) {
+    if (artifactIds.has(artifact?.artifactId)) {
+      add(
+        errors,
+        `$.portfolio[${index}].artifactId`,
+        'duplicate-artifact',
+        'Set-plan artifact IDs must be unique.',
+      );
+    }
+    artifactIds.add(artifact?.artifactId);
+    for (const sourceId of Array.isArray(artifact?.sourceIds)
+      ? artifact.sourceIds
+      : []) {
+      if (!sourceIds.has(sourceId)) {
+        add(
+          errors,
+          `$.portfolio[${index}].sourceIds`,
+          'unknown-source',
+          `Artifact source ${sourceId} is not declared by the set plan.`,
+        );
+      }
+    }
+    if (artifact?.required === false && !isObject(artifact.justification)) {
+      add(
+        errors,
+        `$.portfolio[${index}].justification`,
+        'optional-justification-required',
+        'Optional artifacts require a source-backed justification.',
+      );
+    }
+    for (const sourceId of Array.isArray(artifact?.justification?.sourceIds)
+      ? artifact.justification.sourceIds
+      : []) {
+      if (!sourceIds.has(sourceId) || !artifact.sourceIds?.includes(sourceId)) {
+        add(
+          errors,
+          `$.portfolio[${index}].justification.sourceIds`,
+          'unknown-source',
+          `Justification source ${sourceId} must be declared by the plan and artifact.`,
+        );
+      }
+    }
+  }
+
+  for (const [field, identity] of [
+    ['terminology', (entry) => entry?.term],
+    ['statuses', (entry) => entry?.subject],
+    ['numbers', (entry) => entry?.subject],
+  ]) {
+    const seen = new Map();
+    for (const [index, entry] of (Array.isArray(value.ledger?.[field])
+      ? value.ledger[field]
+      : []
+    ).entries()) {
+      const key = identity(entry);
+      if (
+        seen.has(key) &&
+        canonicalStringify(seen.get(key)) !== canonicalStringify(entry)
+      ) {
+        add(
+          errors,
+          `$.ledger.${field}[${index}]`,
+          'ledger-conflict',
+          `Shared ledger contains conflicting values for ${key}.`,
+        );
+      }
+      seen.set(key, entry);
+    }
+  }
+}
+
+function validateAuthorSetContext(value, errors) {
+  if (!isObject(value.setContext) || !isObject(value.plannedArtifact)) {
+    return;
+  }
+  const planned = Array.isArray(value.setContext.portfolio)
+    ? value.setContext.portfolio.find(
+        ({ artifactId }) => artifactId === value.artifactId,
+      )
+    : undefined;
+  if (
+    !planned ||
+    value.plannedArtifact.artifactId !== value.artifactId ||
+    value.plannedArtifact.artifactType !== value.artifactType
+  ) {
+    add(
+      errors,
+      '$.plannedArtifact',
+      'set-artifact-mismatch',
+      'Author request identity must match one artifact in the shared set plan.',
+    );
+    return;
+  }
+  if (!deepEqual(planned, value.plannedArtifact)) {
+    add(
+      errors,
+      '$.plannedArtifact',
+      'set-plan-drift',
+      'Author request planned artifact must be identical to the shared set plan entry.',
+    );
+  }
+}
+
+function validateVisualAuthoringGuidance(value, errors) {
+  if (typeof value.visualAuthoringGuidance !== 'string') {
+    return;
+  }
+  const guidance = value.visualAuthoringGuidance.toLowerCase();
+  const missing = [
+    'representation',
+    'hierarchy',
+    'responsive navigation',
+    'table',
+    'diagram',
+    'deck',
+  ].filter((topic) => !guidance.includes(topic));
+  if (missing.length > 0) {
+    add(
+      errors,
+      '$.visualAuthoringGuidance',
+      'malformed-authoring-guidance',
+      `Visual authoring guidance is missing bundled topics: ${missing.join(', ')}.`,
+    );
+  }
+}
+
+function validateAuthorGraphSemantics(value, errors) {
+  if (value.graphSemantics === undefined) {
+    return;
+  }
+  if (value.authoring !== 'html' || !Array.isArray(value.graphSemantics)) {
+    add(
+      errors,
+      '$.graphSemantics',
+      'graph-semantics',
+      'Planner-owned graph semantics are allowed only for artistic HTML authoring.',
+    );
+    return;
+  }
+  for (const [graphIndex, graph] of value.graphSemantics.entries()) {
+    if (!isObject(graph)) continue;
+    const nodes = Array.isArray(graph.nodes) ? graph.nodes : [];
+    const edges = Array.isArray(graph.edges) ? graph.edges : [];
+    const nodeIds = nodes.map(({ id }) => id);
+    const edgeIds = edges.map(({ from, to }) => `${from}\0${to}`);
+    if (
+      new Set(nodeIds).size !== nodeIds.length ||
+      new Set(edgeIds).size !== edgeIds.length ||
+      edges.some(
+        ({ from, to }) => !nodeIds.includes(from) || !nodeIds.includes(to),
+      )
+    ) {
+      add(
+        errors,
+        `$.graphSemantics[${graphIndex}]`,
+        'graph-semantics',
+        'Graph semantics require unique nodes and edges with declared endpoints.',
+      );
     }
   }
 }