@phuthuycoding/kanban-flow 0.3.0

package/dist/dashboard/dashboard.js

@@ -0,0 +1,206 @@
+import { createServer } from "node:http";
+import { STAGES, PHASE_NAMES, STAGE_INDEX } from "../workflow/schema.js";
+import { listFeatures } from "../workflow/features.js";
+import { computeStatus, renderStatusText, approvalState } from "../workflow/status.js";
+import { readProjectConfig } from "../project/config.js";
+import { declaredDefaultContext } from "../project/contexts.js";
+import { findWorksRoot } from "../workflow/features.js";
+import { renderDashboardHtml } from "./dashboard-view.js";
+export { renderDashboardHtml };
+export const DEFAULT_PORT = 8787;
+function percentage(done, total) {
+    return total === 0 ? null : Math.round(100 * done / total);
+}
+export function dashboardData(root, filters = {}) {
+    const config = readProjectConfig(root);
+    const allFeatures = listFeatures(root);
+    const features = allFeatures.filter((feature) => (filters.context === undefined || feature.context === filters.context)
+        && (filters.kind === undefined || (feature.meta?.kind ?? "feature") === filters.kind));
+    const snapshot = {
+        root,
+        context: declaredDefaultContext(config),
+        updatedAt: new Date().toISOString(),
+        stages: STAGES.map((stage) => {
+            const stageFeatures = features
+                .filter((f) => f.stage === stage)
+                .map((f) => {
+                const st = computeStatus(f, config.harness);
+                return {
+                    name: st.feature.name,
+                    kind: st.feature.meta?.kind ?? "feature",
+                    context: st.feature.context,
+                    folder: st.feature.folder,
+                    stage,
+                    stageIndex: STAGE_INDEX[stage],
+                    artifacts: st.artifacts.map((a) => ({
+                        id: a.id,
+                        file: a.file,
+                        status: a.status,
+                        due: a.due,
+                        note: a.note,
+                        shortFile: a.file.replace(/^phase-\d-/, ""),
+                    })),
+                    doneCount: st.doneCount,
+                    dueCount: st.dueCount,
+                    totalCount: st.totalCount,
+                    next: st.next,
+                    taskProgress: st.taskProgress,
+                    approval: approvalState(f),
+                    bypasses: f.meta?.bypasses?.length ?? 0,
+                    runs: f.meta?.runs ?? [],
+                    text: renderStatusText(st),
+                };
+            });
+            return {
+                id: stage,
+                name: PHASE_NAMES[stage],
+                features: stageFeatures,
+            };
+        }),
+    };
+    const items = snapshot.stages.flatMap((stage) => stage.features);
+    const executing = items.filter((item) => ["implementation", "testing", "review"].includes(item.stage));
+    const completed = items.filter((item) => item.stage === "dones").length;
+    const cancelled = items.filter((item) => item.stage === "cancelled").length;
+    const approvals = items.filter((item) => item.stage !== "brainstorm" && item.stage !== "dones");
+    const taskDone = executing.reduce((sum, item) => sum + item.taskProgress.done, 0);
+    const taskTotal = executing.reduce((sum, item) => sum + item.taskProgress.total, 0);
+    const itemsTracked = executing.filter((item) => item.taskProgress.total > 0).length;
+    const contexts = [...new Set(allFeatures.map((feature) => feature.context))]
+        .sort((a, b) => (a ?? "").localeCompare(b ?? ""));
+    return {
+        ...snapshot,
+        filters: { context: filters.context, kind: filters.kind ?? null },
+        availableContexts: contexts.map((context) => ({ id: context, label: context ?? "Unassigned" })),
+        metrics: {
+            total: items.length,
+            features: items.filter((item) => item.kind === "feature").length,
+            bugs: items.filter((item) => item.kind === "bug").length,
+            executing: executing.length,
+            backlog: items.filter((item) => item.stage === "backlog").length,
+            completed,
+            cancelled,
+            // Dropped work must not drag the rate down, or nobody will admit to dropping anything.
+            completionRate: percentage(completed, items.length - cancelled),
+            bypassed: items.filter((item) => item.bypasses > 0).length,
+            runs: runMetrics(items.flatMap((item) => item.runs)),
+            tasks: {
+                done: taskDone,
+                total: taskTotal,
+                completionRate: percentage(taskDone, taskTotal),
+                itemsTracked,
+                itemsUntracked: executing.length - itemsTracked,
+            },
+        },
+        charts: {
+            byStage: snapshot.stages.map((stage) => ({
+                id: stage.id, label: stage.id, count: stage.features.length,
+                features: stage.features.filter((item) => item.kind === "feature").length,
+                bugs: stage.features.filter((item) => item.kind === "bug").length,
+            })),
+            byKind: ["feature", "bug"].map((kind) => ({
+                id: kind, label: kind === "feature" ? "Feature" : "Bug",
+                count: items.filter((item) => item.kind === kind).length,
+            })),
+            byContext: contexts.map((context) => {
+                const contextItems = items.filter((item) => item.context === context);
+                return {
+                    id: context, label: context ?? "Unassigned", count: contextItems.length,
+                    features: contextItems.filter((item) => item.kind === "feature").length,
+                    bugs: contextItems.filter((item) => item.kind === "bug").length,
+                };
+            }).filter((context) => context.count > 0).sort((a, b) => b.count - a.count || a.label.localeCompare(b.label)),
+            approvals: ["pending", "approved", "changed"].map((approval) => ({
+                id: approval,
+                label: { pending: "Awaiting approval", approved: "Approved", changed: "Contract changed" }[approval],
+                count: approvals.filter((item) => item.approval === approval).length,
+            })),
+        },
+    };
+}
+function runMetrics(runs) {
+    const byRole = {};
+    const usage = {};
+    for (const r of runs) {
+        const a = (byRole[r.role] ??= { runs: 0, done: 0, failed: 0 });
+        a.runs += 1;
+        if (r.status === "done")
+            a.done += 1;
+        if (r.status === "failed" || r.status === "timeout" || r.status === "reset")
+            a.failed += 1;
+        if (r.usage) {
+            const u = (usage[r.role] ??= { input: 0, output: 0, costUsd: 0 });
+            u.input += r.usage.input;
+            u.output += r.usage.output;
+            u.costUsd += r.usage.costUsd ?? 0;
+        }
+    }
+    return { byRole, usage };
+}
+function json(res, code, body) {
+    res.writeHead(code, { "content-type": "application/json; charset=utf-8" });
+    res.end(JSON.stringify(body, null, 2));
+}
+/**
+ * Start a local dashboard server. The listening server keeps the event loop
+ * alive, so the CLI prints the URL then stays running until Ctrl+C.
+ */
+export async function cmdDashboard(port = DEFAULT_PORT) {
+    const root = findWorksRoot(process.cwd());
+    if (!root) {
+        return { code: 1, stdout: "No .works found. Run: kf init", stderr: "no works" };
+    }
+    const server = createServer((req, res) => {
+        try {
+            const url = new URL(req.url ?? "/", "http://localhost");
+            if (url.pathname === "/api/data") {
+                const kind = url.searchParams.get("kind");
+                if (kind !== null && kind !== "feature" && kind !== "bug") {
+                    json(res, 400, { error: "kind must be feature or bug" });
+                    return;
+                }
+                const context = url.searchParams.get("context");
+                const filters = {
+                    kind: kind ?? undefined,
+                    context: context === "__none__" ? null : context ?? undefined,
+                };
+                try {
+                    json(res, 200, dashboardData(root, filters));
+                }
+                catch (err) {
+                    process.stderr.write(`Dashboard data failed: ${err instanceof Error ? err.stack : String(err)}\n`);
+                    json(res, 500, { error: "Unable to read dashboard metrics. Check the server output." });
+                }
+                return;
+            }
+            if (url.pathname === "/" || url.pathname === "/favicon.ico") {
+                res.writeHead(200, { "content-type": "text/html; charset=utf-8" });
+                res.end(renderDashboardHtml());
+                return;
+            }
+            res.writeHead(404, { "content-type": "text/plain" });
+            res.end("not found");
+        }
+        catch (err) {
+            process.stderr.write(`Dashboard request failed: ${err instanceof Error ? err.stack : String(err)}\n`);
+            if (!res.headersSent)
+                res.writeHead(500, { "content-type": "text/plain" });
+            res.end("internal error");
+        }
+    });
+    const url = `http://localhost:${port}`;
+    await new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(port, "127.0.0.1", () => resolve());
+    });
+    const shutdown = () => {
+        server.close(() => process.exit(0));
+        server.closeAllConnections();
+    };
+    process.once("SIGINT", shutdown);
+    process.once("SIGTERM", shutdown);
+    return {
+        code: 0,
+        stdout: `kanban-flow dashboard running at ${url}\n\nOpen ${url} in your browser. Press Ctrl+C to stop.`,
+    };
+}

