project-tiny-context-harness 0.2.75 → 0.2.77

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

@@ -0,0 +1,202 @@
+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", "delivery", "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 delivery: {
+            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 type SuperpowersProductDeliveryScope = "system_capability_build" | "representative_sample_validation" | "full_population_operation" | "mixed_scope_requires_boundary";
+export type SuperpowersPlanDeliveryScope = "system_capability_build" | "representative_sample_validation" | "full_population_operation" | "out_of_scope_backlog";
+export type SuperpowersAcceptanceScope = "system_capability_build" | "representative_sample_validation" | "full_population_operation" | "full_population_not_required";
+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>[];
+    };
+    delivery: SuperpowersDeliveryState;
+    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: SuperpowersProgressState;
+    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 SuperpowersDeliveryState {
+    product_architecture_scope: SuperpowersProductArchitectureScope;
+    scope_conflicts: string[];
+}
+export interface SuperpowersProductArchitectureScope {
+    delivery_scope: SuperpowersProductDeliveryScope | "";
+    full_population_required: boolean | null;
+    representative_samples_validate: string[];
+    representative_samples_do_not_validate: string[];
+    out_of_scope_backlog: string[];
+}
+export interface SuperpowersProgressState {
+    system_capability_progress: Record<string, unknown>;
+    representative_sample_progress: Record<string, unknown>;
+    real_object_coverage: Record<string, unknown>;
+    full_population_operation_progress: Record<string, unknown>;
+    [key: string]: unknown;
+}
+export interface SuperpowersPlanItem {
+    requirement: string;
+    delivery_scope: SuperpowersPlanDeliveryScope | "";
+    capability_target: string;
+    representative_samples: string[];
+    full_population_boundary: string;
+    non_required_population: 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;
+    acceptance_scope: SuperpowersAcceptanceScope | "";
+    ac_validates: string[];
+    ac_does_not_validate: string[];
+    sample_boundary: string;
+    full_population_required: boolean | null;
+    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,44 @@
+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", "delivery", "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" },
+        delivery: { 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,16 @@
+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 emptyProgressState(): SuperpowersTaskState["progress"];
+export declare function sourceRecords(workdir: string): Promise<SuperpowersTaskState["sources"]>;
+export declare function sha256(value: string): string;
+export declare function stableJson(value: unknown): string;

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

@@ -0,0 +1,241 @@
+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: []
+        },
+        delivery: {
+            product_architecture_scope: {
+                delivery_scope: "",
+                full_population_required: null,
+                representative_samples_validate: [],
+                representative_samples_do_not_validate: [],
+                out_of_scope_backlog: []
+            },
+            scope_conflicts: []
+        },
+        graph: {
+            plan_items: {},
+            acceptance_criteria: {},
+            proof_layers: {},
+            edges: []
+        },
+        slices: [],
+        evidence: [],
+        gates: {},
+        progress: emptyProgressState(),
+        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 function emptyProgressState() {
+    return {
+        system_capability_progress: { status: "not_started" },
+        representative_sample_progress: { status: "not_started" },
+        real_object_coverage: { status: "unknown" },
+        full_population_operation_progress: { status: "not_in_scope" }
+    };
+}
+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;