@jtf19/vibecoding-kit 0.1.0

package/tools/vibe-runtime/runtime-evidence-repair-model.mjs

@@ -0,0 +1,180 @@
+const forbiddenEvidenceRepairs = Object.freeze([
+  'change failing or blocked test evidence into passing evidence',
+  'create passing test evidence for commands that were not run',
+  'mark review evidence as passed without a review artifact',
+  'authorize commit, push, PR, merge, tag, or history rewrite fields',
+  'drop unexpected or missing changed files to hide coverage gaps',
+  'rewrite business source files or runtime command outputs',
+]);
+
+const boundaryAssertions = Object.freeze({
+  evidence_source_write: false,
+  test_result_forgery: false,
+  review_result_forgery: false,
+  commit_authorization: false,
+  command_execution: false,
+  test_execution: false,
+  git: false,
+  git_write: false,
+  worktree_write: false,
+  business_source_write: false,
+  platform_api: false,
+  external_network: false,
+  model_invocation: false,
+  subagent: false,
+  mcp: false,
+});
+
+function asArray(value) {
+  return Array.isArray(value) ? value : [];
+}
+
+function compact(values) {
+  return values.map((value) => String(value || '').trim()).filter(Boolean);
+}
+
+function unique(values) {
+  return [...new Set(compact(values))];
+}
+
+function nestedFindings(bundle) {
+  const implementation = bundle.implementation_chain || {};
+  const readiness = bundle.release_readiness_chain || {};
+  return unique([
+    ...asArray(bundle.evidence_gaps),
+    ...asArray(bundle.blocked_reasons),
+    ...asArray(implementation.test_evidence_gate?.findings),
+    ...asArray(implementation.diff_coverage_gate?.findings),
+    ...asArray(implementation.implementation_alignment_gate?.findings),
+    ...asArray(readiness.commit_readiness_gate?.findings),
+  ]);
+}
+
+function taskRegistry(bundle) {
+  const tasks = bundle.implementation_chain?.implementation_plan_gate?.registry?.tasks;
+  return Array.isArray(tasks) ? tasks : [];
+}
+
+function sourceMode(input) {
+  return String(input?.mode || input?.completion_evidence_bundle?.bundle_kind || input?.artifact_kind || 'unknown');
+}
+
+function sourceBundle(input) {
+  return input?.completion_evidence_bundle || input?.bundle || input;
+}
+
+function repairableAction(kind, target, reason, patch) {
+  return {
+    kind,
+    target,
+    reason,
+    patch,
+    applies_to_source: false,
+    requires_confirmed_sidecar: true,
+    truth_preserving: true,
+  };
+}
+
+function manualAction(target, reason, why) {
+  return {
+    target,
+    reason,
+    manual_action_required: true,
+    why,
+  };
+}
+
+function actionForFinding(finding, context) {
+  if (/must be valid JSON/.test(finding)) return manualAction('json.parse', finding, 'invalid JSON must be corrected in the original evidence by the producer or user');
+  if (/file not provided|not provided/.test(finding)) return manualAction('missing_evidence_file', finding, 'missing evidence cannot be invented by a repair plan');
+  if (/unexpected_files must be empty|missing_files must be empty/.test(finding)) return manualAction('diff_coverage.files', finding, 'changed-file coverage gaps need a real plan or diff update, not silent deletion');
+  if (/exit_code|status must be pass|status must be fail|test evidence|missing_test_evidence|review/i.test(finding)) return manualAction('test_or_review_truth', finding, 'test and review truth must come from real runs or review artifacts');
+  if (/commit_|git_|push|merge|history|tag|PR|pr/.test(finding)) return manualAction('release_boundary', finding, 'release boundary authorization cannot be repaired automatically');
+  if (/not found|unknown|uncovered|operation_mismatch|outside_task_scope|unexplained/.test(finding)) return manualAction('traceability_or_scope', finding, 'scope and traceability mismatches require human mapping or plan changes');
+
+  const taskRefMatch = finding.match(/task_refs\[\] must not be empty/);
+  if (taskRefMatch && context.tasks.length === 1) {
+    return repairableAction('add_task_ref', 'test_evidence.runs[].task_refs', finding, { task_refs: [context.tasks[0].task_id] });
+  }
+  if (taskRefMatch) return manualAction('test_evidence.runs[].task_refs', finding, 'multiple or missing task candidates make automatic task binding unsafe');
+
+  if (/scenario_refs\[\] must not be empty/.test(finding)) return manualAction('test_evidence.runs[].scenario_refs', finding, 'scenario binding needs a real scenario reference from acceptance evidence');
+  if (/output_digest is required/.test(finding)) return manualAction('test_evidence.runs[].output_digest', finding, 'output digest needs the original command output bytes');
+  if (/digest is required/.test(finding)) return manualAction('digest', finding, 'digest repair needs the exact source artifact content');
+
+  const arrayMatch = finding.match(/^(.*?) must be an array/);
+  if (arrayMatch) return repairableAction('normalize_array_field', arrayMatch[1], finding, { value: [] });
+
+  const artifactKindMatch = finding.match(/^(.*?)\.artifact_kind must be ([A-Za-z0-9._-]+)/);
+  if (artifactKindMatch) return repairableAction('set_artifact_kind', `${artifactKindMatch[1]}.artifact_kind`, finding, { value: artifactKindMatch[2] });
+
+  if (/must be explicitly false/.test(finding)) return repairableAction('set_missing_false_boundary', 'boundary_boolean', finding, { value: false });
+  if (/must be false/.test(finding)) return repairableAction('set_missing_false_boundary', 'boundary_boolean', finding, { value: false });
+
+  return manualAction('unclassified_gap', finding, 'the repair plan cannot prove a safe deterministic patch for this gap');
+}
+
+export function evidenceRepairBoundaryAssertions() {
+  return { ...boundaryAssertions };
+}
+
+export function buildEvidenceRepairPlan({ input, source, statePresent = false, persist = false, digestObject }) {
+  const bundle = sourceBundle(input);
+  const context = { tasks: taskRegistry(bundle).filter((task) => String(task?.task_id || '').trim()) };
+  const findings = nestedFindings(bundle);
+  const actions = findings.map((finding) => actionForFinding(finding, context));
+  const repairableActions = actions.filter((action) => action.manual_action_required !== true);
+  const manualActions = actions.filter((action) => action.manual_action_required === true);
+  const base = {
+    version: 1,
+    stage: 'P6',
+    artifact_kind: 'evidence-repair-plan',
+    source_file: source?.relative || '',
+    source_digest: source?.digest || '',
+    source_mode: sourceMode(input),
+    source_bundle_kind: String(bundle?.bundle_kind || bundle?.artifact_kind || ''),
+    status: findings.length === 0 ? 'no_repair_needed' : repairableActions.length > 0 ? 'repair_plan_available' : 'manual_action_required',
+    summary: {
+      finding_count: findings.length,
+      repairable_count: repairableActions.length,
+      manual_action_count: manualActions.length,
+      forbidden_repair_count: forbiddenEvidenceRepairs.length,
+    },
+    repairable_actions: repairableActions,
+    manual_actions: manualActions,
+    forbidden_repairs: [...forbiddenEvidenceRepairs],
+    allowed_targets: ['structure', 'references', 'missing digest only when exact source bytes are available'],
+    writes: false,
+    source_write: false,
+    state_sidecar_write: persist === true,
+    state_directory_created: persist === true,
+    local_only: true,
+    deterministic: true,
+    boundary_assertions: evidenceRepairBoundaryAssertions(),
+  };
+  const plan = { ...base, repair_plan_digest: digestObject(base) };
+  return {
+    mode: 'evidence-repair-plan',
+    ok: true,
+    state_present: statePresent,
+    evidence_repair_plan: plan,
+    safety: { stage: 'P6', evidence_repair_plan_artifact: persist === true, ...evidenceRepairBoundaryAssertions() },
+    quality: manualActions.map((action) => action.reason),
+    action: persist === true
+      ? 'evidence repair plan sidecar was written locally. Original evidence files were not modified, commands/tests were not run, and no git, platform, model, subagent, or business source action occurred.'
+      : 'evidence repair plan was computed read-only from one local bundle. Original evidence files were not modified, commands/tests were not run, and no git, platform, model, subagent, or business source action occurred.',
+  };
+}
+
+export function printEvidenceRepairPlan(envelope, { printList } = {}) {
+  const plan = envelope.evidence_repair_plan;
+  console.log('Vibecoding Runtime Evidence Repair Plan');
+  console.log(`Stage: ${plan.stage}; Status: ${plan.status}`);
+  console.log(`Source: ${plan.source_file || 'not provided'}; mode=${plan.source_mode}`);
+  console.log(`Repairable: ${plan.summary.repairable_count}; manual=${plan.summary.manual_action_count}; forbidden=${plan.summary.forbidden_repair_count}`);
+  if (plan.repairable_actions.length > 0 && printList) printList('Repairable actions', plan.repairable_actions.map((item) => `${item.kind}: ${item.target}`));
+  if (plan.manual_actions.length > 0 && printList) printList('Manual actions', plan.manual_actions.map((item) => item.reason));
+  console.log('Boundary: source_write=false; state_sidecar_write=' + String(plan.state_sidecar_write) + '; test_result_forgery=false; review_result_forgery=false; command_execution=false; git_write=false; business_source_write=false');
+  console.log(`Repair plan digest: ${plan.repair_plan_digest}`);
+  console.log(`Action: ${envelope.action}`);
+}

