@jtf19/vibecoding-kit 0.1.0

package/tools/vibe-runtime/runtime-workflow-discipline-summary.mjs

@@ -0,0 +1,164 @@
+export function buildWorkflowDisciplineSummary({
+  prompt = '',
+  profile = 'vibe-guided',
+  normalizedIntent = '',
+  entrySummary = {},
+  receipt = {},
+  cockpit = {},
+  readiness = {},
+  boundaryAssertions = {},
+  digestObject,
+} = {}) {
+  const protocolLayer = workflowDisciplineProtocolLayer(entrySummary, readiness);
+  const summary = {
+    version: 1,
+    stage: 'Stage 93',
+    discipline_kind: 'workflow-entry-discipline-summary',
+    prompt: String(prompt || '').trim(),
+    automation_profile: profile || 'vibe-guided',
+    normalized_intent: normalizedIntent || '',
+    protocol_layer: protocolLayer,
+    visible_first_step: receipt.selected_skill || 'using-vibecoding',
+    visible_next_action: entrySummary.first_user_decision || cockpit.next_manual_action || '',
+    recommended_next_skill: cockpit.recommended_next_skill || '',
+    entry_classification: entrySummary.entry_classification || 'unknown',
+    state_gap_is_expected: entrySummary.state_gap_is_expected === true,
+    readiness_blocker_count: Number(entrySummary.readiness_blocker_count ?? 0),
+    context_policy: {
+      default_context: 'tiny_context',
+      full_skill_injection: false,
+      raw_evidence_loaded: false,
+      upgrade_to_balanced_when: [
+        'implementation, debugging, or completion verification needs evidence detail',
+        'handoff, stage transition, or risk boundary requires more context',
+      ],
+      full_maintenance_context_only_when_requested: true,
+    },
+    visible_claims: {
+      skill_execution_claimed: false,
+      workflow_execution_claimed: false,
+      command_execution_claimed: false,
+      subagent_dispatch_claimed: false,
+      state_write_claimed: false,
+      git_write_claimed: false,
+      source_write_claimed: false,
+    },
+    escalation_triggers: [
+      'goal, scope, acceptance, or validation strategy is missing',
+      'architecture, state lifecycle, controlled action, background automation, source, history, or delegated work boundary changes are requested',
+      'review, completion, branch closeout, or context handoff is requested',
+    ],
+    blocked_summary: {
+      ready_to_start: readiness.ready_to_start === true,
+      blocking_safety_issues: Array.isArray(entrySummary.blocking_safety_issues) ? entrySummary.blocking_safety_issues : [],
+      blocker_count: Number(entrySummary.readiness_blocker_count ?? 0),
+    },
+    boundary_assertions: workflowDisciplineBoundaryAssertions(boundaryAssertions),
+    writes: false,
+    state_directory_created: false,
+    local_only: true,
+    deterministic: true,
+  };
+  const invariants = workflowDisciplineSummaryInvariants(summary);
+  const withInvariants = {
+    ...summary,
+    workflow_discipline_invariants: invariants,
+  };
+  return {
+    ...withInvariants,
+    discipline_digest: typeof digestObject === 'function' ? digestObject(workflowDisciplineSummaryDigestPayload(withInvariants)) : '',
+  };
+}
+
+export function workflowDisciplineBoundaryAssertions(boundaryAssertions = {}) {
+  const protectedKeys = [
+    'writes',
+    'state_directory_created',
+    'workflow_start_artifact',
+    'sidecar_write',
+    'source_write',
+    'skill_execution',
+    'command_execution',
+    'runtime_action',
+    'auto_execution',
+    'external_network',
+    'model_invocation',
+    'platform_api',
+    'git',
+    'git_write',
+    'worktree',
+    'pr',
+    'push',
+    'merge',
+    'tag',
+    'subagent',
+    'mcp',
+    'shell_interception',
+    'business_source_write',
+    'source_merge',
+  ];
+  return Object.fromEntries(protectedKeys.map((key) => [key, boundaryAssertions[key] === true ? true : false]));
+}
+
+export function workflowDisciplineSummaryDigestPayload(summary) {
+  return {
+    stage: summary.stage,
+    discipline_kind: summary.discipline_kind,
+    prompt: summary.prompt,
+    automation_profile: summary.automation_profile,
+    normalized_intent: summary.normalized_intent,
+    protocol_layer: summary.protocol_layer,
+    visible_first_step: summary.visible_first_step,
+    visible_next_action: summary.visible_next_action,
+    recommended_next_skill: summary.recommended_next_skill,
+    entry_classification: summary.entry_classification,
+    state_gap_is_expected: summary.state_gap_is_expected,
+    readiness_blocker_count: summary.readiness_blocker_count,
+    context_policy: summary.context_policy,
+    visible_claims: summary.visible_claims,
+    escalation_triggers: summary.escalation_triggers,
+    blocked_summary: summary.blocked_summary,
+    boundary_assertions: summary.boundary_assertions,
+    workflow_discipline_invariants: summary.workflow_discipline_invariants,
+  };
+}
+
+export function workflowDisciplineSummaryInvariants(summary) {
+  const boundary = summary.boundary_assertions || {};
+  const unsafeBoundaries = Object.entries(boundary)
+    .filter(([, value]) => value !== false)
+    .map(([key]) => key);
+  const visibleClaimViolations = Object.entries(summary.visible_claims || {})
+    .filter(([, value]) => value !== false)
+    .map(([key]) => key);
+  const findings = [
+    ...(summary.stage === 'Stage 93' ? [] : ['stage must be Stage 93']),
+    ...(summary.discipline_kind === 'workflow-entry-discipline-summary' ? [] : ['discipline_kind must be workflow-entry-discipline-summary']),
+    ...(summary.visible_first_step ? [] : ['visible_first_step is required']),
+    ...(summary.visible_next_action ? [] : ['visible_next_action is required']),
+    ...(summary.context_policy?.default_context === 'tiny_context' ? [] : ['context_policy.default_context must be tiny_context']),
+    ...(summary.context_policy?.full_skill_injection === false ? [] : ['context_policy.full_skill_injection must remain false']),
+    ...(summary.context_policy?.full_maintenance_context_only_when_requested === true ? [] : ['full maintenance context must require an explicit request']),
+    ...visibleClaimViolations.map((key) => `visible claim must remain false: ${key}`),
+    ...unsafeBoundaries.map((key) => `boundary assertion must remain false: ${key}`),
+  ];
+  return {
+    pass: findings.length === 0,
+    checked: [
+      'visible_entry_step',
+      'visible_next_action',
+      'tiny_context_default',
+      'no_full_skill_injection',
+      'no_false_execution_claims',
+      'read_only_boundary_assertions',
+    ],
+    findings,
+  };
+}
+
+function workflowDisciplineProtocolLayer(entrySummary, readiness) {
+  if (entrySummary.blocking_safety_issues?.length > 0) return 'L2-boundary-stop';
+  if (entrySummary.entry_classification === 'planning_needed') return 'L2-planning';
+  if (readiness.ready_to_start === true) return 'L1-standard-execution-ready';
+  return 'L1-evidence-or-scope-needed';
+}

