@phuthuycoding/kanban-flow 0.3.0

package/dist/cli/commands/contexts.js

@@ -0,0 +1,101 @@
+import { readProjectConfig } from "../../project/config.js";
+import { contextsInUse, normalizeContext } from "../../project/contexts.js";
+import { findRoot } from "./helpers.js";
+/**
+ * The brief a worker reads when no list exists yet. It states the grouping rule, the size, and that
+ * the human decides — the last one is a promise in prose, not something the CLI can enforce.
+ */
+function surveyBrief(inUse) {
+    const lines = [
+        "No contexts declared in .kf/config.json.",
+        "",
+        "Survey this repo and propose a context list:",
+        "- read the top-level source directories and the package manifests",
+        "- group by business domain, not by technical layer: billing and catalog,",
+        "  never frontend and backend",
+        "- propose 3 to 7 names, one word each; where a context is already in use,",
+        "  match the spelling the work items use rather than re-casing it",
+        "- show them to the human and write only the list they confirm to",
+        "  .kf/config.json as \"contexts\"; the first entry becomes the default",
+        "",
+        "Do not write the list on your own. Naming a business domain is the",
+        "product owner's call, not something to infer from a directory tree.",
+        "",
+    ];
+    lines.push(inUse.length === 0
+        ? "No work item uses a context yet."
+        : `Contexts currently in use on disk: ${inUse.map((c) => `${c.context} (${c.count})`).join(", ")}`);
+    return lines.join("\n");
+}
+const plural = (n) => `${n} work item${n === 1 ? "" : "s"}`;
+export async function cmdContexts(args, cwd) {
+    const root = await findRoot(cwd);
+    if (!root.ok)
+        return { code: 1, stdout: root.err, stderr: "no works" };
+    const cfg = readProjectConfig(root.root);
+    const inUse = contextsInUse(root.root);
+    const declared = cfg.contexts ?? [];
+    // Exact comparison on both sides. `kf new` accepts a context only on an exact match, so
+    // "declared" here must mean the same thing, or the advice below becomes a lie.
+    const countOf = (name) => inUse.find((u) => u.context === name)?.count ?? 0;
+    const missing = inUse.filter((u) => !declared.includes(u.context));
+    // "Can this name be added?" depends on every other name that would sit beside it, not just on
+    // what is already declared: two undeclared spellings of one name collide with each other too,
+    // and readProjectConfig refuses the repeat either way.
+    const undeclared = missing.map((u) => {
+        const key = normalizeContext(u.context);
+        // Every partner, not the first one found: with a declared clash AND another in-use spelling,
+        // naming only one produces two instructions that cannot both be obeyed, and the reader
+        // bounces between them forever. Only one name in the whole group can ever be declared.
+        const declaredClash = declared.find((d) => normalizeContext(d) === key) ?? null;
+        const inUseClashes = missing.filter((o) => o.context !== u.context && normalizeContext(o.context) === key).map((o) => o.context);
+        return { ...u, collidesWith: declaredClash ?? inUseClashes[0] ?? null, collidesWithDeclared: declaredClash !== null, declaredClash, inUseClashes };
+    });
+    const collisionAdvice = (u) => {
+        const others = [...(u.declaredClash ? [`declared "${u.declaredClash}"`] : []), ...u.inUseClashes.map((c) => `"${c}" (also in use)`)];
+        const list = others.length > 1 ? `${others.slice(0, -1).join(", ")} and ${others[others.length - 1]}` : others[0];
+        return [
+            `    ⚠ differs only by case from ${list}.`,
+            "      The config refuses two names that differ only by case, so only one of",
+            `      these ${others.length + 1} names can be declared. Rename the other work items first.`,
+        ];
+    };
+    const clashing = undeclared.filter((u) => u.inUseClashes.length > 0);
+    // One brief, built once. Splitting it produced a text warning and a JSON brief without one,
+    // and --json is the mode an agent reads, so the warning went missing exactly where it counts.
+    const briefText = clashing.length === 0
+        ? surveyBrief(inUse)
+        : [surveyBrief(inUse), "", "Before you write the list, note:",
+            ...clashing.flatMap((u) => [`  ${u.context}`, ...collisionAdvice(u)])].join("\n");
+    if (args.options.json) {
+        return {
+            code: 0,
+            stdout: JSON.stringify({
+                declared: declared.map((name, index) => ({ name, count: countOf(name), default: index === 0 })),
+                undeclared,
+                restricted: declared.length > 0,
+                // UC-003's actor is an agent, and --json is the mode an agent reads: it needs the brief most.
+                ...(declared.length === 0 ? { brief: briefText } : {}),
+            }, null, 2),
+        };
+    }
+    if (declared.length === 0)
+        return { code: 0, stdout: briefText };
+    const lines = ["Declared contexts:"];
+    for (const [index, name] of declared.entries()) {
+        const marker = index === 0 ? "  (default)" : "";
+        lines.push(`  ${name.padEnd(16)} ${plural(countOf(name))}${marker}`);
+    }
+    if (undeclared.length > 0) {
+        lines.push("", "In use but not declared:");
+        for (const u of undeclared) {
+            lines.push(`  ${u.context.padEnd(16)} ${plural(u.count)}`);
+            if (u.collidesWith)
+                lines.push(...collisionAdvice(u));
+        }
+        if (undeclared.some((u) => !u.collidesWith)) {
+            lines.push("", "kf new refuses these. Add the ones you want to keep to contexts in .kf/config.json.");
+        }
+    }
+    return { code: 0, stdout: lines.join("\n") };
+}

