@phuthuycoding/kanban-flow 0.3.0

package/dist/workflow/schema.js

@@ -0,0 +1,148 @@
+export const STAGES = [
+    "brainstorm",
+    "planning",
+    "backlog",
+    "implementation",
+    "testing",
+    "review",
+    "dones",
+    "cancelled",
+];
+export const ARTIFACT_IDS = [
+    "spec-requirement",
+    "implementation-plan",
+    "use-case-specification",
+    "use-case-diagram",
+    "test-cases",
+    "testing-result",
+    "review-report",
+    "feature-report",
+];
+/** Artifacts that belong to the full feature planning/closure contract only. */
+export const FEATURE_ONLY_ARTIFACTS = [
+    "implementation-plan",
+    "use-case-specification",
+    "use-case-diagram",
+    "test-cases",
+    "feature-report",
+];
+export const ARTIFACTS = {
+    "spec-requirement": {
+        id: "spec-requirement",
+        file: "phase-1-spec-requirement.md",
+        template: "phase-1-spec-requirement.md",
+        phase: "brainstorm",
+        dueFromStage: 0,
+        unlocks: "Phase 1 done — precise requirement agreed with the human",
+    },
+    "implementation-plan": {
+        id: "implementation-plan",
+        file: "phase-2-implementation-plan.md",
+        template: "phase-2-implementation-plan.md",
+        phase: "plan",
+        dueFromStage: 1,
+        unlocks: "Execution contract — scope, tasks, impact, DoD",
+    },
+    "use-case-specification": {
+        id: "use-case-specification",
+        file: "phase-2-use-case-specification.md",
+        template: "phase-2-use-case-specification.md",
+        phase: "plan",
+        dueFromStage: 1,
+        unlocks: "Detailed use case contracts (UC-XXX) for tests and implementation",
+    },
+    "use-case-diagram": {
+        id: "use-case-diagram",
+        file: "phase-2-use-case-diagram.md",
+        template: "phase-2-use-case-diagram.md",
+        phase: "plan",
+        dueFromStage: 1,
+        unlocks: "Visual overview of actors and use cases",
+    },
+    "test-cases": {
+        id: "test-cases",
+        file: "phase-2-test-case.md",
+        template: "phase-2-test-case.md",
+        phase: "plan",
+        dueFromStage: 1,
+        unlocks: "Traceable tests (TC-XXX → FR-XXX/UC-XXX) driving implementation and testing",
+    },
+    "testing-result": {
+        id: "testing-result",
+        file: "phase-4-testing-result.md",
+        template: "phase-4-testing-result.md",
+        phase: "test",
+        dueFromStage: 4,
+        unlocks: "Phase 4 done — PASS gates testing → review; FAIL/REJECT loops back to implementation",
+    },
+    "review-report": {
+        id: "review-report",
+        file: "phase-5-review-report.md",
+        template: "phase-5-review-report.md",
+        phase: "review",
+        dueFromStage: 5,
+        unlocks: "Phase 5 done — review result gates review → dones",
+    },
+    "feature-report": {
+        id: "feature-report",
+        file: "phase-6-feature-report.md",
+        template: "phase-6-feature-report.md",
+        phase: "artifact",
+        dueFromStage: 6,
+        unlocks: "Phase 6 — overall Feature Report completes the feature",
+    },
+};
+/**
+ * Transition gate: artifacts that must exist & be filled to LEAVE the stage
+ * (i.e. to advance to the next stage).
+ */
+export const STAGE_GATES = {
+    brainstorm: ["spec-requirement"],
+    planning: ["implementation-plan", "use-case-specification", "use-case-diagram", "test-cases"],
+    backlog: [],
+    implementation: [],
+    testing: ["testing-result"],
+    review: ["review-report"],
+    dones: [],
+    cancelled: [],
+};
+/**
+ * Allowed transitions between stages.
+ * Forward: one step at a time. Backtrack (loop) edges per the workflow:
+ * a FAIL/REJECT testing/review result sends the feature back to implementation.
+ */
+export const TRANSITIONS = {
+    brainstorm: ["planning"],
+    planning: ["implementation", "backlog"],
+    backlog: ["implementation", "planning"],
+    implementation: ["testing", "planning"],
+    testing: ["review", "implementation", "planning"],
+    review: ["dones", "implementation", "planning"],
+    dones: [],
+    // Entered through `kf cancel`, left only back to the stage it was cancelled from.
+    cancelled: [],
+};
+export const STAGE_INDEX = {
+    brainstorm: 0,
+    planning: 1,
+    backlog: 2,
+    implementation: 3,
+    testing: 4,
+    review: 5,
+    dones: 6,
+    /** Off the linear track on purpose: a negative index turns every "is this artifact due yet"
+     *  and "past planning" comparison false, so a cancelled item is never asked for anything. */
+    cancelled: -1,
+};
+/** Name used by `kf status` for the current phase. */
+export const PHASE_NAMES = {
+    brainstorm: "Phase 1 — Brainstorming",
+    planning: "Phase 2 — Planning",
+    backlog: "Backlog — Awaiting a decision to start",
+    implementation: "Phase 3 — Implement",
+    testing: "Phase 4 — Testing",
+    review: "Phase 5 — Review",
+    dones: "Phase 6 — Artifact",
+    cancelled: "Cancelled — stopped for good",
+};
+export const METADATA_FILE = ".kfw.json";