package/tools/vibe-runtime/runtime-workflow-entry-envelopes.mjs

@@ -0,0 +1,156 @@
+import {
+  bootstrapPromptIntent,
+  buildEntryAdviceModel,
+  buildEntryContractModel,
+  entryAutomationProfile,
+  entryRecommendedLayer,
+} from './runtime-entry-advice-model.mjs';
+import { buildWorkflowStartEnvelopeModel } from './runtime-workflow-start-model.mjs';
+import { methodologyBoundaryAssertions } from './runtime-methodology-route-model.mjs';
+import { workflowReceiptBoundaryAssertions } from './runtime-workflow-ux-model.mjs';
+import {
+  normalizeWorkflowReadinessIntent,
+  workflowReadinessRouteIntent,
+} from './runtime-workflow-readiness-model.mjs';
+
+function effectiveEntryAutomationProfile(context, root, profile = '') {
+  const explicit = String(profile || '').trim();
+  if (explicit) {
+    return { profile: entryAutomationProfile(explicit), source: 'explicit-cli-profile' };
+  }
+  if (typeof context.resolveAutomationProfile === 'function') {
+    return context.resolveAutomationProfile(root);
+  }
+  return { profile: entryAutomationProfile('vibe-guided'), source: 'vibe-guided-fallback' };
+}
+
+function workflowReceiptEnvelope(context, root, { intent = '' } = {}) {
+  const { ensureRoot, isWorkflowRecorded, methodologyRouteEnvelope, digestObject } = context;
+  ensureRoot(root);
+  const normalizedIntent = normalizeWorkflowReadinessIntent(intent || 'unknown');
+  const routeEnvelope = methodologyRouteEnvelope(root, workflowReadinessRouteIntent(normalizedIntent));
+  const route = routeEnvelope.methodology_route;
+  const recommendedLayer = entryRecommendedLayer(route);
+  const selectedSkill = recommendedLayer === 'L0' ? 'using-vibecoding-lightweight-route' : route.first_skill;
+  const because = recommendedLayer === 'L0'
+    ? 'the request is narrow enough for lightweight workflow routing without full handoff ceremony'
+    : route.rationale;
+  const userVisibleSentence = recommendedLayer === 'L0'
+    ? '我会先按 Vibecoding 轻量入口判断处理，并在需要时说明验证方式。'
+    : `我会使用 \`${route.first_skill}\`，因为${route.rationale}。`;
+  const boundaryAssertions = workflowReceiptBoundaryAssertions();
+  const receipt = {
+    version: 1,
+    stage: 'Stage 92',
+    receipt_kind: 'visible-skill-invocation',
+    input_intent: String(intent || '').trim(),
+    normalized_intent: normalizedIntent,
+    recommended_layer: recommendedLayer,
+    selected_skill: selectedSkill,
+    because,
+    user_visible_sentence: userVisibleSentence,
+    handoff_required: recommendedLayer === 'L2',
+    route_summary: {
+      first_skill: route.first_skill,
+      selected_workflow: route.selected_workflow,
+      route_digest: route.route_digest,
+    },
+    false_claim_guardrails: [
+      'do not say a skill was used unless the response follows that skill goal, boundary, and handoff requirements',
+      'use future-tense invocation before entering a skill; do not claim completed skill execution from this read-only receipt',
+      'L0 tasks may use lightweight routing without naming a full workflow skill',
+    ],
+    boundary_assertions: boundaryAssertions,
+    writes: false,
+    state_directory_created: false,
+    local_only: true,
+    deterministic: true,
+  };
+  return {
+    mode: 'visible-skill-invocation',
+    ok: true,
+    state_present: isWorkflowRecorded(root),
+    workflow_receipt: { ...receipt, receipt_digest: digestObject(receipt) },
+    safety: { stage: 'Stage 92', ...boundaryAssertions },
+    quality: [],
+    action: 'workflow receipt was computed read-only from methodology route and entry layering rules. No state directory, sidecar, source write, workflow skill execution, command execution, runtime action, platform API, external network, model, git, worktree, subagent, MCP, daemon, PR, push, merge, tag, or business source mutation occurred.',
+  };
+}
+
+function entryAdviceEnvelope(context, root, intent) {
+  const { methodologyRouteEnvelope, digestObject } = context;
+  const routeEnvelope = methodologyRouteEnvelope(root, intent);
+  const route = routeEnvelope.methodology_route;
+  return {
+    mode: 'entry-advice',
+    ok: true,
+    state_present: routeEnvelope.state_present,
+    entry_advice: buildEntryAdviceModel({ route, digestObject }),
+    methodology_route: route,
+    safety: { stage: 'Stage 78', writes: false, entry_advice_artifact: false, ...methodologyBoundaryAssertions() },
+    quality: routeEnvelope.quality,
+    action: 'entry advice was computed read-only. No state directory, workflow skill execution, dispatch, subagent, platform API, external network, model, git, worktree, or business source write occurred.',
+  };
+}
+
+function entryContractEnvelope(context, root, { intent = '', prompt = '', profile = '' } = {}) {
+  const { ensureRoot, isWorkflowRecorded, methodologyRouteEnvelope, bootstrapAcceptanceEnvelope, digestObject } = context;
+  ensureRoot(root);
+  const effectiveProfile = effectiveEntryAutomationProfile(context, root, profile);
+  const inferredIntent = prompt ? bootstrapPromptIntent(prompt) : normalizeWorkflowReadinessIntent(intent || 'unknown');
+  const routeEnvelope = methodologyRouteEnvelope(root, workflowReadinessRouteIntent(inferredIntent));
+  const route = routeEnvelope.methodology_route;
+  const acceptance = bootstrapAcceptanceEnvelope(root, { prompt: prompt || (intent ? `intent:${intent}` : '') }).bootstrap_acceptance;
+  const { contract, blockedReasons, boundaryAssertions } = buildEntryContractModel({
+    prompt,
+    intent,
+    inferredIntent,
+    route,
+    acceptance,
+    profile: effectiveProfile.profile,
+    digestObject,
+  });
+  return {
+    mode: 'workflow-entry-contract',
+    ok: true,
+    state_present: isWorkflowRecorded(root),
+    entry_contract: contract,
+    methodology_route: route,
+    safety: { stage: 'Stage 91', ...boundaryAssertions },
+    quality: blockedReasons,
+    action: 'entry contract was computed read-only from methodology route and bootstrap acceptance. No state directory, source write, sidecar, workflow skill execution, command execution, runtime action, git, PR, push, merge, tag, platform API, external network, model, worktree, subagent, MCP, daemon, shell interception, or business source mutation occurred.',
+  };
+}
+
+function workflowStartEnvelope(context, root, { intent = '', prompt = '', planFile = '', profile = '' } = {}) {
+  const { ensureRoot, isWorkflowRecorded, workflowReadinessEnvelope, workflowCockpitEnvelope, digestObject } = context;
+  ensureRoot(root);
+  const effectiveProfile = effectiveEntryAutomationProfile(context, root, profile);
+  const normalizedIntent = normalizeWorkflowReadinessIntent(intent || (prompt ? bootstrapPromptIntent(prompt) : 'unknown'));
+  const contract = entryContractEnvelope(context, root, { intent: normalizedIntent, prompt, profile: effectiveProfile.profile }).entry_contract;
+  const receipt = workflowReceiptEnvelope(context, root, { intent: normalizedIntent }).workflow_receipt;
+  const cockpit = workflowCockpitEnvelope(root, { intent: normalizedIntent, planFile }).workflow_cockpit;
+  const readiness = workflowReadinessEnvelope(root, { intent: normalizedIntent }).workflow_readiness;
+  return buildWorkflowStartEnvelopeModel({
+    intent,
+    prompt,
+    normalizedIntent,
+    contract,
+    receipt,
+    cockpit,
+    readiness,
+    profile: effectiveProfile.profile,
+    profileSource: effectiveProfile.source,
+    statePresent: isWorkflowRecorded(root),
+    digestObject,
+  });
+}
+
+export function createRuntimeWorkflowEntryEnvelopes(deps) {
+  return {
+    entryAdviceEnvelope: (root, intent) => entryAdviceEnvelope(deps, root, intent),
+    entryContractEnvelope: (root, options) => entryContractEnvelope(deps, root, options),
+    workflowReceiptEnvelope: (root, options) => workflowReceiptEnvelope(deps, root, options),
+    workflowStartEnvelope: (root, options) => workflowStartEnvelope(deps, root, options),
+  };
+}