package/dist/cli/commands/doctor.js

@@ -0,0 +1,35 @@
+import { runDoctor } from "../../project/doctor.js";
+import { findRoot } from "./helpers.js";
+function renderFinding(f) {
+    const lines = [`  [${f.level}] ${f.area}: ${f.message}`];
+    if (f.action)
+        lines.push(`      → ${f.action}`);
+    return lines;
+}
+export async function cmdDoctor(args, cwd) {
+    const root = await findRoot(cwd);
+    if (!root.ok)
+        return { code: 1, stdout: root.err, stderr: "no works" };
+    const report = runDoctor(root.root);
+    if (args.options.json) {
+        return { code: report.ok ? 0 : 1, stdout: JSON.stringify(report, null, 2) };
+    }
+    const lines = [`Project: ${report.root}`, ""];
+    if (report.findings.length === 0) {
+        lines.push("No problems found.");
+    }
+    else {
+        for (const f of report.findings)
+            lines.push(...renderFinding(f));
+    }
+    lines.push("");
+    // Deliberately below the findings and outside them: an invalid work item is an ordinary state
+    // for a pipeline in motion, not a broken project, so it never changes the verdict.
+    lines.push(report.totalItems === 0
+        ? "Work items: none yet."
+        : `Work items: ${report.totalItems}, ${report.invalidItems} not currently valid` +
+            (report.invalidItems > 0 ? " — run: kf validate --all" : ""));
+    lines.push("");
+    lines.push(report.ok ? "✓ Healthy." : "✗ Problems found — see the ERROR lines above.");
+    return { code: report.ok ? 0 : 1, stdout: lines.join("\n"), stderr: report.ok ? undefined : "doctor found problems" };
+}

package/dist/cli/commands/harness.js

