project-tiny-context-harness 0.2.74 → 0.2.76

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

@@ -0,0 +1,192 @@
+import path from "node:path";
+import { ensureDir, pathExists, readText, writeTextIfChanged } from "./fs.js";
+import { stableJson, loadSuperpowersState } from "./superpowers-task-state.js";
+export async function deriveSuperpowersArtifacts(workdir) {
+    const state = await loadSuperpowersState(workdir);
+    const derived = deriveObjects(state);
+    const derivedDir = path.join(workdir, "derived");
+    await ensureDir(derivedDir);
+    const files = [];
+    await writeDerived(files, path.join(derivedDir, "plan-conformance-matrix.json"), stableJson(derived.matrix));
+    await writeDerived(files, path.join(derivedDir, "final-acceptance-verdict.json"), stableJson(derived.verdict));
+    await writeDerived(files, path.join(derivedDir, "progress-ledger.json"), stableJson(derived.progress));
+    await writeDerived(files, path.join(derivedDir, "plan-conformance-matrix.md"), matrixMarkdown(derived.matrix));
+    await writeDerived(files, path.join(derivedDir, "final-acceptance-verdict.md"), verdictMarkdown(derived.verdict));
+    await writeDerived(files, path.join(derivedDir, "local-audit.md"), localAuditMarkdown(state));
+    await writeDerived(files, path.join(derivedDir, "progress-ledger.md"), progressMarkdown(derived.progress));
+    await writeDerived(files, path.join(derivedDir, "evidence-index.md"), evidenceMarkdown(state));
+    await writeDerived(files, path.join(derivedDir, "context-alignment.md"), contextMarkdown(state));
+    await writeDerived(files, path.join(derivedDir, "final-summary.md"), finalSummaryMarkdown(state, derived.verdict));
+    return { matrix: derived.matrix, verdict: derived.verdict, files };
+}
+export function deriveObjects(state) {
+    const matrixRows = Object.entries(state.graph.plan_items).map(([planItemId, item]) => {
+        const relatedAcs = item.related_acs;
+        const requiredLayers = item.required_proof_layers;
+        const missingLayers = requiredLayers.filter((layerId) => state.graph.proof_layers[layerId]?.status !== "satisfied");
+        const evidenceIds = evidenceForLayers(state, requiredLayers);
+        return {
+            plan_item_id: planItemId,
+            plan_requirement: item.requirement,
+            acceptance_ids: relatedAcs,
+            status: missingLayers.length === 0 && requiredLayers.length > 0 ? "complete" : evidenceIds.length > 0 ? "partial" : item.status,
+            conformance_type: item.owner_surfaces.length > 0 ? "product_surface" : "implementation",
+            owner_surface: item.owner_surfaces[0] ?? "",
+            forbidden_primary_surfaces: item.forbidden_surfaces,
+            negative_surface_checks: item.forbidden_surfaces.map((surface) => `confirmed ${surface} is not the owner surface`),
+            default_visibility_required: item.owner_surfaces.length > 0,
+            real_page_evidence: evidenceText(state, evidenceIds, "browser"),
+            context_fact_refs: [],
+            expected_surfaces: item.owner_surfaces.length > 0 ? ["ui", "runtime"] : ["code"],
+            implemented_paths: item.implementation_paths,
+            missing_paths: [],
+            tests: item.required_tests,
+            runtime_evidence: evidenceText(state, evidenceIds, "runtime"),
+            artifact_evidence: evidenceText(state, evidenceIds, "artifact"),
+            required_proof_layers: requiredLayers,
+            satisfied_proof_layers: requiredLayers.filter((layerId) => state.graph.proof_layers[layerId]?.status === "satisfied"),
+            missing_required_layers: missingLayers,
+            evidence_ids: evidenceIds,
+            scope_assessment: missingLayers.length === 0 ? "full" : "partial",
+            drift: missingLayers.length === 0 ? "no drift detected" : "missing required proof layers"
+        };
+    });
+    const verdictRows = Object.entries(state.graph.acceptance_criteria).map(([acId, ac]) => {
+        const requiredLayers = ac.required_proof_layers.map((layer) => `${acId}.${layer}`);
+        const missingLayers = requiredLayers.filter((layerId) => state.graph.proof_layers[layerId]?.status !== "satisfied");
+        const evidenceIds = evidenceForLayers(state, requiredLayers);
+        const status = missingLayers.length === 0 && requiredLayers.length > 0 ? "complete" : evidenceIds.length > 0 ? "partial" : ac.status;
+        return {
+            ac_id: acId,
+            related_plan_item_ids: ac.related_plan_items,
+            status,
+            required_evidence: requiredLayers,
+            required_proof_chain: requiredLayers,
+            fresh_evidence: evidenceText(state, evidenceIds),
+            missing_evidence: [],
+            missing_required_layers: missingLayers,
+            contradictions: [],
+            context_fact_refs: [],
+            evidence_ids: evidenceIds,
+            drift_severity: "none",
+            sibling_substitution_used: false,
+            auditor_status: auditorStatus(state),
+            decision: status === "complete" ? "accept" : "continue"
+        };
+    });
+    const allComplete = verdictRows.length > 0 && verdictRows.every((row) => row.status === "complete");
+    const progress = {
+        complete_count: verdictRows.filter((row) => row.status === "complete").length,
+        partial_count: verdictRows.filter((row) => row.status === "partial").length,
+        acceptance_required_count: verdictRows.filter((row) => row.status !== "out_of_scope_NA").length,
+        missing_layer_count: verdictRows.reduce((sum, row) => sum + row.missing_required_layers.length, 0),
+        next_clusters: Object.entries(state.graph.proof_layers)
+            .filter(([, layer]) => layer.status !== "satisfied")
+            .slice(0, 5)
+            .map(([layerId]) => layerId)
+    };
+    return {
+        matrix: { overall_status: allComplete ? "complete" : "partial", items: matrixRows },
+        verdict: { overall_status: allComplete ? "complete" : "partial", acceptance_items: verdictRows },
+        progress
+    };
+}
+export async function derivedMatchesState(workdir, state) {
+    const errors = [];
+    const expected = deriveObjects(state);
+    await assertDerivedJson(workdir, "plan-conformance-matrix", expected.matrix, errors);
+    await assertDerivedJson(workdir, "final-acceptance-verdict", expected.verdict, errors);
+    return errors;
+}
+async function assertDerivedJson(workdir, basename, expected, errors) {
+    const file = path.join(workdir, "derived", `${basename}.json`);
+    if (!(await pathExists(file))) {
+        return;
+    }
+    const actual = JSON.parse(await readText(file));
+    if (stableJson(actual) !== stableJson(expected)) {
+        errors.push(`derived/${basename}.json does not match task-state.json; rerun ty-context superpowers derive`);
+    }
+}
+function evidenceForLayers(state, layerIds) {
+    return [...new Set(layerIds.flatMap((layerId) => state.graph.proof_layers[layerId]?.evidence_ids ?? []))];
+}
+function evidenceText(state, evidenceIds, type) {
+    return evidenceIds
+        .map((evidenceId) => state.evidence.find((item) => item.evidence_id === evidenceId))
+        .filter((item) => item && (!type || item.type === type || (type === "artifact" && item.artifact_paths.length > 0)))
+        .map((item) => {
+        const artifacts = item?.artifact_paths.join(", ");
+        return `${item?.type} ${item?.command ?? ""} ${artifacts}`.trim();
+    });
+}
+function auditorStatus(state) {
+    const auditor = state.gates.auditor;
+    if (auditor && typeof auditor === "object" && !Array.isArray(auditor) && typeof auditor.auditor_status === "string") {
+        return String(auditor.auditor_status);
+    }
+    return "not_run";
+}
+async function writeDerived(files, file, content) {
+    await writeTextIfChanged(file, `${content.trimEnd()}\n`);
+    files.push(file.split(path.sep).join("/"));
+}
+function matrixMarkdown(matrix) {
+    const rows = matrix.items ?? [];
+    return ["# Plan Conformance Matrix", "", ...rows.map((row) => `- ${row.plan_item_id}: ${row.status}`)].join("\n");
+}
+function verdictMarkdown(verdict) {
+    const rows = verdict.acceptance_items ?? [];
+    const complete = rows.filter((row) => row.status === "complete").length;
+    const partial = rows.filter((row) => row.status === "partial").length;
+    const required = rows.filter((row) => row.status !== "out_of_scope_NA").length;
+    const missing = rows.reduce((sum, row) => sum + ((row.missing_required_layers ?? []).length), 0);
+    return `# Final Acceptance Verdict
+
+<!-- generated:active-counts:start -->
+complete_count: ${complete}
+partial_count: ${partial}
+acceptance_required_count: ${required}
+missing_layer_count: ${missing}
+<!-- generated:active-counts:end -->
+
+${rows.map((row) => `- ${row.ac_id}: ${row.status}`).join("\n")}
+`;
+}
+function localAuditMarkdown(state) {
+    return `# Local Audit
+
+audit_task_complete: ${state.final.audit_task_complete}
+acceptance_target_status: ${state.final.acceptance_target_status}
+product_goal_complete: ${state.final.product_goal_complete}
+`;
+}
+function progressMarkdown(progress) {
+    return `# Progress Ledger
+
+\`\`\`json
+${stableJson(progress)}
+\`\`\`
+`;
+}
+function evidenceMarkdown(state) {
+    return [
+        "# Evidence Index",
+        "",
+        ...state.evidence.map((item) => `- ${item.evidence_id}: proves ${item.proves.join(", ")}; does_not_prove ${item.does_not_prove.join(", ")}`)
+    ].join("\n");
+}
+function contextMarkdown(state) {
+    return `# Context Alignment
+
+Product Context Delta: ${state.context.product_context_delta}
+Technical Context Delta: ${state.context.technical_context_delta}
+`;
+}
+function finalSummaryMarkdown(state, verdict) {
+    return `# Final Summary
+
+overall_status: ${verdict.overall_status}
+product_goal_complete: ${state.final.product_goal_complete}
+`;
+}

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

