@nodii/dev 0.6.29 → 0.6.31

package/README.md

@@ -87,7 +87,7 @@ nodii-dev login [--no-browser] [--scope KEYS] [--force]
 nodii-dev logout
 nodii-dev whoami                   # OAuth identity plus the registered agent
 nodii-dev config show
-nodii-dev doctor [--figma-file KEY] [--json]   # preflight: everything a lane needs, read-only
+nodii-dev doctor [--figma-file KEY] [--json]   # preflight: Dev, hooks, local Ollama + Gather model, optional Figma
 
 nodii-dev api list [--tag TAG] [--json]
 nodii-dev api OPERATION_ID [--param name=value ...] [--body @file|-|JSON]
@@ -129,6 +129,15 @@ nodii-dev decisions get D123
 nodii-dev decisions search WORDS
 nodii-dev decisions create|lock|supersede|amend
 
+nodii-dev lane gather [KEY] [--delta] [--objective TEXT] [--done-check TEXT]
+                        [--paths A,B] [--components K,L]
+nodii-dev lane freeze add KEY --section SECTION --file ITEM.json --reason TEXT
+nodii-dev lane freeze drop KEY --section SECTION --item ID --reason TEXT
+nodii-dev lane freeze swap KEY --section SECTION [--item ID] --file VALUE.json --reason TEXT
+nodii-dev lane freeze show KEY
+nodii-dev lane freeze history KEY
+nodii-dev rules find "QUESTION" [--limit N]
+
 nodii-dev open-questions list|show|answer
 nodii-dev feature-docs list|show|claim|release|status
 nodii-dev contracts grpc|rest|outbox|saga|table publish|status
@@ -304,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
@@ -420,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
@@ -764,6 +808,13 @@ call until `lane gather --delta` serves the current rules and acknowledges the
 newest displayed version. `NODII_DEV_RUN_ID` makes this check per subagent run,
 so one child cannot acknowledge for its siblings.
 
+Gather also persists the lane's bounded Freeze: the objective and done check,
+strict repository/Figma boundaries, the current pinned clauses, and the lane's
+lookups, decisions, and unconfirmed questions. Ordinary CLI calls print and
+acknowledge a changed Freeze before continuing, and compact SessionStart uses
+the same backstop. `lane freeze add|drop|swap` makes a reasoned, version-checked
+change; `show|history` reads the current contract or its append-only history.
+
 `lane start` creates and starts a lane. It infers the repository (by short
 name, as Dev compares it), branch and worktree from git unless overridden, and resolves `--issue` keys to the UUIDs
 required by Dev. Lane keys are passed directly to every lane and Built

package/dist/cli.js

@@ -23,9 +23,11 @@ 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";
 import {
   figmaChangeSetShow,
   figmaChangeSetText,
@@ -95,8 +97,8 @@ Usage: nodii-dev <command> [options] [--json]
   login [--force] | logout | whoami | config show
                                         # login says so when the machine is already signed in; --force
                                         # replaces that one sign-in (never from a lane)
-  doctor [--figma-file KEY] [--json]    # preflight: sign-in, agent, permissions, machine, repo, lane slots
-                                        # and, given a key (or NODII_DEV_FIGMA_FILE), that Figma file's registration
+  doctor [--figma-file KEY] [--json]    # preflight: sign-in, agent, permissions, machine, repo, lane slots,
+                                        # local Ollama + pinned Gather model, and optional Figma registration
   agent register --name NAME | agent heartbeat
   issues list|show|create|update|claim|release
   issues comment ISSUE --body TEXT      # or --body-file FILE; issues update --comment TEXT|--comment-file FILE adds one too
@@ -125,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
@@ -134,8 +137,8 @@ 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
-  setup [--yes|--check]                 # dry-run by default
+  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
   harness check                         # 0 current, 1 differs from Dev, 2 not installed
@@ -150,6 +153,7 @@ Usage: nodii-dev <command> [options] [--json]
   rulebook list|show CODE [--version V]|diff CODE
   rules core                            # the generated core (M05-33); refused over the cap
   rules report [--section S] [--lane KEY]   # delivery totals per document; rules served per lane
+  rules find "QUESTION" [--limit N]         # answer an ad-hoc rules question from the indexed sections
   rules cap TOKENS                      # operator: set the core token cap (default 3000)
 
   coordinator start --machine NAME       # register this machine's one watched coordinator; refuses a live second
@@ -162,7 +166,8 @@ 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]         # infers a launched worktree; Delta required after an amendment
+  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,
                                         # heartbeats, and records exit code + redacted log tail
@@ -175,12 +180,18 @@ Usage: nodii-dev <command> [options] [--json]
   lane heartbeat|resume|land|verify|prioritize|deprioritize|stop <key>
   lane review <key> --file REVIEW.json  # base/head, outcome and clause-cited findings
   lane reviews <key>                    # stored review history for the lane
+  lane freeze add <key> --section SECTION --file ITEM.json --reason TEXT
+  lane freeze drop <key> --section SECTION --item ID --reason TEXT
+  lane freeze swap <key> --section SECTION [--item ID] --file VALUE.json --reason TEXT
+  lane freeze show|history <key>         # durable compact-safe contract and all versions
   lane non-issue <key> --reason TEXT --evidence TEXT --reroute KEY[,KEY]|none
                  --branch carried:KEY|dropped[:REASON] [--commits SHA[,SHA]]
                                         # DEC-0011: terminal non_issue; issue -> wont_do; slot frees
   lane list [--kind KIND] [--status STATUS] [--mine] [--cursor CURSOR]
   lane show <key> | next <key> [--paths A,B] [--components K,L] [--role R]
                                         # next step, plus the rules Dev serves for it (DEC-0020)