@@ -0,0 +1,60 @@
+import { existsSync } from "node:fs";
+import { delimiter, join } from "node:path";
+import { readProjectConfig } from "../../project/config.js";
+import { HARNESS_STAGES } from "../../harness/config.js";
+import { findWorksRoot } from "../../workflow/features.js";
+/** True when the runner's executable resolves on PATH (Windows also checks .cmd/.exe). */
+export function cliAvailable(cli, env = process.env) {
+    if (cli.includes("/") || cli.includes("\\"))
+        return existsSync(cli);
+    const dirs = (env.PATH ?? "").split(delimiter).filter(Boolean);
+    const names = process.platform === "win32" ? [cli, `${cli}.cmd`, `${cli}.exe`] : [cli];
+    return dirs.some((dir) => names.some((n) => existsSync(join(dir, n))));
+}
+function sessionKind(runner) {
+    if (runner.session === undefined)
+        return "none";
+    if (runner.session === "provided")
+        return "provided";
+    return "stdout" in runner.session ? "stdout" : "command";
+}
+function shorten(text, max = 60) {
+    if (!text)
+        return "";
+    return text.length <= max ? text : `${text.slice(0, max - 1)}…`;
+}
+export async function cmdHarness(args, cwd) {
+    const root = findWorksRoot(cwd) ?? cwd;
+    const harness = readProjectConfig(root).harness;
+    if (!harness) {
+        return { code: 1, stdout: "No harness configured in .kf/config.json — run: kf init (seeds roles and runner presets).", stderr: "no harness" };
+    }
+    const stages = HARNESS_STAGES.map((stage) => ({ stage, roles: harness.stages[stage] ?? [] }));
+    const roles = Object.entries(harness.roles).map(([name, role]) => ({
+        name, runner: role.runner, brief: role.brief ?? null, output: role.output ?? null,
+        available: cliAvailable(harness.runners[role.runner].start[0]),
+    }));
+    const runners = Object.entries(harness.runners).map(([name, runner]) => ({
+        name,
+        cli: runner.start[0],
+        available: cliAvailable(runner.start[0]),
+        resume: runner.resume !== undefined,
+        session: sessionKind(runner),
+        usage: runner.usage ?? null,
+    }));
+    if (args.options.json)
+        return { code: 0, stdout: JSON.stringify({ main: harness.main, stages, roles, runners }, null, 2) };
+    const lines = [
+        `main role: ${harness.main} (${harness.roles[harness.main].runner})`,
+        "",
+        "stages → roles:",
+        ...stages.map((s) => `  ${s.stage.padEnd(14)} ${s.roles.length > 0 ? s.roles.join(" → ") : `${harness.main} (main, not handed off)`}`),
+        "",
+        "roles → runners:",
+        ...roles.map((r) => `  ${r.name.padEnd(12)} ${r.runner.padEnd(10)} ${r.available ? "on PATH" : "missing"}${r.output ? `   output: ${r.output}` : ""}${r.brief ? `\n    ${shorten(r.brief, 96)}` : ""}`),
+        "",
+        "runners:",
+        ...runners.map((r) => `  ${r.name.padEnd(12)} ${r.cli.padEnd(10)} ${r.available ? "on PATH" : "missing"}   resume: ${r.resume ? "yes" : "no"}   session: ${r.session}${r.usage ? `   usage: ${r.usage}` : ""}`),
+    ];
+    return { code: 0, stdout: lines.join("\n") };
+}

package/dist/cli/commands/helpers.js

@@ -0,0 +1,22 @@
+import { findWorksRoot } from "../../workflow/features.js";
+import { nowTimestamp } from "../../shared/time.js";
+export async function findRoot(cwd) {
+    const root = findWorksRoot(cwd);
+    if (!root) {
+        return { root: "", ok: false, err: "No .works found. Run: kf init" };
+    }
+    return { root, ok: true };
+}
+/** Build the audit records for this transition: only bypasses that actually skipped something are recorded. */
+export function recordBypasses(from, to, forcedCodes, skippedHook) {
+    const at = nowTimestamp();
+    const records = [];
+    if (forcedCodes.length > 0)
+        records.push({ at, from, to, flag: "force", codes: [...new Set(forcedCodes)] });
+    if (skippedHook)
+        records.push({ at, from, to, flag: "skip-hooks", codes: [`hook:${skippedHook.path}`] });
+    return records;
+}
+export function bypassNote(recorded) {
+    return recorded.map((b) => `\n  ⚠ Bypass recorded: --${b.flag} (${b.codes.join(", ")})`).join("");
+}

package/dist/cli/commands/init.js

