@gobing-ai/knowledge-kit 0.1.10 → 0.1.12

package/plugins/kk/scripts/kk-workflow-stages.ts

@@ -1263,7 +1263,7 @@ function dailyPublishCompleteness(args: string[]): void {
                 .join('; ');
             console.error(
                 `WARNING: publish completeness — ${completeness.missing.join(', ')} did not complete: ${details}. ` +
-                    'Independent channels never enter publish_status; re-run their stages for this work dir (see ' +
+                    'Side-channel and locale rows never enter publish_status; re-run the relevant stages for this work dir (see ' +
                     `${completenessFile})`,
             );
         }
@@ -1278,9 +1278,10 @@ function targetsOf(path: string): Record<string, unknown>[] {
 }
 
 /**
- * The publish tail's independent channels (locales, XHS, WeChat) and the surfdash CMS re-sync never
- * enter `publish_status` — they are non-blocking by design (ADR-022/025/026). That is also why a
- * tail driven by hand can skip every one of them and still leave a `full` status file behind:
+ * The publish tail's auxiliary channels (locales, XHS, WeChat) and the surfdash CMS re-sync never
+ * enter `publish_status` — only the primary Surfdash + podcast pair does. Locales now validate
+ * before the primary Surfdash publish; XHS/WeChat remain non-blocking by design. A
+ * tail driven by hand can still skip auxiliary channels and leave a `full` status file behind:
  * 20261002 shipped zh-only surfdash with no XHS and no WeChat draft, and nothing in the run's own
  * artifacts said so. Record each channel's state beside the status file so the gap is visible.
  */
