pumuki 6.3.7

package/scripts/build-phase8-ready-handoff-summary.sh

@@ -0,0 +1,66 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+OUT_DIR="${1:-.audit-reports/phase5-latest}"
+SUMMARY_PATH="${OUT_DIR}/phase8-ready-handoff-summary.md"
+HANDOFF_PATH="${OUT_DIR}/phase5-external-handoff.md"
+ESCALATION_DOC="docs/validation/consumer-startup-escalation-handoff-latest.md"
+
+echo "[phase8-ready-handoff] out_dir=${OUT_DIR}"
+
+if ! npm run validation:phase5-latest:ready-check >/tmp/phase8-ready-check.log 2>&1; then
+  cat /tmp/phase8-ready-check.log
+  echo "[phase8-ready-handoff] chain is not READY; summary not generated" >&2
+  exit 1
+fi
+
+if [[ ! -f "${HANDOFF_PATH}" ]]; then
+  echo "[phase8-ready-handoff] missing handoff report: ${HANDOFF_PATH}" >&2
+  exit 1
+fi
+
+if [[ ! -f "${ESCALATION_DOC}" ]]; then
+  echo "[phase8-ready-handoff] missing escalation doc: ${ESCALATION_DOC}" >&2
+  exit 1
+fi
+
+mkdir -p "${OUT_DIR}"
+
+RUN_URLS="$(rg -o 'https://github.com/[^[:space:]]+/actions/runs/[0-9]+' "${HANDOFF_PATH}" | head -n 5 || true)"
+CHECKSUM_LINE="$(rg -n "sha256:" "${ESCALATION_DOC}" | head -n 1 | sed 's/^[0-9]*://')"
+GENERATED_AT="$(date -u +"%Y-%m-%dT%H:%M:%SZ")"
+
+{
+  echo "# Phase 8 Ready Handoff Summary"
+  echo
+  echo "- generated_at: ${GENERATED_AT}"
+  echo "- out_dir: \`${OUT_DIR}\`"
+  echo "- chain_status: \`READY\`"
+  echo
+  echo "## Publication Checklist"
+  echo
+  echo "- [ ] Confirm reports are \`READY\`: blockers, closure-status, external-handoff, startup-unblock."
+  echo "- [ ] Publish final external handoff artifacts/URLs."
+  echo "- [ ] Update \`docs/REFRACTOR_PROGRESS.md\`: mark \`P8-3\` ✅ and set \`P8-4\` 🚧."
+  echo "- [ ] Close \`P8-4\` once URLs are attached and handoff is complete."
+  echo
+  echo "## Latest Run URLs"
+  echo
+  if [[ -n "${RUN_URLS}" ]]; then
+    while IFS= read -r url; do
+      [[ -n "${url}" ]] && echo "- ${url}"
+    done <<< "${RUN_URLS}"
+  else
+    echo "- <missing run URLs in ${HANDOFF_PATH}>"
+  fi
+  echo
+  echo "## Escalation Bundle Checksum"
+  echo
+  if [[ -n "${CHECKSUM_LINE}" ]]; then
+    echo "- ${CHECKSUM_LINE}"
+  else
+    echo "- <missing checksum line in ${ESCALATION_DOC}>"
+  fi
+} > "${SUMMARY_PATH}"
+
+echo "[phase8-ready-handoff] generated ${SUMMARY_PATH}"

package/scripts/check-consumer-ci-auth.ts

