project-tiny-context-harness 0.2.75 → 0.2.76

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

@@ -0,0 +1,223 @@
+import { createHash } from "node:crypto";
+import path from "node:path";
+import { ensureDir, pathExists, readText, writeTextIfChanged } from "./fs.js";
+import { appendSuperpowersEvent } from "./superpowers-task-events.js";
+import { SUPERPOWERS_TASK_STATE_JSON_SCHEMA, SUPERPOWERS_TASK_STATE_SCHEMA_VERSION, asStringArray, isRecord } from "./superpowers-task-state-schema.js";
+const SOURCE_FILES = {
+    product_architecture_source: {
+        path: "product-architecture-source.md",
+        authority: "intent_scope_boundaries"
+    },
+    technical_realization_plan: {
+        path: "technical-realization-plan.md",
+        authority: "plan_items_execution_blueprint_conformance"
+    },
+    acceptance_checklist: {
+        path: "acceptance-checklist.md",
+        authority: "acs_completion_semantics_proof_layers"
+    }
+};
+export async function initializeSuperpowersTask(workdir, options = {}) {
+    await ensureDir(path.join(workdir, "derived"));
+    await writeTextIfChanged(path.join(workdir, "task-state.schema.json"), `${stableJson(SUPERPOWERS_TASK_STATE_JSON_SCHEMA)}\n`);
+    for (const source of Object.values(SOURCE_FILES)) {
+        const target = path.join(workdir, source.path);
+        if (!(await pathExists(target))) {
+            await writeTextIfChanged(target, `# ${source.path.replace(/\.md$/, "").replace(/-/g, " ")}\n`);
+        }
+    }
+    const now = new Date().toISOString();
+    const state = {
+        meta: {
+            task_id: options.taskId ?? `SP-${compactDate(now)}-001`,
+            plan_slug: options.planSlug ?? path.basename(workdir),
+            created_at: now,
+            updated_at: now,
+            schema_version: SUPERPOWERS_TASK_STATE_SCHEMA_VERSION,
+            goal_type: options.goalType ?? "implementation",
+            product_goal_complete: false,
+            acceptance_target_status: "not_run",
+            audit_task_complete: false
+        },
+        sources: await sourceRecords(workdir),
+        context: {
+            product_context_delta: "none",
+            technical_context_delta: "none",
+            source_to_context_coverage: [],
+            context_to_implementation_binding: []
+        },
+        graph: {
+            plan_items: {},
+            acceptance_criteria: {},
+            proof_layers: {},
+            edges: []
+        },
+        slices: [],
+        evidence: [],
+        gates: {},
+        progress: {},
+        blockers: [],
+        final: {
+            product_goal_complete: false,
+            acceptance_target_status: "not_run",
+            audit_task_complete: false,
+            completion_basis: []
+        }
+    };
+    await saveSuperpowersState(workdir, state);
+    await appendSuperpowersEvent(workdir, "task_initialized", { task_id: state.meta.task_id });
+    return state;
+}
+export async function loadSuperpowersState(workdir) {
+    return JSON.parse(await readText(path.join(workdir, "task-state.json")));
+}
+export async function saveSuperpowersState(workdir, state) {
+    state.meta.updated_at = new Date().toISOString();
+    await writeTextIfChanged(path.join(workdir, "task-state.json"), `${stableJson(state)}\n`);
+}
+export async function applySliceDelta(workdir, deltaFile) {
+    const state = await loadSuperpowersState(workdir);
+    const delta = JSON.parse(await readText(deltaFile));
+    const sliceId = String(delta.slice_id ?? "");
+    const progressValue = isRecord(delta.progress_value) ? delta.progress_value : undefined;
+    if (!sliceId) {
+        throw new Error("slice_delta must include slice_id");
+    }
+    if (!progressValue || !String(progressValue.type ?? "").trim() || asStringArray(progressValue.closed_items).length === 0) {
+        throw new Error("slice_delta must include progress_value with type and closed_items");
+    }
+    const evidenceRecords = readEvidenceRecords(delta.evidence_records);
+    for (const evidence of evidenceRecords) {
+        const existingIndex = state.evidence.findIndex((item) => item.evidence_id === evidence.evidence_id);
+        if (existingIndex >= 0) {
+            state.evidence[existingIndex] = evidence;
+        }
+        else {
+            state.evidence.push(evidence);
+        }
+    }
+    const slice = {
+        slice_id: sliceId,
+        slice_goal: String(delta.slice_goal ?? ""),
+        touched_plan_items: asStringArray(delta.touched_plan_items),
+        touched_acs: asStringArray(delta.touched_acs),
+        missing_layer_classes: asStringArray(delta.missing_layer_classes),
+        code_changes: asStringArray(delta.code_changes),
+        evidence_records: evidenceRecords.map((item) => item.evidence_id),
+        closed_layers: asStringArray(delta.closed_layers),
+        remaining_layers: asStringArray(delta.remaining_layers),
+        blockers: Array.isArray(delta.blockers) ? delta.blockers : [],
+        cleanup_assertions: asStringArray(delta.cleanup_assertions),
+        progress_value: {
+            type: String(progressValue.type),
+            closed_items: asStringArray(progressValue.closed_items),
+            why_it_reduces_rework: String(progressValue.why_it_reduces_rework ?? "")
+        }
+    };
+    state.slices.push(slice);
+    for (const layerId of slice.closed_layers) {
+        const layer = state.graph.proof_layers[layerId];
+        if (!layer) {
+            continue;
+        }
+        layer.status = "satisfied";
+        layer.evidence_ids = unique([...layer.evidence_ids, ...evidenceRecords.filter((item) => item.proves.includes(layerId)).map((item) => item.evidence_id)]);
+    }
+    recomputeStatuses(state);
+    await saveSuperpowersState(workdir, state);
+    await appendSuperpowersEvent(workdir, "slice_delta_applied", { slice_id: sliceId });
+    return state;
+}
+export async function refreshSourceHashes(workdir, state) {
+    state.sources = await sourceRecords(workdir);
+}
+export function recomputeStatuses(state) {
+    for (const [acId, ac] of Object.entries(state.graph.acceptance_criteria)) {
+        const layerIds = ac.required_proof_layers.map((layer) => `${acId}.${layer}`);
+        if (layerIds.length === 0) {
+            ac.status = "not_run";
+        }
+        else if (layerIds.every((layerId) => state.graph.proof_layers[layerId]?.status === "satisfied")) {
+            ac.status = "complete";
+        }
+        else if (layerIds.some((layerId) => state.graph.proof_layers[layerId]?.status === "satisfied")) {
+            ac.status = "partial";
+        }
+        else {
+            ac.status = "not_run";
+        }
+    }
+    for (const item of Object.values(state.graph.plan_items)) {
+        if (item.related_acs.length > 0 && item.related_acs.every((acId) => state.graph.acceptance_criteria[acId]?.status === "complete")) {
+            item.status = "complete";
+        }
+        else if (item.related_acs.some((acId) => state.graph.acceptance_criteria[acId]?.status === "partial")) {
+            item.status = "partial";
+        }
+        else if (item.status === "complete") {
+            item.status = "not_started";
+        }
+    }
+}
+export async function sourceRecords(workdir) {
+    const sources = {};
+    for (const [key, source] of Object.entries(SOURCE_FILES)) {
+        const file = path.join(workdir, source.path);
+        const content = (await pathExists(file)) ? await readText(file) : "";
+        sources[key] = { path: source.path, sha256: sha256(content), authority: source.authority };
+    }
+    return sources;
+}
+export function sha256(value) {
+    return createHash("sha256").update(value).digest("hex");
+}
+export function stableJson(value) {
+    return JSON.stringify(sortJson(value), null, 2);
+}
+function readEvidenceRecords(value) {
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    return value.filter(isRecord).map((item) => ({
+        evidence_id: String(item.evidence_id ?? item.evidenceId ?? ""),
+        slice_id: String(item.slice_id ?? item.sliceId ?? ""),
+        type: String(item.type ?? ""),
+        freshness: isRecord(item.freshness)
+            ? {
+                created_at: String(item.freshness.created_at ?? ""),
+                valid_for: String(item.freshness.valid_for ?? ""),
+                stale_after: item.freshness.stale_after === null ? null : item.freshness.stale_after === undefined ? null : String(item.freshness.stale_after)
+            }
+            : { created_at: "", valid_for: "", stale_after: null },
+        command: item.command === undefined ? undefined : String(item.command),
+        artifact_paths: asStringArray(item.artifact_paths),
+        proves: asStringArray(item.proves),
+        does_not_prove: asStringArray(item.does_not_prove),
+        redaction: isRecord(item.redaction)
+            ? { checked: item.redaction.checked === true, contains_secret: item.redaction.contains_secret === true }
+            : { checked: false, contains_secret: false },
+        reviewability: isRecord(item.reviewability)
+            ? {
+                external_reviewer_can_reproduce: item.reviewability.external_reviewer_can_reproduce === true,
+                reproduction_steps: String(item.reviewability.reproduction_steps ?? "")
+            }
+            : { external_reviewer_can_reproduce: false, reproduction_steps: "" },
+        sibling_substitution_used: item.sibling_substitution_used === true,
+        sibling_substitution_approval_source: item.sibling_substitution_approval_source === undefined ? undefined : String(item.sibling_substitution_approval_source)
+    }));
+}
+function sortJson(value) {
+    if (Array.isArray(value)) {
+        return value.map(sortJson);
+    }
+    if (!isRecord(value)) {
+        return value;
+    }
+    return Object.fromEntries(Object.keys(value).sort().map((key) => [key, sortJson(value[key])]));
+}
+function unique(values) {
+    return [...new Set(values.filter(Boolean))];
+}
+function compactDate(value) {
+    return value.slice(0, 10).replace(/-/g, "");
+}

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