package/dist/workflow/secrets.js

@@ -0,0 +1,52 @@
+const SECRET_PATTERNS = [
+    { re: /\bAuthorization\s*:\s*Bearer\s+([A-Za-z0-9._~+/=-]{12,})/i, high: false },
+    { re: /\bCookie\s*:\s*([^;\n]{12,})/i, high: false },
+    { re: /\b(?:API[_-]?KEY|TOKEN|SECRET|PASSWORD)\s*=\s*["']?([^\s"']{8,})/i, high: false },
+    { re: /\b((?:ghp|gho|ghu|ghs|github_pat)_[A-Za-z0-9_]{20,})/, high: true },
+    { re: /\b(sk-[A-Za-z0-9]{20,})/, high: true },
+    { re: /\b(AKIA[0-9A-Z]{16})\b/, high: true },
+    { re: /\b(xox[baprs]-[A-Za-z0-9-]{10,})/, high: true },
+    { re: /(-----BEGIN [A-Z ]*PRIVATE KEY-----)/, high: true },
+    // A JWT needs all three base64url segments. `eyJ` alone is just base64 for `{"`, which any
+    // encoded JSON blob starts with, so matching the prefix on its own would fire on harmless data.
+    { re: /\b(eyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,})/, high: true },
+    { re: /\b(https:\/\/hooks\.slack\.com\/services\/[A-Za-z0-9/+_-]{20,})/, high: true },
+    { re: /\b(https:\/\/(?:ptb\.|canary\.)?discord(?:app)?\.com\/api\/webhooks\/[0-9]+\/[A-Za-z0-9_-]{20,})/, high: true },
+    // Group 1 is the password, not the whole URL, so the placeholder exemption and the masking
+    // done on output both land on the part that actually matters. A URL with no password is not a
+    // secret: `postgres://localhost/db` has nothing to leak.
+    //
+    // This one is NOT high-confidence, unlike the three above. Those match a prefix that only a
+    // real credential carries — `ghp_`, `eyJ…`, the Slack host — so no wording on the line should
+    // excuse them. A connection string has no such marker: it is pure URL shape, which a perfectly
+    // honest template like `scheme://user:<password>@host` also has. Marking it high made the
+    // scanner reject documentation for describing the very format it was taught to find.
+    { re: /\b[a-z][a-z0-9+.-]*:\/\/[^\s:@/]*:([^\s:@/]{3,})@/, high: false },
+];
+const PLACEHOLDERISH = /\{[^}\n]{0,60}\}|<[a-z0-9_ -]+>|\*{3,}|x{4,}|\b(?:redacted|masked|example|changeme|placeholder|dummy|sample)\b|\byour[_-]/i;
+const MASKED_VALUE = /^[A-Za-z_-]*?[xX*]{4,}$/;
+function isPlaceholderValue(value, high) {
+    return high ? MASKED_VALUE.test(value) : PLACEHOLDERISH.test(value);
+}
+/**
+ * Return lines that look like real secrets. The placeholder exemption is applied
+ * to the captured value only, so a comment such as "# example" on the same line
+ * cannot excuse a real credential. Hits are masked: only the first characters of
+ * the value are kept so callers can log them safely.
+ */
+export function findSecretLike(content) {
+    const hits = [];
+    for (const line of content.split("\n")) {
+        for (const { re, high } of SECRET_PATTERNS) {
+            const match = re.exec(line);
+            if (!match)
+                continue;
+            const value = match[1];
+            if (isPlaceholderValue(value, high))
+                continue;
+            hits.push(line.trim().replace(value, `${value.slice(0, 4)}…`).slice(0, 80));
+            break;
+        }
+    }
+    return hits;
+}