@@ -0,0 +1,64 @@
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import {
+  buildConsumerCiAuthMarkdown,
+  parseAuthScopes,
+  parseConsumerCiAuthArgs,
+  REQUIRED_CONSUMER_CI_AUTH_SCOPES,
+  tryRunGh,
+  tryRunGhJson,
+  type RepoActionsPermissionsResponse,
+  type UserActionsBillingResponse,
+} from './consumer-ci-auth-check-lib';
+
+const main = (): number => {
+  const options = parseConsumerCiAuthArgs(process.argv.slice(2));
+  const owner = options.repo.split('/')[0]?.trim();
+
+  if (!owner) {
+    throw new Error('Invalid repo value. Expected owner/repo format.');
+  }
+
+  const authStatus = tryRunGh(['auth', 'status']);
+  const scopes = authStatus.ok ? parseAuthScopes(authStatus.output ?? '') : [];
+  const missingScopes = REQUIRED_CONSUMER_CI_AUTH_SCOPES.filter(
+    (scope) => !scopes.includes(scope)
+  );
+
+  const actionsPermissions = tryRunGhJson<RepoActionsPermissionsResponse>([
+    'api',
+    `repos/${options.repo}/actions/permissions`,
+  ]);
+
+  const billing = tryRunGhJson<UserActionsBillingResponse>([
+    'api',
+    `users/${owner}/settings/billing/actions`,
+  ]);
+
+  const verdict: 'READY' | 'BLOCKED' =
+    authStatus.ok && missingScopes.length === 0 && actionsPermissions.ok
+      ? 'READY'
+      : 'BLOCKED';
+
+  const markdown = buildConsumerCiAuthMarkdown({
+    options,
+    authStatus,
+    scopes,
+    missingScopes,
+    actionsPermissions,
+    billing,
+    verdict,
+  });
+
+  const outputPath = resolve(process.cwd(), options.outFile);
+  mkdirSync(dirname(outputPath), { recursive: true });
+  writeFileSync(outputPath, markdown, 'utf8');
+
+  process.stdout.write(
+    `consumer CI auth check report generated at ${outputPath} (verdict=${verdict})\n`
+  );
+
+  return verdict === 'READY' ? 0 : 1;
+};
+
+process.exitCode = main();

package/scripts/check-package-manifest.ts

@@ -0,0 +1,54 @@
+import { spawnSync } from 'node:child_process';
+import { inspectPackageManifestPaths } from './package-manifest-lib';
+
+type PackFile = {
+  path: string;
+};
+
+type PackPayload = {
+  id: string;
+  files: PackFile[];
+};
+
+const runPackDryRun = (): PackPayload => {
+  const result = spawnSync('npm', ['pack', '--json', '--dry-run'], {
+    encoding: 'utf8',
+  });
+
+  if (typeof result.status !== 'number' || result.status !== 0) {
+    throw new Error(`npm pack --json --dry-run failed:\n${result.stdout ?? ''}\n${result.stderr ?? ''}`);
+  }
+
+  const parsed = JSON.parse(result.stdout) as PackPayload[];
+  if (!Array.isArray(parsed) || parsed.length === 0) {
+    throw new Error('npm pack --json --dry-run returned an empty payload');
+  }
+  const payload = parsed[0];
+  if (!payload || !Array.isArray(payload.files)) {
+    throw new Error('npm pack --json --dry-run returned an invalid payload');
+  }
+  return payload;
+};
+
+const main = (): void => {
+  const payload = runPackDryRun();
+  const filePaths = payload.files.map((file) => file.path);
+  const report = inspectPackageManifestPaths(filePaths);
+
+  if (report.missingRequired.length > 0) {
+    throw new Error(
+      `Package manifest is missing required paths:\n- ${report.missingRequired.join('\n- ')}`
+    );
+  }
+
+  if (report.forbiddenMatches.length > 0) {
+    throw new Error(
+      `Package manifest includes forbidden paths:\n- ${report.forbiddenMatches.join('\n- ')}`
+    );
+  }
+
+  console.log(`package manifest check passed for ${payload.id}`);
+  console.log(`files scanned: ${filePaths.length}`);
+};
+
+main();

package/scripts/check-phase5-escalation-ready-to-submit.sh

