@rpamis/comet 0.4.0-beta.1 → 0.4.0-beta.11

package/dist/domains/factory/package.js

@@ -2,8 +2,25 @@ import { promises as fs } from 'fs';
 import path from 'path';
 import { stringify } from 'yaml';
 import { workflowProtocolHash, } from './artifacts.js';
+import { workflowProjectConfigRuntimeHelperScript, } from '../workflow-contract/index.js';
+function compactDescription(value, maxLength = 240) {
+    const normalized = value
+        .replace(/\s+/gu, ' ')
+        .trim()
+        .replace(/[.!?。！？]+$/u, '');
+    if (normalized.length <= maxLength)
+        return normalized;
+    return `${normalized.slice(0, maxLength - 1).trimEnd()}…`;
+}
 function factoryEntryDescription(plan) {
-    return plan.description || `Use when running the generated ${plan.name} workflow.`;
+    const purpose = compactDescription(plan.description || plan.goal || `run the generated ${plan.name} workflow`);
+    return `Use when the user wants the ${plan.name} managed workflow for ${purpose}, explicitly invokes /${plan.name}, or persisted workflow state identifies one unambiguous active run. Route through this entry Skill; do not invoke its internal Node Skills directly.`;
+}
+function factoryNodeDescription(plan, protocol, node, skillName) {
+    return `Use only when explicitly invoked as /${skillName} or routed by the ${plan.name} entry/runtime to the ${node.id} Node; complete ${node.label} for ${protocol.name}. Do not use for ordinary standalone tasks or as the workflow entry.`;
+}
+function yamlString(value) {
+    return JSON.stringify(value);
 }
 function runtimeEvals() {
     return {
@@ -24,19 +41,6 @@ function artifact(path, kind, content, executable = false) {
 function jsonArtifact(artifactPath, value, kind = 'reference') {
     return artifact(artifactPath, kind, `${JSON.stringify(value, null, 2)}\n`);
 }
-function claudeAgentDefinition(options) {
-    return `---
-name: ${options.name}
-description: ${options.description}
-tools: ${options.tools}
-model: inherit
----
-
-# ${options.title}
-
-${options.body}
-`;
-}
 function portableScriptAuthorBrief() {
     return `# Script Author Brief
 
@@ -134,14 +138,14 @@ function workflowContractEntryMarkdown(plan, protocol, decisionCoreBody) {
         .join('\n');
     const startupProtocol = protocol.kind === 'comet-five-phase-overlay'
         ? `1. Run \`node ${plan.name}/scripts/workflow-state.mjs status\` to read the active Comet change state.
-2. If there is no active Comet change, use \`/comet-open\` or the original \`/comet\` entry to create or resume one.
+2. If there is no active Comet change, use \`/comet-open\` or the permanent \`/comet-classic\` entry to create or resume one.
 3. Run \`node ${plan.name}/scripts/workflow-state.mjs next\` and load **only** the returned Skill. Do not load multiple Skills at once.`
         : `1. Run \`node ${plan.name}/scripts/workflow-state.mjs status\` to read current state.
 2. If the workflow is not started, confirm scope with the user, then run \`node ${plan.name}/scripts/workflow-state.mjs init\`.
 3. Run \`node ${plan.name}/scripts/workflow-state.mjs next\` and load **only** the returned Skill. Do not load multiple Skills at once.`;
     return `---
 name: ${plan.name}
-description: ${factoryEntryDescription(plan)}
+description: ${yamlString(factoryEntryDescription(plan))}
 ---
 
 # ${protocol.name}
@@ -162,6 +166,11 @@ ${bindings || '- No Skill bindings.'}
 
 ${guardrails || '- No explicit guardrails.'}
 
+## Workflow References
+
+- Route, Output Schemas, required Skill calls, and recovery state: \`reference/workflow-protocol.json\`.
+- Resolved source Skill evidence and composition provenance: \`reference/resolved-skills.json\`.
+
 ## Runtime And Recovery
 
 ### Startup Protocol
@@ -242,7 +251,7 @@ function workflowContractNodeMarkdown(plan, protocol, node, guidanceBody) {
             .join('\n');
     return `---
 name: ${skillName}
-description: Run the ${node.label} Node for ${protocol.name}.
+description: ${yamlString(factoryNodeDescription(plan, protocol, node, skillName))}
 ---
 
 # ${node.label}
@@ -346,6 +355,8 @@ main().catch((error) => {
 }
 function workflowContractOverlayHelperScript() {
     return `
+${workflowProjectConfigRuntimeHelperScript()}
+
 function isCometOverlay(protocol) {
   return protocol.kind === 'comet-five-phase-overlay';
 }
@@ -376,8 +387,93 @@ function parseSimpleYaml(raw) {
   return state;
 }
 
+async function workflowPathBaseRoot(pathBase) {
+  if (pathBase === undefined || pathBase === 'project') {
+    await inspectWorkflowProtectedPath(runRoot, runRoot, 'workflow path base', 'directory');
+    return runRoot;
+  }
+  const config = await readWorkflowProjectPathConfig(runRoot);
+  let resolved;
+  let configuredClassicRoot = null;
+  let alternateClassicRoot = null;
+  if (pathBase === 'classic-openspec-root' || pathBase === 'classic-superpowers-root') {
+    if (!config.classicEnabled || config.classicArtifactLayout === null) {
+      throw new Error('Classic workflow is not enabled by .comet/config.yaml');
+    }
+    configuredClassicRoot = config.classicArtifactLayout === 'docs'
+      ? path.join(runRoot, 'docs', 'openspec')
+      : path.join(runRoot, 'openspec');
+    alternateClassicRoot = config.classicArtifactLayout === 'docs'
+      ? path.join(runRoot, 'openspec')
+      : path.join(runRoot, 'docs', 'openspec');
+  }
+  if (pathBase === 'classic-openspec-root') {
+    resolved = configuredClassicRoot;
+  } else if (pathBase === 'classic-superpowers-root') {
+    resolved = path.join(runRoot, 'docs', 'superpowers');
+  } else if (pathBase === 'native-root') {
+    if (!config.nativeEnabled || config.nativeArtifactRoot === null) {
+      throw new Error('Native workflow is not enabled by .comet/config.yaml');
+    }
+    resolved = resolveWorkflowRelativePath(
+      runRoot,
+      config.nativeArtifactRoot,
+      'native.artifact_root',
+    ).target;
+  } else {
+    resolved = runRoot;
+  }
+  if (configuredClassicRoot !== null && alternateClassicRoot !== null) {
+    const [configuredInspection, alternateInspection] = await Promise.all([
+      inspectWorkflowProtectedPath(
+        runRoot,
+        configuredClassicRoot,
+        'configured Classic OpenSpec root',
+        'directory',
+      ),
+      inspectWorkflowProtectedPath(
+        runRoot,
+        alternateClassicRoot,
+        'alternate Classic OpenSpec root',
+        'directory',
+      ),
+    ]);
+    if (!configuredInspection.exists) {
+      throw new Error('Configured Classic OpenSpec root does not exist: ' + configuredClassicRoot);
+    }
+    if (alternateInspection.exists) {
+      throw new Error('Classic layout conflict: both configured and alternate OpenSpec roots exist');
+    }
+  }
+  const rootInspection = await inspectWorkflowProtectedPath(
+    runRoot,
+    resolved,
+    'workflow path base',
+    'directory',
+  );
+  if (!rootInspection.exists) {
+    const label =
+      pathBase === 'classic-openspec-root'
+        ? 'Configured Classic OpenSpec root'
+        : pathBase === 'classic-superpowers-root'
+          ? 'Configured Classic Superpowers root'
+          : pathBase === 'native-root'
+            ? 'Configured Native artifact root'
+            : 'Workflow path base';
+    throw new Error(label + ' does not exist: ' + resolved);
+  }
+  return resolved;
+}
+
 async function activeCometChanges() {
-  const changesRoot = path.join(runRoot, 'openspec', 'changes');
+  const changesRoot = path.join(await workflowPathBaseRoot('classic-openspec-root'), 'changes');
+  const inspection = await inspectWorkflowProtectedPath(
+    runRoot,
+    changesRoot,
+    'Classic changes root',
+    'directory',
+  );
+  if (!inspection.exists) return [];
   let entries;
   try {
     entries = await fs.readdir(changesRoot, { withFileTypes: true });
@@ -387,11 +483,45 @@ async function activeCometChanges() {
   }
   const changes = [];
   for (const entry of entries) {
+    if (entry.isSymbolicLink()) {
+      throw new Error(
+        'Classic changes root crosses a symbolic link or junction at ' + entry.name,
+      );
+    }
     if (!entry.isDirectory()) continue;
-    const statePath = path.join(changesRoot, entry.name, '.comet.yaml');
+    const changeRoot = path.join(changesRoot, entry.name);
+    await inspectWorkflowProtectedPath(
+      runRoot,
+      changeRoot,
+      'Classic change directory',
+      'directory',
+    );
+    const statePath = path.join(changeRoot, '.comet.yaml');
+    const stateInspection = await inspectWorkflowProtectedPath(
+      runRoot,
+      statePath,
+      'Classic change state',
+      'file',
+    );
+    if (!stateInspection.exists) continue;
     let state;
     try {
-      state = parseSimpleYaml(await fs.readFile(statePath, 'utf8'));
+      state = parseSimpleYaml(
+        (
+          await readWorkflowProtectedFile(
+            runRoot,
+            statePath,
+            'Classic change state',
+            WORKFLOW_PROJECT_FILE_MAX_BYTES,
+          )
+        ).toString('utf8'),
+      );
+      await inspectWorkflowProtectedPath(
+        runRoot,
+        statePath,
+        'Classic change state',
+        'file',
+      );
     } catch (error) {
       if (error && typeof error === 'object' && error.code === 'ENOENT') continue;
       throw error;
@@ -405,7 +535,9 @@ async function activeCometChanges() {
 async function resolveCometOverlayChange() {
   const changes = await activeCometChanges();
   if (changes.length === 0) {
-    throw new Error('No active Comet change; use /comet-open or the original /comet entry to create one.');
+    throw new Error(
+      'No active Comet change; use /comet-open or the permanent /comet-classic entry to create one.',
+    );
   }
   if (changes.length > 1) {
     throw new Error(
@@ -463,12 +595,33 @@ function overlayNodeFromState(state, evidence = {}) {
 
 function evidencePathFor(protocol, change) {
   const changeName = typeof change === 'string' ? change : change.name;
-  return path.join(runRoot, '.comet', 'workflow-evidence', changeName, protocol.name + '.json');
+  return resolveWorkflowRelativePath(
+    runRoot,
+    ['.comet', 'workflow-evidence', changeName, protocol.name + '.json'].join('/'),
+    'workflow evidence path',
+  ).target;
 }
 
 async function readOverlayEvidence(protocol, change) {
+  const file = evidencePathFor(protocol, change);
   try {
-    const parsed = JSON.parse(await fs.readFile(evidencePathFor(protocol, change), 'utf8'));
+    const inspection = await inspectWorkflowProtectedPath(
+      runRoot,
+      file,
+      'workflow evidence file',
+      'file',
+    );
+    if (!inspection.exists) return {};
+    const parsed = JSON.parse(
+      (
+        await readWorkflowProtectedFile(
+          runRoot,
+          file,
+          'workflow evidence file',
+          WORKFLOW_PROJECT_FILE_MAX_BYTES,
+        )
+      ).toString('utf8'),
+    );
     return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : {};
   } catch (error) {
     if (error && typeof error === 'object' && error.code === 'ENOENT') return {};
@@ -476,16 +629,262 @@ async function readOverlayEvidence(protocol, change) {
   }
 }
 
+async function workflowProtectedDirectorySnapshot(projectRoot, directory, label) {
+  const inspection = await inspectWorkflowProtectedPath(
+    projectRoot,
+    directory,
+    label,
+    'directory',
+  );
+  if (!inspection.exists) {
+    throw new Error(label + ' does not exist');
+  }
+  const stat = await fs.lstat(directory, { bigint: true });
+  if (!stat.isDirectory() || stat.isSymbolicLink()) {
+    throw new Error(label + ' must be a real directory');
+  }
+  return {
+    stat,
+    realPath: await fs.realpath(directory),
+  };
+}
+
+async function assertWorkflowProtectedDirectorySnapshot(
+  projectRoot,
+  directory,
+  label,
+  expected,
+) {
+  const actual = await workflowProtectedDirectorySnapshot(
+    projectRoot,
+    directory,
+    label,
+  );
+  if (
+    actual.realPath !== expected.realPath ||
+    !workflowSameFileObject(
+      workflowFileObjectIdentity(actual.stat),
+      workflowFileObjectIdentity(expected.stat),
+    )
+  ) {
+    throw new Error(label + ' changed before commit');
+  }
+}
+
+async function ensureWorkflowProtectedDirectory(projectRoot, directory, label) {
+  const root = path.resolve(projectRoot);
+  const target = path.resolve(directory);
+  if (!workflowPathInside(root, target)) {
+    throw new Error(label + ' must stay inside the project root');
+  }
+  const relative = path.relative(root, target);
+  const segments = relative === '' ? [] : relative.split(path.sep);
+  let cursor = root;
+  await inspectWorkflowProtectedPath(root, cursor, label, 'directory');
+  for (const segment of segments) {
+    const parent = cursor;
+    cursor = path.join(cursor, segment);
+    const inspection = await inspectWorkflowProtectedPath(
+      root,
+      cursor,
+      label,
+      'directory',
+    );
+    if (!inspection.exists) {
+      const parentSnapshot = await workflowProtectedDirectorySnapshot(
+        root,
+        parent,
+        label + ' parent',
+      );
+      try {
+        await fs.mkdir(cursor);
+      } catch (error) {
+        if (!error || typeof error !== 'object' || error.code !== 'EEXIST') {
+          throw error;
+        }
+      }
+      await assertWorkflowProtectedDirectorySnapshot(
+        root,
+        parent,
+        label + ' parent',
+        parentSnapshot,
+      );
+    }
+    const created = await inspectWorkflowProtectedPath(
+      root,
+      cursor,
+      label,
+      'directory',
+    );
+    if (!created.exists) {
+      throw new Error(label + ' could not be created safely');
+    }
+  }
+}
+
+async function workflowProtectedTargetSnapshot(projectRoot, file, label) {
+  const inspection = await inspectWorkflowProtectedPath(
+    projectRoot,
+    file,
+    label,
+    'file',
+  );
+  if (!inspection.exists) return { exists: false };
+  const stat = await fs.lstat(file, { bigint: true });
+  if (!stat.isFile() || stat.isSymbolicLink()) {
+    throw new Error(label + ' must be a real file');
+  }
+  return {
+    exists: true,
+    stat,
+    realPath: await fs.realpath(file),
+  };
+}
+
+async function assertWorkflowProtectedTargetSnapshot(
+  projectRoot,
+  file,
+  label,
+  expected,
+) {
+  const actual = await workflowProtectedTargetSnapshot(projectRoot, file, label);
+  if (actual.exists !== expected.exists) {
+    throw new Error(label + ' changed before commit');
+  }
+  if (
+    actual.exists &&
+    expected.exists &&
+    (actual.realPath !== expected.realPath ||
+      !workflowSameFileStat(actual.stat, expected.stat))
+  ) {
+    throw new Error(label + ' changed before commit');
+  }
+}
+
+async function writeWorkflowProtectedFile(
+  projectRoot,
+  file,
+  label,
+  value,
+  maxBytes,
+) {
+  const bytes = Buffer.isBuffer(value) ? value : Buffer.from(String(value), 'utf8');
+  if (!Number.isSafeInteger(maxBytes) || maxBytes < 1) {
+    throw new Error(label + ' byte limit must be a positive integer');
+  }
+  if (bytes.length > maxBytes) {
+    throw new Error(label + ' exceeds ' + String(maxBytes) + ' bytes');
+  }
+  const root = path.resolve(projectRoot);
+  const target = path.resolve(file);
+  const directory = path.dirname(target);
+  await ensureWorkflowProtectedDirectory(root, directory, label + ' directory');
+  const directorySnapshot = await workflowProtectedDirectorySnapshot(
+    root,
+    directory,
+    label + ' directory',
+  );
+  const targetSnapshot = await workflowProtectedTargetSnapshot(root, target, label);
+  await assertWorkflowProtectedDirectorySnapshot(
+    root,
+    directory,
+    label + ' directory',
+    directorySnapshot,
+  );
+  await assertWorkflowProtectedTargetSnapshot(root, target, label, targetSnapshot);
+
+  const temporary = path.join(
+    directory,
+    '.' +
+      path.basename(target) +
+      '.' +
+      String(process.pid) +
+      '.' +
+      String(Date.now()) +
+      '.' +
+      Math.random().toString(16).slice(2) +
+      '.tmp',
+  );
+  const flags =
+    fsConstants.O_WRONLY |
+    fsConstants.O_CREAT |
+    fsConstants.O_EXCL |
+    (process.platform === 'win32' ? 0 : fsConstants.O_NOFOLLOW);
+  let handle;
+  let committed = false;
+  try {
+    await assertWorkflowProtectedDirectorySnapshot(
+      root,
+      directory,
+      label + ' directory',
+      directorySnapshot,
+    );
+    handle = await fs.open(temporary, flags, 0o600);
+    await handle.writeFile(bytes);
+    await handle.sync();
+    const temporaryStat = await handle.stat({ bigint: true });
+    if (!temporaryStat.isFile()) {
+      throw new Error(label + ' temporary path must be a real file');
+    }
+    await handle.close();
+    handle = undefined;
+    await inspectWorkflowProtectedPath(
+      root,
+      temporary,
+      label + ' temporary file',
+      'file',
+    );
+    await assertWorkflowProtectedDirectorySnapshot(
+      root,
+      directory,
+      label + ' directory',
+      directorySnapshot,
+    );
+    await assertWorkflowProtectedTargetSnapshot(root, target, label, targetSnapshot);
+    await fs.rename(temporary, target);
+    committed = true;
+    await inspectWorkflowProtectedPath(root, target, label, 'file');
+    await assertWorkflowProtectedDirectorySnapshot(
+      root,
+      directory,
+      label + ' directory',
+      directorySnapshot,
+    );
+  } finally {
+    if (handle) {
+      await handle.close().catch(() => {});
+    }
+    if (!committed) {
+      try {
+        await assertWorkflowProtectedDirectorySnapshot(
+          root,
+          directory,
+          label + ' directory',
+          directorySnapshot,
+        );
+        await fs.rm(temporary, { force: true });
+      } catch {
+        // Do not follow a replaced parent during cleanup.
+      }
+    }
+  }
+}
+
 async function writeOverlayEvidence(protocol, change, value) {
   const file = evidencePathFor(protocol, change);
-  await fs.mkdir(path.dirname(file), { recursive: true });
-  await fs.writeFile(file, JSON.stringify(value, null, 2) + '\\n', 'utf8');
+  await writeWorkflowProtectedFile(
+    runRoot,
+    file,
+    'workflow evidence file',
+    JSON.stringify(value, null, 2) + '\\n',
+    WORKFLOW_PROJECT_FILE_MAX_BYTES,
+  );
 }
 `;
 }
 function workflowContractHookGuardScript() {
     return `#!/usr/bin/env node
-import { promises as fs } from 'fs';
+  import { constants as fsConstants, promises as fs } from 'fs';
 import path from 'path';
 import { fileURLToPath } from 'url';
 
@@ -496,19 +895,39 @@ const runRoot = process.env.COMET_RUN_ROOT ? path.resolve(process.env.COMET_RUN_
 const protocolPath = path.join(packageRoot, 'reference', 'workflow-protocol.json');
 ${workflowContractOverlayHelperScript()}
 
-function statePath(protocol) {
+async function statePath(protocol) {
   const preferred = String(protocol.state?.statePath ?? '');
-  if (preferred.includes('*')) {
-    throw new Error('workflow-run statePath cannot contain wildcards');
-  }
-  const relative = preferred;
-  return path.join(runRoot, ...relative.split('/').filter(Boolean));
+  const target = resolveWorkflowRelativePath(
+    runRoot,
+    preferred,
+    'workflow-run statePath',
+  ).target;
+  await inspectWorkflowProtectedPath(
+    runRoot,
+    target,
+    'workflow-run statePath',
+    'file',
+  );
+  return target;
 }
 
 async function readJson(file) {
   return JSON.parse(await fs.readFile(file, 'utf8'));
 }
 
+async function readStateJson(file) {
+  return JSON.parse(
+    (
+      await readWorkflowProtectedFile(
+        runRoot,
+        file,
+        'workflow-run state',
+        WORKFLOW_PROJECT_FILE_MAX_BYTES,
+      )
+    ).toString('utf8'),
+  );
+}
+
 function route(protocol) {
   return (protocol.nodes ?? []).filter((node) => !node.disabled);
 }
@@ -545,7 +964,7 @@ async function main() {
   }
   let state;
   try {
-    state = await readJson(statePath(protocol));
+    state = await readStateJson(await statePath(protocol));
   } catch (error) {
     if (error && typeof error === 'object' && error.code === 'ENOENT') {
       throw new Error('workflow state is missing; run workflow-state.mjs init first');
@@ -575,7 +994,7 @@ main().catch((error) => {
 }
 function workflowContractStateScript() {
     return `#!/usr/bin/env node
-import { promises as fs } from 'fs';
+  import { constants as fsConstants, promises as fs } from 'fs';
 import path from 'path';
 import { fileURLToPath } from 'url';
 
@@ -594,22 +1013,47 @@ function generatedNodeSkillName(protocol, nodeId) {
   return (slug(protocol.name) || 'workflow') + '-' + (slug(nodeId) || 'node');
 }
 
-function statePath(protocol) {
+async function statePath(protocol) {
   const preferred = String(protocol.state?.statePath ?? '');
-  if (preferred.includes('*')) {
-    throw new Error('workflow-run statePath cannot contain wildcards');
-  }
-  const relative = preferred;
-  return path.join(runRoot, ...relative.split('/').filter(Boolean));
+  const target = resolveWorkflowRelativePath(
+    runRoot,
+    preferred,
+    'workflow-run statePath',
+  ).target;
+  await inspectWorkflowProtectedPath(
+    runRoot,
+    target,
+    'workflow-run statePath',
+    'file',
+  );
+  return target;
 }
 
 async function readJson(file) {
   return JSON.parse(await fs.readFile(file, 'utf8'));
 }
 
+async function readStateJson(file) {
+  return JSON.parse(
+    (
+      await readWorkflowProtectedFile(
+        runRoot,
+        file,
+        'workflow-run state',
+        WORKFLOW_PROJECT_FILE_MAX_BYTES,
+      )
+    ).toString('utf8'),
+  );
+}
+
 async function writeJson(file, value) {
-  await fs.mkdir(path.dirname(file), { recursive: true });
-  await fs.writeFile(file, JSON.stringify(value, null, 2) + '\\n', 'utf8');
+  await writeWorkflowProtectedFile(
+    runRoot,
+    file,
+    'workflow-run state',
+    JSON.stringify(value, null, 2) + '\\n',
+    WORKFLOW_PROJECT_FILE_MAX_BYTES,
+  );
 }
 
 function route(protocol) {
@@ -647,7 +1091,7 @@ function parseEvidence(raw) {
 
 async function readState(protocol) {
   try {
-    return await readJson(statePath(protocol));
+    return await readStateJson(await statePath(protocol));
   } catch (error) {
     if (error && typeof error === 'object' && error.code === 'ENOENT') {
       throw new Error('Missing workflow state. Run workflow-state.mjs init first.');
@@ -664,7 +1108,7 @@ async function main() {
   if (isCometOverlay(protocol)) {
     if (command === 'init') {
       throw new Error(
-        'Comet overlay state is created by /comet-open; use the original /comet entry to start a change.',
+        'Comet overlay state is created by /comet-open; use the permanent /comet-classic entry to start a change.',
       );
     }
     if (command === 'status') {
@@ -718,7 +1162,7 @@ async function main() {
     }
     throw new Error('Unknown command: ' + command);
   }
-  const file = statePath(protocol);
+  const file = await statePath(protocol);
   if (command === 'init') {
     const node = nextNode(protocol, { completedNodes: [] });
     await writeJson(file, {
@@ -735,7 +1179,7 @@ async function main() {
   }
   if (command === 'status') {
     try {
-      console.log(JSON.stringify(await readJson(file), null, 2));
+      console.log(JSON.stringify(await readStateJson(file), null, 2));
     } catch (error) {
       if (error && typeof error === 'object' && error.code === 'ENOENT') {
         console.log(JSON.stringify({ status: 'not-started' }, null, 2));
@@ -775,7 +1219,7 @@ main().catch((error) => {
 }
 function workflowContractGuardScript() {
     return `#!/usr/bin/env node
-import { promises as fs } from 'fs';
+  import { constants as fsConstants, promises as fs } from 'fs';
 import path from 'path';
 import { fileURLToPath } from 'url';
 
@@ -796,22 +1240,47 @@ function generatedNodeSkillName(protocol, id) {
   return (slug(protocol.name) || 'workflow') + '-' + (slug(id) || 'node');
 }
 
-function statePath(protocol) {
+async function statePath(protocol) {
   const preferred = String(protocol.state?.statePath ?? '');
-  if (preferred.includes('*')) {
-    throw new Error('workflow-run statePath cannot contain wildcards');
-  }
-  const relative = preferred;
-  return path.join(runRoot, ...relative.split('/').filter(Boolean));
+  const target = resolveWorkflowRelativePath(
+    runRoot,
+    preferred,
+    'workflow-run statePath',
+  ).target;
+  await inspectWorkflowProtectedPath(
+    runRoot,
+    target,
+    'workflow-run statePath',
+    'file',
+  );
+  return target;
 }
 
 async function readJson(file) {
   return JSON.parse(await fs.readFile(file, 'utf8'));
 }
 
+async function readStateJson(file) {
+  return JSON.parse(
+    (
+      await readWorkflowProtectedFile(
+        runRoot,
+        file,
+        'workflow-run state',
+        WORKFLOW_PROJECT_FILE_MAX_BYTES,
+      )
+    ).toString('utf8'),
+  );
+}
+
 async function writeJson(file, value) {
-  await fs.mkdir(path.dirname(file), { recursive: true });
-  await fs.writeFile(file, JSON.stringify(value, null, 2) + '\\n', 'utf8');
+  await writeWorkflowProtectedFile(
+    runRoot,
+    file,
+    'workflow-run state',
+    JSON.stringify(value, null, 2) + '\\n',
+    WORKFLOW_PROJECT_FILE_MAX_BYTES,
+  );
 }
 
 function route(protocol) {
@@ -899,15 +1368,17 @@ function patternToRegExp(pattern) {
 }
 
 async function pathPatternExists(root, relativePattern) {
-  const parts = String(relativePattern).split('/').filter(Boolean);
+  const parts = workflowRelativeSegments(relativePattern, 'artifact path', true);
   async function walk(current, index) {
+    const inspection = await inspectWorkflowProtectedPath(
+      runRoot,
+      current,
+      'workflow artifact path',
+      index >= parts.length ? 'any' : 'directory',
+    );
+    if (!inspection.exists) return false;
     if (index >= parts.length) {
-      try {
-        await fs.stat(current);
-        return true;
-      } catch {
-        return false;
-      }
+      return true;
     }
     const part = parts[index];
     if (!part.includes('*')) {
@@ -921,6 +1392,12 @@ async function pathPatternExists(root, relativePattern) {
     }
     const matcher = patternToRegExp(part);
     for (const entry of entries) {
+      if (entry.isSymbolicLink()) {
+        throw new Error(
+          'workflow artifact path crosses a symbolic link or junction at ' +
+            path.join(current, entry.name),
+        );
+      }
       if (matcher.test(entry.name) && (await walk(path.join(current, entry.name), index + 1))) {
         return true;
       }
@@ -939,7 +1416,9 @@ async function missingRequiredArtifacts(protocol, node) {
       if (!artifact.required) continue;
       const exists = (
         await Promise.all(
-          (artifact.paths ?? []).map((artifactPath) => pathPatternExists(runRoot, artifactPath)),
+          (artifact.paths ?? []).map(async (artifactPath) =>
+            pathPatternExists(await workflowPathBaseRoot(artifact.pathBase), artifactPath),
+          ),
         )
       ).some(Boolean);
       if (!exists) missing.push(schemaId + '.' + artifact.id);
@@ -1007,8 +1486,8 @@ async function main() {
     console.log('APPLY: rerun with --apply to update workflow state');
     return;
   }
-  const file = statePath(protocol);
-  const state = await readJson(file);
+  const file = await statePath(protocol);
+  const state = await readStateJson(file);
   state.completedNodes = Array.isArray(state.completedNodes) ? state.completedNodes : [];
   state.evidence = state.evidence && typeof state.evidence === 'object' ? state.evidence : {};
   if (command === 'entry') {
@@ -1156,7 +1635,7 @@ function workflowContractEvalManifest(plan, protocol) {
             'comet-refactor-counter',
             'comet-api-cache-ttl',
         ]
-        : ['generic-skill-smoke', 'authoring-skill-smoke', 'workflow-route-conformance'];
+        : ['authoring-skill-smoke', 'workflow-route-conformance'];
     const activeOutputSchemas = uniqueStrings(activeNodes.flatMap((node) => node.outputSchemas));
     const activeOutputSchemaSet = new Set(activeOutputSchemas);
     const evalRequiredOutputSchemas = protocol.evals[0]?.requiredOutputSchemas ?? [];
@@ -1325,7 +1804,6 @@ function workflowContractArtifacts(plan) {
         'reference/skill-review.md',
         'reference/composition-report.md',
         'reference/subagents/script-author.md',
-        'agents/claude/comet-any-script-author.md',
         'scripts/comet-plan.mjs',
         'scripts/comet-check.mjs',
         'scripts/comet-hook-guard.mjs',
@@ -1348,6 +1826,15 @@ function workflowContractArtifacts(plan) {
         jsonArtifact('reference/resolved-skills.json', {
             schemaVersion: 1,
             resolvedSkills: plan.resolvedSkills ?? [],
+            sourceSummaries: (plan.resolvedSkills ?? []).flatMap((resolved) => resolved.sources.map((source) => ({
+                name: source.name,
+                query: resolved.query,
+                description: source.description,
+                platform: source.platform,
+                scope: source.scope,
+                origin: source.origin,
+                references: source.references ?? [],
+            }))),
             workflow: {
                 kind: protocol.kind,
                 nodes: protocol.nodes.map((node) => ({
@@ -1362,32 +1849,22 @@ function workflowContractArtifacts(plan) {
         }),
         jsonArtifact('reference/workflow-protocol.json', protocol),
         artifact('reference/decision-points.md', 'reference', plan.contentDrafts?.['reference/decision-points.md'] ??
-            `# Workflow Decision Points\n\n${workflowContractRoute(protocol)
-                .map((node) => `- \`${node.id}\`: confirm Output Schemas ${node.outputSchemas.join(', ') || 'none'}.`)
-                .join('\n')}\n`),
+            `# Workflow Decision Classification\n\nNo decision points have been authored. Do not infer that every Node or Output Schema requires confirmation. Classify each candidate as a genuine user decision, automatic handling, a stop condition, or a manual handoff; pause only when at least two valid choices change scope, behavior, accepted risk, or an irreversible outcome.\n`),
         artifact('reference/recovery.md', 'reference', plan.contentDrafts?.['reference/recovery.md'] ??
             `# Workflow Recovery\n\n- State model: \`${protocol.state.kind}\`\n- State path: \`${protocol.state.statePath}\`\n- Resume by reading the first incomplete Workflow Node.\n`),
         artifact('reference/composition-report.md', 'reference', workflowContractCompositionReport(plan, protocol)),
         artifact('reference/skill-review.md', 'reference', renderSkillReviewMarkdown(plan)),
         artifact('reference/subagents/script-author.md', 'reference', portableScriptAuthorBrief()),
-        artifact('agents/claude/comet-any-script-author.md', 'agent', claudeAgentDefinition({
-            name: 'comet-any-script-author',
-            description: 'Use when authoring workflow script contracts for a confirmed comet-any bundle draft.',
-            tools: 'Read, Write, Glob, Grep',
-            title: 'Script Author Agent',
-            body: 'Author the script contract for one comet-any authoring lane. Read the portable brief, write only the assigned report path, and do not publish, install, or run destructive commands.',
-        })),
         jsonArtifact('reference/authoring-lanes.json', {
             schemaVersion: 1,
             protocolHash,
             lanes: [
-                'workflow-entry',
-                'skill-core',
-                'script-contract',
-                'platform-agent',
-                'reference',
-                'eval',
-                'skill-review',
+                { lane: 'script' },
+                { lane: 'reference' },
+                { lane: 'pause-points' },
+                { lane: 'workflow-entry' },
+                { lane: 'skill-core' },
+                { lane: 'skill-review' },
             ],
             review: authoringLanesReview(plan),
         }),
@@ -1499,13 +1976,7 @@ export async function generateFactorySkillPackage(plan) {
                 .filter((item) => item.kind === 'script')
                 .map((item) => artifactTarget(packageRoot, item.path)),
         },
-        platformAgents: [
-            {
-                id: 'comet-any-script-author',
-                platform: 'claude',
-                path: path.join(packageRoot, 'agents', 'claude', 'comet-any-script-author.md'),
-            },
-        ],
+        platformAgents: [],
     };
 }
 //# sourceMappingURL=package.js.map