@phuthuycoding/kanban-flow 0.3.0

package/dist/project/contexts.js

@@ -0,0 +1,98 @@
+import { listFeatures } from "../workflow/features.js";
+/** Fallback when neither `contexts` nor `defaultContext` is set. Matches the historical default. */
+export const FALLBACK_CONTEXT = "app";
+/**
+ * Contexts are compared case-insensitively when suggesting a correction: `assertPathName` accepts
+ * `Auth`, but on a case-sensitive filesystem that would be a second docs tree next to `auth`.
+ */
+export function normalizeContext(context) {
+    return context.trim().toLowerCase();
+}
+function levenshtein(a, b) {
+    // Single-row dynamic programming; the strings here are short context names.
+    let previous = Array.from({ length: b.length + 1 }, (_, i) => i);
+    for (let i = 1; i <= a.length; i += 1) {
+        const current = [i];
+        for (let j = 1; j <= b.length; j += 1) {
+            const substitution = previous[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1);
+            current[j] = Math.min(current[j - 1] + 1, previous[j] + 1, substitution);
+        }
+        previous = current;
+    }
+    return previous[b.length];
+}
+/**
+ * Nearest declared context, or null when nothing is close enough. A suggestion is always a verbatim
+ * element of `declared`, so following one is always accepted by `checkContext`.
+ */
+export function suggestContext(input, declared) {
+    const target = normalizeContext(input);
+    let best = null;
+    for (const name of declared) {
+        const candidate = normalizeContext(name);
+        // Budget from the longer of the two, so dropping characters does not shrink the allowance:
+        // keyed off the typo alone, "au" would be further from "auth" than "biling" is from "billing".
+        const span = Math.max(target.length, candidate.length);
+        const budget = Math.min(3, Math.max(1, Math.ceil(span / 3)));
+        const distance = levenshtein(target, candidate);
+        // The two must still share something: "b" and "a" are one edit apart and wholly unrelated.
+        if (distance <= budget && distance < span && (best === null || distance < best.distance)) {
+            best = { name, distance };
+        }
+    }
+    return best?.name ?? null;
+}
+/**
+ * The default context the config actually states, or null when it states none. `contexts` declares
+ * it by position, so there is no second field to drift out of sync and no config shape whose
+ * default its own guard rejects.
+ */
+export function declaredDefaultContext(cfg) {
+    if (cfg.contexts && cfg.contexts.length > 0)
+        return cfg.contexts[0];
+    return cfg.defaultContext ?? null;
+}
+/** The default context to act on, falling back to the historical value. */
+export function effectiveDefaultContext(cfg) {
+    return declaredDefaultContext(cfg) ?? FALLBACK_CONTEXT;
+}
+/** Check a context against the declared list. An undeclared project is unrestricted, as before. */
+export function checkContext(context, cfg) {
+    const declared = cfg.contexts;
+    if (!declared || declared.length === 0)
+        return { ok: true, suggestion: null, declared: [] };
+    if (declared.includes(context))
+        return { ok: true, suggestion: null, declared };
+    // A case-only difference is refused rather than folded: accepting `Auth` would create a second
+    // directory beside `auth` on a case-sensitive filesystem, which is the whole point of the list.
+    // No special case is needed for it: after normalising, the same name sits at distance 0, which
+    // no other candidate can beat, so suggestContext already returns exactly it.
+    return { ok: false, suggestion: suggestContext(context, declared), declared };
+}
+/** Human-readable refusal naming the input, the nearest declared name, and the whole list. */
+export function contextRefusal(context, check) {
+    const lines = [`"${context}" is not a declared context.`];
+    if (check.suggestion)
+        lines.push(`  Did you mean "${check.suggestion}"?`);
+    lines.push(`  Declared: ${check.declared.join(", ")}`);
+    lines.push("  Add one by editing contexts in .kf/config.json");
+    return lines.join("\n");
+}
+/**
+ * Contexts that work items actually use on disk, with a count each, busiest first.
+ *
+ * Grouped by the exact spelling, not a folded one. `Legacy` and `legacy` are two directories and
+ * therefore two rows: collapsing them would hide the case drift this feature exists to surface,
+ * and would make the surviving spelling depend on folder sort order. Callers compare exactly.
+ */
+export function contextsInUse(root) {
+    const counts = new Map();
+    for (const f of listFeatures(root)) {
+        if (!f.context)
+            continue;
+        counts.set(f.context, (counts.get(f.context) ?? 0) + 1);
+    }
+    return [...counts.entries()]
+        .map(([context, count]) => ({ context, count }))
+        .sort((a, b) => b.count - a.count || a.context.localeCompare(b.context));
+}