@@ -0,0 +1,74 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+OUT_DIR="${1:-.audit-reports/phase5-latest}"
+HANDOFF_FILE="docs/validation/consumer-startup-escalation-handoff-latest.md"
+PAYLOAD_FILE="${OUT_DIR}/github-support-portal-payload.txt"
+BUNDLE_FILE="${OUT_DIR}/consumer-startup-escalation-bundle-latest.tgz"
+
+if [[ ! -f "${HANDOFF_FILE}" ]]; then
+  echo "[phase5-escalation-ready] missing handoff file: ${HANDOFF_FILE}" >&2
+  exit 1
+fi
+
+for file in \
+  "${OUT_DIR}/consumer-ci-auth-check.md" \
+  "${OUT_DIR}/consumer-startup-failure-support-bundle.md" \
+  "${OUT_DIR}/consumer-startup-unblock-status.md" \
+  "${OUT_DIR}/consumer-support-ticket-draft.md" \
+  "${OUT_DIR}/phase5-external-handoff.md" \
+  "${BUNDLE_FILE}"
+do
+  if [[ ! -f "${file}" ]]; then
+    echo "[phase5-escalation-ready] missing required artifact: ${file}" >&2
+    exit 1
+  fi
+done
+
+read_handoff_value() {
+  local key="$1"
+  grep -E "^- ${key}:" "${HANDOFF_FILE}" | head -n1 | sed -E "s/^- ${key}:\\s*//; s/\`//g; s/\r//g" | xargs
+}
+
+SUBMISSION_READINESS="$(read_handoff_value "submission_readiness")"
+PRE_SUBMISSION_VERIFICATION="$(read_handoff_value "pre_submission_verification")"
+EXPECTED_CHECKSUM="$(awk '/Expected:/{flag=1;next} flag && /consumer-startup-escalation-bundle-latest\.tgz/ { print; exit }' "${HANDOFF_FILE}" | grep -Eo '[0-9a-f]{64}' | head -n1 || true)"
+ACTUAL_CHECKSUM="$(shasum -a 256 "${BUNDLE_FILE}" | awk '{print $1}')"
+
+if [[ -z "${EXPECTED_CHECKSUM}" ]]; then
+  echo "[phase5-escalation-ready] expected checksum not found in handoff" >&2
+  exit 1
+fi
+
+if [[ "${SUBMISSION_READINESS}" != "READY_TO_SUBMIT" ]]; then
+  echo "[phase5-escalation-ready] submission_readiness is not READY_TO_SUBMIT: ${SUBMISSION_READINESS:-<empty>}" >&2
+  exit 1
+fi
+
+if [[ "${PRE_SUBMISSION_VERIFICATION}" != "PASS" ]]; then
+  echo "[phase5-escalation-ready] pre_submission_verification is not PASS: ${PRE_SUBMISSION_VERIFICATION:-<empty>}" >&2
+  exit 1
+fi
+
+if [[ "${EXPECTED_CHECKSUM}" != "${ACTUAL_CHECKSUM}" ]]; then
+  echo "[phase5-escalation-ready] checksum mismatch" >&2
+  echo "[phase5-escalation-ready] expected=${EXPECTED_CHECKSUM}" >&2
+  echo "[phase5-escalation-ready] actual=${ACTUAL_CHECKSUM}" >&2
+  exit 1
+fi
+
+if [[ ! -f "${PAYLOAD_FILE}" ]]; then
+  echo "[phase5-escalation-ready] payload file missing; generating now"
+  bash scripts/build-phase5-support-portal-payload.sh "${OUT_DIR}"
+fi
+
+if grep -q "\[MISSING\]" "${PAYLOAD_FILE}"; then
+  echo "[phase5-escalation-ready] payload checklist contains missing attachments" >&2
+  exit 1
+fi
+
+echo "[phase5-escalation-ready] submission_readiness=${SUBMISSION_READINESS}"
+echo "[phase5-escalation-ready] pre_submission_verification=${PRE_SUBMISSION_VERIFICATION}"
+echo "[phase5-escalation-ready] checksum=${ACTUAL_CHECKSUM}"
+echo "[phase5-escalation-ready] payload=${PAYLOAD_FILE}"
+echo "[phase5-escalation-ready] READY TO SUBMIT"

package/scripts/check-phase5-latest-ready-chain.sh