@@ -0,0 +1 @@
+export declare function appendSuperpowersEvent(workdir: string, eventType: string, payload?: Record<string, unknown>): Promise<void>;

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

@@ -0,0 +1,13 @@
+import path from "node:path";
+import { ensureDir, readText, writeTextIfChanged, pathExists } from "./fs.js";
+export async function appendSuperpowersEvent(workdir, eventType, payload = {}) {
+    const eventsPath = path.join(workdir, "events.ndjson");
+    await ensureDir(workdir);
+    const event = {
+        event_type: eventType,
+        created_at: new Date().toISOString(),
+        ...payload
+    };
+    const previous = (await pathExists(eventsPath)) ? await readText(eventsPath) : "";
+    await writeTextIfChanged(eventsPath, `${previous}${JSON.stringify(event)}\n`);
+}

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

@@ -0,0 +1,12 @@
+export declare function runSliceGate(workdir: string, sliceId: string): Promise<{
+    passed: boolean;
+    messages: string[];
+}>;
+export declare function runEpochGate(workdir: string, epochId: string): Promise<{
+    passed: boolean;
+    messages: string[];
+}>;
+export declare function runFinalGate(workdir: string): Promise<{
+    product_goal_complete: boolean;
+    errors: string[];
+}>;

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

@@ -0,0 +1,47 @@
+import { appendSuperpowersEvent } from "./superpowers-task-events.js";
+import { deriveSuperpowersArtifacts } from "./superpowers-task-derive.js";
+import { loadSuperpowersState, recomputeStatuses, saveSuperpowersState } from "./superpowers-task-state.js";
+import { allCompletionConditionsSatisfied, validateSuperpowersState } from "./superpowers-task-validator.js";
+export async function runSliceGate(workdir, sliceId) {
+    const state = await loadSuperpowersState(workdir);
+    const slice = state.slices.find((item) => item.slice_id === sliceId);
+    const messages = [];
+    if (!slice) {
+        messages.push(`slice not found: ${sliceId}`);
+    }
+    else if (!slice.progress_value?.type || slice.progress_value.closed_items.length === 0) {
+        messages.push(`slice ${sliceId} has no progress_value`);
+    }
+    await deriveSuperpowersArtifacts(workdir);
+    await appendSuperpowersEvent(workdir, "slice_gate", { slice_id: sliceId, passed: messages.length === 0 });
+    return { passed: messages.length === 0, messages };
+}
+export async function runEpochGate(workdir, epochId) {
+    await deriveSuperpowersArtifacts(workdir);
+    await appendSuperpowersEvent(workdir, "epoch_gate", { epoch_id: epochId, passed: true });
+    return { passed: true, messages: ["epoch derived artifacts refreshed"] };
+}
+export async function runFinalGate(workdir) {
+    const state = await loadSuperpowersState(workdir);
+    recomputeStatuses(state);
+    state.final.audit_task_complete = true;
+    state.meta.audit_task_complete = true;
+    state.gates.validator = { status: "not_run" };
+    await saveSuperpowersState(workdir, state);
+    await deriveSuperpowersArtifacts(workdir);
+    const report = await validateSuperpowersState(workdir, [workdir]);
+    const latest = await loadSuperpowersState(workdir);
+    const complete = report.errors.length === 0 && allCompletionConditionsSatisfied(latest);
+    latest.final.product_goal_complete = complete;
+    latest.meta.product_goal_complete = complete;
+    latest.final.acceptance_target_status = complete ? "complete" : "partial";
+    latest.meta.acceptance_target_status = latest.final.acceptance_target_status;
+    latest.final.audit_task_complete = true;
+    latest.meta.audit_task_complete = true;
+    latest.final.completion_basis = complete ? ["all_required_acs_complete", "validator_passed", "auditor_no_blocker"] : [];
+    latest.gates.validator = { status: report.errors.length === 0 ? "pass" : "blocked", errors: report.errors };
+    await saveSuperpowersState(workdir, latest);
+    await deriveSuperpowersArtifacts(workdir);
+    await appendSuperpowersEvent(workdir, "final_gate", { product_goal_complete: complete });
+    return { product_goal_complete: complete, errors: report.errors };
+}