package/dist/workflow/status.js

@@ -0,0 +1,188 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { STAGES, ARTIFACTS, FEATURE_ONLY_ARTIFACTS, STAGE_INDEX, PHASE_NAMES, } from "./schema.js";
+import { splitFrontmatter, isFilledFile } from "../shared/frontmatter.js";
+import { executionContractHash } from "./features.js";
+import { validateFeature } from "./validate.js";
+function readArtifactContent(dir, file) {
+    const p = join(dir, file);
+    if (!existsSync(p))
+        return "";
+    return readFileSync(p, "utf8");
+}
+export function countTasks(content) {
+    const lines = content.split("\n");
+    let done = 0;
+    let total = 0;
+    for (const line of lines) {
+        if (/^\s*- \[ \]/.test(line))
+            total += 1;
+        else if (/^\s*- \[[xX]\]/.test(line)) {
+            total += 1;
+            done += 1;
+        }
+    }
+    return { done, total };
+}
+function assignedFor(feature, harness) {
+    const chain = harness?.stages[feature.stage] ?? [];
+    if (chain.length === 1 && chain[0] === harness?.main)
+        return [];
+    return chain.map((role) => ({ role, runner: harness?.roles[role]?.runner ?? "?" }));
+}
+/** Compute artifact completion status for a feature at its current stage. */
+export function computeStatus(feature, harness) {
+    const stageIndex = STAGE_INDEX[feature.stage];
+    const artifacts = [];
+    let doneCount = 0;
+    let dueCount = 0;
+    for (const id of Object.keys(ARTIFACTS)) {
+        if (feature.meta?.kind === "bug" && FEATURE_ONLY_ARTIFACTS.includes(id))
+            continue;
+        const def = ARTIFACTS[id];
+        const path = join(feature.dir, def.file);
+        const exists = existsSync(path);
+        const raw = readArtifactContent(feature.dir, def.file);
+        const { fm, body } = splitFrontmatter(raw);
+        const current = (id !== "testing-result" && id !== "review-report")
+            || (Boolean(feature.meta?.executionId) && fm.execution === feature.meta?.executionId);
+        const filled = exists && isFilledFile(raw, body) && current;
+        const due = stageIndex >= def.dueFromStage;
+        let status;
+        let note = "";
+        if (exists && filled) {
+            status = "done";
+            doneCount += 1;
+        }
+        else if (due) {
+            status = "missing";
+            note = exists ? current ? "not filled (placeholders or empty)" : "report belongs to a different execution" : "file missing";
+            dueCount += 1;
+        }
+        else {
+            status = "waiting";
+            const dueStage = STAGES[def.dueFromStage];
+            note = `due at ${PHASE_NAMES[dueStage]}`;
+        }
+        artifacts.push({ id, file: def.file, exists, filled, due, status, path, note });
+    }
+    const tasksPath = join(feature.dir, "tasks.md");
+    const taskProgress = existsSync(tasksPath)
+        ? countTasks(readFileSync(tasksPath, "utf8"))
+        : { done: 0, total: 0 };
+    const next = artifacts.find((a) => a.due && a.status !== "done")?.id ?? null;
+    // Straight from the real validator — no second set of rules. `approval_required` is the one
+    // ERROR left out: it is not a defect in the artifacts but the human gate, and the `Approval:`
+    // field and the `Next:` line below already say so. Listing it here would put a red ERROR on
+    // every correctly-prepared item sitting in planning, which is exactly where the signal matters.
+    const blockers = validateFeature(feature).issues
+        .filter((i) => i.severity === "ERROR" && i.code !== "approval_required");
+    return {
+        feature,
+        stageIndex,
+        artifacts,
+        doneCount,
+        dueCount,
+        totalCount: artifacts.length,
+        next,
+        blockers,
+        taskProgress,
+        assignedRoles: assignedFor(feature, harness),
+    };
+}
+/** Render a human-readable status snapshot (mirrors `openspec status`). */
+export function renderStatusText(s) {
+    const lines = [];
+    const ready = s.artifacts.filter((a) => a.status !== "waiting");
+    const done = ready.filter((a) => a.status === "done").length;
+    const taskStr = s.taskProgress.total > 0
+        ? `, tasks ${s.taskProgress.done}/${s.taskProgress.total}`
+        : "";
+    const approval = approvalState(s.feature);
+    lines.push(`${s.feature.meta?.kind === "bug" ? "Bug" : "Feature"}: ${s.feature.name} (${s.feature.context ?? "no-context"})`);
+    lines.push(`Stage: ${s.feature.stage} (${PHASE_NAMES[s.feature.stage]})   Approval: ${approval}   Artifacts: ${done}/${ready.length}${taskStr}`);
+    if (s.feature.meta?.executionId)
+        lines.push(`Execution: ${s.feature.meta.executionId}`);
+    const bypasses = s.feature.meta?.bypasses ?? [];
+    if (bypasses.length > 0)
+        lines.push(`Bypasses: ${bypasses.length} (${bypasses.map((b) => `--${b.flag} → ${b.to}`).join(", ")})`);
+    const cancellation = s.feature.meta?.cancellation;
+    if (cancellation) {
+        lines.push(`Cancelled: ${cancellation.at} by ${cancellation.by} (was ${cancellation.fromStage}) — ${cancellation.reason.split("\n")[0]}`);
+    }
+    if (s.assignedRoles.length > 0)
+        lines.push(`Assigned: ${s.assignedRoles.map((a) => `${a.role} (${a.runner})`).join(" → ")} (kf run)`);
+    const runs = s.feature.meta?.runs ?? [];
+    if (runs.length > 0) {
+        const byRole = new Map();
+        for (const r of runs)
+            byRole.set(r.role, (byRole.get(r.role) ?? 0) + 1);
+        lines.push(`Runs: ${runs.length} (${[...byRole].map(([a, n]) => `${a}×${n}`).join(", ")})`);
+    }
+    lines.push("");
+    for (const a of s.artifacts) {
+        const mark = a.status === "done" ? "[x]" : a.status === "missing" ? "[ ]" : "[-]";
+        const suffix = a.status === "done" ? "" : `  ${a.note}`;
+        lines.push(`${mark} ${a.id}${suffix}`);
+    }
+    if (s.blockers.length > 0) {
+        lines.push("");
+        lines.push(`Blocking (${s.blockers.length}) — kf validate --change "${s.feature.name}" for the full report:`);
+        for (const b of s.blockers)
+            lines.push(`  [ERROR] ${b.file}: ${b.message} (${b.code})`);
+    }
+    if (s.next) {
+        lines.push("");
+        lines.push(`Next: kf instruct ${s.next} --change "${s.feature.name}"`);
+    }
+    else if (s.blockers.length > 0) {
+        // Naming a next step that is going to be refused is the whole bug. Say what to fix instead.
+        lines.push("");
+        lines.push(`Next: clear the blocking findings above, then re-run kf status.`);
+    }
+    else if (s.feature.stage === "planning" && approval !== "approved") {
+        lines.push(`Next: human approval, then kf approve "${s.feature.name}"`);
+    }
+    else if (s.feature.stage === "planning" && approval === "approved") {
+        lines.push(`Next: human decision — kf stage "${s.feature.name}" implementation (start) or backlog (defer)`);
+    }
+    else if (s.feature.stage === "backlog") {
+        lines.push(`Next: human decision — kf stage "${s.feature.name}" implementation (start) or planning (revise)`);
+    }
+    return lines.join("\n");
+}
+/** Render a JSON-serializable status object. */
+export function statusToJson(s) {
+    return {
+        feature: s.feature.name,
+        kind: s.feature.meta?.kind ?? "feature",
+        context: s.feature.context,
+        stage: s.feature.stage,
+        approval: approvalState(s.feature),
+        executionId: s.feature.meta?.executionId ?? null,
+        bypasses: s.feature.meta?.bypasses ?? [],
+        cancellation: s.feature.meta?.cancellation ?? null,
+        assignedRoles: s.assignedRoles,
+        runs: s.feature.meta?.runs ?? [],
+        artifacts: s.artifacts.map((a) => ({
+            id: a.id,
+            file: a.file,
+            status: a.status,
+            due: a.due,
+            path: a.path,
+            note: a.note,
+        })),
+        doneCount: s.doneCount,
+        dueCount: s.dueCount,
+        totalCount: s.totalCount,
+        next: s.next,
+        blockers: s.blockers,
+        tasks: s.taskProgress,
+    };
+}
+export function approvalState(feature) {
+    const approval = feature.meta?.approval;
+    if (approval?.status !== "approved")
+        return "pending";
+    return approval.contractHash && approval.contractHash === executionContractHash(feature.dir, feature.meta?.kind === "bug" ? "bug" : "feature") ? "approved" : "changed";
+}

