@jtf19/vibecoding-kit 0.1.0

package/tools/vibe-runtime/runtime-release-command.mjs

@@ -0,0 +1,225 @@
+import path from 'node:path';
+import { localJsonFileWithinRoot } from './runtime-local-json-input.mjs';
+import { closeoutParityEnvelope, printCloseoutReadiness } from './runtime-closeout-parity-contract.mjs';
+import { printTaskCommitGate } from './runtime-task-commit-sidecar.mjs';
+import {
+  releaseStatePresent,
+  taskCommitGateDisplayPath,
+  taskCommitGateEnvelope,
+  taskCommitGateResponse,
+  taskCommitReadinessEnvelope,
+  writeTaskCommitGate,
+} from './runtime-release-state-lifecycle-model.mjs';
+import {
+  printRuntimeSuitePlan,
+  runtimeSuitePlanEnvelope,
+} from './runtime-suite-plan-model.mjs';
+import {
+  buildLocalCommitAutomationGate,
+  printLocalCommitAutomationGate,
+} from './runtime-local-commit-automation-gate.mjs';
+
+function releaseReadOnlyControlRequested(options) {
+  return options.confirm || options.dryRun || options.recoveryPreview || options.hooksPreview || options.write || options.run || options.autoRun || options.scan || options.once || options.preflight || options.dispatch || options.dispatchIntent;
+}
+
+function rejectReleaseReadOnlyControls(options, command) {
+  if (releaseReadOnlyControlRequested(options)) throw new Error(`${command} is read-only and does not accept execution, dispatch, confirm, preview, dry-run, run, scan, preflight, or write flags`);
+}
+
+function emitReleaseEnvelope(deps, options, envelope, print) {
+  if (options.json) deps.writeJsonEnvelope('release', envelope);
+  else print(envelope);
+}
+
+function runReleaseSuitePlanMode(deps, options) {
+  rejectReleaseReadOnlyControls(options, 'release --suite-plan');
+  if (!options.fromFile) throw new Error('release --suite-plan requires --from-file <local-release-check-run-summary-json>');
+  if (options.fromPlan || options.fromRunbook || options.fromEvidence || options.selectedStage || options.commitSubject || options.fromReadiness || options.releaseGateFile || options.releaseNotesFile || options.releaseEvalFiles.length > 0 || options.plannerFile || options.plannerFromHook || options.methodologyKind || options.methodologyIntent || options.learningObservationFiles.length > 0 || options.learningInstinctFile || options.tokenCompactionFiles.length > 0) throw new Error('release --suite-plan only accepts one local timing summary file, optional --change-kind, and read-only output flags');
+  const allowedKinds = new Set(['runtime', 'release', 'execution', 'docs', 'unknown']);
+  if (!allowedKinds.has(options.changeKind)) throw new Error('release --suite-plan --change-kind must be one of runtime, release, execution, docs, or unknown');
+  const timingRef = localJsonFileWithinRoot(options.root, options.fromFile, 'release --suite-plan --from-file');
+  const envelope = runtimeSuitePlanEnvelope({ timingSummary: timingRef.data, timingFile: timingRef.file, changeKind: options.changeKind });
+  emitReleaseEnvelope(deps, options, envelope, printRuntimeSuitePlan);
+}
+
+function runReleaseStagedCommitReadinessMode(deps, options) {
+  rejectReleaseReadOnlyControls(options, 'release --staged-commit-readiness');
+  if (!options.fromRunbook) throw new Error('release --staged-commit-readiness requires --from-runbook <local-runbook-json>');
+  if (!options.fromEvidence) throw new Error('release --staged-commit-readiness requires --from-evidence <local-execution-evidence-json>');
+  if (!options.selectedStage) throw new Error('release --staged-commit-readiness requires --stage <stage-id>');
+  if (!options.commitSubject) throw new Error('release --staged-commit-readiness requires --subject <commit-subject>');
+  if (options.fromFile || options.fromReadiness || options.plannerFile || options.plannerFromHook || options.methodologyKind || options.learningObservationFiles.length > 0 || options.learningInstinctFile || options.tokenCompactionFiles.length > 0) throw new Error('release --staged-commit-readiness only accepts one local runbook, one local execution evidence binding, one stage, one subject, and read-only output flags');
+  const envelope = deps.stagedCommitReadinessEnvelope(options.root, options.fromRunbook, options.fromEvidence, { selectedStage: options.selectedStage, subject: options.commitSubject });
+  emitReleaseEnvelope(deps, options, envelope, deps.printStagedCommitReadiness);
+}
+
+function runReleaseDiffReadMode(deps, options) {
+  rejectReleaseReadOnlyControls(options, 'release --diff-read');
+  if (!options.fromPlan) throw new Error('release --diff-read requires --from-plan <local-plan-file>');
+  if (options.fromFile || options.commitSubject || options.fromReadiness || options.plannerFile || options.plannerFromHook || options.methodologyKind || options.learningObservationFiles.length > 0 || options.learningInstinctFile || options.tokenCompactionFiles.length > 0) throw new Error('release --diff-read only accepts one local plan file and read-only output flags');
+  const envelope = deps.gitDiffReadEnvelope(options.root, deps.collectGitDiffReadResults(options.root), { planFile: options.fromPlan });
+  emitReleaseEnvelope(deps, options, envelope, deps.printGitDiffRead);
+}
+
+function runReleaseDiffCoverageMode(deps, options) {
+  rejectReleaseReadOnlyControls(options, 'release --diff-coverage');
+  if (!options.fromFile) throw new Error('release --diff-coverage requires --from-file <local-diff-file>');
+  if (!options.fromPlan) throw new Error('release --diff-coverage requires --from-plan <local-plan-file>');
+  if (options.commitSubject || options.fromReadiness || options.plannerFile || options.plannerFromHook || options.methodologyKind || options.learningObservationFiles.length > 0 || options.learningInstinctFile || options.tokenCompactionFiles.length > 0) throw new Error('release --diff-coverage only accepts one local diff file, one local plan file, and read-only output flags');
+  const envelope = deps.diffCoverageEnvelope(options.root, options.fromFile, { planFile: options.fromPlan });
+  emitReleaseEnvelope(deps, options, envelope, deps.printDiffCoverage);
+}
+
+function runReleaseCommitReadinessMode(deps, options) {
+  rejectReleaseReadOnlyControls(options, 'release --commit-readiness');
+  if (!options.fromFile) throw new Error('release --commit-readiness requires --from-file <local-plan-file>');
+  if (!options.commitSubject) throw new Error('release --commit-readiness requires --subject <commit-subject>');
+  if (options.fromReadiness || options.plannerFile || options.plannerFromHook || options.methodologyKind || options.learningObservationFiles.length > 0 || options.learningInstinctFile || options.tokenCompactionFiles.length > 0) throw new Error('release --commit-readiness only accepts one local plan file, one subject, optional intent, and read-only output flags');
+  const envelope = deps.commitReadinessEnvelope(options.root, options.fromFile, { intent: options.methodologyIntent || 'implementation', subject: options.commitSubject });
+  emitReleaseEnvelope(deps, options, envelope, deps.printCommitReadiness);
+}
+
+function runReleaseLocalCommitGateMode(deps, options) {
+  const forbiddenControls = options.confirm || options.write || options.run || options.autoRun || options.scan || options.once || options.preflight || options.dispatch || options.dispatchIntent || options.recoveryPreview || options.hooksPreview;
+  if (forbiddenControls) throw new Error('release --local-commit-gate is dry-run planning only and does not accept confirm, write, run, auto-run, scan, preflight, dispatch, or preview flags');
+  if (!options.fromReadiness) throw new Error('release --local-commit-gate requires --from-readiness <local-readiness-json>');
+  if (!options.commitSubject) throw new Error('release --local-commit-gate requires --subject <commit-subject>');
+  if (options.fromFile || options.fromPlan || options.fromRunbook || options.fromEvidence || options.selectedStage || options.taskResultFile || options.releaseGateFile || options.releaseNotesFile || options.releaseEvalFiles.length > 0 || options.plannerFile || options.plannerFromHook || options.methodologyKind || options.methodologyIntent || options.learningObservationFiles.length > 0 || options.learningInstinctFile || options.tokenCompactionFiles.length > 0) throw new Error('release --local-commit-gate only accepts one local readiness file, one subject, optional --dry-run, --json, and --root');
+  const readinessSource = localJsonFileWithinRoot(options.root, options.fromReadiness, 'release --local-commit-gate --from-readiness');
+  const envelope = buildLocalCommitAutomationGate({
+    readiness: readinessSource.data,
+    readinessSource,
+    subject: options.commitSubject,
+    digestObject: deps.digestObject,
+  });
+  emitReleaseEnvelope(deps, options, envelope, printLocalCommitAutomationGate);
+}
+
+function runReleaseCloseoutReadinessMode(deps, options) {
+  rejectReleaseReadOnlyControls(options, 'release --closeout-readiness');
+  if (options.profile !== 'superpowers-parity') throw new Error('release --closeout-readiness requires --profile superpowers-parity');
+  for (const [key, label] of [['fromFile', '--from-file <local-sdd-progress-ledger-json>'], ['fromEvidence', '--from-evidence <local-test-evidence-json>'], ['fromDiffCoverage', '--from-diff-coverage <local-diff-coverage-json>'], ['fromReadiness', '--from-readiness <local-task-commit-readiness-json>']]) if (!options[key]) throw new Error(`release --closeout-readiness requires ${label}`);
+  if (options.fromPlan || options.fromRunbook || options.selectedStage || options.taskResultFile || options.commitSubject || options.releaseGateFile || options.releaseNotesFile || options.releaseEvalFiles.length > 0 || options.plannerFile || options.plannerFromHook || options.methodologyKind || options.methodologyIntent || options.learningObservationFiles.length > 0 || options.learningInstinctFile || options.tokenCompactionFiles.length > 0) throw new Error('release --closeout-readiness only accepts local ledger, test, diff, task commit readiness evidence, --profile superpowers-parity, read-only output flags, and --root');
+  const readLocalJson = (file, flag) => localJsonFileWithinRoot(options.root, file, `release --closeout-readiness ${flag}`);
+  const envelope = closeoutParityEnvelope({ ledgerSource: readLocalJson(options.fromFile, '--from-file'), testSource: readLocalJson(options.fromEvidence, '--from-evidence'), diffSource: readLocalJson(options.fromDiffCoverage, '--from-diff-coverage'), readinessSource: readLocalJson(options.fromReadiness, '--from-readiness'), digestObject: deps.digestObject, statePresent: releaseStatePresent(deps, options.root) });
+  emitReleaseEnvelope(deps, options, envelope, printCloseoutReadiness);
+}
+function runReleaseTaskCommitReadinessMode(deps, options) {
+  rejectReleaseReadOnlyControls(options, 'release --task-commit-readiness');
+  if (options.profile !== 'superpowers-parity-task-commits') throw new Error('release --task-commit-readiness requires --profile superpowers-parity-task-commits');
+  if (!options.taskResultFile) throw new Error('release --task-commit-readiness requires --from-task-result <local-task-result-json>');
+  if (options.fromFile || options.fromPlan || options.fromRunbook || options.fromEvidence || options.selectedStage || options.fromReadiness || options.commitSubject || options.releaseGateFile || options.releaseNotesFile || options.releaseEvalFiles.length > 0 || options.plannerFile || options.plannerFromHook || options.methodologyKind || options.methodologyIntent || options.learningObservationFiles.length > 0 || options.learningInstinctFile || options.tokenCompactionFiles.length > 0) throw new Error('release --task-commit-readiness only accepts one local task result file, --profile superpowers-parity-task-commits, and read-only output flags');
+  const envelope = taskCommitReadinessEnvelope(deps, options.root, options.taskResultFile);
+  emitReleaseEnvelope(deps, options, envelope, printTaskCommitGate);
+}
+
+function runReleaseTaskCommitMode(deps, options) {
+  if (!options.confirm) throw new Error('release --task-commit requires --confirm');
+  if (options.profile !== 'superpowers-parity-task-commits') throw new Error('release --task-commit requires --profile superpowers-parity-task-commits');
+  if (!options.fromReadiness) throw new Error('release --task-commit requires --from-readiness <local-task-commit-readiness-json>');
+  if (options.write || options.dryRun || options.run || options.autoRun || options.dispatch || options.dispatchIntent || options.preflight || options.scan || options.once || options.fromFile || options.fromPlan || options.fromRunbook || options.fromEvidence || options.selectedStage || options.taskResultFile || options.commitSubject || options.releaseGateFile || options.releaseNotesFile || options.releaseEvalFiles.length > 0 || options.plannerFile || options.plannerFromHook || options.methodologyKind || options.methodologyIntent || options.learningObservationFiles.length > 0 || options.learningInstinctFile || options.tokenCompactionFiles.length > 0) throw new Error('release --task-commit only accepts --from-readiness, --profile superpowers-parity-task-commits, --confirm, --json, and --root');
+  const envelope = taskCommitGateEnvelope(deps, options.root, options.fromReadiness);
+  const file = writeTaskCommitGate(deps, options.root, envelope);
+  const response = taskCommitGateResponse(envelope, file);
+  if (options.json) deps.writeJsonEnvelope('release', response);
+  else printTaskCommitGate(response, taskCommitGateDisplayPath(process, file));
+}
+
+export function runReleaseCommand(deps, options) {
+  const {
+    ensureRoot,
+    writeJsonEnvelope,
+    releaseGateAuditEnvelope,
+    releaseNotesAuditEnvelope,
+    releaseNotesEnvelope,
+    writeReleaseNotesArtifact,
+    buildReleaseGateEnvelope,
+    writeReleaseGateArtifact,
+    commitGuardEnvelope,
+    commitGuardBoundaryAssertions,
+    printRelease,
+    printCommitGuard,
+  } = deps;
+
+  ensureRoot(options.root);
+  const modes = [options.releaseGate, options.releaseVerifyGate, options.releaseNotes, options.releaseVerifyNotes, options.releaseCommitGuard, options.releaseCommitReadiness, options.releaseStagedCommitReadiness, options.releaseLocalCommitGate, options.releaseCloseoutReadiness, options.releaseTaskCommitReadiness, options.releaseTaskCommit, options.releaseDiffCoverage, options.releaseDiffRead, options.releaseSuitePlan].filter(Boolean);
+  if (modes.length !== 1) throw new Error('release requires exactly one of --gate, --verify-gate, --notes, --verify-notes, --commit-guard, --commit-readiness, --staged-commit-readiness, --local-commit-gate, --closeout-readiness, --task-commit-readiness, --task-commit, --diff-coverage, --diff-read, or --suite-plan');
+  if (options.changeKind !== 'unknown' && !options.releaseSuitePlan) throw new Error('--change-kind is only supported by release --suite-plan');
+  if (options.releaseVerifyGate && options.releaseWithConvergence) throw new Error('release --verify-gate does not accept --with-convergence');
+  if (!options.releaseGate && options.releaseWithConvergence) throw new Error('--with-convergence is only supported by release --gate');
+  if (options.methodologyIntent && !(options.releaseCommitReadiness || options.releaseTaskCommitReadiness)) throw new Error('--intent is only supported by release --commit-readiness');
+  if (options.fromPlan && !(options.releaseDiffCoverage || options.releaseDiffRead)) throw new Error('--from-plan is only supported by release --diff-coverage or release --diff-read');
+  if ((options.fromRunbook || options.selectedStage) && !options.releaseStagedCommitReadiness) throw new Error('--from-runbook and --stage are only supported by release --staged-commit-readiness');
+  if (options.fromEvidence && !(options.releaseStagedCommitReadiness || options.releaseCloseoutReadiness)) throw new Error('--from-evidence is only supported by release --staged-commit-readiness or release --closeout-readiness');
+  if (options.fromReadiness && !(options.releaseLocalCommitGate || options.releaseTaskCommit || options.releaseCloseoutReadiness)) throw new Error('--from-readiness is only supported by release --local-commit-gate, release --task-commit, or release --closeout-readiness');
+  if (options.fromDiffCoverage && !options.releaseCloseoutReadiness) throw new Error('--from-diff-coverage is only supported by release --closeout-readiness');
+  if (options.taskResultFile && !options.releaseTaskCommitReadiness) throw new Error('--from-task-result is only supported by release --task-commit-readiness');
+  if (options.releaseLocalCommitGate) return runReleaseLocalCommitGateMode(deps, options);
+  if (options.releaseCloseoutReadiness) return runReleaseCloseoutReadinessMode(deps, options);
+  if (options.releaseTaskCommitReadiness) return runReleaseTaskCommitReadinessMode(deps, options);
+  if (options.releaseTaskCommit) return runReleaseTaskCommitMode(deps, options);
+  if (options.releaseStagedCommitReadiness) return runReleaseStagedCommitReadinessMode(deps, options);
+  if (options.releaseSuitePlan) return runReleaseSuitePlanMode(deps, options);
+  if (options.releaseDiffRead) return runReleaseDiffReadMode(deps, options);
+  if (options.releaseDiffCoverage) return runReleaseDiffCoverageMode(deps, options);
+  if (options.releaseCommitReadiness) return runReleaseCommitReadinessMode(deps, options);
+  if (options.releaseCommitGuard) {
+    if (options.confirm || options.dryRun || options.write) throw new Error('release --commit-guard is read-only and does not accept --confirm, --preview, --dry-run, or --write');
+    const commitGuard = commitGuardEnvelope(options.root, { subject: options.commitSubject, evidenceFile: options.fromFile });
+    const envelope = {
+      mode: 'commit-title-guard',
+      ok: commitGuard.guard_pass,
+      state_present: releaseStatePresent(deps, options.root),
+      commit_guard: commitGuard,
+      safety: { stage: 'Stage 98', ...commitGuardBoundaryAssertions() },
+      quality: commitGuard.findings,
+      action: 'commit title guard was computed read-only from an explicit subject or local evidence file. No git command, commit, history rewrite, tag, PR, push, merge, platform API, external network, model invocation, state directory, sidecar, worktree write, runtime action, release gate requirement, or business source write occurred.',
+    };
+    if (options.json) writeJsonEnvelope('release', envelope);
+    else printCommitGuard(envelope);
+    return;
+  }
+  if (options.releaseVerifyGate) {
+    if (options.confirm) throw new Error('release --verify-gate is read-only');
+    if (!options.releaseGateFile) throw new Error('release --verify-gate requires a release gate file');
+    const envelope = releaseGateAuditEnvelope(options.root, options.releaseGateFile);
+    if (options.json) writeJsonEnvelope('release', envelope);
+    else printRelease(envelope);
+    return;
+  }
+  if (options.releaseVerifyNotes) {
+    if (options.confirm) throw new Error('release --verify-notes is read-only');
+    if (!options.releaseNotesFile) throw new Error('release --verify-notes requires a release notes file');
+    const envelope = releaseNotesAuditEnvelope(options.root, options.releaseNotesFile);
+    if (options.json) writeJsonEnvelope('release', envelope);
+    else printRelease(envelope);
+    return;
+  }
+  if (options.releaseNotes) {
+    if (options.confirm && options.dryRun) throw new Error('release --notes accepts either --preview or --confirm, not both');
+    if (!options.fromFile) throw new Error('release --notes requires --from-file <local-evidence-file>');
+    const envelope = releaseNotesEnvelope(options.root, { evidenceFile: options.fromFile, persist: options.confirm });
+    if (options.confirm) {
+      const file = writeReleaseNotesArtifact(options.root, envelope);
+      const response = { ...envelope, files: { release_notes: path.basename(file) }, release_notes_file: path.basename(file) };
+      if (options.json) writeJsonEnvelope('release', response);
+      else printRelease(response, file);
+      return;
+    }
+    if (options.json) writeJsonEnvelope('release', envelope);
+    else printRelease(envelope);
+    return;
+  }
+  if (options.releaseEvalFiles.length === 0) throw new Error('release --gate requires --from-evals');
+  const envelope = buildReleaseGateEnvelope(options.root, options.releaseEvalFiles, { persist: options.confirm, withConvergence: options.releaseWithConvergence });
+  if (options.confirm) {
+    const file = writeReleaseGateArtifact(options.root, envelope);
+    const response = { ...envelope, files: { release_gate: path.basename(file) }, release_gate_file: path.basename(file) };
+    if (options.json) writeJsonEnvelope('release', response);
+    else printRelease(response, file);
+    return;
+  }
+  if (options.json) writeJsonEnvelope('release', envelope);
+  else printRelease(envelope);
+}