package/tools/vibe-runtime/runtime-workflow-ledger-command.mjs

@@ -0,0 +1,239 @@
+import {
+  resetWorkflowLedgerState,
+  writeWorkflowRootArtifacts,
+  writeWorkflowTaskArtifacts,
+} from './runtime-workflow-ledger-state-lifecycle-model.mjs';
+
+export function createRuntimeWorkflowLedgerCommand(deps) {
+  const {
+    path,
+    process,
+    ensureRoot,
+    readWorkflow,
+    writeJsonEnvelope,
+    validateState,
+    tasksFromState,
+    jsonTaskSummaries,
+    taskSummaryStatus,
+    taskReadinessSummaryLine,
+    reviewSummaryStatus,
+    generateArtifacts,
+    generateTaskArtifacts,
+    filterTaskArtifacts,
+    nextAdvice,
+    stateDirectoryName,
+    taskArtifactsDirectoryName,
+    confirmDispatchEnvelope,
+    writeDispatchEvent,
+    printConfirmDispatch,
+    dispatchIntentEnvelope,
+    printDispatchIntent,
+  } = deps;
+
+  function printList(title, items) {
+    if (!items || items.length === 0) return;
+    console.log(`${title}:`);
+    for (const item of items) {
+      console.log(`- ${item}`);
+    }
+  }
+
+  function printTaskArtifacts(taskArtifacts, options = {}) {
+    console.log('Vibecoding Runtime Task Artifacts');
+    console.log('Mode: dry-run');
+    if (options.task) {
+      console.log(`Task filter: ${options.task}`);
+      console.log(`Tasks selected: ${taskArtifacts.length} of ${options.totalTasks}`);
+    }
+    if (taskArtifacts.length === 0) {
+      console.log('Tasks: not recorded');
+      console.log('Action: task artifacts were previewed. No files were written.');
+      return;
+    }
+
+    for (const entry of taskArtifacts) {
+      for (const [fileName, content] of Object.entries(entry.files)) {
+        console.log(`\n--- ${stateDirectoryName}/${taskArtifactsDirectoryName}/${entry.task.id}/${fileName} ---`);
+        console.log(content.trimEnd());
+      }
+    }
+    console.log('\nAction: task artifacts were previewed. No files were written.');
+  }
+
+  function runTasks(options) {
+    if (options.dryRun && options.write) throw new Error('tasks accepts either --dry-run or --write, not both');
+    if (options.json && options.write) throw new Error('tasks --json is only supported with dry-run output');
+    ensureRoot(options.root);
+    const state = readWorkflow(options.root);
+    if (!state) throw new Error('Workflow state not found. Record a handoff before generating task artifacts.');
+    validateState(state);
+
+    const allTaskArtifacts = generateTaskArtifacts(state);
+    const taskArtifacts = filterTaskArtifacts(allTaskArtifacts, options.task);
+
+    if (!options.write) {
+      if (options.json) {
+        const selectedTasks = taskArtifacts.map((entry) => entry.task);
+        writeJsonEnvelope('tasks', {
+          mode: 'dry-run',
+          ok: true,
+          state_present: true,
+          summary: {
+            total_tasks: allTaskArtifacts.length,
+            selected_count: taskArtifacts.length,
+            selected_task_ids: selectedTasks.map((task) => task.id),
+            task_filter: options.task || '',
+            task_status: taskSummaryStatus(selectedTasks),
+            task_readiness: taskReadinessSummaryLine(selectedTasks),
+            review_status: reviewSummaryStatus(selectedTasks),
+          },
+          tasks: jsonTaskSummaries(selectedTasks, tasksFromState(state)),
+          quality: [],
+          action: 'task artifacts were previewed. No files were written.',
+        });
+        return;
+      }
+      printTaskArtifacts(taskArtifacts, { task: options.task, totalTasks: allTaskArtifacts.length });
+      return;
+    }
+
+    const writtenTaskArtifacts = writeWorkflowTaskArtifacts(deps, options.root, taskArtifacts);
+
+    console.log('Vibecoding Runtime Task Artifacts');
+    console.log('Mode: write');
+    if (options.task) {
+      console.log(`Task filter: ${options.task}`);
+      console.log(`Tasks selected: ${taskArtifacts.length} of ${allTaskArtifacts.length}`);
+    }
+    if (taskArtifacts.length === 0) {
+      console.log('Tasks: not recorded');
+    }
+    for (const entry of writtenTaskArtifacts) {
+      for (const file of entry.files) {
+        console.log(`Wrote ${path.relative(process.cwd(), file.filePath)}`);
+      }
+    }
+    console.log('Action: task artifacts were written. No next skill was executed.');
+  }
+
+  function printArtifacts(artifacts) {
+    console.log('Vibecoding Runtime Artifacts');
+    console.log('Mode: dry-run');
+    for (const [fileName, content] of Object.entries(artifacts)) {
+      console.log(`\n--- ${stateDirectoryName}/${fileName} ---`);
+      console.log(content.trimEnd());
+    }
+    console.log('\nAction: artifacts were previewed. No files were written.');
+  }
+
+  function runArtifacts(options) {
+    if (options.json) throw new Error('artifacts does not support --json in this stage');
+    if (options.dryRun && options.write) throw new Error('artifacts accepts either --dry-run or --write, not both');
+    ensureRoot(options.root);
+    const state = readWorkflow(options.root);
+    if (!state) throw new Error('Workflow state not found. Record a handoff before generating artifacts.');
+    validateState(state);
+
+    const artifacts = generateArtifacts(state);
+
+    if (!options.write) {
+      printArtifacts(artifacts);
+      return;
+    }
+
+    const writtenArtifacts = writeWorkflowRootArtifacts(deps, options.root, artifacts);
+
+    console.log('Vibecoding Runtime Artifacts');
+    console.log('Mode: write');
+    for (const file of writtenArtifacts) {
+      console.log(`Wrote ${path.relative(process.cwd(), file.filePath)}`);
+    }
+    console.log('Action: artifacts were written. No next skill was executed.');
+  }
+
+  function printNextAdvice(advice) {
+    console.log('Vibecoding Runtime Next Step');
+    console.log('Mode: dry-run');
+    console.log(`Status: ${advice.status}`);
+    console.log(`Current skill: ${advice.currentSkill}`);
+    console.log(`Next skill: ${advice.nextSkill}`);
+    if (advice.reason) console.log(`Reason: ${advice.reason}`);
+    if (advice.stopCondition) console.log(`Stop condition: ${advice.stopCondition}`);
+    if (advice.taskStatus) console.log(`Task status: ${advice.taskStatus}`);
+    if (advice.taskReadiness) console.log(`Task readiness: ${advice.taskReadiness}`);
+    if (advice.reviewStatus) console.log(`Review status: ${advice.reviewStatus}`);
+    console.log(`Manual action: ${advice.manualAction}`);
+    printList('Risks', advice.risks);
+    printList('Acceptance', advice.acceptance);
+    console.log('Action: no skill was executed.');
+  }
+
+  function runNext(options) {
+    if (options.confirm && options.dispatchIntent) throw new Error('next --confirm --dispatch-intent is not supported in Stage 5');
+    if (options.dispatchIntent && !options.dryRun) throw new Error('next --dispatch-intent requires --dry-run in this stage');
+    if (options.dispatch && options.dryRun) throw new Error('next --dispatch does not support --dry-run');
+    if (options.dispatch && !options.confirm) throw new Error('next --dispatch requires --confirm');
+    if (options.confirm && !options.dispatch) throw new Error('next --confirm requires --dispatch');
+    if (!options.dryRun && !options.dispatch) throw new Error('next only supports --dry-run or --confirm --dispatch in this stage');
+    const state = readWorkflow(options.root);
+    const advice = nextAdvice(state);
+    if (options.dispatch) {
+      const envelope = confirmDispatchEnvelope(state, advice);
+      const file = writeDispatchEvent(options.root, envelope);
+      if (options.json) {
+        writeJsonEnvelope('next', envelope);
+        return;
+      }
+      printConfirmDispatch(envelope, file);
+      return;
+    }
+    if (options.dispatchIntent) {
+      const intent = dispatchIntentEnvelope(state, advice);
+      if (options.json) {
+        writeJsonEnvelope('next', intent);
+        return;
+      }
+      printDispatchIntent(intent);
+      return;
+    }
+    if (options.json) {
+      writeJsonEnvelope('next', {
+        mode: 'dry-run',
+        ok: true,
+        state_present: Boolean(state),
+        summary: {
+          status: advice.status,
+          current_skill: advice.currentSkill,
+          next_skill: advice.nextSkill,
+          reason: advice.reason || '',
+          stop_condition: advice.stopCondition || '',
+          manual_action: advice.manualAction,
+          task_status: advice.taskStatus || 'not recorded',
+          task_readiness: advice.taskReadiness || 'not recorded',
+          review_status: advice.reviewStatus || 'not recorded',
+          risks: advice.risks || [],
+          acceptance: advice.acceptance || [],
+        },
+        tasks: state ? jsonTaskSummaries(tasksFromState(state)) : [],
+        quality: [],
+        action: 'no skill was executed.',
+      });
+      return;
+    }
+    printNextAdvice(advice);
+  }
+
+  function runReset(options) {
+    if (options.json) throw new Error('reset does not support --json in this stage');
+    if (!options.confirm) throw new Error('reset requires --confirm');
+    const directory = resetWorkflowLedgerState(deps, options.root);
+    console.log(`Removed ${path.relative(process.cwd(), directory)}`);
+  }
+
+  return {
+    runArtifacts,
+    runNext,
+    runReset,
+    runTasks,
+  };
+}

