project-tiny-context-harness 0.2.78 → 0.2.80

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

@@ -0,0 +1,190 @@
+import { fieldArray, fieldBoolean, fieldLine, fieldText, parseDocumentFields, parseHeadingDefinitions } from "./superpowers-task-source-parser.js";
+export const DEFAULT_LAYERS = ["code", "test"];
+const PRODUCT_DELIVERY_SCOPES = new Set(["system_capability_build", "representative_sample_validation", "full_population_operation", "mixed_scope_requires_boundary"]);
+const PLAN_DELIVERY_SCOPES = new Set(["system_capability_build", "representative_sample_validation", "full_population_operation", "out_of_scope_backlog"]);
+const ACCEPTANCE_SCOPES = new Set(["system_capability_build", "representative_sample_validation", "full_population_operation", "full_population_not_required"]);
+const PRODUCT_FIELDS = new Set([
+    "delivery_scope",
+    "full_population_required",
+    "representative_samples_validate",
+    "representative_samples_do_not_validate",
+    "out_of_scope_backlog",
+    "source_authority",
+    "product_goal",
+    "surface_ia_lock",
+    "decision_lock",
+    "context_delta",
+    "source_to_context_coverage",
+    "acceptance_semantics",
+    "impact"
+]);
+const PLAN_FIELDS = new Set([
+    "delivery_scope",
+    "capability_target",
+    "representative_samples",
+    "full_population_boundary",
+    "non_required_population",
+    "owner_surfaces",
+    "forbidden_surfaces",
+    "implementation_paths",
+    "required_tests",
+    "related_acs",
+    "requirement_ref",
+    "decision_id",
+    "proof_layer_ids",
+    "api_schema_changes",
+    "state_machine",
+    "data_flow",
+    "worker_runtime_behavior",
+    "ui_ia_changes",
+    "migration_plan",
+    "evidence_artifacts",
+    "explicit_no_test_scope",
+    "non_completing_shortcuts",
+    "substitution_policy",
+    "drift_severity",
+    "partial_conditions",
+    "blockers",
+    "context_fact_refs"
+]);
+const ACCEPTANCE_FIELDS = new Set([
+    "checklist_source",
+    "acceptance_scope",
+    "ac_validates",
+    "ac_does_not_validate",
+    "sample_boundary",
+    "full_population_required",
+    "related_plan_items",
+    "required_proof_layers",
+    "ac_type",
+    "proof_chain",
+    "verification_method",
+    "fail_conditions",
+    "invalid_evidence",
+    "substitution_policy",
+    "missing_layer_downgrade",
+    "auditor_expectation",
+    "out_of_scope_na_approval_source",
+    "required_test_ids",
+    "explicit_no_test_scope",
+    "hard_blockers",
+    "validates_explanation",
+    "does_not_validate_explanation",
+    "final_evidence_expected",
+    "test_cases"
+]);
+export function parseProductArchitectureScope(content, sourceFile) {
+    const fields = parseDocumentFields(content, sourceFile, PRODUCT_FIELDS);
+    const errors = [];
+    const scope = {
+        delivery_scope: requireEnum(errors, "Product / Architecture Source", "delivery_scope", fields, PRODUCT_DELIVERY_SCOPES, sourceFile, 1),
+        full_population_required: requireBoolean(errors, "Product / Architecture Source", "full_population_required", fields, sourceFile, 1),
+        representative_samples_validate: requireArray(errors, "Product / Architecture Source", "representative_samples_validate", fields, sourceFile, 1),
+        representative_samples_do_not_validate: requireArray(errors, "Product / Architecture Source", "representative_samples_do_not_validate", fields, sourceFile, 1),
+        out_of_scope_backlog: requireArray(errors, "Product / Architecture Source", "out_of_scope_backlog", fields, sourceFile, 1)
+    };
+    throwCompileErrors(errors);
+    return scope;
+}
+export function parsePlanItems(content, sourceFile) {
+    const items = {};
+    const errors = [];
+    for (const definition of parseHeadingDefinitions(content, { kind: "PI", sourceFile, allowedFields: PLAN_FIELDS })) {
+        const fields = definition.fields;
+        items[definition.id] = {
+            requirement: definition.title,
+            source_file: definition.source_file,
+            source_start_line: definition.source_start_line,
+            source_end_line: definition.source_end_line,
+            delivery_scope: requireEnum(errors, definition.id, "delivery_scope", fields, PLAN_DELIVERY_SCOPES, sourceFile, definition.source_start_line),
+            capability_target: requireText(errors, definition.id, "capability_target", fields, sourceFile, definition.source_start_line),
+            representative_samples: requireArray(errors, definition.id, "representative_samples", fields, sourceFile, definition.source_start_line),
+            full_population_boundary: requireText(errors, definition.id, "full_population_boundary", fields, sourceFile, definition.source_start_line),
+            non_required_population: requireArray(errors, definition.id, "non_required_population", fields, sourceFile, definition.source_start_line),
+            owner_surfaces: optionalArray(fields, "owner_surfaces"),
+            forbidden_surfaces: optionalArray(fields, "forbidden_surfaces"),
+            implementation_paths: optionalArray(fields, "implementation_paths"),
+            required_tests: optionalArray(fields, "required_tests"),
+            status: "not_started",
+            related_acs: optionalArray(fields, "related_acs").map((item) => item.toUpperCase()),
+            required_proof_layers: []
+        };
+    }
+    throwCompileErrors(errors);
+    return items;
+}
+export function parseAcceptanceCriteria(content, sourceFile) {
+    const items = {};
+    const errors = [];
+    for (const definition of parseHeadingDefinitions(content, { kind: "AC", sourceFile, allowedFields: ACCEPTANCE_FIELDS })) {
+        const fields = definition.fields;
+        const layers = optionalArray(fields, "required_proof_layers").map(normalizeLayer).filter(Boolean);
+        items[definition.id] = {
+            scope: definition.title,
+            source_file: definition.source_file,
+            source_start_line: definition.source_start_line,
+            source_end_line: definition.source_end_line,
+            acceptance_scope: requireEnum(errors, definition.id, "acceptance_scope", fields, ACCEPTANCE_SCOPES, sourceFile, definition.source_start_line),
+            ac_validates: requireArray(errors, definition.id, "ac_validates", fields, sourceFile, definition.source_start_line),
+            ac_does_not_validate: requireArray(errors, definition.id, "ac_does_not_validate", fields, sourceFile, definition.source_start_line),
+            sample_boundary: requireText(errors, definition.id, "sample_boundary", fields, sourceFile, definition.source_start_line),
+            full_population_required: requireBoolean(errors, definition.id, "full_population_required", fields, sourceFile, definition.source_start_line),
+            related_plan_items: optionalArray(fields, "related_plan_items").map((item) => item.toUpperCase()),
+            required_proof_layers: layers.length > 0 ? layers : DEFAULT_LAYERS,
+            status: "not_run"
+        };
+    }
+    throwCompileErrors(errors);
+    return items;
+}
+function normalizeLayer(value) {
+    return value.trim().toLowerCase().replace(/[- ]+/g, "_");
+}
+function requireEnum(errors, label, name, fields, allowed, sourceFile, fallbackLine) {
+    const value = fieldText(fields, name);
+    const line = fieldLine(fields, name) ?? fallbackLine;
+    if (!value) {
+        errors.push(`${label} missing ${name} at ${sourceFile}:${line}`);
+        return "";
+    }
+    if (!allowed.has(value)) {
+        errors.push(`${label} invalid ${name}: ${value} at ${sourceFile}:${line}; allowed: ${[...allowed].join(", ")}`);
+    }
+    return value;
+}
+function requireText(errors, label, name, fields, sourceFile, fallbackLine) {
+    const value = fieldText(fields, name);
+    const line = fieldLine(fields, name) ?? fallbackLine;
+    if (!value) {
+        errors.push(`${label} missing ${name} at ${sourceFile}:${line}`);
+    }
+    return value;
+}
+function requireArray(errors, label, name, fields, sourceFile, fallbackLine) {
+    const line = fieldLine(fields, name) ?? fallbackLine;
+    if (!fields[name]) {
+        errors.push(`${label} missing ${name} at ${sourceFile}:${line}`);
+        return [];
+    }
+    return fieldArray(fields, name);
+}
+function requireBoolean(errors, label, name, fields, sourceFile, fallbackLine) {
+    const line = fieldLine(fields, name) ?? fallbackLine;
+    if (!fields[name]) {
+        errors.push(`${label} missing ${name} at ${sourceFile}:${line}`);
+        return null;
+    }
+    const value = fieldBoolean(fields, name);
+    if (value === null) {
+        errors.push(`${label} invalid ${name}: ${fieldText(fields, name)} at ${sourceFile}:${line}; must be true or false`);
+    }
+    return value;
+}
+function optionalArray(fields, name) {
+    return fields[name] ? fieldArray(fields, name) : [];
+}
+function throwCompileErrors(errors) {
+    if (errors.length > 0) {
+        throw new Error(`Superpowers source compile failed:\n- ${errors.join("\n- ")}`);
+    }
+}

