@1aboveio/skills 0.10.0

package/skills/engineering/engineering-runtime/scripts/workflow-coherence.mjs

@@ -0,0 +1,576 @@
+import { createHash } from 'node:crypto';
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { isAbsolute, join, normalize, relative } from 'node:path';
+import { isDeepStrictEqual } from 'node:util';
+
+import { isMainModule } from './main-module.mjs';
+import {
+  HARNESS_RUNTIME_DEPENDENCY_MEMBERS,
+  MATT_DEPENDENCY_MEMBERS,
+  WORKFLOW_OWNED_MEMBERS,
+  WORKFLOW_TRUSTED_DEPENDENCY_CLOSURES,
+  WORKFLOW_TRUSTED_REPAIR_RECIPE,
+  WORKFLOW_TRUSTED_SOURCES,
+} from './workflow-policy.mjs';
+
+export {
+  HARNESS_RUNTIME_DEPENDENCY_MEMBERS,
+  MATT_DEPENDENCY_MEMBERS,
+  WORKFLOW_OWNED_MEMBERS,
+  WORKFLOW_TRUSTED_DEPENDENCY_CLOSURES,
+  WORKFLOW_TRUSTED_REPAIR_RECIPE,
+} from './workflow-policy.mjs';
+
+// v2 (#996): a first-party member digests its PUBLISHED content — the file set the release ships on
+// every render target — while an external member still digests its reviewed upstream tree exactly.
+// v1 digested the exact tree for both, which made the same first-party release digest differently in
+// a private checkout and in the npm package and reported every correctly installed member modified.
+export const WORKFLOW_DIGEST_ALGORITHM = 'sha256-path-content-v2';
+export const WORKFLOW_COHERENCE_PATH = 'skills/engineering/engineering-runtime/coherence/workflow.json';
+const DIGEST = /^[0-9a-f]{64}$/;
+
+function deepFreeze(value) {
+  if (value && typeof value === 'object' && !Object.isFrozen(value)) {
+    for (const child of Object.values(value)) deepFreeze(child);
+    Object.freeze(value);
+  }
+  return value;
+}
+
+const FIRST_PARTY_SOURCE = WORKFLOW_TRUSTED_SOURCES.firstParty;
+const MATT_SOURCE = WORKFLOW_TRUSTED_SOURCES.matt;
+const MATT_MEMBER_PATHS = Object.freeze({
+  'batch-grill-me': 'skills/in-progress/batch-grill-me',
+  'code-review': 'skills/engineering/code-review',
+  'codebase-design': 'skills/engineering/codebase-design',
+  'diagnosing-bugs': 'skills/engineering/diagnosing-bugs',
+  'domain-modeling': 'skills/engineering/domain-modeling',
+  'grill-me': 'skills/productivity/grill-me',
+  'grill-with-docs': 'skills/engineering/grill-with-docs',
+  grilling: 'skills/productivity/grilling',
+  handoff: 'skills/productivity/handoff',
+  'improve-codebase-architecture': 'skills/engineering/improve-codebase-architecture',
+  prototype: 'skills/engineering/prototype',
+  research: 'skills/engineering/research',
+  'resolving-merge-conflicts': 'skills/engineering/resolving-merge-conflicts',
+  'setup-matt-pocock-skills': 'skills/engineering/setup-matt-pocock-skills',
+  tdd: 'skills/engineering/tdd',
+  'to-spec': 'skills/engineering/to-spec',
+  'to-tickets': 'skills/engineering/to-tickets',
+  triage: 'skills/engineering/triage',
+  wayfinder: 'skills/engineering/wayfinder',
+});
+export const WORKFLOW_TRUSTED_POLICY = deepFreeze({
+  members: [
+    ...MATT_DEPENDENCY_MEMBERS.map((installName) => ({
+      installName,
+      ownership: 'dependency',
+      sourcePath: MATT_MEMBER_PATHS[installName],
+      expectedSource: MATT_SOURCE,
+    })),
+    ...HARNESS_RUNTIME_DEPENDENCY_MEMBERS.map((installName) => ({
+      installName,
+      ownership: 'dependency',
+      sourcePath: 'skills/engineering/harness-runtime',
+      expectedSource: FIRST_PARTY_SOURCE,
+    })),
+    ...WORKFLOW_OWNED_MEMBERS.map((installName) => ({
+      installName,
+      ownership: 'owned',
+      sourcePath: `skills/engineering/${installName}`,
+      expectedSource: FIRST_PARTY_SOURCE,
+    })),
+  ],
+  dependencyClosures: WORKFLOW_TRUSTED_DEPENDENCY_CLOSURES,
+  repairRecipe: WORKFLOW_TRUSTED_REPAIR_RECIPE,
+});
+
+const TRUSTED_MEMBER_BY_NAME = new Map(
+  WORKFLOW_TRUSTED_POLICY.members.map((member) => [member.installName, member]),
+);
+const REPAIR_RECIPE_REFERENCE = deepFreeze({
+  id: WORKFLOW_TRUSTED_REPAIR_RECIPE.id,
+  generatedFrom: WORKFLOW_TRUSTED_REPAIR_RECIPE.generatedFrom,
+  groupId: WORKFLOW_TRUSTED_REPAIR_RECIPE.groupId,
+  lifecycle: WORKFLOW_TRUSTED_REPAIR_RECIPE.lifecycle,
+});
+const FALLBACK_SOURCE = FIRST_PARTY_SOURCE;
+
+// Install / OS debris that must never enter a member content digest. Same names
+// distribution.mjs skips when walking trees for census/generate. Without this,
+// a local `npm install` that drops package-lock.json or node_modules (gitignored)
+// silently changes digests and CI (which has a clean checkout) reports
+// member-content-modified / committed drift — residual of #791/#792 digest chores.
+const DIGEST_SKIP_NAMES = new Set([
+  'node_modules',
+  'package-lock.json',
+  '.DS_Store',
+  '.git',
+  '.unit-git',
+  '.system',
+]);
+
+// `<name>.fixture.<ext>` / `<name>.fixtures.<ext>` — this repository's convention for a recorded
+// payload that exists only so a `*.test.mjs` can replay it. Anchored on a FILE extension, which is
+// what keeps fixture DIRECTORIES included: `harness-runtime/fixtures/` is cited by a shipped
+// reference document as its machine-readable schema summary, so it is genuine payload and its name
+// (`fixtures`, no extension) cannot match.
+const TEST_FIXTURE = /\.fixtures?\.[^.]+$/;
+
+// What a first-party member's PUBLISHED content is NOT. This is the packaging rule — the same
+// predicate `skills/distribution/scripts/package-build.mjs` stages the public package with, imported
+// from here so the two cannot drift. A file the package does not carry must not enter a first-party
+// member's digest: otherwise one release digests differently on its two render targets, and the
+// checkout digest committed into workflow.json condemns every correct npm installation as modified.
+// Deliberately NOT a way to hide runtime content — everything the release ships is still digested.
+//
+// The clauses, and why each is here rather than only in one of the two callers:
+//
+//   `.`-prefixed  — `.git`, `.DS_Store` and any local tooling dotfile.
+//   node_modules  — installed dependencies, never authored payload.
+//   `*-workspace` — this repository's gitignored eval fixture convention.
+//   `*.test.mjs`  — tests are not runtime payload.
+//   TEST_FIXTURE  — dropping the test while keeping the recording it replays publishes a test
+//                   artifact, which the distribution boundary excludes on its own terms and which in
+//                   practice carries material a public tarball must not: the Mergify comment fixture
+//                   is a verbatim capture of a private-repository pull request, private repository
+//                   name included, and it was staged into the tarball for exactly as long as the two
+//                   rules disagreed (#995).
+//
+// Accepted consequence, stated rather than implied (#999): under a private-checkout install, a
+// modified `*.test.mjs` — or a modified recorded fixture — inside an installed member is no longer
+// detected by coherence, and neither reaches the public channel at all. Tests are not runtime and
+// `walkRuntimeModules` (distribution.mjs) skips them by name. The recorded fixtures in this tree are
+// all `*.fixture.json`, which that walk skips only because it collects `.mjs` alone — so a
+// `*.fixture.mjs` would be the one shape where the release scope and the dependency-closure walk
+// disagree, with the closure reaching a module the package does not ship. None exists; this note is
+// here so that the first one is a decision rather than a discovery.
+export function publishedContentExcluded(name) {
+  return name.startsWith('.')
+    || name === 'node_modules'
+    || name.endsWith('-workspace')
+    || name.endsWith('.test.mjs')
+    || TEST_FIXTURE.test(name);
+}
+
+// Whether a member's expected source identity is the first-party release — the ONE place that
+// question is answered, for the generator that computes a digest and the validator that checks it.
+//
+// It exists because the two ends used to read different fields of the same object: the generator
+// tested `expectedSource.id`, the runtime digest scope tested `expectedSource.type`. Those agree
+// today only because the manifest's first-party source happens to be NAMED `first-party`. Rename
+// that source id and the generator would digest the whole checkout tree while the validator digested
+// published content only, so every first-party member of a correct installation would report as
+// modified — on both transports, which is the exact failure the published scope exists to prevent.
+// `type` is the field carrying the meaning (`expectedSourceIdentity` branches on `source.type`, and
+// `first-party`/`external` is the source TAXONOMY); `id` is a name and may change.
+export function firstPartySource(expectedSource) {
+  return expectedSource?.type === 'first-party';
+}
+
+function collectFiles(baseDir, currentDir, excludedPaths, files, published) {
+  for (const entry of readdirSync(currentDir, { withFileTypes: true })) {
+    if (DIGEST_SKIP_NAMES.has(entry.name) || entry.name.endsWith('-workspace')) continue;
+    if (published && publishedContentExcluded(entry.name)) continue;
+    const path = join(currentDir, entry.name);
+    const relativePath = relative(baseDir, path).replaceAll('\\', '/');
+    if (excludedPaths.has(relativePath)) continue;
+    if (entry.isDirectory()) collectFiles(baseDir, path, excludedPaths, files, published);
+    else if (entry.isFile()) files.push({ path, relativePath });
+    else throw new Error(`Unsupported member content entry: ${relativePath}`);
+  }
+}
+
+/**
+ * @param {object} [options]
+ * @param {string[]} [options.exclude]  member-relative paths to omit
+ * @param {object[]} [options.injected] generated content to digest instead of reading from disk
+ * @param {boolean} [options.published] digest the member's published content — the file set the
+ *   release ships — rather than its exact tree. Set for first-party members, whose authority is the
+ *   published release; left off for external members, whose authority is the reviewed upstream tree
+ *   byte for byte. See {@link publishedContentExcluded}.
+ */
+export function contentDigest(directory, { exclude = [], injected = [], published = false } = {}) {
+  const files = [];
+  const excluded = new Set(exclude);
+  for (const file of injected) excluded.add(file.relativePath);
+  collectFiles(directory, directory, excluded, files, published);
+  for (const file of injected) files.push({ relativePath: file.relativePath, contents: file.contents });
+  files.sort((left, right) => left.relativePath.localeCompare(right.relativePath));
+  const hash = createHash('sha256');
+  for (const file of files) {
+    hash.update(file.relativePath);
+    hash.update(file.contents ?? readFileSync(file.path));
+  }
+  return hash.digest('hex');
+}
+
+export function workflowReleaseIdentity(releaseData) {
+  return createHash('sha256').update(JSON.stringify(releaseData)).digest('hex');
+}
+
+function validRelativePath(path) {
+  return typeof path === 'string'
+    && path.length > 0
+    && !isAbsolute(path)
+    && !path.split('/').includes('..')
+    && normalize(path).replaceAll('\\', '/') === path;
+}
+
+function releaseData(manifest) {
+  return {
+    schemaVersion: manifest.schemaVersion,
+    groupId: manifest.groupId,
+    ownedMembers: manifest.ownedMembers,
+    dependencies: manifest.dependencies,
+    dependencyClosures: manifest.dependencyClosures,
+    digestAlgorithm: manifest.digestAlgorithm,
+    members: manifest.members,
+  };
+}
+
+function repairRecipeReference() {
+  return REPAIR_RECIPE_REFERENCE;
+}
+
+function finding({ state, code, member, ownership, expectedSource, manifest, expectedDigest, actualDigest, detail }) {
+  return {
+    state,
+    code,
+    member,
+    ownership,
+    expectedSource,
+    ...(expectedDigest ? { expectedDigest } : {}),
+    ...(actualDigest ? { actualDigest } : {}),
+    detail,
+    repairRecipe: repairRecipeReference(manifest),
+  };
+}
+
+function exactContract(actual, expected) {
+  return isDeepStrictEqual(actual, expected);
+}
+
+function validateManifest(manifest) {
+  const findings = [];
+  const memberByName = new Map(Array.isArray(manifest?.members)
+    ? manifest.members.map((member) => [member?.installName, member])
+    : []);
+  const add = (code, memberName, detail) => {
+    const expectedMember = TRUSTED_MEMBER_BY_NAME.get(memberName);
+    const ownership = expectedMember?.ownership
+      ?? (WORKFLOW_OWNED_MEMBERS.includes(memberName) ? 'owned' : 'dependency');
+    findings.push(finding({
+      state: 'missing-manifest',
+      code,
+      member: memberName,
+      ownership,
+      expectedSource: expectedMember?.expectedSource ?? FALLBACK_SOURCE,
+      manifest,
+      detail,
+    }));
+  };
+
+  if (!manifest || manifest.schemaVersion !== 1 || manifest.groupId !== 'engineering-workflow') {
+    add('manifest-identity-invalid', 'engineering-runtime', 'The coherence schema or group identity is missing or malformed.');
+    return findings;
+  }
+  if (manifest.lifecycleAuthority !== 'native-skills-cli') {
+    add('lifecycle-authority-invalid', 'engineering-runtime', 'The coherence data must point to the native Skills CLI lifecycle authority.');
+  }
+  if (manifest.digestAlgorithm !== WORKFLOW_DIGEST_ALGORITHM) {
+    add('digest-algorithm-invalid', 'engineering-runtime', 'The coherence digest algorithm is missing or unsupported.');
+  }
+  if (JSON.stringify(manifest.ownedMembers) !== JSON.stringify(WORKFLOW_OWNED_MEMBERS)) {
+    add('owned-census-invalid', 'engineering-runtime', 'The exact eight-member Workflow ownership census is missing or malformed.');
+  }
+  if (JSON.stringify(manifest.dependencies) !== JSON.stringify([
+    { groupId: 'matt-pocock-toolkit', members: MATT_DEPENDENCY_MEMBERS },
+    { groupId: 'harness-runtime', members: HARNESS_RUNTIME_DEPENDENCY_MEMBERS },
+  ])) {
+    add('dependency-census-invalid', 'engineering-runtime', 'The exact Matt and harness runtime dependency census is missing or malformed.');
+  }
+  if (!exactContract(manifest.dependencyClosures, WORKFLOW_TRUSTED_DEPENDENCY_CLOSURES)) {
+    const names = new Set(Array.isArray(manifest.dependencyClosures)
+      ? manifest.dependencyClosures.map((closure) => closure?.invokedSkill)
+      : []);
+    const member = WORKFLOW_TRUSTED_DEPENDENCY_CLOSURES.find((closure) => !names.has(closure.invokedSkill))?.invokedSkill
+      ?? 'resolve-issues';
+    add('dependency-closure-invalid', member, 'The invoked-skill dependency closure is missing, weakened, reordered or malformed.');
+  }
+
+  const expectedOrder = [
+    ...MATT_DEPENDENCY_MEMBERS,
+    ...HARNESS_RUNTIME_DEPENDENCY_MEMBERS,
+    ...WORKFLOW_OWNED_MEMBERS,
+  ];
+  if (!Array.isArray(manifest.members)
+    || JSON.stringify(manifest.members.map((member) => member?.installName)) !== JSON.stringify(expectedOrder)) {
+    add('member-census-invalid', 'engineering-runtime', 'The dependency-first member records are missing, reordered or malformed.');
+  } else {
+    for (const memberName of expectedOrder) {
+      const member = memberByName.get(memberName);
+      const expectedMember = TRUSTED_MEMBER_BY_NAME.get(memberName);
+      const firstParty = firstPartySource(expectedMember.expectedSource);
+      if (member.ownership !== expectedMember.ownership) {
+        add('member-ownership-invalid', memberName, 'The member ownership identity is missing or malformed.');
+      }
+      if (!validRelativePath(member.sourcePath) || member.sourcePath !== expectedMember.sourcePath) {
+        add('member-source-path-invalid', memberName, 'The expected source-relative member path is missing or malformed.');
+      }
+      if (!DIGEST.test(member.contentDigest ?? '')) {
+        add('member-digest-invalid', memberName, 'The expected member content digest is missing or malformed.');
+      }
+      if (!exactContract(member.expectedSource, expectedMember.expectedSource)) {
+        add('member-source-identity-invalid', memberName, 'The expected member source identity is missing or malformed.');
+      }
+      const expectedExcludes = firstParty && memberName === 'engineering-runtime'
+        ? ['coherence/workflow.json']
+        : [];
+      if (Object.hasOwn(member, 'releaseMarker')
+        || JSON.stringify(member.digestExcludes) !== JSON.stringify(expectedExcludes)) {
+        add('member-digest-contract-invalid', memberName, 'The member digest exclusion contract is missing or malformed.');
+      }
+    }
+  }
+
+  if (!exactContract(manifest.repairRecipe, WORKFLOW_TRUSTED_REPAIR_RECIPE)) {
+    add('repair-recipe-invalid', 'engineering-runtime', 'The generated dependency-first repair recipe is missing or malformed.');
+  }
+  if (!DIGEST.test(manifest.releaseIdentity ?? '')
+    || workflowReleaseIdentity(releaseData(manifest)) !== manifest.releaseIdentity) {
+    add('release-identity-invalid', 'engineering-runtime', 'The release identity is missing, malformed or inconsistent with member data.');
+  }
+  return findings;
+}
+
+function memberDirectory(member, options) {
+  if (options.layout === 'installed') return join(options.skillsRoot, member.installName);
+  const sourceRoot = options.sourceRoots?.[member.expectedSource.id];
+  return sourceRoot ? join(sourceRoot, member.sourcePath) : null;
+}
+
+function missingManifestResult(layout, code, detail, invokedSkills) {
+  return {
+    schemaVersion: 1,
+    groupId: 'engineering-workflow',
+    layout,
+    releaseIdentity: null,
+    ...(Array.isArray(invokedSkills) ? { scope: { invokedSkills: [...invokedSkills], members: [], generatedIdentities: [] } } : {}),
+    coherent: false,
+    findings: [finding({
+      state: 'missing-manifest',
+      code,
+      member: 'engineering-runtime',
+      ownership: 'owned',
+      expectedSource: FALLBACK_SOURCE,
+      detail,
+    })],
+    repairRecipe: WORKFLOW_TRUSTED_REPAIR_RECIPE,
+  };
+}
+
+export function verifyWorkflowCoherence(options = {}) {
+  const layout = options.layout ?? 'installed';
+  if (!['installed', 'source'].includes(layout)) {
+    return missingManifestResult(layout, 'layout-invalid', 'The requested installation layout is unsupported.', options.invokedSkills);
+  }
+  const manifestPath = options.manifestPath ?? (layout === 'installed'
+    ? join(options.skillsRoot ?? '', 'engineering-runtime', 'coherence', 'workflow.json')
+    : join(options.sourceRoots?.['first-party'] ?? '', WORKFLOW_COHERENCE_PATH));
+  if (!manifestPath || !existsSync(manifestPath)) {
+    return missingManifestResult(layout, 'manifest-missing', 'The Workflow coherence manifest is missing.', options.invokedSkills);
+  }
+
+  let manifest;
+  try {
+    manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
+  } catch {
+    return missingManifestResult(layout, 'manifest-malformed', 'The Workflow coherence manifest is not valid JSON.', options.invokedSkills);
+  }
+  const manifestFindings = validateManifest(manifest);
+  if (manifestFindings.length > 0) {
+    return {
+      schemaVersion: 1,
+      groupId: 'engineering-workflow',
+      layout,
+      releaseIdentity: DIGEST.test(manifest.releaseIdentity ?? '') ? manifest.releaseIdentity : null,
+      ...(Array.isArray(options.invokedSkills) ? { scope: { invokedSkills: [...options.invokedSkills], members: [], generatedIdentities: [] } } : {}),
+      coherent: false,
+      findings: manifestFindings,
+      repairRecipe: manifestFindings.some((candidate) => candidate.code === 'repair-recipe-invalid')
+        ? WORKFLOW_TRUSTED_REPAIR_RECIPE
+        : manifest.repairRecipe,
+    };
+  }
+
+  const findings = [];
+  const requested = options.invokedSkills;
+  const invokedSkills = requested === undefined ? [] : requested;
+  const closureBySkill = new Map(manifest.dependencyClosures.map((closure) => [closure.invokedSkill, closure]));
+  const selectedNames = new Set();
+  const selectedGenerated = new Map();
+  if (!Array.isArray(invokedSkills) || invokedSkills.length === 0 && requested !== undefined
+      || invokedSkills.some((skill) => typeof skill !== 'string' || !skill.trim())
+      || new Set(invokedSkills).size !== invokedSkills.length) {
+    findings.push(finding({
+      state: 'missing-manifest', code: 'invoked-skill-invalid', member: 'engineering-runtime', ownership: 'owned',
+      expectedSource: FALLBACK_SOURCE, manifest,
+      detail: 'invokedSkills must be a non-empty array of unique installed skill names when scoped verification is requested.',
+    }));
+  } else if (requested === undefined) {
+    for (const member of manifest.members) selectedNames.add(member.installName);
+    for (const closure of manifest.dependencyClosures) {
+      for (const identity of closure.generatedIdentities) selectedGenerated.set(`${identity.member}:${identity.path}`, identity);
+    }
+  } else {
+    for (const invokedSkill of invokedSkills) {
+      const closure = closureBySkill.get(invokedSkill);
+      if (!closure) {
+        const expected = TRUSTED_MEMBER_BY_NAME.get(invokedSkill);
+        findings.push(finding({
+          state: 'missing-manifest', code: 'invoked-skill-unknown', member: invokedSkill,
+          ownership: expected?.ownership ?? 'owned', expectedSource: expected?.expectedSource ?? FALLBACK_SOURCE,
+          manifest, detail: `No trusted dependency closure exists for invoked skill ${JSON.stringify(invokedSkill)}.`,
+        }));
+        continue;
+      }
+      for (const memberName of closure.members) selectedNames.add(memberName);
+      for (const identity of closure.generatedIdentities) selectedGenerated.set(`${identity.member}:${identity.path}`, identity);
+    }
+  }
+
+  const selectedMembers = manifest.members.filter((member) => selectedNames.has(member.installName));
+  for (const member of selectedMembers) {
+    const directory = memberDirectory(member, { ...options, layout });
+    if (!directory || !existsSync(directory)) {
+      findings.push(finding({
+        state: 'missing',
+        code: 'member-missing',
+        member: member.installName,
+        ownership: member.ownership,
+        expectedSource: member.expectedSource,
+        expectedDigest: member.contentDigest,
+        manifest,
+        detail: 'The expected member directory is missing.',
+      }));
+      continue;
+    }
+
+    let actualDigest;
+    try {
+      // First-party members are digested over the release's file set on BOTH transports (ADR 0004
+      // decision 4), so a correct npm installation is not reported as modified. The scope is derived
+      // from the member's declared source rather than carried as a second field, so there is no way
+      // for a member to claim a scope its source does not have — and `validateManifest` has already
+      // proved `expectedSource` deep-equal to the trusted policy above (`member-source-identity-
+      // invalid` returns before this loop), so the derivation reads trusted data, not manifest claims.
+      actualDigest = contentDigest(directory, {
+        exclude: member.digestExcludes,
+        published: firstPartySource(member.expectedSource),
+      });
+    } catch (error) {
+      findings.push(finding({
+        state: 'modified',
+        code: 'member-content-unreadable',
+        member: member.installName,
+        ownership: member.ownership,
+        expectedSource: member.expectedSource,
+        expectedDigest: member.contentDigest,
+        manifest,
+        detail: error.message,
+      }));
+      continue;
+    }
+    if (actualDigest !== member.contentDigest) {
+      findings.push(finding({
+        state: 'modified',
+        code: 'member-content-modified',
+        member: member.installName,
+        ownership: member.ownership,
+        expectedSource: member.expectedSource,
+        expectedDigest: member.contentDigest,
+        actualDigest,
+        manifest,
+        detail: 'The installed member content does not match its deterministic digest.',
+      }));
+    }
+  }
+
+  const generatedIdentities = [];
+  const memberByName = new Map(manifest.members.map((member) => [member.installName, member]));
+  for (const identity of selectedGenerated.values()) {
+    const member = memberByName.get(identity.member);
+    const directory = member ? memberDirectory(member, { ...options, layout }) : null;
+    const generatedPath = directory ? join(directory, identity.path) : null;
+    let actualDigest = null;
+    if (generatedPath && existsSync(generatedPath)) {
+      try { actualDigest = createHash('sha256').update(readFileSync(generatedPath)).digest('hex'); } catch {}
+    }
+    generatedIdentities.push({ ...identity, digestAlgorithm: 'sha256', actualDigest });
+    if (actualDigest === null) {
+      findings.push(finding({
+        state: 'missing', code: 'generated-identity-missing', member: identity.member,
+        ownership: member?.ownership ?? 'owned', expectedSource: member?.expectedSource ?? FALLBACK_SOURCE,
+        manifest, detail: `Generated identity ${identity.path} is missing or unreadable.`,
+      }));
+    }
+  }
+
+  return {
+    schemaVersion: 1,
+    groupId: manifest.groupId,
+    layout,
+    releaseIdentity: manifest.releaseIdentity,
+    scope: {
+      invokedSkills: [...invokedSkills],
+      members: selectedMembers.map((member) => member.installName),
+      generatedIdentities,
+    },
+    coherent: findings.length === 0,
+    findings,
+    repairRecipe: manifest.repairRecipe,
+  };
+}
+
+export function runWorkflowCoherenceCli(args) {
+  if (args[0] !== 'verify') {
+    process.stderr.write(
+      'Usage: workflow-coherence.mjs verify --layout installed --skills-root <path> [--manifest <path>] [--invoked-skill <name>]...\n'
+      + '   or: workflow-coherence.mjs verify --layout source --source-root <id=path>... [--manifest <path>] [--invoked-skill <name>]...\n',
+    );
+    return 2;
+  }
+
+  const options = { sourceRoots: {} };
+  for (let index = 1; index < args.length; index += 1) {
+    const argument = args[index];
+    const value = args[index + 1];
+    if (argument === '--layout' || argument === '--skills-root' || argument === '--manifest') {
+      if (!value) return 2;
+      const key = argument === '--layout' ? 'layout' : argument === '--skills-root' ? 'skillsRoot' : 'manifestPath';
+      options[key] = value;
+      index += 1;
+    } else if (argument === '--source-root') {
+      const separator = value?.indexOf('=') ?? -1;
+      if (separator < 1 || separator === value.length - 1) return 2;
+      options.sourceRoots[value.slice(0, separator)] = value.slice(separator + 1);
+      index += 1;
+    } else if (argument === '--invoked-skill') {
+      if (!value) return 2;
+      if (!options.invokedSkills) options.invokedSkills = [];
+      options.invokedSkills.push(value);
+      index += 1;
+    } else {
+      return 2;
+    }
+  }
+
+  const result = verifyWorkflowCoherence(options);
+  process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+  return result.coherent ? 0 : 1;
+}
+
+if (isMainModule(import.meta.url)) {
+  process.exitCode = runWorkflowCoherenceCli(process.argv.slice(2));
+}