@jtf19/vibecoding-kit 0.1.0

package/tools/vibe-runtime/runtime-delivery-methodology-gates.mjs

@@ -0,0 +1,277 @@
+import crypto from 'node:crypto';
+import { runtimeStatePresent } from './runtime-state-presence-model.mjs';
+import {
+  productMethodologyBoundaryAssertions,
+  readLocalTextArtifact,
+} from './runtime-product-methodology-gates.mjs';
+
+export const deliveryMethodologyGateKinds = new Set([
+  'architecture-design',
+  'delivery-traceability',
+]);
+
+const falseBoundaryKeys = ['writes', 'state_directory_created', 'command_execution', 'test_execution', 'skill_execution', 'subagent', 'mcp', 'git'];
+const traceabilityStatuses = new Set(['verified', 'not_verified', 'blocked', 'not_applicable']);
+
+const architectureContract = {
+  artifact_kind: 'architecture-design',
+  source_skill: 'vibe-planning',
+  next_skills: ['vibe-writing-plans', 'vibe-test-driven-development', 'none'],
+  sections: [
+    'Goal',
+    'Input',
+    'Architecture Decision Frame',
+    'Module Ownership',
+    'Layer And Dependency Direction',
+    'Data Flow',
+    'State Lifecycle',
+    'Contract Sync',
+    'Blast Radius',
+    'Verification Strategy',
+    'Risks',
+    'Non Goals',
+    'Evidence',
+    'Boundary',
+    'Handoff',
+  ],
+  fields: [
+    'architecture_goal',
+    'responsibility_owner',
+    'layer_and_dependency_direction',
+    'data_flow',
+    'state_lifecycle',
+    'contract_sync',
+    'blast_radius',
+    'risk_class',
+    'verification_strategy',
+    'architecture_decisions',
+  ],
+};
+
+export function normalizeDeliveryMethodologyKind(kind) {
+  return String(kind || '').trim().toLowerCase().replace(/_/g, '-');
+}
+
+export function deliveryMethodologyGateEnvelope(root, { kind = '', fromFile = '' } = {}) {
+  const gateKind = normalizeDeliveryMethodologyKind(kind);
+  if (!deliveryMethodologyGateKinds.has(gateKind)) throw new Error(`unsupported delivery methodology gate kind: ${kind}`);
+  const source = readLocalTextArtifact(root, fromFile, `methodology --gate --kind ${gateKind}`);
+  const validation = gateKind === 'architecture-design'
+    ? validateArchitectureDesignArtifact(source.text)
+    : validateDeliveryTraceabilityArtifact(source.text);
+  const boundaryAssertions = deliveryMethodologyBoundaryAssertions();
+  const checks = validation.checks;
+  const blockedReasons = checks.filter((check) => !check.pass).map((check) => `${check.id}: ${check.reason}`);
+  const gate = {
+    version: 1,
+    stage: gateKind === 'architecture-design' ? 'Stage 153' : 'Stage 154',
+    gate_kind: gateKind,
+    artifact_kind: validation.artifact_kind,
+    gate_outcome: blockedReasons.length === 0 ? 'pass' : 'blocked',
+    source_bindings: {
+      artifact_file: source.relative,
+      artifact_digest: source.digest,
+      expected_source_skill: validation.expected_source_skill,
+      declared_source_skill: validation.declared_source_skill,
+      declared_next_skill: validation.declared_next_skill,
+    },
+    checks,
+    blocked_reasons: blockedReasons,
+    summary: validation.summary,
+    invariants: {
+      pass: blockedReasons.length === 0 && Object.values(boundaryAssertions).every((value) => value === false),
+      checked: ['source_binding', 'artifact_kind', 'source_skill', 'next_skill', 'required_sections_or_links', 'required_fields', 'evidence', 'boundary_assertions'],
+    },
+    next_manual_action: blockedReasons.length === 0
+      ? 'Artifact contract is complete enough for the next manual workflow handoff; no workflow, test, browser, subagent, git, or platform action was run.'
+      : 'Fix the listed artifact gaps manually, then rerun methodology --gate with the same local file.',
+    boundary_assertions: boundaryAssertions,
+    writes: false,
+    state_directory_created: false,
+    local_only: true,
+    deterministic: true,
+  };
+  return {
+    mode: 'delivery-methodology-gate',
+    ok: gate.invariants.pass,
+    state_present: runtimeStatePresent(root),
+    delivery_methodology_gate: {
+      ...gate,
+      gate_digest: digestDeliveryMethodologyGate(deliveryMethodologyGateDigestPayload(gate)),
+    },
+    safety: { stage: gate.stage, ...boundaryAssertions },
+    quality: blockedReasons,
+    action: 'methodology delivery gate read one local artifact and computed deterministic checks only. No state directory, artifact write, workflow skill execution, command/check/test/browser execution, runtime action, git, platform API, external network, model, MCP, subagent, or business source mutation occurred.',
+  };
+}
+
+export function deliveryMethodologyBoundaryAssertions() {
+  return {
+    ...productMethodologyBoundaryAssertions(),
+    architecture_artifact_write: false,
+    traceability_artifact_write: false,
+    plan_artifact_write: false,
+    diff_coverage_artifact: false,
+    commit_readiness_artifact: false,
+    git_add: false,
+    history_rewrite: false,
+  };
+}
+
+export function deliveryMethodologyGateDigestPayload(gate) {
+  return {
+    version: gate.version,
+    stage: gate.stage,
+    gate_kind: gate.gate_kind,
+    artifact_kind: gate.artifact_kind,
+    source_bindings: gate.source_bindings,
+    checks: gate.checks,
+    summary: gate.summary,
+    boundary_assertions: gate.boundary_assertions,
+    writes: gate.writes,
+    state_directory_created: gate.state_directory_created,
+  };
+}
+
+export function digestDeliveryMethodologyGate(payload) {
+  return crypto.createHash('sha256').update(stableStringify(payload)).digest('hex');
+}
+
+function validateArchitectureDesignArtifact(text) {
+  const frontmatter = parseFrontmatter(text);
+  const checks = [];
+  const fieldValues = parseFieldValues(text);
+  addCheck(checks, 'frontmatter.artifact_kind', frontmatter.artifact_kind === architectureContract.artifact_kind, `expected artifact_kind: ${architectureContract.artifact_kind}`);
+  addCheck(checks, 'frontmatter.version', String(frontmatter.version || '') === '1', 'expected version: 1');
+  addCheck(checks, 'frontmatter.source_skill', frontmatter.source_skill === architectureContract.source_skill, `expected source_skill: ${architectureContract.source_skill}`);
+  addCheck(checks, 'frontmatter.status', Boolean(String(frontmatter.status || '').trim()), 'status is required');
+  addCheck(checks, 'frontmatter.next_skill', architectureContract.next_skills.includes(String(frontmatter.next_skill || '').trim()), `next_skill must be one of ${architectureContract.next_skills.join(', ')}`);
+  for (const section of architectureContract.sections) addCheck(checks, `section.${section}`, hasSection(text, section), `missing section: ${section}`);
+  for (const field of architectureContract.fields) addCheck(checks, `field.${field}`, hasNonEmptyField(fieldValues, field), `missing non-empty field: ${field}`);
+  addCheck(checks, 'evidence.present', hasSection(text, 'Evidence') && (/evidence_sources\s*:/i.test(text) || /not_verified\s*:/i.test(text)), 'Evidence must include evidence_sources or not_verified');
+  for (const key of falseBoundaryKeys) addCheck(checks, `boundary.${key}`, boundaryFalse(text, key), `Boundary must declare ${key}: false`);
+  return {
+    artifact_kind: architectureContract.artifact_kind,
+    expected_source_skill: architectureContract.source_skill,
+    declared_source_skill: frontmatter.source_skill || '',
+    declared_next_skill: frontmatter.next_skill || '',
+    summary: {
+      required_section_count: architectureContract.sections.length,
+      required_field_count: architectureContract.fields.length,
+    },
+    checks,
+  };
+}
+
+function validateDeliveryTraceabilityArtifact(text) {
+  const top = parseYamlTopLevel(text);
+  const links = parseTraceabilityLinks(text);
+  const checks = [];
+  addCheck(checks, 'artifact_kind', top.artifact_kind === 'delivery-traceability', 'expected artifact_kind: delivery-traceability');
+  addCheck(checks, 'version', String(top.version || '') === '1', 'expected version: 1');
+  addCheck(checks, 'source_skill', top.source_skill === 'vibe-writing-plans', 'expected source_skill: vibe-writing-plans');
+  addCheck(checks, 'next_skill', ['vibe-test-driven-development', 'vibe-product-acceptance', 'vibe-verification-before-completion', 'none'].includes(String(top.next_skill || '').trim()), 'next_skill must route to TDD, product acceptance, verification, or none');
+  addCheck(checks, 'links.non_empty', links.length > 0, 'links[] must not be empty');
+  for (const link of links) {
+    const keyCount = traceabilityRefKeys().filter((key) => hasScalarValue(link.block, key)).length;
+    addCheck(checks, `link.${link.id || 'missing-id'}.id`, Boolean(link.id), 'link id is required');
+    addCheck(checks, `link.${link.id || 'missing-id'}.refs`, keyCount >= 8, 'link must bind requirement/product/UI/architecture/task/test/scenario/acceptance refs');
+    addCheck(checks, `link.${link.id || 'missing-id'}.status`, traceabilityStatuses.has(link.status), 'status must be verified, not_verified, blocked, or not_applicable');
+  }
+  for (const key of falseBoundaryKeys) addCheck(checks, `boundary.${key}`, boundaryFalse(text, key), `boundary.${key} must be false`);
+  return {
+    artifact_kind: 'delivery-traceability',
+    expected_source_skill: 'vibe-writing-plans',
+    declared_source_skill: top.source_skill || '',
+    declared_next_skill: top.next_skill || '',
+    summary: {
+      link_count: links.length,
+      statuses: Object.fromEntries([...traceabilityStatuses].map((status) => [status, links.filter((link) => link.status === status).length])),
+    },
+    checks,
+  };
+}
+
+function traceabilityRefKeys() {
+  return ['requirement_ref', 'product_story_ref', 'ui_flow_ref', 'architecture_decision_ref', 'implementation_task_ref', 'test_evidence_ref', 'scenario_ref', 'product_acceptance_ref'];
+}
+
+function parseFrontmatter(text) {
+  const match = text.match(/^---\s*\n([\s\S]*?)\n---\s*\n/);
+  if (!match) return {};
+  return Object.fromEntries(match[1].split(/\r?\n/).map((line) => line.match(/^([A-Za-z0-9_-]+):\s*(.*?)\s*$/)).filter(Boolean).map(([, key, value]) => [key, stripQuotes(value)]));
+}
+
+function parseFieldValues(text) {
+  const values = new Map();
+  const regex = /(?:^|\n)\s*-\s*([A-Za-z0-9_]+):\s*(.*?)\s*(?=\n|$)/g;
+  let match;
+  while ((match = regex.exec(text))) values.set(match[1], stripQuotes(match[2]));
+  return values;
+}
+
+function parseYamlTopLevel(text) {
+  const top = {};
+  for (const line of text.split(/\r?\n/)) {
+    const match = line.match(/^([A-Za-z0-9_-]+):\s*(.*?)\s*$/);
+    if (match) top[match[1]] = stripQuotes(match[2]);
+  }
+  return top;
+}
+
+function parseTraceabilityLinks(text) {
+  const lines = text.split(/\r?\n/);
+  const blocks = [];
+  let current = null;
+  for (const line of lines) {
+    const start = line.match(/^\s*-\s+id:\s*(\S.*?)\s*$/);
+    if (start) {
+      if (current) blocks.push(current);
+      current = { id: stripQuotes(start[1]), lines: [line] };
+      continue;
+    }
+    if (current) current.lines.push(line);
+  }
+  if (current) blocks.push(current);
+  return blocks.map((block) => {
+    const textBlock = block.lines.join('\n');
+    const statusMatch = textBlock.match(/(?:^|\n)\s*status:\s*(\S+)\s*(?:\n|$)/);
+    return { id: block.id, block: textBlock, status: stripQuotes(statusMatch?.[1] || '') };
+  });
+}
+
+function hasSection(text, section) {
+  return new RegExp(`^##\\s+${escapeRegExp(section)}\\s*$`, 'm').test(text);
+}
+
+function hasNonEmptyField(fieldValues, field) {
+  return Boolean(String(fieldValues.get(field) || '').trim());
+}
+
+function hasScalarValue(block, key) {
+  return new RegExp(`${key}:\\s*\\S`, 'm').test(block);
+}
+
+function boundaryFalse(text, key) {
+  return new RegExp(`${key}:\\s*false\\b`, 'i').test(text);
+}
+
+function stripQuotes(value) {
+  return String(value || '').trim().replace(/^['"]|['"]$/g, '');
+}
+
+function addCheck(checks, id, pass, reason) {
+  checks.push({ id, pass: Boolean(pass), reason: pass ? '' : reason });
+}
+
+function escapeRegExp(value) {
+  return String(value).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+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-diff-coverage-envelope.mjs

@@ -0,0 +1,301 @@
+import crypto from 'node:crypto';
+
+const diffCoverageStage = 'Stage 111';
+const diffCoverageKind = 'diff-coverage-envelope';
+const maxDiffBytes = 1024 * 1024;
+
+export function runtimeDiffCoverageEnvelope({
+  diffText = '',
+  diffSource = {},
+  planActionManifest = {},
+  registry = {},
+  registryDigest = '',
+} = {}) {
+  const boundaryAssertions = runtimeDiffCoverageBoundaryAssertions();
+  const diffFindings = diffSafetyFindings(diffText);
+  const changedFiles = parseChangedFiles(diffText);
+  const expected = expectedFilesFor(planActionManifest);
+  const changedSet = new Set(changedFiles);
+  const expectedSet = new Set(expected.expected_files);
+  const coveredExpectedFiles = expected.expected_files.filter((file) => changedSet.has(file));
+  const missingExpectedFiles = expected.expected_files.filter((file) => !changedSet.has(file));
+  const unexpectedFiles = changedFiles.filter((file) => !expectedSet.has(file));
+  const pathFindings = pathSafetyFindings(changedFiles);
+  const docsCoverage = expectationCoverage('docs', expected.docs_expected_files, changedSet, planActionManifest.docs_expectations || []);
+  const codeCoverage = expectationCoverage('code', expected.code_expected_files, changedSet, planActionManifest.code_expectations || []);
+  const blockedReasons = [
+    ...diffFindings.filter((item) => item.severity === 'blocker').map((item) => item.reason),
+    ...pathFindings.filter((item) => item.severity === 'blocker').map((item) => item.reason),
+    ...missingExpectedFiles.map((file) => `missing expected changed file: ${file}`),
+    ...unexpectedFiles.map((file) => `unexpected changed file outside plan manifest: ${file}`),
+  ];
+  const envelope = {
+    version: 1,
+    stage: diffCoverageStage,
+    coverage_kind: diffCoverageKind,
+    source_diff: {
+      file: diffSource.relative || diffSource.file || '',
+      digest: diffSource.digest || '',
+      byte_length: Buffer.byteLength(String(diffText || ''), 'utf8'),
+      line_count: String(diffText || '').length === 0 ? 0 : String(diffText || '').replace(/\r\n/g, '\n').replace(/\r/g, '\n').split('\n').length,
+    },
+    source_bindings: {
+      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,
+    },
+    diff_coverage: {
+      diff_file_read: Boolean(diffSource.digest),
+      changed_file_count: changedFiles.length,
+      expected_file_count: expected.expected_files.length,
+      covered_expected_file_count: coveredExpectedFiles.length,
+      missing_expected_file_count: missingExpectedFiles.length,
+      unexpected_file_count: unexpectedFiles.length,
+      coverage_complete: missingExpectedFiles.length === 0 && unexpectedFiles.length === 0 && changedFiles.length > 0,
+      git_executed_by_stage_111: false,
+      diff_generated_by_stage_111: false,
+      execution_authorized: false,
+    },
+    changed_files: changedFiles,
+    expected_files: expected.expected_files,
+    covered_expected_files: coveredExpectedFiles,
+    missing_expected_files: missingExpectedFiles,
+    unexpected_files: unexpectedFiles,
+    docs_coverage: docsCoverage,
+    code_coverage: codeCoverage,
+    safety_findings: [...diffFindings, ...pathFindings],
+    blocked_reasons: blockedReasons,
+    allowed_followup: [
+      'manual diff capture outside Stage 111',
+      'manual scope reconciliation before commit readiness',
+      'Stage 112 review intake from local review evidence',
+    ],
+    forbidden_actions: [
+      'running git diff, git status, git add, git commit, push, PR, merge, reset, checkout, or history rewrite',
+      'executing tests, checks, repair, formatting, or code generation',
+      'creating or rewriting diff artifacts',
+      'sidecar or .vibecoding-state write',
+      'platform API, external network, model, MCP, or subagent invocation',
+      'treating diff coverage pass as execution or commit permission',
+    ],
+    boundary_assertions: boundaryAssertions,
+    writes: false,
+    state_directory_created: false,
+    local_only: true,
+    deterministic: true,
+  };
+  const invariants = runtimeDiffCoverageInvariants(envelope);
+  return {
+    ...envelope,
+    diff_coverage_invariants: invariants,
+    manual_action: invariants.pass
+      ? 'Diff coverage is structurally aligned with the local plan manifest. Stage 111 only read the local diff file and did not call git.'
+      : 'Resolve the listed diff coverage blockers before using this diff as closeout evidence.',
+  };
+}
+
+export function runtimeDiffCoverageInvariants(envelope) {
+  const writableBoundaries = Object.entries(envelope.boundary_assertions || {})
+    .filter(([, value]) => value !== false)
+    .map(([key]) => key);
+  const forbiddenMissing = ['diff_coverage_artifact', 'diff_artifact_write', 'command_execution', 'git', 'git_write', 'commit', 'push', 'pr', 'merge', 'platform_api', 'external_network', 'model_invocation', 'subagent', 'mcp', 'business_source_write']
+    .filter((key) => envelope.boundary_assertions?.[key] !== false);
+  const findings = [
+    ...(envelope.source_diff?.digest ? [] : ['missing diff source digest']),
+    ...((envelope.changed_files || []).length > 0 ? [] : ['changed_files must not be empty']),
+    ...((envelope.expected_files || []).length > 0 ? [] : ['expected_files must not be empty']),
+    ...((envelope.blocked_reasons || []).map((item) => `blocked: ${item}`)),
+    ...(envelope.diff_coverage?.git_executed_by_stage_111 === false ? [] : ['Stage 111 must not execute git']),
+    ...(envelope.diff_coverage?.diff_generated_by_stage_111 === false ? [] : ['Stage 111 must not generate diff files']),
+    ...(envelope.diff_coverage?.execution_authorized === false ? [] : ['Stage 111 must not authorize execution']),
+    ...writableBoundaries.map((item) => `boundary assertion must remain false: ${item}`),
+    ...forbiddenMissing.map((item) => `forbidden boundary missing or not false: ${item}`),
+  ];
+  return {
+    pass: findings.length === 0,
+    checked: [
+      'local_diff_source_digest',
+      'changed_file_extraction',
+      'plan_manifest_expected_files',
+      'docs_code_scope_coverage',
+      'unexpected_file_detection',
+      'no_git_execution',
+      'read_only_boundary_assertions',
+    ],
+    findings,
+  };
+}
+
+export function runtimeDiffCoverageBoundaryAssertions() {
+  return {
+    diff_coverage_artifact: false,
+    diff_artifact_write: false,
+    sidecar_write: false,
+    state_directory_created: false,
+    command_execution: false,
+    check_execution: false,
+    test_execution: false,
+    verification_execution: false,
+    repair_execution: false,
+    formatting_execution: false,
+    code_generation: false,
+    runtime_action: false,
+    workflow_execution: false,
+    scheduler: false,
+    daemon: false,
+    retry: false,
+    git: false,
+    git_write: false,
+    commit: false,
+    pr: false,
+    push: false,
+    merge: false,
+    tag: false,
+    history_rewrite: false,
+    platform_api: false,
+    external_network: false,
+    model_invocation: false,
+    subagent: false,
+    mcp: false,
+    worktree: false,
+    business_source_write: false,
+  };
+}
+
+export function runtimeDiffCoverageDigestPayload(envelope) {
+  return {
+    stage: envelope.stage,
+    coverage_kind: envelope.coverage_kind,
+    source_diff: envelope.source_diff,
+    source_bindings: envelope.source_bindings,
+    diff_coverage: envelope.diff_coverage,
+    changed_files: envelope.changed_files,
+    expected_files: envelope.expected_files,
+    covered_expected_files: envelope.covered_expected_files,
+    missing_expected_files: envelope.missing_expected_files,
+    unexpected_files: envelope.unexpected_files,
+    docs_coverage: envelope.docs_coverage,
+    code_coverage: envelope.code_coverage,
+    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,
+    diff_coverage_invariants: envelope.diff_coverage_invariants,
+  };
+}
+
+export function digestDiffCoverage(value) {
+  return crypto.createHash('sha256').update(stableStringify(value)).digest('hex');
+}
+
+function parseChangedFiles(diffText) {
+  const files = [];
+  const lines = String(diffText || '').split(/\r?\n/);
+  for (const raw of lines) {
+    const line = raw.trim();
+    if (!line) continue;
+    const gitMatch = line.match(/^diff --git\s+(?:"?a\/(.+?)"?)\s+(?:"?b\/(.+?)"?)$/);
+    if (gitMatch) {
+      files.push(gitMatch[2] || gitMatch[1]);
+      continue;
+    }
+    const markerMatch = line.match(/^(?:---|\+\+\+)\s+(?:a\/|b\/)?(.+)$/);
+    if (markerMatch && markerMatch[1] !== '/dev/null') {
+      files.push(markerMatch[1]);
+      continue;
+    }
+    const renameMatch = line.match(/^rename (?:to|from)\s+(.+)$/);
+    if (renameMatch) {
+      files.push(renameMatch[1]);
+      continue;
+    }
+    const statMatch = line.match(/^(.+?)\s+\|\s+\d+/);
+    if (statMatch) {
+      files.push(statMatch[1]);
+      continue;
+    }
+    if (/^[\w./@+-]+\.(?:mjs|js|ts|tsx|json|md|yml|yaml|py|go|rs|java|css|scss|html)$/.test(line)) files.push(line);
+  }
+  return [...new Set(files.map(normalizeFilePath).filter(Boolean))].sort();
+}
+
+function expectedFilesFor(planActionManifest) {
+  const actionFiles = (planActionManifest.action_items || []).flatMap((item) => item.target_files || []);
+  const docsExpected = expectationFiles(planActionManifest.docs_expectations || []);
+  const codeExpected = expectationFiles(planActionManifest.code_expectations || []);
+  const expectedFiles = [...new Set([...actionFiles, ...docsExpected, ...codeExpected].map(normalizeFilePath).filter(Boolean))].sort();
+  return {
+    expected_files: expectedFiles,
+    docs_expected_files: [...new Set(docsExpected.map(normalizeFilePath).filter(Boolean))].sort(),
+    code_expected_files: [...new Set(codeExpected.map(normalizeFilePath).filter(Boolean))].sort(),
+  };
+}
+
+function expectationFiles(expectations) {
+  return expectations.flatMap((item) => extractPaths(item.expectation || item.title || item.file || ''));
+}
+
+function expectationCoverage(kind, expectedFiles, changedSet, expectations) {
+  const covered = expectedFiles.filter((file) => changedSet.has(file));
+  const missing = expectedFiles.filter((file) => !changedSet.has(file));
+  return {
+    kind,
+    expectation_count: expectations.length,
+    expected_files: expectedFiles,
+    covered_files: covered,
+    missing_files: missing,
+    coverage_complete: missing.length === 0,
+  };
+}
+
+function diffSafetyFindings(diffText) {
+  const text = String(diffText || '');
+  const findings = [];
+  if (!text.trim()) findings.push({ id: 'stage111-diff-empty', severity: 'blocker', reason: 'diff input is empty' });
+  if (Buffer.byteLength(text, 'utf8') > maxDiffBytes) findings.push({ id: 'stage111-diff-too-large', severity: 'blocker', reason: `diff input exceeds ${maxDiffBytes} bytes` });
+  if (/GIT binary patch|Binary files .* differ/i.test(text)) findings.push({ id: 'stage111-binary-diff', severity: 'blocker', reason: 'binary diff input is not supported by Stage 111 coverage parsing' });
+  return findings;
+}
+
+function pathSafetyFindings(files) {
+  return files.flatMap((file) => {
+    const findings = [];
+    if (isAbsolutePath(file)) findings.push({ id: `stage111-absolute-path-${slugify(file)}`, severity: 'blocker', reason: `absolute diff path is not allowed: ${file}` });
+    if (file.split('/').includes('..')) findings.push({ id: `stage111-parent-path-${slugify(file)}`, severity: 'blocker', reason: `parent traversal diff path is not allowed: ${file}` });
+    if (/[\\]/.test(file)) findings.push({ id: `stage111-backslash-path-${slugify(file)}`, severity: 'blocker', reason: `backslash diff path is not allowed: ${file}` });
+    return findings;
+  });
+}
+
+function normalizeFilePath(value) {
+  const raw = String(value || '').trim().replace(/^"|"$/g, '');
+  if (!raw || raw === '/dev/null') return '';
+  return raw.replace(/^\.\//, '').replace(/^[ab]\//, '').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 [...new Set([...backtickPathMatches, ...barePathMatches].map(normalizeFilePath).filter(Boolean))].sort();
+}
+
+function isAbsolutePath(file) {
+  return /^\/|^[A-Za-z]:[\\/]/.test(String(file || ''));
+}
+
+function slugify(value) {
+  const slug = String(value || '').toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '').slice(0, 48);
+  return slug || 'path';
+}
+
+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);
+}