+  lane gather [key] [--delta] [--paths A,B] [--components K,L]
+                                        # local document pick; prints Lane contract then Clause map
   built list | built ack <key...>
   machine list|show|set-coordinator|assign|report
   agent lane-limit|grant|revoke
@@ -435,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" });
   }
@@ -556,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") {
@@ -573,7 +591,15 @@ 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));
   if (command === "next") return emitCommand(await nextCommand(action, f));
   if (command === "built") return emitCommand(await builtCommand(action, rest, f));
@@ -805,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)) {
@@ -910,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.29";
+export const VERSION = "0.6.31";
 export const configPath = () =>
   process.env.NODII_DEV_CONFIG_PATH ??
   join(homedir(), ".config/nodii-dev/config.json");
@@ -119,9 +119,30 @@ const staleCode = (raw) => {
   }
 };
 
-async function devFetch(method, path, bodyText, contentType, accept, extra = {}) {
-  const config = await readConfig();
-  const auth = await authProvider();
+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); },
+    );
+  });
+};
+
+async function devFetch(method, path, bodyText, contentType, accept, extra = {}, signal) {
+  const wait = async (promise) => {
+    try {
+      return await withSignal(promise, signal);
+    } catch (error) {
+      if (signal?.aborted) throw new CliError("DEV_TIMEOUT", `Dev request timed out: ${method} ${path}`, 1);
+      throw error;
+    }
+  };
+  const config = await wait(readConfig());
+  const auth = await wait(authProvider());
   const url = requestUrl(config, path);
   // The edge refuses a token minted before the principal's claims epoch with
   // 401 token_stale (refresh and retry once). The request never reached Dev,
@@ -132,26 +153,28 @@ async function devFetch(method, path, bodyText, contentType, accept, extra = {})
   for (;;) {
     const headers = { accept, ...extra };
     if (bodyText !== undefined) headers["content-type"] = contentType;
-    Object.assign(headers, await auth.headers({ method, path, body: bodyText ?? "" }));
+    Object.assign(headers, await wait(auth.headers({ method, path, body: bodyText ?? "" })));
     let response;
     try {
-      response = await fetch(url, { method, headers, body: bodyText });
+      response = await wait(fetch(url, { method, headers, body: bodyText, signal }));
     } catch (error) {
+      if (error?.code === "DEV_TIMEOUT") throw error;
+      if (signal?.aborted) throw new CliError("DEV_TIMEOUT", `Dev request timed out: ${method} ${path}`, 1);
       throw new CliError("DEV_UNREACHABLE", `Cannot reach Dev at ${new URL(url).origin}: ${error.message}`);
     }
-    const raw = await response.text();
+    const raw = await wait(response.text());
     if (response.status !== 401 || typeof auth.refreshStale !== "function" || !staleCode(raw)) return { response, raw };
     if (refreshed) return { response, raw };
     // A cached token that is stale too is not adopted twice: the next one is refreshed.
     const used = String(headers.authorization ?? "").replace(/^Bearer /, "");
-    if ((await auth.refreshStale(used, { force: adopted })) === "refreshed") refreshed = true;
+    if ((await wait(auth.refreshStale(used, { force: adopted }))) === "refreshed") refreshed = true;
     else adopted = true;
   }
 }
 
 /** A JSON call that keeps the status: `{ status, payload }`. Errors throw as devRawRequest's do. */
-export async function devExchange(method, path, bodyText, { contentType = "application/json", headers = {} } = {}) {
-  const { response, raw } = await devFetch(method, path, bodyText, contentType, "application/json", headers);
+export async function devExchange(method, path, bodyText, { contentType = "application/json", headers = {}, signal } = {}) {
+  const { response, raw } = await devFetch(method, path, bodyText, contentType, "application/json", headers, signal);
   let payload;
   try {
     payload = raw ? JSON.parse(raw) : {};
@@ -168,8 +191,8 @@ export async function devExchange(method, path, bodyText, { contentType = "appli
   return { status: response.status, payload };
 }
 
-export async function devRawRequest(method, path, bodyText, contentType = "application/json") {
-  return (await devExchange(method, path, bodyText, { contentType })).payload;
+export async function devRawRequest(method, path, bodyText, contentType = "application/json", options = {}) {
+  return (await devExchange(method, path, bodyText, { ...options, contentType })).payload;
 }
 
 /** A Dev route that answers with text (e.g. a document body as text/markdown). Errors are Dev's JSON. */
@@ -181,8 +204,8 @@ export async function devTextRequest(method, path) {
   throw new CliError(payload.code ?? `HTTP_${response.status}`, payload.message ?? `Dev returned HTTP ${response.status}`, 1, payload.details);
 }
 
-export const devRequest = (method, path, body) =>
-  devRawRequest(method, path, body === undefined ? undefined : JSON.stringify(body));
+export const devRequest = (method, path, body, options) =>
+  devRawRequest(method, path, body === undefined ? undefined : JSON.stringify(body), "application/json", options);
 
 /** A JSON call sent with `Prefer: respond-async` (RFC 7240): `{ status, payload }`, 202 when Dev took it as a job. */
 export const devAsyncRequest = async (method, path, body) =>