@@ -0,0 +1,119 @@
+import { mkdir } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { STAGES } from "../../workflow/schema.js";
+import { assertPathName, ensureWorksStructure } from "../../workflow/features.js";
+import { checkContext, contextRefusal, effectiveDefaultContext } from "../../project/contexts.js";
+import { readProjectConfig, detectStacks, writeProjectConfig, configPath } from "../../project/config.js";
+import { seedHarness } from "../../harness/config.js";
+import { nowTimestamp } from "../../shared/time.js";
+import { parseAgentIds } from "../../integrations/agents.js";
+import { installProjectSkills } from "../../integrations/install.js";
+import { hasWorkItems, bootstrapDefaults, onboardAnswers, seedOverrides, saveConfig, appendIgnoreWorks, seedAgentsFile } from "../../project/bootstrap.js";
+import { cmdNew } from "./new.js";
+export async function cmdInit(args, cwd) {
+    const target = resolve(cwd, args.positionals[0] ?? ".");
+    const agents = parseAgentIds(args.options.agent);
+    if (typeof args.options.context === "string") {
+        assertPathName(args.options.context, "context");
+        // Seeding docs/{ctx}/ for a context kf new would refuse leaves a tree nothing can ever fill.
+        // This runs before either branch, so --minimal and the bootstrap path are both covered.
+        const explicit = checkContext(args.options.context, readProjectConfig(target));
+        if (!explicit.ok)
+            return { code: 1, stdout: contextRefusal(args.options.context, explicit), stderr: "unknown context" };
+    }
+    const minimal = Boolean(args.options.minimal);
+    const useDefaults = Boolean(args.options.defaults);
+    if (!minimal) {
+        return cmdBootstrap(args, target, !useDefaults);
+    }
+    const cfg = readProjectConfig(target);
+    const ctx = typeof args.options.context === "string" ? args.options.context : effectiveDefaultContext(cfg);
+    // Same rule as the bootstrap path: an explicit --context on a genuinely new project is a
+    // decision and gets declared. --minimal writes a config anyway, so leaving it out here would
+    // mean the same command declares or not depending on a flag that says nothing about contexts.
+    const declareHere = typeof args.options.context === "string"
+        && cfg.contexts === undefined && !existsSync(configPath(target)) && !hasWorkItems(target);
+    ensureWorksStructure(target);
+    // A named context must be recorded even when FR-007 forbids declaring a list, or --minimal
+    // seeds docs/{ctx}/ and then sends every new item somewhere else — but only where nothing else
+    // already decides the default. With `contexts` present, `contexts[0]` is the default and
+    // `defaultContext` is ignored, so writing it would leave a config contradicting itself: the
+    // file naming one default while `kf new` and `kf contexts` use another.
+    const recordContext = typeof args.options.context === "string" && cfg.contexts === undefined;
+    // The write sits OUTSIDE the harness check on purpose. Every project kf init has already
+    // touched carries a harness, so guarding it on `!cfg.harness` meant the record never happened
+    // on any real project — only on the two config shapes a real init never produces.
+    if (!cfg.harness || recordContext) {
+        await mkdir(join(target, ".kf"), { recursive: true });
+        writeProjectConfig(target, {
+            ...cfg, schema: "kanban-flow", created: cfg.created ?? nowTimestamp(),
+            ...(declareHere ? { contexts: [ctx] } : {}),
+            ...(!declareHere && recordContext ? { defaultContext: ctx } : {}),
+            harness: cfg.harness ?? seedHarness(agents.length ? agents : parseAgentIds(cfg.agents)),
+        });
+    }
+    await mkdir(join(target, ".kf", "templates"), { recursive: true });
+    await mkdir(join(target, ".kf", "hooks"), { recursive: true });
+    await mkdir(join(target, ".kf", "review", "rules"), { recursive: true });
+    for (const docsDir of ["requirement", "use-cases", "testplan"]) {
+        await mkdir(join(target, "docs", docsDir, ctx), { recursive: true });
+    }
+    const skills = await installProjectSkills(target, agents.length ? agents : parseAgentIds(cfg.agents));
+    if (skills.code !== 0)
+        return skills;
+    const agentsFile = seedAgentsFile(target, cfg.stacks?.length ? cfg.stacks : detectStacks(target));
+    return {
+        code: 0,
+        stdout: `✓ Initialized kanban-flow in ${target}\n  .works/{${STAGES.join(",")}}\n  docs/{requirement,use-cases,testplan}/${ctx}\n  .kf/templates (project overrides)\n  .kf/hooks (phase hooks, e.g. hooks/planning.sh)\n  .kf/review/rules (project review rules)\n  AGENTS.md: ${agentsFile === "created" ? "created" : "kept existing AGENTS.md/CLAUDE.md"}\n\n${skills.stdout}`,
+    };
+}
+async function cmdBootstrap(args, target, interactive) {
+    const tty = process.stdin.isTTY && process.stdout.isTTY;
+    const explicitContext = typeof args.options.context === "string" ? args.options.context : undefined;
+    let answers;
+    if (interactive && !tty) {
+        answers = bootstrapDefaults(target, explicitContext);
+    }
+    else if (interactive) {
+        answers = await onboardAnswers(target, explicitContext);
+    }
+    else {
+        answers = bootstrapDefaults(target, explicitContext);
+    }
+    const flagged = parseAgentIds(args.options.agent);
+    if (flagged.length > 0)
+        answers.agents = flagged;
+    // Name validity lives in saveConfig, the one point every set of answers passes through;
+    // repeating it here would be a guard that can never fire.
+    ensureWorksStructure(target);
+    await seedOverrides(target);
+    saveConfig(target, answers);
+    const skills = await installProjectSkills(target, answers.agents);
+    if (skills.code !== 0)
+        return skills;
+    for (const docsDir of ["requirement", "use-cases", "testplan"]) {
+        await mkdir(join(target, "docs", docsDir, answers.defaultContext), { recursive: true });
+    }
+    const out = [];
+    out.push(`✓ Bootstrapped kanban-flow in ${target}${interactive && !tty ? " (non-interactive: using defaults)" : ""}`);
+    out.push(`  .works/{${STAGES.join(",")}}`);
+    const ctxLine = answers.contexts.length > 0 ? `contexts: ${answers.contexts.join(", ")}` : `context: ${answers.defaultContext} (not restricted)`;
+    out.push(`  ${ctxLine}   stacks: ${answers.stacks.join(", ") || "unset"}   reviewer: ${answers.reviewer}`);
+    out.push(`  agents: ${answers.agents.join(", ")}`);
+    out.push(`  .kf/config.json (defaults for new features)`);
+    out.push(`  .kf/{templates,hooks,review/rules} seeded from package`);
+    out.push(skills.stdout);
+    out.push(`  AGENTS.md: ${seedAgentsFile(target, answers.stacks) === "created" ? "created" : "kept existing AGENTS.md/CLAUDE.md"}`);
+    if (answers.ignoreWorks) {
+        appendIgnoreWorks(target);
+        out.push(`  .gitignore: added .works/`);
+    }
+    if (answers.seedFeature) {
+        const seed = await cmdNew({ command: "new", positionals: ["demo"], options: { context: answers.defaultContext } }, target);
+        if (seed.code !== 0)
+            return seed;
+        out.push(`  seeded demo feature → brainstorm`);
+    }
+    return { code: 0, stdout: out.join("\n") };
+}