@@ -0,0 +1,44 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+OUT_DIR="${1:-.audit-reports/phase5-latest}"
+
+STATUS_REPORT="${OUT_DIR}/phase5-execution-closure-status.md"
+BLOCKERS_REPORT="${OUT_DIR}/phase5-blockers-readiness.md"
+HANDOFF_REPORT="${OUT_DIR}/phase5-external-handoff.md"
+UNBLOCK_REPORT="${OUT_DIR}/consumer-startup-unblock-status.md"
+
+for file in "${STATUS_REPORT}" "${BLOCKERS_REPORT}" "${HANDOFF_REPORT}" "${UNBLOCK_REPORT}"; do
+  if [[ ! -f "${file}" ]]; then
+    echo "[phase5-ready-check] missing report: ${file}" >&2
+    exit 1
+  fi
+done
+
+extract_verdict() {
+  local file="$1"
+  local verdict
+  verdict="$(grep -E '(^|\s)- verdict:\s*' "${file}" | head -n1 | sed -E 's/.*- verdict:\s*//; s/`//g; s/\r//g' || true)"
+  if [[ -z "${verdict}" ]]; then
+    verdict="$(grep -E '(^|\s)- status:\s*' "${file}" | head -n1 | sed -E 's/.*- status:\s*//; s/`//g; s/\r//g' || true)"
+  fi
+  echo "${verdict}" | xargs
+}
+
+PHASE5_STATUS="$(extract_verdict "${STATUS_REPORT}")"
+PHASE5_BLOCKERS="$(extract_verdict "${BLOCKERS_REPORT}")"
+PHASE5_HANDOFF="$(extract_verdict "${HANDOFF_REPORT}")"
+CONSUMER_UNBLOCK="$(extract_verdict "${UNBLOCK_REPORT}")"
+
+echo "[phase5-ready-check] phase5-execution-closure-status=${PHASE5_STATUS:-UNKNOWN}"
+echo "[phase5-ready-check] phase5-blockers-readiness=${PHASE5_BLOCKERS:-UNKNOWN}"
+echo "[phase5-ready-check] phase5-external-handoff=${PHASE5_HANDOFF:-UNKNOWN}"
+echo "[phase5-ready-check] consumer-startup-unblock-status=${CONSUMER_UNBLOCK:-UNKNOWN}"
+
+if [[ "${PHASE5_STATUS}" == "READY" && "${PHASE5_BLOCKERS}" == "READY" && "${PHASE5_HANDOFF}" == "READY" && "${CONSUMER_UNBLOCK}" == "READY" ]]; then
+  echo "[phase5-ready-check] READY chain confirmed"
+  exit 0
+fi
+
+echo "[phase5-ready-check] chain not ready yet"
+exit 1

package/scripts/check-phase8-loop-guard-coverage.sh

@@ -0,0 +1,44 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT="${1:-.}"
+GUARD_REF="scripts/check-phase8-loop-guard.sh"
+
+REQUIRED_FILES=(
+  "scripts/refresh-phase5-latest-escalation.sh"
+  "scripts/run-phase5-post-support-refresh.sh"
+  "scripts/run-phase8-tick.sh"
+  "scripts/run-phase8-autopilot.sh"
+  "scripts/run-phase8-after-billing-reactivation.sh"
+  "scripts/run-phase8-next-step.sh"
+  "scripts/run-phase8-status-pack.sh"
+  "scripts/run-phase8-doctor.sh"
+)
+
+echo "[phase8-loop-guard-coverage] root=${ROOT}"
+echo "[phase8-loop-guard-coverage] guard_ref=${GUARD_REF}"
+
+MISSING=0
+
+for file in "${REQUIRED_FILES[@]}"; do
+  target="${ROOT}/${file}"
+  if [[ ! -f "${target}" ]]; then
+    echo "[phase8-loop-guard-coverage] MISSING_FILE ${file}" >&2
+    MISSING=1
+    continue
+  fi
+
+  if rg -q "${GUARD_REF}" "${target}"; then
+    echo "[phase8-loop-guard-coverage] COVERED ${file}"
+  else
+    echo "[phase8-loop-guard-coverage] MISSING_GUARD ${file}" >&2
+    MISSING=1
+  fi
+done
+
+if [[ "${MISSING}" -ne 0 ]]; then
+  echo "[phase8-loop-guard-coverage] FAILED" >&2
+  exit 1
+fi
+
+echo "[phase8-loop-guard-coverage] PASS"