package/dist/lib/superpowers-task-next-slices.d.ts

@@ -0,0 +1 @@
+export declare function nextSuperpowersSlices(workdir: string, limit?: number): Promise<string[]>;

package/dist/lib/superpowers-task-next-slices.js

@@ -0,0 +1,12 @@
+import { loadSuperpowersState } from "./superpowers-task-state.js";
+export async function nextSuperpowersSlices(workdir, limit = 5) {
+    const state = await loadSuperpowersState(workdir);
+    return Object.entries(state.graph.proof_layers)
+        .filter(([, layer]) => layer.required && layer.status !== "satisfied")
+        .slice(0, limit)
+        .map(([layerId], index) => {
+        const acId = layerId.split(".")[0];
+        const planId = Object.entries(state.graph.plan_items).find(([, item]) => item.related_acs.includes(acId))?.[0] ?? "PI";
+        return `${index + 1}. ${planId}/${acId}: close ${layerId}`;
+    });
+}

package/dist/lib/superpowers-task-state-schema.d.ts

@@ -0,0 +1,167 @@
+export declare const SUPERPOWERS_TASK_STATE_SCHEMA_VERSION = "superpowers-task-state-v1";
+export declare const SUPERPOWERS_TASK_STATE_JSON_SCHEMA: {
+    readonly $schema: "https://json-schema.org/draft/2020-12/schema";
+    readonly $id: "https://project-tiny-context-harness.local/superpowers-task-state.schema.json";
+    readonly title: "Superpowers Long-Task State";
+    readonly type: "object";
+    readonly required: readonly ["meta", "sources", "context", "graph", "slices", "evidence", "gates", "progress", "blockers", "final"];
+    readonly properties: {
+        readonly meta: {
+            readonly type: "object";
+            readonly required: readonly ["task_id", "plan_slug", "created_at", "updated_at", "schema_version", "product_goal_complete", "acceptance_target_status"];
+            readonly properties: {
+                readonly schema_version: {
+                    readonly const: "superpowers-task-state-v1";
+                };
+                readonly product_goal_complete: {
+                    readonly type: "boolean";
+                };
+                readonly acceptance_target_status: {
+                    readonly type: "string";
+                };
+            };
+        };
+        readonly sources: {
+            readonly type: "object";
+        };
+        readonly context: {
+            readonly type: "object";
+        };
+        readonly graph: {
+            readonly type: "object";
+        };
+        readonly slices: {
+            readonly type: "array";
+        };
+        readonly evidence: {
+            readonly type: "array";
+        };
+        readonly gates: {
+            readonly type: "object";
+        };
+        readonly progress: {
+            readonly type: "object";
+        };
+        readonly blockers: {
+            readonly type: "array";
+        };
+        readonly final: {
+            readonly type: "object";
+        };
+    };
+};
+export type SuperpowersProofLayerStatus = "missing" | "satisfied" | "invalidated" | "blocked";
+export type SuperpowersPlanItemStatus = "not_started" | "complete" | "partial" | "sampled_only" | "not_implemented" | "blocked" | "scope_changed_requires_user_approval" | "contradicted_by_current_state" | "out_of_scope_NA";
+export type SuperpowersAcceptanceStatus = "not_run" | "complete" | "partial" | "blocked" | "invalidated" | "out_of_scope_NA";
+export interface SuperpowersTaskState {
+    meta: {
+        task_id: string;
+        plan_slug: string;
+        created_at: string;
+        updated_at: string;
+        schema_version: typeof SUPERPOWERS_TASK_STATE_SCHEMA_VERSION;
+        goal_type: string;
+        product_goal_complete: boolean;
+        acceptance_target_status: string;
+        audit_task_complete: boolean;
+    };
+    sources: Record<string, SuperpowersSourceRecord>;
+    context: {
+        product_context_delta: "none" | "required";
+        technical_context_delta: "none" | "required";
+        source_to_context_coverage: Record<string, unknown>[];
+        context_to_implementation_binding: Record<string, unknown>[];
+    };
+    graph: {
+        plan_items: Record<string, SuperpowersPlanItem>;
+        acceptance_criteria: Record<string, SuperpowersAcceptanceCriterion>;
+        proof_layers: Record<string, SuperpowersProofLayer>;
+        edges: SuperpowersGraphEdge[];
+    };
+    slices: SuperpowersSliceRecord[];
+    evidence: SuperpowersEvidenceRecord[];
+    gates: Record<string, unknown>;
+    progress: Record<string, unknown>;
+    blockers: unknown[];
+    final: {
+        product_goal_complete: boolean;
+        acceptance_target_status: string;
+        audit_task_complete: boolean;
+        completion_basis: string[];
+    };
+}
+export interface SuperpowersSourceRecord {
+    path: string;
+    sha256: string;
+    authority: string;
+}
+export interface SuperpowersPlanItem {
+    requirement: string;
+    owner_surfaces: string[];
+    forbidden_surfaces: string[];
+    implementation_paths: string[];
+    required_tests: string[];
+    status: SuperpowersPlanItemStatus;
+    related_acs: string[];
+    required_proof_layers: string[];
+}
+export interface SuperpowersAcceptanceCriterion {
+    scope: string;
+    related_plan_items: string[];
+    required_proof_layers: string[];
+    status: SuperpowersAcceptanceStatus;
+}
+export interface SuperpowersProofLayer {
+    required: boolean;
+    status: SuperpowersProofLayerStatus;
+    evidence_ids: string[];
+}
+export interface SuperpowersGraphEdge {
+    from: string;
+    to: string;
+    type: "supports" | string;
+}
+export interface SuperpowersSliceRecord {
+    slice_id: string;
+    slice_goal: string;
+    touched_plan_items: string[];
+    touched_acs: string[];
+    missing_layer_classes?: string[];
+    code_changes: string[];
+    evidence_records: string[];
+    closed_layers: string[];
+    remaining_layers: string[];
+    blockers: unknown[];
+    cleanup_assertions: string[];
+    progress_value: {
+        type: string;
+        closed_items: string[];
+        why_it_reduces_rework: string;
+    };
+}
+export interface SuperpowersEvidenceRecord {
+    evidence_id: string;
+    slice_id: string;
+    type: string;
+    freshness: {
+        created_at: string;
+        valid_for: string;
+        stale_after: string | null;
+    };
+    command?: string;
+    artifact_paths: string[];
+    proves: string[];
+    does_not_prove: string[];
+    redaction: {
+        checked: boolean;
+        contains_secret: boolean;
+    };
+    reviewability: {
+        external_reviewer_can_reproduce: boolean;
+        reproduction_steps: string;
+    };
+    sibling_substitution_used?: boolean;
+    sibling_substitution_approval_source?: string;
+}
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
+export declare function asStringArray(value: unknown): string[];

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