package/dist/harness/chain.js

@@ -0,0 +1,41 @@
+import { randomUUID } from "node:crypto";
+import { findFeature } from "../workflow/features.js";
+import { createRunPlan, executeRun, writeRunPlan } from "./run.js";
+function loadFeature(root, name) {
+    const feature = findFeature(root, name);
+    if (!feature)
+        throw new Error(`Work item '${name}' not found.`);
+    return feature;
+}
+/** Plan for one role, with the id fixed when a supervisor already announced it. */
+export function planFor(root, feature, assignment, opts, previous, position, id) {
+    const plan = createRunPlan(root, feature, assignment, { fresh: opts.fresh, timeoutMs: opts.timeoutMs, previous });
+    return { ...plan, ...(id ? { id } : {}), ...(position ? { chain: position } : {}) };
+}
+/**
+ * Run a stage's roles in order. Each role is its own worker and its own run
+ * record; the next role is told where the previous one wrote. A step that does
+ * not finish DONE stops the chain, so no worker builds on half-finished work
+ * and no tokens are spent on steps that cannot succeed.
+ */
+export async function executeChain(root, featureName, chain, opts) {
+    const outcomes = [];
+    let previous = null;
+    const chainId = opts.firstRunId ?? newChainId();
+    for (const [index, assignment] of chain.entries()) {
+        const feature = loadFeature(root, featureName);
+        const position = { id: chainId, index: index + 1, total: chain.length };
+        const plan = planFor(root, feature, assignment, opts, previous, position, index === 0 ? opts.firstRunId : undefined);
+        writeRunPlan(feature, plan);
+        const outcome = await executeRun(plan, opts.env ?? process.env);
+        outcomes.push(outcome);
+        if (!outcome.ok) {
+            return { outcomes, ok: false, stoppedAt: assignment.role, skipped: chain.slice(index + 1).map((a) => a.role) };
+        }
+        previous = { role: assignment.role, output: assignment.output, log: outcome.record.log };
+    }
+    return { outcomes, ok: true, skipped: [] };
+}
+export function newChainId() {
+    return randomUUID().slice(0, 8);
+}