package/scripts/check-phase8-loop-guard.sh

@@ -0,0 +1,81 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+HANDOFF_FILE="${1:-docs/validation/consumer-startup-escalation-handoff-latest.md}"
+NOW_UTC="${2:-$(date -u +"%Y-%m-%dT%H:%M:%SZ")}"
+
+if [[ ! -f "${HANDOFF_FILE}" ]]; then
+  echo "[phase8-loop-guard] missing handoff file: ${HANDOFF_FILE}" >&2
+  exit 2
+fi
+
+extract_field() {
+  local key="$1"
+  local value
+  value="$(
+    rg -n "^- ${key}:" "${HANDOFF_FILE}" \
+      | head -n 1 \
+      | sed -E "s/^[0-9]+:- ${key}:[[:space:]]*//; s/\`//g; s/\r//g" \
+      | xargs || true
+  )"
+  echo "${value}"
+}
+
+GUARD_STARTED_AT="$(extract_field "loop_guard_started_at_utc")"
+GUARD_NOT_BEFORE="$(extract_field "loop_guard_next_refresh_not_before_utc")"
+GUARD_OVERRIDE_CONDITION="$(extract_field "loop_guard_override_condition")"
+FOLLOW_UP_STATE="$(extract_field "follow_up_state")"
+SUPPORT_REPLY_RECEIVED_AT_UTC="$(extract_field "support_reply_received_at_utc")"
+
+if [[ -z "${GUARD_NOT_BEFORE}" ]]; then
+  echo "[phase8-loop-guard] no guard window configured; refresh allowed"
+  exit 0
+fi
+
+if [[ "${FOLLOW_UP_STATE}" == "SUPPORT_REPLIED" ]]; then
+  echo "[phase8-loop-guard] support reply state detected in handoff"
+  echo "[phase8-loop-guard] follow_up_state=${FOLLOW_UP_STATE}"
+  echo "[phase8-loop-guard] support_reply_received_at_utc=${SUPPORT_REPLY_RECEIVED_AT_UTC:-<unset>}"
+  echo "[phase8-loop-guard] refresh allowed"
+  exit 0
+fi
+
+if [[ "${PHASE8_LOOP_GUARD_OVERRIDE:-0}" == "1" ]]; then
+  echo "[phase8-loop-guard] override enabled via PHASE8_LOOP_GUARD_OVERRIDE=1"
+  echo "[phase8-loop-guard] override_condition=${GUARD_OVERRIDE_CONDITION:-<unset>}"
+  echo "[phase8-loop-guard] refresh allowed"
+  exit 0
+fi
+
+COMPARE_RESULT="$(
+  node -e '
+    const now = Date.parse(process.argv[1]);
+    const notBefore = Date.parse(process.argv[2]);
+    if (Number.isNaN(now) || Number.isNaN(notBefore)) {
+      process.stdout.write("INVALID");
+      process.exit(0);
+    }
+    process.stdout.write(now >= notBefore ? "ALLOW" : "BLOCK");
+  ' "${NOW_UTC}" "${GUARD_NOT_BEFORE}"
+)"
+
+if [[ "${COMPARE_RESULT}" == "INVALID" ]]; then
+  echo "[phase8-loop-guard] invalid timestamp format" >&2
+  echo "[phase8-loop-guard] now_utc=${NOW_UTC}" >&2
+  echo "[phase8-loop-guard] guard_next_refresh_not_before_utc=${GUARD_NOT_BEFORE}" >&2
+  exit 2
+fi
+
+echo "[phase8-loop-guard] now_utc=${NOW_UTC}"
+echo "[phase8-loop-guard] guard_started_at_utc=${GUARD_STARTED_AT:-<unset>}"
+echo "[phase8-loop-guard] guard_next_refresh_not_before_utc=${GUARD_NOT_BEFORE}"
+
+if [[ "${COMPARE_RESULT}" == "ALLOW" ]]; then
+  echo "[phase8-loop-guard] refresh allowed"
+  exit 0
+fi
+
+echo "[phase8-loop-guard] refresh blocked by loop guard"
+echo "[phase8-loop-guard] override_condition=${GUARD_OVERRIDE_CONDITION:-<unset>}"
+echo "[phase8-loop-guard] if support replied already, rerun with PHASE8_LOOP_GUARD_OVERRIDE=1"
+exit 1