package/dist/workflow/validate-approval.js

@@ -0,0 +1,25 @@
+import { STAGE_INDEX } from "./schema.js";
+import { executionContractHash } from "./features.js";
+import { finding } from "./findings.js";
+/** Approval binds the requirement and planning artifacts throughout execution. */
+export function checkApproval(feature, requireApproval) {
+    if (STAGE_INDEX[feature.stage] < STAGE_INDEX.planning || !requireApproval)
+        return [];
+    const isBug = feature.meta?.kind === "bug";
+    const status = feature.meta?.approval?.status ?? "pending";
+    if (status !== "approved") {
+        return [finding(feature, "ERROR", "plan", "approval_required", "Execution contract not approved by a human (Phase 2 gate). Return to planning and run: kf approve <feature>")];
+    }
+    if (!feature.meta?.approval?.contractHash || feature.meta.approval.contractHash !== executionContractHash(feature.dir, isBug ? "bug" : "feature")) {
+        return [finding(feature, "ERROR", "plan", "approval_changed", "Execution contract changed or has no approval fingerprint. Return to planning for human approval.")];
+    }
+    return [];
+}
+/** Deliberate bypasses are recorded, never hidden: surface them on every validation. */
+export function checkBypasses(feature) {
+    const bypasses = feature.meta?.bypasses ?? [];
+    if (bypasses.length === 0)
+        return [];
+    const last = bypasses[bypasses.length - 1];
+    return [finding(feature, "WARNING", ".kfw.json", "gate_bypassed", `${bypasses.length} gate/hook bypass${bypasses.length > 1 ? "es" : ""} recorded (last: --${last.flag} ${last.from ?? "?"} → ${last.to} at ${last.at}); review them before trusting this item`)];
+}