package/dist/cli/commands/inspect.js

@@ -0,0 +1,141 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { ARTIFACTS } from "../../workflow/schema.js";
+import { findFeature, listFeatures } from "../../workflow/features.js";
+import { computeStatus, renderStatusText, statusToJson } from "../../workflow/status.js";
+import { validateFeature, renderValidateText, validateToJson } from "../../workflow/validate.js";
+import { dashboardData } from "../../dashboard/dashboard.js";
+import { readProjectConfig } from "../../project/config.js";
+import { findRoot } from "./helpers.js";
+export async function cmdList(args, cwd) {
+    const root = await findRoot(cwd);
+    if (!root.ok)
+        return { code: 1, stdout: root.err, stderr: "no works" };
+    const features = listFeatures(root.root);
+    if (args.options.json) {
+        return {
+            code: 0,
+            stdout: JSON.stringify(features.map((f) => ({
+                name: f.name,
+                kind: f.meta?.kind ?? "feature",
+                context: f.context,
+                stage: f.stage,
+                folder: f.folder,
+            })), null, 2),
+        };
+    }
+    if (features.length === 0) {
+        return { code: 0, stdout: "No features found." };
+    }
+    const lines = features.map((f) => `${f.stage.padEnd(14)} ${(f.meta?.kind === "bug" ? "[bug] " : "") + f.name}${f.context ? ` (${f.context})` : ""}`);
+    return { code: 0, stdout: lines.join("\n") };
+}
+export async function cmdShow(args, cwd) {
+    const name = args.positionals[0];
+    if (!name)
+        return { code: 1, stdout: "Missing feature name.", stderr: "missing feature" };
+    const root = await findRoot(cwd);
+    if (!root.ok)
+        return { code: 1, stdout: root.err, stderr: "no works" };
+    const f = findFeature(root.root, name);
+    if (!f)
+        return { code: 1, stdout: `Unknown feature '${name}'. Run: kf list`, stderr: "unknown feature" };
+    const specPath = join(f.dir, ARTIFACTS["spec-requirement"].file);
+    let content;
+    try {
+        content = await readFile(specPath, "utf8");
+    }
+    catch (err) {
+        if (!(err instanceof Error && "code" in err && err.code === "ENOENT"))
+            throw err;
+        content = `(no ${ARTIFACTS["spec-requirement"].file} in ${f.dir})`;
+    }
+    if (args.options.json) {
+        return { code: 0, stdout: JSON.stringify({ feature: f.name, kind: f.meta?.kind ?? "feature", context: f.context, stage: f.stage, spec: content }) };
+    }
+    return { code: 0, stdout: content };
+}
+export async function cmdView(args, cwd) {
+    const root = await findRoot(cwd);
+    if (!root.ok)
+        return { code: 1, stdout: root.err, stderr: "no works" };
+    const data = dashboardData(root.root);
+    if (args.options.json)
+        return { code: 0, stdout: JSON.stringify(data, null, 2) };
+    const m = data.metrics;
+    const lines = [
+        "kanban-flow analytics", "",
+        `Total: ${m.total} (${m.features} features, ${m.bugs} bugs)`,
+        `Executing: ${m.executing}   Backlog: ${m.backlog}   Completed: ${m.completed}   Cancelled: ${m.cancelled}   Bypassed: ${m.bypassed}`,
+        `Completion rate: ${m.completionRate === null ? "N/A" : m.completionRate + "%"} (cancelled work excluded)`,
+        `Executing tasks: ${m.tasks.done}/${m.tasks.total} (${m.tasks.completionRate === null ? "N/A" : m.tasks.completionRate + "%"})`,
+        ...(Object.keys(m.runs.byRole).length > 0
+            ? ["", "Worker runs by role:", ...Object.entries(m.runs.byRole).map(([role, r]) => `  ${role.padEnd(12)} ${r.runs} runs (${r.done} done, ${r.failed} failed)${m.runs.usage[role] ? `  ${m.runs.usage[role].input} in / ${m.runs.usage[role].output} out` : ""}`)]
+            : []),
+        "", "By stage:",
+        ...data.charts.byStage.map((row) => `  ${row.id.padEnd(14)} ${row.count} (${row.features} features, ${row.bugs} bugs)`),
+        "", "By context:",
+        ...data.charts.byContext.map((row) => `  ${row.label}: ${row.count} (${row.features} features, ${row.bugs} bugs)`),
+        "", "Approval (planning through review):",
+        ...data.charts.approvals.map((row) => `  ${row.id}: ${row.count}`),
+    ];
+    return { code: 0, stdout: lines.join("\n") };
+}
+export async function cmdStatus(args, cwd) {
+    const root = await findRoot(cwd);
+    if (!root.ok)
+        return { code: 1, stdout: root.err, stderr: "no works" };
+    const json = Boolean(args.options.json);
+    const all = Boolean(args.options.all);
+    const change = typeof args.options.change === "string" ? args.options.change : null;
+    if (!change && !all) {
+        return { code: 1, stdout: 'Missing required option --change <feature> (or --all for every feature).\nRun: kf list', stderr: "missing --change" };
+    }
+    const features = change
+        ? (() => { const f = findFeature(root.root, change); return f ? [f] : []; })()
+        : listFeatures(root.root);
+    if (change && features.length === 0) {
+        return { code: 1, stdout: `Unknown feature '${change}'. Run: kf list`, stderr: "unknown feature" };
+    }
+    const harness = readProjectConfig(root.root).harness;
+    const statuses = features.map((f) => computeStatus(f, harness));
+    if (json) {
+        return {
+            code: 0,
+            stdout: JSON.stringify(change
+                ? statusToJson(statuses[0])
+                : { features: statuses.map(statusToJson) }, null, 2),
+        };
+    }
+    if (statuses.length === 0) {
+        return { code: 0, stdout: "No active features. Create one with: kf new <feature> --context <ctx>" };
+    }
+    const blocks = statuses.map(renderStatusText);
+    return { code: 0, stdout: blocks.join("\n\n") };
+}
+export async function cmdValidate(args, cwd) {
+    const root = await findRoot(cwd);
+    if (!root.ok)
+        return { code: 1, stdout: root.err, stderr: "no works" };
+    const json = Boolean(args.options.json);
+    const strict = Boolean(args.options.strict);
+    const all = Boolean(args.options.all);
+    const change = typeof args.options.change === "string" ? args.options.change : null;
+    if (!change && !all) {
+        return { code: 1, stdout: 'Missing required option --change <feature> (or --all).', stderr: "missing --change" };
+    }
+    const features = change
+        ? (() => { const f = findFeature(root.root, change); return f ? [f] : []; })()
+        : listFeatures(root.root);
+    if (change && features.length === 0) {
+        return { code: 1, stdout: `Unknown feature '${change}'.`, stderr: "unknown feature" };
+    }
+    const results = features.map((f) => validateFeature(f, strict));
+    const allValid = results.every((r) => r.valid);
+    if (json) {
+        return { code: allValid ? 0 : 1, stdout: JSON.stringify(results.map(validateToJson), null, 2), stderr: allValid ? undefined : "validation failed" };
+    }
+    const blocks = results.map(renderValidateText);
+    const codes = blocks.join("\n") + `\nTotals: ${results.filter((r) => r.valid).length} passed, ${results.filter((r) => !r.valid).length} failed (${results.length} items)`;
+    return { code: allValid ? 0 : 1, stdout: codes, stderr: allValid ? undefined : "validation failed" };
+}