@@ -1301,9 +1302,44 @@ function publishCompleteness(
             detail: 'translate markers absent (en/ja never scaffolded)',
         });
     } else {
-        const syncResultFile = at('24_translate-sync_sync-result.json');
-        const syncResult = isFile(syncResultFile) ? readJson(syncResultFile) : null;
-        if (syncResult === null) {
+        const validationResultFile = at('24_translate-validate_result.json');
+        const legacySyncResultFile = at('24_translate-sync_sync-result.json');
+        const hasValidationResult = isFile(validationResultFile);
+        const validationResult = hasValidationResult ? readJson(validationResultFile) : null;
+        const syncResult = isFile(legacySyncResultFile) ? readJson(legacySyncResultFile) : null;
+        if (hasValidationResult) {
+            const primaryPublished = targetsOf(at('14_publish-surfdash_result.json')).some(
+                (entry) => entry.target === 'surfdash-pub' && entry.ok === true && entry.status === 'published',
+            );
+            if (validationResult?.ok !== true) {
+                rows.push({
+                    channel: 'locales',
+                    state: 'failed',
+                    detail: String(validationResult?.error ?? 'translate-validate receipt is missing or malformed'),
+                });
+            } else if (!primaryPublished) {
+                rows.push({
+                    channel: 'locales',
+                    state: 'failed',
+                    detail: 'local validation passed, but final Surfdash publish did not complete',
+                });
+            } else {
+                const untranslated = ['en', 'ja'].filter((locale) => {
+                    const marker = readFileSync(at(`20_translate-localize_${locale}-post-path.txt`), 'utf-8').trim();
+                    if (!isFile(marker)) return true;
+                    const head = readFileSync(marker, 'utf-8').split('---')[1] ?? '';
+                    return /^draft:\s*true\s*$/m.test(head);
+                });
+                rows.push({
+                    channel: 'locales',
+                    state: untranslated.length === 0 ? 'done' : 'failed',
+                    detail:
+                        untranslated.length === 0
+                            ? 'en/ja drafts validated and published with the primary Surfdash sync'
+                            : `${untranslated.join(', ')} draft is still a scaffold (draft: true) — not translated, so it stays unpublished`,
+                });
+            }
+        } else if (syncResult === null) {
             rows.push({
                 channel: 'locales',
                 state: 'not-run',
@@ -1406,6 +1442,180 @@ function dailyPublishPartial(args: string[]): void {
  * `KK_SURFDASH_PATCH_OFFLINE=1` keeps fixture tests hermetic — the plugin would otherwise write to,
  * commit and push a real checkout.
  */
+/**
+ * `publish-matrix-partial` (0333): a partial/none window leaves an explicit recovery marker.
+ *
+ * Reads the window's receipt-derived outcome (written by `publish-matrix-classify`) — the legacy
+ * `_17_publish_result.json` aggregate is never an input — names the exact failed target ids, and
+ * points at the matrix rerun contract (`kk stage run publish-matrix-send <work_dir> --window <w>
+ * --retry`). The rerun is receipt-scoped: `--retry` resends only effect-none failures, never a
+ * succeeded or live-uncertain row, so there is no `--retry-from`/`_17` style file replay. A full
+ * window deletes any stale marker from a previous attempt, so the report never re-flags recovered
+ * targets.
+ */
+function publishMatrixPartial(args: string[]): void {
+    const flag = (name: string): string | undefined => {
+        const i = args.indexOf(name);
+        return i >= 0 ? args[i + 1] : undefined;
+    };
+    const workDir = args[0] ?? '';
+    const window = flag('--window');
+    if (workDir === '' || window === undefined || window === '') {
+        failWith(1, 'usage: publish-matrix-partial <work_dir> --window <w>');
+    }
+    const outcomePath = join(workDir, '4-publish', `outcome.${window}.json`);
+    const outcome = requireJson(outcomePath, 'publish-matrix-partial') as {
+        status?: string;
+        rows?: Array<{ id?: string; status?: string; dummy?: boolean }>;
+    };
+    const marker = join(workDir, '4-publish', `partial-marker.${window}.txt`);
+    timed(workDir, 'publish-matrix-partial', () => {
+        if (outcome.status === 'full') {
+            if (isFile(marker)) sted('rm', marker, () => unlinkSync(marker));
+            return;
+        }
+        const failed = (outcome.rows ?? [])
+            .filter((row) => row.dummy !== true && row.status !== 'succeeded')
+            .map((row) => row.id ?? '(unknown)')
+            .join(',');
+        sted('mkdir', dirname(marker), () => mkdirSync(dirname(marker), { recursive: true }));
+        sted('write', marker, () =>
+            writeRaw(
+                marker,
+                `window ${window} ended ${outcome.status ?? 'unknown'}: failed targets: ${failed === '' ? '(unparsed)' : failed}\n` +
+                    `recovery: kk stage run publish-matrix-send ${workDir} --window ${window} --retry (resends effect-none failures only; receipts scope the retry)\n`,
+            ),
+        );
+        console.error(`WARNING: partial publish — failed targets: ${failed === '' ? '(unparsed)' : failed}`);
+    });
+}
+
+/**
+ * `publish-matrix-patch-surfdash` (0333): patch podcast links into a real surfdash post.
+ *
+ * The patch payload is derived from the window's own receipts, not from legacy aggregate files and
+ * not from a `KK_SURFDASH_ROOT` argument — the plugin resolves its checkout itself. Evidence rules:
+ * the surfdash row must have a real (non-dummy) succeeded receipt whose aggregate metadata carries
+ * an absolute `postPath`; without that there is nothing to patch and the stage records an explicit
+ * skip result instead of fabricating one. Podcast links ride along only when the podcast row is
+ * real too — a dummy or missing episode yields explicit empty `coverUrl`/`showNotesUrl`, never a
+ * fabricated link. `KK_SURFDASH_PATCH_OFFLINE=1` keeps rehearsal runs hermetic the same way the
+ * legacy voice2 stage does.
+ */
+function publishMatrixPatchSurfdash(args: string[]): void {
+    const flag = (name: string): string | undefined => {
+        const i = args.indexOf(name);
+        return i >= 0 ? args[i + 1] : undefined;
+    };
+    const workDir = args[0] ?? '';
+    const window = flag('--window');
+    if (workDir === '' || window === undefined || window === '') {
+        failWith(1, 'usage: publish-matrix-patch-surfdash <work_dir> --window <w>');
+    }
+    const publishDir = join(workDir, '4-publish');
+    const resultPath = join(publishDir, 'patch-surfdash.result.json');
+    const writeResult = (value: Record<string, unknown>): void => {
+        sted('write', resultPath, () => writeJqText(resultPath, value));
+    };
+    const receipt = (id: string): Record<string, unknown> | null =>
+        readJson(join(publishDir, 'receipts', `${id}.json`));
+    const aggregateTarget = (receiptPath: string | undefined): Record<string, unknown> => {
+        const aggregate = receiptPath === undefined ? null : readJson(receiptPath);
+        const targets = aggregate?.targets;
+        if (!Array.isArray(targets) || targets.length === 0 || targets[0] === null || typeof targets[0] !== 'object') {
+            return {};
+        }
+        return targets[0] as Record<string, unknown>;
+    };
+    timed(workDir, 'publish-matrix-patch-surfdash', () => {
+        const outcome = readJson(join(publishDir, `outcome.${window}.json`)) as {
+            rows?: Array<{ id?: string }>;
+        } | null;
+        const rowId = (prefix: string): string | undefined =>
+            (outcome?.rows ?? []).map((row) => row.id ?? '').find((id) => id.startsWith(prefix));
+        const sdId = rowId('surfdash-pub');
+        const podId = rowId('podcast-pub');
+        if (sdId === undefined) {
+            const error = 'skipped: no surfdash target in this window — nothing to patch';
+            writeResult({ ok: false, target: 'surfdash-pub', error });
+            console.error(`patch-surfdash: ${error}`);
+            return;
+        }
+        const sdReceipt = receipt(sdId);
+        const sdReal = sdReceipt !== null && sdReceipt?.dummy !== true && sdReceipt?.status === 'succeeded';
+        const sdTarget = aggregateTarget(
+            typeof sdReceipt?.aggregatePath === 'string' ? sdReceipt.aggregatePath : undefined,
+        );
+        const postPath = (sdTarget.metadata as Record<string, unknown> | undefined)?.postPath;
+        if (!sdReal || typeof postPath !== 'string' || postPath === '') {
+            const error =
+                sdReceipt === null
+                    ? 'skipped: no surfdash publish receipt — nothing to patch'
+                    : typeof postPath !== 'string' || postPath === ''
+                      ? 'skipped: surfdash receipt carries no real postPath — nothing to patch'
+                      : 'skipped: surfdash receipt is dummy — nothing to patch';
+            writeResult({ ok: false, target: 'surfdash-pub', error });
+            console.error(`patch-surfdash: ${error}`);
+            return;
+        }
+        // Links ride along only from real podcast evidence; dummy/missing episodes patch as
+        // explicit empty strings — the patch must never fabricate a link.
+        const podReceipt = podId === undefined ? null : receipt(podId);
+        const podReal = podReceipt !== null && podReceipt?.dummy !== true && podReceipt?.status === 'succeeded';
+        const podTarget = aggregateTarget(
+            typeof podReceipt?.aggregatePath === 'string' ? podReceipt.aggregatePath : undefined,
+        );
+        const podMeta = (podTarget.metadata ?? {}) as Record<string, unknown>;
+        const runDate = String(readJson(join(publishDir, `outcome.${window}.json`))?.runDate ?? '');
+        const payload = join(publishDir, 'patch-surfdash.payload.json');
+        sted('write', payload, () =>
+            writeJqText(payload, {
+                body: '',
+                options: {
+                    operation: 'patch',
+                    postPath,
+                    coverUrl: podReal && typeof podMeta.imageUrl === 'string' ? podMeta.imageUrl : '',
+                    showNotesUrl: podReal && typeof podTarget.url === 'string' ? podTarget.url : '',
+                    ...(runDate.length === 8
+                        ? { dateIso: `${runDate.slice(0, 4)}-${runDate.slice(4, 6)}-${runDate.slice(6, 8)}` }
+                        : runDate.length === 10
+                          ? { dateIso: runDate }
+                          : {}),
+                },
+            }),
+        );
+        if (process.env.KK_SURFDASH_PATCH_OFFLINE === '1') {
+            // Offline rehearsals still derive the payload (evidence), but never invoke the plugin.
+            writeResult({ ok: false, target: 'surfdash-pub', error: 'skipped: offline (KK_SURFDASH_PATCH_OFFLINE=1)' });
+            console.error(
+                'patch-surfdash: offline — payload derived, plugin patch skipped (KK_SURFDASH_PATCH_OFFLINE=1)',
+            );
+            return;
+        }
+        const status = kk(['executor', 'run', 'surfdash-pub', '--in', payload, '--out', resultPath], {
+            unset: NESTED_SPUR_UNSET,
+            soft: true,
+        });
+        const result = readJson(resultPath);
+        if (result?.ok === true) {
+            const meta = (result.metadata ?? {}) as Record<string, unknown>;
+            console.error(
+                `patch-surfdash: ${String(result.message ?? 'patched')} — cms-resync ${String(meta.cmsResync ?? 'ok')}`,
+            );
+            return;
+        }
+        const meta = (result?.metadata ?? {}) as Record<string, unknown>;
+        if (meta.cmsResync === 'failed') {
+            // The posts are patched and committed; only the CMS re-sync (a soft channel) failed.
+            console.error(
+                `patch-surfdash: WARNING: cms re-sync failed — ${String(result?.error ?? `exit ${status}`)}; fix: kk executor run surfdash-pub --in ${payload} --out ${resultPath}`,
+            );
+            return;
+        }
+        failWith(1, `patch-surfdash: ${String(result?.error ?? `surfdash-pub patch exited ${status}`)}`);
+    });
+}
+
 function dailyPatchSurfdash(args: string[]): void {
     const [workDir = '', runDate = '', surfdashRoot = '', pluginsPath = ''] = args;
     if (!surfdashRoot || !existsSync(surfdashRoot)) {
@@ -1415,8 +1625,24 @@ function dailyPatchSurfdash(args: string[]): void {
     timed(workDir, 'patch-surfdash', () => {
         const sdResult = join(workDir, '31-publish', `${runDate}_14_publish-surfdash_result.json`);
         const podcastResult = join(workDir, '31-publish', `${runDate}_16_publish-podcast_result.json`);
-        if (!isFile(sdResult) || !isFile(podcastResult)) {
-            failWith(1, 'patch-surfdash: missing surfdash/podcast publish results — run the publish states first');
+        const resultPath = join(workDir, '31-publish', `${runDate}_23_patch-surfdash_sync-result.json`);
+        const invalidReceipt = (path: string): boolean => {
+            const parsed = readJson(path);
+            return (
+                !isFile(path) ||
+                parsed === null ||
+                !Array.isArray(parsed.targets) ||
+                parsed.targets.length === 0 ||
+                !parsed.targets.every(
+                    (target) => target !== null && typeof target === 'object' && !Array.isArray(target),
+                )
+            );
+        };
+        if (invalidReceipt(sdResult) || invalidReceipt(podcastResult)) {
+            const error = 'patch-surfdash: malformed surfdash/podcast publish receipt — nothing to patch';
+            sted('write', resultPath, () => writeJqText(resultPath, { ok: false, target: 'surfdash-pub', error }));
+            console.error(error);
+            return;
         }
         const targetOf = (path: string): Record<string, unknown> => {
             const parsed = readJson(path) as { targets?: Array<Record<string, unknown>> };
@@ -1433,7 +1659,6 @@ function dailyPatchSurfdash(args: string[]): void {
             console.error('patch-surfdash: surfdash result carries no postPath — nothing to patch, skip');
             return;
         }
-        const resultPath = join(workDir, '31-publish', `${runDate}_23_patch-surfdash_sync-result.json`);
         if (process.env.KK_SURFDASH_PATCH_OFFLINE === '1') {
             // The marker keeps the completeness report's cms-resync row honest in offline runs.
             const skipMarker = join(workDir, '31-publish', `${runDate}_23_patch-surfdash_emdash-resync.txt`);
@@ -1667,6 +1892,11 @@ if (import.meta.main)
             dailyPreflight(rest);
             break;
         }
+        case 'daily-safety-manifest': {
+            const { dailySafetyManifest } = await loadDailyStages();
+            dailySafetyManifest(rest);
+            break;
+        }
         case 'daily-safety-prep': {
             const { dailySafetyPrep } = await loadDailyStages();
             dailySafetyPrep(rest);
@@ -1717,6 +1947,11 @@ if (import.meta.main)
             dailyQualityReport(rest);
             break;
         }
+        case 'daily-quality-verdict': {
+            const { dailyQualityVerdict } = await loadDailyStages();
+            dailyQualityVerdict(rest);
+            break;
+        }
         case 'daily-publish-prep': {
             const { dailyPublishPrep } = await loadDailyStages();
             dailyPublishPrep(rest);
@@ -1727,6 +1962,11 @@ if (import.meta.main)
             dailyPublishSurfdash(rest);
             break;
         }
+        case 'daily-prepare-surfdash': {
+            const { dailyPrepareSurfdash } = await loadDailyStages();
+            dailyPrepareSurfdash(rest);
+            break;
+        }
         case 'daily-show-notes': {
             const { dailyShowNotes } = await loadDailyStages();
             dailyShowNotes(rest);
@@ -1764,6 +2004,12 @@ if (import.meta.main)
         case 'daily-publish-partial':
             dailyPublishPartial(rest);
             break;
+        case 'publish-matrix-partial':
+            publishMatrixPartial(rest);
+            break;
+        case 'publish-matrix-patch-surfdash':
+            publishMatrixPatchSurfdash(rest);
+            break;
         case 'daily-run-report':
             dailyRunReport(rest);
             break;
@@ -1772,11 +2018,21 @@ if (import.meta.main)
             dailyTranslateLocalize(rest);
             break;
         }
+        case 'daily-surfdash-refine': {
+            const { dailySurfdashRefine } = await loadDailyStages();
+            dailySurfdashRefine(rest);
+            break;
+        }
         case 'daily-translate-sync': {
             const { dailyTranslateSync } = await loadDailyStages();
             dailyTranslateSync(rest);
             break;
         }
+        case 'daily-translate-validate': {
+            const { dailyTranslateValidate } = await loadDailyStages();
+            dailyTranslateValidate(rest);
+            break;
+        }
         case 'itc-outline-pick': {
             const { itcOutlinePick } = await loadItcStages();
             itcOutlinePick(rest);

package/plugins/kk/scripts/safety-artifact-check.ts

@@ -0,0 +1,277 @@
+#!/usr/bin/env bun
+import { spawnSync } from 'node:child_process';
+/**
+ * Pure safety-workflow transition predicates.
+ *
+ * The safety state machine cannot put a condition on an individual action. These predicates keep
+ * retry routing outside the agent actions: a successful primary artifact is preserved, while a
+ * missing or malformed artifact takes the bounded retry edge. The revision predicate also uses the
+ * safety request digest rather than Spur's Git working-tree `requireDiff` contract because daily
+ * drafts live under the ignored `.works` tree. The publish predicate keeps a real safety escalation
+ * out of unattended publication without mistaking a catalog fallback value for one.
+ */
+import { createHash } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+const REPORT_DECISIONS = new Set(['OK', 'RISK', 'BLOCK']);
+const CONFIDENCE = new Set(['HIGH', 'MEDIUM', 'LOW']);
+const FINDING_DISPOSITIONS = new Set(['note', 'fix', 'gap', 'escalate']);
+const FINDING_STATUSES = new Set(['pass', 'fail', 'warn']);
+const COMPLIANCE_CRITERIA = new Set([
+    'no-prohibited-claims',
+    'disclosure-presence',
+    'jurisdictional-rules',
+    'data-handling',
+]);
+const VERDICTS = new Set(['PASS', 'FAIL', 'NEEDS_REVISION']);
+
+type JsonObject = Record<string, unknown>;
+
+function isObject(value: unknown): value is JsonObject {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function readJson(path: string): JsonObject | null {
+    try {
+        const value: unknown = JSON.parse(readFileSync(path, 'utf8'));
+        return isObject(value) ? value : null;
+    } catch {
+        return null;
+    }
+}
+
+/** 0331: scope-aware artifact root — `24-script` (or empty) keeps the drafts paths byte-identical. */
+function safetyPath(workDir: string, scopeDir: string, runDate: string, name: string): string {
+    const dir = scopeDir.trim() === '' || scopeDir.trim() === '24-script' ? '24-script' : scopeDir.trim();
+    return join(workDir, dir, `${runDate}_09_${name}`);
+}
+
+function nonEmptyString(value: unknown): value is string {
+    return typeof value === 'string' && value.trim() !== '';
+}
+
+function stringList(value: unknown): string[] | null {
+    if (!Array.isArray(value) || value.some((entry) => !nonEmptyString(entry))) return null;
+    return value.map((entry) => String(entry));
+}
+
+function sortedUnique(values: string[]): string[] | null {
+    const unique = [...new Set(values)];
+    return unique.length === values.length ? unique.sort() : null;
+}
+
+function reportValid(workDir: string, scopeDir: string, runDate: string): string | null {
+    const request = readJson(safetyPath(workDir, scopeDir, runDate, 'safety-review_request.json'));
+    const report = readJson(safetyPath(workDir, scopeDir, runDate, 'safety-review_report.json'));
+    if (request === null || report === null) return 'review request or report is missing/invalid JSON';
+
+    const requested = stringList(request.platforms);
+    const platforms = report.platforms;
+    if (requested === null || !Array.isArray(platforms) || platforms.length === 0) {
+        return 'review request platforms or report platforms[] is missing/empty';
+    }
+    const requestedNames = sortedUnique(requested);
+    const actualNames: string[] = [];
+    for (const platform of platforms) {
+        if (!isObject(platform) || !nonEmptyString(platform.platform)) return 'report platform entry is malformed';
+        const name = String(platform.platform);
+        if (!REPORT_DECISIONS.has(String(platform.decision))) return `invalid platform decision for ${name}`;
+        if (!Array.isArray(platform.findings)) return `findings[] is missing for ${name}`;
+        for (const finding of platform.findings) {
+            if (!isObject(finding)) return `finding entry is malformed for ${name}`;
+            if (finding.disposition !== undefined && !FINDING_DISPOSITIONS.has(String(finding.disposition))) {
+                return `invalid finding disposition for ${name}`;
+            }
+            if (finding.evidenceGap !== undefined && typeof finding.evidenceGap !== 'boolean') {
+                return `evidenceGap must be boolean for ${name}`;
+            }
+        }
+        actualNames.push(name);
+    }
+    const actualNamesSorted = sortedUnique(actualNames);
+    if (
+        requestedNames === null ||
+        actualNamesSorted === null ||
+        requestedNames.join('\0') !== actualNamesSorted.join('\0')
+    ) {
+        return 'report platforms do not exactly match the requested platforms';
+    }
+    if (!CONFIDENCE.has(String(report.confidence))) return 'report confidence is missing/invalid';
+    if (typeof report.escalate !== 'boolean') return 'report escalate must be boolean';
+    return null;
+}
+
+function judgeValid(workDir: string, scopeDir: string, runDate: string): string | null {
+    const verdict = readJson(safetyPath(workDir, scopeDir, runDate, 'safety-judge_verdict.json'));
+    if (verdict === null) return 'judge verdict is missing/invalid JSON';
+    if (!VERDICTS.has(String(verdict.verdict))) return 'judge verdict value is invalid';
+    if (!CONFIDENCE.has(String(verdict.confidence))) return 'judge confidence is missing/invalid';
+    if (verdict.rubric !== 'compliance') return 'judge rubric must be compliance';
+    if (
+        typeof verdict.score !== 'number' ||
+        !Number.isFinite(verdict.score) ||
+        verdict.score < 0 ||
+        verdict.score > 1
+    ) {
+        return 'judge score must be a finite number from 0 through 1';
+    }
+    if (!nonEmptyString(verdict.summary)) return 'judge summary is missing/empty';
+    if (!Array.isArray(verdict.findings) || verdict.findings.length === 0) return 'judge findings[] is missing/empty';
+    const criteria = new Set<string>();
+    for (const finding of verdict.findings) {
+        if (!isObject(finding)) return 'judge finding entry is malformed';
+        if (!nonEmptyString(finding.criterion)) return 'judge finding criterion is missing/empty';
+        if (!FINDING_STATUSES.has(String(finding.status))) return 'judge finding status is invalid';
+        if (!nonEmptyString(finding.detail)) return 'judge finding detail is missing/empty';
+        criteria.add(String(finding.criterion));
+    }
+    if (
+        verdict.verdict === 'PASS' &&
+        verdict.findings.some((finding) => isObject(finding) && finding.status === 'fail')
+    ) {
+        return 'PASS verdict cannot contain a fail finding';
+    }
+    for (const criterion of COMPLIANCE_CRITERIA) {
+        if (!criteria.has(criterion)) return `judge findings omit compliance criterion ${criterion}`;
+    }
+    if (!Array.isArray(verdict.feedback) || verdict.feedback.some((entry) => !nonEmptyString(entry))) {
+        return 'judge feedback[] is missing or contains an empty/non-string entry';
+    }
+    if (!nonEmptyString(verdict.content_ref)) return 'judge content_ref is missing/empty';
+    if (!nonEmptyString(verdict.evaluated_at) || !/^\d{4}-\d{2}-\d{2}T/.test(verdict.evaluated_at)) {
+        return 'judge evaluated_at must be an ISO-8601 timestamp';
+    }
+    if (!Number.isFinite(Date.parse(verdict.evaluated_at))) return 'judge evaluated_at is not a valid timestamp';
+    return null;
+}
+
+/**
+ * The catalog decision may fall back to `escalate` even when the gate admitted `pass` or `exclude`.
+ * Only the gate's persisted status represents a real content-safety escalation, so unattended mode
+ * rejects that status while attended mode leaves it for the caller's pause node.
+ */
+function publishValid(workDir: string, scopeDir: string, runDate: string, unattendedArg: string): string | null {
+    if (unattendedArg !== 'true' && unattendedArg !== 'false') return 'unattended must be true or false';
+    const verdictToken = safetyPath(workDir, scopeDir, runDate, 'safety-verdict.status');
+    const gateStatusPath = safetyPath(workDir, scopeDir, runDate, 'safety-judge_status.txt');
+    let token = '';
+    let gateStatus = '';
+    try {
+        token = readFileSync(verdictToken, 'utf8').trim();
+        gateStatus = readFileSync(gateStatusPath, 'utf8').trim();
+    } catch {
+        return 'safety verdict token or gate status is missing/unreadable';
+    }
+    if (token !== 'accept') return `safety verdict token is ${token || 'missing'}, not accept`;
+    if (!new Set(['pass', 'exclude', 'escalate']).has(gateStatus)) {
+        return `gate status ${gateStatus || 'missing'} is not publish-valid`;
+    }
+    if (unattendedArg === 'true' && gateStatus === 'escalate') {
+        return 'unattended run refuses a real safety escalation; attended review is required';
+    }
+    return null;
+}
+
+function draftDigest(workDir: string, scopeDir: string, runDate: string): string | null {
+    const hash = createHash('sha256');
+    if (scopeDir.trim() === '' || scopeDir.trim() === '24-script') {
+        const article = join(workDir, '22-article', `${runDate}_06_article_content.json`);
+        const script = join(workDir, '24-script', `${runDate}_08_script_voicescript.yaml`);
+        try {
+            hash.update(readFileSync(article)).update('\0');
+            hash.update(readFileSync(script)).update('\0');
+            return hash.digest('hex');
+        } catch {
+            return null;
+        }
+    }
+    // Variants scope: digest over the manifest's sorted keys + current bytes (mirrors the
+    // daily-stages scopeDigest algorithm, so request/guard/verdict all bind the same bytes).
+    try {
+        const manifest = readJson(join(workDir, '4-safety-variants', 'manifest.json')) as {
+            variants?: Record<string, { path?: unknown }>;
+        } | null;
+        if (manifest === null || !isObject(manifest.variants)) return null;
+        for (const key of Object.keys(manifest.variants).sort()) {
+            const path = join(workDir, String(manifest.variants[key].path));
+            hash.update(key).update('\0').update(readFileSync(path)).update('\0');
+        }
+        return hash.digest('hex');
+    } catch {
+        return null;
+    }
+}
+
+function revisionValid(workDir: string, scopeDir: string, runDate: string): string | null {
+    const request = readJson(safetyPath(workDir, scopeDir, runDate, 'safety-review_request.json'));
+    if (request === null || !nonEmptyString(request.digest)) return 'review request digest is missing';
+    const isVariants = scopeDir.trim() !== '' && scopeDir.trim() !== '24-script';
+    const digest = draftDigest(workDir, scopeDir, runDate);
+    if (digest === null) {
+        return isVariants
+            ? 'a manifest-listed variant is missing/unreadable'
+            : 'revised article or VoiceScript is missing/unreadable';
+    }
+    if (digest === request.digest) return isVariants ? 'variant digest is unchanged' : 'draft digest is unchanged';
+    if (isVariants) {
+        const manifest = readJson(join(workDir, '4-safety-variants', 'manifest.json')) as {
+            variants?: Record<string, { path?: unknown }>;
+        } | null;
+        if (manifest === null || !isObject(manifest.variants)) return 'variants manifest is missing/malformed';
+        for (const entry of Object.values(manifest.variants)) {
+            const value = readJson(join(workDir, String(entry.path)));
+            if (value === null || !nonEmptyString(value.title) || !nonEmptyString(value.body)) {
+                return 'revised variant title/body is missing';
+            }
+        }
+        return null;
+    }
+    const articlePath = join(workDir, '22-article', `${runDate}_06_article_content.json`);
+    const scriptPath = join(workDir, '24-script', `${runDate}_08_script_voicescript.yaml`);
+    const article = readJson(articlePath);
+    if (article === null || !nonEmptyString(article.title) || !nonEmptyString(article.body)) {
+        return 'revised article title/body is missing';
+    }
+
+    const validator = join(import.meta.dir, 'validate-voicescript.ts');
+    const result = spawnSync(process.execPath, [validator, '--in', scriptPath], {
+        encoding: 'utf8',
+        stdio: 'ignore',
+    });
+    if (result.status !== 0) return 'revised VoiceScript failed content validation';
+    return null;
+}
+
+function main(): number {
+    // 0331: an optional trailing scope dir re-roots every artifact path (variants review reads
+    // 4-safety-variants); publish-valid keeps `unattended` in the 4th slot it has always had.
+    const [kind = '', workDir = '', runDate = '', fourth = '', fifth = ''] = process.argv.slice(2);
+    const isPublish = kind === 'publish-valid';
+    const unattended = isPublish ? fourth : 'false';
+    const scopeDir = isPublish ? fifth : fourth;
+    if (!kind || !workDir || !runDate) {
+        console.error(
+            'usage: safety-artifact-check.ts <report-valid|judge-valid|revision-valid|publish-valid> <work_dir> <run_date> [unattended] [scope_dir]',
+        );
+        return 2;
+    }
+    const reason =
+        kind === 'report-valid'
+            ? reportValid(workDir, scopeDir, runDate)
+            : kind === 'judge-valid'
+              ? judgeValid(workDir, scopeDir, runDate)
+              : kind === 'revision-valid'
+                ? revisionValid(workDir, scopeDir, runDate)
+                : kind === 'publish-valid'
+                  ? publishValid(workDir, scopeDir, runDate, unattended)
+                  : 'unknown predicate';
+    if (reason !== null) {
+        console.error(`safety-artifact-check: ${kind}: ${reason}`);
+        return 1;
+    }
+    console.log(`safety-artifact-check: ${kind}: ok`);
+    return 0;
+}
+
+process.exitCode = main();