package/dist/project/doctor.js

@@ -0,0 +1,163 @@
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { STAGES } from "../workflow/schema.js";
+import { listFeatures, readFeatureMeta } from "../workflow/features.js";
+import { validateFeature } from "../workflow/validate.js";
+import { readProjectConfig, configPath } from "./config.js";
+import { AGENTS, DEFAULT_AGENT, projectSkillsDir, parseAgentIds } from "../integrations/agents.js";
+import { MANAGED_SKILLS } from "../integrations/install.js";
+/** Every stage needs its directory; a file sitting where one belongs counts as missing. */
+function checkStageDirs(root) {
+    const missing = STAGES.filter((stage) => {
+        const dir = join(root, ".works", stage);
+        if (!existsSync(dir))
+            return true;
+        try {
+            return !statSync(dir).isDirectory();
+        }
+        catch {
+            // Unreadable is as unusable as absent, and saying so beats crashing.
+            return true;
+        }
+    });
+    if (missing.length === 0)
+        return [];
+    return [{
+            level: "ERROR",
+            area: ".works/",
+            message: `Missing stage ${missing.length === 1 ? "directory" : "directories"}: ${missing.join(", ")}`,
+            action: "kf init --minimal (recreates the stage directories; existing work items are left alone)",
+        }];
+}
+/**
+ * The config check has to survive a config it cannot read — that is the case it exists for.
+ * readProjectConfig throws on bad JSON and on a bad shape, so the throw is caught here and turned
+ * into the diagnosis. This is not swallowing: the error becomes the answer the command returns.
+ */
+function checkConfig(root) {
+    const path = configPath(root);
+    if (!existsSync(path)) {
+        return {
+            findings: [{ level: "WARNING", area: ".kf/config.json", message: "No project config; defaults are in use.", action: "kf init --defaults" }],
+            cfg: null,
+        };
+    }
+    try {
+        return { findings: [], cfg: readProjectConfig(root) };
+    }
+    catch (err) {
+        return {
+            findings: [{
+                    level: "ERROR",
+                    area: ".kf/config.json",
+                    message: `Cannot read the project config: ${err instanceof Error ? err.message : String(err)}`,
+                    action: "fix the JSON by hand, or delete .kf/config.json and re-run kf init",
+                }],
+            cfg: null,
+        };
+    }
+}
+/** A work item whose metadata cannot be read is invisible to every other command. */
+function checkItemMetadata(root) {
+    const findings = [];
+    for (const f of listFeatures(root)) {
+        try {
+            readFeatureMeta(f.dir);
+        }
+        catch (err) {
+            findings.push({
+                level: "ERROR",
+                area: `${f.stage}/${f.folder}`,
+                message: `Unreadable metadata: ${err instanceof Error ? err.message : String(err)}`,
+                action: `fix ${join(f.dir, ".kfw.json")} by hand`,
+            });
+            continue;
+        }
+        if (!f.meta) {
+            findings.push({
+                level: "ERROR",
+                area: `${f.stage}/${f.folder}`,
+                message: "No .kfw.json — the item is invisible to approval and execution tracking.",
+                action: `write ${join(f.dir, ".kfw.json")}, or remove the folder if it is not a work item`,
+            });
+        }
+    }
+    return findings;
+}
+/** Skills can be installed and then deleted; nothing notices until a worker has no instructions. */
+function checkSkills(root, agents) {
+    const findings = [];
+    for (const id of agents) {
+        const adapter = AGENTS.find((a) => a.id === id);
+        if (!adapter)
+            continue;
+        const dir = projectSkillsDir(adapter, root);
+        const missing = MANAGED_SKILLS.filter((s) => !existsSync(join(dir, s, "SKILL.md")));
+        if (missing.length === 0)
+            continue;
+        findings.push({
+            level: "ERROR",
+            area: dir,
+            message: `${missing.length} of ${MANAGED_SKILLS.length} skills missing: ${missing.join(", ")}`,
+            action: `kf install --agent ${id}`,
+        });
+    }
+    return findings;
+}
+/** Config fields that still parse but no longer mean what someone reading them would assume. */
+function checkLegacyFields(root, cfg) {
+    if (!cfg)
+        return [];
+    const findings = [];
+    const raw = readRawConfig(root);
+    if (cfg.contexts && cfg.contexts.length > 0 && raw?.defaultContext !== undefined) {
+        findings.push({
+            level: "WARNING",
+            area: ".kf/config.json",
+            message: `defaultContext "${String(raw.defaultContext)}" is ignored because contexts is declared; the default is contexts[0] = "${cfg.contexts[0]}".`,
+            action: "remove defaultContext, or reorder contexts so the intended default is first",
+        });
+    }
+    if (raw?.stack !== undefined && raw?.stacks !== undefined) {
+        findings.push({
+            level: "WARNING",
+            area: ".kf/config.json",
+            message: "Both stack (legacy, singular) and stacks are set; only stacks is read.",
+            action: "remove the legacy stack field",
+        });
+    }
+    return findings;
+}
+/** The file as written, not as normalised by readProjectConfig, which fills stacks in from stack. */
+function readRawConfig(root) {
+    try {
+        const parsed = JSON.parse(readFileSync(configPath(root), "utf8"));
+        return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : null;
+    }
+    catch {
+        // checkConfig already reported an unreadable config; a second finding would be noise.
+        return null;
+    }
+}
+/** Diagnose a project. Read-only: nothing here writes, moves or deletes. */
+export function runDoctor(root) {
+    const findings = [];
+    findings.push(...checkStageDirs(root));
+    const config = checkConfig(root);
+    findings.push(...config.findings);
+    findings.push(...checkLegacyFields(root, config.cfg));
+    const agents = config.cfg?.agents ? parseAgentIds(config.cfg.agents) : [DEFAULT_AGENT];
+    findings.push(...checkSkills(root, agents.length > 0 ? agents : [DEFAULT_AGENT]));
+    findings.push(...checkItemMetadata(root));
+    // Invalid work items are the normal state of a running pipeline, so they are counted and
+    // reported but deliberately kept out of `findings` — they must not decide the verdict.
+    const items = listFeatures(root);
+    const invalidItems = items.filter((f) => !validateFeature(f).valid).length;
+    return {
+        root,
+        findings,
+        invalidItems,
+        totalItems: items.length,
+        ok: findings.every((f) => f.level !== "ERROR"),
+    };
+}

