@ryuenn3123/agentic-senior-core 3.0.50 → 4.0.1

package/scripts/audit-release-bundle.mjs

@@ -0,0 +1,170 @@
+#!/usr/bin/env node
+// @ts-check
+
+/**
+ * audit-release-bundle.mjs
+ *
+ * Phase 5 Task 5.4 integrity gate. Validates that
+ * benchmarks/results/release-bundle-4.0.0.json exists, references real source
+ * artifacts, and that each recorded SHA-256 hash still matches the current
+ * file content. Wired into npm run validate.
+ */
+
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const SCRIPT_FILE_PATH = fileURLToPath(import.meta.url);
+const REPOSITORY_ROOT = resolve(dirname(SCRIPT_FILE_PATH), '..');
+const ARGS = new Set(process.argv.slice(2));
+const JSON_ONLY = ARGS.has('--json');
+
+const DEFAULT_BUNDLE_PATH = join(REPOSITORY_ROOT, 'benchmarks', 'results', 'release-bundle-4.0.0.json');
+
+function sha256Hex(buffer) {
+  // Normalize CRLF -> LF before hashing so bundle integrity is reproducible
+  // across platforms (Windows working tree may be CRLF; CI checkouts are LF).
+  const normalized = buffer.toString('utf8').replace(/\r\n/g, '\n');
+  const hash = createHash('sha256');
+  hash.update(normalized, 'utf8');
+  return hash.digest('hex');
+}
+
+export function runReleaseBundleAudit(options = {}) {
+  const rootDir = options.rootDir ? resolve(String(options.rootDir)) : REPOSITORY_ROOT;
+  const bundlePath = options.bundlePath ? resolve(String(options.bundlePath)) : DEFAULT_BUNDLE_PATH;
+  const violations = [];
+
+  if (!existsSync(bundlePath)) {
+    violations.push({
+      kind: 'bundle.missing',
+      detail: `Release bundle is missing at ${bundlePath}. Run scripts/build-release-benchmark-bundle.mjs to regenerate.`,
+    });
+    return finalizeReport(violations, { bundlePath, artifactCount: 0 });
+  }
+
+  let parsed;
+  try {
+    parsed = JSON.parse(readFileSync(bundlePath, 'utf8'));
+  } catch (error) {
+    violations.push({
+      kind: 'bundle.invalid-json',
+      detail: `Release bundle is not valid JSON: ${error?.message || error}`,
+    });
+    return finalizeReport(violations, { bundlePath, artifactCount: 0 });
+  }
+
+  if (!Array.isArray(parsed.artifacts) || parsed.artifacts.length === 0) {
+    violations.push({
+      kind: 'bundle.empty',
+      detail: 'Release bundle artifacts array must be non-empty.',
+    });
+    return finalizeReport(violations, { bundlePath, artifactCount: 0 });
+  }
+
+  if (parsed.integrity?.hash_algorithm !== 'SHA-256') {
+    violations.push({
+      kind: 'bundle.unexpected-hash-algorithm',
+      detail: `Expected hash_algorithm "SHA-256", got "${parsed.integrity?.hash_algorithm}".`,
+    });
+  }
+
+  if (parsed.release_status !== 'release-candidate-unpublished' && parsed.release_status !== 'released') {
+    violations.push({
+      kind: 'bundle.invalid-release-status',
+      detail: `release_status must be either "release-candidate-unpublished" or "released"; got "${parsed.release_status}".`,
+    });
+  }
+
+  for (const artifact of parsed.artifacts) {
+    if (!artifact.relative_path || typeof artifact.relative_path !== 'string') {
+      violations.push({
+        kind: 'artifact.missing-relative-path',
+        detail: `Artifact "${artifact.artifact_id}" missing relative_path.`,
+      });
+      continue;
+    }
+
+    const absolutePath = join(rootDir, artifact.relative_path);
+    if (!existsSync(absolutePath)) {
+      violations.push({
+        kind: 'artifact.missing-file',
+        detail: `Artifact "${artifact.artifact_id}" references missing file at ${artifact.relative_path}.`,
+      });
+      continue;
+    }
+
+    if (!artifact.sha256 || typeof artifact.sha256 !== 'string') {
+      violations.push({
+        kind: 'artifact.missing-sha256',
+        detail: `Artifact "${artifact.artifact_id}" missing sha256 hash.`,
+      });
+      continue;
+    }
+
+    const currentHash = sha256Hex(readFileSync(absolutePath));
+    if (currentHash !== artifact.sha256) {
+      violations.push({
+        kind: 'artifact.hash-mismatch',
+        detail: `Artifact "${artifact.artifact_id}" sha256 drift: bundle records ${artifact.sha256}, current file is ${currentHash}. Regenerate the bundle via scripts/build-release-benchmark-bundle.mjs.`,
+      });
+    }
+  }
+
+  return finalizeReport(violations, {
+    bundlePath,
+    artifactCount: parsed.artifacts.length,
+    releaseTarget: parsed.release_target || null,
+    releaseStatus: parsed.release_status || null,
+  });
+}
+
+function finalizeReport(violations, extras) {
+  return {
+    auditName: 'audit-release-bundle',
+    reportVersion: '1.0.0',
+    generatedAt: new Date().toISOString(),
+    violationCount: violations.length,
+    passed: violations.length === 0,
+    violations,
+    ...extras,
+  };
+}
+
+function main() {
+  const report = runReleaseBundleAudit();
+
+  if (JSON_ONLY) {
+    process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+    process.exit(report.passed ? 0 : 1);
+  }
+
+  console.log('===============================================');
+  console.log('  audit:release-bundle');
+  console.log('===============================================');
+  console.log(`  Bundle path:      ${report.bundlePath}`);
+  console.log(`  Artifact count:   ${report.artifactCount}`);
+  console.log(`  Release target:   ${report.releaseTarget || '(missing)'}`);
+  console.log(`  Release status:   ${report.releaseStatus || '(missing)'}`);
+  console.log('');
+
+  if (report.passed) {
+    console.log('  Release bundle is intact. All artifact hashes match.');
+    process.stderr.write(`AUDIT_RELEASE_BUNDLE_REPORT: ${JSON.stringify({ passed: true, artifactCount: report.artifactCount })}\n`);
+    process.exit(0);
+  }
+
+  console.log('  Violations:');
+  for (const violation of report.violations) {
+    console.log(`    [${violation.kind}] ${violation.detail}`);
+  }
+  console.log('');
+  console.log(`  ${report.violationCount} violation(s) found.`);
+  process.stderr.write(`AUDIT_RELEASE_BUNDLE_REPORT: ${JSON.stringify({ passed: false, violationCount: report.violationCount })}\n`);
+  process.exit(1);
+}
+
+if (process.argv[1] && (import.meta.url === `file://${process.argv[1].replace(/\\/g, '/')}` || process.argv[1].endsWith('audit-release-bundle.mjs'))) {
+  main();
+}

