@jtf19/vibecoding-kit 0.1.0

package/tools/vibe-runtime/runtime-foreground-worker-plan.mjs

@@ -0,0 +1,275 @@
+import crypto from 'node:crypto';
+import { buildControlledLongRunningAutomationContract } from './runtime-controlled-long-running-automation-contract.mjs';
+
+const stage = 'Stage 14';
+const kind = 'leased-foreground-worker-plan';
+const lifecycleSteps = Object.freeze([
+  'acquire lease',
+  'run one approved item',
+  'heartbeat',
+  'evidence audit',
+  'release lease',
+  'summary',
+]);
+const stopConditions = Object.freeze([
+  'hidden background worker requested',
+  'watcher requested',
+  'automatic polling requested',
+  'cross-process preemption requested',
+  'automatic cleanup requested',
+  'automatic dispatch requested',
+  'platform API requested',
+  'source or git coupling requested',
+  'stop file present',
+  'lease missing or stale',
+  'max iterations exceeded',
+  'max item count exceeded',
+]);
+
+function asArray(value) {
+  return Array.isArray(value) ? value : [];
+}
+
+function uniqueStrings(value) {
+  return [...new Set(asArray(value).map((item) => String(item || '').trim()).filter(Boolean))];
+}
+
+function bool(value) {
+  return value === true || value === 'true' || value === 'approved' || value === 'fresh' || value === 'present' || value === 'active';
+}
+
+function numeric(value, fallback) {
+  const number = Number(value);
+  return Number.isFinite(number) ? Math.floor(number) : fallback;
+}
+
+function normalizeWorkerInput(input = {}) {
+  const lease = input.lease || {};
+  const heartbeat = input.heartbeat || {};
+  const stopFile = input.stop_file || input.stopFile || {};
+  const controls = input.controls || input.worker_controls || {};
+  const approvedItems = asArray(input.approved_items || input.items || input.runbook_items);
+  const firstItem = approvedItems[0] || input.item || {};
+  const flags = input.flags || input.risks || {};
+  const maxIterations = numeric(controls.max_iterations ?? input.max_iterations, 1);
+  const maxItemCount = numeric(controls.max_item_count ?? input.max_item_count, approvedItems.length || 1);
+  const maxRuntimeMs = numeric(controls.max_runtime_ms ?? input.max_runtime_ms, 60_000);
+  return {
+    item_id: String(firstItem.item_id || firstItem.id || input.item_id || 'foreground-worker-item'),
+    item_approved: bool(firstItem.approved ?? input.approved),
+    approved_item_count: approvedItems.length || (firstItem && Object.keys(firstItem).length > 0 ? 1 : 0),
+    lease_required: lease.required !== false,
+    lease_acquired: bool(lease.acquired ?? lease.present),
+    lease_stale: bool(lease.stale),
+    lease_id: String(lease.id || lease.lease_id || ''),
+    heartbeat_required: heartbeat.required !== false,
+    heartbeat_interval_ms: numeric(heartbeat.interval_ms ?? heartbeat.heartbeat_interval_ms, 10_000),
+    stop_file_required: stopFile.required !== false,
+    stop_file_path: String(stopFile.path || stopFile.file || '.vibecoding-state/daemon-stop/stop.json'),
+    stop_file_present: bool(stopFile.present),
+    max_iterations: maxIterations,
+    max_item_count: maxItemCount,
+    max_runtime_ms: maxRuntimeMs,
+    hidden_background_worker: bool(flags.hidden_background_worker ?? input.hidden_background_worker),
+    watcher: bool(flags.watcher ?? input.watcher),
+    automatic_polling: bool(flags.automatic_polling ?? input.automatic_polling),
+    cross_process_preemption: bool(flags.cross_process_preemption ?? input.cross_process_preemption),
+    automatic_cleanup: bool(flags.automatic_cleanup ?? input.automatic_cleanup),
+    automatic_dispatch: bool(flags.automatic_dispatch ?? input.automatic_dispatch),
+    platform_api: bool(flags.platform_api ?? input.platform_api),
+    source_coupling: bool(flags.source_coupling ?? input.source_coupling),
+    git_coupling: bool(flags.git_coupling ?? input.git_coupling),
+  };
+}
+
+function blockedReasons(controls) {
+  return uniqueStrings([
+    ...(controls.item_approved ? [] : ['worker may only process an approved runbook item']),
+    ...(controls.approved_item_count === 1 ? [] : ['worker dry-run must target exactly one approved item']),
+    ...(controls.lease_required && controls.lease_acquired && !controls.lease_stale ? [] : ['fresh foreground lease is required']),
+    ...(controls.heartbeat_required && controls.heartbeat_interval_ms > 0 ? [] : ['heartbeat policy is required']),
+    ...(controls.stop_file_required && controls.stop_file_path ? [] : ['stop file policy is required']),
+    ...(controls.stop_file_present ? ['stop file present'] : []),
+    ...(controls.max_iterations > 0 && controls.max_iterations <= 3 ? [] : ['max iterations must be between 1 and 3']),
+    ...(controls.max_item_count === 1 ? [] : ['max item count must be exactly 1 for Stage 14 foreground worker']),
+    ...(controls.max_runtime_ms > 0 && controls.max_runtime_ms <= 300_000 ? [] : ['max runtime must be positive and no more than 300000ms']),
+    ...(controls.hidden_background_worker ? ['hidden background worker requested'] : []),
+    ...(controls.watcher ? ['watcher requested'] : []),
+    ...(controls.automatic_polling ? ['automatic polling requested'] : []),
+    ...(controls.cross_process_preemption ? ['cross-process preemption requested'] : []),
+    ...(controls.automatic_cleanup ? ['automatic cleanup requested'] : []),
+    ...(controls.automatic_dispatch ? ['automatic dispatch requested'] : []),
+    ...(controls.platform_api ? ['platform API requested'] : []),
+    ...(controls.source_coupling || controls.git_coupling ? ['source or git coupling requested'] : []),
+  ]);
+}
+
+function lifecycleFor(controls, blocked) {
+  const executable = blocked.length === 0;
+  return lifecycleSteps.map((step, index) => ({
+    index: index + 1,
+    step,
+    planned: true,
+    executed: false,
+    dry_run: true,
+    budget_consumed: step === 'run one approved item' ? 1 : 0,
+    evidence_written: false,
+    status: executable ? 'planned' : 'blocked',
+    item_id: step === 'run one approved item' ? controls.item_id : '',
+  }));
+}
+
+export function buildLeasedForegroundWorkerPlan({ input = {}, source = {}, digestObject } = {}) {
+  const controls = normalizeWorkerInput(input);
+  const blocked = blockedReasons(controls);
+  const lifecycle = lifecycleFor(controls, blocked);
+  const ready = blocked.length === 0;
+  const core = {
+    version: 1,
+    stage,
+    plan_kind: kind,
+    source_file: source.relative || source.file || '',
+    source_digest: source.digest || '',
+    status: ready ? 'foreground-worker-dry-run-ready' : 'blocked',
+    lifecycle,
+    lease: {
+      required: controls.lease_required,
+      acquired_for_plan: controls.lease_acquired,
+      stale: controls.lease_stale,
+      lease_id: controls.lease_id,
+      release_required: true,
+    },
+    heartbeat: {
+      required: controls.heartbeat_required,
+      interval_ms: controls.heartbeat_interval_ms,
+      dry_run_written: false,
+      stale_lease_audit_required: true,
+    },
+    stop_file: {
+      required: controls.stop_file_required,
+      path: controls.stop_file_path,
+      present: controls.stop_file_present,
+      kill_switch: true,
+    },
+    controls: {
+      foreground_only: true,
+      hidden_background_worker: false,
+      scheduler: false,
+      background: false,
+      watcher: false,
+      automatic_polling: false,
+      max_iterations: controls.max_iterations,
+      max_item_count: controls.max_item_count,
+      max_runtime_ms: controls.max_runtime_ms,
+      source_coupling: false,
+      git_coupling: false,
+      platform_api: false,
+      automatic_cleanup: false,
+      automatic_dispatch: false,
+      cross_process_preemption: false,
+    },
+    approved_item: {
+      item_id: controls.item_id,
+      approved: controls.item_approved,
+      approved_item_count: controls.approved_item_count,
+      run_one_item_only: true,
+    },
+    stop_conditions: [...stopConditions],
+    blocked_reasons: blocked,
+    dry_run_only: true,
+    writes: false,
+    evidence_audit: {
+      required_after_each_step: true,
+      evidence_written_by_plan: false,
+      budget_consumed_per_step: true,
+      summary_required: true,
+    },
+    controlled_long_running_automation: buildControlledLongRunningAutomationContract({
+      phase: 'leased-foreground-worker-dry-run',
+      artifactSummary: {
+        source_stage: stage,
+        status: ready ? 'foreground-worker-dry-run-ready' : 'blocked',
+        max_iterations: controls.max_iterations,
+        max_item_count: controls.max_item_count,
+        approved_item_count: controls.approved_item_count,
+      },
+      policyBound: true,
+      loopPolicyBound: true,
+      lockAuditBound: controls.lease_required,
+      heartbeatPolicyBound: controls.heartbeat_required,
+      stopFilePolicyBound: controls.stop_file_required,
+      iterationBudgetBound: controls.max_iterations > 0,
+      killSwitchBound: true,
+      blockedReasons: blocked,
+      nextManualAction: ready
+        ? 'Review this dry-run lifecycle, then separately approve any foreground worker execution plan. No hidden daemon, watcher, automatic polling, source write, git write, platform API, or automatic dispatch is authorized.'
+        : 'Resolve the foreground worker blockers before requesting any execution approval.',
+    }),
+    forbidden_actions: ['hidden background worker', 'watcher', 'automatic polling', 'cross-process preemption', 'automatic cleanup', 'automatic dispatch', 'platform API', 'source coupling', 'git coupling'],
+    boundary_assertions: {
+      writes: false,
+      worker_started: false,
+      hidden_background_worker: false,
+      scheduler: false,
+      daemon: false,
+      watcher: false,
+      automatic_polling: false,
+      source_write: false,
+      git: false,
+      git_write: false,
+      platform_api: false,
+      subagent: false,
+      mcp: false,
+      business_source_write: false,
+    },
+  };
+  const digest = typeof digestObject === 'function' ? digestObject(core) : digestLeasedForegroundWorkerPlan(core);
+  return {
+    mode: 'leased-foreground-worker-plan',
+    ok: true,
+    leased_foreground_worker_plan: { ...core, foreground_worker_plan_digest: digest },
+    safety: {
+      stage,
+      writes: false,
+      command_execution: false,
+      worker_started: false,
+      foreground_only: true,
+      background: false,
+      daemon: false,
+      scheduler: false,
+      watcher: false,
+      automatic_polling: false,
+      source_write: false,
+      git: false,
+      git_write: false,
+      platform_api: false,
+      subagent: false,
+      mcp: false,
+      business_source_write: false,
+    },
+    quality: blocked,
+    action: 'leased foreground worker plan was computed as a dry-run from one local approved item. It did not start a worker, write heartbeat files, acquire real leases, poll, dispatch, call platform APIs, mutate source, use git, or run in the background.',
+  };
+}
+
+export function printLeasedForegroundWorkerPlan(envelope, { printList } = {}) {
+  const plan = envelope.leased_foreground_worker_plan;
+  console.log('Vibecoding Runtime Leased Foreground Worker Plan');
+  console.log(`Stage: ${plan.stage}; Status: ${plan.status}`);
+  console.log(`Item: ${plan.approved_item.item_id}; max_iterations=${plan.controls.max_iterations}; max_item_count=${plan.controls.max_item_count}`);
+  console.log(`Lifecycle: ${plan.lifecycle.map((item) => item.step).join(' -> ')}`);
+  console.log('Boundary: foreground_only=true; worker_started=false; background=false; daemon=false; scheduler=false; watcher=false; source_write=false; git=false; platform_api=false');
+  if (plan.blocked_reasons.length > 0 && printList) printList('Blocked reasons', plan.blocked_reasons);
+  console.log(`Foreground worker plan digest: ${plan.foreground_worker_plan_digest}`);
+  console.log(`Action: ${envelope.action}`);
+}
+
+export function digestLeasedForegroundWorkerPlan(value) {
+  return crypto.createHash('sha256').update(stableStringify(value)).digest('hex');
+}
+
+function stableStringify(value) {
+  if (Array.isArray(value)) return `[${value.map((item) => stableStringify(item)).join(',')}]`;
+  if (value && typeof value === 'object') return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${stableStringify(value[key])}`).join(',')}}`;
+  return JSON.stringify(value);
+}