package/dist/harness/config.js

@@ -0,0 +1,168 @@
+import { STAGES } from "../workflow/schema.js";
+export const HARNESS_STAGES = STAGES.filter((s) => s !== "backlog");
+const isStringArray = (v) => Array.isArray(v) && v.every((x) => typeof x === "string");
+function validateRunner(name, value, fail) {
+    const at = `harness.runners.${name}`;
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        fail(at, "must be an object");
+    const r = value;
+    if (!isStringArray(r.start) || r.start.length === 0)
+        fail(`${at}.start`, "must be a non-empty array of strings");
+    if (!r.start.some((a) => a.includes("{prompt}")))
+        fail(`${at}.start`, "must contain {prompt}");
+    if (r.resume !== undefined) {
+        if (!isStringArray(r.resume) || r.resume.length === 0)
+            fail(`${at}.resume`, "must be a non-empty array of strings");
+        if (!r.resume.some((a) => a.includes("{session}")))
+            fail(`${at}.resume`, "must contain {session}");
+    }
+    const session = r.session;
+    if (session !== undefined && session !== "provided") {
+        if (!session || typeof session !== "object")
+            fail(`${at}.session`, 'must be "provided", { stdout } or { command, idField, matchField }');
+        const s = session;
+        if ("stdout" in s) {
+            if (typeof s.stdout !== "string")
+                fail(`${at}.session.stdout`, "must be a regex string");
+        }
+        else if (!isStringArray(s.command) || typeof s.idField !== "string" || typeof s.matchField !== "string") {
+            fail(`${at}.session`, "command capture needs command[], idField, matchField");
+        }
+    }
+    if (r.start.some((a) => a.includes("{session}")) && session !== "provided") {
+        fail(`${at}.start`, '{session} is only allowed when session is "provided"');
+    }
+    if (r.usage !== undefined && r.usage !== "json")
+        fail(`${at}.usage`, 'must be "json"');
+    if (r.skillsDir !== undefined && typeof r.skillsDir !== "string")
+        fail(`${at}.skillsDir`, "must be a string");
+    if (r.resumeFailure !== undefined && typeof r.resumeFailure !== "string")
+        fail(`${at}.resumeFailure`, "must be a regex string");
+    return r;
+}
+function validateRole(name, value, runners, fail) {
+    const at = `harness.roles.${name}`;
+    const role = typeof value === "string" ? { runner: value } : { ...value };
+    if (!value || (typeof value !== "string" && (typeof value !== "object" || Array.isArray(value)))) {
+        fail(at, "must be a runner name or an object { runner, brief?, output? }");
+    }
+    if (typeof role.runner !== "string" || !role.runner)
+        fail(`${at}.runner`, "must be a runner name");
+    if (!(role.runner in runners))
+        fail(`${at}.runner`, `"${role.runner}" is not declared in harness.runners`);
+    if (role.brief !== undefined && typeof role.brief !== "string")
+        fail(`${at}.brief`, "must be a string");
+    if (role.output !== undefined) {
+        if (typeof role.output !== "string" || !role.output)
+            fail(`${at}.output`, "must be a path relative to the work item folder");
+        const output = role.output;
+        if (output.startsWith("/") || output.split(/[/\\]/).includes(".."))
+            fail(`${at}.output`, "must stay inside the work item folder");
+    }
+    return role;
+}
+function validateChain(stage, value, roles, runners, fail) {
+    const at = `harness.stages.${stage}`;
+    const chain = typeof value === "string" ? [value] : value;
+    if (!isStringArray(chain))
+        fail(at, "must be a role name or an array of role names");
+    if (chain.length === 0)
+        fail(at, "must list at least one role");
+    const seen = new Set();
+    for (const role of chain) {
+        if (!(role in roles)) {
+            // The previous release let stages point straight at a runner; say so instead of "unknown role".
+            if (role in runners)
+                fail(at, `"${role}" is a runner, not a role; declare a role in harness.roles that points at it`);
+            fail(at, `"${role}" is not a role. Known roles: ${Object.keys(roles).join(", ")}`);
+        }
+        if (seen.has(role))
+            fail(at, `lists role "${role}" twice; each role runs once per stage`);
+        seen.add(role);
+    }
+    return chain;
+}
+/** Validate the `harness` block of .kf/config.json; throws with the offending field. */
+export function validateHarness(value, file) {
+    const fail = (field, why) => {
+        throw new Error(`Invalid project config: ${file} — ${field} ${why}`);
+    };
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        fail("harness", "must be an object");
+    const h = value;
+    if (!h.runners || typeof h.runners !== "object" || Array.isArray(h.runners))
+        fail("harness.runners", "must be an object");
+    const runners = {};
+    for (const [name, runner] of Object.entries(h.runners))
+        runners[name] = validateRunner(name, runner, fail);
+    if (!h.roles || typeof h.roles !== "object" || Array.isArray(h.roles))
+        fail("harness.roles", "must be an object mapping role names to runners");
+    const roles = {};
+    for (const [name, role] of Object.entries(h.roles))
+        roles[name] = validateRole(name, role, runners, fail);
+    const main = typeof h.main === "string" ? h.main : "";
+    if (!main)
+        fail("harness.main", "must be a role name");
+    if (!(main in roles)) {
+        if (main in runners)
+            fail("harness.main", `"${main}" is a runner, not a role; declare a role in harness.roles that points at it`);
+        fail("harness.main", `"${main}" is not a role. Known roles: ${Object.keys(roles).join(", ")}`);
+    }
+    const stagesRaw = h.stages ?? {};
+    if (!stagesRaw || typeof stagesRaw !== "object" || Array.isArray(stagesRaw))
+        fail("harness.stages", "must be an object");
+    const stages = {};
+    for (const [stage, chain] of Object.entries(stagesRaw)) {
+        if (!HARNESS_STAGES.includes(stage))
+            fail(`harness.stages.${stage}`, `is not an assignable stage (${HARNESS_STAGES.join(", ")})`);
+        stages[stage] = validateChain(stage, chain, roles, runners, fail);
+    }
+    return { main, roles, stages, runners };
+}
+/**
+ * Runner presets verified against each CLI's --help and a one-prompt smoke run
+ * on 2026-09-19. gemini and opencode could not be verified for resume, so they
+ * start fresh every time until the user adds a `resume` template.
+ */
+export function harnessPresets() {
+    return {
+        claude: {
+            start: ["claude", "-p", "{prompt}", "--session-id", "{session}", "--permission-mode", "acceptEdits", "--output-format", "json"],
+            resume: ["claude", "-p", "{prompt}", "-r", "{session}", "--permission-mode", "acceptEdits", "--output-format", "json"],
+            session: "provided",
+            usage: "json",
+        },
+        codex: {
+            start: ["codex", "exec", "--json", "{prompt}"],
+            resume: ["codex", "exec", "resume", "{session}", "{prompt}"],
+            session: { stdout: "\"thread_id\":\"([^\"]+)\"" },
+            usage: "json",
+        },
+        devin: {
+            start: ["devin", "-p", "{prompt}", "--permission-mode", "accept-edits"],
+            resume: ["devin", "-p", "{prompt}", "-r", "{session}", "--permission-mode", "accept-edits"],
+            session: { command: ["devin", "list", "--format", "json"], idField: "id", matchField: "title" },
+        },
+        gemini: {
+            start: ["gemini", "-p", "{prompt}", "--approval-mode", "auto_edit"],
+        },
+        opencode: {
+            start: ["opencode", "run", "{prompt}"],
+        },
+    };
+}
+/** Default roles: the jobs a kanban pipeline actually has, all pointing at one runner until the user splits them. */
+export const ROLE_BRIEFS = {
+    architect: "Orchestrates the pipeline and keeps the human gates. Decides transitions; does not do a stage's work when that stage has its own role.",
+    researcher: "Explores breadth: prior art, libraries, existing code paths, comparable features. Reports findings and trade-offs; does not design or write the spec.",
+    writer: "Turns agreed decisions into precise prose that follows the template exactly. Adds no scope of its own.",
+    coder: "Implements the approved plan and keeps the build green. Changes nothing outside the approved contract.",
+    tester: "Runs the real test suite against the approved test cases and records evidence with exact commands and exit codes. Never claims a result it did not observe.",
+    reviewer: "Audits the diff against the contract and the review rules, hunting for failures the author would not see. Reproduces plausible failures instead of guessing.",
+};
+export function seedHarness(agents) {
+    const runners = harnessPresets();
+    const runner = agents.find((a) => a in runners) ?? "claude";
+    const roles = Object.fromEntries(Object.entries(ROLE_BRIEFS).map(([name, brief]) => [name, { runner, brief }]));
+    return { main: "architect", roles, stages: {}, runners };
+}