@@ -0,0 +1,43 @@
+export const SUPERPOWERS_TASK_STATE_SCHEMA_VERSION = "superpowers-task-state-v1";
+export const SUPERPOWERS_TASK_STATE_JSON_SCHEMA = {
+    $schema: "https://json-schema.org/draft/2020-12/schema",
+    $id: "https://project-tiny-context-harness.local/superpowers-task-state.schema.json",
+    title: "Superpowers Long-Task State",
+    type: "object",
+    required: ["meta", "sources", "context", "graph", "slices", "evidence", "gates", "progress", "blockers", "final"],
+    properties: {
+        meta: {
+            type: "object",
+            required: ["task_id", "plan_slug", "created_at", "updated_at", "schema_version", "product_goal_complete", "acceptance_target_status"],
+            properties: {
+                schema_version: { const: SUPERPOWERS_TASK_STATE_SCHEMA_VERSION },
+                product_goal_complete: { type: "boolean" },
+                acceptance_target_status: { type: "string" }
+            }
+        },
+        sources: { type: "object" },
+        context: { type: "object" },
+        graph: { type: "object" },
+        slices: { type: "array" },
+        evidence: { type: "array" },
+        gates: { type: "object" },
+        progress: { type: "object" },
+        blockers: { type: "array" },
+        final: { type: "object" }
+    }
+};
+export function isRecord(value) {
+    return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}
+export function asStringArray(value) {
+    if (Array.isArray(value)) {
+        return value.flatMap(asStringArray);
+    }
+    if (value === undefined || value === null) {
+        return [];
+    }
+    return String(value)
+        .split(/[,;\n]/)
+        .map((item) => item.trim())
+        .filter(Boolean);
+}

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

@@ -0,0 +1,15 @@
+import { type SuperpowersTaskState } from "./superpowers-task-state-schema.js";
+export interface InitializeSuperpowersTaskOptions {
+    taskId?: string;
+    planSlug?: string;
+    goalType?: string;
+}
+export declare function initializeSuperpowersTask(workdir: string, options?: InitializeSuperpowersTaskOptions): Promise<SuperpowersTaskState>;
+export declare function loadSuperpowersState(workdir: string): Promise<SuperpowersTaskState>;
+export declare function saveSuperpowersState(workdir: string, state: SuperpowersTaskState): Promise<void>;
+export declare function applySliceDelta(workdir: string, deltaFile: string): Promise<SuperpowersTaskState>;
+export declare function refreshSourceHashes(workdir: string, state: SuperpowersTaskState): Promise<void>;
+export declare function recomputeStatuses(state: SuperpowersTaskState): void;
+export declare function sourceRecords(workdir: string): Promise<SuperpowersTaskState["sources"]>;
+export declare function sha256(value: string): string;
+export declare function stableJson(value: unknown): string;