@rsaglobaltech/specgate 0.21.0 → 0.22.0

package/dist/scripts/cli/commands/change/TicketCommand.js

@@ -0,0 +1,657 @@
+"use strict";
+/**
+ * `specgate propose --from-ticket <KEY | issue.json>` — a Jira ticket as the
+ * source text of a change (ADR-0039).
+ *
+ * Reading the ticket is the ALM provider's job and stays read-only; writing
+ * the change is this command's, as `alm pull` writes its own outside
+ * `scripts/alm/` (ADR-0021 §1).
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TicketCommand = void 0;
+exports.parseTicketArgs = parseTicketArgs;
+exports.changeIdFor = changeIdFor;
+const node_child_process_1 = require("node:child_process");
+const crypto = __importStar(require("node:crypto"));
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const command_1 = require("../../../lib/command");
+const ui = __importStar(require("../../../lib/ui"));
+const agent_1 = require("../../../lib/agent");
+const diagnostics_1 = require("../../../lib/diagnostics");
+const project_root_1 = require("../../../lib/project-root");
+const core_1 = require("../../../alm/core");
+const clients_1 = require("../../../alm/clients");
+const TicketText_1 = require("../../../../packages/core/src/domain/TicketText");
+const DraftChecklist_1 = require("../../../../packages/core/src/domain/DraftChecklist");
+const ChangeTemplates_1 = require("../../../../packages/core/src/domain/ChangeTemplates");
+const DiskLanguageRepository_1 = require("../../../../packages/core/src/infrastructure/DiskLanguageRepository");
+const ChangeWorkspace_1 = require("../../../../packages/core/src/infrastructure/ChangeWorkspace");
+const DraftCommand_1 = require("../spec/DraftCommand");
+const ticket_guide_1 = require("../../../draft/ticket-guide");
+const confined_agent_1 = require("../../../draft/confined-agent");
+const ticket_keys_1 = require("../../../lib/ticket-keys");
+const CHANGES = "docs/specs/changes";
+/** The placeholder `templateDelta` writes: a delta nobody has written yet. */
+const PLACEHOLDER = "feature=features/<area>/<name>.feature";
+const NULL_SHAPE = { ticket: null };
+const JIRA_KEY = /^[A-Z][A-Z0-9_]+-\d+$/;
+function usage() {
+    process.stdout.write([
+        "",
+        "  specgate propose --from-ticket <KEY | issue.json> [options]",
+        "",
+        "  A Jira ticket as the source text of a change (docs/from-a-ticket.md).",
+        "",
+        "  --check               Its Definition of Ready (T1–T9); writes nothing",
+        "  --capability <name>   The capability, when its epic is not under epics:",
+        "  --agent <cmd>         Have your agent draft it, confined to the change",
+        "  --no-branch           Do not create feature/<KEY>-<slug>",
+        "  --no-push             Create it, but do not push it to origin",
+        "  --project-dir <path>  --json",
+        "",
+    ].join("\n") + "\n");
+}
+function parseTicketArgs(argv) {
+    const opts = {
+        ticket: "",
+        check: false,
+        json: false,
+        projectDir: ".",
+        capability: "",
+        branch: true,
+        push: true,
+        agent: "",
+    };
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === "--from-ticket")
+            opts.ticket = argv[++i] ?? "";
+        else if (a === "--check")
+            opts.check = true;
+        else if (a === "--json")
+            opts.json = true;
+        else if (a === "--project-dir")
+            opts.projectDir = argv[++i] ?? ".";
+        else if (a === "--capability")
+            opts.capability = argv[++i] ?? "";
+        else if (a === "--no-branch")
+            opts.branch = false;
+        else if (a === "--no-push")
+            opts.push = false;
+        else if (a === "--agent")
+            opts.agent = argv[++i] ?? "";
+    }
+    return opts;
+}
+/** `alm.config.yaml`, when there is one: a file needs none, a key does. */
+function almConfig(projectDir) {
+    return fs.existsSync(path.join(projectDir, "alm.config.yaml"))
+        ? (0, core_1.readAlmConfig)(projectDir)
+        : undefined;
+}
+const looksLikeFile = (ref) => /\.json$/i.test(ref) || fs.existsSync(ref);
+/** The ticket: an exported issue on disk, or the issue read from the board. */
+async function loadTicket(ref, cfg, projectDir) {
+    const opts = {
+        acceptanceField: cfg?.acceptance_field ? String(cfg.acceptance_field) : undefined,
+        baseUrl: cfg?.base_url,
+    };
+    if (looksLikeFile(ref)) {
+        const file = path.resolve(ref);
+        return (0, TicketText_1.readTicket)(JSON.parse(fs.readFileSync(file, "utf8")), opts);
+    }
+    if (!cfg) {
+        throw new Error(`alm.config.yaml not found in ${projectDir}: reading ${ref} from the board needs it.\n` +
+            "Fix: add it (`specgate alm --help`), or export the issue as JSON and pass the file.");
+    }
+    const client = (0, clients_1.makeClient)(cfg, undefined, projectDir);
+    if (typeof client.readIssue !== "function") {
+        throw new Error(`Provider '${cfg.provider}' cannot read one issue.\n` +
+            "Fix: export the issue as JSON and pass the file to --from-ticket.");
+    }
+    return (0, TicketText_1.readTicket)(await client.readIssue(ref), opts);
+}
+function git(dir, args) {
+    return (0, node_child_process_1.spawnSync)("git", ["-C", dir, ...args], { encoding: "utf8" });
+}
+const isBug = (t) => /^(bug|defect|fehler|incidencia|error)$/i.test(t.type.trim());
+/**
+ * `feature/KAN-13-register-vehicle-entry`, or `bugfix/…` for a bug: the key is
+ * what makes the Git host show the branch in the ticket. Only from a clean
+ * tree — carrying someone's uncommitted work onto a ticket's branch would mix
+ * it into that ticket.
+ */
+function ticketBranch(dir, t) {
+    if (git(dir, ["rev-parse", "--is-inside-work-tree"]).status !== 0) {
+        return { name: null, note: null };
+    }
+    const name = `${isBug(t) ? "bugfix" : "feature"}/${t.key}${changeIdFor(t).slice(t.key.length)}`;
+    if (git(dir, ["status", "--porcelain"]).stdout.trim()) {
+        return {
+            name: null,
+            note: `Branch not created: there are uncommitted changes. Commit them, then: git checkout -b ${name}`,
+        };
+    }
+    // From the base, not from wherever HEAD is: another ticket's branch would
+    // bring its commits into this ticket's pull request.
+    let base;
+    try {
+        base = (0, ticket_keys_1.baseFor)(dir);
+    }
+    catch {
+        return {
+            name: null,
+            note: `Branch ${name} not created: the base branch is not a safe git ref (check --base or SPECGATE_BASE).`,
+        };
+    }
+    const made = git(dir, ["checkout", "-q", "-b", name, ...(base ? [base] : [])]);
+    if (made.status !== 0) {
+        return { name: null, note: `Branch ${name} not created: ${made.stderr.trim()}` };
+    }
+    return { name, note: null };
+}
+/**
+ * The branch on `origin` as soon as work starts: a Git host linked to Jira
+ * shows it in the ticket, and a Jira automation ("branch created → In
+ * Progress") moves the ticket — Specgate itself never writes to Jira. A failed
+ * push is said and leaves the change as it is.
+ */
+function pushBranch(dir, name) {
+    if (git(dir, ["remote", "get-url", "origin"]).status !== 0)
+        return null;
+    const pushed = git(dir, ["push", "-q", "-u", "origin", name]);
+    if (pushed.status === 0)
+        return { ok: true, note: `Branch ${name} pushed to origin` };
+    const why = pushed.stderr.trim().split("\n")[0] ?? "";
+    return {
+        ok: false,
+        note: `Branch not pushed (${why}). Push it yourself: git push -u origin ${name}`,
+    };
+}
+function readIf(file) {
+    return fs.existsSync(file) ? fs.readFileSync(file, "utf8") : undefined;
+}
+/** `kan-13-register-vehicle-entry`: the key, then the summary's first words. */
+function changeIdFor(t) {
+    const slug = t.summary
+        .normalize("NFKD")
+        .replace(/[\u0300-\u036f]/g, "")
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, " ")
+        .trim()
+        .split(/\s+/)
+        .filter(Boolean)
+        .slice(0, 6)
+        .join("-");
+    return [t.key.toLowerCase(), slug].filter(Boolean).join("-");
+}
+/** The capability the ticket's epic maps to, under `epics:` in `alm.config.yaml`. */
+function capabilityOf(t, cfg) {
+    const epics = cfg?.epics;
+    if (!t.parent || !epics || typeof epics !== "object")
+        return "";
+    const mapped = epics[t.parent];
+    return typeof mapped === "string" ? mapped.trim() : "";
+}
+const sha256 = (text) => crypto.createHash("sha256").update(text, "utf8").digest("hex");
+/** `ticket.md`: what was read, unedited, and when. */
+function ticketCopy(t) {
+    const meta = [
+        `key=${t.key}`,
+        `type=${t.type.replace(/\s+/g, "_") || "issue"}`,
+        ...(t.parent ? [`parent=${t.parent}`] : []),
+        ...(t.url ? [`url=${t.url}`] : []),
+        `read=${new Date().toISOString()}`,
+    ].join(" ");
+    return [
+        `# ${t.key} — ${t.summary}`,
+        "",
+        `<!-- specgate:ticket ${meta} -->`,
+        "",
+        ...(t.labels.length ? [`Labels: ${t.labels.join(", ")}`, ""] : []),
+        t.description,
+        "",
+        ...(t.criteria.length && !/acceptance|akzeptanz|aceptaci/i.test(t.description)
+            ? ["Acceptance Criteria", "", ...t.criteria.map((c) => `- ${c}`), ""]
+            : []),
+    ].join("\n");
+}
+function proposalFor(t, changeId, capability) {
+    return [
+        `# Proposal: ${changeId}`,
+        "",
+        `ticket: ${t.key}`,
+        ...(t.url ? [`link: ${t.url}`] : []),
+        ...(t.source ? [`source: ${t.source}`] : []),
+        "",
+        "## Intent",
+        "",
+        ...(t.intent ? t.intent.split("\n").map((l) => `> ${l}`) : [`> ${t.summary}`]),
+        "",
+        "## Scope",
+        "",
+        `In scope: the acceptance criteria of ${t.key}, in the \`${capability}\` capability.`,
+        "",
+        `Out of scope: anything ${t.key} does not state.`,
+        "",
+    ].join("\n");
+}
+function questionsFor(t) {
+    if (t.questions.length === 0)
+        return undefined;
+    const cell = (s) => s.replace(/\|/g, "\\|").replace(/\s+/g, " ").trim();
+    return [
+        "# Questions",
+        "",
+        `From ${t.key}'s open questions. The answer is the analyst's assumption until`,
+        "someone confirms it.",
+        "",
+        "| # | Question | Blocks | Answer |",
+        "|---|---|---|---|",
+        ...t.questions.map((q, i) => `| Q${i + 1} | ${cell(q.text)} |  | ${q.assumption ? `Assumption: ${cell(q.assumption)}` : ""} |`),
+        "",
+    ].join("\n");
+}
+/** Write the change: the copy, the proposal, the questions, the guide and the delta. */
+function openChange(projectDir, t, changeId, capability) {
+    const final = path.join(projectDir, CHANGES, changeId);
+    // Written aside and moved in one rename: a change folder is either whole
+    // or absent, so an interrupted run never leaves one that looks opened.
+    const dir = path.join(projectDir, CHANGES, `.${changeId}.opening`);
+    fs.rmSync(dir, { recursive: true, force: true });
+    try {
+        const reqRange = (0, ChangeWorkspace_1.reserveReqRange)(projectDir, Math.min(10, Math.max(3, t.criteria.length)));
+        const scnRange = (0, DraftCommand_1.reserveScenarioRange)(projectDir, reqRange);
+        const copyPath = `${CHANGES}/${changeId}/ticket.md`;
+        const copy = ticketCopy(t);
+        const created = [];
+        const write = (rel, contents) => {
+            const full = path.join(dir, rel);
+            fs.mkdirSync(path.dirname(full), { recursive: true });
+            fs.writeFileSync(full, contents, "utf8");
+            created.push(`${CHANGES}/${changeId}/${rel}`);
+        };
+        const values = [...new Set(t.criteria.flatMap((c) => (0, DraftChecklist_1.statedValues)(c)))];
+        write("ticket.md", copy);
+        write("proposal.md", proposalFor(t, changeId, capability));
+        const questions = questionsFor(t);
+        if (questions)
+            write("questions.md", questions);
+        write("DRAFTING.md", (0, ticket_guide_1.ticketGuide)({
+            ticket: t,
+            capability,
+            changeId,
+            copy: copyPath,
+            reqRange,
+            firstScenario: scnRange[0],
+            lastScenario: scnRange[1],
+            values,
+        }));
+        write(path.join("specs", capability, "spec.md"), (0, ChangeTemplates_1.templateDelta)(capability, reqRange[0], (0, DiskLanguageRepository_1.phrases)(projectDir)));
+        const config = {
+            ...ChangeWorkspace_1.DEFAULT_CONFIG,
+            created: new Date().toISOString().slice(0, 10),
+            req_range: reqRange,
+        };
+        write("change.yaml", `${(0, ChangeWorkspace_1.renderConfig)(config).trimEnd()}\nscn_range: [${scnRange[0]}, ${scnRange[1]}]\nbrief: ${copyPath}\nticket: ${t.key}\nticket_sha256: ${sha256(copy)}\n`);
+        fs.renameSync(dir, final);
+        return { reqRange, created };
+    }
+    catch (e) {
+        fs.rmSync(dir, { recursive: true, force: true });
+        throw e;
+    }
+}
+/** The copy without the line that records when it was read. */
+const comparable = (copy) => copy
+    .split("\n")
+    .filter((l) => !l.startsWith("<!-- specgate:ticket "))
+    .map((l) => l.trimEnd());
+/**
+ * `ticket_changed`: the ticket on the board is not the one the change was
+ * drafted from. The copy stays the record of what was agreed; the person
+ * decides whether the change follows.
+ */
+function changedSince(projectDirOption, t) {
+    let projectDir;
+    try {
+        projectDir = (0, project_root_1.resolveProjectDir)(projectDirOption);
+    }
+    catch {
+        return [];
+    }
+    const copy = readIf(path.join(projectDir, CHANGES, changeIdFor(t), "ticket.md"));
+    if (copy === undefined)
+        return [];
+    const before = comparable(copy);
+    const now = comparable(ticketCopy(t));
+    const gone = before.filter((l) => l.trim() && !now.includes(l));
+    const added = now.filter((l) => l.trim() && !before.includes(l));
+    if (gone.length === 0 && added.length === 0)
+        return [];
+    return [
+        (0, diagnostics_1.warning)("ticket_changed", `${t.key} changed since ${changeIdFor(t)} was opened:\n` +
+            [...gone.map((l) => `       - ${l}`), ...added.map((l) => `       + ${l}`)].join("\n"), {
+            target: t.key,
+            fix: "Decide with the analyst whether the change follows; if it does, update the delta and ticket.md together, in one commit naming the ticket.",
+        }),
+    ];
+}
+/** `ticket_copy_edited` when `ticket.md` no longer matches the hash taken when it was read. */
+function copyIntegrity(dir) {
+    const yaml = readIf(path.join(dir, "change.yaml")) ?? "";
+    const recorded = /^ticket_sha256:\s*([0-9a-f]{64})\s*$/m.exec(yaml)?.[1];
+    const copy = readIf(path.join(dir, "ticket.md"));
+    if (!recorded)
+        return [];
+    if (copy !== undefined && sha256(copy) === recorded)
+        return [];
+    return [
+        (0, diagnostics_1.error)("ticket_copy_edited", "ticket.md is not the ticket as it was read: the draft cannot be checked against it.", {
+            file: "ticket.md",
+            fix: "Restore it (git checkout -- ticket.md). If the ticket changed in Jira, run --check to see the difference.",
+        }),
+    ];
+}
+function listDeltas(dir) {
+    const specs = path.join(dir, "specs");
+    if (!fs.existsSync(specs))
+        return [];
+    return fs
+        .readdirSync(specs)
+        .map((cap) => path.join(specs, cap, "spec.md"))
+        .filter((f) => fs.existsSync(f))
+        .map((f) => fs.readFileSync(f, "utf8"));
+}
+function ticketJson(t) {
+    return {
+        key: t.key,
+        summary: t.summary,
+        type: t.type,
+        parent: t.parent,
+        labels: t.labels,
+        url: t.url,
+        intent: t.intent,
+        source: t.source,
+        criteria: t.criteria,
+        questions: t.questions,
+    };
+}
+class TicketCommand extends command_1.BaseCommand {
+    async execute() {
+        if (this.args.includes("--help") || this.args.includes("-h"))
+            return usage();
+        const opts = parseTicketArgs(this.args);
+        const io = (0, agent_1.agentIo)(opts.json);
+        if (!opts.ticket) {
+            io.usage(NULL_SHAPE, [
+                (0, diagnostics_1.error)("ticket_missing", "--from-ticket needs a ticket key or an exported issue.", {
+                    fix: "specgate propose --from-ticket KAN-13 --check, or --from-ticket KAN-13.json",
+                }),
+            ]);
+        }
+        let projectDir;
+        let ticket;
+        try {
+            projectDir = (0, project_root_1.resolveProjectDir)(opts.projectDir);
+            ticket = await loadTicket(opts.ticket, almConfig(projectDir), projectDir);
+        }
+        catch (e) {
+            return io.fail(NULL_SHAPE, [(0, diagnostics_1.error)("ticket_unreadable", e.message)]);
+        }
+        // The key names the change, the branch and its folder: one that is not a
+        // Jira key — an exported file can say anything — would put them anywhere.
+        if (!JIRA_KEY.test(ticket.key)) {
+            return io.fail(NULL_SHAPE, [
+                (0, diagnostics_1.error)("ticket_bad_key", `${JSON.stringify(ticket.key)} is not a Jira issue key.`, {
+                    fix: 'An issue key is a project key and a number: "KAN-13". Export the issue from Jira again.',
+                }),
+            ]);
+        }
+        if (opts.check)
+            return this.check(opts, ticket);
+        return this.open(opts, projectDir, ticket);
+    }
+    /** Open the ticket's change, or report on the one already open. */
+    open(opts, projectDir, ticket) {
+        const io = (0, agent_1.agentIo)(opts.json);
+        const changeId = changeIdFor(ticket);
+        const dir = path.join(projectDir, CHANGES, changeId);
+        if (fs.existsSync(dir)) {
+            if (opts.agent)
+                return this.withAgent(opts, projectDir, ticket, changeId);
+            return this.report(opts, projectDir, ticket, changeId);
+        }
+        const findings = (0, TicketText_1.checkTicket)(ticket);
+        if (!(0, TicketText_1.ticketReady)(findings)) {
+            io.fail(NULL_SHAPE, [
+                (0, diagnostics_1.error)("ticket_not_ready", `${ticket.key} is not ready to draft.`, {
+                    fix: `Fix what \`specgate propose --from-ticket ${opts.ticket} --check\` reports, in Jira.`,
+                }),
+                ...findings.filter((d) => d.severity === "error"),
+            ]);
+        }
+        if (!fs.existsSync(path.join(projectDir, "spec.md"))) {
+            io.fail(NULL_SHAPE, [
+                (0, diagnostics_1.error)("ticket_no_project", "This folder is not a Specgate project yet.", {
+                    fix: "Run `specgate init` (or `specgate adopt`) first.",
+                }),
+            ]);
+        }
+        const capability = opts.capability || capabilityOf(ticket, almConfig(projectDir));
+        if (!capability) {
+            io.fail(NULL_SHAPE, [
+                (0, diagnostics_1.error)("ticket_no_capability", `No capability for ${ticket.key}: ${ticket.parent ? `its epic ${ticket.parent} is not mapped` : "it has no epic"}.`, {
+                    fix: `Pass --capability <name>, or map the epic in alm.config.yaml:\n` +
+                        `epics:\n  ${ticket.parent ?? "KAN-5"}: <capability>`,
+                }),
+            ]);
+        }
+        const branch = opts.branch ? ticketBranch(projectDir, ticket) : { name: null, note: null };
+        const opened = openChange(projectDir, ticket, changeId, capability);
+        const pushed = branch.name && opts.push ? pushBranch(projectDir, branch.name) : null;
+        if (opts.agent)
+            return this.withAgent(opts, projectDir, ticket, changeId, opened.created);
+        io.emit({
+            ticket: ticketJson(ticket),
+            change: changeId,
+            capability,
+            reserved: opened.reqRange,
+            created: opened.created,
+            branch: branch.name,
+            pushed: pushed?.ok ?? false,
+            next: `specgate propose --from-ticket ${opts.ticket}`,
+            status: findings,
+        }, () => {
+            const out = process.stdout;
+            out.write(ui.header("propose --from-ticket", ticket.key));
+            out.write(ui.ok(`Change ${ui.bold(changeId)} opened for ${ticket.key} ` +
+                ui.muted(`· ${capability} · REQ ids ${opened.reqRange[0]}…${opened.reqRange[1]} reserved`)) + "\n");
+            for (const f of opened.created)
+                out.write(ui.fileLine("added", f, ""));
+            if (branch.name)
+                out.write("\n" + ui.ok(`On branch ${ui.bold(branch.name)}`));
+            if (branch.note)
+                out.write("\n" + ui.info(branch.note));
+            if (pushed)
+                out.write(pushed.ok ? ui.ok(pushed.note) : ui.warn(pushed.note));
+            out.write("\n" +
+                ui.section("Have your agent write it") +
+                "  Paste this into Claude Code, Cursor, Codex…\n\n");
+            out.write(ui.quote(`Draft ${ticket.key}: follow ${CHANGES}/${changeId}/DRAFTING.md`));
+            out.write(ui.next(`specgate propose --from-ticket ${opts.ticket} --agent "claude -p"`, `or let Specgate call it — then run specgate propose --from-ticket ${opts.ticket} until it says Ready to review`));
+        });
+    }
+    /** Hand the guide to the agent; it may write the change, never the ticket's copy. */
+    withAgent(opts, projectDir, ticket, changeId, created = []) {
+        const io = (0, agent_1.agentIo)(opts.json);
+        const guide = readIf(path.join(projectDir, CHANGES, changeId, "DRAFTING.md")) ?? "";
+        const agent = (0, confined_agent_1.withWritePermission)(opts.agent);
+        const copy = `${CHANGES}/${changeId}/ticket.md`;
+        if (!opts.json) {
+            process.stdout.write(ui.header("propose --from-ticket", ticket.key) +
+                (created.length ? ui.ok(`Change ${changeId} opened.`) : "") +
+                ui.logLine(`${agent.command} is drafting ${ticket.key}`));
+        }
+        const run = (0, confined_agent_1.runConfinedAgent)({
+            projectDir,
+            changeId,
+            allowed: (rel) => rel.startsWith(`${CHANGES}/${changeId}/`) && rel !== copy,
+            command: agent.command,
+            // A second run fixes what the checklist found, as on the brief path:
+            // without the findings, the agent read a finished draft and changed nothing.
+            prompt: (0, ticket_guide_1.ticketPrompt)(ticket, changeId, guide) + (0, DraftCommand_1.openFindings)(projectDir, changeId, copy),
+            showOutput: !opts.json,
+        });
+        if (run.problem === "no_git") {
+            io.fail(NULL_SHAPE, [
+                (0, diagnostics_1.error)("draft_agent_needs_git", "--agent needs a git repository.", {
+                    fix: "Run `git init`, or paste the prompt into your agent yourself.",
+                }),
+            ]);
+        }
+        if (run.reverted.length > 0 && !opts.json) {
+            process.stdout.write("\n" + ui.warn(`Undone — the agent wrote outside the draft: ${run.reverted.join(", ")}`));
+        }
+        if (!run.ok) {
+            io.fail(NULL_SHAPE, [
+                (0, diagnostics_1.error)("draft_agent_failed", `The agent ${run.detail}.`, {
+                    fix: `Check the command runs on its own, or paste this into your agent: Draft ${ticket.key}: follow ${CHANGES}/${changeId}/DRAFTING.md`,
+                }),
+            ]);
+        }
+        if (!opts.json)
+            process.stdout.write(ui.rule());
+        this.report(opts, projectDir, ticket, changeId, true);
+    }
+    /** The checklist on the ticket's change, the copy's integrity first. */
+    report(opts, projectDir, ticket, changeId, afterAgent = false) {
+        const io = (0, agent_1.agentIo)(opts.json);
+        const dir = path.join(projectDir, CHANGES, changeId);
+        const integrity = copyIntegrity(dir);
+        const deltas = listDeltas(dir);
+        const notWritten = deltas.length > 0 && deltas.every((d) => d.includes(PLACEHOLDER));
+        const result = notWritten ? undefined : (0, DraftCommand_1.draftReport)(projectDir, changeId);
+        if (result && "failure" in result) {
+            io.fail(NULL_SHAPE, [result.failure]);
+            return;
+        }
+        const report = result?.report;
+        const status = [...integrity, ...(report?.status ?? [])];
+        const errors = status.filter((d) => d.severity === "error").length;
+        const ready = !notWritten && errors === 0;
+        const next = ready ? "specgate apply" : `specgate propose --from-ticket ${opts.ticket}`;
+        io.emit({
+            ticket: ticketJson(ticket),
+            change: changeId,
+            state: notWritten ? "not written" : ready ? "ready" : "drafting",
+            requirements: report?.requirements ?? 0,
+            scenarios: report?.scenarios ?? 0,
+            next,
+            status,
+        }, () => {
+            const out = process.stdout;
+            out.write(afterAgent ? "\n" : ui.header("propose --from-ticket", ticket.key));
+            if (report) {
+                out.write(`  ${ui.bold(String(report.requirements))} requirement(s) · ${ui.bold(String(report.scenarios))} scenario(s)\n\n`);
+            }
+            writeFindings(status);
+            if (notWritten) {
+                out.write((status.length ? "\n" : "") +
+                    "  The draft is still the placeholder. Have your agent write it:\n\n" +
+                    ui.quote(`Draft ${ticket.key}: follow ${CHANGES}/${changeId}/DRAFTING.md`) +
+                    ui.next(`specgate propose --from-ticket ${opts.ticket} --agent "claude -p"`, "or let Specgate call it"));
+                return;
+            }
+            out.write("\n" +
+                (ready
+                    ? ui.ok(ui.bold("Ready to review"))
+                    : ui.fail(`${ui.bold(`${errors} finding(s) to fix`)} ${ui.muted("— each says how; DRAFTING.md has the formats")}`)));
+            out.write(ui.next(next, ready
+                ? `once a person has reviewed ${CHANGES}/${changeId}/ — its requirements, one at a time`
+                : "again, until it says Ready to review"));
+        });
+        process.exitCode = ready ? 0 : 1;
+    }
+    /** `--check`: the ticket's parts, and what keeps it from being drafted. */
+    check(opts, ticket) {
+        const io = (0, agent_1.agentIo)(opts.json);
+        const findings = [...(0, TicketText_1.checkTicket)(ticket), ...changedSince(opts.projectDir, ticket)];
+        const errors = findings.filter((d) => d.severity === "error").length;
+        const warnings = findings.filter((d) => d.severity === "warning").length;
+        const ready = (0, TicketText_1.ticketReady)(findings);
+        const epic = findings.some((d) => d.code === "ticket_epic");
+        const next = ready
+            ? `specgate propose --from-ticket ${opts.ticket}`
+            : epic
+                ? "specgate propose --from-ticket <story key> --check"
+                : `specgate propose --from-ticket ${opts.ticket} --check`;
+        io.emit({ ticket: ticketJson(ticket), ready, errors, warnings, next, status: findings }, () => {
+            const out = process.stdout;
+            out.write(ui.header("propose --from-ticket --check", ticket.key));
+            out.write(ui.ok(`${ui.bold(ticket.key)} ${ticket.summary} ` +
+                ui.muted(`· ${ticket.type || "issue"} · ${ticket.criteria.length} criteria · ` +
+                    `${ticket.questions.length} open question(s)`)) + (findings.length ? "\n" : ""));
+            writeFindings(findings);
+            out.write("\n" +
+                (ready
+                    ? ui.ok(ui.bold("Ready to draft") +
+                        (warnings ? ui.muted(` — ${warnings} warning(s) for you to judge`) : ""))
+                    : ui.fail(epic
+                        ? ui.bold("An epic is not drafted — its stories are")
+                        : `${ui.bold(`${errors} error(s) to fix in Jira before drafting`)} ${ui.muted("— each says how")}`)));
+            out.write(ui.next(next, ready ? "open the change" : epic ? "one of its stories" : "once the ticket is fixed"));
+        });
+        process.exitCode = ready ? 0 : 1;
+    }
+}
+exports.TicketCommand = TicketCommand;
+function writeFindings(findings) {
+    const out = process.stdout;
+    for (const d of findings) {
+        const where = d.target ? `${ui.bold(d.target)}  ` : "";
+        const line = `${ui.muted(d.code)}  ${where}${d.message}`;
+        out.write(d.severity === "error"
+            ? ui.fail(line)
+            : d.severity === "warning"
+                ? ui.warn(line)
+                : ui.info(line));
+        if (d.fix)
+            out.write(ui.fix(d.fix));
+    }
+}
+//# sourceMappingURL=TicketCommand.js.map