package/tools/vibe-runtime/runtime-workflow-ledger-state-lifecycle-model.mjs

@@ -0,0 +1,46 @@
+function requireWorkflowStateDirectory(deps, root) {
+  const directory = deps.stateDirectory(root);
+  const { existsSync } = deps.fs;
+  if (!existsSync(directory)) throw new Error(`State directory not found: ${directory}`);
+  return directory;
+}
+
+export function writeWorkflowTaskArtifacts(deps, root, taskArtifacts) {
+  requireWorkflowStateDirectory(deps, root);
+  const { mkdirSync, writeFileSync } = deps.fs;
+  const written = [];
+
+  for (const entry of taskArtifacts) {
+    mkdirSync(deps.taskDirectory(root, entry.task.id), { recursive: true });
+    const files = [];
+    for (const [fileName, content] of Object.entries(entry.files)) {
+      const filePath = deps.taskArtifactPath(root, entry.task.id, fileName);
+      writeFileSync(filePath, content, 'utf8');
+      files.push({ fileName, filePath });
+    }
+    written.push({ task: entry.task, files });
+  }
+
+  return written;
+}
+
+export function writeWorkflowRootArtifacts(deps, root, artifacts) {
+  requireWorkflowStateDirectory(deps, root);
+  const { writeFileSync } = deps.fs;
+  const written = [];
+
+  for (const [fileName, content] of Object.entries(artifacts)) {
+    const filePath = deps.artifactPath(root, fileName);
+    writeFileSync(filePath, content, 'utf8');
+    written.push({ fileName, filePath });
+  }
+
+  return written;
+}
+
+export function resetWorkflowLedgerState(deps, root) {
+  const directory = deps.stateDirectory(root);
+  const { rmSync } = deps.fs;
+  rmSync(directory, { recursive: true, force: true });
+  return directory;
+}