package/tools/vibe-runtime/runtime-release-state-lifecycle-model.mjs

@@ -0,0 +1,48 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { localJsonFileWithinRoot } from './runtime-local-json-input.mjs';
+import { taskCommitGates, taskCommitSummary } from './runtime-task-commit-gates.mjs';
+import { taskCommitReadinessGate } from './runtime-task-commit-readiness.mjs';
+import { taskCommitSidecarGate, verifyTaskCommitReadiness } from './runtime-task-commit-sidecar.mjs';
+
+export function releaseStatePresent(deps, root) {
+  return fs.existsSync(deps.stateDirectory(root));
+}
+
+export function taskCommitReadinessEnvelope(deps, root, taskResultFile) {
+  const source = localJsonFileWithinRoot(root, taskResultFile, 'release --task-commit-readiness --from-task-result');
+  const summary = taskCommitSummary(source.data);
+  const gates = taskCommitGates(summary);
+  const blocked = gates.filter((item) => item.status !== 'ready').map((item) => `${item.id}: ${item.reason}`);
+  return taskCommitReadinessGate({ source, summary, gates, blocked, digestObject: deps.digestObject, statePresent: releaseStatePresent(deps, root) });
+}
+
+export function taskCommitGateEnvelope(deps, root, readinessFile) {
+  const source = localJsonFileWithinRoot(root, readinessFile, 'release --task-commit --from-readiness');
+  const readiness = source.data.task_commit_readiness || source.data.release_task_commit_readiness || source.data;
+  const verification = verifyTaskCommitReadiness(readiness, deps.digestObject);
+  if (!verification.ok) throw new Error(`task commit readiness verification failed: ${verification.failures.join('; ')}`);
+  if (readiness.gate_pass !== true) throw new Error('release --task-commit blocked: readiness gate is not pass-ready');
+  return taskCommitSidecarGate({
+    source,
+    readiness,
+    verification,
+    digestObject: deps.digestObject,
+    statePresent: releaseStatePresent(deps, root),
+  });
+}
+
+export function writeTaskCommitGate(deps, root, envelope) {
+  const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+  const file = `${stamp}.task-commit-gate.json`;
+  const payload = { schema_version: 1, command: 'release', ...envelope };
+  return deps.writeStateArtifact(path.join(root, '.vibecoding-state', 'task-commit-gates'), file, payload);
+}
+
+export function taskCommitGateResponse(envelope, file) {
+  return { ...envelope, files: { task_commit_gate: path.basename(file) }, task_commit_gate_file: path.basename(file) };
+}
+
+export function taskCommitGateDisplayPath(process, file) {
+  return path.relative(process.cwd(), file);
+}

