@nodii/dev 0.6.30 → 0.6.31

package/README.md

@@ -313,6 +313,9 @@ nodii-dev hook claude-figma-pre       # reads Claude Code hook JSON on stdin
 nodii-dev hook claude-figma-post      # reads Claude Code hook JSON on stdin
 nodii-dev hook safety-pre             # silent safety decision; blocks with exit 2
 nodii-dev hook safety-post            # silently records resources created by successful commands
+nodii-dev hook nudge-pre              # guideline nudges before a tool call; never blocks
+nodii-dev hook nudge-stop             # guideline nudges when a lane session stops; asks once
+nodii-dev figma checked CS-n --unused-properties --stale-placeholders --dialog-body
 nodii-dev hook print-settings         # prints managed-settings JSON; writes nothing
 
 nodii-dev lane start KEY --title TEXT --kind dev_fix|new_build|docs_change|uat_fix|prod_fix
@@ -429,6 +432,38 @@ deploy. A coordinator's exceptional `--no-verify` also requires
 `NODII_DEV_NO_VERIFY_REASON`; the CLI records the reason in private Git
 metadata. Lanes and subagents can never use `--no-verify`.
 
+### Guideline nudges (AGENT-HARNESS-21)
+
+`harness install` and `harness update` add two more `nodii-dev` hooks for
+Claude Code and Codex. A nudge reminds a lane of a rule at the moment it is
+about to be broken and **says nothing when the rule is met**. Nudges never
+block a tool call, fail open on any error or unknown payload, and stay silent
+in any session that is not a Dev lane. Each cites the clause it protects.
+
+| Moment | Nudge | Silent when |
+|---|---|---|
+| Edit or write | A DS component or product page is used or edited and its guideline is not in the lane's gathered set (U07-19, DEC-0010) | the guideline is in the gathered set, or was read with `design guideline show` |
+| Edit or write | `className` or `style` on a DS component (U07-19) | the tag is not a DS import, or has neither prop |
+| Edit or write | A new migration: journal `when` = max + 1, then a Delta gather. A `_journal.json` write whose `when` values do not rise | the migration is covered by a Delta gather, or already exists |
+| Edit or write | Code renders a person: `PiiText` without `self`, a raw `.email`/`.phone`/`.displayName`, or the page masks a value itself (R5, U05-25) | `PiiText` carries `self`, or no person is rendered |
+| Figma read | A code lane reads by node id (`get_design_context`, `get_metadata`, `get_screenshot`, ...) instead of the published key (MW8-20) | a Figma lane, or no node id |
+| `figma submit CS-n` | The unused-property, stale `Blocked on DS` placeholder and Dialog-without-body hand checks (F-34, CS-2453) | all three are recorded with `figma checked CS-n --unused-properties --stale-placeholders --dialog-body` |
+| AskUserQuestion | The question is also an item in `docs/figma-ux-drive/qa-with-abhi/open.md` (R7) | open.md already holds the question |
+| Stop | The lane is not `on_dev` but "done" was claimed (MW3); an "I couldn't" with no filed issue; Unconfirmed Freeze items still open; uncommitted work | none of those; a Stop that was already nudged once may stop |
+
+The lane's gathered set is the private Git file `nodii-lane-knowledge.json`:
+`lane gather --components a,b` adds the components it covered to `guidelines`,
+`lane gather --delta` adds the paths it saw (`--paths`, else every path this
+worktree changes against origin/main) to `deltaGathered`, and `design guideline
+show` adds to `guidelinesRead`. A part's guideline is its root's (`dialog`
+covers `dialog-content`). Edits are judged against the file they produce, so
+an Edit or `apply_patch` that only changes an attribute is read in full.
+
+The Stop nudge asks the session to continue once (`decision: block`, skipped
+when `stop_hook_active`); Codex passes it through its managed dispatcher. A
+nudge hook skips the amendment guard and the waiting-results banner, since
+either would corrupt its JSON; it cannot run a Delta gather.
+
 ### DS conformance: `design roles` and `design check` (DEC-0034)
 
 Every UI role names exactly one DS component (MW6-14). Resolve your brief's

