@openflowjs/cli 0.2.0

package/dist/core/artifacts.js

@@ -0,0 +1,809 @@
+import { OPENFLOW_STAGES, OPENFLOW_LEVELS } from "./index.js";
+export const REVIEW_STATUSES = ["approved", "changes_requested", "partial", "rejected"];
+export const EXTENSION_STATUSES = ["passed", "failed", "skipped"];
+export const FLOW_GATES = ["draft", "review_required", "changes_requested", "approved", "skipped", "blocked"];
+export function validateOpenFlowConfig(value, path = "config.json") {
+    const issues = [];
+    if (!isRecord(value)) {
+        return withIssues([{ code: "config.type", message: "config.json must contain a JSON object.", path }]);
+    }
+    if (value.version !== 1) {
+        issues.push(error("config.version", "config.version must be 1.", `${path}.version`));
+    }
+    if (!isOpenFlowLevel(value.defaultLevel)) {
+        issues.push(error("config.defaultLevel", `config.defaultLevel must be one of: ${OPENFLOW_LEVELS.join(", ")}.`, `${path}.defaultLevel`));
+    }
+    if ("language" in value && !isLanguageTag(value.language)) {
+        issues.push(error("config.language", "config.language must be a non-empty language tag such as zh-CN or en-US.", `${path}.language`));
+    }
+    if ("review" in value) {
+        validateReviewConfig(value.review, `${path}.review`, issues);
+    }
+    if ("extensions" in value) {
+        validateExtensionConfigs(value.extensions, `${path}.extensions`, issues);
+    }
+    if ("modules" in value) {
+        if (!Array.isArray(value.modules)) {
+            issues.push(error("config.modules.type", "config.modules must be an array of strings.", `${path}.modules`));
+        }
+        else {
+            if (value.modules.length === 0) {
+                issues.push(error("config.modules.empty", "config.modules must contain at least one module.", `${path}.modules`));
+            }
+            for (const mod of value.modules) {
+                if (typeof mod !== "string") {
+                    issues.push(error("config.modules.item", "Each config.modules item must be a string.", `${path}.modules`));
+                    break;
+                }
+            }
+            if (!value.modules.includes("core")) {
+                issues.push(error("config.modules.core", "config.modules must include 'core'.", `${path}.modules`));
+            }
+            const validModules = ["core", "brainstorm-prd"];
+            for (const mod of value.modules) {
+                if (typeof mod === "string" && !validModules.includes(mod)) {
+                    issues.push(error("config.modules.invalid", `config.modules contains unknown module '${mod}'. Valid modules: ${validModules.join(", ")}.`, `${path}.modules`));
+                }
+            }
+        }
+    }
+    return fromIssues(issues);
+}
+export function validateFlowState(value, path = "flow.json") {
+    const issues = [];
+    if (!isRecord(value)) {
+        return withIssues([{ code: "flow.type", message: "flow.json must contain a JSON object.", path }]);
+    }
+    if (!nonEmptyString(value.id)) {
+        issues.push(error("flow.id", "flow.id must be a non-empty string.", `${path}.id`));
+    }
+    if (!nonEmptyString(value.title)) {
+        issues.push(error("flow.title", "flow.title must be a non-empty string.", `${path}.title`));
+    }
+    if (!isOpenFlowLevel(value.level)) {
+        issues.push(error("flow.level", `flow.level must be one of: ${OPENFLOW_LEVELS.join(", ")}.`, `${path}.level`));
+    }
+    if (!isOpenFlowStage(value.stage)) {
+        issues.push(error("flow.stage", `flow.stage must be one of: ${OPENFLOW_STAGES.join(", ")}.`, `${path}.stage`));
+    }
+    if (!Number.isInteger(value.revision) || value.revision < 1) {
+        issues.push(error("flow.revision", "flow.revision must be an integer greater than 0.", `${path}.revision`));
+    }
+    if (!isFlowGate(value.gate)) {
+        issues.push(error("flow.gate", `flow.gate must be one of: ${FLOW_GATES.join(", ")}.`, `${path}.gate`));
+    }
+    if (typeof value.createdAt !== "string" || !isIsoDate(value.createdAt)) {
+        issues.push(error("flow.createdAt", "flow.createdAt must be an ISO timestamp.", `${path}.createdAt`));
+    }
+    if (typeof value.updatedAt !== "string" || !isIsoDate(value.updatedAt)) {
+        issues.push(error("flow.updatedAt", "flow.updatedAt must be an ISO timestamp.", `${path}.updatedAt`));
+    }
+    if (value.activeTask !== null && typeof value.activeTask !== "string") {
+        issues.push(error("flow.activeTask", "flow.activeTask must be a string or null.", `${path}.activeTask`));
+    }
+    if ("knowledge_citations" in value) {
+        validateKnowledgeCitations(value.knowledge_citations, `${path}.knowledge_citations`, issues);
+    }
+    return fromIssues(issues);
+}
+export function validateReviewResult(value, path = "reviews/spec-review.json") {
+    const issues = [];
+    if (!isRecord(value)) {
+        return withIssues([{ code: "review.type", message: "review result must contain a JSON object.", path }]);
+    }
+    if (value.stage !== "spec" && value.stage !== "plan" && value.stage !== "prd" && value.stage !== "archive") {
+        issues.push(error("review.stage", "review.stage must be spec, plan, prd, or archive.", `${path}.stage`));
+    }
+    if (!Number.isInteger(value.revision) || value.revision < 1) {
+        issues.push(error("review.revision", "review.revision must be an integer greater than 0.", `${path}.revision`));
+    }
+    if (!isReviewStatus(value.status)) {
+        issues.push(error("review.status", `review.status must be one of: ${REVIEW_STATUSES.join(", ")}.`, `${path}.status`));
+    }
+    if (typeof value.reviewedAt !== "string") {
+        issues.push(error("review.reviewedAt", "review.reviewedAt must be a string.", `${path}.reviewedAt`));
+    }
+    else if (value.status === "approved" && !isIsoDate(value.reviewedAt)) {
+        issues.push(error("review.reviewedAt.iso", "approved reviews must include an ISO reviewedAt timestamp.", `${path}.reviewedAt`));
+    }
+    else if (value.reviewedAt !== "" && !isIsoDate(value.reviewedAt)) {
+        issues.push(warning("review.reviewedAt.iso", "review.reviewedAt should be an ISO timestamp when present.", `${path}.reviewedAt`));
+    }
+    validateStringArray(value.comments, `${path}.comments`, "review.comments", issues);
+    validateStringArray(value.requestedChanges, `${path}.requestedChanges`, "review.requestedChanges", issues);
+    if ("annotations" in value) {
+        validateReviewAnnotations(value.annotations, `${path}.annotations`, issues);
+    }
+    if ("approvedBy" in value && typeof value.approvedBy !== "string") {
+        issues.push(error("review.approvedBy", "review.approvedBy must be a string when present.", `${path}.approvedBy`));
+    }
+    return fromIssues(issues);
+}
+export function validateExtensionResult(value, path = "result.json") {
+    const issues = [];
+    if (!isRecord(value)) {
+        return withIssues([{ code: "extension.type", message: "extension result must contain a JSON object.", path }]);
+    }
+    if (!nonEmptyString(value.name)) {
+        issues.push(error("extension.name", "extension result name must be a non-empty string.", `${path}.name`));
+    }
+    if (!isExtensionStatus(value.status)) {
+        issues.push(error("extension.status", `extension status must be one of: ${EXTENSION_STATUSES.join(", ")}.`, `${path}.status`));
+    }
+    if (typeof value.required !== "boolean") {
+        issues.push(error("extension.required", "extension required must be a boolean.", `${path}.required`));
+    }
+    if (typeof value.summary !== "string") {
+        issues.push(error("extension.summary", "extension summary must be a string.", `${path}.summary`));
+    }
+    validateStringArray(value.artifacts, `${path}.artifacts`, "extension.artifacts", issues);
+    if (typeof value.createdAt !== "string" || !isIsoDate(value.createdAt)) {
+        issues.push(error("extension.createdAt", "extension createdAt must be an ISO timestamp.", `${path}.createdAt`));
+    }
+    return fromIssues(issues);
+}
+export function validatePrdMeta(value, path = "prd.json") {
+    const issues = [];
+    if (!isRecord(value)) {
+        return withIssues([{ code: "prd.type", message: "prd.json must contain a JSON object.", path }]);
+    }
+    if (!nonEmptyString(value.id)) {
+        issues.push(error("prd.id", "prd.id must be a non-empty string.", `${path}.id`));
+    }
+    else if (!/^\d{4}-\d{2}-\d{2}-/.test(value.id)) {
+        issues.push(error("prd.id.format", "prd.id must start with a YYYY-MM-DD- prefix.", `${path}.id`));
+    }
+    if (value.status !== "draft" && value.status !== "reviewing" && value.status !== "approved") {
+        issues.push(error("prd.status", "prd.status must be draft, reviewing, or approved.", `${path}.status`));
+    }
+    if (!Number.isInteger(value.revision) || value.revision < 0) {
+        issues.push(error("prd.revision", "prd.revision must be a non-negative integer.", `${path}.revision`));
+    }
+    if (value.linkedIteration !== null && typeof value.linkedIteration !== "string") {
+        issues.push(error("prd.linkedIteration", "prd.linkedIteration must be a string or null.", `${path}.linkedIteration`));
+    }
+    validateStringArray(value.assets, `${path}.assets`, "prd.assets", issues);
+    if (typeof value.createdAt !== "string" || !isIsoDate(value.createdAt)) {
+        issues.push(error("prd.createdAt", "prd.createdAt must be an ISO timestamp.", `${path}.createdAt`));
+    }
+    if (typeof value.updatedAt !== "string" || !isIsoDate(value.updatedAt)) {
+        issues.push(error("prd.updatedAt", "prd.updatedAt must be an ISO timestamp.", `${path}.updatedAt`));
+    }
+    return fromIssues(issues);
+}
+export function validateStateMarkdown(markdown, path = "STATE.md") {
+    const issues = [];
+    requireHeading(markdown, "# OpenFlow State", path, issues);
+    requireLinePrefix(markdown, "- Flow:", path, issues);
+    requireLinePrefix(markdown, "- Title:", path, issues);
+    requireLinePrefix(markdown, "- Stage:", path, issues);
+    requireLinePrefix(markdown, "- Level:", path, issues);
+    requireLinePrefix(markdown, "- Revision:", path, issues);
+    requireLinePrefix(markdown, "- Active task:", path, issues);
+    requireLinePrefix(markdown, "- Gate status:", path, issues);
+    const stage = readListValue(markdown, "Stage");
+    if (stage && !isOpenFlowStage(stage)) {
+        issues.push(error("state.stage", `STATE.md Stage must be one of: ${OPENFLOW_STAGES.join(", ")}.`, path));
+    }
+    const level = readListValue(markdown, "Level");
+    if (level && !isOpenFlowLevel(level)) {
+        issues.push(error("state.level", `STATE.md Level must be one of: ${OPENFLOW_LEVELS.join(", ")}.`, path));
+    }
+    return fromIssues(issues);
+}
+export function validateSpecMarkdown(markdown, path = "SPEC.md", level) {
+    const issues = [];
+    requireHeadingPattern(markdown, /^# Spec(?::\s+.+)?\s*$/m, "# Spec: <title>", path, issues);
+    for (const heading of [
+        "## One-Sentence Goal",
+        "## Scope",
+        "## Non-Goals",
+        "## Acceptance Criteria"
+    ]) {
+        requireHeading(markdown, heading, path, issues);
+    }
+    if (level === undefined || level === "2" || level === "3") {
+        requireHeading(markdown, "## Risks", path, issues);
+    }
+    if (/^## Decisions Needed\s*$/m.test(markdown)) {
+        issues.push(warning("spec.deprecated.decisions", "SPEC.md should not include '## Decisions Needed'. Decisions belong in PLAN.md.", path));
+    }
+    if (/^## AI Execution Summary\s*$/m.test(markdown)) {
+        issues.push(warning("spec.deprecated.executionSummary", "SPEC.md should not include '## AI Execution Summary'. Execution details belong in PLAN.md and TASKS.md.", path));
+    }
+    return fromIssues(issues);
+}
+export function validateContextMarkdown(markdown, path = "CONTEXT.md") {
+    const issues = [];
+    requireHeading(markdown, "# Context", path, issues);
+    return fromIssues(issues);
+}
+export function validateTasksMarkdown(markdown, path = "TASKS.md") {
+    const issues = [];
+    requireHeading(markdown, "# Tasks", path, issues);
+    if (!/^-\s+\[[ xX]\]\s+T-\d{3}:/m.test(markdown)) {
+        issues.push(error("tasks.checkbox", "TASKS.md must include at least one checkbox task with a stable T-### id.", path));
+    }
+    for (const label of ["Action:", "Validation:", "Evidence:"]) {
+        if (!markdown.includes(label)) {
+            issues.push(error(`tasks.${label.toLowerCase().replace(":", "")}`, `TASKS.md must include ${label} for each task.`, path));
+        }
+    }
+    for (const label of ["**Files:**", "**Read First:**", "**Acceptance Criteria:**"]) {
+        if (!markdown.includes(label)) {
+            issues.push(warning(`tasks.${label.toLowerCase().replace(/[^a-z]/g, "")}`, `TASKS.md should include ${label} for each task (Level 2+ recommended).`, path));
+        }
+    }
+    return fromIssues(issues);
+}
+export function validatePlanMarkdown(markdown, path = "PLAN.md", level) {
+    const issues = [];
+    requireHeadingPattern(markdown, /^# Plan(?::\s+.+)?\s*$/m, "# Plan: <title>", path, issues);
+    for (const heading of [
+        "## Context",
+        "## Decisions",
+        "## File Map",
+        "## Spec Coverage"
+    ]) {
+        requireHeading(markdown, heading, path, issues);
+    }
+    if (level === "3") {
+        for (const heading of ["## Must Haves", "## Key Interfaces", "## Dependencies", "## Risks"]) {
+            requireHeading(markdown, heading, path, issues);
+        }
+    }
+    return fromIssues(issues);
+}
+export function validateSummaryMarkdown(markdown, path = "SUMMARY.md") {
+    const issues = [];
+    requireHeading(markdown, "# Summary", path, issues);
+    for (const heading of ["## Shipped Changes", "## Validation Evidence", "## Deferred Items", "## Durable Knowledge"]) {
+        requireHeading(markdown, heading, path, issues);
+    }
+    return fromIssues(issues);
+}
+export function validateKnowledgeCatalog(value, path = "knowledge/catalog.json") {
+    const issues = [];
+    if (!isRecord(value)) {
+        return withIssues([{ code: "knowledge.catalog.type", message: "catalog.json must contain a JSON object.", path }]);
+    }
+    if (typeof value.version !== "number" || !Number.isInteger(value.version)) {
+        issues.push(error("knowledge.catalog.version", "catalog.json version must be an integer.", `${path}.version`));
+    }
+    if (!Array.isArray(value.entries)) {
+        issues.push(error("knowledge.catalog.entries", "catalog.json entries must be an array.", `${path}.entries`));
+    }
+    else {
+        validateCatalogEntries(value.entries, `${path}.entries`, issues);
+    }
+    return fromIssues(issues);
+}
+export function validateKnowledgeIndex(value, path = "knowledge/decisions/index.json") {
+    const issues = [];
+    if (!isRecord(value)) {
+        return withIssues([{ code: "knowledge.index.type", message: "index.json must contain a JSON object.", path }]);
+    }
+    if (typeof value.type !== "string" || value.type.trim().length === 0) {
+        issues.push(error("knowledge.index.type", "index.json type must be a non-empty string.", `${path}.type`));
+    }
+    if (!Array.isArray(value.entries)) {
+        issues.push(error("knowledge.index.entries", "index.json entries must be an array.", `${path}.entries`));
+    }
+    else {
+        validateIndexEntries(value.entries, `${path}.entries`, issues);
+    }
+    return fromIssues(issues);
+}
+export function validateWorkingMemoryMarkdown(markdown, path = "WORKING_MEMORY.md") {
+    const issues = [];
+    for (const heading of [
+        "## Injected Knowledge",
+        "## Execution Observations",
+        "## Knowledge Candidates",
+        "## Blockers and Resolutions"
+    ]) {
+        requireHeading(markdown, heading, path, issues);
+    }
+    return fromIssues(issues);
+}
+export function validateStageTransition(input) {
+    const issues = [];
+    if (input.targetStage === "implement" && requiresReviewBeforeExecute(input.level)) {
+        if (!input.review || input.review.stage !== "spec" || input.review.status !== "approved") {
+            issues.push(error("gate.specReview", `Level ${input.level} flows require an approved spec review before implement.`));
+        }
+    }
+    if (input.targetStage === "archived" && requiresArchiveReview(input.level)) {
+        if (!input.review || input.review.stage !== "archive" || input.review.status !== "approved") {
+            issues.push(error("gate.archiveReview", `Level ${input.level} flows require an approved archive review before finalize.`));
+        }
+    }
+    if (input.currentStage === "archived" && input.targetStage !== "archived") {
+        issues.push(error("gate.archived", "archived flows cannot transition back to an active stage."));
+    }
+    return fromIssues(issues);
+}
+export function validateOpenFlowArtifacts(artifacts) {
+    const issues = [];
+    if (artifacts.config !== undefined) {
+        issues.push(...validateOpenFlowConfig(artifacts.config).issues);
+    }
+    const resolvedFlowLevel = isFlowStateValue(artifacts.flow) ? artifacts.flow.level : undefined;
+    if (artifacts.flow !== undefined) {
+        issues.push(...validateFlowState(artifacts.flow).issues);
+    }
+    if (artifacts.specReview !== undefined) {
+        issues.push(...validateReviewResult(artifacts.specReview, "reviews/spec-review.json").issues);
+    }
+    if (artifacts.archiveReview !== undefined) {
+        issues.push(...validateReviewResult(artifacts.archiveReview, "reviews/archive-review.json").issues);
+    }
+    for (const result of artifacts.extensionResults ?? []) {
+        issues.push(...validateExtensionResult(result.value, result.path).issues);
+    }
+    if (artifacts.stateMarkdown !== undefined) {
+        issues.push(...validateStateMarkdown(artifacts.stateMarkdown).issues);
+    }
+    if (artifacts.specMarkdown !== undefined) {
+        issues.push(...validateSpecMarkdown(artifacts.specMarkdown, "SPEC.md", resolvedFlowLevel).issues);
+    }
+    if (artifacts.contextMarkdown !== undefined) {
+        issues.push(...validateContextMarkdown(artifacts.contextMarkdown).issues);
+    }
+    if (artifacts.tasksMarkdown !== undefined) {
+        issues.push(...validateTasksMarkdown(artifacts.tasksMarkdown).issues);
+    }
+    if (artifacts.planMarkdown !== undefined) {
+        issues.push(...validatePlanMarkdown(artifacts.planMarkdown, "PLAN.md", resolvedFlowLevel).issues);
+    }
+    if (artifacts.summaryMarkdown !== undefined) {
+        issues.push(...validateSummaryMarkdown(artifacts.summaryMarkdown).issues);
+    }
+    issues.push(...validateKnowledgeDirectories(artifacts));
+    issues.push(...validateKnowledgeCatalogAndIndices(artifacts));
+    issues.push(...validateWorkingMemory(artifacts));
+    issues.push(...validateSpecApprovalGate(artifacts));
+    issues.push(...validateExecutionEvidenceGate(artifacts));
+    issues.push(...validateArchiveGate(artifacts));
+    return fromIssues(issues);
+}
+export function requiresHumanReview(level) {
+    return level === "2" || level === "3";
+}
+export function requiresReviewBeforeExecute(level) {
+    return requiresHumanReview(level);
+}
+// No formal archive-review.json gate file exists in the workflow.
+// Archive-stage quality checks (code-reviewer, artifact-reviewer) are
+// performed by the AI agent during /openflow-finalize, not as a file-producing gate.
+export function requiresArchiveReview(_level) {
+    return false;
+}
+function validateSpecApprovalGate(artifacts) {
+    if (!isFlowStateValue(artifacts.flow) || !requiresHumanReview(artifacts.flow.level) || artifacts.flow.gate !== "approved") {
+        return [];
+    }
+    if (!isReviewResultValue(artifacts.specReview)) {
+        return [error("gate.specReview", `approved Level ${artifacts.flow.level} flows require reviews/spec-review.json.`)];
+    }
+    if (artifacts.specReview.stage !== "spec" || artifacts.specReview.status !== "approved") {
+        return [error("gate.specReview.status", "reviews/spec-review.json must be an approved spec review.")];
+    }
+    if (artifacts.specReview.revision !== artifacts.flow.revision) {
+        return [error("gate.specReview.revision", "approved spec review revision must match flow.json revision.")];
+    }
+    return [];
+}
+function validateExecutionEvidenceGate(artifacts) {
+    if (artifacts.tasksMarkdown === undefined) {
+        return [];
+    }
+    const issues = [];
+    const tasks = parseTasks(artifacts.tasksMarkdown);
+    const flow = isFlowStateValue(artifacts.flow) ? artifacts.flow : undefined;
+    const closingFlow = flow?.stage === "finalize" || flow?.stage === "archived";
+    const flowLevel = flow?.level;
+    for (const task of tasks) {
+        if (task.checked) {
+            if (!isConcreteTaskEvidence(task.evidence)) {
+                issues.push(error("tasks.evidence.concrete", `${task.id} is checked but does not include concrete evidence. Record commands, results, screenshots, reviewer signal, or exact blocker text.`, "TASKS.md"));
+            }
+            if (!isConcreteTaskValidation(task.validation)) {
+                issues.push(error("tasks.validation.concrete", `${task.id} is checked but does not include a concrete validation signal.`, "TASKS.md"));
+            }
+            continue;
+        }
+        if (closingFlow && !isExplicitlyDeferred(task.evidence)) {
+            issues.push(error("tasks.incomplete.archive", `${task.id} is incomplete during archive. Complete it or record an explicit deferred/blocked/waived evidence note with rationale.`, "TASKS.md"));
+        }
+    }
+    return issues;
+}
+function validateArchiveGate(artifacts) {
+    if (!isFlowStateValue(artifacts.flow)) {
+        return [];
+    }
+    const issues = [];
+    const flow = artifacts.flow;
+    const finalArchive = flow.stage === "archived" || (flow.stage === "finalize" && flow.gate === "approved");
+    if (!finalArchive) {
+        return issues;
+    }
+    if (artifacts.summaryMarkdown === undefined) {
+        issues.push(error("gate.summary", "Final archive requires SUMMARY.md.", "SUMMARY.md"));
+    }
+    issues.push(...validateRequiredExtensionGate(artifacts));
+    return issues;
+}
+const REQUIRED_KNOWLEDGE_SUB_DIRS = ["guidelines", "processes", "archive"];
+function validateKnowledgeDirectories(artifacts) {
+    if (artifacts.knowledgeSubDirs === undefined || artifacts.knowledgeSubDirs.length === 0) {
+        return [];
+    }
+    const issues = [];
+    for (const subDir of REQUIRED_KNOWLEDGE_SUB_DIRS) {
+        if (!artifacts.knowledgeSubDirs.includes(subDir)) {
+            issues.push(error("knowledge.directory.missing", `knowledge/ directory is missing required sub-directory: ${subDir}/.`, `knowledge/${subDir}/`));
+        }
+    }
+    return issues;
+}
+function validateKnowledgeCatalogAndIndices(artifacts) {
+    const issues = [];
+    if (artifacts.knowledgeCatalog !== undefined) {
+        issues.push(...validateKnowledgeCatalog(artifacts.knowledgeCatalog).issues);
+    }
+    for (const indexFile of artifacts.knowledgeIndexFiles ?? []) {
+        issues.push(...validateKnowledgeIndex(indexFile.value, indexFile.path).issues);
+    }
+    return issues;
+}
+function validateWorkingMemory(artifacts) {
+    if (artifacts.workingMemoryMarkdown === undefined) {
+        return [];
+    }
+    const issues = [];
+    issues.push(...validateWorkingMemoryMarkdown(artifacts.workingMemoryMarkdown).issues);
+    return issues;
+}
+function validateRequiredExtensionGate(artifacts) {
+    if (!isRecord(artifacts.config) || !isRecord(artifacts.config.extensions)) {
+        return [];
+    }
+    const issues = [];
+    const results = new Map();
+    for (const result of artifacts.extensionResults ?? []) {
+        if (isExtensionResultValue(result.value)) {
+            results.set(result.value.name, result.value);
+        }
+    }
+    for (const [name, config] of Object.entries(artifacts.config.extensions)) {
+        if (!isRecord(config) || config.enabled !== true || config.required !== true) {
+            continue;
+        }
+        const result = results.get(name);
+        if (!result) {
+            issues.push(error("gate.extension.missing", `required extension "${name}" has no result.json.`, `extensions/${name}/result.json`));
+            continue;
+        }
+        if (result.status !== "passed" && !isAcceptedExtensionDeferral(result)) {
+            issues.push(error("gate.extension.status", `required extension "${name}" must pass or be skipped with an accepted deferral rationale.`, `extensions/${name}/result.json`));
+        }
+    }
+    return issues;
+}
+function parseTasks(markdown) {
+    const matches = [...markdown.matchAll(/^-\s+\[([ xX])\]\s+(T-\d{3}):\s*(.+?)\s*$/gm)];
+    return matches.map((match, index) => {
+        const nextMatch = matches[index + 1];
+        const block = markdown.slice(match.index, nextMatch?.index ?? markdown.length);
+        return {
+            id: match[2],
+            checked: match[1].toLowerCase() === "x",
+            title: match[3].trim(),
+            block,
+            validation: readTaskField(block, "Validation"),
+            evidence: readTaskField(block, "Evidence"),
+        };
+    });
+}
+function readTaskField(block, field) {
+    const match = new RegExp(`^\\s*-\\s+\\*{0,2}${escapeRegExp(field)}:\\*{0,2}\\s*(.+?)\\s*$`, "m").exec(block);
+    return match?.[1]?.trim();
+}
+function isConcreteTaskValidation(value) {
+    return isConcreteText(value);
+}
+function isConcreteTaskEvidence(value) {
+    return isConcreteText(value);
+}
+function isConcreteText(value) {
+    if (!value) {
+        return false;
+    }
+    const normalized = value.trim().toLowerCase();
+    if (normalized.length < 8) {
+        return false;
+    }
+    return !["pending", "todo", "tbd", "none", "n/a", "na", "done", "complete", "completed", "yes"].includes(normalized);
+}
+function isExplicitlyDeferred(value) {
+    if (!isConcreteText(value)) {
+        return false;
+    }
+    return /\b(deferred|blocked|waived)\b/i.test(value ?? "");
+}
+function isAcceptedExtensionDeferral(result) {
+    return result.status === "skipped" && /\b(deferred|waived|accepted)\b/i.test(result.summary);
+}
+function validateReviewConfig(value, path, issues) {
+    if (!isRecord(value)) {
+        issues.push(error("config.review.type", "config.review must be an object.", path));
+        return;
+    }
+    if (typeof value.required !== "boolean") {
+        issues.push(error("config.review.required", "config.review.required must be a boolean.", `${path}.required`));
+    }
+    if ("port" in value && (!Number.isInteger(value.port) || value.port < 1 || value.port > 65535)) {
+        issues.push(error("config.review.port", "config.review.port must be an integer from 1 to 65535.", `${path}.port`));
+    }
+}
+function validateExtensionConfigs(value, path, issues) {
+    if (!isRecord(value)) {
+        issues.push(error("config.extensions.type", "config.extensions must be an object.", path));
+        return;
+    }
+    for (const [name, extension] of Object.entries(value)) {
+        const extensionPath = `${path}.${name}`;
+        if (!isRecord(extension)) {
+            issues.push(error("config.extensions.item", "each extension config must be an object.", extensionPath));
+            continue;
+        }
+        if (typeof extension.enabled !== "boolean") {
+            issues.push(error("config.extensions.enabled", "extension enabled must be a boolean.", `${extensionPath}.enabled`));
+        }
+        if ("required" in extension && typeof extension.required !== "boolean") {
+            issues.push(error("config.extensions.required", "extension required must be a boolean.", `${extensionPath}.required`));
+        }
+        if ("hooks" in extension) {
+            validateStringArray(extension.hooks, `${extensionPath}.hooks`, "config.extensions.hooks", issues);
+        }
+        if ("command" in extension && typeof extension.command !== "string") {
+            issues.push(error("config.extensions.command", "extension command must be a string.", `${extensionPath}.command`));
+        }
+        if ("outputs" in extension) {
+            validateStringArray(extension.outputs, `${extensionPath}.outputs`, "config.extensions.outputs", issues);
+        }
+    }
+}
+function validateStringArray(value, path, code, issues) {
+    if (!Array.isArray(value) || value.some((item) => typeof item !== "string")) {
+        issues.push(error(code, `${path} must be an array of strings.`, path));
+    }
+}
+function validateReviewAnnotations(value, path, issues) {
+    if (!Array.isArray(value)) {
+        issues.push(error("review.annotations", `${path} must be an array.`, path));
+        return;
+    }
+    value.forEach((annotation, index) => {
+        const annotationPath = `${path}[${index}]`;
+        if (!isRecord(annotation)) {
+            issues.push(error("review.annotation.type", "review annotation must be an object.", annotationPath));
+            return;
+        }
+        if (!nonEmptyString(annotation.id)) {
+            issues.push(error("review.annotation.id", "review annotation id must be a non-empty string.", `${annotationPath}.id`));
+        }
+        if (!isReviewAnnotationArtifact(annotation.artifact)) {
+            issues.push(error("review.annotation.artifact", "review annotation artifact must be one of: SPEC.md, TASKS.md, CONTEXT.md, PLAN.md, SUMMARY.md.", `${annotationPath}.artifact`));
+        }
+        if ("section" in annotation && typeof annotation.section !== "string") {
+            issues.push(error("review.annotation.section", "review annotation section must be a string when present.", `${annotationPath}.section`));
+        }
+        if ("lineStart" in annotation && (!Number.isInteger(annotation.lineStart) || annotation.lineStart < 1)) {
+            issues.push(error("review.annotation.lineStart", "review annotation lineStart must be an integer greater than 0.", `${annotationPath}.lineStart`));
+        }
+        if ("lineEnd" in annotation && (!Number.isInteger(annotation.lineEnd) || annotation.lineEnd < 1)) {
+            issues.push(error("review.annotation.lineEnd", "review annotation lineEnd must be an integer greater than 0.", `${annotationPath}.lineEnd`));
+        }
+        if (Number.isInteger(annotation.lineStart) &&
+            Number.isInteger(annotation.lineEnd) &&
+            annotation.lineEnd < annotation.lineStart) {
+            issues.push(error("review.annotation.lineRange", "review annotation lineEnd must be greater than or equal to lineStart.", annotationPath));
+        }
+        if (!isReviewAnnotationKind(annotation.kind)) {
+            issues.push(error("review.annotation.kind", "review annotation kind must be question, change, risk, or nit.", `${annotationPath}.kind`));
+        }
+        if (annotation.severity !== "blocking" && annotation.severity !== "non_blocking") {
+            issues.push(error("review.annotation.severity", "review annotation severity must be blocking or non_blocking.", `${annotationPath}.severity`));
+        }
+        if (!nonEmptyString(annotation.text)) {
+            issues.push(error("review.annotation.text", "review annotation text must be a non-empty string.", `${annotationPath}.text`));
+        }
+        if (annotation.status !== "open" && annotation.status !== "resolved") {
+            issues.push(error("review.annotation.status", "review annotation status must be open or resolved.", `${annotationPath}.status`));
+        }
+    });
+}
+function validateCatalogEntries(entries, path, issues) {
+    entries.forEach((entry, index) => {
+        const entryPath = `${path}[${index}]`;
+        if (!isRecord(entry)) {
+            issues.push(error("knowledge.catalog.entry.type", "Each catalog entry must be an object.", entryPath));
+            return;
+        }
+        if (!nonEmptyString(entry.id)) {
+            issues.push(error("knowledge.catalog.entry.id", "Catalog entry id must be a non-empty string.", `${entryPath}.id`));
+        }
+        if (typeof entry.type !== "string" || entry.type.trim().length === 0) {
+            issues.push(error("knowledge.catalog.entry.type", "Catalog entry type must be a non-empty string.", `${entryPath}.type`));
+        }
+        if (!nonEmptyString(entry.title)) {
+            issues.push(error("knowledge.catalog.entry.title", "Catalog entry title must be a non-empty string.", `${entryPath}.title`));
+        }
+        if (!Array.isArray(entry.tags)) {
+            issues.push(error("knowledge.catalog.entry.tags", "Catalog entry tags must be an array.", `${entryPath}.tags`));
+        }
+        if (!Array.isArray(entry.scope)) {
+            issues.push(error("knowledge.catalog.entry.scope", "Catalog entry scope must be an array.", `${entryPath}.scope`));
+        }
+        if (typeof entry.summary !== "string") {
+            issues.push(error("knowledge.catalog.entry.summary", "Catalog entry summary must be a string.", `${entryPath}.summary`));
+        }
+    });
+}
+function validateIndexEntries(entries, path, issues) {
+    entries.forEach((entry, index) => {
+        const entryPath = `${path}[${index}]`;
+        if (!isRecord(entry)) {
+            issues.push(error("knowledge.index.entry.type", "Each index entry must be an object.", entryPath));
+            return;
+        }
+        if (!nonEmptyString(entry.id)) {
+            issues.push(error("knowledge.index.entry.id", "Index entry id must be a non-empty string.", `${entryPath}.id`));
+        }
+        if (!nonEmptyString(entry.title)) {
+            issues.push(error("knowledge.index.entry.title", "Index entry title must be a non-empty string.", `${entryPath}.title`));
+        }
+        if (!Array.isArray(entry.tags)) {
+            issues.push(error("knowledge.index.entry.tags", "Index entry tags must be an array.", `${entryPath}.tags`));
+        }
+        if (!Array.isArray(entry.scope)) {
+            issues.push(error("knowledge.index.entry.scope", "Index entry scope must be an array.", `${entryPath}.scope`));
+        }
+        if (typeof entry.summary !== "string") {
+            issues.push(error("knowledge.index.entry.summary", "Index entry summary must be a string.", `${entryPath}.summary`));
+        }
+    });
+}
+function requireHeading(markdown, heading, path, issues) {
+    const escaped = escapeRegExp(heading);
+    if (!new RegExp(`^${escaped}\\s*$`, "m").test(markdown)) {
+        issues.push(error("markdown.heading", `${path} must include "${heading}".`, path));
+    }
+}
+function requireHeadingPattern(markdown, pattern, label, path, issues) {
+    if (!pattern.test(markdown)) {
+        issues.push(error("markdown.heading", `${path} must include "${label}".`, path));
+    }
+}
+function requireLinePrefix(markdown, prefix, path, issues) {
+    const escaped = escapeRegExp(prefix);
+    if (!new RegExp(`^${escaped}`, "m").test(markdown)) {
+        issues.push(error("markdown.field", `${path} must include "${prefix}".`, path));
+    }
+}
+function readListValue(markdown, field) {
+    const match = new RegExp(`^-\\s+${escapeRegExp(field)}:\\s*(.+?)\\s*$`, "m").exec(markdown);
+    return match?.[1]?.trim();
+}
+function isOpenFlowStage(value) {
+    return typeof value === "string" && OPENFLOW_STAGES.includes(value);
+}
+function isOpenFlowLevel(value) {
+    return typeof value === "string" && OPENFLOW_LEVELS.includes(value);
+}
+function isFlowGate(value) {
+    return typeof value === "string" && FLOW_GATES.includes(value);
+}
+function isReviewStatus(value) {
+    return typeof value === "string" && REVIEW_STATUSES.includes(value);
+}
+function isReviewAnnotationArtifact(value) {
+    return value === "SPEC.md" || value === "TASKS.md" || value === "CONTEXT.md" || value === "PLAN.md" || value === "SUMMARY.md";
+}
+function isReviewAnnotationKind(value) {
+    return value === "question" || value === "change" || value === "risk" || value === "nit";
+}
+function isExtensionStatus(value) {
+    return typeof value === "string" && EXTENSION_STATUSES.includes(value);
+}
+function isIsoDate(value) {
+    if (!/^\d{4}-\d{2}-\d{2}T/.test(value)) {
+        return false;
+    }
+    const time = Date.parse(value);
+    return Number.isFinite(time);
+}
+function isFlowStateValue(value) {
+    return (isRecord(value) &&
+        typeof value.id === "string" &&
+        typeof value.title === "string" &&
+        isOpenFlowLevel(value.level) &&
+        isOpenFlowStage(value.stage) &&
+        Number.isInteger(value.revision) &&
+        isFlowGate(value.gate));
+}
+function isReviewResultValue(value) {
+    return (isRecord(value) &&
+        (value.stage === "spec" || value.stage === "plan" || value.stage === "prd" || value.stage === "archive") &&
+        Number.isInteger(value.revision) &&
+        isReviewStatus(value.status) &&
+        typeof value.reviewedAt === "string" &&
+        Array.isArray(value.comments) &&
+        Array.isArray(value.requestedChanges));
+}
+function isExtensionResultValue(value) {
+    return (isRecord(value) &&
+        typeof value.name === "string" &&
+        isExtensionStatus(value.status) &&
+        typeof value.required === "boolean" &&
+        typeof value.summary === "string" &&
+        Array.isArray(value.artifacts) &&
+        typeof value.createdAt === "string");
+}
+function validateKnowledgeCitations(value, path, issues) {
+    if (!Array.isArray(value)) {
+        issues.push(error("flow.knowledgeCitations.type", "flow.knowledge_citations must be an array.", path));
+        return;
+    }
+    for (let index = 0; index < value.length; index += 1) {
+        const item = value[index];
+        const itemPath = `${path}[${index}]`;
+        if (!isRecord(item)) {
+            issues.push(error("flow.knowledgeCitations.item", "Each knowledge_citations entry must be an object.", itemPath));
+            continue;
+        }
+        if (typeof item.id !== "string" || item.id.trim().length === 0) {
+            issues.push(error("flow.knowledgeCitations.id", "Each citation must have a non-empty id.", `${itemPath}.id`));
+        }
+        if (item.phase !== "spec" && item.phase !== "implement") {
+            issues.push(error("flow.knowledgeCitations.phase", "Citation phase must be spec or implement.", `${itemPath}.phase`));
+        }
+        if ("wave" in item && item.wave !== null && typeof item.wave !== "string") {
+            issues.push(error("flow.knowledgeCitations.wave", "Citation wave must be a string or null.", `${itemPath}.wave`));
+        }
+        if (typeof item.injected_at !== "string" || !/^\d{4}-\d{2}-\d{2}$/.test(item.injected_at)) {
+            issues.push(error("flow.knowledgeCitations.injectedAt", "Citation injected_at must be a YYYY-MM-DD date.", `${itemPath}.injected_at`));
+        }
+    }
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isLanguageTag(value) {
+    return typeof value === "string" && /^[A-Za-z]{2,3}(?:-[A-Za-z0-9]{2,8})*$/.test(value.trim());
+}
+function nonEmptyString(value) {
+    return typeof value === "string" && value.trim().length > 0;
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function error(code, message, path) {
+    return { code, message, path, severity: "error" };
+}
+function warning(code, message, path) {
+    return { code, message, path, severity: "warning" };
+}
+function withIssues(issues) {
+    return fromIssues(issues.map((issue) => ({ severity: "error", ...issue })));
+}
+function fromIssues(issues) {
+    return {
+        valid: issues.every((issue) => issue.severity !== "error"),
+        issues
+    };
+}
+//# sourceMappingURL=artifacts.js.map