package/dist/lib/superpowers-task-source-parser.d.ts

@@ -0,0 +1,23 @@
+export interface ParsedField {
+    value: string | string[];
+    line: number;
+}
+export interface ParsedDefinition {
+    id: string;
+    title: string;
+    fields: Record<string, ParsedField>;
+    source_file: string;
+    source_start_line: number;
+    source_end_line: number;
+}
+export interface DefinitionParseOptions {
+    kind: "PI" | "AC";
+    sourceFile: string;
+    allowedFields: Set<string>;
+}
+export declare function parseHeadingDefinitions(content: string, options: DefinitionParseOptions): ParsedDefinition[];
+export declare function parseDocumentFields(content: string, sourceFile: string, allowedFields: Set<string>): Record<string, ParsedField>;
+export declare function fieldText(fields: Record<string, ParsedField>, name: string): string;
+export declare function fieldArray(fields: Record<string, ParsedField>, name: string): string[];
+export declare function fieldBoolean(fields: Record<string, ParsedField>, name: string): boolean | null;
+export declare function fieldLine(fields: Record<string, ParsedField>, name: string): number | undefined;

package/dist/lib/superpowers-task-source-parser.js

@@ -0,0 +1,224 @@
+export function parseHeadingDefinitions(content, options) {
+    const lines = splitLines(content);
+    const errors = [];
+    rejectListStyleDefinitions(lines, options, errors);
+    const headings = findDefinitionHeadings(lines, options.kind);
+    const seen = new Map();
+    const definitions = [];
+    for (const heading of headings) {
+        const firstLine = seen.get(heading.id);
+        if (firstLine !== undefined) {
+            errors.push(`${heading.id} duplicate definition at ${options.sourceFile}:${firstLine} and ${options.sourceFile}:${heading.line}`);
+            continue;
+        }
+        seen.set(heading.id, heading.line);
+        const sourceEndLine = sectionEndLine(lines, heading.index, heading.level);
+        const section = lines.slice(heading.index, sourceEndLine);
+        definitions.push({
+            id: heading.id,
+            title: heading.title,
+            fields: parseFields(section, options.sourceFile, heading.line, options.allowedFields, errors),
+            source_file: options.sourceFile,
+            source_start_line: heading.line,
+            source_end_line: sourceEndLine
+        });
+    }
+    if (definitions.length === 0) {
+        errors.push(`${options.sourceFile} must define ${options.kind} items with Markdown headings like "## ${options.kind}-001: ..."`);
+    }
+    throwIfErrors(errors);
+    return definitions;
+}
+export function parseDocumentFields(content, sourceFile, allowedFields) {
+    const errors = [];
+    const fields = parseFields(splitLines(content), sourceFile, 1, allowedFields, errors);
+    throwIfErrors(errors);
+    return fields;
+}
+export function fieldText(fields, name) {
+    const field = fields[name];
+    if (!field) {
+        return "";
+    }
+    return Array.isArray(field.value) ? field.value.join("\n").trim() : field.value.trim();
+}
+export function fieldArray(fields, name) {
+    const field = fields[name];
+    if (!field) {
+        return [];
+    }
+    if (Array.isArray(field.value)) {
+        return field.value.flatMap(splitScalarArray).filter(Boolean);
+    }
+    return splitScalarArray(field.value);
+}
+export function fieldBoolean(fields, name) {
+    const value = fieldText(fields, name).toLowerCase();
+    if (value === "true") {
+        return true;
+    }
+    if (value === "false") {
+        return false;
+    }
+    return null;
+}
+export function fieldLine(fields, name) {
+    return fields[name]?.line;
+}
+function parseFields(lines, sourceFile, startLine, allowedFields, errors) {
+    const fields = {};
+    for (let index = 0; index < lines.length; index++) {
+        const line = lines[index];
+        const lineNumber = startLine + index;
+        const heading = /^(#{1,6})\s+(.+?)\s*$/.exec(line);
+        if (heading && allowedFields.has(heading[2].trim())) {
+            errors.push(`${sourceFile}:${lineNumber} field headings are not supported; use "${heading[2].trim()}: ..."`);
+            continue;
+        }
+        if (/^\s*\|/.test(line) && containsKnownField(line, allowedFields)) {
+            errors.push(`${sourceFile}:${lineNumber} table fields are not supported; use key: value fields`);
+            continue;
+        }
+        const match = /^([a-z][a-z0-9_]*)\s*:\s*(.*)$/.exec(line);
+        if (!match) {
+            continue;
+        }
+        const name = match[1];
+        if (!allowedFields.has(name)) {
+            if (name.includes("_")) {
+                errors.push(`${sourceFile}:${lineNumber} unknown field ${name}`);
+            }
+            continue;
+        }
+        if (fields[name]) {
+            errors.push(`${sourceFile}:${lineNumber} duplicate field ${name}`);
+            continue;
+        }
+        const parsed = parseFieldValue(lines, index, match[2], sourceFile, lineNumber, errors);
+        fields[name] = { value: parsed.value, line: lineNumber };
+        index = parsed.endIndex;
+    }
+    return fields;
+}
+function parseFieldValue(lines, index, rest, sourceFile, lineNumber, errors) {
+    const trimmed = rest.trim();
+    if (trimmed === "|") {
+        const block = [];
+        let cursor = index + 1;
+        for (; cursor < lines.length; cursor++) {
+            const next = lines[cursor];
+            if (next.trim() && isTopLevelFieldOrHeading(next)) {
+                break;
+            }
+            block.push(next.replace(/^\s{0,2}/, ""));
+        }
+        if (block.length === 0) {
+            errors.push(`${sourceFile}:${lineNumber} block field must include indented text`);
+        }
+        return { value: block.join("\n").trim(), endIndex: cursor - 1 };
+    }
+    if (trimmed) {
+        return { value: cleanValue(trimmed), endIndex: index };
+    }
+    const values = [];
+    let cursor = index + 1;
+    for (; cursor < lines.length; cursor++) {
+        const next = lines[cursor];
+        if (!next.trim()) {
+            continue;
+        }
+        if (isTopLevelFieldOrHeading(next)) {
+            break;
+        }
+        const listItem = /^\s*[-*+]\s+(.+?)\s*$/.exec(next);
+        if (!listItem) {
+            errors.push(`${sourceFile}:${cursor + 1} field lists must use indented "- item" entries or key: | blocks`);
+            continue;
+        }
+        values.push(cleanValue(listItem[1]));
+    }
+    return { value: values, endIndex: cursor - 1 };
+}
+function isTopLevelFieldOrHeading(line) {
+    if (/^(#{1,6})\s+/.test(line)) {
+        return true;
+    }
+    return /^([a-z][a-z0-9_]*)\s*:/.test(line);
+}
+function rejectListStyleDefinitions(lines, options, errors) {
+    const idPattern = options.kind === "PI" ? "PI" : "AC";
+    const listPattern = new RegExp(`^\\s*[-*+]\\s+(${idPattern}-\\d{3,})\\b\\s*[:.-]?`, "i");
+    for (let index = 0; index < lines.length; index++) {
+        const match = listPattern.exec(lines[index]);
+        if (!match) {
+            continue;
+        }
+        const block = listItemBlock(lines, index);
+        if (!block.some((line) => containsKnownField(line, options.allowedFields))) {
+            continue;
+        }
+        const id = match[1].toUpperCase();
+        errors.push(`${id} list-style definition is not allowed at ${options.sourceFile}:${index + 1}; use "## ${id}: ..."`);
+    }
+}
+function listItemBlock(lines, start) {
+    const block = [lines[start]];
+    for (let index = start + 1; index < lines.length; index++) {
+        const line = lines[index];
+        if (line.trim() && !/^\s/.test(line)) {
+            break;
+        }
+        block.push(line);
+    }
+    return block;
+}
+function findDefinitionHeadings(lines, kind) {
+    const pattern = new RegExp(`^(#{1,6})\\s+(${kind}-\\d{3,})\\b(?:\\s*[:.-]\\s*|\\s+)?(.*?)\\s*$`, "i");
+    return lines.flatMap((line, index) => {
+        const match = pattern.exec(line);
+        if (!match) {
+            return [];
+        }
+        return [{
+                id: match[2].toUpperCase(),
+                level: match[1].length,
+                title: cleanValue(match[3]) || match[2].toUpperCase(),
+                index,
+                line: index + 1
+            }];
+    });
+}
+function sectionEndLine(lines, headingIndex, headingLevel) {
+    for (let index = headingIndex + 1; index < lines.length; index++) {
+        const match = /^(#{1,6})\s+/.exec(lines[index]);
+        if (match && match[1].length <= headingLevel) {
+            return index;
+        }
+    }
+    return lines.length;
+}
+function containsKnownField(line, allowedFields) {
+    for (const field of allowedFields) {
+        if (new RegExp(`\\b${field}\\b\\s*:`, "i").test(line) || new RegExp(`\\b${field}\\b`, "i").test(line)) {
+            return true;
+        }
+    }
+    return false;
+}
+function splitScalarArray(value) {
+    return value
+        .split(/[,;\n]/)
+        .map((item) => cleanValue(item))
+        .filter(Boolean);
+}
+function splitLines(content) {
+    return content.replace(/\r\n/g, "\n").replace(/\r/g, "\n").split("\n");
+}
+function cleanValue(value) {
+    return value.replace(/^[-#*\s]+/, "").trim();
+}
+function throwIfErrors(errors) {
+    if (errors.length > 0) {
+        throw new Error(`Superpowers source compile failed:\n- ${errors.join("\n- ")}`);
+    }
+}

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

@@ -122,6 +122,9 @@ export interface SuperpowersProgressState {
 }
 export interface SuperpowersPlanItem {
     requirement: string;
+    source_file: string;
+    source_start_line: number;
+    source_end_line: number;
     delivery_scope: SuperpowersPlanDeliveryScope | "";
     capability_target: string;
     representative_samples: string[];
@@ -137,6 +140,9 @@ export interface SuperpowersPlanItem {
 }
 export interface SuperpowersAcceptanceCriterion {
     scope: string;
+    source_file: string;
+    source_start_line: number;
+    source_end_line: number;
     acceptance_scope: SuperpowersAcceptanceScope | "";
     ac_validates: string[];
     ac_does_not_validate: string[];

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

@@ -1,4 +1,5 @@
 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 completionConditionErrors(state: SuperpowersTaskState): string[];
 export declare function allCompletionConditionsSatisfied(state: SuperpowersTaskState): boolean;

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

@@ -221,6 +221,9 @@ function validateFinalCompletion(state, errors) {
             errors.push("product_goal_complete=true but Context Delta coverage is unresolved");
         }
     }
+    validateFullPopulationEvidence(state, errors);
+}
+function validateFullPopulationEvidence(state, errors) {
     if (fullPopulationRequired(state)) {
         const sampleOnlyEvidence = state.evidence.filter((evidence) => evidence.does_not_prove.some((claim) => /\b(full[-_ ]?population|all[-_ ]?provider|all[-_ ]?interface|all[-_ ]?platform)\b/i.test(claim)));
         if (sampleOnlyEvidence.length > 0) {
@@ -230,11 +233,11 @@ function validateFinalCompletion(state, errors) {
         }
     }
 }
-export function allCompletionConditionsSatisfied(state) {
+export function completionConditionErrors(state) {
     const errors = [];
     validateShape(state, errors);
     if (!hasUsableShape(state)) {
-        return false;
+        return errors;
     }
     validateDeliveryContract(state, errors);
     validateScopeConflicts(state, errors);
@@ -242,11 +245,21 @@ export function allCompletionConditionsSatisfied(state) {
     validateEvidenceRecords(state, errors);
     validateProofLayers(state, errors);
     validateAuditor(state, errors);
+    validateFullPopulationEvidence(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;
+    if (planItems.length === 0 || acceptanceCriteria.length === 0 || proofLayers.length === 0) {
+        errors.push("completion conditions require a compiled task graph with plan items, ACs and proof layers");
+    }
+    if (!allPlansComplete || !allAcsComplete || !allLayersSatisfied) {
+        errors.push("completion conditions require all required plan items, ACs and proof layers to be complete");
+    }
+    return errors;
+}
+export function allCompletionConditionsSatisfied(state) {
+    return completionConditionErrors(state).length === 0;
 }

package/package.json

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