package/tools/vibe-runtime/runtime-reply-artifact-lifecycle-model.mjs

@@ -0,0 +1,84 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+const schedName = ['sche', 'duler'].join('');
+const rtName = ['re', 'try'].join('');
+const stateArtifactWriterKey = ['write', 'State', 'Artifact'].join('');
+
+export function replyArtifactPath(root, directory, suffix) {
+  const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+  return path.join(directory(root), `${timestamp}.${suffix}.json`);
+}
+
+export function latestReplyArtifactDescriptor(deps, root, type, directory, extension) {
+  const fileName = deps.latestStateFile(root, directory, extension);
+  if (!fileName) return { type, file: '', digest: '', present: false };
+  const file = path.join(directory(root), fileName);
+  return { type, file: fileName, digest: deps.fileDigest(file), present: true };
+}
+
+export function replySourceManifest(deps, root) {
+  const workflowFile = deps.workflowPath(root);
+  const schedRunsDirectory = deps[`${schedName}RunsDirectory`];
+  const rtRunsDirectory = deps[`${rtName}RunsDirectory`];
+  const sources = [
+    { type: 'workflow', file: fs.existsSync(workflowFile) ? deps.workflowFileName : '', digest: deps.optionalFileDigest(workflowFile), present: fs.existsSync(workflowFile) },
+    latestReplyArtifactDescriptor(deps, root, 'latest_execution', deps.executionsDirectory, '.execution.json'),
+    latestReplyArtifactDescriptor(deps, root, `latest_${schedName}_run`, schedRunsDirectory, `.${schedName}-run.json`),
+    latestReplyArtifactDescriptor(deps, root, 'latest_recovery_run', deps.recoveryRunsDirectory, '.recovery-run.json'),
+    latestReplyArtifactDescriptor(deps, root, `latest_${rtName}_run`, rtRunsDirectory, `.${rtName}-run.json`),
+    latestReplyArtifactDescriptor(deps, root, 'latest_observability', deps.observabilityDirectory, '.observability.json'),
+    latestReplyArtifactDescriptor(deps, root, 'latest_runtime_trace', deps.runtimeTracesDirectory, '.runtime-trace.json'),
+  ];
+  const presentSources = sources.filter((source) => source.present);
+  return {
+    version: 1,
+    stage: 'Reply E',
+    source_bound: true,
+    sources,
+    present_count: presentSources.length,
+    source_digest: deps.digestObject(sources),
+    external_delivery: false,
+    model_invocation: false,
+  };
+}
+
+export function validateReplySourceManifest(deps, root, manifest) {
+  const failures = [];
+  if (!manifest || typeof manifest !== 'object') return ['reply source manifest is required'];
+  if (manifest.stage !== 'Reply E') failures.push('reply source manifest stage must be Reply E');
+  if (manifest.source_bound !== true) failures.push('reply source manifest source_bound must be true');
+  if (manifest.external_delivery !== false) failures.push('reply source manifest external_delivery must be false');
+  if (manifest.model_invocation !== false) failures.push('reply source manifest model_invocation must be false');
+  if (!Array.isArray(manifest.sources)) failures.push('reply source manifest sources must be an array');
+  else {
+    const expected = replySourceManifest(deps, root).sources;
+    const expectedTypes = expected.map((source) => source.type).sort();
+    const actualTypes = manifest.sources.map((source) => source?.type || '').sort();
+    const duplicateTypes = actualTypes.filter((type, index) => type && actualTypes.indexOf(type) !== index);
+    if (manifest.sources.length !== expected.length) failures.push('reply source manifest source count mismatch');
+    if (JSON.stringify(actualTypes) !== JSON.stringify(expectedTypes)) failures.push('reply source manifest source type set mismatch');
+    if (duplicateTypes.length > 0) failures.push(`reply source manifest duplicate source type: ${[...new Set(duplicateTypes)].join(', ')}`);
+    const currentByType = new Map(expected.map((source) => [source.type, source]));
+    for (const source of manifest.sources) {
+      const current = currentByType.get(source.type);
+      if (!current) {
+        failures.push(`reply source manifest unknown source type: ${source.type || ''}`);
+        continue;
+      }
+      if (source.present !== current.present) failures.push(`reply source manifest ${source.type} present mismatch`);
+      if (source.file !== current.file) failures.push(`reply source manifest ${source.type} file mismatch`);
+      if (source.digest !== current.digest) failures.push(`reply source manifest ${source.type} digest mismatch`);
+    }
+    const presentCount = manifest.sources.filter((source) => source?.present).length;
+    if (manifest.present_count !== presentCount) failures.push('reply source manifest present_count mismatch');
+    if (manifest.source_digest !== deps.digestObject(manifest.sources)) failures.push('reply source manifest source_digest mismatch');
+  }
+  return failures;
+}
+
+export function writeReplyArtifact(deps, root, directory, suffix, envelope) {
+  const file = replyArtifactPath(root, directory, suffix);
+  const persistStateArtifact = deps[stateArtifactWriterKey];
+  return persistStateArtifact(path.dirname(file), path.basename(file), { schema_version: deps.jsonSchemaVersion, command: 'reply', ...envelope });
+}