@nodii/dev 0.6.29 → 0.6.31

package/dist/nudges.js

@@ -0,0 +1,441 @@
+// Guideline nudge hooks (AGENT-HARNESS-21, agent-harness-design.md "Hooks").
+//
+// A nudge reminds a lane of a rule at the moment it is about to break it, and
+// says nothing when the rule is already met. Nothing here blocks a tool call;
+// the one hard stop in a session (Stop) is asked at most once. Every entry
+// point fails open: an error, an unknown payload or no lane yields no nudge.
+// Each nudge names the clause it protects, so an unused one can be retired.
+import { execFile } from "node:child_process";
+import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { dirname, isAbsolute, relative, resolve } from "node:path";
+import { promisify } from "node:util";
+import { isFigmaTool, isReadTool } from "./hooks.js";
+import { patchPaths } from "./safety.js";
+
+const execFileAsync = promisify(execFile);
+const EDIT_TOOLS = new Set(["Edit", "Write", "MultiEdit", "NotebookEdit", "apply_patch"]);
+const SHELL_TOOLS = new Set(["Bash", "shell", "exec_command"]);
+export const LANE_KNOWLEDGE = "nodii-lane-knowledge.json";
+export const SUBMIT_CHECKS = "nodii-submit-checks.json";
+export const SUBMIT_CHECK_FLAGS = ["unused-properties", "stale-placeholders", "dialog-body"];
+const OPEN_MD = "docs/figma-ux-drive/qa-with-abhi/open.md";
+const DS_SOURCE = /["'](@cognion-nucleus\/nodii-(?:design-system|blocks)(?:\/[^"']*)?)["']/;
+const MAX_LISTED = 6;
+
+// A file a nudge cannot read is the same as one that is not there.
+async function optional(path) {
+  try { return await readFile(path, "utf8"); }
+  catch { return null; }
+}
+
+async function git(cwd, ...args) {
+  return (await execFileAsync("git", args, { cwd, encoding: "utf8" })).stdout.trim();
+}
+
+const privatePath = (cwd, name) => git(cwd, "rev-parse", "--path-format=absolute", "--git-path", name);
+
+async function readPrivateJson(cwd, name) {
+  try {
+    const text = await optional(await privatePath(cwd, name));
+    return text ? JSON.parse(text) : {};
+  } catch { return {}; }
+}
+
+async function writePrivateJson(cwd, name, update) {
+  const path = await privatePath(cwd, name);
+  const before = await optional(path).then((text) => (text ? JSON.parse(text) : {})).catch(() => ({}));
+  const next = update(before);
+  await mkdir(dirname(path), { recursive: true });
+  const temporary = `${path}.${process.pid}.tmp`;
+  await writeFile(temporary, `${JSON.stringify(next, null, 2)}\n`, { mode: 0o600 });
+  await rename(temporary, path);
+  return next;
+}
+
+/**
+ * What the lane has already read. Gather writes `guidelines` (the lane's
+ * gathered set) and `deltaGathered` (paths a Delta gather covered); reading a
+ * guideline with `design guideline show` adds to `guidelinesRead`.
+ */
+export const laneKnowledge = (cwd) => readPrivateJson(cwd, LANE_KNOWLEDGE);
+
+/** What `lane gather` covered: the components asked for, and on a Delta gather the paths it saw. */
+export const recordGathered = (cwd, { guidelines = [], deltaGathered = [] }) =>
+  writePrivateJson(cwd, LANE_KNOWLEDGE, (state) => ({
+    ...state,
+    guidelines: [...new Set([...(state.guidelines ?? []), ...guidelines])],
+    deltaGathered: [...new Set([...(state.deltaGathered ?? []), ...deltaGathered])],
+  }));
+
+/** The paths this worktree changes against origin/main, committed or not. */
+export async function changedPaths(cwd) {
+  const base = await git(cwd, "merge-base", "origin/main", "HEAD");
+  const lines = [await git(cwd, "diff", "--name-only", base), await git(cwd, "ls-files", "--others", "--exclude-standard", "--full-name")];
+  return [...new Set(lines.join("\n").split("\n").map((line) => line.trim()).filter(Boolean))].slice(0, 5000);
+}
+
+export const recordGuidelineRead = (cwd, key) =>
+  writePrivateJson(cwd, LANE_KNOWLEDGE, (state) => ({ ...state, guidelinesRead: [...new Set([...(state.guidelinesRead ?? []), key])] }));
+
+/** The checks attested for one Figma change set before its submit. */
+export const recordSubmitChecks = (cwd, changeSet, checks) =>
+  writePrivateJson(cwd, SUBMIT_CHECKS, (state) => ({ ...state, [changeSet]: { ...state[changeSet], ...Object.fromEntries(checks.map((check) => [check, new Date().toISOString()])) } }));
+
+// ─── reading the edit ──────────────────────────────────────────────────────
+
+const cleanPath = (path) => String(path).split("\\").join("/").replace(/^\.\//, "");
+
+function editedPaths(payload) {
+  const input = payload.tool_input ?? {};
+  if (payload.tool_name === "apply_patch") return patchPaths(input.command ?? input.input);
+  return [input.file_path, input.path, input.notebook_path].filter((x) => typeof x === "string" && x);
+}
+
+const lf = (text) => String(text).replace(/\r\n/g, "\n");
+const replaceOnce = (text, from, to, all = false) => {
+  if (!from || !text.includes(from)) return null;
+  return all ? text.split(from).join(to) : text.replace(from, () => to);
+};
+
+/** One v4A patch section applied to `text`; a hunk that does not apply adds its new lines at the end. */
+function patchedText(text, section) {
+  let result = text;
+  for (const hunk of section.split(/^@@.*$/m)) {
+    const oldLines = [];
+    const newLines = [];
+    const lines = hunk.split("\n");
+    while (lines.length && lines.at(-1) === "") lines.pop();
+    for (const line of lines) {
+      if (line === "") { oldLines.push(""); newLines.push(""); }
+      else if (line.startsWith("+")) newLines.push(line.slice(1));
+      else if (line.startsWith("-")) oldLines.push(line.slice(1));
+      else if (line.startsWith(" ")) { oldLines.push(line.slice(1)); newLines.push(line.slice(1)); }
+    }
+    if (!oldLines.length && !newLines.length) continue;
+    const next = oldLines.length ? replaceOnce(result, oldLines.join("\n"), newLines.join("\n")) : null;
+    result = next ?? `${result}\n${newLines.join("\n")}`;
+  }
+  return result;
+}
+
+/** Each file the call writes, before and after it, as best the payload shows. */
+async function editedFiles(payload, cwd) {
+  const input = payload.tool_input ?? {};
+  const absolute = (path) => (isAbsolute(path) ? path : resolve(cwd, path));
+  if (payload.tool_name === "apply_patch") {
+    const sections = String(input.command ?? input.input ?? "").split(/^\*\*\* (?=(?:Add|Update|Delete) File: )/m).slice(1);
+    return Promise.all(sections.map(async (section) => {
+      const [head, ...body] = section.split("\n");
+      const [, kind, name] = /^(Add|Update|Delete) File: (.+)$/.exec(head) ?? [];
+      const from = absolute(name?.trim() ?? "");
+      const moved = /^\*\*\* Move to: (.+)$/m.exec(body.join("\n"))?.[1]?.trim();
+      const path = moved ? absolute(moved) : from;
+      const disk = await optional(from);
+      const before = kind === "Add" ? "" : lf(disk ?? "");
+      const text = body.join("\n");
+      const after = kind === "Add" ? text.split("\n").filter((line) => line.startsWith("+")).map((line) => line.slice(1)).join("\n") : patchedText(before, lf(text));
+      return { kind, path, existed: (moved ? await optional(path) : disk) !== null, before, after };
+    })).then((files) => files.filter((file) => file.kind !== "Delete"));
+  }
+  const paths = editedPaths(payload).map(absolute).slice(0, 1);
+  return Promise.all(paths.map(async (path) => {
+    const disk = await optional(path);
+    const before = lf(disk ?? "");
+    let after;
+    if (typeof input.content === "string") after = lf(input.content);
+    else if (typeof input.new_source === "string") after = lf(input.new_source);
+    else if (Array.isArray(input.edits)) after = input.edits.reduce((text, edit) => replaceOnce(text, lf(edit?.old_string ?? ""), lf(edit?.new_string ?? ""), edit?.replace_all) ?? `${text}\n${lf(edit?.new_string ?? "")}`, before);
+    else after = replaceOnce(before, lf(input.old_string ?? ""), lf(input.new_string ?? ""), input.replace_all) ?? `${before}\n${lf(input.new_string ?? "")}`;
+    return { path, existed: disk !== null, before, after };
+  }));
+}
+
+const lineCounts = (text) => {
+  const counts = new Map();
+  for (const line of String(text).split("\n")) counts.set(line.trim(), (counts.get(line.trim()) ?? 0) + 1);
+  return counts;
+};
+/** Lines of `after` that `before` does not have. */
+function changedLines(before, after) {
+  const had = lineCounts(before);
+  return String(after).split("\n").filter((line) => {
+    const key = line.trim();
+    if (!key) return false;
+    if (had.get(key) > 0) { had.set(key, had.get(key) - 1); return false; }
+    return true;
+  });
+}
+
+const kebab = (name) => name.replace(/([a-z0-9])([A-Z])/g, "$1-$2").replace(/([A-Z])([A-Z][a-z])/g, "$1-$2").toLowerCase();
+
+/** Local name → DS export, for PascalCase components imported from the DS or its blocks. */
+export function dsImports(text) {
+  const out = new Map();
+  for (const match of String(text).matchAll(/import\s+(?!type\b)\{([^}]*)\}\s+from\s+(["'][^"']+["'])/g)) {
+    if (!DS_SOURCE.test(match[2])) continue;
+    for (const part of match[1].split(",")) {
+      const spec = part.trim();
+      if (!spec || /^type\s/.test(spec)) continue;
+      const [imported, local = imported] = spec.split(/\s+as\s+/);
+      if (/^[A-Z]/.test(imported) && !/(?:Props|Variants?|Context)$/.test(imported)) out.set(local.trim(), imported.trim());
+    }
+  }
+  return out;
+}
+
+/**
+ * Every `<Tag …>` opening tag: its name, its source (`raw`), and the attribute
+ * text outside `{…}` and quotes. An expression is skipped by brace depth alone,
+ * so an apostrophe or a regex inside one cannot swallow the rest of the file.
+ */
+export function jsxOpenTags(text) {
+  const tags = [];
+  const source = String(text);
+  for (const match of source.matchAll(/<([A-Z][\w.]*)(?=[\s/>])/g)) {
+    let depth = 0;
+    let quote = null;
+    let attrs = "";
+    let end = source.length;
+    for (let at = match.index + match[0].length; at < source.length; at += 1) {
+      const char = source[at];
+      if (quote) { attrs += char === quote ? char : " "; if (char === quote) quote = null; continue; }
+      if (char === "{") { depth += 1; attrs += " "; continue; }
+      if (char === "}") { depth = Math.max(0, depth - 1); continue; }
+      if (depth > 0) continue;
+      if (char === '"' || char === "'") { quote = char; attrs += char; continue; }
+      if (char === ">") { end = at; break; }
+      attrs += char;
+    }
+    tags.push({ tag: match[1], attrs, raw: source.slice(match.index, end + 1) });
+  }
+  return tags;
+}
+
+/** Opening tags in `after` that `before` does not already have verbatim. */
+function changedTags(before, after) {
+  const had = new Map();
+  for (const { raw } of jsxOpenTags(before)) had.set(raw, (had.get(raw) ?? 0) + 1);
+  return jsxOpenTags(after).filter(({ raw }) => {
+    if (had.get(raw) > 0) { had.set(raw, had.get(raw) - 1); return false; }
+    return true;
+  });
+}
+
+const withoutTags = (text) => jsxOpenTags(text).reduce((out, { raw }) => out.replace(raw, " "), String(text));
+const uiFile = (path) => /\.(?:tsx|jsx)$/.test(path) && !/\.(?:test|spec|stories)\.[jt]sx?$/.test(path);
+
+// ─── the nudges ────────────────────────────────────────────────────────────
+
+// A part's guideline is its root's: `dialog` covers `dialog-content`, but `alert` does not cover `alert-dialog`.
+const PARTS = /^(?:content|header|footer|title|description|trigger|item|items|list|group|label|separator|body|row|cell|head|caption|action|cancel|close|overlay|portal|value|indicator|viewport|sub|text|root)$/;
+const covers = (known, key) => known.some((entry) => key === entry || (key.startsWith(`${entry}-`) && key.slice(entry.length + 1).split("-").every((part) => PARTS.test(part))));
+const listed = (items) => items.slice(0, MAX_LISTED).join(", ") + (items.length > MAX_LISTED ? `, +${items.length - MAX_LISTED} more` : "");
+const PAGE_NOISE = /^(?:index|types?|utils?|constants?|use-.*|.*-(?:types?|utils?|constants?|mocks?|fixtures?|helpers?|hooks?))$/;
+
+/** DS component or product page used or edited without its guideline in the lane's gathered set. */
+export function guidelineNudges({ rel, before, after }, knowledge) {
+  const known = [...(knowledge.guidelines ?? []), ...(knowledge.guidelinesRead ?? [])].map(kebab);
+  const keys = new Set();
+  const component = /(?:^|\/)packages\/design-system\/src\/components\/([a-z0-9-]+)\.tsx$/.exec(rel);
+  if (component) keys.add(component[1]);
+  const page = /(?:^|\/)product-pages\/(?:.*\/)?([a-z0-9-]+?)(?:\.figma)?\.(?:tsx|ts)$/.exec(rel);
+  if (page && page[1].includes("-") && !PAGE_NOISE.test(page[1])) keys.add(page[1]);
+  if (uiFile(rel)) {
+    const imports = dsImports(after);
+    for (const { tag } of changedTags(before, after)) {
+      const root = tag.split(".")[0];
+      if (imports.has(root)) keys.add(kebab(imports.get(root)));
+    }
+  }
+  const missing = [...keys].filter((key) => !covers(known, key));
+  if (!missing.length) return [];
+  return [`nodii-dev nudge: no guideline for ${listed(missing)} in this lane's gathered set. Read it before using or editing it: ${missing.slice(0, 3).map((key) => `\`nodii-dev design guideline show ${key}\``).join(", ")} (U07-19, DEC-0010).`];
+}
+
+/** className or style passed to a DS component (U07-19). */
+export function restyleNudges({ rel, before, after }) {
+  if (!uiFile(rel)) return [];
+  const imports = dsImports(after);
+  const hits = new Set();
+  for (const { tag, attrs } of changedTags(before, after)) {
+    if (!imports.has(tag.split(".")[0])) continue;
+    for (const prop of ["className", "style"]) if (new RegExp(`(?:^|\\s)${prop}\\s*=`).test(attrs)) hits.add(`<${tag} ${prop}>`);
+  }
+  if (!hits.size) return [];
+  return [`nodii-dev nudge: ${listed([...hits])}: a consumer MUST NOT pass className or style to a DS component (U07-19). Set only props, variants, slots and children; a missing capability is a DS gap (U07-20), filed as a DS issue.`];
+}
+
+const PERSON_FIELD = /(?<!\$)\{\s*[\w$.?]+\??\.(?:email|phone|mobile|displayName|fullName|firstName|lastName|personName)\s*\}/;
+const MASKING = /\bmask(?:ed)?(?:Name|Email|Phone|Pii|Person)?\s*\(|\b[A-Za-z]\*{3,}/;
+
+/** Code that renders a person: through PiiText, never masking the viewer (R5, U05-25). */
+export function selfPiiNudges({ rel, before, after }) {
+  if (!uiFile(rel)) return [];
+  const notes = [];
+  for (const { tag, raw } of changedTags(before, after))
+    if (tag === "PiiText" && /\bkind\s*=\s*\{?["']?(?:name|email|phone)/.test(raw) && !/\bself\b/.test(raw))
+      notes.push("PiiText shows a person without `self`: if this can be the viewer pass `self={isSelf}`");
+  if (PERSON_FIELD.test(changedLines(withoutTags(before), withoutTags(after)).join("\n"))) notes.push("a person's name, email or phone is rendered without PiiText");
+  if (MASKING.test(changedLines(before, after).join("\n"))) notes.push("the page masks a value itself (a page never masks or reveals; PiiText does)");
+  if (!notes.length) return [];
+  return [`nodii-dev nudge: ${notes.join("; ")}. Ask: is this the viewer? Self is never masked (R5, D967, U05-25); every other person goes through PiiText.`];
+}
+
+/** `when` values of a Drizzle journal, in file order. */
+const journalWhens = (text) => (JSON.parse(text).entries ?? []).map((entry) => entry.when);
+
+/** A new migration, or a journal edit that breaks the `when` rule. */
+export async function migrationNudges({ path, rel, existed, after }, knowledge) {
+  const notes = [];
+  if (/(?:^|\/)(?:migrations|drizzle)\/(?:.*\/)?[^/]+\.sql$/.test(rel) && !existed) {
+    const covered = (knowledge.deltaGathered ?? []).map((item) => cleanPath(item).replace(/\/$/, ""));
+    if (!covered.some((item) => rel === item || rel.startsWith(`${item}/`))) {
+      let newest = "";
+      try { const whens = journalWhens(await optional(resolve(dirname(path), "meta/_journal.json")) ?? "{}"); if (whens.length) newest = ` (the journal's newest is ${Math.max(...whens)}, so the next \`when\` is ${Math.max(...whens) + 1})`; } catch {}
+      notes.push(`${rel} is a new migration. Its journal entry needs when = max(existing when) + 1${newest} with idx and tag strictly increasing (never drizzle-kit's now()); then run \`nodii-dev lane gather --delta\` (scope drift)`);
+    }
+  }
+  if (/(?:^|\/)meta\/_journal\.json$/.test(rel)) {
+    try {
+      const whens = journalWhens(after);
+      const bad = whens.findIndex((when, at) => at > 0 && !(when > whens[at - 1]));
+      if (bad !== -1) notes.push(`${rel}: journal entry ${bad} has when ${whens[bad]}, not above the one before (${whens[bad - 1]}); Drizzle silently skips a migration whose when is not newer`);
+    } catch {}
+  }
+  return notes.map((note) => `nodii-dev nudge: ${note}.`);
+}
+
+const NODE_ID_TOOLS = /(?:get_design_context|get_metadata|get_screenshot|get_variable_defs|get_motion_context)$/;
+
+/** A code lane reading Figma by node id (MW8-20). */
+export function figmaReadNudges(payload, lane) {
+  const name = payload.tool_name ?? "";
+  if (!isFigmaTool(name) || !isReadTool(name) || !NODE_ID_TOOLS.test(name)) return [];
+  if (/figma|design/i.test(`${lane.kind ?? ""} ${lane.side ?? ""}`)) return [];
+  const input = payload.tool_input ?? {};
+  const byUrl = typeof input.url === "string" && /[?&]node-id=/.test(input.url);
+  if (!(typeof input.nodeId === "string" || typeof input.node_id === "string" || byUrl)) return [];
+  return ["nodii-dev nudge: this code lane reads Figma by node id. Find the surface by its published component-set key (`figma:keys:refresh`), never a node id; a node id is not a stable reference across hops (MW8-20, MW8-17)."];
+}
+
+const SUBMIT_COMMAND = /(?:nodii-dev|@nodii\/dev(?:@\S+)?)\s+figma\s+submit\b([^;&|\n]*)/;
+const CHECKED_COMMAND = /(?:nodii-dev|@nodii\/dev(?:@\S+)?)\s+figma\s+checked\s+(CS-[\w-]+)([^;&|\n]*)/g;
+
+/** `nodii-dev figma submit CS-n`: the hand checks Dev's gate cannot see. */
+export async function submitNudges(command, { cwd }) {
+  const text = String(command ?? "");
+  const submit = SUBMIT_COMMAND.exec(text);
+  const changeSet = /\b(CS-[\w-]+)/.exec(submit?.[1] ?? "")?.[1];
+  if (!changeSet) return [];
+  const done = { ...(await readPrivateJson(cwd, SUBMIT_CHECKS))[changeSet] };
+  // The same command line may record them first: `figma checked CS-n … && figma submit CS-n …`.
+  for (const [, id, flags] of text.matchAll(CHECKED_COMMAND)) if (id === changeSet) for (const check of SUBMIT_CHECK_FLAGS) if (flags.includes(`--${check}`)) done[check] = true;
+  const label = { "unused-properties": "every component property is used (F-34)", "stale-placeholders": 'every "Blocked on DS: <part>" placeholder is re-checked against the published library (CS-2453)', "dialog-body": "a Dialog with no body is an AlertDialog" };
+  const missing = SUBMIT_CHECK_FLAGS.filter((check) => !done[check]);
+  if (!missing.length) return [];
+  return [`nodii-dev nudge: before submitting ${changeSet}, check that ${missing.map((check) => label[check]).join("; ")}. Then record it: \`nodii-dev figma checked ${changeSet} ${missing.map((check) => `--${check}`).join(" ")}\` (DEC-0034 hand check).`];
+}
+
+/** AskUserQuestion: the ask also lives as an item in open.md (R7). */
+export async function askNudges(payload, { root }) {
+  if (payload.tool_name !== "AskUserQuestion") return [];
+  const questions = (payload.tool_input?.questions ?? []).map((item) => String(item?.question ?? "")).filter(Boolean);
+  const openMd = (await optional(resolve(root, OPEN_MD)))?.toLowerCase().replace(/\s+/g, " ");
+  const unrecorded = questions.filter((question) => !openMd?.includes(question.toLowerCase().replace(/\s+/g, " ").slice(0, 60)));
+  if (questions.length && !unrecorded.length) return [];
+  return [`nodii-dev nudge: a question for the operator is also an item in ${OPEN_MD} (R7), with its Q section; chat alone is not where an ask lives. Add it, and say "item #n in open.md" here.`];
+}
+
+const SIGNALS = /@cognion-nucleus|PiiText|\bmask\w*\(|\b[A-Za-z]\*{3,}|\.(?:email|phone|mobile|displayName|fullName|firstName|lastName|personName)\b/;
+
+/** Whether any nudge could apply to this call, so most calls never resolve the lane. */
+export async function nudgeCandidate(payload) {
+  const tool = payload.tool_name ?? "";
+  if (isFigmaTool(tool)) return isReadTool(tool) && NODE_ID_TOOLS.test(tool);
+  if (tool === "AskUserQuestion") return true;
+  if (SHELL_TOOLS.has(tool)) return /\bfigma\s+submit\b/.test(String(payload.tool_input?.command ?? ""));
+  if (!EDIT_TOOLS.has(tool)) return false;
+  const cwd = payload.cwd ?? process.cwd();
+  return (await editedFiles(payload, cwd)).some(({ path, before, after }) => {
+    const p = cleanPath(path);
+    if (/\.sql$|_journal\.json$|product-pages\/|design-system\/src\/components\//.test(p)) return true;
+    if (!uiFile(p)) return false;
+    return SIGNALS.test(changedLines(before, after).join("\n")) || (changedTags(before, after).length > 0 && SIGNALS.test(after));
+  });
+}
+
+/** PreToolUse nudges for one tool call. Returns [] outside a lane. */
+export async function nudgePre(payload, context, { knowledge = laneKnowledge } = {}) {
+  const lane = context?.lane;
+  if (!lane) return [];
+  const tool = payload.tool_name ?? "";
+  const root = context.root;
+  const cwd = payload.cwd ?? context.cwd ?? root;
+  if (isFigmaTool(tool)) return figmaReadNudges(payload, lane);
+  if (tool === "AskUserQuestion") return askNudges(payload, { root });
+  if (SHELL_TOOLS.has(tool)) return submitNudges(payload.tool_input?.command, { cwd });
+  if (!EDIT_TOOLS.has(tool)) return [];
+  const known = await knowledge(cwd);
+  const out = [];
+  for (const file of await editedFiles(payload, cwd)) {
+    const edit = { ...file, rel: cleanPath(relative(root, file.path)) };
+    out.push(...guidelineNudges(edit, known), ...restyleNudges(edit), ...selfPiiNudges(edit), ...(await migrationNudges(edit, known)));
+  }
+  return out;
+}
+
+// ─── Stop ──────────────────────────────────────────────────────────────────
+
+// A claim that the work is finished, judged a sentence at a time so "the docs are not done" cannot hide "it is done".
+const DONE_CLAIM = /\b(?:all|everything|work|lane|task|ticket|issue|build|it|this|that|i'm|we're|i am|we are)\s*(?:is|are|'s|'m|'re)?\s*(?:now\s+)?(?:done|complete[d]?|finished)\b|^\W*(?:done|all done|complete)\b/i;
+const SHOUTED_DONE = /\bDONE\b/;
+const NOT_DONE = /\b(?:not|isn't|aren't|wasn't|never|until|nothing is|n't)\s+(?:yet\s+)?(?:done|complete[d]?|finished)\b|\b(?:unfinished|incomplete)\b/i;
+const claimsDone = (text) => String(text).split(/(?<=[.!?\n])\s+/).some((sentence) => (DONE_CLAIM.test(sentence) || SHOUTED_DONE.test(sentence)) && !NOT_DONE.test(sentence));
+const COULDNT = /\b(?:I|we)\s+(?:couldn't|could not|can't|cannot|was unable to|were unable to|wasn't able to|am unable to)\b/i;
+const FILED = /\b[A-Z][A-Z0-9]+(?:-[A-Z0-9]+)*-\d+\b|\bfiled\b|\bissue\s+#?\d+|\bopen\.md\b/;
+
+/** The last assistant message: the Stop payload's own, else the transcript's final one. */
+export async function lastAssistantText(payload) {
+  if (typeof payload.last_assistant_message === "string") return payload.last_assistant_message;
+  if (!payload.transcript_path) return "";
+  try {
+    const lines = String(await optional(payload.transcript_path) ?? "").trim().split("\n");
+    for (const line of lines.reverse()) {
+      const entry = JSON.parse(line);
+      if ((entry.type ?? entry.message?.role) !== "assistant") continue;
+      const content = entry.message?.content;
+      const text = Array.isArray(content) ? content.filter((part) => part?.type === "text").map((part) => part.text).join("\n") : String(content ?? "");
+      if (text.trim()) return text;
+    }
+  } catch {}
+  return "";
+}
+
+const openUnconfirmed = (lane) => [lane.freeze?.unconfirmed, lane.unconfirmed].flat().filter(Boolean).filter((item) =>
+  typeof item === "string" || !(item?.resolvedAt || item?.confirmedAt || ["resolved", "confirmed", "dropped"].includes(item?.status)));
+
+/** Stop nudges. A lane that has just been nudged once is left to stop (stop_hook_active). */
+export async function nudgeStop(payload, context, { lastText = lastAssistantText, status = (root) => git(root, "status", "--porcelain") } = {}) {
+  const lane = context?.lane;
+  if (!lane || payload.stop_hook_active) return [];
+  const notes = [];
+  const text = await lastText(payload);
+  if (claimsDone(text) && lane.status !== "on_dev")
+    notes.push(`${lane.key} reads ${lane.status}, not on_dev: done means merged, deployed and verified live on dev (MW3). Run \`nodii-dev lane show ${lane.key}\`, and say what is left instead of "done"`);
+  if (COULDNT.test(text) && !FILED.test(text))
+    notes.push('you said you couldn\'t do something and cited no filed issue; file it (`nodii-dev issues create`, or a request or drift entry) so it is not lost');
+  const unconfirmed = openUnconfirmed(lane);
+  if (unconfirmed.length)
+    notes.push(`${unconfirmed.length} Unconfirmed item${unconfirmed.length === 1 ? " is" : "s are"} still open in ${lane.key}'s Freeze; confirm or drop each with a reason (\`nodii-dev lane freeze\`)`);
+  const dirty = (await status(context.root).catch(() => "")).split("\n").filter(Boolean);
+  if (dirty.length)
+    notes.push(`${dirty.length} uncommitted path${dirty.length === 1 ? "" : "s"} in ${context.root}: commit in your worktree (push on commit, so a death loses nothing)`);
+  return notes.map((note) => `nodii-dev nudge: ${note}.`);
+}
+
+export const nudgeSettingsSnippet = () => ({
+  hooks: {
+    PreToolUse: [{ matcher: "^(AskUserQuestion|mcp__(?:figma|claude_ai_Figma|figma-dev-mode)__.*|Bash|Edit|Write|MultiEdit|NotebookEdit)$", hooks: [{ type: "command", command: "nodii-dev hook nudge-pre" }] }],
+    Stop: [{ hooks: [{ type: "command", command: "nodii-dev hook nudge-stop" }] }],
+  },
+});

package/dist/setup.js

@@ -3,6 +3,7 @@ import { dirname, join, resolve } from "node:path";
 import { CliError, checkLogin } from "./core.js";
 import { codexHooksFromClaude } from "./harness.js";
 import { regroundingHooksSnippet, safetySettingsSnippet } from "./safety.js";
+import { PICKER_MODEL, setupOllama } from "./gather.js";
 
 export const SKILL_PATH = ".claude/skills/nodii-build-workflow/SKILL.md";
 const START = "<!-- nodii-dev build workflow:start -->";
@@ -118,21 +119,37 @@ export async function setupPlan(root = process.cwd()) {
   return changes;
 }
 
-export async function setupCommand(flags, { root = process.cwd(), authCheck = checkLogin } = {}) {
+export async function setupCommand(flags, { root = process.cwd(), authCheck = checkLogin, pickerSetup = setupOllama } = {}) {
+  if (flags.yes && flags.check) throw new CliError("USAGE", "setup accepts either --yes or --check, not both.", 2);
   const changes = await setupPlan(root);
   let authenticated = true;
   try { await authCheck(); } catch { authenticated = false; }
+  let pickerReady = true;
+  let pickerStatus;
+  try { pickerStatus = await pickerSetup({ check: !flags.yes }); }
+  catch (error) {
+    pickerReady = false;
+    pickerStatus = { code: error?.code ?? "PICKER_UNAVAILABLE", message: error?.message ?? String(error) };
+  }
   if (flags.check) {
-    if (changes.length) throw new CliError("SETUP_DRIFT", `Workflow harness drift: ${changes.map((x) => x.relative).join(", ")}`, 1);
-    return { payload: { ok: true, changed: [], authenticated }, human: authenticated ? "Workflow harness is current." : "Workflow harness is current. Not logged in; run `nodii-dev login`." };
+    const drift = [
+      ...(changes.length ? [`Workflow harness drift: ${changes.map((x) => x.relative).join(", ")}`] : []),
+      ...(!pickerReady ? [`Gather picker: ${pickerStatus.message}`] : []),
+    ];
+    if (drift.length) throw new CliError("SETUP_DRIFT", drift.join("; "), 1);
+    return { payload: { ok: true, changed: [], authenticated, picker: pickerStatus }, human: authenticated ? "Workflow harness and Gather picker are current." : "Workflow harness and Gather picker are current. Not logged in; run `nodii-dev login`." };
   }
   if (!flags.yes) {
-    const preview = changes.length ? changes.map((x) => `${x.before === null ? "+ create" : "~ update"} ${x.relative}`).join("\n") : "No changes.";
-    return { payload: { dryRun: true, changed: changes.map((x) => x.relative), authenticated }, human: `${preview}\n${authenticated ? "Authentication: ready." : "Authentication: not logged in; run `nodii-dev login`."}\nRun \`nodii-dev setup --yes\` to apply.` };
+    const preview = [
+      ...(changes.length ? changes.map((x) => `${x.before === null ? "+ create" : "~ update"} ${x.relative}`) : ["No workflow changes."]),
+      pickerReady ? `Gather picker: ${PICKER_MODEL} is ready.` : `+ install Ollama and pull ${PICKER_MODEL}`,
+    ].join("\n");
+    return { payload: { dryRun: true, changed: [...changes.map((x) => x.relative), ...(!pickerReady ? [`ollama:${PICKER_MODEL}`] : [])], authenticated, picker: pickerStatus }, human: `${preview}\n${authenticated ? "Authentication: ready." : "Authentication: not logged in; run `nodii-dev login`."}\nRun \`nodii-dev setup --yes\` to apply.` };
   }
+  if (!pickerReady) throw new CliError(pickerStatus.code, pickerStatus.message, 1);
   for (const change of changes) {
     await mkdir(dirname(change.path), { recursive: true });
     await writeFile(change.path, change.content);
   }
-  return { payload: { applied: true, changed: changes.map((x) => x.relative), authenticated }, human: `${changes.length ? `Applied: ${changes.map((x) => x.relative).join(", ")}` : "Workflow harness already current."}\n${authenticated ? "Authentication: ready." : "Not logged in; run `nodii-dev login`."}` };
+  return { payload: { applied: true, changed: [...changes.map((x) => x.relative), ...(pickerStatus.changed ?? []).map((x) => `ollama:${x}`)], authenticated, picker: pickerStatus }, human: `${changes.length ? `Applied: ${changes.map((x) => x.relative).join(", ")}` : "Workflow harness already current."}\nGather picker: ${PICKER_MODEL} ready on Ollama ${pickerStatus.version}.\n${authenticated ? "Authentication: ready." : "Not logged in; run `nodii-dev login`."}` };
 }

package/dist/starting.js

@@ -4,12 +4,26 @@ import { setTimeout as delay } from "node:timers/promises";
 import { basename, dirname, isAbsolute, join, resolve } from "node:path";
 import { promisify } from "node:util";
 import { CliError, configPath, devRequest, encode, query, readConfig, requireFlag } from "./core.js";
-import { nextCommand } from "./lanes.js";
+import { GATHER_TIMEOUT_MS } from "./gather.js";
+import { laneCommand, nextCommand } from "./lanes.js";
 
 const execFile = promisify(execFileCallback);
 const via = { via: "nodii-dev" };
 const values = (value) => value === undefined ? [] : Array.isArray(value) ? value : [value];
 
+const withSignal = (promise, signal) => {
+  if (!signal) return promise;
+  if (signal.aborted) return Promise.reject(signal.reason ?? new Error("aborted"));
+  return new Promise((resolvePromise, rejectPromise) => {
+    const abort = () => rejectPromise(signal.reason ?? new Error("aborted"));
+    signal.addEventListener("abort", abort, { once: true });
+    Promise.resolve(promise).then(
+      (value) => { signal.removeEventListener("abort", abort); resolvePromise(value); },
+      (error) => { signal.removeEventListener("abort", abort); rejectPromise(error); },
+    );
+  });
+};
+
 function pairs(value, flag) {
   const out = new Map();
   for (const raw of values(value)) {
@@ -380,27 +394,42 @@ export async function amendmentGuard(argv, { request = devRequest, marker = curr
   throw new CliError("LANE_AMENDMENT_ACK_REQUIRED", `Lane ${lane.laneKey} changed:\n${detail}\nDelta gather required: run nodii-dev lane gather ${lane.laneKey} --delta.`, 1, { amendments: pending.data });
 }
 
-export async function gatherLaneCommand(key, flags, { request = devRequest, marker = currentMarker, gather = nextCommand } = {}) {
-  const lane = await marker();
-  key ??= lane?.laneKey;
-  if (!key) throw new CliError("USAGE", "lane gather needs <key> outside a launched lane worktree.", 2);
-  if (!flags.delta) return gather(key, flags, { request });
-  if (!lane || lane.laneKey !== key) throw new CliError("LANE_RUN_REQUIRED", "Delta gather must run inside this lane's registered worktree.", 1);
-  const pending = await request("GET", `/api/v1/lanes/${encode(key)}/amendments${query({ runId: lane.runId })}`);
-  if (!pending.data.length) {
-    const gathered = await gather(key, flags, { request });
-    return { ...gathered, human: `${typeof gathered.human === "string" ? gathered.human : "Gather complete."}\nNo pending amendments.` };
+const runGather = (key, flags, { request, signal }) => laneCommand("gather", [key], flags, { request, gatherSignal: signal });
+
+export async function gatherLaneCommand(key, flags, { request = devRequest, marker = currentMarker, gather = runGather, acknowledge = nextCommand, gatherTimeoutMs = GATHER_TIMEOUT_MS } = {}) {
+  const controller = new AbortController();
+  const deadline = setTimeout(() => controller.abort(), gatherTimeoutMs);
+  const signal = controller.signal;
+  const timedRequest = (method, path, body, options = {}) => withSignal(request(method, path, body, { ...options, signal }), signal);
+  try {
+    const lane = await withSignal(marker(), signal);
+    key ??= lane?.laneKey;
+    if (!key) throw new CliError("USAGE", "lane gather needs <key> outside a launched lane worktree.", 2);
+    if (!flags.delta) return await withSignal(gather(key, flags, { request: timedRequest, signal }), signal);
+    if (lane && lane.laneKey !== key) throw new CliError("LANE_RUN_REQUIRED", "Delta gather for another lane cannot run inside this lane's registered worktree.", 1);
+    if (!lane) return await withSignal(gather(key, flags, { request: timedRequest, signal }), signal);
+    const pending = await timedRequest("GET", `/api/v1/lanes/${encode(key)}/amendments${query({ runId: lane.runId })}`);
+    if (!pending.data.length) {
+      const gathered = await withSignal(gather(key, flags, { request: timedRequest, signal }), signal);
+      return { ...gathered, human: `${typeof gathered.human === "string" ? gathered.human : "Gather complete."}\nNo pending amendments.` };
+    }
+    const version = Math.max(...pending.data.map((item) => item.version));
+    const gathered = await withSignal(gather(key, flags, { request: timedRequest, signal }), signal);
+    const acknowledgement = await withSignal(acknowledge(key, {
+      ...flags,
+      deltaContext: { runId: lane.runId, amendmentVersion: version },
+    }, { request: timedRequest }), signal);
+    const acknowledgedVersion = acknowledgement.payload?.rules?.amendmentAcknowledgement?.version;
+    if (acknowledgedVersion !== version)
+      throw new CliError("LANE_AMENDMENT_ACK_FAILED", `Delta gather did not acknowledge amendment version ${version}; the lane remains blocked.`, 1);
+    return {
+      payload: { ...gathered.payload, rules: acknowledgement.payload?.rules, amendments: pending.data, acknowledgedVersion },
+      human: `${pending.data.map((item) => `v${item.version} ${item.reason}: ${JSON.stringify(item.change)}`).join("\n")}\n${typeof gathered.human === "string" ? gathered.human : "Gather complete."}\nAcknowledged amendment version ${version}.`,
+    };
+  } catch (error) {
+    if (signal.aborted) throw new CliError("GATHER_TIMEOUT", `Gather exceeded its ${Math.round(gatherTimeoutMs / 1000)}-second deadline; nothing was retried.`, 1);
+    throw error;
+  } finally {
+    clearTimeout(deadline);
   }
-  const version = Math.max(...pending.data.map((item) => item.version));
-  const gathered = await gather(key, {
-    ...flags,
-    deltaContext: { runId: lane.runId, amendmentVersion: version },
-  }, { request });
-  const acknowledgedVersion = gathered.payload?.rules?.amendmentAcknowledgement?.version;
-  if (acknowledgedVersion !== version)
-    throw new CliError("LANE_AMENDMENT_ACK_FAILED", `Delta gather did not acknowledge amendment version ${version}; the lane remains blocked.`, 1);
-  return {
-    payload: { ...gathered.payload, amendments: pending.data, acknowledgedVersion },
-    human: `${pending.data.map((item) => `v${item.version} ${item.reason}: ${JSON.stringify(item.change)}`).join("\n")}\n${typeof gathered.human === "string" ? gathered.human : "Gather complete."}\nAcknowledged amendment version ${version}.`,
-  };
 }

package/dist/upload.js

@@ -8,6 +8,7 @@ import { join, relative, resolve } from "node:path";
 import { setTimeout as sleep } from "node:timers/promises";
 import { CliError, devRequest, devTextRequest, encode, query } from "./core.js";
 import { CHANGE_CLASSES, validateDocument } from "./docs.js";
+import { rulesFindText } from "./gather.js";
 
 /** Exit code when Dev is waiting on the operator to acknowledge parked items. */
 export const EXIT_PARKED = 4;
@@ -307,6 +308,15 @@ const pad = (v, n) => String(v).padStart(n);
  * core, the delivery report, and the operator's core token cap.
  */
 export async function rulesCommand(action, args, flags, { request = devRequest } = {}) {
+  if (action === "find") {
+    const question = args.join(" ").trim();
+    if (!question) throw new CliError("USAGE", 'rules find needs a question, for example: nodii-dev rules find "may this route use offset paging?"', 2);
+    if (question.length > 20_000) throw new CliError("USAGE", "rules find questions are at most 20,000 characters", 2);
+    const limit = flags.limit === undefined ? 10 : Number(flags.limit);
+    if (!Number.isInteger(limit) || limit < 1 || limit > 100) throw new CliError("USAGE", "rules find --limit needs a whole number from 1 to 100", 2);
+    const payload = await request("GET", `/api/v1/rules/find${query({ question, limit })}`);
+    return { payload, human: rulesFindText };
+  }
   if (action === "core") {
     // Dev refuses a core over the cap with CORE_OVER_CAP; that error is the output.
     const payload = await request("GET", "/api/v1/rules/core");
@@ -337,5 +347,5 @@ export async function rulesCommand(action, args, flags, { request = devRequest }
     const payload = await request("PUT", "/api/v1/rules/core/cap", { cap });
     return { payload, human: (p) => `Core cap: ${p.data.previous} -> ${p.data.cap} tokens.` };
   }
-  throw new CliError("USAGE", "rules core | rules report [--section rulebook|services|all] [--lane KEY] | rules cap TOKENS", 2);
+  throw new CliError("USAGE", 'rules find "QUESTION" [--limit N] | rules core | rules report [--section rulebook|services|all] [--lane KEY] | rules cap TOKENS', 2);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nodii/dev",
-  "version": "0.6.29",
+  "version": "0.6.31",
   "description": "Agent CLI for Nodii Dev, reached through the platform edge",
   "type": "module",
   "bin": {