@@ -0,0 +1,4 @@
+import { type SuperpowersTaskState } from "./superpowers-task-state-schema.js";
+import type { ValidatorReport } from "./validators.js";
+export declare function validateSuperpowersState(projectRoot: string, args?: string[]): Promise<ValidatorReport>;
+export declare function allCompletionConditionsSatisfied(state: SuperpowersTaskState): boolean;

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

@@ -0,0 +1,238 @@
+import path from "node:path";
+import { pathExists, readText } from "./fs.js";
+import { findSensitiveEvidence } from "./plan-acceptance-evidence.js";
+import { primitiveText, repoRelative, resolveInputDir } from "./plan-validator-common.js";
+import { derivedMatchesState } from "./superpowers-task-derive.js";
+import { loadSuperpowersState, sha256 } from "./superpowers-task-state.js";
+import { isRecord } from "./superpowers-task-state-schema.js";
+export async function validateSuperpowersState(projectRoot, args = []) {
+    const info = [];
+    const warnings = [];
+    const hygiene = [];
+    const errors = [];
+    const targetDir = await resolveInputDir(projectRoot, args[0], "tmp/ty-context/plan-acceptance");
+    const statePath = path.join(targetDir, "task-state.json");
+    if (!(await pathExists(statePath))) {
+        return { info, warnings, hygiene, errors: [`superpowers task state is missing: ${repoRelative(projectRoot, statePath)}`] };
+    }
+    let state;
+    try {
+        state = await loadSuperpowersState(targetDir);
+    }
+    catch (error) {
+        return {
+            info,
+            warnings,
+            hygiene,
+            errors: [`${repoRelative(projectRoot, statePath)} is not valid JSON: ${error instanceof Error ? error.message : String(error)}`]
+        };
+    }
+    validateShape(state, errors);
+    if (!hasUsableShape(state)) {
+        info.push("checked superpowers task state with unusable or incomplete shape");
+        return { info, warnings, hygiene, errors };
+    }
+    await validateSourceHashes(targetDir, state, errors);
+    validateGraphReferences(state, errors);
+    validateEvidenceRecords(state, errors);
+    validateProofLayers(state, errors);
+    validateAuditor(state, errors);
+    validateFinalCompletion(state, errors);
+    errors.push(...(await derivedMatchesState(targetDir, state)));
+    info.push(`checked superpowers task state ${repoRelative(projectRoot, targetDir)} plan_items=${Object.keys(state.graph?.plan_items ?? {}).length} acs=${Object.keys(state.graph?.acceptance_criteria ?? {}).length} evidence=${state.evidence?.length ?? 0}`);
+    if (errors.length === 0) {
+        info.push("Superpowers task state validation passed");
+    }
+    return { info, warnings, hygiene, errors };
+}
+async function validateSourceHashes(workdir, state, errors) {
+    for (const [key, source] of Object.entries(state.sources ?? {})) {
+        const file = path.join(workdir, source.path);
+        if (!(await pathExists(file))) {
+            errors.push(`source file is missing for ${key}: ${source.path}`);
+            continue;
+        }
+        const actual = sha256(await readText(file));
+        if (actual !== source.sha256) {
+            errors.push(`source hash mismatch for ${key}: expected ${source.sha256}, actual ${actual}; recompile graph before continuing`);
+        }
+    }
+}
+function validateShape(state, errors) {
+    if (state.meta?.schema_version !== "superpowers-task-state-v1") {
+        errors.push("task-state.json schema_version must be superpowers-task-state-v1");
+    }
+    for (const key of ["meta", "sources", "context", "graph", "slices", "evidence", "gates", "progress", "blockers", "final"]) {
+        if (!(key in state)) {
+            errors.push(`task-state.json is missing section: ${key}`);
+        }
+    }
+}
+function hasUsableShape(state) {
+    const candidate = state;
+    return (isRecord(candidate.meta) &&
+        isRecord(candidate.sources) &&
+        isRecord(candidate.context) &&
+        isRecord(candidate.graph) &&
+        isRecord(candidate.graph.plan_items) &&
+        isRecord(candidate.graph.acceptance_criteria) &&
+        isRecord(candidate.graph.proof_layers) &&
+        Array.isArray(candidate.slices) &&
+        Array.isArray(candidate.evidence) &&
+        isRecord(candidate.gates) &&
+        isRecord(candidate.progress) &&
+        Array.isArray(candidate.blockers) &&
+        isRecord(candidate.final));
+}
+function validateGraphReferences(state, errors) {
+    const planIds = new Set(Object.keys(state.graph?.plan_items ?? {}));
+    const acIds = new Set(Object.keys(state.graph?.acceptance_criteria ?? {}));
+    for (const [planId, item] of Object.entries(state.graph?.plan_items ?? {})) {
+        for (const acId of item.related_acs ?? []) {
+            if (!acIds.has(acId)) {
+                errors.push(`plan item ${planId} references unknown AC: ${acId}`);
+            }
+        }
+        for (const layerId of item.required_proof_layers ?? []) {
+            if (!state.graph.proof_layers[layerId]) {
+                errors.push(`plan item ${planId} references unknown proof layer: ${layerId}`);
+            }
+        }
+    }
+    for (const [acId, ac] of Object.entries(state.graph?.acceptance_criteria ?? {})) {
+        for (const planId of ac.related_plan_items ?? []) {
+            if (!planIds.has(planId)) {
+                errors.push(`AC ${acId} references unknown plan item: ${planId}`);
+            }
+        }
+        for (const layer of ac.required_proof_layers ?? []) {
+            const layerId = `${acId}.${layer}`;
+            if (!state.graph.proof_layers[layerId]) {
+                errors.push(`AC ${acId} references unknown proof layer: ${layerId}`);
+            }
+        }
+    }
+}
+function validateEvidenceRecords(state, errors) {
+    const ids = new Set();
+    for (const [index, evidence] of (state.evidence ?? []).entries()) {
+        const label = `evidence ${evidence.evidence_id || index + 1}`;
+        if (!evidence.evidence_id) {
+            errors.push(`${label} is missing evidence_id`);
+        }
+        else if (ids.has(evidence.evidence_id)) {
+            errors.push(`${label} duplicates evidence_id`);
+        }
+        ids.add(evidence.evidence_id);
+        if (!evidence.slice_id) {
+            errors.push(`${label} is missing slice_id`);
+        }
+        if ((evidence.proves ?? []).length === 0) {
+            errors.push(`${label} is missing proves`);
+        }
+        if ((evidence.does_not_prove ?? []).length === 0) {
+            errors.push(`${label} is missing does_not_prove`);
+        }
+        if (!evidence.freshness?.created_at || !evidence.freshness.valid_for) {
+            errors.push(`${label} is missing freshness`);
+        }
+        if (evidence.freshness?.stale_after && Date.parse(evidence.freshness.stale_after) < Date.now()) {
+            errors.push(`${label} is stale evidence: ${evidence.freshness.stale_after}`);
+        }
+        if (evidence.redaction?.checked !== true) {
+            errors.push(`${label} redaction.checked must be true`);
+        }
+        if (evidence.redaction?.contains_secret === true) {
+            errors.push(`${label} redaction contains_secret is true`);
+        }
+        if (evidence.reviewability?.external_reviewer_can_reproduce !== true || !evidence.reviewability.reproduction_steps) {
+            errors.push(`${label} is not reviewable by an external reviewer`);
+        }
+        const sensitive = findSensitiveEvidence(primitiveText(evidence));
+        if (sensitive) {
+            errors.push(`${label} contains raw secret/token/cookie material: ${sensitive}`);
+        }
+        if (evidence.sibling_substitution_used === true && !evidence.sibling_substitution_approval_source) {
+            errors.push(`${label} uses sibling substitution without approval`);
+        }
+        for (const proofLayer of evidence.proves ?? []) {
+            if (proofLayer.endsWith(".runtime") && /\b(mock|unit|viewmodel)\b/i.test(evidence.type)) {
+                errors.push(`${label} runtime proof cannot be mock/unit/viewmodel only`);
+            }
+            if (proofLayer.endsWith(".ui_browser") && !/\b(browser|ui_browser|screenshot)\b/i.test(evidence.type)) {
+                errors.push(`${label} UI proof must use browser owner surface evidence`);
+            }
+        }
+    }
+}
+function validateProofLayers(state, errors) {
+    const evidenceById = new Map((state.evidence ?? []).map((item) => [item.evidence_id, item]));
+    for (const [layerId, layer] of Object.entries(state.graph?.proof_layers ?? {})) {
+        if (layer.status === "satisfied" && layer.evidence_ids.length === 0) {
+            errors.push(`proof layer ${layerId} is satisfied but has no evidence_ids`);
+        }
+        for (const evidenceId of layer.evidence_ids ?? []) {
+            const evidence = evidenceById.get(evidenceId);
+            if (!evidence) {
+                errors.push(`proof layer ${layerId} references unknown evidence_id: ${evidenceId}`);
+                continue;
+            }
+            if (!evidence.proves.includes(layerId)) {
+                errors.push(`proof layer ${layerId} references ${evidenceId} but that evidence does not prove it`);
+            }
+        }
+    }
+}
+function validateAuditor(state, errors) {
+    const auditor = state.gates?.auditor;
+    if (!isRecord(auditor)) {
+        return;
+    }
+    const status = String(auditor.auditor_status ?? "").toLowerCase();
+    const findings = Array.isArray(auditor.findings) ? auditor.findings : [];
+    if (status === "blocking_gap" || findings.some((finding) => isRecord(finding) && String(finding.severity ?? "").toLowerCase() === "blocking")) {
+        errors.push(`auditor blocker remains: ${findings.map((finding) => (isRecord(finding) ? finding.id : "")).filter(Boolean).join(", ") || status}`);
+    }
+}
+function validateFinalCompletion(state, errors) {
+    const finalComplete = state.final?.product_goal_complete === true || state.meta?.product_goal_complete === true;
+    if (!finalComplete) {
+        return;
+    }
+    const planEntries = Object.entries(state.graph.plan_items);
+    const acEntries = Object.entries(state.graph.acceptance_criteria);
+    const layerEntries = Object.entries(state.graph.proof_layers);
+    if (planEntries.length === 0 || acEntries.length === 0 || layerEntries.length === 0) {
+        errors.push("product_goal_complete=true but task graph is empty or uncompiled");
+    }
+    const incompleteAcs = acEntries.filter(([, ac]) => ac.status !== "complete" && ac.status !== "out_of_scope_NA");
+    const incompletePlans = planEntries.filter(([, item]) => item.status !== "complete" && item.status !== "out_of_scope_NA");
+    const incompleteLayers = layerEntries.filter(([, layer]) => layer.required && layer.status !== "satisfied");
+    if (incompleteAcs.length > 0 || incompletePlans.length > 0 || incompleteLayers.length > 0) {
+        errors.push("product_goal_complete=true but required plan items, ACs or proof layers are incomplete");
+    }
+    if (state.context.product_context_delta === "required" || state.context.technical_context_delta === "required") {
+        const unresolvedCoverage = (state.context.source_to_context_coverage ?? []).filter((row) => /\b(new_context_required|needs_user_decision|under_scoped)\b/i.test(primitiveText(row)));
+        if (unresolvedCoverage.length > 0) {
+            errors.push("product_goal_complete=true but Context Delta coverage is unresolved");
+        }
+    }
+}
+export function allCompletionConditionsSatisfied(state) {
+    const errors = [];
+    validateShape(state, errors);
+    if (!hasUsableShape(state)) {
+        return false;
+    }
+    validateGraphReferences(state, errors);
+    validateEvidenceRecords(state, errors);
+    validateProofLayers(state, errors);
+    validateAuditor(state, errors);
+    const planItems = Object.values(state.graph.plan_items);
+    const acceptanceCriteria = Object.values(state.graph.acceptance_criteria);
+    const proofLayers = Object.values(state.graph.proof_layers);
+    const allPlansComplete = planItems.every((item) => item.status === "complete" || item.status === "out_of_scope_NA");
+    const allAcsComplete = acceptanceCriteria.every((ac) => ac.status === "complete" || ac.status === "out_of_scope_NA");
+    const allLayersSatisfied = proofLayers.every((layer) => !layer.required || layer.status === "satisfied");
+    return errors.length === 0 && planItems.length > 0 && acceptanceCriteria.length > 0 && proofLayers.length > 0 && allPlansComplete && allAcsComplete && allLayersSatisfied;
+}

