ikanban 0.4.9 → 0.5.1

package/lib/plancheck.js

@@ -0,0 +1,231 @@
+// ikanban plan check FILE [--done]: one shared definition of "a plan that passes" (plan 7 P1).
+// The plan gate (before code), the deploy and merge gate (--done) and the runner's plan stage
+// all call it. The plan file is repository input: it is parsed as JSON and never run.
+const fs = require("node:fs");
+// Only the status words at load: the plan gate runs check() from a plain checkout. The
+// network parts (roadmap.js, ikanban-safe.js) load when --done --task needs them.
+const { TASK_STATUS, PHASE_STATUS } = require("./statuswords.js");
+
+// The Roadmap sync's own words, plus the two it reads as "waiting".
+const PHASE_WORDS = new Set([...Object.keys(PHASE_STATUS), "pending", "waiting"]);
+const SHORT_KINDS = new Set(["bug", "chore"]);
+const GUIDE = "wiki/06-Templates/0-Shared/3-Feature-Plan/feature-plan-guide.md (in the kit: .iKanban/prompts/feature-plan.md)";
+
+// An expect names something a reader can compare: a number or status code, a quoted
+// string, a file or a URL. "is correct" names nothing.
+const EXACT = /\d|["'`“”‘’]|https?:\/\/|\/|\.[a-z]{1,5}\b/i;
+// Evidence is what was seen: output with a number, a status code, a link or a file.
+const SEEN = /\d|https?:\/\/|\/|\.[a-z]{1,5}\b/i;
+const EMPTY_WORDS = /^(ok|okay|done|pass(ed)?|works|working|yes|verified|checked|fine)\.?$/i;
+
+const text = (v) => (typeof v === "string" ? v.trim() : "");
+
+/** Every problem in `plan`, each with where it is, what is wrong and the fix. */
+function check(plan, { done = false, merge = null } = {}) {
+  const errors = [];
+  const add = (where, problem, fix) => errors.push({ where, problem, fix });
+  if (!plan || typeof plan !== "object" || Array.isArray(plan)) {
+    add("plan", "not a JSON object", `start from the template in ${GUIDE}`);
+    return { errors, summary: null };
+  }
+  const short = SHORT_KINDS.has(text(plan.kind).toLowerCase());
+  const phases = Array.isArray(plan.phases) ? plan.phases : [];
+  if (!short && plan.schema_version !== 2) {
+    add("schema_version", `is ${JSON.stringify(plan.schema_version ?? null)}, not 2`,
+      `set "schema_version": 2 and use the template's sections, or "kind": "bug" or "chore" for a short plan`);
+  }
+  if (phases.length === 0) add("phases", "none", "add at least one phase with tasks and criteria");
+  if (short && phases.length !== 1) {
+    add("phases", `a short plan (kind ${plan.kind}) has one phase, this one has ${phases.length}`,
+      "keep one phase for a bug or chore, or write a full plan (schema_version 2)");
+  }
+
+  const criteria = new Map();
+  for (const ph of phases) {
+    const id = text(ph && ph.id) || "(phase with no id)";
+    const word = text(ph && ph.status).toLowerCase();
+    if (word && !PHASE_WORDS.has(word)) {
+      add(id, `status "${ph.status}" is not a status the Roadmap knows`, `use one of ${[...PHASE_WORDS].join(", ")}`);
+    }
+    for (const t of Array.isArray(ph && ph.tasks) ? ph.tasks : []) {
+      const tw = text(t && t.status || "pending").toLowerCase();
+      if (!TASK_STATUS[tw]) {
+        add(text(t && t.id) || `${id} task`, `status "${t.status}" is not a status the Roadmap knows`,
+          `use one of ${Object.keys(TASK_STATUS).join(", ")}`);
+      }
+    }
+    const list = Array.isArray(ph && ph.criteria) ? ph.criteria : [];
+    if (list.length === 0) {
+      add(id, "no criteria", "add at least one criterion with check, how (the exact test, command or page) and expect (the exact result)");
+    }
+    for (const c of list) {
+      const cid = text(c && c.id) || `${id} criterion`;
+      criteria.set(cid, c);
+      const claim = text(c && c.check).replace(/^\[[ xX]?\]\s*/, "");
+      if (/^works\.?$/i.test(claim) || /^it works\.?$/i.test(claim)) {
+        add(cid, "the check says only 'works'", "say what is true when it works: the result a test, command or page shows");
+      }
+      if (!text(c && c.how)) add(cid, "no how", "name the exact test file, command, API call or page and its steps");
+      const expect = text(c && c.expect);
+      if (!expect) add(cid, "no expect", "write the exact result: output, status code, field or what the page shows");
+      else if (!EXACT.test(expect)) {
+        add(cid, `expect "${expect}" names nothing a reader can compare`,
+          "name a number, a status code, an exact string in quotes, a file or a URL");
+      }
+      if (done) {
+        const ev = text(c && c.evidence);
+        if (!ev) add(cid, "no evidence", "run the check and paste what it showed (output, status code, URL or file)");
+        else if (EMPTY_WORDS.test(ev) || !SEEN.test(ev)) {
+          add(cid, `evidence "${ev}" shows nothing that was seen`, "paste the command output, status code, URL or file that proves it");
+        }
+      }
+    }
+  }
+
+  // A decision written as a sentence is a recorded answer (older plans); an object with a
+  // question is open until its "decision" holds the answer.
+  for (const d of Array.isArray(plan.decisions) ? plan.decisions : []) {
+    if (d && typeof d === "object" && (d.decision === null || d.decision === undefined || text(String(d.decision)) === "")) {
+      add(text(d.id) || "decision", "not answered", "ask the owner and write the answer in \"decision\" before building");
+    }
+  }
+  for (const k of Array.isArray(plan.claims) ? plan.claims : []) {
+    const ids = text(k && k.prove_by).match(/\b[A-Z]+\d+-C\d+\b/g) || [];
+    const missing = ids.filter((x) => !criteria.has(x));
+    if (ids.length === 0) add(text(k && k.id) || "claim", "no criterion proves it", "set prove_by to the criterion ids that prove the claim, e.g. P2-C1");
+    else if (missing.length) add(text(k.id) || "claim", `prove_by names ${missing.join(", ")}, which no phase has`, "fix the ids or add those criteria");
+  }
+  if (done) {
+    const gaps = (plan.critic && plan.critic.before_done && plan.critic.before_done.gaps) || [];
+    for (const g of Array.isArray(gaps) ? gaps : []) {
+      const st = text(g && g.status).toLowerCase();
+      if (st !== "closed" && st !== "accepted") {
+        add(text(g && g.id) || "critic gap", "critic gap still open", "close it with proof, or have the owner accept it with a reason");
+      }
+    }
+  }
+  // D6: before a merge or deploy, the task's own phase proves every criterion a test or a
+  // command can prove; criteria proved on dev (browser, api) get their evidence after the deploy.
+  // P5-C4: `merge: true` (no phase named) asks it of every phase, as the runner does for a task's plan.
+  if (merge) {
+    const ph = merge === true ? null : phases.find((x) => text(x && x.id) === merge);
+    if (merge !== true && !ph) {
+      add("phase", `no phase ${merge} in this plan`, `set "phase" in the branch's plan pointer to one of ${phases.map((x) => x.id).join(", ")}`);
+      return { errors, summary: null };
+    }
+    const list = (ph ? [ph] : phases).flatMap((x) => (Array.isArray(x && x.criteria) ? x.criteria : []));
+    const before = list.filter((c) => ["test", "command"].includes(text(c && c.kind).toLowerCase()));
+    for (const c of before) {
+      const ev = text(c.evidence);
+      if (!ev) add(text(c.id), "no evidence", "run the test or command and paste what it showed, before the merge");
+      else if (EMPTY_WORDS.test(ev) || !SEEN.test(ev)) add(text(c.id), `evidence "${ev}" shows nothing that was seen`, "paste the output, status code or file that proves it");
+    }
+    if (!errors.length) {
+      return { errors, summary: `merge ok: ${merge === true ? "every phase" : merge}, ${before.length} of ${list.length} criteria proved before the deploy, ${list.length - before.length} on dev after` };
+    }
+  }
+  const n = [...criteria.keys()].length;
+  return { errors, summary: errors.length ? null : `plan ok: ${phases.length} ${phases.length === 1 ? "phase" : "phases"}, ${n} ${n === 1 ? "criterion" : "criteria"}` };
+}
+
+/** The shared fetch helper: copied into lib/ at pack and test time; in a plain checkout it is
+ *  read from the kit, where it lives (.iKanban/hooks/ikanban-safe.js). */
+function safe() {
+  try {
+    return require("./ikanban-safe.js");
+  } catch {
+    return require("../../.iKanban/hooks/ikanban-safe.js");
+  }
+}
+
+/** "--task IKA-1" → { task: "IKA-1" }; flags without a value are true. */
+function flags(args) {
+  const out = {};
+  for (let i = 0; i < args.length; i++) {
+    if (!args[i].startsWith("--")) continue;
+    const next = args[i + 1];
+    out[args[i].slice(2)] = next && !next.startsWith("--") ? args[++i] : true;
+  }
+  return out;
+}
+
+/** D5: the task's open "before Done" gaps on iKanban (the runner's critic files them there).
+ *  Fails closed: no key, no team or no answer is a problem, never a pass. */
+async function serverGaps(file, plan, opts, stages = ["before_done"]) {
+  const { connection } = require("./roadmap.js");
+  const { ikanbanFetch } = safe();
+  const c = connection({ token: opts.token, "base-url": opts["base-url"] }, file);
+  // IKA-2839: --team, then the plan's own team, then the settings team (another team's plan
+  // was read from the settings team and refused with a 404).
+  let team = String(opts.team || (plan.roadmap && plan.roadmap.team) || c.team || "");
+  const task = String(opts.task);
+  if (!c.token) return [{ where: task, problem: "no API key to read its critic gaps", fix: "set VIBE_API_TOKEN, pass --token, or set api_key in .iKanban/settings-local.json" }];
+  let res;
+  try {
+    // The route takes only a team id: an identifier such as "TUT" is looked up among the key's teams.
+    if (team && !/^[0-9a-f-]{36}$/i.test(team)) {
+      const t = await ikanbanFetch("/api/teams", { base: c.base, token: c.token });
+      const body = await t.json().catch(() => ({}));
+      const hit = t.ok && Array.isArray(body.data) && body.data.find((x) => String(x.identifier || "").toLowerCase() === team.toLowerCase());
+      if (!hit) return [{ where: task, problem: `team "${team}" not found among your teams${t.ok ? "" : ` (HTTP ${t.status})`}`, fix: "set roadmap.team to a team identifier or id the key's account is in, or pass --team <team id>" }];
+      team = hit.id;
+    }
+    if (!/^[0-9a-f-]{36}$/i.test(team)) return [{ where: task, problem: `team "${team}" is not a team id`, fix: "pass --team <team id> or set team in .iKanban/settings-local.json" }];
+    res = await ikanbanFetch(`/api/teams/${team}/tasks/${encodeURIComponent(task)}/critic-reviews`, { base: c.base, token: c.token });
+  } catch (e) {
+    return [{ where: task, problem: `critic gaps not read: ${e.message}`, fix: "check the network and the API address, then run the check again" }];
+  }
+  const body = await res.json().catch(() => ({}));
+  if (!res.ok || body.success === false) {
+    return [{ where: task, problem: `critic gaps not read: HTTP ${res.status} ${body.message || ""}`.trim(), fix: "check the task key and that the key's account is in the team" }];
+  }
+  const gaps = (body.data.reviews || []).filter((rv) => stages.includes(rv.stage))
+    .flatMap((rv) => rv.gaps || []).filter((g) => g.state === "open");
+  return gaps.map((g) => ({ where: `${task} gap ${g.id}`, problem: `${g.gap || "critic gap"} (still open on iKanban)`, fix: "close it with proof, or have the owner accept it with a reason (MCP close_critic_gap / accept_critic_gap)" }));
+}
+
+/** `ikanban plan check FILE [--done [--task KEY]]`: exit 0 with the summary, 1 with each problem. */
+function run(args) {
+  const [sub, ...rest] = args;
+  const file = rest.find((a) => !a.startsWith("--"));
+  if (sub !== "check" || !file || rest.includes("--help")) {
+    console.log("Usage: ikanban plan check FILE [--done [--task KEY] [--team ID]]\n  --done  also every criterion has evidence and every before_done critic gap is closed or accepted\n  --task  with --done: also the task's open before_done gaps on iKanban (the runner's critic)");
+    return sub === "check" && file ? 0 : 1;
+  }
+  let raw;
+  try {
+    raw = fs.readFileSync(file, "utf8");
+  } catch {
+    console.error(`plan file not found: ${file}\nWrite it from the template: ${GUIDE}`);
+    return 1;
+  }
+  let plan;
+  try {
+    plan = JSON.parse(raw);
+  } catch (e) {
+    console.error(`${file} is not valid JSON (${e.message}). Fix it, then run: ikanban plan check ${file}`);
+    return 1;
+  }
+  const opts = flags(rest);
+  const merge = typeof opts.merge === "string" ? opts.merge : typeof opts.phase === "string" && opts.merge ? opts.phase : opts.merge === true ? true : null;
+  const r = check(plan, { done: Boolean(opts.done), merge });
+  const report = (errors, summary) => {
+    if (errors.length) {
+      for (const e of errors) console.error(`${e.where}: ${e.problem}. Fix: ${e.fix}.`);
+      console.error(`${errors.length} ${errors.length === 1 ? "problem" : "problems"} in ${file}. Guide: ${GUIDE}`);
+      return 1;
+    }
+    console.log(summary);
+    return 0;
+  };
+  if (merge && typeof opts.task === "string") {
+    // D6: any open critic gap of the task blocks the merge, before the build or before Done.
+    return serverGaps(file, plan, opts, ["before_build", "before_done"]).then((gaps) =>
+      report([...r.errors, ...gaps], `${r.summary}; ${opts.task}: 0 open critic gaps on iKanban`));
+  }
+  if (!(opts.done && typeof opts.task === "string")) return report(r.errors, r.summary);
+  return serverGaps(file, plan, opts).then((gaps) =>
+    report([...r.errors, ...gaps], `${r.summary}; ${opts.task}: 0 open critic gaps on iKanban`));
+}
+
+module.exports = { check, run };

package/lib/roadmap.js

@@ -6,19 +6,22 @@
 //   "roadmap": {"team": "<team id or identifier>", "plan_id": "<plan feature id>",
 //               "project": "<project id or name for new tasks>", "name": "<plan name>"}
 // plan_id is written back after the first sync creates the plan. Phases:
-//   [{id, title, status, depends_on, tasks: [{id, description|title, status}]}]
+//   [{id, title, status, depends_on, criteria: [...], tasks: [{id, description|title, status}]}]
 const fs = require("node:fs");
 const path = require("node:path");
-const { runCommand, ikanbanFetch, apiOrigin } = require("./ikanban-safe.js");
+// Copied into lib/ at pack and test time; a plain checkout reads it from the kit (plan 7: the
+// gates run `ikanban plan check` there).
+const { runCommand, ikanbanFetch, apiOrigin } = (() => {
+  try {
+    return require("./ikanban-safe.js");
+  } catch {
+    return require("../../.iKanban/hooks/ikanban-safe.js");
+  }
+})();
 
-const TASK_STATUS = {
-  done: "done", complete: "done", completed: "done",
-  in_progress: "inprogress", inprogress: "inprogress", "in-progress": "inprogress", started: "inprogress",
-  in_review: "inreview", inreview: "inreview", review: "inreview",
-  pending: "todo", todo: "todo", waiting: "todo", deferred: "todo", blocked: "todo",
-  cancelled: "cancelled", canceled: "cancelled", skipped: "cancelled", dropped: "cancelled",
-};
-const PHASE_STATUS = { done: "done", in_progress: "in_progress", inprogress: "in_progress", "in-progress": "in_progress" };
+const { TASK_STATUS, PHASE_STATUS } = require("./statuswords.js");
+// Plan 34 R3-T6: the words a plan file uses to hold a task on purpose.
+const HOLD_WORDS = new Set(["blocked", "deferred", "waiting"]);
 
 /** First clause of a task text, cut at a word; no links or email addresses. */
 function short(text, limit = 60) {
@@ -47,13 +50,19 @@ function toDocument(plan) {
       // Only an explicit "name" renames an existing phase; a name made from the
       // title only names a new one, so a rename on the Roadmap (the pencil) stays.
       rename: Boolean(ph.name),
+      // IKA-2675: only the count goes; the server warns for a phase with none. Old
+      // "acceptance_criteria" strings do not count, as in `ikanban plan check`.
+      criteria: Array.isArray(ph.criteria) ? ph.criteria.length : 0,
       tasks: (ph.tasks || []).map((t) => {
         const word = String(t.status || "pending").toLowerCase();
         let status = TASK_STATUS[word];
         if (!status) errors.push(`task ${t.id}: unknown status "${t.status}"`);
         // A deferred task in a phase the plan calls done is out of its scope.
         if (word === "deferred" && phaseWord === "done") status = "cancelled";
-        return { key: t.id, title: `${t.id}: ${short(t.title || t.description)}`, status, rename: Boolean(t.title) };
+        // Plan 34 R3-T6: a task held on purpose may go back to To do on the Roadmap; a file that
+        // only says less ("pending", "todo") never pulls a task back.
+        const hold = status === "todo" && HOLD_WORDS.has(word);
+        return { key: t.id, title: `${t.id}: ${short(t.title || t.description)}`, status, rename: Boolean(t.title), hold };
       }),
     };
   });