package/scripts/check-refactor-progress-single-active.sh

@@ -0,0 +1,25 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+FILE="${1:-docs/REFRACTOR_PROGRESS.md}"
+
+if [[ ! -f "${FILE}" ]]; then
+  echo "[progress-single-active] missing file: ${FILE}" >&2
+  exit 1
+fi
+
+ACTIVE_PATTERN="^- 🚧 \`P[0-9A-Za-z-]+\` "
+ACTIVE_COUNT="$(rg -n "${ACTIVE_PATTERN}" "${FILE}" | wc -l | tr -d ' ')"
+
+echo "[progress-single-active] file=${FILE}"
+echo "[progress-single-active] in_progress_count=${ACTIVE_COUNT}"
+
+if [[ "${ACTIVE_COUNT}" -eq 1 ]]; then
+  echo "[progress-single-active] OK: exactly one in-progress task."
+  exit 0
+fi
+
+echo "[progress-single-active] ERROR: expected exactly 1 in-progress task (🚧), found ${ACTIVE_COUNT}." >&2
+echo "[progress-single-active] current in-progress entries:" >&2
+rg -n "${ACTIVE_PATTERN}" "${FILE}" >&2 || true
+exit 1

package/scripts/check-validation-docs-hygiene.ts

@@ -0,0 +1,42 @@
+import { execFileSync } from 'node:child_process';
+import { checkValidationDocsHygiene } from './validation-docs-hygiene-lib';
+
+const loadTrackedValidationDocs = (): ReadonlyArray<string> => {
+  const output = execFileSync('git', ['ls-files', 'docs/validation'], {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+
+  return output
+    .split('\n')
+    .map((line) => line.trim())
+    .filter((line) => line.length > 0);
+};
+
+const main = (): number => {
+  const trackedPaths = loadTrackedValidationDocs();
+  const result = checkValidationDocsHygiene(trackedPaths);
+
+  if (result.violations.length === 0) {
+    process.stdout.write('validation docs hygiene check passed\n');
+    return 0;
+  }
+
+  process.stderr.write('validation docs hygiene check failed\n');
+  process.stderr.write(
+    [
+      'Unexpected tracked files under docs/validation (generated outputs should not be committed):',
+      ...result.violations.map((violation) => `- ${violation}`),
+    ].join('\n')
+  );
+  process.stderr.write('\n');
+  return 1;
+};
+
+try {
+  process.exit(main());
+} catch (error) {
+  const message = error instanceof Error ? error.message : 'unknown error';
+  process.stderr.write(`validation docs hygiene check failed: ${message}\n`);
+  process.exit(1);
+}

package/scripts/clean-validation-artifacts-cli-lib.ts

@@ -0,0 +1,38 @@
+import { resolve } from 'node:path';
+
+export type CleanValidationArtifactsCliOptions = {
+  repoRoot: string;
+  dryRun: boolean;
+};
+
+export const parseCleanValidationArtifactsArgs = (
+  args: ReadonlyArray<string>
+): CleanValidationArtifactsCliOptions => {
+  const options: CleanValidationArtifactsCliOptions = {
+    repoRoot: process.cwd(),
+    dryRun: false,
+  };
+
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+
+    if (arg === '--repo-root') {
+      const value = args[index + 1];
+      if (!value) {
+        throw new Error('Missing value for --repo-root');
+      }
+      options.repoRoot = resolve(value);
+      index += 1;
+      continue;
+    }
+
+    if (arg === '--dry-run') {
+      options.dryRun = true;
+      continue;
+    }
+
+    throw new Error(`Unknown argument: ${arg}`);
+  }
+
+  return options;
+};

package/scripts/clean-validation-artifacts-lib.ts

@@ -0,0 +1,64 @@
+import { existsSync, readdirSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+
+const collectArtifactDirectories = (root: string): string[] => {
+  if (!existsSync(root)) {
+    return [];
+  }
+
+  const matches: string[] = [];
+
+  const walk = (current: string): void => {
+    for (const entry of readdirSync(current, { withFileTypes: true })) {
+      if (!entry.isDirectory()) {
+        continue;
+      }
+
+      const nextPath = join(current, entry.name);
+      if (entry.name === 'artifacts') {
+        matches.push(nextPath);
+        continue;
+      }
+
+      walk(nextPath);
+    }
+  };
+
+  walk(root);
+  return matches;
+};
+
+export const resolveValidationArtifactTargets = (repoRoot: string): string[] => {
+  const docsValidationRoot = join(repoRoot, 'docs', 'validation');
+  const artifactDirs = collectArtifactDirectories(docsValidationRoot);
+  const auditTmp = join(repoRoot, '.audit_tmp');
+  const candidates = existsSync(auditTmp) ? [...artifactDirs, auditTmp] : artifactDirs;
+
+  return candidates.sort((left, right) => left.localeCompare(right));
+};
+
+export type CleanValidationArtifactsResult = {
+  removed: ReadonlyArray<string>;
+  skipped: ReadonlyArray<string>;
+};
+
+export const cleanValidationArtifacts = (params: {
+  repoRoot: string;
+  dryRun: boolean;
+}): CleanValidationArtifactsResult => {
+  const targets = resolveValidationArtifactTargets(params.repoRoot);
+  const removed: string[] = [];
+  const skipped: string[] = [];
+
+  for (const target of targets) {
+    if (params.dryRun) {
+      skipped.push(target);
+      continue;
+    }
+
+    rmSync(target, { recursive: true, force: true });
+    removed.push(target);
+  }
+
+  return { removed, skipped };
+};

package/scripts/clean-validation-artifacts-output-lib.ts

@@ -0,0 +1,21 @@
+export const printCleanValidationArtifactsNoTargets = (): void => {
+  process.stdout.write('validation artifact cleanup: no targets found\n');
+};
+
+export const printCleanValidationArtifactsDryRun = (params: {
+  skipped: ReadonlyArray<string>;
+}): void => {
+  process.stdout.write('validation artifact cleanup dry-run targets:\n');
+  for (const target of params.skipped) {
+    process.stdout.write(`- ${target}\n`);
+  }
+};
+
+export const printCleanValidationArtifactsRemoved = (params: {
+  removed: ReadonlyArray<string>;
+}): void => {
+  process.stdout.write('validation artifact cleanup removed:\n');
+  for (const target of params.removed) {
+    process.stdout.write(`- ${target}\n`);
+  }
+};

package/scripts/clean-validation-artifacts.ts

@@ -0,0 +1,42 @@
+import { cleanValidationArtifacts, resolveValidationArtifactTargets } from './clean-validation-artifacts-lib';
+import { parseCleanValidationArtifactsArgs } from './clean-validation-artifacts-cli-lib';
+import {
+  printCleanValidationArtifactsDryRun,
+  printCleanValidationArtifactsNoTargets,
+  printCleanValidationArtifactsRemoved,
+} from './clean-validation-artifacts-output-lib';
+
+const main = (): number => {
+  const options = parseCleanValidationArtifactsArgs(process.argv.slice(2));
+  const targets = resolveValidationArtifactTargets(options.repoRoot);
+
+  if (targets.length === 0) {
+    printCleanValidationArtifactsNoTargets();
+    return 0;
+  }
+
+  const result = cleanValidationArtifacts({
+    repoRoot: options.repoRoot,
+    dryRun: options.dryRun,
+  });
+
+  if (options.dryRun) {
+    printCleanValidationArtifactsDryRun({
+      skipped: result.skipped,
+    });
+    return 0;
+  }
+
+  printCleanValidationArtifactsRemoved({
+    removed: result.removed,
+  });
+  return 0;
+};
+
+try {
+  process.exit(main());
+} catch (error) {
+  const message = error instanceof Error ? error.message : 'unknown error';
+  process.stderr.write(`validation artifact cleanup failed: ${message}\n`);
+  process.exit(1);
+}