package/scripts/audit-rule-id-uniqueness.mjs

@@ -0,0 +1,313 @@
+#!/usr/bin/env node
+// @ts-check
+
+/**
+ * audit-rule-id-uniqueness.mjs
+ *
+ * Phase 1 GATE B citability gate. Checks every migrated rule file under
+ * `.agent-context/rules/` for:
+ *
+ *   1. YAML frontmatter parses and contains required keys (id_prefix, domain,
+ *      priority, scope, applies_to, keywords).
+ *   2. Section IDs match the file's locked id_prefix and are unique within
+ *      the file.
+ *   3. Every `[REF:<PREFIX>-NNN]` mention across the rules pack, prompts/,
+ *      and review-checklists/ resolves to a real section ID.
+ *   4. Every `related:` entry in any rule's frontmatter resolves to a real
+ *      section ID.
+ *   5. No ambiguous prose references (`see above`, `as noted earlier`,
+ *      `the next section`, etc.) survive in any rule body.
+ *
+ * Files that have not been migrated yet (no YAML frontmatter) are skipped
+ * with a notice. The audit only enforces shape on migrated files.
+ *
+ * Usage:
+ *   node scripts/audit-rule-id-uniqueness.mjs            (human + report line)
+ *   node scripts/audit-rule-id-uniqueness.mjs --json     (JSON only)
+ *
+ * Exit codes:
+ *   0 — clean
+ *   1 — at least one violation
+ */
+
+import { readdirSync, readFileSync, existsSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parse as parseYaml } from 'yaml';
+
+const SCRIPT_FILE_PATH = fileURLToPath(import.meta.url);
+const REPOSITORY_ROOT = resolve(dirname(SCRIPT_FILE_PATH), '..');
+const RULES_DIRECTORY = join(REPOSITORY_ROOT, '.agent-context', 'rules');
+const PROMPTS_DIRECTORY = join(REPOSITORY_ROOT, '.agent-context', 'prompts');
+const REVIEW_CHECKLISTS_DIRECTORY = join(REPOSITORY_ROOT, '.agent-context', 'review-checklists');
+
+const ARGS = new Set(process.argv.slice(2));
+const JSON_ONLY = ARGS.has('--json');
+
+const RULE_ID_PATTERN = /\b([A-Z]+)-(\d{3,4})(?:-([A-Z]))?\b/;
+const REF_PATTERN = /\[REF:([A-Z]+-\d{3,4}(?:-[A-Z])?)\]/g;
+const SECTION_HEADING_PATTERN = /^##\s+([A-Z]+-\d{3,4}(?:-[A-Z])?):\s+(.+)$/;
+const REQUIRED_FRONTMATTER_KEYS = ['id_prefix', 'domain', 'priority', 'scope', 'applies_to', 'keywords'];
+const FRONTMATTER_PATTERN = /^---\n([\s\S]*?)\n---\n/;
+
+const AMBIGUOUS_PROSE_REFERENCE_PATTERNS = [
+  /\bsee above\b/i,
+  /\bsee below\b/i,
+  /\bas noted earlier\b/i,
+  /\bas noted above\b/i,
+  /\bas mentioned earlier\b/i,
+  /\bas mentioned above\b/i,
+  /\bin the previous section\b/i,
+  /\bin the next section\b/i,
+  /\bthe next section\b/i,
+  /\bthe previous section\b/i,
+  /\bsee earlier\b/i,
+  /\bsee later\b/i,
+];
+
+function listRuleFiles() {
+  return readdirSync(RULES_DIRECTORY)
+    .filter((filename) => filename.endsWith('.md') && !filename.endsWith('.candidate.md'))
+    .sort()
+    .map((filename) => ({ filename, absolutePath: join(RULES_DIRECTORY, filename) }));
+}
+
+function parseFrontmatter(sourceText) {
+  const match = sourceText.match(FRONTMATTER_PATTERN);
+  if (!match) return null;
+  try {
+    return parseYaml(match[1]);
+  } catch {
+    return null;
+  }
+}
+
+function extractSectionIds(sourceText) {
+  const sectionIds = [];
+  for (const line of sourceText.split(/\r?\n/)) {
+    const match = line.match(SECTION_HEADING_PATTERN);
+    if (match) {
+      sectionIds.push({ id: match[1], title: match[2].trim() });
+    }
+  }
+  return sectionIds;
+}
+
+function findAmbiguousProseReferences(sourceText) {
+  const findings = [];
+  const lines = sourceText.split(/\r?\n/);
+  for (let lineIndex = 0; lineIndex < lines.length; lineIndex += 1) {
+    for (const pattern of AMBIGUOUS_PROSE_REFERENCE_PATTERNS) {
+      if (pattern.test(lines[lineIndex])) {
+        findings.push({ lineNumber: lineIndex + 1, snippet: lines[lineIndex].trim() });
+        break;
+      }
+    }
+  }
+  return findings;
+}
+
+function listMarkdownFilesIn(absoluteDirectoryPath) {
+  if (!existsSync(absoluteDirectoryPath)) return [];
+  return readdirSync(absoluteDirectoryPath)
+    .filter((filename) => filename.endsWith('.md'))
+    .map((filename) => join(absoluteDirectoryPath, filename));
+}
+
+function collectAllRefMentions() {
+  const mentions = [];
+  const candidatePaths = [
+    ...listRuleFiles().map((entry) => entry.absolutePath),
+    ...listMarkdownFilesIn(PROMPTS_DIRECTORY),
+    ...listMarkdownFilesIn(REVIEW_CHECKLISTS_DIRECTORY),
+  ];
+  for (const filePath of candidatePaths) {
+    const sourceText = readFileSync(filePath, 'utf8');
+    for (const match of sourceText.matchAll(REF_PATTERN)) {
+      mentions.push({ filePath, refId: match[1] });
+    }
+  }
+  return mentions;
+}
+
+export function runRuleIdUniquenessAudit() {
+  const violations = [];
+  const ruleFiles = listRuleFiles();
+  const allKnownSectionIds = new Set();
+  const migratedFileCount = { migrated: 0, skipped: 0 };
+  const perFile = [];
+
+  for (const { filename, absolutePath } of ruleFiles) {
+    const sourceText = readFileSync(absolutePath, 'utf8');
+    const frontmatter = parseFrontmatter(sourceText);
+    if (!frontmatter) {
+      migratedFileCount.skipped += 1;
+      perFile.push({ filename, status: 'skipped', reason: 'no-yaml-frontmatter' });
+      continue;
+    }
+
+    migratedFileCount.migrated += 1;
+
+    for (const requiredKey of REQUIRED_FRONTMATTER_KEYS) {
+      if (!(requiredKey in frontmatter)) {
+        violations.push({
+          file: filename,
+          kind: 'frontmatter.missing-key',
+          detail: `frontmatter is missing required key: ${requiredKey}`,
+        });
+      }
+    }
+
+    const idPrefix = frontmatter.id_prefix;
+    if (typeof idPrefix !== 'string' || idPrefix.length === 0) {
+      violations.push({ file: filename, kind: 'frontmatter.invalid-id-prefix', detail: 'id_prefix must be a non-empty string' });
+      perFile.push({ filename, status: 'failed', reason: 'invalid-id-prefix' });
+      continue;
+    }
+
+    const sections = extractSectionIds(sourceText);
+    const seenIdsInFile = new Set();
+    for (const section of sections) {
+      const idMatch = section.id.match(RULE_ID_PATTERN);
+      if (!idMatch || idMatch[1] !== idPrefix) {
+        violations.push({
+          file: filename,
+          kind: 'id.prefix-mismatch',
+          detail: `section id '${section.id}' does not match the file's id_prefix '${idPrefix}'`,
+        });
+        continue;
+      }
+      if (seenIdsInFile.has(section.id)) {
+        violations.push({
+          file: filename,
+          kind: 'id.duplicate',
+          detail: `section id '${section.id}' is reused within the same file`,
+        });
+      }
+      seenIdsInFile.add(section.id);
+      allKnownSectionIds.add(section.id);
+    }
+
+    const ambiguousProse = findAmbiguousProseReferences(sourceText);
+    for (const finding of ambiguousProse) {
+      violations.push({
+        file: filename,
+        kind: 'prose.ambiguous-reference',
+        detail: `line ${finding.lineNumber}: ${finding.snippet}`,
+      });
+    }
+
+    perFile.push({
+      filename,
+      status: 'audited',
+      idPrefix,
+      sectionCount: sections.length,
+      ambiguousProseCount: ambiguousProse.length,
+      knownSectionIdsInFile: sections.map((section) => section.id),
+      relatedRefs: (frontmatter.related && typeof frontmatter.related === 'object' && !Array.isArray(frontmatter.related))
+        ? frontmatter.related
+        : null,
+    });
+  }
+
+  for (const fileEntry of perFile) {
+    if (fileEntry.status !== 'audited') continue;
+    if (!fileEntry.relatedRefs) continue;
+    for (const [parentId, relatedList] of Object.entries(fileEntry.relatedRefs)) {
+      if (!fileEntry.knownSectionIdsInFile.includes(parentId)) {
+        violations.push({
+          file: fileEntry.filename,
+          kind: 'related.parent-missing',
+          detail: `related map key '${parentId}' is not a section in this file`,
+        });
+      }
+      if (!Array.isArray(relatedList)) {
+        violations.push({
+          file: fileEntry.filename,
+          kind: 'related.malformed',
+          detail: `related[${parentId}] must be an array of <PREFIX>-NNN ids`,
+        });
+        continue;
+      }
+      for (const relatedId of relatedList) {
+        if (typeof relatedId !== 'string' || !RULE_ID_PATTERN.test(relatedId)) {
+          violations.push({
+            file: fileEntry.filename,
+            kind: 'related.malformed',
+            detail: `related[${parentId}] entry '${relatedId}' is not a valid <PREFIX>-NNN id`,
+          });
+          continue;
+        }
+        if (!allKnownSectionIds.has(relatedId)) {
+          violations.push({
+            file: fileEntry.filename,
+            kind: 'related.unresolved',
+            detail: `related[${parentId}] entry '${relatedId}' does not resolve to any section in the rules pack`,
+          });
+        }
+      }
+    }
+  }
+
+  const refMentions = collectAllRefMentions();
+  for (const mention of refMentions) {
+    if (!allKnownSectionIds.has(mention.refId)) {
+      violations.push({
+        file: mention.filePath.replace(REPOSITORY_ROOT, '').replace(/^[\\/]+/, ''),
+        kind: 'ref.unresolved',
+        detail: `[REF:${mention.refId}] does not resolve to any section in the rules pack`,
+      });
+    }
+  }
+
+  return {
+    auditName: 'audit-rule-id-uniqueness',
+    reportVersion: '1.0.0',
+    generatedAt: new Date().toISOString(),
+    migratedFileCount: migratedFileCount.migrated,
+    skippedFileCount: migratedFileCount.skipped,
+    knownSectionIdCount: allKnownSectionIds.size,
+    refMentionCount: refMentions.length,
+    perFile,
+    violationCount: violations.length,
+    violations,
+    passed: violations.length === 0,
+  };
+}
+
+function main() {
+  const report = runRuleIdUniquenessAudit();
+
+  if (JSON_ONLY) {
+    process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+    process.exit(report.passed ? 0 : 1);
+  }
+
+  console.log('===============================================');
+  console.log('  audit:rule-id-uniqueness');
+  console.log('===============================================');
+  console.log(`  Migrated rule files: ${report.migratedFileCount} of ${report.migratedFileCount + report.skippedFileCount} scanned`);
+  console.log(`  Pre-migration files: ${report.skippedFileCount} (no YAML frontmatter, skipped)`);
+  console.log(`  Known section IDs:   ${report.knownSectionIdCount}`);
+  console.log(`  [REF:...] mentions:  ${report.refMentionCount}`);
+  console.log('');
+
+  if (report.violationCount === 0) {
+    console.log('  All migrated files clean. No prefix mismatches, duplicates, ambiguous prose references, or unresolved [REF:] / related: links.');
+    process.stderr.write(`AUDIT_RULE_ID_REPORT: ${JSON.stringify({ passed: true, ...{ migratedFileCount: report.migratedFileCount, knownSectionIdCount: report.knownSectionIdCount, refMentionCount: report.refMentionCount } })}\n`);
+    process.exit(0);
+  }
+
+  console.log('  Violations:');
+  for (const violation of report.violations) {
+    console.log(`    [${violation.kind}] ${violation.file}: ${violation.detail}`);
+  }
+  console.log('');
+  console.log(`  ${report.violationCount} violation(s) found. Phase 1 GATE B requires zero.`);
+  process.stderr.write(`AUDIT_RULE_ID_REPORT: ${JSON.stringify({ passed: false, violationCount: report.violationCount, kinds: [...new Set(report.violations.map((v) => v.kind))] })}\n`);
+  process.exit(1);
+}
+
+if (import.meta.url === `file://${process.argv[1].replace(/\\/g, '/')}` || process.argv[1].endsWith('audit-rule-id-uniqueness.mjs')) {
+  main();
+}