@@ -65,6 +74,17 @@ function toDocument(plan) {
   };
 }
 
+/** IKA-2870 (plan 45 P7): <name>.graph.json beside the plan, one view per phase. Only a regular file
+ *  of at most 256 KB holding a JSON object; else no diagram, never a failed sync (the server checks). */
+function readGraph(file) {
+  const g = file.replace(/\.json$/i, "") + ".graph.json";
+  try {
+    const st = fs.lstatSync(g);
+    const doc = st.isFile() && st.size <= 256 * 1024 ? JSON.parse(fs.readFileSync(g, "utf8")) : null;
+    return doc && typeof doc === "object" && !Array.isArray(doc) ? doc : undefined;
+  } catch { return undefined; }
+}
+
 /** .iKanban/settings-local.json (or the older .i-kanban/) nearest to `dir`. */
 function localSettings(dir) {
   for (let d = path.resolve(dir); ; d = path.dirname(d)) {
@@ -116,6 +136,7 @@ async function syncFile(file, opts) {
   const doc = toDocument(plan);
   doc.project = doc.project || c.project;
   doc.dry_run = Boolean(opts.check || opts["dry-run"]);
+  doc.graph = readGraph(file) ?? null; // null clears a diagram the file no longer has
   // Deleting an empty phase the sync created needs an explicit flag; MCP never deletes.
   if (opts["allow-delete"]) doc.allow_delete = true;
   let res;
@@ -171,27 +192,84 @@ function mergeJson(file, update) {
   fs.writeFileSync(file, JSON.stringify(next, null, 2) + "\n");
 }
 
-/** Adds one entry to hooks[event]; an entry that already runs roadmap-sync.js is replaced
- *  by it (IKA-2244: so a re-install fixes an older install's command), never doubled. */
-function addHook(settings, event, entry) {
+// Plan 35 V1-T4: the deploy check runs after each shell command (it acts only on the deploy
+// commands named in settings-local.json "deploy_check"). Not async: its answer is the context.
+const DEPLOY_COMMAND = "node .iKanban/hooks/deploy-check.js";
+const CLAUDE_DEPLOY_COMMAND = 'node "$CLAUDE_PROJECT_DIR/.iKanban/hooks/deploy-check.js"';
+// Plan 7 P4-T3: before each edit and shell command, the task's plan must pass (no bypass, D2).
+const GATE_COMMAND = "node .iKanban/hooks/plan-gate.js";
+const CLAUDE_GATE_COMMAND = 'node "$CLAUDE_PROJECT_DIR/.iKanban/hooks/plan-gate.js"';
+
+/** Adds one entry to hooks[event]; an entry that already runs the same script (`script`) is
+ *  replaced by it (IKA-2244: so a re-install fixes an older install's command), never doubled. */
+function addHook(settings, event, entry, script = "roadmap-sync.js") {
   settings.hooks = settings.hooks || {};
   const list = (settings.hooks[event] = settings.hooks[event] || []);
-  const at = list.findIndex((e) => JSON.stringify(e).includes("roadmap-sync.js"));
+  const at = list.findIndex((e) => JSON.stringify(e).includes(script));
   if (at < 0) list.push(entry);
   else list[at] = entry;
   return settings;
 }
 
+// Plan 43 P4-T2: `--trace` also wires the trace hook, exactly as .iKanban/README.md shows it.
+// Wiring only: the hook does nothing until `node .iKanban/hooks/trace.js --on`.
+const TRACE = "node .iKanban/hooks/trace.js";
+const CLAUDE_TRACE = 'node "$CLAUDE_PROJECT_DIR/.iKanban/hooks/trace.js"';
+const TRACE_AGENTS = {
+  claude: (root) => {
+    mergeJson(path.join(root, ".claude", "settings.json"), (s) => {
+      addHook(s, "PostToolUse", { hooks: [{ type: "command", command: CLAUDE_TRACE, async: true }] }, "trace.js");
+      addHook(s, "PostToolUseFailure", { hooks: [{ type: "command", command: CLAUDE_TRACE, async: true }] }, "trace.js");
+      // Stop in the foreground: a background Stop hook is stopped when Claude Code exits (README).
+      return addHook(s, "Stop", { hooks: [{ type: "command", command: CLAUDE_TRACE }] }, "trace.js");
+    });
+    return ".claude/settings.json trace (PostToolUse, PostToolUseFailure, Stop)";
+  },
+  gemini: (root) => {
+    mergeJson(path.join(root, ".gemini", "settings.json"), (s) => {
+      addHook(s, "AfterTool", { matcher: "*", hooks: [{ name: "ikanban-trace", type: "command", command: TRACE, timeout: 10000 }] }, "trace.js");
+      return addHook(s, "AfterAgent", { hooks: [{ name: "ikanban-trace", type: "command", command: TRACE, timeout: 10000 }] }, "trace.js");
+    });
+    return ".gemini/settings.json trace (AfterTool, AfterAgent)";
+  },
+  copilot: (root) => {
+    mergeJson(path.join(root, ".github", "hooks", "ikanban-trace.json"), (s) => {
+      s.version = 1;
+      for (const event of ["postToolUse", "postToolUseFailure", "agentStop"]) {
+        addHook(s, event, { type: "command", bash: `${TRACE} copilot:${event}`, cwd: ".", timeoutSec: 10 }, "trace.js");
+      }
+      return s;
+    });
+    return ".github/hooks/ikanban-trace.json (postToolUse, postToolUseFailure, agentStop)";
+  },
+  agy: (root) => {
+    mergeJson(path.join(root, ".agents", "hooks.json"), (s) => {
+      s["ikanban-trace"] = {
+        PostToolUse: [{ matcher: ".*", hooks: [{ type: "command", command: "node ../.iKanban/hooks/trace.js agy:PostToolUse", timeout: 10 }] }],
+        Stop: [{ type: "command", command: "node ../.iKanban/hooks/trace.js agy:Stop", timeout: 10 }],
+      };
+      return s;
+    });
+    return ".agents/hooks.json trace (PostToolUse, Stop)";
+  },
+};
+
 const AGENTS = {
   claude: (root) => {
-    mergeJson(path.join(root, ".claude", "settings.json"), (s) =>
-      addHook(s, "PostToolUse", { matcher: "Write|Edit|MultiEdit", hooks: [{ type: "command", command: CLAUDE_COMMAND, timeout: 90 }] }));
-    return ".claude/settings.json (PostToolUse)";
+    mergeJson(path.join(root, ".claude", "settings.json"), (s) => {
+      addHook(s, "PostToolUse", { matcher: "Write|Edit|MultiEdit", hooks: [{ type: "command", command: CLAUDE_COMMAND, timeout: 90 }] });
+      addHook(s, "PostToolUse", { matcher: "Bash", hooks: [{ type: "command", command: CLAUDE_DEPLOY_COMMAND, timeout: 20 }] }, "deploy-check.js");
+      return addHook(s, "PreToolUse", { matcher: "Edit|Write|MultiEdit|NotebookEdit|Bash|PowerShell", hooks: [{ type: "command", command: CLAUDE_GATE_COMMAND, timeout: 20 }] }, "plan-gate.js");
+    });
+    return ".claude/settings.json (PreToolUse, PostToolUse)";
   },
   gemini: (root) => {
-    mergeJson(path.join(root, ".gemini", "settings.json"), (s) =>
-      addHook(s, "AfterTool", { matcher: "write_file|replace", hooks: [{ name: "ikanban-roadmap-sync", type: "command", command: AGENT_COMMAND, timeout: 90000 }] }));
-    return ".gemini/settings.json (AfterTool)";
+    mergeJson(path.join(root, ".gemini", "settings.json"), (s) => {
+      addHook(s, "AfterTool", { matcher: "write_file|replace", hooks: [{ name: "ikanban-roadmap-sync", type: "command", command: AGENT_COMMAND, timeout: 90000 }] });
+      addHook(s, "AfterTool", { matcher: "run_shell_command", hooks: [{ name: "ikanban-deploy-check", type: "command", command: DEPLOY_COMMAND, timeout: 20000 }] }, "deploy-check.js");
+      return addHook(s, "BeforeTool", { matcher: "write_file|replace|run_shell_command", hooks: [{ name: "ikanban-plan-gate", type: "command", command: GATE_COMMAND, timeout: 20000 }] }, "plan-gate.js");
+    });
+    return ".gemini/settings.json (BeforeTool, AfterTool)";
   },
   copilot: (root) => {
     const file = path.join(root, ".github", "hooks", "ikanban-roadmap.json");
@@ -199,7 +277,24 @@ const AGENTS = {
       s.version = 1;
       return addHook(s, "postToolUse", { type: "command", bash: AGENT_COMMAND, powershell: AGENT_COMMAND, cwd: ".", timeoutSec: 90 });
     });
-    return ".github/hooks/ikanban-roadmap.json (postToolUse)";
+    mergeJson(path.join(root, ".github", "hooks", "ikanban-deploy-check.json"), (s) => {
+      s.version = 1;
+      return addHook(s, "postToolUse", { type: "command", bash: DEPLOY_COMMAND, powershell: DEPLOY_COMMAND, cwd: ".", timeoutSec: 20 }, "deploy-check.js");
+    });
+    mergeJson(path.join(root, ".github", "hooks", "ikanban-plan-gate.json"), (s) => {
+      s.version = 1;
+      return addHook(s, "preToolUse", { type: "command", matcher: "edit|create|bash|powershell", bash: GATE_COMMAND, powershell: GATE_COMMAND, cwd: ".", timeoutSec: 20 }, "plan-gate.js");
+    });
+    return ".github/hooks/ikanban-roadmap.json, ikanban-deploy-check.json (postToolUse) and ikanban-plan-gate.json (preToolUse)";
+  },
+  // Antigravity CLI (agy, where Gemini users went) reads .agents/hooks.json, named hooks, and runs
+  // them from .agents/ (antigravity.google/docs/hooks). Its edit tools are not listed, so ".*".
+  agy: (root) => {
+    mergeJson(path.join(root, ".agents", "hooks.json"), (s) => {
+      s["ikanban-plan-gate"] = { PreToolUse: [{ matcher: ".*", hooks: [{ type: "command", command: "node ../.iKanban/hooks/plan-gate.js", timeout: 20 }] }] };
+      return s;
+    });
+    return ".agents/hooks.json (PreToolUse, Antigravity)";
   },
 };
 
@@ -211,10 +306,15 @@ function installHooks(opts) {
   const script = path.join(root, ".iKanban", "hooks", "roadmap-sync.js");
   fs.mkdirSync(path.dirname(script), { recursive: true });
   // The hook runs its commands through ikanban-safe.js, so both files go together.
-  for (const name of ["roadmap-sync.js", "ikanban-safe.js"]) {
+  for (const name of ["roadmap-sync.js", "deploy-check.js", "ikanban-safe.js", "plan-gate.js", ...(opts.trace ? ["trace.js"] : [])]) {
     fs.copyFileSync(path.join(__dirname, "..", "hooks", name), path.join(path.dirname(script), name));
     done.push(`.iKanban/hooks/${name}`);
   }
+  // The plan gate checks with this package's own checker, so a repository needs no network for it.
+  for (const name of ["plancheck.js", "statuswords.js"]) {
+    fs.copyFileSync(path.join(__dirname, name), path.join(path.dirname(script), name));
+    done.push(`.iKanban/hooks/${name}`);
+  }
 
   const hooksDir = runCommand("git", ["rev-parse", "--git-path", "hooks"], { cwd: root, encoding: "utf8" }).stdout.trim();
   const prePush = path.resolve(root, hooksDir, "pre-push");
@@ -227,13 +327,18 @@ function installHooks(opts) {
   done.push("git pre-push hook");
 
   const wanted = opts.agent ? String(opts.agent).split(",") : Object.keys(AGENTS).filter((a) =>
-    fs.existsSync(path.join(root, { claude: ".claude", gemini: ".gemini", copilot: ".github" }[a])));
+    fs.existsSync(path.join(root, { claude: ".claude", gemini: ".gemini", copilot: ".github", agy: ".agents" }[a])));
   for (const a of wanted) {
-    if (!AGENTS[a]) throw new Error(`unknown agent "${a}" (claude, gemini, copilot)`);
+    if (!AGENTS[a]) throw new Error(`unknown agent "${a}" (claude, gemini, copilot, agy)`);
     done.push(AGENTS[a](root));
+    if (opts.trace) done.push(TRACE_AGENTS[a](root));
   }
   for (const d of done) console.log(`  installed: ${d}`);
   console.log("Plan files (JSON with a top-level \"roadmap\" block) now reach the Roadmap on every agent write and every git push.");
+  console.log("Before an edit or a writing shell command, the plan gate needs the task's plan, docs/plans/<TASK-KEY>.json (the key from the branch name), to pass: node .iKanban/hooks/plan-gate.js check docs/plans/<TASK-KEY>.json. How to write one: .iKanban/prompts/feature-plan.md.");
+  console.log("After a deploy, the deploy check reads your site's build marker; name your deploy commands in .iKanban/settings-local.json \"deploy_check\" (README).");
+  if (opts.trace && wanted.length) console.log("The trace hook is wired but still off. Turn it on in this repository with: node .iKanban/hooks/trace.js --on");
+  else if (opts.trace) console.log("Trace hook not wired: no agent folder found (looked for .claude, .gemini, .github, .agents). Create the agent's folder, or name it: ikanban hooks install --trace --agent claude");
   // IKA-2244: the sync's default server is prod; say which one this repository will use.
   const base = connection({}, path.join(root, "plan.json")).base;
   console.log(`  server: ${base} (set api_url in .iKanban/settings-local.json, or IKANBAN_BASE_URL, to use another)`);
@@ -245,9 +350,11 @@ const HELP = `Usage:
       Make each plan's Roadmap match the file. No file: every tracked JSON file
       with a top-level "roadmap" block. --check: change nothing, exit 1 on drift.
       --allow-delete: also delete an emptied phase the sync created (else it stays).
-  ikanban hooks install [--agent claude,gemini,copilot]
+  ikanban hooks install [--agent claude,gemini,copilot,agy] [--trace]
       Keep the Roadmap in step without CI: a git pre-push hook (any git host) and
-      a hook for each agent whose folder exists (.claude, .gemini, .github).
+      a hook for each agent whose folder exists (.claude, .gemini, .github, .agents).
+      --trace: also wire .iKanban/hooks/trace.js for those agents. Tracing stays
+      off until: node .iKanban/hooks/trace.js --on
 
 Key: VIBE_API_TOKEN, --token, or api_key in .iKanban/settings-local.json.
 Server: IKANBAN_BASE_URL, --base-url, or api_url there (default https://api.i-kanban.com).`;
@@ -290,4 +397,4 @@ async function run(cmd, args) {
   return code;
 }
 
-module.exports = { run, toDocument, short, writePlanId, addHook, apiOrigin };
+module.exports = { run, toDocument, short, writePlanId, addHook, apiOrigin, connection, TASK_STATUS, PHASE_STATUS };