package/dist/lib/validators.js

@@ -5,13 +5,15 @@ import { listFiles, pathExists, readText } from "./fs.js";
 import { runModularityCheck } from "./modularity.js";
 import { validatePlanAcceptance } from "./plan-acceptance-validator.js";
 import { validatePlanContract } from "./plan-contract-validator.js";
+import { validateSuperpowersState } from "./superpowers-task-validator.js";
 import { unsupportedSchemaMessage } from "./schema-guard.js";
 const VALIDATORS = {
     "validate-context": validateContext,
     "validate-code-modularity": validateCodeModularity,
     "validate-harness": validateHarness,
     "validate-plan-contract": validatePlanContract,
-    "validate-plan-acceptance": validatePlanAcceptance
+    "validate-plan-acceptance": validatePlanAcceptance,
+    "validate-superpowers-state": validateSuperpowersState
 };
 const GLOBAL_REQUIRED_SECTIONS = [
     ...sectionSpecs([
@@ -77,7 +79,7 @@ export async function runValidator(projectRoot, gate, args = []) {
         return {
             info: [],
             errors: [
-                `unknown validator: ${gate}. Minimal Context Harness supports validate-context, validate-code-modularity, validate-harness, validate-plan-contract and validate-plan-acceptance only.`
+                `unknown validator: ${gate}. Minimal Context Harness supports validate-context, validate-code-modularity, validate-harness, validate-plan-contract, validate-plan-acceptance and validate-superpowers-state only.`
             ]
         };
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "project-tiny-context-harness",
-  "version": "0.2.75",
+  "version": "0.2.76",
   "description": "Minimal project memory and validation harness for AI coding agents.",
   "license": "MIT",
   "author": "Seven128",