package/dist/workflow/validate-artifacts.js

@@ -0,0 +1,89 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { ARTIFACTS, STAGE_GATES, STAGE_INDEX, FEATURE_ONLY_ARTIFACTS } from "./schema.js";
+import { splitFrontmatter, isFilledFile } from "../shared/frontmatter.js";
+import { findSecretLike } from "./secrets.js";
+import { finding } from "./findings.js";
+/** Each artifact that is DUE at the current stage must exist, be filled and contain no secrets. */
+export function checkDueArtifacts(feature) {
+    const issues = [];
+    const stageIndex = STAGE_INDEX[feature.stage];
+    const isBug = feature.meta?.kind === "bug";
+    for (const id of Object.keys(ARTIFACTS)) {
+        const def = ARTIFACTS[id];
+        if (isBug && FEATURE_ONLY_ARTIFACTS.includes(id))
+            continue;
+        const path = join(feature.dir, def.file);
+        if (stageIndex < def.dueFromStage)
+            continue;
+        if (!existsSync(path)) {
+            issues.push(finding(feature, "ERROR", def.file, "artifact_missing", `Required artifact ${def.file} is missing`));
+            continue;
+        }
+        const content = readFileSync(path, "utf8");
+        if (!isFilledFile(content, splitFrontmatter(content).body)) {
+            issues.push(finding(feature, "ERROR", def.file, "artifact_unfilled", `${def.file} is empty or still contains template placeholders (needs real content)`));
+        }
+    }
+    return issues;
+}
+/**
+ * Secrets in any artifact that is on disk, whatever stage the item is in.
+ *
+ * This deliberately does NOT share the `dueFromStage` guard above. A credential is a credential
+ * whether or not the workflow has reached the phase that asks for the file, and `cancelled` sits
+ * at `STAGE_INDEX = -1`, which made that guard skip every artifact — so cancelling an item was
+ * the quietest way to take a committed token off the radar while leaving it in the repo.
+ */
+export function checkSecrets(feature) {
+    const issues = [];
+    const isBug = feature.meta?.kind === "bug";
+    for (const id of Object.keys(ARTIFACTS)) {
+        const def = ARTIFACTS[id];
+        if (isBug && FEATURE_ONLY_ARTIFACTS.includes(id))
+            continue;
+        const path = join(feature.dir, def.file);
+        if (!existsSync(path))
+            continue;
+        const secrets = findSecretLike(readFileSync(path, "utf8"));
+        if (secrets.length > 0) {
+            issues.push(finding(feature, "ERROR", def.file, "artifact_secret", `${def.file} contains secret-like content (${secrets.length} line${secrets.length > 1 ? "s" : ""}) — remove credentials from workflow artifacts`));
+        }
+    }
+    return issues;
+}
+/** Stage gate: to leave the current stage, gate artifacts must be complete and the requirement confirmed. */
+export function checkStageGate(feature) {
+    const issues = [];
+    const isBug = feature.meta?.kind === "bug";
+    for (const id of STAGE_GATES[feature.stage]) {
+        if (isBug && FEATURE_ONLY_ARTIFACTS.includes(id))
+            continue;
+        const def = ARTIFACTS[id];
+        const path = join(feature.dir, def.file);
+        if (!existsSync(path)) {
+            issues.push(finding(feature, "ERROR", def.file, "gate_blocked", `Cannot leave stage "${feature.stage}" — ${def.file} is missing`));
+            continue;
+        }
+        const raw = readFileSync(path, "utf8");
+        if (!isFilledFile(raw, splitFrontmatter(raw).body)) {
+            issues.push(finding(feature, "ERROR", def.file, "gate_blocked", `Cannot leave stage "${feature.stage}" — ${def.file} is not filled`));
+        }
+    }
+    // Scoped to the stages that still owe a confirmed requirement. Unguarded it fired everywhere:
+    // an archived item whose spec reads `status: archived`, or one in review reading `approved`,
+    // were both told the requirement must be confirmed "before leaving brainstorm".
+    //
+    // It must keep firing at `planning`, not only at `brainstorm`: `kf approve` validates there,
+    // and this is the only check that reads the spec's status. Narrowing it to brainstorm alone
+    // let `kf approve` seal a contract whose requirement had been reopened to `pending`, and the
+    // fingerprint cannot catch that — it hashes the spec as it stands at approval time, so the
+    // pending state becomes the contract and it is the later *correction* that reads as drift.
+    const specPath = join(feature.dir, ARTIFACTS["spec-requirement"].file);
+    const owesConfirmation = STAGE_INDEX[feature.stage] <= STAGE_INDEX.planning;
+    if (owesConfirmation && existsSync(specPath)
+        && splitFrontmatter(readFileSync(specPath, "utf8")).fm.status !== "confirmed") {
+        issues.push(finding(feature, "ERROR", ARTIFACTS["spec-requirement"].file, "requirement_unconfirmed", "Requirement must have status: confirmed before the contract is approved or leaves brainstorm."));
+    }
+    return issues;
+}