package/scripts/benchmark-evidence-bundle.mjs

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 
+// @file-size-exception: Pre-existing benchmark bundler (sequential per-section assembly); planned for split in Phase 1.
 /**
  * benchmark-evidence-bundle.mjs
  *

package/scripts/build-release-benchmark-bundle.mjs

@@ -0,0 +1,204 @@
+#!/usr/bin/env node
+// @ts-check
+
+/**
+ * build-release-benchmark-bundle.mjs
+ *
+ * Phase 5 Task 5.4. Reads the locked benchmark artifacts produced in Phases
+ * 0-3 and emits a single release bundle that references each artifact by
+ * SHA-256 hash plus a non-marketing summary section. The script never
+ * regenerates Phase 0-3 numbers; it only references and hashes them.
+ */
+
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const SCRIPT_FILE_PATH = fileURLToPath(import.meta.url);
+const REPOSITORY_ROOT = resolve(dirname(SCRIPT_FILE_PATH), '..');
+const ARGS = new Set(process.argv.slice(2));
+const JSON_ONLY = ARGS.has('--json');
+
+const SOURCE_ARTIFACTS = [
+  {
+    artifactId: 'phase-0-baseline',
+    relativePath: 'benchmarks/results/baseline-2026-05-16.json',
+    role: 'token-baseline',
+    description: 'Phase 0 token-usage baseline measured across providers using free count-tokens APIs and tiktoken estimates.',
+  },
+  {
+    artifactId: 'phase-2-cache',
+    relativePath: 'benchmarks/results/cache-phase-2-2026-05-16.json',
+    role: 'cache-simulation',
+    description: 'Phase 2 offline warm-cache simulation. Direct provider API integration mode; see docs/architecture/decisions-foundation.md D4 for the per-tool scope matrix.',
+  },
+  {
+    artifactId: 'phase-3-anti-halu',
+    relativePath: 'benchmarks/results/anti-halu-phase-3-2026-05-16.json',
+    role: 'anti-halu-benchmark',
+    description: 'Phase 3 offline provider-free anti-halu benchmark.',
+  },
+  {
+    artifactId: 'scorecard-2026-05-16',
+    relativePath: 'benchmarks/results/scorecard-2026-05-16.json',
+    role: 'supply-chain-snapshot',
+    description: 'Phase 5 Task 5.3 supply-chain snapshot. Scorecard CLI was not installed locally; fallback signals are documented honestly.',
+  },
+];
+
+function sha256Hex(buffer) {
+  // Normalize CRLF -> LF before hashing so bundle integrity is reproducible
+  // across platforms (Windows working tree may be CRLF; CI checkouts are LF).
+  const normalized = buffer.toString('utf8').replace(/\r\n/g, '\n');
+  const hash = createHash('sha256');
+  hash.update(normalized, 'utf8');
+  return hash.digest('hex');
+}
+
+function loadArtifact(rootDir, descriptor) {
+  const absolutePath = join(rootDir, descriptor.relativePath);
+  if (!existsSync(absolutePath)) {
+    return {
+      ...descriptor,
+      status: 'missing',
+      sha256: null,
+      sizeBytes: 0,
+      summary: null,
+    };
+  }
+  const content = readFileSync(absolutePath);
+  const sha = sha256Hex(content);
+  let summary = null;
+  try {
+    const parsed = JSON.parse(content.toString('utf8'));
+    summary = summarizeArtifact(descriptor.role, parsed);
+  } catch {
+    summary = { error: 'artifact is not valid JSON' };
+  }
+  return {
+    ...descriptor,
+    status: 'present',
+    sha256: sha,
+    sizeBytes: content.length,
+    summary,
+  };
+}
+
+function summarizeArtifact(role, parsed) {
+  if (!parsed || typeof parsed !== 'object') {
+    return null;
+  }
+  if (role === 'token-baseline') {
+    return {
+      report_version: parsed.report_version || null,
+      generated_at: parsed.generated_at || null,
+      provider_count: Array.isArray(parsed.providers) ? parsed.providers.length : null,
+    };
+  }
+  if (role === 'cache-simulation') {
+    const anthropicWithLoaded = Array.isArray(parsed.summary)
+      ? parsed.summary.find((row) => row.provider === 'anthropic' && row.scenario === 'with_loaded_rules')
+      : null;
+    return {
+      report_version: parsed.report_version || null,
+      integration_mode: parsed.integration_mode || null,
+      fixture_count: parsed.fixture_count || null,
+      provider_count: parsed.provider_count || null,
+      anthropic_with_loaded_avg_total_input: anthropicWithLoaded?.average_total_input_tokens ?? null,
+      anthropic_with_loaded_avg_warm_read: anthropicWithLoaded?.average_warm_read_effective_tokens ?? null,
+      scope_caveat_present: typeof parsed.scope_caveat === 'string' && parsed.scope_caveat.length > 0,
+    };
+  }
+  if (role === 'anti-halu-benchmark') {
+    return {
+      reportVersion: parsed.reportVersion || null,
+      generatedAt: parsed.generatedAt || null,
+      passRatePercent: parsed.passRatePercent ?? null,
+      citationValidityRatePercent: parsed.citationValidityRatePercent ?? null,
+      fixtureCount: parsed.fixtureCount ?? null,
+      passedCount: parsed.passedCount ?? null,
+      failedCount: parsed.failedCount ?? null,
+    };
+  }
+  if (role === 'supply-chain-snapshot') {
+    return {
+      report_version: parsed.report_version || null,
+      status: parsed.status || null,
+      npm_audit_full: parsed.fallback_signals?.npm_audit_full || null,
+      lockfile_consistent: parsed.fallback_signals?.lockfile_consistent ?? null,
+      runtime_dependencies_count: parsed.fallback_signals?.runtime_dependencies_count ?? null,
+    };
+  }
+  return null;
+}
+
+export function buildReleaseBenchmarkBundle(options = {}) {
+  const rootDir = options.rootDir ? resolve(String(options.rootDir)) : REPOSITORY_ROOT;
+  const artifacts = SOURCE_ARTIFACTS.map((descriptor) => loadArtifact(rootDir, descriptor));
+  const missingArtifacts = artifacts.filter((artifact) => artifact.status === 'missing');
+
+  return {
+    bundle_version: '1.0.0',
+    release_target: '4.0.0',
+    release_status: 'released',
+    generated_at: new Date().toISOString(),
+    description: 'Phase 5 release benchmark bundle. References Phase 0-3 locked artifacts plus the Phase 5 supply-chain snapshot. No artifact is regenerated by this bundle. Artifact integrity is verified by SHA-256 hash via scripts/audit-release-bundle.mjs.',
+    sources: {
+      research_foundation: 'docs/architecture/decisions-foundation.md',
+      d4_caching_scope_matrix: 'docs/architecture/decisions-foundation.md#d4',
+      caching_reporting_format: 'docs/benchmark-reference.md',
+      phase_2_outcome: 'docs/archive/phase-2-outcome.md',
+      phase_3_outcome: 'docs/archive/phase-3-outcome.md',
+      phase_5_plan: 'docs/archive/phase-5-hardening.md',
+    },
+    integrity: {
+      hash_algorithm: 'SHA-256',
+      missing_artifact_count: missingArtifacts.length,
+      missing_artifacts: missingArtifacts.map((artifact) => artifact.relativePath),
+    },
+    artifacts: artifacts.map((artifact) => ({
+      artifact_id: artifact.artifactId,
+      role: artifact.role,
+      relative_path: artifact.relativePath,
+      description: artifact.description,
+      status: artifact.status,
+      sha256: artifact.sha256,
+      size_bytes: artifact.sizeBytes,
+      summary: artifact.summary,
+    })),
+  };
+}
+
+function main() {
+  const bundle = buildReleaseBenchmarkBundle();
+
+  if (bundle.integrity.missing_artifact_count > 0) {
+    process.stderr.write(`build-release-benchmark-bundle: ${bundle.integrity.missing_artifact_count} artifact(s) missing: ${bundle.integrity.missing_artifacts.join(', ')}\n`);
+    process.exit(1);
+  }
+
+  const outputPath = join(REPOSITORY_ROOT, 'benchmarks', 'results', 'release-bundle-4.0.0.json');
+  writeFileSync(outputPath, `${JSON.stringify(bundle, null, 2)}\n`, 'utf8');
+
+  if (JSON_ONLY) {
+    process.stdout.write(`${JSON.stringify(bundle, null, 2)}\n`);
+    process.exit(0);
+  }
+
+  console.log('===============================================');
+  console.log('  build-release-benchmark-bundle');
+  console.log('===============================================');
+  console.log(`  Release target:        ${bundle.release_target}`);
+  console.log(`  Release status:        ${bundle.release_status}`);
+  console.log(`  Artifact count:        ${bundle.artifacts.length}`);
+  console.log(`  Missing artifacts:     ${bundle.integrity.missing_artifact_count}`);
+  console.log(`  Output:                benchmarks/results/release-bundle-4.0.0.json`);
+  console.log('');
+  console.log('  Bundle written. Run scripts/audit-release-bundle.mjs to verify integrity before release.');
+  process.exit(0);
+}
+
+if (process.argv[1] && (import.meta.url === `file://${process.argv[1].replace(/\\/g, '/')}` || process.argv[1].endsWith('build-release-benchmark-bundle.mjs'))) {
+  main();
+}