package/tools/vibe-runtime/runtime-executable-plan-contract.mjs

@@ -0,0 +1,428 @@
+import crypto from 'node:crypto';
+
+const executablePlanStage = 'Stage 117';
+const executablePlanKind = 'executable-plan-quality-contract';
+const scoreWeights = {
+  exact_file_paths: 15,
+  action_items: 15,
+  docs_code_expectations: 15,
+  verification_commands: 15,
+  expected_output_markers: 10,
+  commit_subject_hints: 10,
+  no_placeholders: 10,
+  stage_boundaries: 5,
+  rollback_stop_conditions: 5,
+};
+
+export function runtimeExecutablePlanContract({ sourcePlan = {}, planLint = {}, registry = {}, registryDigest = '' } = {}) {
+  const text = String(sourcePlan.text || '');
+  const boundaryAssertions = runtimeExecutablePlanContractBoundaryAssertions();
+  const extracted = extractPlanSignals(text);
+  const requirementChecks = executableRequirementChecks(extracted);
+  const taskReadiness = buildTaskReadiness(extracted);
+  const taskQualityContract = buildTaskQualityContract(taskReadiness);
+  const missingRequirements = requirementChecks.filter((item) => !item.pass).map((item) => item.id);
+  const planQualityScore = requirementChecks.reduce((score, item) => score + (item.pass ? item.weight : 0), 0);
+  const blockedReasons = blockedReasonsFor(requirementChecks, taskReadiness, taskQualityContract, planLint);
+  const contract = {
+    version: 1,
+    stage: executablePlanStage,
+    contract_kind: executablePlanKind,
+    source_plan: {
+      file: sourcePlan.file || '',
+      digest: sourcePlan.digest || '',
+      line_count: Number(sourcePlan.line_count || 0),
+    },
+    source_bindings: {
+      plan_lint_stage: planLint.stage || '',
+      plan_lint_digest: planLint.lint_digest || '',
+      registry_stage: registry.registry_stage || '',
+      registry_kind: registry.registry_kind || '',
+      registry_version: registry.registry_version || 0,
+      registry_digest: registryDigest,
+    },
+    requirement_checks: requirementChecks,
+    task_readiness: taskReadiness,
+    task_quality_contract: taskQualityContract,
+    failure_mode: {
+      blocking_gaps_only: true,
+      auto_repair: false,
+      plan_mutation: false,
+      rationale: 'Stage 117 reports executable plan gaps but never rewrites or repairs the source plan.',
+    },
+    missing_requirements: missingRequirements,
+    blocked_reasons: blockedReasons,
+    plan_quality_score: planQualityScore,
+    quality_threshold: 80,
+    plan_quality_pass: planQualityScore >= 80 && blockedReasons.length === 0,
+    extracted_expectations: {
+      exact_file_paths: extracted.paths,
+      action_items: extracted.actionItems.map((item) => item.title),
+      docs_expectations: extracted.docsExpectations,
+      code_expectations: extracted.codeExpectations,
+      verification_commands: extracted.commands,
+      expected_output_markers: extracted.outputMarkers,
+      commit_subject_hints: extracted.commitSubjects,
+      stage_boundaries: extracted.stageBoundaries,
+      rollback_stop_conditions: extracted.rollbackStopConditions,
+      placeholders: extracted.placeholders,
+    },
+    next_manual_action: nextManualAction(planQualityScore, blockedReasons),
+    allowed_followup: ['Stage 118 sequential stage runbook', 'manual plan refinement before Stage 118'],
+    forbidden_actions: [
+      'plan mutation or auto repair',
+      'test/check/command execution',
+      'action item execution',
+      'source write or formatting/code generation',
+      'sidecar or .vibecoding-state write',
+      'git commit/push/PR/merge/tag',
+      'platform API, external network, model, MCP, or subagent invocation',
+    ],
+    boundary_assertions: boundaryAssertions,
+    writes: false,
+    state_directory_created: false,
+    local_only: true,
+    deterministic: true,
+  };
+  const invariants = runtimeExecutablePlanContractInvariants(contract);
+  return {
+    ...contract,
+    executable_plan_invariants: invariants,
+    manual_action: invariants.pass
+      ? 'Executable plan quality contract is ready. Use it to decide whether Stage 118 runbook synthesis should proceed; Stage 117 did not execute or repair the plan.'
+      : 'Fix the listed executable plan contract gaps before deriving a Stage 118 runbook.',
+  };
+}
+
+export function runtimeExecutablePlanContractInvariants(contract) {
+  const missingSourceBindings = ['source_plan.digest', 'source_bindings.plan_lint_digest', 'source_bindings.registry_digest']
+    .filter((key) => !getPath(contract, key));
+  const missingFields = ['task_readiness', 'task_quality_contract', 'failure_mode', 'missing_requirements', 'blocked_reasons', 'plan_quality_score', 'requirement_checks']
+    .filter((field) => contract[field] === undefined || contract[field] === null);
+  const incompleteTasks = (contract.task_readiness || [])
+    .filter((item) => !item.id || !item.title || !Array.isArray(item.files_to_change) || !Array.isArray(item.verification_commands) || !Array.isArray(item.expected_output_markers) || !Array.isArray(item.stop_conditions) || item.execution_authorized !== false)
+    .map((item) => item.id || item.title || 'unknown');
+  const taskQualityFindings = contract.task_quality_contract?.pass === true ? [] : ['task_quality_contract must pass before Stage 118 runbook synthesis'];
+  const failureModeFindings = [
+    ...(contract.failure_mode?.blocking_gaps_only === true ? [] : ['failure_mode.blocking_gaps_only must be true']),
+    ...(contract.failure_mode?.auto_repair === false ? [] : ['failure_mode.auto_repair must be false']),
+    ...(contract.failure_mode?.plan_mutation === false ? [] : ['failure_mode.plan_mutation must be false']),
+  ];
+  const writableBoundaries = Object.entries(contract.boundary_assertions || {})
+    .filter(([, value]) => value !== false)
+    .map(([key]) => key);
+  const forbiddenMissing = ['command_execution', 'test_execution', 'repair_execution', 'source_write', 'sidecar_write', 'state_directory_created', 'git', 'git_write', 'commit', 'push', 'pr', 'merge', 'platform_api', 'external_network', 'model_invocation', 'subagent', 'mcp', 'business_source_write']
+    .filter((key) => contract.boundary_assertions?.[key] !== false);
+  const executionLeak = [
+    ...((contract.task_readiness || []).filter((item) => item.execution_authorized !== false).map((item) => `task:${item.id}`)),
+    ...((contract.requirement_checks || []).filter((item) => item.execution_authorized !== false).map((item) => `requirement:${item.id}`)),
+  ];
+  const findings = [
+    ...(contract.stage === executablePlanStage ? [] : ['stage must be Stage 117']),
+    ...(contract.contract_kind === executablePlanKind ? [] : ['contract_kind must be executable-plan-quality-contract']),
+    ...missingSourceBindings.map((item) => `missing source binding: ${item}`),
+    ...missingFields.map((item) => `missing required field: ${item}`),
+    ...incompleteTasks.map((item) => `incomplete or executable task readiness item: ${item}`),
+    ...taskQualityFindings,
+    ...failureModeFindings,
+    ...writableBoundaries.map((item) => `boundary assertion must remain false: ${item}`),
+    ...forbiddenMissing.map((item) => `forbidden boundary missing or not false: ${item}`),
+    ...executionLeak.map((item) => `execution must not be authorized: ${item}`),
+  ];
+  return {
+    pass: findings.length === 0,
+    checked: [
+      'source_plan_binding',
+      'plan_lint_binding',
+      'requirement_scoring_schema',
+      'task_readiness_schema',
+      'task_quality_contract_schema',
+      'blocking_gaps_only_failure_mode',
+      'execution_authorized_false',
+      'read_only_boundary_assertions',
+    ],
+    findings,
+  };
+}
+
+export function runtimeExecutablePlanContractBoundaryAssertions() {
+  return {
+    executable_plan_artifact: false,
+    plan_repair_artifact: false,
+    sidecar_write: false,
+    state_directory_created: false,
+    source_write: false,
+    command_execution: false,
+    check_execution: false,
+    test_execution: false,
+    repair_execution: false,
+    formatting_execution: false,
+    code_generation: false,
+    action_item_execution: false,
+    workflow_execution: false,
+    runtime_action: false,
+    auto_execution: false,
+    scheduler: false,
+    daemon: false,
+    retry: false,
+    git: false,
+    git_write: false,
+    commit: false,
+    pr: false,
+    push: false,
+    merge: false,
+    tag: false,
+    platform_api: false,
+    external_network: false,
+    model_invocation: false,
+    subagent: false,
+    mcp: false,
+    worktree: false,
+    business_source_write: false,
+  };
+}
+
+export function runtimeExecutablePlanContractDigestPayload(contract) {
+  return {
+    stage: contract.stage,
+    contract_kind: contract.contract_kind,
+    source_plan: contract.source_plan,
+    source_bindings: contract.source_bindings,
+    requirement_checks: contract.requirement_checks,
+    task_readiness: contract.task_readiness,
+    task_quality_contract: contract.task_quality_contract,
+    failure_mode: contract.failure_mode,
+    missing_requirements: contract.missing_requirements,
+    blocked_reasons: contract.blocked_reasons,
+    plan_quality_score: contract.plan_quality_score,
+    quality_threshold: contract.quality_threshold,
+    plan_quality_pass: contract.plan_quality_pass,
+    extracted_expectations: contract.extracted_expectations,
+    next_manual_action: contract.next_manual_action,
+    allowed_followup: contract.allowed_followup,
+    forbidden_actions: contract.forbidden_actions,
+    boundary_assertions: contract.boundary_assertions,
+    executable_plan_invariants: contract.executable_plan_invariants,
+  };
+}
+
+export function digestExecutablePlanContract(value) {
+  return crypto.createHash('sha256').update(stableStringify(value)).digest('hex');
+}
+
+function extractPlanSignals(text) {
+  const lines = String(text || '').split(/\r?\n/);
+  const paths = extractPaths(text);
+  const actionItems = extractActionItems(lines);
+  const commands = extractCommands(text);
+  return {
+    paths,
+    actionItems,
+    commands,
+    outputMarkers: extractOutputMarkers(lines),
+    commitSubjects: extractCommitSubjects(text),
+    stageBoundaries: extractStageBoundaries(lines),
+    rollbackStopConditions: extractRollbackStopConditions(lines),
+    placeholders: extractPlaceholders(text),
+    docsExpectations: paths.filter(isDocsPath),
+    codeExpectations: paths.filter((file) => !isDocsPath(file)),
+  };
+}
+
+function executableRequirementChecks(signals) {
+  return [
+    requirement('exact_file_paths', 'exact file paths', signals.paths.length > 0, scoreWeights.exact_file_paths, signals.paths),
+    requirement('action_items', 'action items', signals.actionItems.length > 0, scoreWeights.action_items, signals.actionItems.map((item) => item.title)),
+    requirement('docs_code_expectations', 'docs/code expectations', signals.docsExpectations.length > 0 && signals.codeExpectations.length > 0, scoreWeights.docs_code_expectations, [...signals.docsExpectations, ...signals.codeExpectations]),
+    requirement('verification_commands', 'test or verification commands', signals.commands.length > 0, scoreWeights.verification_commands, signals.commands),
+    requirement('expected_output_markers', 'expected output markers', signals.outputMarkers.length > 0, scoreWeights.expected_output_markers, signals.outputMarkers),
+    requirement('commit_subject_hints', 'commit subject hints', signals.commitSubjects.length > 0, scoreWeights.commit_subject_hints, signals.commitSubjects),
+    requirement('no_placeholders', 'no placeholders', signals.placeholders.length === 0, scoreWeights.no_placeholders, signals.placeholders),
+    requirement('stage_boundaries', 'stage boundaries', signals.stageBoundaries.length > 0, scoreWeights.stage_boundaries, signals.stageBoundaries),
+    requirement('rollback_stop_conditions', 'rollback / stop conditions', signals.rollbackStopConditions.length > 0, scoreWeights.rollback_stop_conditions, signals.rollbackStopConditions),
+  ];
+}
+
+function requirement(id, label, pass, weight, evidence) {
+  return {
+    id,
+    label,
+    pass: Boolean(pass),
+    weight,
+    evidence: Array.isArray(evidence) ? evidence.slice(0, 20) : [],
+    execution_authorized: false,
+  };
+}
+
+function buildTaskReadiness(signals) {
+  const fallbackFiles = signals.paths.slice(0, 12);
+  const fallbackCommands = signals.commands.slice(0, 8);
+  return signals.actionItems.slice(0, 30).map((item, index) => {
+    const localFiles = extractPaths(item.title);
+    const files = localFiles.length > 0 ? localFiles : fallbackFiles;
+    return {
+      id: `stage117-task-${String(index + 1).padStart(2, '0')}-${slugify(item.title)}`,
+      title: item.title,
+      source_line: item.line,
+      files_to_change: files,
+      docs_expectation_present: files.some(isDocsPath) || signals.docsExpectations.length > 0,
+      code_expectation_present: files.some((file) => !isDocsPath(file)) || signals.codeExpectations.length > 0,
+      verification_commands: fallbackCommands,
+      expected_output_markers: signals.outputMarkers.slice(0, 8),
+      commit_subject_hints: signals.commitSubjects.slice(0, 5),
+      stop_conditions: signals.rollbackStopConditions.slice(0, 8),
+      readiness_status: files.length > 0 && fallbackCommands.length > 0 && signals.outputMarkers.length > 0 && signals.rollbackStopConditions.length > 0 ? 'ready_for_runbook' : 'needs_plan_detail',
+      execution_authorized: false,
+    };
+  });
+}
+
+function buildTaskQualityContract(taskReadiness) {
+  const requiredFields = ['files_to_change', 'verification_commands', 'expected_output_markers', 'stop_conditions'];
+  const perTaskGates = taskReadiness.map((task) => {
+    const gaps = [
+      ...(task.files_to_change.length > 0 ? [] : ['exact_file_paths']),
+      ...(task.verification_commands.length > 0 ? [] : ['verification_commands']),
+      ...(task.expected_output_markers.length > 0 ? [] : ['expected_output_markers']),
+      ...(task.stop_conditions.length > 0 ? [] : ['rollback_stop_conditions']),
+    ];
+    return {
+      task_id: task.id,
+      title: task.title,
+      required_fields: requiredFields,
+      pass: gaps.length === 0 && task.execution_authorized === false,
+      blocking_gaps: gaps,
+      failure_output: gaps.length > 0 ? `blocking gaps only: ${gaps.join(', ')}` : '',
+      auto_repair: false,
+      execution_authorized: false,
+    };
+  });
+  const blockingGaps = perTaskGates
+    .filter((item) => !item.pass)
+    .map((item) => `task quality gap: ${item.task_id}: ${item.blocking_gaps.join(', ')}`);
+  return {
+    required_task_fields: requiredFields,
+    per_task_gates: perTaskGates,
+    blocking_gaps: blockingGaps,
+    blocking_gaps_only: true,
+    auto_repair: false,
+    plan_mutation: false,
+    pass: perTaskGates.length > 0 && blockingGaps.length === 0,
+  };
+}
+
+function blockedReasonsFor(requirementChecks, taskReadiness, taskQualityContract, planLint) {
+  const reasons = requirementChecks
+    .filter((item) => !item.pass)
+    .map((item) => `missing ${item.label}`);
+  const blockedTasks = taskReadiness
+    .filter((item) => item.readiness_status !== 'ready_for_runbook')
+    .map((item) => `task not ready for runbook: ${item.id}`);
+  const lintBlockers = Array.isArray(planLint.blocking_findings) ? planLint.blocking_findings.map((item) => `plan lint blocker: ${item}`) : [];
+  const taskQualityBlockers = Array.isArray(taskQualityContract.blocking_gaps) ? taskQualityContract.blocking_gaps : [];
+  return [...reasons, ...blockedTasks, ...taskQualityBlockers, ...lintBlockers].slice(0, 40);
+}
+
+function nextManualAction(score, blockedReasons) {
+  if (blockedReasons.length > 0) return `Refine the plan before Stage 118. First blocker: ${blockedReasons[0]}`;
+  if (score < 80) return 'Raise plan_quality_score to at least 80 before deriving a Stage 118 runbook.';
+  return 'Plan is structurally ready for Stage 118 sequential stage runbook synthesis; Stage 117 did not execute commands or modify the plan.';
+}
+
+function extractActionItems(lines) {
+  const items = [];
+  for (const [index, raw] of lines.entries()) {
+    const line = raw.trim();
+    if (!line) continue;
+    const checkbox = line.match(/^- \[[ xX]\]\s+(.+)$/);
+    const numbered = line.match(/^\d+[.)]\s+(.+)$/);
+    const bullet = line.match(/^-\s+(Stage\s+\d+|Task\b|Add\b|Update\b|Run\b|Validate\b|Implement\b|Create\b|Sync\b|Reject\b|Rollback\b|Stop\b|任务|阶段|修改|新增|验证|检查|文档|实现).+/i);
+    const title = checkbox?.[1] || numbered?.[1] || bullet?.[0]?.replace(/^[-\s]+/, '') || '';
+    if (title) items.push({ title: title.trim(), line: index + 1 });
+  }
+  return dedupeByTitle(items).slice(0, 40);
+}
+
+function extractPaths(text) {
+  const matches = String(text || '').match(/(?:[A-Za-z]:[\\/])?(?:[\w.-]+[\\/])+(?:[\w.-]+\.(?:mjs|js|ts|tsx|jsx|json|md|yml|yaml|toml|txt|css|html)|[\w.-]+)/g) || [];
+  return [...new Set(matches
+    .map((item) => item.replace(/\\/g, '/'))
+    .filter((item) => !item.startsWith('http'))
+    .filter((item) => /\.(?:mjs|js|ts|tsx|jsx|json|md|yml|yaml|toml|txt|css|html)$/i.test(item)))]
+    .slice(0, 60);
+}
+
+function extractCommands(text) {
+  const fencedCommands = [...String(text || '').matchAll(/`([^`]*(?:node|npm|pnpm|yarn|git|pytest|python|tsc|eslint|vitest|jest|powershell)[^`]*)`/gi)].map((match) => match[1].trim());
+  const lineCommands = [...String(text || '').matchAll(/(?:^|\n)\s*(?:[-*]\s*)?((?:node|npm|pnpm|yarn|git|pytest|python|tsc|eslint|vitest|jest|powershell)\s+[^\n`]+)/gi)].map((match) => match[1].trim());
+  return [...new Set([...fencedCommands, ...lineCommands].map((item) => item.trim()))].slice(0, 30);
+}
+
+function extractOutputMarkers(lines) {
+  const markers = [];
+  for (const raw of lines) {
+    const line = raw.trim();
+    const marker = line.match(/(?:expect(?:ed)? output|output marker|marker|结果|输出|应包含|包含)[:：]\s*(.+)$/i);
+    if (marker?.[1]) markers.push(marker[1].trim());
+    const quoted = line.match(/(?:Result:\s*PASS|PASS|Stage\s+\d+|contract_digest|plan_quality_score|executable_plan_contract)/i);
+    if (quoted) markers.push(quoted[0]);
+  }
+  return [...new Set(markers)].slice(0, 30);
+}
+
+function extractCommitSubjects(text) {
+  const explicit = [...String(text || '').matchAll(/(?:commit|提交)(?: subject| message| 信息|：|:)\s*[`"“]?([^`"”\n]+)/gi)].map((match) => match[1].trim());
+  const conventional = String(text || '').match(/\b(?:feat|fix|docs|test|refactor|chore|perf)\([^\n)]+\):\s*[^\n]+/g) || [];
+  return [...new Set([...explicit, ...conventional].map((item) => item.trim()))].slice(0, 10);
+}
+
+function extractStageBoundaries(lines) {
+  const boundaries = lines
+    .map((line) => line.trim())
+    .filter((line) => /Stage\s+\d+|阶段\s*\d+|按.*顺序|sequential|runbook|stage boundary/i.test(line));
+  return [...new Set(boundaries)].slice(0, 30);
+}
+
+function extractRollbackStopConditions(lines) {
+  const conditions = lines
+    .map((line) => line.trim().replace(/^[-*]\s+/, ''))
+    .filter((line) => /rollback|stop if|stop condition|blocked|fail|失败|阻塞|停止|回滚|不要|不得/i.test(line));
+  return [...new Set(conditions)].slice(0, 30);
+}
+
+function extractPlaceholders(text) {
+  const matches = String(text || '').match(/\b(?:TODO|TBD|FIXME|placeholder|待定|占位|稍后补充|xxx)\b/gi) || [];
+  return [...new Set(matches)].slice(0, 20);
+}
+
+function isDocsPath(file) {
+  return /(^|\/)(docs?|README|CHANGELOG)|\.md$/i.test(String(file || ''));
+}
+
+function slugify(value) {
+  return String(value || 'item').toLowerCase().replace(/[^a-z0-9\u4e00-\u9fa5]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 48) || 'item';
+}
+
+function dedupeByTitle(items) {
+  const seen = new Set();
+  const result = [];
+  for (const item of items) {
+    const key = item.title.toLowerCase();
+    if (seen.has(key)) continue;
+    seen.add(key);
+    result.push(item);
+  }
+  return result;
+}
+
+function getPath(value, dotted) {
+  return dotted.split('.').reduce((current, key) => current?.[key], value);
+}
+
+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);
+}