project-tiny-context-harness 0.2.74 → 0.2.76

package/dist/commands/index.js

@@ -3,6 +3,7 @@ import { doctor } from "./doctor.js";
 import { exportContext } from "./export-context.js";
 import { init } from "./init.js";
 import { packageSource } from "./package-source.js";
+import { superpowers } from "./superpowers.js";
 import { sync } from "./sync.js";
 import { upgrade } from "./upgrade.js";
 import { validate } from "./validate.js";
@@ -20,6 +21,8 @@ export const commands = {
     "validate-harness": (args) => validate(["validate-harness", ...args]),
     "validate-plan-contract": (args) => validate(["validate-plan-contract", ...args]),
     "validate-plan-acceptance": (args) => validate(["validate-plan-acceptance", ...args]),
+    "validate-superpowers-state": (args) => validate(["validate-superpowers-state", ...args]),
+    superpowers,
     package: packageSource
 };
 export function help() {
@@ -32,16 +35,20 @@ export function help() {
   doctor               Diagnose project configuration and drift
   check-modularity --touched|--file <path>|--base <ref> [--limit 300] [--fail-on-warning]
                        Warn when selected handwritten source files exceed a line-count limit
-  export-context --full|--code|--all|--source-pack|--code-index|--task-context
-                       Export temporary Context, code snapshot or bounded Source Pack artifacts
+  export-context --full|--code|--all|--source-pack|--code-index|--task-context
+                       Export temporary Context, code snapshot or bounded Source Pack artifacts
   validate <gate>      Run a Harness validation gate
   validate-context     Validate Minimal Context fact-source recoverability
-  validate-code-modularity
-                       Enforce touched handwritten source file modularity
-  validate-harness     Run validate-context and validate-code-modularity
-  validate-plan-contract <plan.md|dir>
-                       Validate workflow-contract plan surface consistency
-  validate-plan-acceptance <dir>
-                       Validate plan-conformance matrix and final verdict consistency
+  validate-code-modularity
+                       Enforce touched handwritten source file modularity
+  validate-harness     Run validate-context and validate-code-modularity
+  validate-plan-contract <plan.md|dir>
+                       Validate workflow-contract plan surface consistency
+  validate-plan-acceptance <dir>
+                       Validate plan-conformance matrix and final verdict consistency
+  validate-superpowers-state <dir>
+                       Validate canonical Superpowers task-state.json
+  superpowers <subcommand>
+                       Manage explicit Superpowers long-task state workdirs
   package <subcommand> Maintain package canonical source`);
 }

package/dist/commands/superpowers.d.ts

@@ -0,0 +1 @@
+export declare function superpowers(args: string[]): Promise<void>;

package/dist/commands/superpowers.js

@@ -0,0 +1,89 @@
+import path from "node:path";
+import { applySliceDelta, initializeSuperpowersTask } from "../lib/superpowers-task-state.js";
+import { compileSuperpowersTask } from "../lib/superpowers-task-compile.js";
+import { deriveSuperpowersArtifacts } from "../lib/superpowers-task-derive.js";
+import { runEpochGate, runFinalGate, runSliceGate } from "../lib/superpowers-task-gates.js";
+import { nextSuperpowersSlices } from "../lib/superpowers-task-next-slices.js";
+export async function superpowers(args) {
+    const subcommand = args[0] ?? "help";
+    const workdirArg = args[1];
+    if (!workdirArg || subcommand === "help") {
+        help();
+        return;
+    }
+    const workdir = path.resolve(process.cwd(), workdirArg);
+    if (subcommand === "init") {
+        await initializeSuperpowersTask(workdir, { planSlug: path.basename(workdir) });
+        console.log(`initialized superpowers task state at ${workdirArg}/task-state.json`);
+        return;
+    }
+    if (subcommand === "compile") {
+        const state = await compileSuperpowersTask(workdir);
+        console.log(`compiled superpowers task graph plan_items=${Object.keys(state.graph.plan_items).length} acs=${Object.keys(state.graph.acceptance_criteria).length}`);
+        return;
+    }
+    if (subcommand === "apply-slice-delta") {
+        const delta = args[2];
+        if (!delta) {
+            throw new Error("apply-slice-delta requires <slice-delta.json>");
+        }
+        await applySliceDelta(workdir, path.resolve(process.cwd(), delta));
+        const result = await deriveSuperpowersArtifacts(workdir);
+        console.log(`applied superpowers slice delta and derived files=${result.files.length}`);
+        return;
+    }
+    if (subcommand === "derive") {
+        const result = await deriveSuperpowersArtifacts(workdir);
+        console.log(`derived superpowers artifacts files=${result.files.length}`);
+        return;
+    }
+    if (subcommand === "slice-gate") {
+        const sliceId = optionValue(args, "--slice") ?? "";
+        const result = await runSliceGate(workdir, sliceId);
+        console.log(result.passed ? `slice gate passed ${sliceId}` : `slice gate blocked ${result.messages.join("; ")}`);
+        if (!result.passed) {
+            process.exitCode = 1;
+        }
+        return;
+    }
+    if (subcommand === "epoch-gate") {
+        const epochId = optionValue(args, "--epoch") ?? "";
+        const result = await runEpochGate(workdir, epochId);
+        console.log(result.passed ? `epoch gate passed ${epochId}` : `epoch gate blocked ${result.messages.join("; ")}`);
+        return;
+    }
+    if (subcommand === "final-gate") {
+        const result = await runFinalGate(workdir);
+        console.log(`final gate product_goal_complete=${result.product_goal_complete}`);
+        if (!result.product_goal_complete) {
+            process.exitCode = 1;
+            for (const error of result.errors) {
+                console.error(`error: ${error}`);
+            }
+        }
+        return;
+    }
+    if (subcommand === "next-slices") {
+        const limit = Number.parseInt(optionValue(args, "--limit") ?? "5", 10);
+        const slices = await nextSuperpowersSlices(workdir, Number.isFinite(limit) ? limit : 5);
+        console.log(`Next ${Math.min(Number.isFinite(limit) ? limit : 5, 5)} high-value clusters:`);
+        console.log(slices.join("\n"));
+        return;
+    }
+    help();
+}
+function help() {
+    console.log(`ty-context superpowers commands:
+  init <workdir>                         Initialize task-state.json and events.ndjson
+  compile <workdir>                      Compile sources into task graph
+  apply-slice-delta <workdir> <delta>    Apply structured slice delta, evidence and derived views
+  derive <workdir>                       Generate derived/** views
+  slice-gate <workdir> --slice <id>      Validate one slice has real progress
+  epoch-gate <workdir> --epoch <id>      Refresh shared epoch evidence views
+  final-gate <workdir>                   Compute product_goal_complete
+  next-slices <workdir> --limit 5        Recommend next proof clusters`);
+}
+function optionValue(args, name) {
+    const index = args.indexOf(name);
+    return index >= 0 ? args[index + 1] : undefined;
+}

package/dist/commands/validate.js

@@ -5,6 +5,12 @@ export async function validate(args) {
     for (const line of report.info) {
         console.log(line);
     }
+    for (const warning of report.warnings ?? []) {
+        console.error(`warning: ${warning}`);
+    }
+    for (const hygiene of report.hygiene ?? []) {
+        console.error(`hygiene: ${hygiene}`);
+    }
     for (const error of report.errors) {
         console.error(`error: ${error}`);
     }

package/dist/lib/plan-acceptance-artifacts.d.ts

@@ -0,0 +1 @@
+export declare function validateAcceptanceArtifactDiagnostics(projectRoot: string, targetDir: string, matrixRows: Record<string, unknown>[], verdictRows: Record<string, unknown>[], verdictOverall: string, errors: string[], warnings: string[], hygiene: string[]): Promise<void>;

package/dist/lib/plan-acceptance-artifacts.js

@@ -0,0 +1,220 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { readText } from "./fs.js";
+import { findSensitiveEvidence } from "./plan-acceptance-evidence.js";
+import { isOutOfScope, statusOf } from "./plan-acceptance-json.js";
+import { isBlankish, primitiveText, repoRelative, valuesAsArray } from "./plan-validator-common.js";
+const MILESTONE_STATUSES = new Set([
+    "not_started",
+    "implemented_no_proof",
+    "proof_partial",
+    "proof_ready",
+    "complete",
+    "blocked",
+    "out_of_scope_NA"
+]);
+const GENERATED_ACTIVE_COUNTS = /<!--\s*generated:active-counts:start\s*-->([\s\S]*?)<!--\s*generated:active-counts:end\s*-->/i;
+export async function validateAcceptanceArtifactDiagnostics(projectRoot, targetDir, matrixRows, verdictRows, verdictOverall, errors, warnings, hygiene) {
+    validateRows(matrixRows, "plan-conformance matrix row", warnings, hygiene);
+    validateRows(verdictRows, "final acceptance verdict row", warnings, hygiene);
+    const manifestEvidenceIds = await validateEvidenceManifest(projectRoot, targetDir, errors, warnings);
+    if (manifestEvidenceIds.size > 0) {
+        validateEvidenceIdReferences(matrixRows, "plan-conformance matrix row", manifestEvidenceIds, errors);
+        validateEvidenceIdReferences(verdictRows, "final acceptance verdict row", manifestEvidenceIds, errors);
+    }
+    await validateFinalVerdictMarkdown(projectRoot, targetDir, verdictRows, verdictOverall, errors, warnings, hygiene);
+}
+function validateRows(rows, labelPrefix, warnings, hygiene) {
+    for (const [index, row] of rows.entries()) {
+        const label = `${labelPrefix} ${index + 1}`;
+        validateMilestones(row, label, warnings);
+        validateStalePartialText(row, label, hygiene);
+    }
+}
+function validateMilestones(row, label, warnings) {
+    const milestones = row.milestones ?? row.proof_layer_milestones ?? row.proofLayerMilestones;
+    if (isBlankish(milestones)) {
+        return;
+    }
+    for (const status of extractMilestoneStatuses(milestones)) {
+        if (!MILESTONE_STATUSES.has(status)) {
+            warnings.push(`${label} has unsupported milestone status: ${status || "<empty>"}`);
+        }
+    }
+}
+function extractMilestoneStatuses(value) {
+    if (Array.isArray(value)) {
+        return value.flatMap(extractMilestoneStatuses);
+    }
+    if (!value || typeof value !== "object") {
+        return valuesAsArray(value).map((item) => item.trim());
+    }
+    const object = value;
+    if (!isBlankish(object.status)) {
+        return [String(object.status).trim()];
+    }
+    return Object.values(object).flatMap(extractMilestoneStatuses);
+}
+function validateStalePartialText(row, label, hygiene) {
+    const status = statusOf(row);
+    if (status === "complete" || status === "out_of_scope_NA") {
+        return;
+    }
+    const text = primitiveText(row);
+    const hasCompletionClaim = /\b(accepted|complete|final passed|goal achieved|product_goal_complete=true)\b/i.test(text);
+    const hasStaleQualifier = /\b(old|stale|previously|prior|outdated|superseded|no longer current)\b/i.test(text);
+    if (hasCompletionClaim && hasStaleQualifier) {
+        hygiene.push(`${label} has stale or overclaim completion prose while status is ${status || "<empty>"}`);
+    }
+}
+async function validateEvidenceManifest(projectRoot, targetDir, errors, warnings) {
+    const manifestFile = await findFile(targetDir, "evidence-manifest", ".json");
+    const evidenceIds = new Set();
+    if (!manifestFile) {
+        return evidenceIds;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(await readText(manifestFile));
+    }
+    catch (error) {
+        errors.push(`${repoRelative(projectRoot, manifestFile)} is not valid JSON: ${error instanceof Error ? error.message : String(error)}`);
+        return evidenceIds;
+    }
+    const entries = findManifestEntries(parsed);
+    if (entries.length === 0) {
+        warnings.push(`${repoRelative(projectRoot, manifestFile)} has no evidence entries`);
+        return evidenceIds;
+    }
+    for (const [index, entry] of entries.entries()) {
+        const label = `evidence manifest entry ${index + 1}`;
+        const evidenceId = firstString(entry.evidence_id, entry.evidenceId, entry.id);
+        if (evidenceId) {
+            evidenceIds.add(evidenceId);
+        }
+        else {
+            errors.push(`${label} is missing evidence_id`);
+        }
+        warnIfBlank(entry, label, warnings, "slice_id", "sliceId");
+        warnIfBlank(entry, label, warnings, "slice_goal", "sliceGoal");
+        warnIfBlank(entry, label, warnings, "touched_plan_item_ids", "touched_plan_ids", "plan_item_ids");
+        warnIfBlank(entry, label, warnings, "touched_ac_ids", "acceptance_ids", "ac_ids");
+        warnIfBlank(entry, label, warnings, "missing_layer_classes");
+        warnIfBlank(entry, label, warnings, "proves");
+        warnIfBlank(entry, label, warnings, "explicitly_does_not_prove", "does_not_prove");
+        warnIfBlank(entry, label, warnings, "closed_missing_layers", "closed_layers");
+        warnIfBlank(entry, label, warnings, "remaining_missing_layers", "remaining_layers");
+        warnIfBlank(entry, label, warnings, "cleanup_status");
+        warnIfBlank(entry, label, warnings, "redaction_security_status", "security_redaction_status");
+        warnIfBlank(entry, label, warnings, "freshness");
+        const sensitiveEvidence = findSensitiveEvidence(primitiveText(entry));
+        if (sensitiveEvidence) {
+            errors.push(`${label} contains raw secret/token/cookie material: ${sensitiveEvidence}`);
+        }
+        if (entry.safe_to_sync_to_verdict === true && !isBlankish(entry.remaining_missing_layers ?? entry.remaining_layers)) {
+            warnings.push(`${label} is safe_to_sync_to_verdict but still has remaining missing layers`);
+        }
+    }
+    return evidenceIds;
+}
+function findManifestEntries(value) {
+    if (Array.isArray(value)) {
+        return value.filter(isRecord);
+    }
+    if (!isRecord(value)) {
+        return [];
+    }
+    for (const key of ["evidence", "entries", "items", "manifest"]) {
+        const rows = findManifestEntries(value[key]);
+        if (rows.length > 0) {
+            return rows;
+        }
+    }
+    return [];
+}
+function validateEvidenceIdReferences(rows, labelPrefix, evidenceIds, errors) {
+    for (const [index, row] of rows.entries()) {
+        for (const evidenceId of valuesAsArray(row.evidence_id ?? row.evidence_ids ?? row.evidenceId ?? row.evidenceIds)) {
+            if (!evidenceIds.has(evidenceId)) {
+                errors.push(`${labelPrefix} ${index + 1} references unknown evidence_id: ${evidenceId}`);
+            }
+        }
+    }
+}
+async function validateFinalVerdictMarkdown(projectRoot, targetDir, verdictRows, verdictOverall, errors, warnings, hygiene) {
+    const markdownFile = await findFile(targetDir, "final-acceptance-verdict", ".md");
+    if (!markdownFile) {
+        return;
+    }
+    const content = await readText(markdownFile);
+    const match = GENERATED_ACTIVE_COUNTS.exec(content);
+    if (!match) {
+        if (/\b(active[-_ ]?count|complete_count|acceptance_required_count|missing_layer_count)\b/i.test(content)) {
+            hygiene.push(`${repoRelative(projectRoot, markdownFile)} has active-count-like prose outside generated active-count markers`);
+        }
+        return;
+    }
+    const declared = parseCountBlock(match[1]);
+    const actual = activeCounts(verdictRows);
+    for (const [key, expected] of Object.entries(actual)) {
+        const declaredValue = declared[key];
+        if (declaredValue === undefined) {
+            warnings.push(`${repoRelative(projectRoot, markdownFile)} generated active-count block is missing ${key}`);
+            continue;
+        }
+        if (declaredValue !== expected) {
+            const message = `${repoRelative(projectRoot, markdownFile)} generated active-count ${key}=${declaredValue} but current verdict has ${expected}`;
+            if (verdictOverall === "complete") {
+                errors.push(message);
+            }
+            else {
+                warnings.push(message);
+            }
+        }
+    }
+}
+function parseCountBlock(content) {
+    const counts = {};
+    for (const line of content.split(/\r?\n/)) {
+        const match = /^\s*([A-Za-z0-9_-]+)\s*[:=]\s*(\d+)\s*$/.exec(line);
+        if (match) {
+            counts[match[1].replace(/-/g, "_")] = Number(match[2]);
+        }
+    }
+    return counts;
+}
+function activeCounts(rows) {
+    return {
+        complete_count: rows.filter((row) => statusOf(row) === "complete").length,
+        partial_count: rows.filter((row) => statusOf(row) === "partial").length,
+        acceptance_required_count: rows.filter((row) => !isOutOfScope(row)).length,
+        missing_layer_count: rows.reduce((sum, row) => sum + missingLayerCount(row), 0)
+    };
+}
+function missingLayerCount(row) {
+    return valuesAsArray(row.missing_required_layers ?? row.missingRequiredLayers ?? row.missing_proof_layers ?? row.missing_evidence).length;
+}
+async function findFile(targetDir, marker, extension) {
+    const entries = await fs.readdir(targetDir, { withFileTypes: true });
+    return entries
+        .filter((entry) => entry.isFile() && entry.name.endsWith(extension) && entry.name.includes(marker))
+        .map((entry) => path.join(targetDir, entry.name))
+        .sort()[0];
+}
+function warnIfBlank(entry, label, warnings, ...keys) {
+    if (keys.some((key) => !isBlankish(entry[key]))) {
+        return;
+    }
+    warnings.push(`${label} is missing ${keys[0]}`);
+}
+function firstString(...values) {
+    for (const value of values) {
+        if (!isBlankish(value)) {
+            return String(value).trim();
+        }
+    }
+    return undefined;
+}
+function isRecord(value) {
+    return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}

package/dist/lib/plan-acceptance-evidence.d.ts

@@ -1 +1,2 @@
 export declare function assertExternalReviewerFields(label: string, row: Record<string, unknown>, evidenceText: string, errors: string[]): void;
+export declare function findSensitiveEvidence(text: string): string | undefined;

package/dist/lib/plan-acceptance-evidence.js

@@ -1,6 +1,20 @@
 import { isOutOfScope } from "./plan-acceptance-json.js";
 import { isBlankish, primitiveText, valuesAsArray } from "./plan-validator-common.js";
 const BLOCKING_AUDITOR_STATUSES = new Set(["partial", "blocked", "invalidated"]);
+const SENSITIVE_EVIDENCE_PATTERNS = [
+    {
+        label: "Authorization bearer token",
+        pattern: /\bauthorization\s*:\s*bearer\s+(?!<redacted>|redacted|\[redacted\])[A-Za-z0-9._~+/=-]{8,}/i
+    },
+    {
+        label: "cookie value",
+        pattern: /\bcookie\s*[:=]\s*(?!<redacted>|redacted|\[redacted\])[^;\s]{8,}/i
+    },
+    {
+        label: "secret assignment",
+        pattern: /\b(?:api[_-]?key|access[_-]?token|refresh[_-]?token|token|secret|password)\s*[:=]\s*["']?(?!<redacted>|redacted|\[redacted\])[A-Za-z0-9_./+=-]{8,}/i
+    }
+];
 export function assertExternalReviewerFields(label, row, evidenceText, errors) {
     if (hasUnresolvedMissingRequiredLayers(row)) {
         errors.push(`${label} is complete but missing_required_layers is not empty`);
@@ -12,6 +26,9 @@ export function assertExternalReviewerFields(label, row, evidenceText, errors) {
     if (siblingSubstitutionUsed(row) && !hasSiblingSubstitutionApproval(row)) {
         errors.push(`${label} is complete but sibling_substitution_used without approval`);
     }
+    if (liveProofSubstitutionUsed(row) && !hasLiveProofSubstitutionApproval(row)) {
+        errors.push(`${label} is complete but live_proof_substitution_used without approval`);
+    }
     const auditorStatus = String(row.auditor_status ?? row.auditorStatus ?? "").trim().toLowerCase();
     if (BLOCKING_AUDITOR_STATUSES.has(auditorStatus)) {
         errors.push(`${label} is complete but auditor_status is ${auditorStatus}`);
@@ -19,6 +36,13 @@ export function assertExternalReviewerFields(label, row, evidenceText, errors) {
     if (hasOnlySelfCertifyingEvidence(evidenceText)) {
         errors.push(`${label} is complete but fresh_evidence contains only summary or self-certifying evidence`);
     }
+    const sensitiveEvidence = findSensitiveEvidence(evidenceText);
+    if (sensitiveEvidence) {
+        errors.push(`${label} is complete but evidence contains raw secret/token/cookie material: ${sensitiveEvidence}`);
+    }
+}
+export function findSensitiveEvidence(text) {
+    return SENSITIVE_EVIDENCE_PATTERNS.find((item) => item.pattern.test(text))?.label;
 }
 function hasUnresolvedMissingRequiredLayers(row) {
     const value = row.missing_required_layers ?? row.missingRequiredLayers ?? row.missing_proof_layers;
@@ -59,6 +83,22 @@ function hasSiblingSubstitutionApproval(row) {
         !isBlankish(row.substitution_approval_source) ||
         /\b(approved|explicitly allowed|out[_ -]?of[_ -]?scope[_ -]?NA)\b/i.test(primitiveText([row.sibling_substitution_approved, row.substitution_approval])));
 }
+function liveProofSubstitutionUsed(row) {
+    const value = row.live_proof_substitution_used ?? row.liveProofSubstitutionUsed;
+    if (value === true) {
+        return true;
+    }
+    const text = primitiveText(value);
+    if (/\b(false|no|none|not used|not_used)\b/i.test(text)) {
+        return false;
+    }
+    return /\b(true|yes|used|present|substituted)\b/i.test(text);
+}
+function hasLiveProofSubstitutionApproval(row) {
+    return (!isBlankish(row.live_proof_substitution_approval_source) ||
+        !isBlankish(row.liveProofSubstitutionApprovalSource) ||
+        /\b(approved|explicitly allowed|out[_ -]?of[_ -]?scope[_ -]?NA)\b/i.test(primitiveText([row.live_proof_substitution_approved, row.liveProofSubstitutionApproved])));
+}
 function hasOnlySelfCertifyingEvidence(text) {
     const entries = valuesAsArray(text);
     return entries.length > 0 && entries.every(isSelfCertifyingEvidence);

package/dist/lib/plan-acceptance-json.js

@@ -107,10 +107,14 @@ export function assertSurfaceConformance(row, label, errors) {
         errors.push(`${label} declares forbidden_primary_surfaces but negative_surface_checks is empty`);
     }
     const userPathText = primitiveText([row.required_user_paths, row.primary_user_paths]);
+    const evidenceText = primitiveText([row.real_page_evidence, row.user_path_evidence, row.fresh_evidence, row.runtime_evidence, row.artifact_evidence]);
     for (const forbiddenSurface of valuesAsArray(row.forbidden_primary_surfaces)) {
         if (userPathText.toLowerCase().includes(forbiddenSurface.toLowerCase())) {
             errors.push(`${label} routes a required/primary user path through forbidden surface: ${forbiddenSurface}`);
         }
+        if (evidenceText.toLowerCase().includes(forbiddenSurface.toLowerCase())) {
+            errors.push(`${label} uses wrong owner surface evidence from forbidden surface: ${forbiddenSurface}`);
+        }
     }
     if (row.default_visibility_required === true && !mentionsDefaultVisibility(primitiveText(row.real_page_evidence))) {
         errors.push(`${label} requires default visibility but real_page_evidence does not record default-visible proof`);

package/dist/lib/plan-acceptance-validator.js

@@ -1,13 +1,31 @@
+import path from "node:path";
 import { pathExists } from "./fs.js";
+import { validateAcceptanceArtifactDiagnostics } from "./plan-acceptance-artifacts.js";
 import { assertExternalReviewerFields } from "./plan-acceptance-evidence.js";
 import { AC_STATUSES, MATRIX_STATUSES, NON_COMPLETE_AC, NON_COMPLETE_MATRIX, assertStructuredNa, assertSurfaceConformance, contextDeltaRequired, findJsonFile, findRows, hasExplicitNoTestScope, isOutOfScope, isSurfaceConformanceRow, overallStatus, readJson, statusOf } from "./plan-acceptance-json.js";
 import { assertReferencedPathsExist, hasRealPageEvidence, isBlankish, isUiFacing, primitiveText, repoRelative, resolveInputDir, valuesAsArray, weakProofHit } from "./plan-validator-common.js";
+import { validateSuperpowersState } from "./superpowers-task-validator.js";
 export async function validatePlanAcceptance(projectRoot, args = []) {
     const info = [];
+    const warnings = [];
+    const hygiene = [];
     const errors = [];
     const targetDir = await resolveInputDir(projectRoot, args[0], "tmp/ty-context/plan-acceptance");
     if (!(await pathExists(targetDir))) {
-        return { info, errors: [`plan acceptance directory is missing: ${repoRelative(projectRoot, targetDir)}`] };
+        return { info, warnings, hygiene, errors: [`plan acceptance directory is missing: ${repoRelative(projectRoot, targetDir)}`] };
+    }
+    if (await pathExists(path.join(targetDir, "task-state.json"))) {
+        const stateReport = await validateSuperpowersState(projectRoot, [targetDir]);
+        return {
+            info: [
+                `checked state-backed plan acceptance ${repoRelative(projectRoot, targetDir)}`,
+                ...stateReport.info,
+                ...(stateReport.errors.length === 0 ? ["Plan acceptance state-backed artifact consistency passed"] : [])
+            ],
+            warnings: stateReport.warnings,
+            hygiene: stateReport.hygiene,
+            errors: stateReport.errors
+        };
     }
     const matrixFile = await findJsonFile(targetDir, "plan-conformance-matrix");
     const verdictFile = await findJsonFile(targetDir, "final-acceptance-verdict");
@@ -18,12 +36,12 @@ export async function validatePlanAcceptance(projectRoot, args = []) {
         errors.push(`plan acceptance directory is missing *-final-acceptance-verdict.json`);
     }
     if (!matrixFile || !verdictFile) {
-        return { info, errors };
+        return { info, warnings, hygiene, errors };
     }
     const matrix = await readJson(matrixFile, errors);
     const verdict = await readJson(verdictFile, errors);
     if (matrix === undefined || verdict === undefined) {
-        return { info, errors };
+        return { info, warnings, hygiene, errors };
     }
     const matrixRows = findRows(matrix, ["plan_items", "items", "matrix", "entries", "plan_conformance"]);
     const verdictRows = findRows(verdict, ["acceptance_items", "ac_verdicts", "verdicts", "items", "entries", "acs"]);
@@ -31,11 +49,12 @@ export async function validatePlanAcceptance(projectRoot, args = []) {
     await validateVerdictRows(projectRoot, verdictRows, overallStatus(verdict), errors);
     validateCrossReferences(matrixRows, verdictRows, errors);
     validateContextFactReferences(matrix, verdict, matrixRows, verdictRows, errors);
+    await validateAcceptanceArtifactDiagnostics(projectRoot, targetDir, matrixRows, verdictRows, overallStatus(verdict), errors, warnings, hygiene);
     info.push(`checked plan acceptance ${repoRelative(projectRoot, targetDir)} matrix_rows=${matrixRows.length} verdict_rows=${verdictRows.length}`);
     if (errors.length === 0) {
         info.push("Plan acceptance artifact consistency passed");
     }
-    return { info, errors };
+    return { info, warnings, hygiene, errors };
 }
 async function validateMatrixRows(projectRoot, rows, overall, errors) {
     if (rows.length === 0) {

package/dist/lib/superpowers-task-compile.d.ts

@@ -0,0 +1 @@
+export declare function compileSuperpowersTask(workdir: string): Promise<import("./superpowers-task-state-schema.js").SuperpowersTaskState>;

package/dist/lib/superpowers-task-compile.js

@@ -0,0 +1,114 @@
+import path from "node:path";
+import { readText } from "./fs.js";
+import { appendSuperpowersEvent } from "./superpowers-task-events.js";
+import { loadSuperpowersState, recomputeStatuses, saveSuperpowersState, refreshSourceHashes } from "./superpowers-task-state.js";
+import { asStringArray } from "./superpowers-task-state-schema.js";
+const DEFAULT_LAYERS = ["code", "test"];
+export async function compileSuperpowersTask(workdir) {
+    const state = await loadSuperpowersState(workdir);
+    await refreshSourceHashes(workdir, state);
+    const technicalPlan = await readText(path.join(workdir, state.sources.technical_realization_plan.path));
+    const checklist = await readText(path.join(workdir, state.sources.acceptance_checklist.path));
+    const planItems = parsePlanItems(technicalPlan);
+    const acceptanceCriteria = parseAcceptanceCriteria(checklist);
+    const acIds = Object.keys(acceptanceCriteria);
+    for (const [planId, item] of Object.entries(planItems)) {
+        if (item.related_acs.length === 0) {
+            item.related_acs = acIds;
+        }
+        item.required_proof_layers = item.related_acs.flatMap((acId) => (acceptanceCriteria[acId]?.required_proof_layers ?? DEFAULT_LAYERS).map((layer) => `${acId}.${layer}`));
+    }
+    for (const [acId, ac] of Object.entries(acceptanceCriteria)) {
+        if (ac.related_plan_items.length === 0) {
+            ac.related_plan_items = Object.keys(planItems);
+        }
+    }
+    state.graph.plan_items = planItems;
+    state.graph.acceptance_criteria = acceptanceCriteria;
+    state.graph.proof_layers = {};
+    for (const [acId, ac] of Object.entries(acceptanceCriteria)) {
+        for (const layer of ac.required_proof_layers) {
+            state.graph.proof_layers[`${acId}.${layer}`] = { required: true, status: "missing", evidence_ids: [] };
+        }
+    }
+    state.graph.edges = Object.entries(planItems).flatMap(([planId, item]) => item.related_acs.map((acId) => ({ from: planId, to: acId, type: "supports" })));
+    recomputeStatuses(state);
+    await saveSuperpowersState(workdir, state);
+    await appendSuperpowersEvent(workdir, "graph_compiled", {
+        plan_items: Object.keys(planItems).length,
+        acceptance_criteria: Object.keys(acceptanceCriteria).length
+    });
+    return state;
+}
+function parsePlanItems(content) {
+    const items = {};
+    const matches = [...content.matchAll(/\b(PI-\d{3,})\b\s*[:.-]?\s*([^\n]*)/gi)];
+    for (const [index, match] of matches.entries()) {
+        const id = match[1].toUpperCase();
+        const block = blockAfter(content, match.index ?? 0, matches[index + 1]?.index);
+        items[id] = {
+            requirement: cleanText(match[2]) || firstLine(block) || id,
+            owner_surfaces: field(block, "owner_surfaces"),
+            forbidden_surfaces: field(block, "forbidden_surfaces"),
+            implementation_paths: field(block, "implementation_paths"),
+            required_tests: field(block, "required_tests"),
+            status: "not_started",
+            related_acs: field(block, "related_acs").map((item) => item.toUpperCase()),
+            required_proof_layers: []
+        };
+    }
+    if (Object.keys(items).length === 0) {
+        items["PI-001"] = {
+            requirement: firstLine(content) || "Implement technical realization plan",
+            owner_surfaces: [],
+            forbidden_surfaces: [],
+            implementation_paths: [],
+            required_tests: [],
+            status: "not_started",
+            related_acs: [],
+            required_proof_layers: []
+        };
+    }
+    return items;
+}
+function parseAcceptanceCriteria(content) {
+    const items = {};
+    const matches = [...content.matchAll(/\b(AC-\d{3,})\b\s*[:.-]?\s*([^\n]*)/gi)];
+    for (const [index, match] of matches.entries()) {
+        const id = match[1].toUpperCase();
+        const block = blockAfter(content, match.index ?? 0, matches[index + 1]?.index);
+        const layers = field(block, "required_proof_layers").map(normalizeLayer).filter(Boolean);
+        items[id] = {
+            scope: cleanText(match[2]) || firstLine(block) || id,
+            related_plan_items: field(block, "related_plan_items").map((item) => item.toUpperCase()),
+            required_proof_layers: layers.length > 0 ? layers : DEFAULT_LAYERS,
+            status: "not_run"
+        };
+    }
+    if (Object.keys(items).length === 0) {
+        items["AC-001"] = {
+            scope: firstLine(content) || "Acceptance checklist item",
+            related_plan_items: [],
+            required_proof_layers: DEFAULT_LAYERS,
+            status: "not_run"
+        };
+    }
+    return items;
+}
+function blockAfter(content, start, end) {
+    return content.slice(start, end ?? content.length);
+}
+function field(block, name) {
+    const pattern = new RegExp(`${name}\\s*:\\s*([^\\n]+)`, "i");
+    const match = pattern.exec(block);
+    return match ? asStringArray(match[1]) : [];
+}
+function normalizeLayer(value) {
+    return value.trim().toLowerCase().replace(/[- ]+/g, "_");
+}
+function firstLine(content) {
+    return cleanText(content.split(/\r?\n/).find((line) => cleanText(line)) ?? "");
+}
+function cleanText(value) {
+    return value.replace(/^[-#*\s]+/, "").trim();
+}

package/dist/lib/superpowers-task-derive.d.ts

@@ -0,0 +1,13 @@
+import { type SuperpowersTaskState } from "./superpowers-task-state-schema.js";
+export interface DerivedSuperpowersArtifacts {
+    matrix: Record<string, unknown>;
+    verdict: Record<string, unknown>;
+    files: string[];
+}
+export declare function deriveSuperpowersArtifacts(workdir: string): Promise<DerivedSuperpowersArtifacts>;
+export declare function deriveObjects(state: SuperpowersTaskState): {
+    matrix: Record<string, unknown>;
+    verdict: Record<string, unknown>;
+    progress: Record<string, unknown>;
+};
+export declare function derivedMatchesState(workdir: string, state: SuperpowersTaskState): Promise<string[]>;