package/dist/harness/prompt.js

@@ -0,0 +1,105 @@
+import { existsSync } from "node:fs";
+import { join, relative } from "node:path";
+import { ARTIFACTS } from "../workflow/schema.js";
+import { skillsDirFor } from "../integrations/agents.js";
+/** Skill a worker loads for each stage; backlog has no work to hand off. */
+export const STAGE_SKILL = {
+    brainstorm: "kanban-brainstorm",
+    planning: "kanban-plan",
+    backlog: null,
+    implementation: "kanban-implement",
+    testing: "kanban-test",
+    review: "kanban-review",
+    dones: "kanban-archive",
+    cancelled: null,
+};
+function assign(role, config, harness, stage, skillName, root) {
+    const runner = harness.runners[config.runner];
+    if (!runner)
+        return `Role "${role}" points at runner "${config.runner}", which is not declared.`;
+    const skillsDir = runner.skillsDir ? join(root, runner.skillsDir) : skillsDirFor(config.runner, root);
+    const skillPath = join(skillsDir, skillName, "SKILL.md");
+    if (!existsSync(skillPath)) {
+        return `Skill ${relative(root, skillPath)} is missing for role "${role}" (runner ${config.runner}) — run: kf install --agent ${config.runner} (or set harness.runners.${config.runner}.skillsDir).`;
+    }
+    return { role, runnerName: config.runner, runner, stage, skill: skillName, skillPath, brief: config.brief, output: config.output };
+}
+/**
+ * Resolve the chain of roles that runs a stage. A stage can name several roles
+ * (research then write, say); they run in order and each is a separate worker.
+ */
+export function resolveChain(harness, feature, root, overrides = {}) {
+    if (!harness)
+        return { ok: false, reason: "No harness configured in .kf/config.json — run: kf init (seeds roles and runner presets)." };
+    const stage = overrides.stage ?? feature.stage;
+    if (feature.stage === "dones" && !overrides.stage)
+        return { ok: false, reason: `'${feature.name}' is archived (dones); nothing to run.` };
+    const skillName = feature.meta?.kind === "bug" && stage === "brainstorm" ? "kanban-bug" : STAGE_SKILL[stage];
+    if (!skillName)
+        return { ok: false, reason: `Stage "${stage}" has no work to hand off.` };
+    const stageChain = harness.stages[stage] ?? [];
+    let roles = stageChain;
+    if (overrides.role) {
+        if (!(overrides.role in harness.roles)) {
+            return { ok: false, reason: `Unknown role "${overrides.role}". Known roles: ${Object.keys(harness.roles).join(", ")}.` };
+        }
+        if (stageChain.length > 0 && !stageChain.includes(overrides.role)) {
+            return { ok: false, reason: `Role "${overrides.role}" is not in the chain for stage "${stage}" (${stageChain.join(" → ")}). Pass --stage to run it elsewhere.` };
+        }
+        roles = [overrides.role];
+    }
+    if (roles.length === 0) {
+        return { ok: false, reason: `Stage "${stage}" has no role assigned in harness.stages — the main role (${harness.main}) does it. Use --role <name> to hand it off anyway.` };
+    }
+    const chain = [];
+    for (const role of roles) {
+        const config = harness.roles[role];
+        if (!config)
+            return { ok: false, reason: `Unknown role "${role}". Known roles: ${Object.keys(harness.roles).join(", ")}.` };
+        const result = assign(role, config, harness, stage, skillName, root);
+        if (typeof result === "string")
+            return { ok: false, reason: result };
+        chain.push(result);
+    }
+    return { ok: true, chain };
+}
+/** Marker placed first in every worker prompt so sessions can be traced back to a run. */
+export function runMarker(runId) {
+    return `kf-run:${runId}`;
+}
+/** Find the current testing/review report when it is a loop-back result. */
+export function currentFailReport(feature) {
+    for (const id of ["review-report", "testing-result"]) {
+        const p = join(feature.dir, ARTIFACTS[id].file);
+        if (existsSync(p))
+            return p;
+    }
+    return null;
+}
+export function buildWorkerPrompt(input) {
+    const { feature, root, assignment, runId } = input;
+    const kind = feature.meta?.kind === "bug" ? "bug" : "feature";
+    const dir = relative(root, feature.dir);
+    const lines = [
+        runMarker(runId),
+        `You are the "${assignment.role}" worker for the kanban-flow ${kind} "${feature.name}" (context ${feature.context ?? "n/a"}) at stage "${assignment.stage}".`,
+    ];
+    if (assignment.brief)
+        lines.push(`Your role: ${assignment.brief}`);
+    lines.push(`Project root: ${root}`, `Work item folder: ${dir}`, `Load and follow the skill: ${relative(root, assignment.skillPath)} (${assignment.skill}). Skip its "move to stage" step — the stage is already set.`, "Read the artifacts in the work item folder before acting; run `kf status --change " + feature.name + "` for the checklist and `kf instruct <artifact> --change " + feature.name + "` for the exact template and output path of anything you must write.");
+    if (input.previous) {
+        const parts = [`The "${input.previous.role}" role ran before you in this stage.`];
+        if (input.previous.output)
+            parts.push(`Read its output first: ${join(dir, input.previous.output)}.`);
+        parts.push(`Its full log is at ${join(dir, input.previous.log)} if you need the details.`);
+        lines.push(`Previous step: ${parts.join(" ")}`);
+    }
+    if (assignment.output) {
+        lines.push(`Write your findings to ${join(dir, assignment.output)} so the next role can read them; this is in addition to the stage's own artifacts.`);
+    }
+    if (input.failReport) {
+        lines.push(`This is a repair loop: read ${relative(root, input.failReport)} first and fix exactly what it reports.`);
+    }
+    lines.push("Contract:", "- Do only this stage's work and write its artifacts into the work item folder.", "- Never run `kf stage`, `kf approve`, `kf archive`, or `kf run`; the main agent decides transitions.", "- Never edit approved contract artifacts (requirement, plan, use cases, test cases); track progress in tasks.md.", "- Do not commit or push.", "- Finish with two final lines exactly in this form:", "STATUS: DONE | DONE_WITH_CONCERNS | BLOCKED | NEEDS_CONTEXT", "Summary: <one or two sentences>");
+    return lines.join("\n");
+}