package/dist/cli/commands/new.js

@@ -0,0 +1,80 @@
+import { mkdir, writeFile, rm } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { ARTIFACTS } from "../../workflow/schema.js";
+import { assertPathName, listFeatures, featureFolderName, writeFeatureMeta, stageDir } from "../../workflow/features.js";
+import { readProjectConfig } from "../../project/config.js";
+import { checkContext, contextRefusal, declaredDefaultContext, effectiveDefaultContext } from "../../project/contexts.js";
+import { readTemplate } from "../../shared/paths.js";
+import { nowTimestamp } from "../../shared/time.js";
+import { runHook } from "../../integrations/hooks.js";
+import { findRoot } from "./helpers.js";
+export async function cmdNew(args, cwd) {
+    const feature = args.positionals[0];
+    if (!feature) {
+        return { code: 1, stdout: "Missing feature name. Usage: kf new <feature> --context <ctx>", stderr: "missing feature" };
+    }
+    assertPathName(feature, "feature");
+    const kindRaw = args.options.type;
+    const kindValue = kindRaw === undefined ? "feature" : String(kindRaw);
+    if (kindValue !== "feature" && kindValue !== "bug") {
+        return { code: 1, stdout: `Unknown work item type '${kindValue}'. Expected feature or bug.`, stderr: "invalid type" };
+    }
+    const kind = kindValue;
+    const root = await findRoot(cwd);
+    if (!root.ok)
+        return { code: 1, stdout: root.err, stderr: "no works" };
+    if (listFeatures(root.root).some((f) => f.name === feature)) {
+        return { code: 1, stdout: `Feature '${feature}' already exists. Select it with kf status --change ${feature}.`, stderr: "feature exists" };
+    }
+    const cfg = readProjectConfig(root.root);
+    // The config's own answer wins; only when it states none do we guess from existing work items.
+    const ctx = typeof args.options.context === "string"
+        ? args.options.context
+        : declaredDefaultContext(cfg) ?? listFeatures(root.root).find((f) => f.context)?.context ?? effectiveDefaultContext(cfg);
+    assertPathName(ctx, "context");
+    // Only bites once the project has declared a list; an undeclared project behaves exactly as before.
+    const check = checkContext(ctx, cfg);
+    if (!check.ok)
+        return { code: 1, stdout: contextRefusal(ctx, check), stderr: "unknown context" };
+    const requirementTemplate = kind === "bug" ? "phase-1-bug-report.md" : ARTIFACTS["spec-requirement"].template;
+    const tpl = await readTemplate(root.root, requirementTemplate);
+    if (!tpl)
+        return { code: 1, stdout: "Requirement template not found.", stderr: "no template" };
+    const ts = nowTimestamp();
+    const dir = join(stageDir(root.root, "brainstorm"), featureFolderName(feature, ts));
+    await mkdir(dirname(dir), { recursive: true });
+    try {
+        await mkdir(dir);
+    }
+    catch (err) {
+        if (err instanceof Error && "code" in err && err.code === "EEXIST") {
+            return { code: 1, stdout: `Feature folder already exists: ${dir}`, stderr: "feature exists" };
+        }
+        throw err;
+    }
+    await writeFeatureMeta(dir, {
+        schema: "kanban-flow",
+        feature,
+        context: ctx,
+        created: ts,
+        kind,
+        goal: typeof args.options.goal === "string" ? args.options.goal : undefined,
+    });
+    const rendered = tpl
+        .replaceAll("{feature_name}", feature)
+        .replaceAll("{Feature Name}", feature.split("-").map((w) => w[0]?.toUpperCase() + w.slice(1)).join(" "))
+        .replaceAll("{context}", ctx)
+        .replaceAll("{timestamp}", ts);
+    await writeFile(join(dir, ARTIFACTS["spec-requirement"].file), rendered, "utf8");
+    const hook = runHook(root.root, {
+        feature, context: ctx, dir, root: root.root, from: null, to: "brainstorm", approval: "pending",
+    });
+    if (hook.ran && !hook.ok) {
+        await rm(dir, { recursive: true });
+        return { code: 1, stdout: `Brainstorm hook failed (exit ${hook.code}). Feature creation rolled back.\n${hook.output}`, stderr: "hook failed" };
+    }
+    return {
+        code: 0,
+        stdout: `Created ${kind} '${feature}' at ${dir}/\nContext: ${ctx}\nNext: kf instruct spec-requirement --change "${feature}"`,
+    };
+}