package/dist/cli.js

@@ -23,7 +23,8 @@ import {
 import { heartbeatCurrentLane, postHook, postHookFailure, preHook, sessionStartContext, settingsSnippet, workflowSuggestion } from "./hooks.js";
 import { setupCommand } from "./setup.js";
 import { harnessCommand } from "./harness.js";
-import { hookRuntime, recordHookFire, safetyPostHook, safetyPreHook } from "./safety.js";
+import { hookRuntime, recordHookFire, safetyContext, safetyPostHook, safetyPreHook } from "./safety.js";
+import { SUBMIT_CHECK_FLAGS, changedPaths, nudgeCandidate, nudgePre, nudgeStop, recordGathered, recordGuidelineRead, recordSubmitChecks } from "./nudges.js";
 import { doctorCommand } from "./doctor.js";
 import { dispatchManagedHook } from "./managed-hooks.js";
 import { freezeCommand } from "./freeze.js";
@@ -126,6 +127,7 @@ Usage: nodii-dev <command> [options] [--json]
   figma published FILE_KEY|CHANGE_SET --figma-version V   # a file key marks every awaiting set published
   figma check|log-write|submit|apply|abandon|release
   figma submit CHANGE_SET --file SUBMIT.json [--sync]
+  figma checked CHANGE_SET --unused-properties --stale-placeholders --dialog-body   # the hand checks the submit nudge asks for
                                         # submit, resubmit and design check --change-set run as a job in Dev
                                         # and poll it (a large set outlasts the edge's timeout); --sync waits
                                         # on one request instead. A 502/504 is checked against the set, never resent
@@ -135,7 +137,7 @@ Usage: nodii-dev <command> [options] [--json]
   figma changeset show CHANGE_SET       # items, variants, round, decision and comment (with the previous round's)
   figma file add FILE_KEY --name TEXT --kind design-system|surfaces|prototype [--module M]
                                         # register a Figma file in Dev so it can be locked
-  hook claude-figma-pre|claude-figma-post|safety-pre|safety-post|session-start|managed-dispatch|print-settings
+  hook claude-figma-pre|claude-figma-post|safety-pre|safety-post|nudge-pre|nudge-stop|session-start|managed-dispatch|print-settings
   setup [--yes|--check]                 # dry-run by default; installs/checks Ollama and pulls the Gather model
   harness install|update [--include-drafts[=false]] [--adopt PATH,...] [--dry-run] [--system]
                                         # --system stages managed hooks and only prints operator-reviewed sudo commands
@@ -164,7 +166,7 @@ Usage: nodii-dev <command> [options] [--json]
                                         # authoritative preflight, one worktree per repo, watched launch
                                         # uses the provisioned agents/lane-<key>.json Dev identity
   lane amend <key> --objective|--scope|--rules TEXT --reason TEXT
-  lane gather [<key>] [--delta] [--objective TEXT] [--done-check TEXT]
+  lane gather [<key>] [--delta] [--objective TEXT] [--done-check TEXT] [--components a,b] [--paths a,b]
                                         # infers a launched worktree; explicit contract inputs support manual lane start
   run [--kind build|test_run|subagent|deploy] [--name TEXT] -- <command> [args...]
                                         # watched command: registers with NODII_DEV_RUN_ID,
@@ -444,7 +446,9 @@ export async function figmaFileAdd(value, flags, { request = devRequest } = {})
 export async function main(argv = process.argv.slice(2)) {
   // Amendment acknowledgement is a lane-wide backstop, including otherwise
   // local commands such as help and version.
-  if (argv[0] !== "__run-supervisor") {
+  // A nudge hook is fail-open and writes only its own JSON: it cannot run a
+  // Delta gather, and a waiting-results banner would corrupt its output.
+  if (argv[0] !== "__run-supervisor" && !(argv[0] === "hook" && argv[1]?.startsWith("nudge-"))) {
     await amendmentGuard(argv);
     await showWaitingResults({ acknowledge: argv[0] !== "hook" });
   }
@@ -565,7 +569,12 @@ export async function main(argv = process.argv.slice(2)) {
   if (command === "rulebook" && ["list", "show", "diff"].includes(action)) return emitCommand(await rulebookCommand(action, rest, f));
   if (command === "rules") return emitCommand(await rulesCommand(action, rest, f));
   // Guideline change sets: approving or rejecting one is a person's action in Dev.
-  if (command === "design" && action === "guideline") return emitCommand(await guidelineCommand(rest[0], rest.slice(1), f));
+  if (command === "design" && action === "guideline") {
+    const result = await guidelineCommand(rest[0], rest.slice(1), f);
+    // A guideline read in a lane counts toward the lane's gathered set (nudge hooks).
+    if (rest[0] === "show" && rest[1]) await recordGuidelineRead(process.cwd(), rest[1]).catch(() => {});
+    return emitCommand(result);
+  }
   if (command === "design" && action === "changeset") return emitCommand(await changeSetCommand(rest[0], rest.slice(1), f));
   if (command === "design" && action === "roles") return emit(await designRoles(rest), json, designRolesText);
   if (command === "design" && action === "check") {
@@ -582,7 +591,13 @@ export async function main(argv = process.argv.slice(2)) {
   if (command === "coordinator") return emitCommand(await coordinatorCommand(action, f));
   if (command === "lane" && action === "launch") return emitCommand(await launchLaneCommand(rest[0], f));
   if (command === "lane" && action === "amend") return emitCommand(await amendLaneCommand(rest[0], f));
-  if (command === "lane" && action === "gather") return emitCommand(await gatherLaneCommand(rest[0], f));
+  if (command === "lane" && action === "gather") {
+    const result = await gatherLaneCommand(rest[0], f);
+    // What a gather covered is the lane's gathered set for the nudge hooks.
+    const asked = (value) => (typeof value === "string" ? value.split(",").map((item) => item.trim()).filter(Boolean) : []);
+    await (async () => recordGathered(process.cwd(), { guidelines: asked(f.components), deltaGathered: f.delta ? (f.paths ? asked(f.paths) : await changedPaths(process.cwd())) : [] }))().catch(() => {});
+    return emitCommand(result);
+  }
   if (command === "lane" && action === "freeze")
     return emitCommand(await freezeCommand(rest[0], rest.slice(1), f));
   if (command === "lane") return emitCommand(await laneCommand(action, rest, f));
@@ -816,6 +831,13 @@ export async function main(argv = process.argv.slice(2)) {
       if (!result.data.allowed) process.exitCode = 3;
       return;
     }
+    if (action === "checked") {
+      const flagged = SUBMIT_CHECK_FLAGS.filter((check) => f[check]);
+      if (!isChangeSetId(rest[0]) || rest.length > 1 || !flagged.length)
+        throw new CliError("USAGE", `figma checked CHANGE_SET ${SUBMIT_CHECK_FLAGS.map((check) => `--${check}`).join(" ")} (at least one)`, 2);
+      await recordSubmitChecks(process.cwd(), rest[0], flagged);
+      return emit({ data: { changeSetId: rest[0], checked: flagged } }, json, `${rest[0]}: recorded ${flagged.join(", ")}.`);
+    }
     if (action === "log-write")
       return emit(await figmaLogWrite(rest[0], requireFlag(f, "tool"), requireFlag(f, "nodes").split(",").filter(Boolean)), json);
     if (["apply", "published", "abandon"].includes(action)) {
@@ -921,6 +943,27 @@ export async function main(argv = process.argv.slice(2)) {
       } catch {}
       return;
     }
+    // Guideline nudges (AGENT-HARNESS-21) never block: any error, a payload
+    // they don't know or a session outside a lane ends in no output.
+    if (action === "nudge-pre") {
+      try {
+        const payload = JSON.parse(await stdinText());
+        await recordHookFire(payload).catch(() => {});
+        if (!(await nudgeCandidate(payload))) return;
+        const nudges = await nudgePre(payload, await safetyContext(payload.cwd ?? process.cwd()));
+        if (nudges.length) console.log(JSON.stringify({ hookSpecificOutput: { hookEventName: "PreToolUse", additionalContext: nudges.join("\n") } }));
+      } catch {}
+      return;
+    }
+    if (action === "nudge-stop") {
+      try {
+        const payload = JSON.parse(await stdinText());
+        await recordHookFire(payload).catch(() => {});
+        const nudges = await nudgeStop(payload, await safetyContext(payload.cwd ?? process.cwd()));
+        if (nudges.length) console.log(JSON.stringify({ decision: "block", reason: nudges.join("\n") }));
+      } catch {}
+      return;
+    }
     if (action === "lane-heartbeat") {
       const result = await heartbeatCurrentLane();
       return emit(result, json, result.heartbeated ? `Heartbeat recorded for ${result.key}.` : "No current-branch lane; no heartbeat sent.");

package/dist/core.js

@@ -4,7 +4,7 @@ import { chmod, mkdir, readFile, rm, writeFile } from "node:fs/promises";
 import { homedir, platform } from "node:os";
 import { dirname, join } from "node:path";
 
-export const VERSION = "0.6.30";
+export const VERSION = "0.6.31";
 export const configPath = () =>
   process.env.NODII_DEV_CONFIG_PATH ??
   join(homedir(), ".config/nodii-dev/config.json");

package/dist/harness.js

@@ -11,6 +11,7 @@ import { fileURLToPath } from "node:url";
 import { promisify } from "node:util";
 import { CliError, devRequest, query } from "./core.js";
 import { managedHookBundle, nodiiCommandArgs, writeManagedHookBundle } from "./managed-hooks.js";
+import { nudgeSettingsSnippet } from "./nudges.js";
 import { codexSafetyHooksSnippet, regroundingHooksSnippet, safetySettingsSnippet } from "./safety.js";
 
 /** What this CLI wrote, per path: { mode, sha256 }, or for merge-json the hook entries it `added`. */
@@ -198,6 +199,7 @@ export function withSafetyHooks(harness) {
   const parsed = JSON.parse(settings.content);
   let hooks = addHookEntries(parsed.hooks, safetySettingsSnippet().hooks);
   hooks = addHookEntries(hooks, regroundingHooksSnippet().hooks);
+  hooks = addHookEntries(hooks, nudgeSettingsSnippet().hooks);
   assertNodiiHooks(hooks, ".claude/settings.json");
   settings.content = JSON.stringify({ ...parsed, hooks });
   settings.sha256 = sha(settings.content);

package/dist/managed-hooks.js

@@ -135,7 +135,12 @@ export async function dispatchManagedHook(event, payloadText, deps = {}) {
     }
     const structured = messages.map((message) => message.hookSpecificOutput?.additionalContext).filter(Boolean);
     const plain = successful.map((result) => responseOf(result.stdout) ? "" : result.stdout.trim()).filter(Boolean);
-    if (["Stop", "SubagentStop"].includes(event)) return "{}\n";
+    // A Stop nudge asks the session to continue once; any other Stop output is dropped.
+    if (event === "Stop") {
+      const block = messages.find((message) => message.decision === "block" && typeof message.reason === "string");
+      return block ? `${JSON.stringify({ decision: "block", reason: block.reason })}\n` : "{}\n";
+    }
+    if (event === "SubagentStop") return "{}\n";
     return [...structured, ...plain].join("\n") + ([...structured, ...plain].length ? "\n" : "");
   } catch {
     return emptyResponse(event);

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/package.json

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