@jtf19/vibecoding-kit 0.1.0

package/tools/vibe-runtime/runtime-next-action-evidence-prompts.mjs

@@ -0,0 +1,327 @@
+import crypto from 'node:crypto';
+
+const promptsStage = 'Stage 143';
+const promptsKind = 'next-action-evidence-prompts';
+const consoleStage = 'Stage 127';
+const dashboardStage = 'Stage 132';
+const upgradesStage = 'Stage 139';
+
+export function runtimeNextActionEvidencePrompts({ console: consoleInput = {}, dashboard = {}, upgrades = {}, source = {} } = {}) {
+  const panel = unwrapConsole(consoleInput);
+  const board = unwrapDashboard(dashboard);
+  const prioritizer = unwrapUpgrades(upgrades);
+  const selectedAction = selectedNextAction(panel, board, prioritizer);
+  const promptCards = evidencePromptCards(panel, board, prioritizer, selectedAction);
+  const core = {
+    version: 1,
+    stage: promptsStage,
+    prompts_kind: promptsKind,
+    source_bindings: sourceBindingSummary(source, panel, board, prioritizer),
+    input_summary: inputSummary(panel, board, prioritizer, selectedAction, promptCards),
+    selected_next_action: selectedAction,
+    evidence_prompt_cards: promptCards,
+    copy_ready_validation_notes: copyReadyValidationNotes(promptCards, selectedAction),
+    blocked_until: blockedUntil(promptCards, board, prioritizer),
+    boundary_assertions: runtimeNextActionEvidencePromptsBoundaryAssertions(),
+    writes: false,
+    state_directory_created: false,
+    local_only: true,
+    deterministic: true,
+  };
+  const invariants = runtimeNextActionEvidencePromptsInvariants(core);
+  const prompts = {
+    ...core,
+    ok: invariants.pass,
+    prompts_invariants: invariants,
+  };
+  return {
+    ...prompts,
+    prompts_digest: digestNextActionEvidencePrompts(runtimeNextActionEvidencePromptsDigestPayload(prompts)),
+  };
+}
+
+export function runtimeNextActionEvidencePromptsDigestPayload(prompts) {
+  return {
+    stage: prompts.stage,
+    prompts_kind: prompts.prompts_kind,
+    source_bindings: prompts.source_bindings,
+    input_summary: prompts.input_summary,
+    selected_next_action: prompts.selected_next_action,
+    evidence_prompt_cards: prompts.evidence_prompt_cards,
+    copy_ready_validation_notes: prompts.copy_ready_validation_notes,
+    blocked_until: prompts.blocked_until,
+    boundary_assertions: prompts.boundary_assertions,
+    prompts_invariants: prompts.prompts_invariants,
+  };
+}
+
+export function runtimeNextActionEvidencePromptsBoundaryAssertions() {
+  return {
+    next_action_evidence_prompts_artifact: false,
+    evidence_prompt_artifact: false,
+    console_artifact: false,
+    dashboard_artifact: false,
+    upgrade_artifact: false,
+    source_write: false,
+    sidecar_write: false,
+    state_directory_created: false,
+    evidence_write: false,
+    validation_note_write: false,
+    dashboard_write: false,
+    command_execution: false,
+    check_execution: false,
+    smoke_execution: false,
+    test_execution: false,
+    verification_execution: false,
+    workflow_execution: false,
+    skill_execution: false,
+    runtime_action: false,
+    auto_execution: false,
+    repair_execution: false,
+    prompt_mutation: false,
+    template_mutation: false,
+    skill_mutation: false,
+    hook_execution: false,
+    adapter_execution: false,
+    dynamic_tool_execution: false,
+    platform_api: false,
+    external_network: false,
+    model_invocation: false,
+    subagent: false,
+    mcp: false,
+    daemon: false,
+    git: false,
+    git_write: false,
+    git_add: false,
+    commit: false,
+    pr: false,
+    push: false,
+    merge: false,
+    tag: false,
+    worktree: false,
+    business_source_write: false,
+  };
+}
+
+export function runtimeNextActionEvidencePromptsInvariants(prompts) {
+  const unsafeBoundaries = Object.entries(prompts.boundary_assertions || {})
+    .filter(([, value]) => value !== false)
+    .map(([key]) => key);
+  const missingForbidden = Object.keys(runtimeNextActionEvidencePromptsBoundaryAssertions())
+    .filter((key) => prompts.boundary_assertions?.[key] !== false);
+  const cards = Array.isArray(prompts.evidence_prompt_cards) ? prompts.evidence_prompt_cards : [];
+  const duplicateCards = cards.map((card) => card.id).filter((id, index, values) => values.indexOf(id) !== index);
+  const executableNotes = (prompts.copy_ready_validation_notes || [])
+    .filter((note) => /(^|\s)(npm\s+test|node\s+.*--confirm|git\s+(commit|push|merge|tag)|gh\s+pr|--run|--once|--auto-run)(\s|$)/i.test(note.note || ''))
+    .map((note) => note.id);
+  const findings = [
+    ...(prompts.stage === promptsStage ? [] : [`stage must be ${promptsStage}`]),
+    ...(prompts.prompts_kind === promptsKind ? [] : [`prompts_kind must be ${promptsKind}`]),
+    ...(prompts.source_bindings?.console_file ? [] : ['console file binding is required']),
+    ...(prompts.source_bindings?.console_digest ? [] : ['console digest binding is required']),
+    ...(prompts.source_bindings?.dashboard_file ? [] : ['dashboard file binding is required']),
+    ...(prompts.source_bindings?.dashboard_digest ? [] : ['dashboard digest binding is required']),
+    ...(prompts.source_bindings?.upgrades_file ? [] : ['upgrades file binding is required']),
+    ...(prompts.source_bindings?.upgrades_digest ? [] : ['upgrades digest binding is required']),
+    ...(prompts.input_summary?.console_stage === consoleStage ? [] : [`console input must be ${consoleStage} evidence`]),
+    ...(prompts.input_summary?.dashboard_stage === dashboardStage ? [] : [`dashboard input must be ${dashboardStage} evidence`]),
+    ...(prompts.input_summary?.upgrades_stage === upgradesStage ? [] : [`upgrades input must be ${upgradesStage} evidence`]),
+    ...(prompts.selected_next_action?.id ? [] : ['selected_next_action.id is required']),
+    ...(cards.length >= 3 ? [] : ['evidence_prompt_cards must include at least console, dashboard, and upgrade evidence cards']),
+    ...(Array.isArray(prompts.copy_ready_validation_notes) && prompts.copy_ready_validation_notes.length > 0 ? [] : ['copy_ready_validation_notes must be non-empty']),
+    ...(Array.isArray(prompts.blocked_until) && prompts.blocked_until.length > 0 ? [] : ['blocked_until must be non-empty']),
+    ...duplicateCards.map((id) => `duplicate evidence prompt card: ${id}`),
+    ...unsafeBoundaries.map((key) => `boundary assertion must remain false: ${key}`),
+    ...missingForbidden.map((key) => `forbidden boundary missing or not false: ${key}`),
+    ...executableNotes.map((id) => `copy-ready validation note must remain non-executing: ${id}`),
+  ];
+  return {
+    pass: findings.length === 0,
+    checked: ['source_bindings', 'stage_127_console', 'stage_132_dashboard', 'stage_139_upgrades', 'selected_next_action', 'evidence_prompt_cards', 'copy_ready_validation_notes', 'blocked_until', 'read_only_boundary_assertions'],
+    findings,
+  };
+}
+
+export function digestNextActionEvidencePrompts(value) {
+  return crypto.createHash('sha256').update(stableStringify(value)).digest('hex');
+}
+
+function unwrapConsole(input) {
+  return objectValue(input.next_action_console || input['console'] || input);
+}
+
+function unwrapDashboard(input) {
+  return objectValue(input.experience_regression_dashboard || input.dashboard || input);
+}
+
+function unwrapUpgrades(input) {
+  return objectValue(input.experience_upgrade_prioritizer || input.upgrade_prioritizer || input.upgrades || input);
+}
+
+function sourceBindingSummary(source, panel, board, prioritizer) {
+  return {
+    console_file: stringValue(source.console_file),
+    console_digest: stringValue(source.console_digest),
+    dashboard_file: stringValue(source.dashboard_file),
+    dashboard_digest: stringValue(source.dashboard_digest),
+    upgrades_file: stringValue(source.upgrades_file),
+    upgrades_digest: stringValue(source.upgrades_digest),
+    console_stage: stringValue(panel.stage),
+    dashboard_stage: stringValue(board.stage),
+    upgrades_stage: stringValue(prioritizer.stage),
+    console_artifact_digest: stringValue(panel.console_digest),
+    dashboard_artifact_digest: stringValue(board.dashboard_digest),
+    upgrades_artifact_digest: stringValue(prioritizer.upgrade_digest),
+  };
+}
+
+function inputSummary(panel, board, prioritizer, selectedAction, cards) {
+  return {
+    console_stage: stringValue(panel.stage),
+    console_kind: stringValue(panel.console_kind),
+    console_next_action_id: stringValue(panel.recommended_next_action?.id),
+    console_target_stage: stringValue(panel.recommended_next_action?.target_stage),
+    dashboard_stage: stringValue(board.stage),
+    dashboard_kind: stringValue(board.dashboard_kind),
+    dashboard_score: numberValue(board.experience_scorecard?.overall_experience_score),
+    dashboard_next_bet_id: stringValue(board.next_bet?.id),
+    upgrades_stage: stringValue(prioritizer.stage),
+    upgrades_kind: stringValue(prioritizer.prioritizer_kind),
+    upgrade_next_bet_id: stringValue(prioritizer.next_upgrade_bet?.candidate_id || prioritizer.next_upgrade_bet?.id),
+    selected_action_id: selectedAction.id,
+    evidence_prompt_count: cards.length,
+  };
+}
+
+function selectedNextAction(panel, board, prioritizer) {
+  const consoleAction = objectValue(panel.recommended_next_action);
+  const dashboardBet = objectValue(board.next_bet);
+  const upgradeBet = objectValue(prioritizer.next_upgrade_bet);
+  const recommendedOrder = listValue(prioritizer.recommended_stage_order);
+  const upgradeCandidate = stringValue(upgradeBet.candidate_id || upgradeBet.id || recommendedOrder[0]?.candidate_id);
+  const selectedId = stringValue(consoleAction.id || dashboardBet.id || upgradeCandidate || 'collect-local-evidence');
+  return {
+    id: selectedId,
+    target_stage: stringValue(consoleAction.target_stage || dashboardBet.target_stage || upgradeBet.target_stage || recommendedOrder[0]?.stage || 'Stage 143'),
+    action: stringValue(consoleAction.action || dashboardBet.action || upgradeBet.action || 'Collect the minimum local evidence needed before claiming the next action is complete.'),
+    upgrade_candidate: upgradeCandidate || 'unknown',
+    why: stringValue(board.next_bet?.why || upgradeBet.why || panel.why_now || 'Evidence prompts make the next step verifiable before execution.'),
+  };
+}
+
+function evidencePromptCards(panel, board, prioritizer, selectedAction) {
+  return [
+    consoleEvidenceCard(panel, selectedAction),
+    dashboardEvidenceCard(board, selectedAction),
+    upgradeEvidenceCard(prioritizer, selectedAction),
+    ...blockerCards(board),
+  ];
+}
+
+function consoleEvidenceCard(panel, selectedAction) {
+  const needed = listValue(panel.evidence_needed_next);
+  return {
+    id: 'stage127-console-evidence',
+    title: 'Bind the one-screen next-action evidence requirement',
+    source_stage: stringValue(panel.stage || consoleStage),
+    severity: needed.length > 0 ? 'high' : 'medium',
+    prompt: needed.length > 0
+      ? `Capture local evidence for: ${needed.map((item) => stringValue(item.id || item.reason)).filter(Boolean).join(', ')}.`
+      : `Capture the minimum local evidence proving ${selectedAction.id} is ready to continue.`,
+    required_fields: ['evidence_kind', 'source_digest', 'observed_result', 'remaining_blockers'],
+    acceptance_note: 'A human-readable local evidence JSON exists and references the Stage 127 console digest; this command only describes the requirement.',
+  };
+}
+
+function dashboardEvidenceCard(board, selectedAction) {
+  const blockers = listValue(board.regression_blockers);
+  return {
+    id: 'stage132-dashboard-blockers',
+    title: 'Resolve or explicitly carry dashboard regression blockers',
+    source_stage: stringValue(board.stage || dashboardStage),
+    severity: blockers.some((item) => stringValue(item.severity) === 'high') ? 'high' : 'medium',
+    prompt: blockers.length > 0
+      ? `For ${selectedAction.id}, record whether these blockers are resolved or intentionally carried: ${blockers.map((item) => stringValue(item.id)).filter(Boolean).join(', ')}.`
+      : 'Record that Stage 132 has no blocking regression finding for the selected next action.',
+    required_fields: ['dashboard_digest', 'blocker_id', 'resolution_status', 'evidence_digest'],
+    acceptance_note: 'The next action is not complete until Stage 132 regression blockers are resolved or deliberately carried in local evidence.',
+  };
+}
+
+function upgradeEvidenceCard(prioritizer, selectedAction) {
+  const order = listValue(prioritizer.recommended_stage_order);
+  const bet = objectValue(prioritizer.next_upgrade_bet);
+  return {
+    id: 'stage139-upgrade-priority',
+    title: 'Bind the selected next action to the prioritized upgrade bet',
+    source_stage: stringValue(prioritizer.stage || upgradesStage),
+    severity: selectedAction.upgrade_candidate && selectedAction.upgrade_candidate !== 'unknown' ? 'medium' : 'high',
+    prompt: `Show why ${selectedAction.id} matches the Stage 139 priority ${selectedAction.upgrade_candidate || stringValue(order[0]?.candidate_id || bet.candidate_id || 'unknown')}.`,
+    required_fields: ['upgrade_digest', 'candidate_id', 'priority_score', 'why_now'],
+    acceptance_note: 'The selected next action remains advisory unless it is tied back to a local Stage 139 upgrade candidate.',
+  };
+}
+
+function blockerCards(board) {
+  return listValue(board.regression_blockers)
+    .filter((blocker) => stringValue(blocker.severity) === 'high')
+    .slice(0, 3)
+    .map((blocker) => ({
+      id: `blocker-${safeId(blocker.id)}`,
+      title: `High-severity blocker: ${stringValue(blocker.id)}`,
+      source_stage: stringValue(board.stage || dashboardStage),
+      severity: 'high',
+      prompt: stringValue(blocker.recommendation || blocker.reason || 'Record the local evidence that resolves or carries this blocker.'),
+      required_fields: ['blocker_id', 'local_resolution_evidence', 'remaining_risk'],
+      acceptance_note: 'Do not claim completion while this blocker is unaddressed.',
+    }));
+}
+
+function copyReadyValidationNotes(cards, selectedAction) {
+  return cards.slice(0, 5).map((card) => ({
+    id: `note-${card.id}`,
+    note: `Before completing ${selectedAction.id}, collect local JSON evidence with fields: ${card.required_fields.join(', ')}. This is a note only; no command is executed.`,
+  }));
+}
+
+function blockedUntil(cards, board, prioritizer) {
+  const highCards = cards.filter((card) => card.severity === 'high');
+  const reasons = highCards.length > 0 ? highCards : cards.slice(0, 2);
+  return reasons.map((card) => ({
+    id: card.id,
+    condition: card.acceptance_note,
+    source: card.source_stage,
+  })).concat([
+    {
+      id: 'no-execution-boundary',
+      condition: 'No check/test/workflow/git/subagent action is authorized by this prompt pack; execution remains a separate human-controlled step.',
+      source: `${stringValue(board.stage || dashboardStage)} + ${stringValue(prioritizer.stage || upgradesStage)}`,
+    },
+  ]);
+}
+
+function objectValue(value) {
+  return value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+}
+
+function listValue(value) {
+  return Array.isArray(value) ? value : [];
+}
+
+function stringValue(value) {
+  return typeof value === 'string' ? value : value == null ? '' : String(value);
+}
+
+function numberValue(value) {
+  return Number.isFinite(value) ? value : 0;
+}
+
+function safeId(value) {
+  return stringValue(value).toLowerCase().replace(/[^a-z0-9._-]+/g, '-').replace(/^-+|-+$/g, '') || 'unknown';
+}
+
+function stableStringify(value) {
+  if (Array.isArray(value)) return `[${value.map(stableStringify).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-observability-command.mjs

@@ -0,0 +1,96 @@
+import { createRuntimeObservabilityReadinessModel } from './runtime-observability-readiness-model.mjs';
+import { createRuntimeObservabilityPresentation } from './runtime-observability-presentation.mjs';
+import { buildReadinessGateSplitEnvelope } from './runtime-readiness-gate-split.mjs';
+
+export function createRuntimeObservabilityCommand(deps) {
+  const {
+    path,
+    jsonSchemaVersion,
+    ensureRoot,
+    writeJsonEnvelope,
+    writeStateArtifact,
+    validateCommonArtifactSafety,
+    observabilitySnapshotPath,
+  } = deps;
+
+  const readinessModel = createRuntimeObservabilityReadinessModel(deps);
+  const {
+    readinessDimension,
+    verificationSummaryFromFiles,
+    loopHealthSummary,
+    replyHealthSummary,
+    traceHealthSummary,
+    readinessScoreFromFailures,
+    readinessEnvelope,
+  } = readinessModel;
+  const { printObservability, printReadinessGateSplit } = createRuntimeObservabilityPresentation(deps);
+
+  function validateObservabilityArtifact(observability) {
+    const failures = [];
+    if (observability.schema_version !== jsonSchemaVersion) failures.push('schema_version must be 1');
+    if (observability.command !== 'observability') failures.push('command must be observability');
+    if (observability.mode !== 'observability-readiness-score') failures.push('mode must be observability-readiness-score');
+    if (typeof observability.readiness?.overall_score !== 'number') failures.push('readiness.overall_score must be a number');
+    if (!Array.isArray(observability.readiness?.dimensions)) failures.push('readiness.dimensions must be an array');
+    if (observability.readiness?.deterministic !== true) failures.push('readiness.deterministic must be true');
+    if (!['Stage 20', 'Stage 30'].includes(observability.safety?.stage)) failures.push('safety.stage must be Stage 20 or Stage 30');
+    else failures.push(...validateCommonArtifactSafety(observability.safety, observability.safety.stage));
+    if (observability.safety?.observability_snapshot !== true) failures.push('safety.observability_snapshot must be true');
+    return { ok: failures.length === 0, failures };
+  }
+
+  function writeObservabilitySnapshot(root, envelope) {
+    const file = observabilitySnapshotPath(root);
+    const payload = { schema_version: jsonSchemaVersion, command: 'observability', ...envelope };
+    const verification = validateObservabilityArtifact(payload);
+    if (!verification.ok) throw new Error(`observability verification failed: ${verification.failures.join('; ')}`);
+    return writeStateArtifact(path.dirname(file), path.basename(file), payload);
+  }
+
+  function runReadinessGateSplit(options) {
+    if (options.confirm || options.write || options.dryRun || options.scan || options.fromDispatch || options.actor || options.approval || options.run || options.autoRun || options.preflight) throw new Error('readiness --gates is read-only and does not accept execution, dispatch, confirm, dry-run, run, scan, preflight, or write flags');
+    if (options.readinessScore) throw new Error('readiness --gates is separate from readiness --score; choose exactly one readiness mode');
+    ensureRoot(options.root);
+    const envelope = buildReadinessGateSplitEnvelope(options.root, { evidenceFile: options.fromFile || '' });
+    if (options.json) writeJsonEnvelope('readiness', envelope);
+    else printReadinessGateSplit(envelope);
+  }
+
+  function runObservability(options) {
+    if (options.command === 'readiness' && options.readinessGates) return runReadinessGateSplit(options);
+    if (options.write || options.dryRun || options.scan || options.fromDispatch || options.actor || options.approval || options.run || options.autoRun) throw new Error(`${options.command} supports summary/score only`);
+    const wantsScore = options.command === 'readiness' ? options.readinessScore : options.observabilitySummary;
+    if (!wantsScore) throw new Error(`${options.command} requires ${options.command === 'readiness' ? '--score' : '--summary'}`);
+    ensureRoot(options.root);
+    const envelope = readinessEnvelope(options.root, { persist: options.confirm });
+    if (options.confirm) {
+      const file = writeObservabilitySnapshot(options.root, envelope);
+      if (options.json) {
+        writeJsonEnvelope('observability', { ...envelope, observability_file: path.basename(file) });
+        return;
+      }
+      printObservability(envelope, file);
+      return;
+    }
+    if (options.json) {
+      writeJsonEnvelope('observability', envelope);
+      return;
+    }
+    printObservability(envelope);
+  }
+
+  return {
+    readinessDimension,
+    verificationSummaryFromFiles,
+    loopHealthSummary,
+    replyHealthSummary,
+    traceHealthSummary,
+    readinessScoreFromFailures,
+    readinessEnvelope,
+    validateObservabilityArtifact,
+    writeObservabilitySnapshot,
+    printObservability,
+    printReadinessGateSplit,
+    runObservability,
+  };
+}

package/tools/vibe-runtime/runtime-observability-presentation.mjs

@@ -0,0 +1,30 @@
+export function createRuntimeObservabilityPresentation(deps) {
+  const { path, process, printList } = deps;
+
+  function printObservability(envelope, file = '') {
+    console.log('Vibecoding Runtime Observability');
+    console.log('Mode: readiness-score');
+    console.log(`Overall score: ${envelope.readiness.overall_score}; Grade: ${envelope.readiness.grade}`);
+    console.log(`Queue: items=${envelope.observability.queue_summary.items}; ready=${envelope.observability.queue_summary.ready}; blocked=${envelope.observability.queue_summary.blocked}`);
+    console.log(`Leases: active=${envelope.observability.lease_summary.active_count}; stale=${envelope.observability.lease_summary.stale_count}; invalid=${envelope.observability.lease_summary.invalid_count}`);
+    if (file) console.log(`Observability snapshot: ${path.relative(process.cwd(), file)}`);
+    for (const dimension of envelope.readiness.dimensions) console.log(`- ${dimension.name}: ${dimension.score} (weight=${dimension.weight}) ${dimension.explanation}`);
+    if (envelope.readiness.warnings.length > 0) printList('Top blockers', envelope.readiness.warnings);
+    console.log(`Action: ${envelope.action}`);
+  }
+
+  function printReadinessGateSplit(envelope) {
+    const split = envelope.readiness_gate_split;
+    console.log('Vibecoding Runtime Readiness Gate Split');
+    console.log(`Stage: ${split.stage}; Kind: ${split.readiness_kind}`);
+    console.log(`Source evidence: ${split.source_evidence.file || 'not provided'}; provided=${split.source_evidence.provided}`);
+    for (const gate of split.gates) console.log(`- ${gate.gate}: ${gate.ready ? 'ready' : 'blocked'}; blockers=${gate.blocked_reasons.join(', ') || 'none'}; execution_authorized=false; git_authorized=false`);
+    console.log(`Ready gates: ${split.ready_gates.join(', ') || 'none'}`);
+    console.log(`Blocked gates: ${split.blocked_gates.join(', ') || 'none'}`);
+    console.log('Boundary: writes=false; readiness_gate_split_artifact=false; completion_claim=false; local_commit_authorization=false; review_request_created=false; release_candidate_created=false; command_execution=false; test_execution=false; git=false; git_write=false; commit=false; pr=false; push=false; merge=false; platform_api=false; subagent=false; business_source_write=false');
+    console.log(`Readiness gate split digest: ${split.readiness_gate_split_digest}`);
+    console.log(`Action: ${envelope.action}`);
+  }
+
+  return { printObservability, printReadinessGateSplit };
+}

package/tools/vibe-runtime/runtime-observability-readiness-model.mjs

@@ -0,0 +1,204 @@
+export function createRuntimeObservabilityReadinessModel(deps) {
+  const {
+    fs,
+    path,
+    jsonSchemaVersion,
+    workflowPath,
+    readJsonArtifact,
+    listStateFiles,
+    digestObject,
+    runtimeTracesDirectory,
+    daemonLoopsDirectory,
+    daemonHeartbeatsDirectory,
+    daemonStopFilePath,
+    listDaemonLoopFiles,
+    listReplyDraftFiles,
+    listReplyApprovalFiles,
+    listReplyOutboxFiles,
+    listReplySendRunFiles,
+    replyDraftsDirectory,
+    replyApprovalsDirectory,
+    replyOutboxDirectory,
+    replySendRunsDirectory,
+    validateReplyArtifact,
+    runtimeTraceReferences,
+    validateRuntimeTraceArtifact,
+    queueScanEnvelope,
+    leaseAuditEnvelope,
+    recoveryEnvelope,
+    retryHealthSummary,
+  } = deps;
+
+  function readinessDimension(name, score, weight, explanation, evidence = []) {
+    return { name, score, weight, explanation, evidence };
+  }
+
+  function verificationSummaryFromFiles(root, files, directory, label, verifier) {
+    const details = files.map((fileName) => {
+      try {
+        const file = path.join(directory(root), fileName);
+        const artifact = readJsonArtifact(file, label);
+        const verification = verifier(artifact, fileName, file);
+        return { file: fileName, ok: verification.ok, failures: verification.failures || [] };
+      } catch (error) {
+        return { file: fileName, ok: false, failures: [error.message] };
+      }
+    });
+    return {
+      count: details.length,
+      ok_count: details.filter((item) => item.ok).length,
+      failed_count: details.filter((item) => !item.ok).length,
+      details,
+    };
+  }
+
+  function loopHealthSummary(root) {
+    const loopFiles = listDaemonLoopFiles(root);
+    const loops = verificationSummaryFromFiles(root, loopFiles, daemonLoopsDirectory, 'Daemon loop', (artifact) => {
+      const failures = [];
+      if (artifact.schema_version !== jsonSchemaVersion) failures.push('schema_version must be 1');
+      if (artifact.command !== 'daemon') failures.push('command must be daemon');
+      if (artifact.mode !== 'daemon-loop-run') failures.push('mode must be daemon-loop-run');
+      if (artifact.safety?.stage !== 'Stage 28') failures.push('safety.stage must be Stage 28');
+      if (artifact.safety?.long_running !== false) failures.push('safety.long_running must be false');
+      if (artifact.safety?.watcher !== false) failures.push('safety.watcher must be false');
+      return { ok: failures.length === 0, failures };
+    });
+    const heartbeatFiles = listStateFiles(root, daemonHeartbeatsDirectory, '.heartbeat.json');
+    const latestHeartbeat = heartbeatFiles.length > 0 ? heartbeatFiles[heartbeatFiles.length - 1] : '';
+    const latestHeartbeatPath = latestHeartbeat ? path.join(daemonHeartbeatsDirectory(root), latestHeartbeat) : '';
+    const heartbeatAgeMs = latestHeartbeatPath && fs.existsSync(latestHeartbeatPath) ? Math.max(0, Date.now() - fs.statSync(latestHeartbeatPath).mtimeMs) : null;
+    const stopPresent = fs.existsSync(daemonStopFilePath(root));
+    const blocked = loops.details.flatMap((item) => item.ok ? [] : item.failures.map((failure) => `${item.file}: ${failure}`));
+    if (stopPresent) blocked.push('daemon stop file is present');
+    return { loops, heartbeat_count: heartbeatFiles.length, latest_heartbeat_file: latestHeartbeat, heartbeat_age_ms: heartbeatAgeMs, stop_present: stopPresent, blocked_reasons: blocked };
+  }
+
+  function replyHealthSummary(root) {
+    const groups = [
+      [listReplyDraftFiles(root), replyDraftsDirectory, 'Reply draft'],
+      [listReplyApprovalFiles(root), replyApprovalsDirectory, 'Reply approval'],
+      [listReplyOutboxFiles(root), replyOutboxDirectory, 'Reply outbox'],
+      [listReplySendRunFiles(root), replySendRunsDirectory, 'Reply send run'],
+    ];
+    const details = groups.flatMap(([files, directory, label]) => verificationSummaryFromFiles(root, files, directory, label, (artifact, fileName, file) => validateReplyArtifact(root, artifact, fileName, file)).details);
+    const sendDisabled = details.every((item) => item.ok);
+    return {
+      count: details.length,
+      ok_count: details.filter((item) => item.ok).length,
+      failed_count: details.filter((item) => !item.ok).length,
+      send_disabled: sendDisabled,
+      blocked_reasons: details.flatMap((item) => item.ok ? [] : item.failures.map((failure) => `${item.file}: ${failure}`)),
+      details,
+    };
+  }
+
+  function traceHealthSummary(root) {
+    const traceFiles = listStateFiles(root, runtimeTracesDirectory, '.runtime-trace.json');
+    const traces = verificationSummaryFromFiles(root, traceFiles, runtimeTracesDirectory, 'Runtime trace', (artifact) => validateRuntimeTraceArtifact(root, artifact));
+    const latestTraceFile = traceFiles.length > 0 ? traceFiles[traceFiles.length - 1] : '';
+    const latestTrace = latestTraceFile ? readJsonArtifact(path.join(runtimeTracesDirectory(root), latestTraceFile), 'Runtime trace') : null;
+    const latestSourceDigest = latestTrace?.runtime_trace?.source_digest || '';
+    const latestComparableDigest = latestTrace ? digestObject((latestTrace.runtime_trace?.sources || []).filter((source) => source.type !== 'observability')) : '';
+    const currentSourceDigest = digestObject(runtimeTraceReferences(root).filter((source) => source.type !== 'observability'));
+    const drift = Boolean(latestTrace && latestComparableDigest && latestComparableDigest !== currentSourceDigest);
+    const blocked = traces.details.flatMap((item) => item.ok ? [] : item.failures.map((failure) => `${item.file}: ${failure}`));
+    if (drift) blocked.push('latest runtime trace source digest drift detected');
+    return { traces, latest_trace_file: latestTraceFile, latest_source_digest: latestSourceDigest, current_source_digest: currentSourceDigest, drift, blocked_reasons: blocked };
+  }
+
+  function readinessScoreFromFailures(total, failed, emptyScore = 100) {
+    if (total === 0) return emptyScore;
+    return Math.max(0, Math.round(((total - failed) / total) * 100));
+  }
+
+  function readinessEnvelope(root, { persist = false } = {}) {
+    const queue = queueScanEnvelope(root, { persist: false });
+    const leases = leaseAuditEnvelope(root, 'list');
+    const recovery = recoveryEnvelope(root, { persist: false });
+    const retryHealth = retryHealthSummary(root);
+    const loopHealth = loopHealthSummary(root);
+    const replyHealth = replyHealthSummary(root);
+    const traceHealth = traceHealthSummary(root);
+    const dimensions = [
+      readinessDimension('candidate_readiness', queue.queue.items.length === 0 ? 50 : Math.round((queue.queue.ready.length / queue.queue.items.length) * 100), 15, 'derived from queue ready versus blocked items', queue.queue.items.map((item) => item.candidate_file)),
+      readinessDimension('approval_validity', queue.queue.items.length === 0 ? 50 : Math.round((queue.queue.items.filter((item) => item.approval_file && !item.blocked_reasons.includes('approval missing')).length / queue.queue.items.length) * 100), 10, 'derived from approval presence and verification in queue scan', queue.queue.items.map((item) => item.approval_file).filter(Boolean)),
+      readinessDimension('policy_allowed', queue.queue.items.some((item) => item.blocked_reasons.some((reason) => reason.includes('policy'))) ? 40 : 100, 10, 'policy blocks reduce readiness but do not trigger execution', []),
+      readinessDimension('queue_status', queue.queue.blocked.length === 0 ? 100 : Math.max(0, 100 - queue.queue.blocked.length * 20), 10, 'blocked queue items reduce readiness', queue.queue.blocked.map((item) => item.candidate_file)),
+      readinessDimension('lease_health', leases.summary.count === 0 ? 100 : Math.max(0, 100 - leases.summary.active_count * 25 - leases.summary.stale_count * 40 - leases.summary.invalid_count * 50), 10, 'active, stale, or invalid leases reduce readiness', leases.leases.map((lease) => lease.file)),
+      readinessDimension('execution_history', recovery.recovery.retry_candidates.length === 0 ? 100 : Math.max(0, 100 - recovery.recovery.retry_candidates.length * 30), 10, 'failed, timed_out, or running retry candidates reduce readiness', recovery.recovery.retry_candidates.map((item) => item.execution_file)),
+      readinessDimension('retry_health', Math.max(0, readinessScoreFromFailures(retryHealth.packages.count + retryHealth.runs.count, retryHealth.packages.failed_count + retryHealth.runs.failed_count) - retryHealth.duplicate_count * 20), 10, 'Stage 27 retry package/run artifacts are verified without allowing automatic retry', [...retryHealth.packages.details, ...retryHealth.runs.details].map((item) => item.file)),
+      readinessDimension('loop_health', Math.max(0, readinessScoreFromFailures(loopHealth.loops.count, loopHealth.loops.failed_count) - (loopHealth.stop_present ? 20 : 0)), 10, 'Stage 28 foreground loop artifacts, heartbeat, and stop file are inspected read-only', loopHealth.loops.details.map((item) => item.file)),
+      readinessDimension('reply_health', replyHealth.send_disabled ? readinessScoreFromFailures(replyHealth.count, replyHealth.failed_count) : 0, 10, 'Reply A-D artifacts are verified and external delivery remains disabled', replyHealth.details.map((item) => item.file)),
+      readinessDimension('trace_health', Math.max(0, readinessScoreFromFailures(traceHealth.traces.count, traceHealth.traces.failed_count, 50) - (traceHealth.drift ? 30 : 0)), 10, 'Stage 29 trace ledger is verified and checked for source digest drift', traceHealth.traces.details.map((item) => item.file)),
+      readinessDimension('observability_completeness', 100, 5, 'all local sources were inspected with corrupt artifacts isolated', []),
+    ];
+    const totalWeight = dimensions.reduce((sum, item) => sum + item.weight, 0);
+    const overall = Math.round(dimensions.reduce((sum, item) => sum + item.score * item.weight, 0) / totalWeight);
+    const blockedReasons = [...new Set([
+      ...queue.quality,
+      ...leases.quality,
+      ...recovery.quality,
+      ...retryHealth.blocked_reasons,
+      ...loopHealth.blocked_reasons,
+      ...replyHealth.blocked_reasons,
+      ...traceHealth.blocked_reasons,
+    ])];
+    return {
+      mode: 'observability-readiness-score',
+      ok: true,
+      state_present: fs.existsSync(workflowPath(root)),
+      observability: {
+        writes: Boolean(persist),
+        sources: ['workflow', 'queue', 'candidate', 'approval', 'execution', 'lock', 'lease', 'recovery', 'retry', 'daemon-loop', 'reply', 'runtime-trace'],
+        queue_summary: { items: queue.queue.items.length, ready: queue.queue.ready.length, blocked: queue.queue.blocked.length },
+        lease_summary: leases.summary,
+        recovery_summary: { retry_candidates: recovery.recovery.retry_candidates.length, retry_allowed: false },
+        retry_health: retryHealth,
+        loop_health: loopHealth,
+        reply_health: replyHealth,
+        trace_health: traceHealth,
+      },
+      readiness: {
+        overall_score: overall,
+        grade: overall >= 90 ? 'ready' : overall >= 70 ? 'review' : overall >= 50 ? 'blocked' : 'critical',
+        dimensions,
+        blocked_reasons: blockedReasons,
+        warnings: blockedReasons.slice(0, 10),
+        evidence_completeness: 'local-artifacts-only',
+        deterministic: true,
+      },
+      safety: {
+        stage: 'Stage 30',
+        writes: Boolean(persist),
+        observability_snapshot: Boolean(persist),
+        runtime_action: false,
+        auto_execution: false,
+        platform_api: false,
+        skill_execution: false,
+        business_source_write: false,
+        subagent: false,
+        mcp: false,
+        daemon: false,
+        git: false,
+        worktree: false,
+        dispatch_event_modified: false,
+        claim_modified: false,
+      },
+      quality: blockedReasons,
+      action: persist
+        ? 'observability snapshot was written. No readiness gate was changed and no runtime action occurred.'
+        : 'observability readiness score was computed read-only. No files were written and no runtime action occurred.',
+    };
+  }
+
+  return {
+    readinessDimension,
+    verificationSummaryFromFiles,
+    loopHealthSummary,
+    replyHealthSummary,
+    traceHealthSummary,
+    readinessScoreFromFailures,
+    readinessEnvelope,
+  };
+}