package/dist/cli/commands/rules.js

@@ -0,0 +1,69 @@
+import { existsSync, mkdirSync, readFileSync } from "node:fs";
+import { copyFile } from "node:fs/promises";
+import { join } from "node:path";
+import { findWorksRoot } from "../../workflow/features.js";
+import { detectStacks, STACK_IDS } from "../../project/config.js";
+import { PKG_STACK_RULES_DIR } from "../../shared/paths.js";
+/** Copy stack-specific review rules from the package into .kf/review/rules/. */
+export async function cmdRules(args, cwd) {
+    const root = findWorksRoot(cwd) ?? cwd;
+    const detected = detectStacks(root);
+    const available = STACK_IDS.filter((id) => existsSync(join(PKG_STACK_RULES_DIR, `${id}.md`)));
+    if (args.options.list) {
+        return {
+            code: 0,
+            stdout: [
+                `Detected stacks: ${detected.join(", ") || "none"}`,
+                `Available rule packs: ${available.join(", ") || "none"}`,
+            ].join("\n"),
+        };
+    }
+    const requested = args.options.stack;
+    const stacks = Array.isArray(requested)
+        ? requested.map(String)
+        : typeof requested === "string"
+            ? [requested]
+            : detected;
+    if (stacks.length === 0) {
+        return {
+            code: 1,
+            stdout: `Cannot detect project stack. Pass --stack <id>. Available: ${available.join(", ")}`,
+            stderr: "no stack detected",
+        };
+    }
+    const invalid = stacks.filter((s) => !available.includes(s));
+    if (invalid.length > 0) {
+        return {
+            code: 1,
+            stdout: `Unknown stack '${invalid.join(", ")}'. Available: ${available.join(", ")}`,
+            stderr: "unknown stack",
+        };
+    }
+    const force = Boolean(args.options.force);
+    const rulesDir = join(root, ".kf", "review", "rules");
+    const lines = [];
+    for (const stack of stacks) {
+        const src = join(PKG_STACK_RULES_DIR, `${stack}.md`);
+        const dest = join(rulesDir, `${stack}.md`);
+        if (existsSync(dest)) {
+            if (readFileSync(dest, "utf8") === readFileSync(src, "utf8")) {
+                lines.push(`· ${stack}: already installed`);
+                continue;
+            }
+            if (!force) {
+                lines.push(`⚠ ${stack}: exists with local changes — skipped (use --force to overwrite)`);
+                continue;
+            }
+            mkdirSync(rulesDir, { recursive: true });
+            await copyFile(src, dest);
+            lines.push(`✓ ${stack}: overwritten → ${dest}`);
+            continue;
+        }
+        mkdirSync(rulesDir, { recursive: true });
+        await copyFile(src, dest);
+        lines.push(`✓ ${stack}: installed → ${dest}`);
+    }
+    lines.push("");
+    lines.push("kanban-review loads these rules automatically (project → user → package).");
+    return { code: 0, stdout: lines.join("\n") };
+}