package/dist/workflow/validate-cancel.js

@@ -0,0 +1,14 @@
+import { finding } from "./findings.js";
+/**
+ * A cancelled item is asked for nothing else (its stage index is negative), so
+ * the one thing it must carry is why it was stopped. Without that it is just a
+ * folder nobody can explain.
+ */
+export function checkCancellation(feature) {
+    if (feature.stage !== "cancelled")
+        return [];
+    const reason = feature.meta?.cancellation?.reason?.trim();
+    if (reason)
+        return [];
+    return [finding(feature, "ERROR", ".kfw.json", "cancellation_missing", "Cancelled work item has no recorded reason. Re-run: kf cancel <feature> --reason \"<why>\" (or move it back to its stage).")];
+}

package/dist/workflow/validate-reports.js

@@ -0,0 +1,121 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { ARTIFACTS, STAGE_INDEX } from "./schema.js";
+import { splitFrontmatter } from "../shared/frontmatter.js";
+import { countTasks } from "./status.js";
+import { finding } from "./findings.js";
+const TEST_RESULTS = /^(PASS|FAIL|REJECT|BLOCKED)$/;
+const REVIEW_RESULTS = /^(PASS|FAIL|REJECT|REQUIREMENT_BUG)$/;
+const COMMANDS_HEADING = /^##\s+Commands and Evidence\b/i;
+/**
+ * Exit-code column of every data row in the table under "## Commands and Evidence".
+ * Returns null when the section is absent. Cells are split on "|" so an escaped
+ * pipe inside a cell is not supported — the template never needs one.
+ */
+export function commandExitCodes(body) {
+    const lines = body.split("\n");
+    const start = lines.findIndex((line) => COMMANDS_HEADING.test(line));
+    if (start === -1)
+        return null;
+    const codes = [];
+    let rows = 0;
+    for (const line of lines.slice(start + 1)) {
+        if (/^##\s/.test(line))
+            break;
+        if (!line.trim().startsWith("|"))
+            continue;
+        rows += 1;
+        if (rows <= 2)
+            continue;
+        codes.push(line.split("|").map((cell) => cell.trim())[2] ?? "");
+    }
+    return codes;
+}
+/** tasks.md checkbox presence: without checkboxes progress cannot be tracked; unfinished tasks block dones. */
+export function checkTasks(feature) {
+    const issues = [];
+    const tasksPath = join(feature.dir, "tasks.md");
+    if (!existsSync(tasksPath))
+        return issues;
+    const { done, total } = countTasks(readFileSync(tasksPath, "utf8"));
+    if (total === 0) {
+        issues.push(finding(feature, "WARNING", "tasks.md", "no_tasks", 'tasks.md has no task checkboxes ("- [ ] 1. Task description"); progress cannot be tracked'));
+    }
+    if (feature.stage === "dones" && done < total) {
+        issues.push(finding(feature, "ERROR", "tasks.md", "tasks_incomplete_archived", `Feature has unfinished tasks (${done}/${total} done)`));
+    }
+    return issues;
+}
+/** testing-result semantics: PASS allows review; FAIL/REJECT must loop back; BLOCKED is a red flag. */
+export function checkTestingResult(feature) {
+    const issues = [];
+    const stageIndex = STAGE_INDEX[feature.stage];
+    const file = ARTIFACTS["testing-result"].file;
+    const trPath = join(feature.dir, file);
+    if (!existsSync(trPath) || stageIndex < STAGE_INDEX.testing)
+        return issues;
+    const { fm, body } = splitFrontmatter(readFileSync(trPath, "utf8"));
+    const status = fm.status ?? "";
+    if (!TEST_RESULTS.test(status)) {
+        issues.push(finding(feature, "ERROR", file, "testing_status", `testing-result status is "${status}"; expected PASS/FAIL/REJECT/BLOCKED`));
+    }
+    if (status === "PASS") {
+        const codes = commandExitCodes(body) ?? [];
+        const failing = codes.filter((code) => code !== "0").length;
+        if (codes.length === 0) {
+            issues.push(finding(feature, "ERROR", file, "testing_exit_code", "PASS requires at least one command row under \"## Commands and Evidence\" with exit code 0."));
+        }
+        else if (failing > 0) {
+            issues.push(finding(feature, "ERROR", file, "testing_exit_code", `PASS requires every command in "## Commands and Evidence" to exit 0 (${failing} row${failing > 1 ? "s" : ""} with a different exit code).`));
+        }
+    }
+    if (!feature.meta?.executionId || fm.execution !== feature.meta.executionId) {
+        issues.push(finding(feature, "ERROR", file, "testing_stale", "Testing report must reference the current execution id from kf status/instruct."));
+    }
+    if (stageIndex >= STAGE_INDEX.review && status !== "PASS") {
+        issues.push(finding(feature, "ERROR", file, "testing_not_pass", "Only a current PASS testing report may enter review or dones."));
+    }
+    if (/^(FAIL|REJECT)/i.test(status) && feature.stage === "testing") {
+        issues.push(finding(feature, "WARNING", file, "testing_loops_back", `Testing ${status.toUpperCase()}: must loop back to implementation (kf stage ${feature.name} implementation)`));
+    }
+    return issues;
+}
+/** review-report semantics: PASS allows archive; FAIL/REJECT loops back; REQUIREMENT_BUG stops the feature. */
+export function checkReviewReport(feature) {
+    const issues = [];
+    const stageIndex = STAGE_INDEX[feature.stage];
+    const file = ARTIFACTS["review-report"].file;
+    const rvPath = join(feature.dir, file);
+    if (!existsSync(rvPath) || stageIndex < STAGE_INDEX.review)
+        return issues;
+    const { fm } = splitFrontmatter(readFileSync(rvPath, "utf8"));
+    const status = fm.status ?? "";
+    if (!REVIEW_RESULTS.test(status)) {
+        issues.push(finding(feature, "ERROR", file, "review_status", `review-report status is "${status}"; expected PASS/FAIL/REJECT/REQUIREMENT_BUG`));
+    }
+    if (!feature.meta?.executionId || fm.execution !== feature.meta.executionId) {
+        issues.push(finding(feature, "ERROR", file, "review_stale", "Review report must reference the current execution id from kf status/instruct."));
+    }
+    if (feature.stage === "dones" && status !== "PASS") {
+        issues.push(finding(feature, "ERROR", file, "review_not_pass", "Only a current PASS review report may enter dones."));
+    }
+    if (/^(FAIL|REJECT)/i.test(status) && feature.stage === "review") {
+        issues.push(finding(feature, "WARNING", file, "review_loops_back", `Review ${status.toUpperCase()}: must loop back to implementation, then testing again (kf stage ${feature.name} implementation)`));
+    }
+    if (/^REQUIREMENT_BUG/i.test(status)) {
+        issues.push(finding(feature, "ERROR", file, "requirement_bug_stop", "REQUIREMENT_BUG: STOP FEATURE. Do not silently rewrite the requirement — report back to the human."));
+    }
+    return issues;
+}
+/** A feature in dones without its reports (and feature report) is incomplete. */
+export function checkDonesArtifacts(feature) {
+    if (feature.stage !== "dones")
+        return [];
+    const isBug = feature.meta?.kind === "bug";
+    const required = isBug
+        ? ["testing-result", "review-report"]
+        : ["testing-result", "review-report", "feature-report"];
+    return required
+        .filter((id) => !existsSync(join(feature.dir, ARTIFACTS[id].file)))
+        .map((id) => finding(feature, "ERROR", ARTIFACTS[id].file, "artifact_missing", `Archived feature is incomplete: ${ARTIFACTS[id].file} is missing`));
+}