package/tools/vibe-runtime/runtime-git-diff-read-model.mjs

@@ -0,0 +1,322 @@
+import crypto from 'node:crypto';
+
+const gitDiffReadStage = 'P3';
+const gitDiffReadKind = 'git-diff-read-evidence';
+const allowedGitDiffArgv = new Set([
+  'git diff --name-status',
+  'git diff --stat',
+  'git diff --numstat',
+  'git diff --cached --name-status',
+  'git diff --cached --stat',
+  'git diff --cached --numstat',
+]);
+
+export function runtimeGitDiffReadEnvelope({
+  commandResults = [],
+  planActionManifest = {},
+  registry = {},
+  registryDigest = '',
+} = {}) {
+  const boundaryAssertions = runtimeGitDiffReadBoundaryAssertions();
+  const changedEntries = parseChangedEntries(commandResults);
+  const changedFiles = changedEntries.map((entry) => entry.path);
+  const plannedFiles = plannedFilesFor(planActionManifest);
+  const changedSet = new Set(changedFiles);
+  const plannedSet = new Set(plannedFiles);
+  const missingFiles = plannedFiles.filter((file) => !changedSet.has(file));
+  const unexpectedFiles = changedFiles.filter((file) => !plannedSet.has(file));
+  const taskCoverage = taskCoverageFor(planActionManifest, changedEntries);
+  const commandFindings = commandResults.flatMap(commandFindingFor);
+  const blockedReasons = [
+    ...commandFindings.map((finding) => finding.reason),
+    ...missingFiles.map((file) => `missing planned changed file: ${file}`),
+    ...unexpectedFiles.map((file) => `unexpected changed file outside plan manifest: ${file}`),
+  ];
+  const evidence = {
+    artifact_kind: 'diff-coverage-evidence',
+    stage: gitDiffReadStage,
+    evidence_kind: gitDiffReadKind,
+    planned_files: plannedFiles,
+    changed_files: changedFiles,
+    unexpected_files: unexpectedFiles,
+    missing_files: missingFiles,
+    task_coverage: taskCoverage,
+    runtime_read_git_diff: true,
+    git_read: true,
+    git_write: false,
+    worktree_write: false,
+    command_execution: false,
+    test_execution: false,
+    git: false,
+    commit: false,
+    push: false,
+    pr: false,
+    merge: false,
+    tag: false,
+    history_rewrite: false,
+    boundary_assertions: boundaryAssertions,
+  };
+  const read = {
+    version: 1,
+    stage: gitDiffReadStage,
+    read_kind: gitDiffReadKind,
+    source_bindings: gitDiffReadSourceBindings({ planActionManifest, registry, registryDigest }),
+    contract_sync_markers: ['runtime-cli-usage', 'tools/vibe-release-check'],
+    git_diff_read: gitDiffReadSummary({ commandResults, changedFiles, plannedFiles, missingFiles, unexpectedFiles }),
+    commands: commandResults.map(commandSummary),
+    diff_coverage_evidence: evidence,
+    safety_findings: commandFindings,
+    blocked_reasons: blockedReasons,
+    allowed_followup: [
+      'manual review of generated diff coverage evidence',
+      'completion evidence bundle consumption through --from-diff-coverage',
+      'manual scope reconciliation before commit readiness',
+    ],
+    forbidden_actions: [
+      'git add, git commit, git checkout, git reset, tag, PR, or history rewrite',
+      'worktree writes, source edits, formatting, repair, test execution, or code generation',
+      'sidecar or state-directory write',
+      'platform API, external network, model, MCP, background worker, or delegated-agent invocation',
+    ],
+    boundary_assertions: boundaryAssertions,
+    writes: false,
+    state_directory_created: false,
+    local_only: true,
+    deterministic: true,
+  };
+  const invariants = runtimeGitDiffReadInvariants(read);
+  return {
+    ...read,
+    git_diff_read_invariants: invariants,
+    diff_read_digest: digestGitDiffRead(runtimeGitDiffReadDigestPayload({ ...read, git_diff_read_invariants: invariants })),
+    manual_action: invariants.pass
+      ? 'Git diff read evidence is ready for manual review or completion evidence binding. It did not authorize git write or worktree mutation.'
+      : 'Resolve the listed diff read blockers before using this evidence for closeout.',
+  };
+}
+
+function gitDiffReadSourceBindings({ planActionManifest, registry, registryDigest }) {
+  return {
+    plan_action_manifest_stage: planActionManifest.stage || '',
+    plan_action_manifest_digest: planActionManifest.plan_action_manifest_digest || '',
+    registry_stage: registry.registry_stage || '',
+    registry_kind: registry.registry_kind || '',
+    registry_version: registry.registry_version || 0,
+    registry_digest: registryDigest,
+  };
+}
+
+function gitDiffReadSummary({ commandResults, changedFiles, plannedFiles, missingFiles, unexpectedFiles }) {
+  return {
+    command_count: commandResults.length,
+    allowed_command_count: commandResults.filter((result) => allowedGitDiffArgv.has(commandKey(result.argv))).length,
+    failed_command_count: commandResults.filter((result) => result.exit_code !== 0).length,
+    changed_file_count: changedFiles.length,
+    planned_file_count: plannedFiles.length,
+    missing_file_count: missingFiles.length,
+    unexpected_file_count: unexpectedFiles.length,
+    git_read: true,
+    git_write: false,
+    worktree_write: false,
+    execution_authorized: false,
+  };
+}
+
+export function runtimeGitDiffReadInvariants(envelope) {
+  const commands = Array.isArray(envelope.commands) ? envelope.commands : [];
+  const evidence = envelope.diff_coverage_evidence || {};
+  const findings = [
+    ...(commands.length > 0 ? [] : ['git diff read requires at least one command result']),
+    ...commands.filter((command) => !allowedGitDiffArgv.has(command.command)).map((command) => `git diff command is not allowed: ${command.command}`),
+    ...commands.filter((command) => command.exit_code !== 0).map((command) => `git diff command failed: ${command.command}`),
+    ...(evidence.runtime_read_git_diff === true ? [] : ['diff coverage evidence must mark runtime_read_git_diff=true']),
+    ...(evidence.git_read === true ? [] : ['diff coverage evidence must mark git_read=true']),
+    ...(evidence.git_write === false ? [] : ['diff coverage evidence must mark git_write=false']),
+    ...(evidence.worktree_write === false ? [] : ['diff coverage evidence must mark worktree_write=false']),
+    ...(evidence.git === false ? [] : ['diff coverage evidence must keep git=false for write boundary compatibility']),
+    ...(evidence.commit === false && evidence.push === false && evidence.pr === false && evidence.merge === false ? [] : ['git write followups must remain false']),
+    ...(Array.isArray(evidence.planned_files) && evidence.planned_files.length > 0 ? [] : ['planned_files must not be empty']),
+    ...(Array.isArray(evidence.changed_files) && evidence.changed_files.length > 0 ? [] : ['changed_files must not be empty']),
+    ...((evidence.missing_files || []).map((file) => `blocked: missing planned changed file: ${file}`)),
+    ...((evidence.unexpected_files || []).map((file) => `blocked: unexpected changed file outside plan manifest: ${file}`)),
+  ];
+  return {
+    pass: findings.length === 0,
+    checked: [
+      'fixed_git_diff_allowlist',
+      'git_write_false',
+      'worktree_write_false',
+      'legacy_diff_coverage_shape',
+      'plan_file_coverage',
+      'no_state_or_artifact_write',
+    ],
+    findings,
+  };
+}
+
+export function runtimeGitDiffReadDigestPayload(envelope) {
+  return {
+    stage: envelope.stage,
+    read_kind: envelope.read_kind,
+    source_bindings: envelope.source_bindings,
+    contract_sync_markers: envelope.contract_sync_markers,
+    git_diff_read: envelope.git_diff_read,
+    commands: envelope.commands,
+    diff_coverage_evidence: envelope.diff_coverage_evidence,
+    safety_findings: envelope.safety_findings,
+    blocked_reasons: envelope.blocked_reasons,
+    allowed_followup: envelope.allowed_followup,
+    forbidden_actions: envelope.forbidden_actions,
+    boundary_assertions: envelope.boundary_assertions,
+    git_diff_read_invariants: envelope.git_diff_read_invariants,
+  };
+}
+
+export function digestGitDiffRead(value) {
+  return crypto.createHash('sha256').update(stableStringify(value)).digest('hex');
+}
+
+export function runtimeGitDiffReadBoundaryAssertions() {
+  return {
+    diff_read_artifact: false,
+    diff_coverage_artifact: false,
+    sidecar_write: false,
+    state_directory_created: false,
+    git_read: true,
+    git_write: false,
+    worktree_write: false,
+    commit: false,
+    push: false,
+    pr: false,
+    merge: false,
+    tag: false,
+    history_rewrite: false,
+    test_execution: false,
+    repair_execution: false,
+    formatting_execution: false,
+    code_generation: false,
+    platform_api: false,
+    external_network: false,
+    model_invocation: false,
+    mcp: false,
+    business_source_write: false,
+  };
+}
+
+function commandSummary(result) {
+  return {
+    id: result.id || slugify(commandKey(result.argv)),
+    command: commandKey(result.argv),
+    argv: Array.isArray(result.argv) ? result.argv : [],
+    exit_code: Number.isInteger(result.exit_code) ? result.exit_code : 1,
+    stdout_digest: digestText(result.stdout || ''),
+    stderr_digest: digestText(result.stderr || ''),
+    stdout_line_count: lineCount(result.stdout || ''),
+    stderr_line_count: lineCount(result.stderr || ''),
+  };
+}
+
+function commandFindingFor(result) {
+  const command = commandKey(result.argv);
+  const findings = [];
+  if (!allowedGitDiffArgv.has(command)) findings.push({ id: `git-diff-read-command-${slugify(command)}`, severity: 'blocker', reason: `git diff command is not allowed: ${command}` });
+  if (result.exit_code !== 0) findings.push({ id: `git-diff-read-failed-${slugify(command)}`, severity: 'blocker', reason: `git diff command failed: ${command}` });
+  return findings;
+}
+
+function parseChangedEntries(commandResults) {
+  const entries = commandResults
+    .filter((result) => commandKey(result.argv).includes('--name-status'))
+    .flatMap((result) => parseNameStatus(result.stdout || '', result.id || 'git-diff'));
+  const byPath = new Map();
+  for (const entry of entries) {
+    if (!entry.path) continue;
+    byPath.set(entry.path, byPath.has(entry.path) ? { ...byPath.get(entry.path), sources: [...byPath.get(entry.path).sources, ...entry.sources] } : entry);
+  }
+  return [...byPath.values()].sort((left, right) => left.path.localeCompare(right.path));
+}
+
+function parseNameStatus(text, source) {
+  return String(text || '').split(/\r?\n/).map((line) => line.trim()).filter(Boolean).flatMap((line) => {
+    const parts = line.split(/\t+/).map((part) => part.trim()).filter(Boolean);
+    if (parts.length < 2) return [];
+    const status = parts[0];
+    const path = normalizeFilePath(status.startsWith('R') || status.startsWith('C') ? parts[2] || parts[1] : parts[1]);
+    return path ? [{ path, operation: operationForStatus(status), sources: [source] }] : [];
+  });
+}
+
+function plannedFilesFor(planActionManifest) {
+  const actionFiles = (planActionManifest.action_items || []).flatMap((item) => item.target_files || []);
+  const docsFiles = (planActionManifest.docs_expectations || []).flatMap((item) => extractPaths(item.expectation || item.title || item.file || ''));
+  const codeFiles = (planActionManifest.code_expectations || []).flatMap((item) => extractPaths(item.expectation || item.title || item.file || ''));
+  return unique([...actionFiles, ...docsFiles, ...codeFiles].map(normalizeFilePath).filter(Boolean));
+}
+
+function taskCoverageFor(planActionManifest, changedEntries) {
+  const byPath = new Map(changedEntries.map((entry) => [entry.path, entry]));
+  return (planActionManifest.action_items || []).map((item) => {
+    const targetFiles = unique((item.target_files || []).map(normalizeFilePath).filter(Boolean));
+    const changed = targetFiles.filter((file) => byPath.has(file)).map((file) => {
+      const entry = byPath.get(file);
+      return {
+        path: file,
+        operation: entry.operation,
+        digest: digestText(`${file}:${entry.operation}:${entry.sources.join('|')}`),
+      };
+    });
+    return {
+      task_ref: item.id || item.title || 'plan-action-item',
+      status: changed.length > 0 ? 'covered' : 'not_started',
+      changed_files: changed,
+      rationale: changed.length > 0 ? 'planned file changed in read-only git diff output' : 'planned file not present in read-only git diff output',
+    };
+  });
+}
+
+function operationForStatus(status) {
+  const marker = String(status || '').charAt(0).toUpperCase();
+  if (marker === 'A' || marker === 'C') return 'add';
+  if (marker === 'D') return 'delete';
+  return 'modify';
+}
+
+function commandKey(argv) {
+  return (Array.isArray(argv) ? argv : []).join(' ').replace(/\s+/g, ' ').trim();
+}
+
+function normalizeFilePath(value) {
+  const raw = String(value || '').trim().replace(/^"|"$/g, '');
+  if (!raw || raw === '/dev/null') return '';
+  return raw.replace(/^\.\//, '').replace(/^[ab]\//, '').replace(/\\/g, '/').replace(/\s+$/, '');
+}
+
+function extractPaths(text) {
+  const backtickPathMatches = (String(text || '').match(/`[^`]+\.(?:mjs|js|ts|tsx|json|md|yml|yaml|py|go|rs|java|css|scss|html)`/g) || []).map((item) => item.slice(1, -1));
+  const barePathMatches = String(text || '').match(/\b(?:[\w.-]+[\\/])+[\w.-]+\.(?:mjs|js|ts|tsx|json|md|yml|yaml|py|go|rs|java|css|scss|html)\b/g) || [];
+  return unique([...backtickPathMatches, ...barePathMatches].map(normalizeFilePath).filter(Boolean));
+}
+
+function unique(values) {
+  return [...new Set(values)].sort();
+}
+
+function digestText(value) {
+  return crypto.createHash('sha256').update(String(value || '')).digest('hex');
+}
+
+function lineCount(value) {
+  const text = String(value || '');
+  return text.trim() ? text.replace(/\r\n/g, '\n').replace(/\r/g, '\n').split('\n').length : 0;
+}
+
+function slugify(value) {
+  const slug = String(value || '').toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '').slice(0, 48);
+  return slug || 'command';
+}
+
+function stableStringify(value) {
+  if (Array.isArray(value)) return `[${value.map((item) => stableStringify(item)).join(',')}]`;
+  if (value && typeof value === 'object') return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${stableStringify(value[key])}`).join(',')}}`;
+  return JSON.stringify(value);
+}