package/dist/shared/frontmatter.js

@@ -0,0 +1,54 @@
+/**
+ * Minimal YAML frontmatter support (key: value lines). No external deps.
+ * Used only for the standard `---` blocks in our templates.
+ */
+/** Extract the frontmatter block and body from a markdown file. */
+export function splitFrontmatter(content) {
+    if (!content.startsWith("---")) {
+        return { fm: {}, body: content };
+    }
+    const end = content.indexOf("\n---", 3);
+    if (end === -1)
+        return { fm: {}, body: content };
+    const block = content.slice(3, end).trim();
+    const body = content.slice(end + 4);
+    const fm = {};
+    for (const line of block.split("\n")) {
+        const idx = line.indexOf(":");
+        if (idx === -1)
+            continue;
+        const key = line.slice(0, idx).trim();
+        const value = line.slice(idx + 1).trim();
+        if (key && !/^\s/.test(line))
+            fm[key] = value.replace(/^["']|["']$/g, "");
+    }
+    return { fm, body };
+}
+/** Serialize frontmatter back into a `---\n...\n---\n` document. */
+export function applyFrontmatter(fm, body) {
+    const keys = Object.keys(fm);
+    if (keys.length === 0)
+        return body;
+    const block = keys.map((k) => `${k}: ${fm[k]}`).join("\n");
+    const trimmed = body.replace(/^\n+/, "");
+    return `---\n${block}\n---\n${trimmed}`;
+}
+/** Get one frontmatter key value (string) if present. */
+export function getFmValue(content, key) {
+    const { fm } = splitFrontmatter(content);
+    return fm[key] ?? null;
+}
+/** Returns true if the content still contains unresolved template placeholder tokens like `{feature_name}`. Tokens inside code blocks and inline code are literal content, not placeholders. */
+export function hasUnresolvedPlaceholders(content) {
+    const stripped = content
+        .replace(/```[\s\S]*?(```|$)/g, "")
+        .replace(/`[^`\n]*`/g, "");
+    return /\{[a-z0-9_-]+\}/i.test(stripped);
+}
+/** True when an artifact file is considered "filled" — exists, non-empty, no template tokens left. */
+export function isFilledFile(raw, body) {
+    const text = body.trim();
+    if (text.length === 0)
+        return false;
+    return !hasUnresolvedPlaceholders(raw);
+}

package/dist/shared/paths.js

@@ -0,0 +1,78 @@
+import { existsSync, statSync } from "node:fs";
+import { mkdir, writeFile, rename, rm } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { findWorksRoot } from "../workflow/features.js";
+export const USER_KABAN_DIR = resolve(homedir(), ".kf");
+function findPackageRoot() {
+    let dir = dirname(fileURLToPath(import.meta.url));
+    for (let i = 0; i < 8; i += 1) {
+        if (existsSync(join(dir, "package.json")))
+            return dir;
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return dir;
+}
+export const PKG_ROOT = findPackageRoot();
+export const PKG_TEMPLATES_DIR = join(PKG_ROOT, "kanban-flow", "templates");
+export const PKG_RULES_DIR = join(PKG_ROOT, "kanban-flow", "review", "rules");
+export const PKG_STACK_RULES_DIR = join(PKG_ROOT, "kanban-flow", "review", "stacks");
+/**
+ * Find a kanban-flow config dir relative to project root (project overrides).
+ * Project layout: {project}/.kf/{templates|hooks|review/rules}
+ */
+function projectKabanDir(cwd) {
+    return join(findWorksRoot(cwd) ?? cwd, ".kf");
+}
+/** Resolve one template file. Precedence: project → user → package. */
+export function resolveTemplate(cwd, template) {
+    const candidates = [
+        ["project", join(projectKabanDir(cwd), "templates", template)],
+        ["user", join(USER_KABAN_DIR, "templates", template)],
+        ["package", join(PKG_TEMPLATES_DIR, template)],
+    ];
+    for (const [source, path] of candidates) {
+        if (existsSync(path))
+            return { name: template, path, source };
+    }
+    return null;
+}
+/** Resolve a review rule file. Precedence: project → user → package. */
+export function resolveRule(cwd, rule) {
+    const candidates = [
+        ["project", join(projectKabanDir(cwd), "review", "rules", rule)],
+        ["user", join(USER_KABAN_DIR, "review", "rules", rule)],
+        ["package", join(PKG_RULES_DIR, rule)],
+    ];
+    for (const [source, path] of candidates) {
+        if (existsSync(path))
+            return { name: rule, path, source };
+    }
+    return null;
+}
+/** Read a template's raw text (for `kf instruct`). */
+export async function readTemplate(cwd, template) {
+    const resolved = resolveTemplate(cwd, template);
+    if (!resolved)
+        return null;
+    return (await import("node:fs/promises")).readFile(resolved.path, "utf8");
+}
+export async function ensureDir(dir) {
+    await mkdir(dir, { recursive: true });
+}
+export async function writeFileAtomic(file, content) {
+    await ensureDir(dirname(file));
+    const temp = `${file}.${randomUUID()}.tmp`;
+    try {
+        await writeFile(temp, content, { encoding: "utf8", flag: "wx", mode: existsSync(file) ? statSync(file).mode & 0o777 : 0o600 });
+        await rename(temp, file);
+    }
+    finally {
+        await rm(temp, { force: true });
+    }
+}

package/dist/shared/time.js

@@ -0,0 +1,5 @@
+export function nowTimestamp() {
+    const d = new Date();
+    const pad = (n) => String(n).padStart(2, "0");
+    return `${d.getFullYear()}${pad(d.getMonth() + 1)}${pad(d.getDate())}_${pad(d.getHours())}${pad(d.getMinutes())}`;
+}

package/dist/workflow/direction.js

@@ -0,0 +1,56 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { ARTIFACTS } from "./schema.js";
+import { splitFrontmatter } from "../shared/frontmatter.js";
+import { countTasks } from "./status.js";
+import { finding } from "./findings.js";
+/**
+ * Checks whether the CURRENT stage allows leaving toward `to`.
+ * This is the semantic half of the gate: it reads the report STATUS, not just
+ * artifact existence. The artifact gate (validateFeature) and the transition
+ * graph (TRANSITIONS) both still apply on top.
+ * Returns a list of blocking findings (empty = allowed).
+ */
+export function checkDirectionGate(feature, to) {
+    const issues = [];
+    const read = (file) => {
+        const p = join(feature.dir, file);
+        if (!existsSync(p))
+            return null;
+        const { fm } = splitFrontmatter(readFileSync(p, "utf8"));
+        return fm.status ?? null;
+    };
+    // implementation → testing requires all tracked tasks done (DoD).
+    if (feature.stage === "implementation" && to === "testing") {
+        const tasksPath = join(feature.dir, "tasks.md");
+        if (existsSync(tasksPath)) {
+            const { done, total } = countTasks(readFileSync(tasksPath, "utf8"));
+            if (done < total) {
+                issues.push(finding(feature, "ERROR", "tasks.md", "tasks_incomplete", `Feature has unfinished tasks (${done}/${total} done) — complete them before testing`));
+            }
+        }
+    }
+    // testing → review requires PASS; testing → implementation required on FAIL.
+    if (feature.stage === "testing") {
+        const file = ARTIFACTS["testing-result"].file;
+        const status = read(file);
+        if (to === "review" && status !== "PASS") {
+            issues.push(finding(feature, "ERROR", file, "testing_not_pass", `testing-result status is ${status ?? "missing"}; only PASS may enter review (FAIL/REJECT must loop back to implementation)`));
+        }
+        if (to === "implementation" && status === "PASS") {
+            issues.push(finding(feature, "ERROR", file, "testing_already_pass", "testing-result is PASS — looping back to implementation hides passing tests; re-run kf stage <feature> review instead"));
+        }
+    }
+    // review → dones requires PASS; REQUIREMENT_BUG stops the feature entirely.
+    if (feature.stage === "review") {
+        const file = ARTIFACTS["review-report"].file;
+        const status = read(file);
+        if (to === "dones" && status !== "PASS") {
+            issues.push(finding(feature, "ERROR", file, "review_not_pass", `review-report status is ${status ?? "missing"}; only PASS may enter dones (FAIL/REJECT loop to implementation)`));
+        }
+        if (status === "REQUIREMENT_BUG") {
+            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;
+}

package/dist/workflow/features.js

@@ -0,0 +1,198 @@
+import { readdirSync, existsSync, statSync, mkdirSync, readFileSync } from "node:fs";
+import { join, resolve, dirname } from "node:path";
+import { createHash } from "node:crypto";
+import { STAGES, ARTIFACTS, STAGE_GATES, METADATA_FILE } from "./schema.js";
+import { writeFileAtomic } from "../shared/paths.js";
+/** Walk up from cwd to find the directory containing `.works/`. */
+export function findWorksRoot(start) {
+    let dir = resolve(start);
+    for (;;) {
+        if (existsSync(join(dir, ".works")))
+            return dir;
+        const parent = dirname(dir);
+        if (parent === dir)
+            return null;
+        dir = parent;
+    }
+}
+/** A feature folder is `{feature}_{YYYYMMDD_HHmm}` (timestamp trailing part). */
+export function parseFolderName(folder) {
+    const m = /^(.+?)_(\d{8}_\d{4})$/.exec(folder);
+    if (m)
+        return { name: m[1], ts: m[2] };
+    return { name: folder, ts: null };
+}
+export function readFeatureMeta(dir) {
+    const f = join(dir, METADATA_FILE);
+    if (!existsSync(f))
+        return null;
+    let meta;
+    try {
+        meta = JSON.parse(readFileSync(f, "utf8"));
+    }
+    catch (err) {
+        if (err instanceof SyntaxError)
+            throw new Error(`Invalid JSON in feature metadata: ${f}`, { cause: err });
+        throw err;
+    }
+    if (!meta || meta.schema !== "kanban-flow" || typeof meta.feature !== "string"
+        || typeof meta.context !== "string" || typeof meta.created !== "string"
+        || (meta.kind !== undefined && !["feature", "bug"].includes(meta.kind))
+        || (meta.executionId !== undefined && typeof meta.executionId !== "string")
+        || (meta.approval !== undefined && (!meta.approval
+            || !["pending", "approved"].includes(meta.approval.status)
+            || (meta.approval.contractHash !== undefined && typeof meta.approval.contractHash !== "string")))
+        || (meta.bypasses !== undefined && (!Array.isArray(meta.bypasses) || !meta.bypasses.every(isBypass)))
+        || (meta.sessions !== undefined && (!meta.sessions || typeof meta.sessions !== "object" || Array.isArray(meta.sessions)
+            || !Object.values(meta.sessions).every((s) => typeof s === "string")))
+        || (meta.runs !== undefined && (!Array.isArray(meta.runs) || !meta.runs.every(isRunRecord)))
+        || (meta.status !== undefined && meta.status !== "archived" && meta.status !== "cancelled")
+        || (meta.cancellation !== undefined && !isCancellation(meta.cancellation))) {
+        throw new Error(`Invalid feature metadata: ${f}`);
+    }
+    assertPathName(meta.feature, "feature");
+    assertPathName(meta.context, "context");
+    return meta;
+}
+function isBypass(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const b = value;
+    return typeof b.at === "string" && (b.from === null || (typeof b.from === "string" && STAGES.includes(b.from)))
+        && typeof b.to === "string" && STAGES.includes(b.to)
+        && (b.flag === "force" || b.flag === "skip-hooks")
+        && Array.isArray(b.codes) && b.codes.every((c) => typeof c === "string");
+}
+function isCancellation(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const c = value;
+    return typeof c.at === "string" && typeof c.by === "string" && typeof c.reason === "string"
+        && typeof c.fromStage === "string" && STAGES.includes(c.fromStage);
+}
+const RUN_STATUSES = ["running", "done", "failed", "timeout", "reset"];
+function isRunRecord(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const r = value;
+    if (r.chain !== undefined && (typeof r.chain !== "object" || r.chain === null
+        || typeof r.chain.id !== "string" || typeof r.chain.index !== "number" || typeof r.chain.total !== "number"))
+        return false;
+    return typeof r.id === "string" && typeof r.role === "string" && typeof r.runner === "string"
+        && typeof r.stage === "string" && STAGES.includes(r.stage)
+        && (r.mode === "start" || r.mode === "resume") && typeof r.at === "string" && typeof r.log === "string"
+        && typeof r.status === "string" && RUN_STATUSES.includes(r.status);
+}
+export async function writeFeatureMeta(dir, meta) {
+    await writeFileAtomic(join(dir, METADATA_FILE), `${JSON.stringify(meta, null, 2)}\n`);
+}
+export function assertPathName(value, label) {
+    if (!/^[a-z0-9][a-z0-9_-]*$/i.test(value)) {
+        throw new Error(`Invalid ${label} '${value}': use letters, digits, hyphens or underscores, starting with a letter or digit.`);
+    }
+}
+export function executionContractHash(dir, kind = "feature") {
+    const hash = createHash("sha256");
+    const contractArtifacts = kind === "bug"
+        ? ["spec-requirement"]
+        : ["spec-requirement", ...STAGE_GATES.planning];
+    for (const id of contractArtifacts) {
+        const file = ARTIFACTS[id].file;
+        const path = join(dir, file);
+        if (!existsSync(path))
+            return null;
+        hash.update(JSON.stringify([file, readFileSync(path, "utf8")]));
+    }
+    if (kind === "feature") {
+        const useCaseDir = join(dir, "use-cases");
+        if (existsSync(useCaseDir)) {
+            for (const file of readdirSync(useCaseDir).filter((entry) => /^UC-\d+\.md$/i.test(entry)).sort()) {
+                hash.update(JSON.stringify([`use-cases/${file}`, readFileSync(join(useCaseDir, file), "utf8")]));
+            }
+        }
+    }
+    return hash.digest("hex");
+}
+/** True only for a real, readable directory. Anything else is not a stage we can walk. */
+function isDirectory(path) {
+    const stats = statSync(path, { throwIfNoEntry: false });
+    return stats !== undefined && stats.isDirectory();
+}
+/** List all features found under a `.works` root, in stage order (brainstorm → dones). */
+export function listFeatures(root) {
+    const out = [];
+    // Within a stage, sort by folder name desc — the trailing timestamp approximates newest first.
+    for (const stage of STAGES) {
+        const stageDir = join(root, ".works", stage);
+        // A stage path that is not a directory — a stray file, a dangling link — used to reach
+        // readdirSync and throw ENOTDIR out of every command that lists work items. A malformed
+        // tree is exactly when `kf list` and `kf doctor` have to keep working; `kf doctor` reports
+        // the missing stage separately, so skipping here loses nothing.
+        if (!isDirectory(stageDir))
+            continue;
+        const folders = readdirSync(stageDir)
+            .map((folder) => {
+            const dir = join(stageDir, folder);
+            // `throwIfNoEntry: false` covers exactly one case: a symlink whose target is gone. That
+            // used to throw a raw ENOENT out of every command that lists features, so one dangling
+            // link made `kf list` — the command you run to find out what is wrong — unusable. Any
+            // other stat failure (EACCES, ELOOP) still propagates; this is not a blanket guard.
+            //
+            // A missing target falls through rather than returning null: if the name looks like a
+            // work item it is reported with no metadata, so `kf validate` calls it invalid instead
+            // of the item silently disappearing.
+            const stats = statSync(dir, { throwIfNoEntry: false });
+            if (stats && !stats.isDirectory())
+                return null;
+            const parsed = parseFolderName(folder);
+            let meta = null;
+            let metaError;
+            try {
+                meta = readFeatureMeta(dir);
+            }
+            catch (err) {
+                metaError = err instanceof Error ? err.message : String(err);
+            }
+            if (!meta && !metaError && !parsed.ts)
+                return null;
+            return { folder, dir, name: (meta && meta.feature) || parsed.name, meta, metaError };
+        })
+            .filter((x) => x !== null)
+            .sort((a, b) => (b.folder.localeCompare(a.folder)));
+        for (const f of folders) {
+            out.push({
+                name: f.name,
+                context: f.meta ? f.meta.context : null,
+                stage,
+                dir: f.dir,
+                folder: f.folder,
+                meta: f.meta,
+                metaError: f.metaError,
+            });
+        }
+    }
+    return out;
+}
+/** Find a single feature by name across all stages. */
+export function findFeature(root, name) {
+    const matches = listFeatures(root).filter((f) => f.name === name || f.folder === name);
+    if (matches.length > 1) {
+        throw new Error(`Ambiguous feature '${name}': select its full folder name (${matches.map((f) => f.folder).join(", ")}).`);
+    }
+    return matches[0] ?? null;
+}
+/** Ensure the workflow folders and canonical documentation roots exist under root. */
+export function ensureWorksStructure(root) {
+    for (const stage of STAGES) {
+        mkdirSync(join(root, ".works", stage), { recursive: true });
+    }
+    for (const docsDir of ["requirement", "use-cases", "testplan"]) {
+        mkdirSync(join(root, "docs", docsDir), { recursive: true });
+    }
+}
+export function stageDir(root, stage) {
+    return join(root, ".works", stage);
+}
+export function featureFolderName(feature, ts) {
+    return `${feature}_${ts}`;
+}

package/dist/workflow/findings.js

@@ -0,0 +1,3 @@
+export function finding(feature, severity, file, code, message) {
+    return { severity, feature: feature.name, stage: feature.stage, file, code, message };
+}