@nodii/dev 0.3.1 → 0.4.0

package/README.md

@@ -103,8 +103,71 @@ nodii-dev figma release FILE_KEY
 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 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
+                     --side backend|frontend|both [--repo REPO] [--issue ISSUE]
+nodii-dev lane step KEY --side backend|frontend --start|--done|--block STEP
+nodii-dev lane evidence KEY --pr|--commit|--figma|--deploy|--dev-check REF
+nodii-dev lane heartbeat KEY [--note TEXT]
+nodii-dev lane review KEY
+nodii-dev lane land KEY
+nodii-dev lane verify KEY --dev-check REF
+nodii-dev lane list [--kind KIND] [--status STATUS] [--machine UUID]
+                    [--agent UUID|--mine] [--waiting-on SIDE] [--stuck true|false]
+                    [--cursor CURSOR] [--limit N]
+nodii-dev lane show KEY
+nodii-dev lane prioritize|deprioritize KEY --reason TEXT
+nodii-dev lane stop KEY --reason TEXT
+nodii-dev next KEY
+
+nodii-dev built list [--cursor CURSOR] [--include-acknowledged true]
+nodii-dev built ack KEY [KEY ...] [--note TEXT]
+nodii-dev machine list|show
+nodii-dev machine set-coordinator MACHINE AGENT
+nodii-dev machine assign MACHINE AGENT --home-repo REPO
+nodii-dev machine report MACHINE --host-facts JSON --memory-facts JSON --heavy-slot-total N
+nodii-dev agent lane-limit AGENT N
+nodii-dev agent grant|revoke AGENT REPO
+nodii-dev people reveal PERSON --reason TEXT
+nodii-dev people refresh-names
+
+nodii-dev setup                    # preview files that would change
+nodii-dev setup --yes              # merge and write the harness
+nodii-dev setup --check            # exit non-zero when it has drifted
 ```
 
+## Build lanes and repository setup
+
+`lane start` creates and starts a lane. It infers the repository, branch and
+worktree from git unless overridden, and resolves `--issue` keys to the UUIDs
+required by the hub. Lane keys are passed directly to every lane and Built
+acknowledgement route. `next` reads the lane's generated
+API steps and prints the exact next `lane step` command. Server refusals,
+including operator-only actions, workflow blocks, lane limits and Built items
+that are not on dev, retain the hub error code/message and exit non-zero.
+
+`setup` installs the Claude Code workflow harness in the current repository.
+It writes `.claude/skills/nodii-build-workflow/SKILL.md`, merges SessionStart,
+Stop and Bash PostToolUse hooks into `.claude/settings.json`, and maintains one
+marked section in an existing `CLAUDE.md` or `AGENTS.md` (creating `CLAUDE.md`
+when neither exists). Existing settings and hooks are preserved. The default
+is a read-only preview; `--yes` applies, and `--check` is suitable for drift
+checks. Setup also checks `whoami` and prints `nodii-dev login` guidance without
+exposing credential details.
+
+Heartbeat notes are optional and limited by the hub to 500 characters.
+Prioritize and deprioritize require a 1–500 character reason, which the CLI
+sends to the hub. `lane review` records the review gate.
+
+The CLI does not duplicate authorization policy. It sends requests and prints
+the hub's refusal unchanged. Stop, Built acknowledgement, and machine
+create/update/coordinator changes require a staff person login. Machine agent
+assignment is for coordinators; lane-limit and repository-grant changes are for
+the target agent's coordinator or staff. Agent registration does not accept
+machine, role, home-repository, or lane-limit fields. Machine reports may be
+sent by the machine's agent or coordinator. People name reveal requires a
+reason; refreshing the names cache is staff-only.
+
 Every first-class resource command accepts positional path identifiers and
 OpenAPI property names as kebab-case flags. For example:
 
@@ -121,7 +184,7 @@ deploy reports, runtime, people, agents, inbox/gates, design, runbooks,
 doctrine and exceptions, changelog, health verdicts, approval kinds,
 notification registry, skills, questions, decisions, drift, requests,
 pipelines, runners, routing, usage, audit, reconciliation, cron, composite
-surfaces, and service edges. `api list` is the authoritative discovery view;
+surfaces, service edges, lanes, swaps, ideas, and terminology. `api list` is the authoritative discovery view;
 `api OPERATION_ID` makes every operation callable even without an alias.
 
 `figma check` exits `0` when allowed and `3` when denied. The pre-hook permits

package/dist/api.js

@@ -98,7 +98,8 @@ export const GROUPS = {
   "approval-kinds": "ApprovalKinds", "notification-registry": "Notification registry", skills: "Skills", "open-questions": "OpenQuestions",
   decisions: "Decisions", drift: "Drift", requests: "Requests", pipelines: "Pipelines", slices: "Slices", "sql-lookups": "SqlLookups",
   runners: "Runners", routing: "Routing", usage: "Usage", audit: "AuditLog", reconciliation: "Reconciliation", cron: "Cron", health: "Health",
-  composite: "Composite", "service-edges": "ServiceEdges",
+  composite: "Composite", "service-edges": "ServiceEdges", lanes: "Lanes",
+  swaps: "Swaps", ideas: "Ideas", terminology: "Terminology",
 };
 
 export const ALIASES = {
@@ -139,6 +140,9 @@ export const ALIASES = {
   "audit:list": "listAuditLog", "health:show": "getHealth",
   "composite:refresher": "getServiceRefresher", "composite:impact": "getImpact", "composite:search": "search",
   "service-edges:list": "listServiceEdges", "service-edges:show": "getServiceEdgesForService",
+  "swaps:list": "listSwaps", "swaps:show": "getSwap", "swaps:create": "createSwap", "swaps:close": "closeSwap",
+  "ideas:list": "listIdeas", "ideas:show": "getIdea", "ideas:create": "createIdea", "ideas:status": "updateIdeaStatus",
+  "terminology:list": "listTerminology", "terminology:show": "getTerminologyTerm", "terminology:create": "createTerminologyTerm", "terminology:update": "updateTerminologyTerm",
 };
 
 export function findFirstClass(operations, group, action) {

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.3.1";
+export const VERSION = "0.4.0";
 export const DEFAULT_HUB_URL = "https://planning.dev.nucleus-cloud.in";
 export const OPERATOR_AGENT_ID = "00000000-0000-0000-0000-000000000001";
 export const configPath = () =>

package/dist/hooks.js

@@ -1,4 +1,8 @@
 import { CliError, hubRequest } from "./core.js";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+
+const execFileAsync = promisify(execFile);
 
 const FIGMA_PREFIXES = [
   "mcp__figma__",
@@ -151,3 +155,22 @@ export const settingsSnippet = () => ({
     ],
   },
 });
+
+export async function heartbeatCurrentLane(request = hubRequest) {
+  let branch;
+  try { branch = (await execFileAsync("git", ["branch", "--show-current"], { encoding: "utf8" })).stdout.trim(); }
+  catch { return { heartbeated: false, reason: "not a git worktree" }; }
+  if (!branch) return { heartbeated: false, reason: "detached HEAD" };
+  const lanes = (await request("GET", "/api/v1/lanes?limit=200")).data ?? [];
+  const lane = lanes.find((x) => x.branch === branch && !["on_dev", "stopped"].includes(x.status));
+  if (!lane) return { heartbeated: false, reason: "no lane for current branch" };
+  await request("POST", `/api/v1/lanes/${encodeURIComponent(lane.id)}/heartbeat`, { via: "nodii-dev" });
+  return { heartbeated: true, key: lane.key };
+}
+
+export function workflowSuggestion(payload) {
+  const command = payload?.tool_input?.command ?? "";
+  if (/\bgit\s+push\b/.test(command)) return "nodii-dev: pushed work; record it with `nodii-dev lane evidence <key> --commit <sha>` or `--pr <url>`.";
+  if (/\bgh\s+pr\s+merge\b/.test(command)) return "nodii-dev: after the merge, run `nodii-dev lane land <key>`.";
+  return null;
+}

package/dist/lanes.js

@@ -0,0 +1,160 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { CliError, encode, hubRequest, query, readConfig, requireFlag } from "./core.js";
+
+const execFileAsync = promisify(execFile);
+const via = { via: "nodii-dev" };
+
+const need = (value, usage) => {
+  if (!value) throw new CliError("USAGE", usage, 2);
+  return value;
+};
+
+async function git(...args) {
+  try {
+    return (await execFileAsync("git", args, { encoding: "utf8" })).stdout.trim();
+  } catch {
+    throw new CliError("GIT_REQUIRED", "Run this command inside a git worktree, or pass --repo and --branch.", 2);
+  }
+}
+
+export async function inferGitContext() {
+  const worktree = await git("rev-parse", "--show-toplevel");
+  const branch = await git("branch", "--show-current");
+  let repo;
+  try {
+    const remote = await git("remote", "get-url", "origin");
+    repo = remote.replace(/\.git$/, "").replace(/^git@[^:]+:/, "").replace(/^https?:\/\/[^/]+\//, "");
+  } catch {
+    repo = worktree.split("/").filter(Boolean).at(-1);
+  }
+  return { repo, branch: need(branch, "Detached HEAD: pass --branch."), worktree };
+}
+
+const laneLine = (x) => `${x.key}\t${x.status}\t${x.kind}/${x.side}\t${x.title}${x.stuck ? "\tSTUCK" : ""}`;
+const detailText = (x) => [laneLine(x), ...(x.steps ?? []).map((s) => `  ${s.side}\t${s.state}\t${s.stepKey}\t${s.label}`)].join("\n");
+
+function evidence(flags) {
+  const selected = ["pr", "commit", "figma", "deploy", "dev-check"].filter((x) => flags[x] !== undefined);
+  if (selected.length !== 1) throw new CliError("USAGE", "Choose exactly one of --pr, --commit, --figma, --deploy, or --dev-check.", 2);
+  const flag = selected[0];
+  const value = requireFlag(flags, flag);
+  return { kind: flag === "figma" ? "figma_frame" : flag.replace("-", "_"), ...(URL.canParse(value) ? { url: value } : { ref: value }), ...via };
+}
+
+export async function laneCommand(action, args, flags, { request = hubRequest, config = readConfig, gitContext = inferGitContext } = {}) {
+  if (action === "list") {
+    const c = flags.mine ? await config() : null;
+    const payload = await request("GET", `/api/v1/lanes${query({ kind: flags.kind, status: flags.status, machine: flags.machine, agent: flags.mine ? c.agentId : flags.agent, "waiting-on": flags["waiting-on"], stuck: flags.stuck, cursor: flags.cursor, limit: flags.limit })}`);
+    return { payload, human: (p) => p.data.map(laneLine).join("\n") || "No lanes." };
+  }
+  if (action === "start") {
+    const key = need(args[0], "lane start needs <key>");
+    const c = await config();
+    const context = await gitContext();
+    const agent = (await request("GET", `/api/v1/agents/${encode(c.agentId)}`)).data;
+    if (!agent.machineId) throw new CliError("MACHINE_REQUIRED", "The current agent is not assigned to a machine.", 1);
+    let issueIds = [];
+    if (flags.issue) issueIds = [String(flags.issue)].flatMap((x) => x.split(",")).map(String);
+    issueIds = await Promise.all(issueIds.map(async (ref) => (await request("GET", `/api/v1/issues/${encode(ref)}`)).data.id));
+    await request("POST", "/api/v1/lanes", {
+      key, title: requireFlag(flags, "title"), kind: requireFlag(flags, "kind"), side: requireFlag(flags, "side"),
+      repos: [flags.repo ?? context.repo], agentId: c.agentId, machineId: agent.machineId,
+      branch: flags.branch ?? context.branch, worktree: flags.worktree ?? context.worktree, issueIds,
+      ...(flags["step-limit"] ? { stepLimitSeconds: Number(flags["step-limit"]) } : {}), ...via,
+    });
+    const payload = await request("POST", `/api/v1/lanes/${encode(key)}/start`, via);
+    return { payload, human: (p) => `Started ${laneLine(p.data)}` };
+  }
+  const ref = need(args[0], `lane ${action} needs <key>`);
+  const id = ref;
+  if (action === "show") {
+    const payload = await request("GET", `/api/v1/lanes/${encode(id)}`);
+    return { payload, human: (p) => detailText(p.data) };
+  }
+  if (action === "step") {
+    const selected = ["start", "done", "block"].filter((x) => flags[x]);
+    if (selected.length !== 1) throw new CliError("USAGE", "lane step needs exactly one of --start, --done, or --block.", 2);
+    const side = requireFlag(flags, "side");
+    const stepRef = need(flags[selected[0]] === true ? args[1] : flags[selected[0]], "lane step needs <key> --side <side> --start|--done|--block <step>");
+    const lane = (await request("GET", `/api/v1/lanes/${encode(id)}`)).data;
+    const step = lane.steps.find((x) => x.side === side && (x.id === stepRef || x.stepKey === stepRef));
+    if (!step) throw new CliError("STEP_NOT_FOUND", `No ${side} step ${stepRef} on ${ref}.`, 1);
+    const payload = await request("POST", `/api/v1/lanes/${encode(id)}/steps/${encode(step.id)}/${selected[0]}`, via);
+    return { payload, human: `${ref}: ${side}/${step.stepKey} ${selected[0]}` };
+  }
+  if (action === "evidence") {
+    const body = evidence(flags);
+    const payload = await request("POST", `/api/v1/lanes/${encode(id)}/evidence`, body);
+    return { payload, human: `${ref}: recorded ${body.kind} evidence.` };
+  }
+  if (action === "heartbeat") {
+    return { payload: await request("POST", `/api/v1/lanes/${encode(id)}/heartbeat`, { ...(flags.note !== undefined ? { note: flags.note } : {}), ...via }), human: `${ref}: heartbeat recorded.` };
+  }
+  if (action === "land") return { payload: await request("POST", `/api/v1/lanes/${encode(id)}/land`, via), human: `${ref}: recorded on main.` };
+  if (action === "review") return { payload: await request("POST", `/api/v1/lanes/${encode(id)}/review`, via), human: `${ref}: review recorded.` };
+  if (action === "verify") {
+    const value = requireFlag(flags, "dev-check");
+    return { payload: await request("POST", `/api/v1/lanes/${encode(id)}/verify`, { ...(URL.canParse(value) ? { url: value } : { ref: value }), ...via }), human: `${ref}: verified on dev.` };
+  }
+  if (["prioritize", "deprioritize"].includes(action)) {
+    const payload = await request("POST", `/api/v1/lanes/${encode(id)}/${action}`, { reason: requireFlag(flags, "reason"), ...via });
+    return { payload, human: `${ref}: ${action}d.` };
+  }
+  if (action === "stop") return { payload: await request("POST", `/api/v1/lanes/${encode(id)}/stop`, { reason: requireFlag(flags, "reason"), ...via }), human: `${ref}: stopped.` };
+  throw new CliError("USAGE", `Unknown lane action: ${action}`, 2);
+}
+
+export async function nextCommand(ref, flags, { request = hubRequest } = {}) {
+  const lane = (await request("GET", `/api/v1/lanes/${encode(ref)}`)).data;
+  const pending = lane.steps.filter((x) => ["waiting", "current", "blocked"].includes(x.state)).sort((a, b) => a.position - b.position);
+  const steps = ["backend", "frontend"].map((side) => pending.find((x) => x.side === side)).filter(Boolean);
+  const data = steps.map((step) => ({ side: step.side, step: step.stepKey, label: step.label, state: step.state, command: `nodii-dev lane step ${lane.key} --side ${step.side} --${step.state === "current" ? "done" : "start"} ${step.stepKey}` }));
+  return { payload: { data }, human: data.length ? data.map((x) => `${x.side}: ${x.label}\n  ${x.command}`).join("\n") : `All workflow steps are complete. Run: nodii-dev lane land ${lane.key}` };
+}
+
+export async function builtCommand(action, args, flags, { request = hubRequest } = {}) {
+  if (action === "list") {
+    const payload = await request("GET", `/api/v1/built${query({ cursor: flags.cursor, limit: flags.limit, includeAcknowledged: flags["include-acknowledged"] })}`);
+    return { payload, human: (p) => p.data.map(laneLine).join("\n") || "No built lanes awaiting acknowledgement." };
+  }
+  if (action === "ack") {
+    if (!args.length) throw new CliError("USAGE", "built ack needs one or more lane keys", 2);
+    const results = await Promise.all(args.map((ref) => request("POST", `/api/v1/built/${encode(ref)}/acknowledge`, { ...(flags.note !== undefined ? { note: flags.note } : {}), ...via })));
+    return { payload: args.length === 1 ? results[0] : { data: results.map((x) => x.data) }, human: `Acknowledged ${args.join(", ")}.` };
+  }
+  throw new CliError("USAGE", `Unknown built action: ${action}`, 2);
+}
+
+export async function machineCommand(action, args, flags, { request = hubRequest } = {}) {
+  if (action === "list") return { payload: await request("GET", "/api/v1/machines"), human: (p) => p.data.map((x) => `${x.id}\t${x.name}\tcoordinator=${x.coordinatorAgentId}`).join("\n") || "No machines." };
+  const id = need(args[0], `machine ${action} needs <machine>`);
+  if (action === "show") return { payload: await request("GET", `/api/v1/machines/${encode(id)}`) };
+  if (action === "set-coordinator") return { payload: await request("PUT", `/api/v1/machines/${encode(id)}/coordinator`, { agentId: need(args[1] ?? flags.agent, "machine set-coordinator needs <machine> <agent>") }), human: "Coordinator updated." };
+  if (action === "assign") return { payload: await request("POST", `/api/v1/machines/${encode(id)}/agents`, { agentId: need(args[1] ?? flags.agent, "machine assign needs <machine> <agent>"), homeRepo: requireFlag(flags, "home-repo") }), human: "Agent assigned." };
+  if (action === "report") return { payload: await request("POST", `/api/v1/machines/${encode(id)}/report`, { hostFacts: JSON.parse(requireFlag(flags, "host-facts")), memoryFacts: JSON.parse(requireFlag(flags, "memory-facts")), heavySlotTotal: Number(requireFlag(flags, "heavy-slot-total")) }), human: "Machine report recorded." };
+  throw new CliError("USAGE", `Unknown machine action: ${action}`, 2);
+}
+
+export async function peopleCommand(action, args, flags, { request = hubRequest } = {}) {
+  if (action === "reveal") {
+    const id = need(args[0], "people reveal needs <person>");
+    return { payload: await request("POST", `/api/v1/people/${encode(id)}/reveal-name`, { reason: requireFlag(flags, "reason") }), human: (p) => p.data.value ?? p.data.hint ?? "Name unavailable." };
+  }
+  if (action === "refresh-names") return { payload: await request("POST", "/api/v1/people/refresh-names"), human: "People names refreshed." };
+  throw new CliError("USAGE", `Unknown people action: ${action}`, 2);
+}
+
+export async function agentWorkflowCommand(action, args, flags, { request = hubRequest } = {}) {
+  const agent = need(args[0], `agent ${action} needs <agent>`);
+  if (action === "lane-limit") return { payload: await request("PUT", `/api/v1/agents/${encode(agent)}/lane-limit`, { laneLimit: Number(need(args[1], "agent lane-limit needs <agent> <n>")) }), human: "Lane limit updated." };
+  if (action === "grant") return { payload: await request("POST", `/api/v1/agents/${encode(agent)}/repo-grants`, { repo: need(args[1], `agent ${action} needs <agent> <repo>`) }), human: "Repository grant added." };
+  if (action === "revoke") {
+    const repo = need(args[1], "agent revoke needs <agent> <repo>");
+    const grants = (await request("GET", `/api/v1/agents/${encode(agent)}/repo-grants`)).data;
+    const grant = grants.find((x) => x.repo === repo && !x.revokedAt);
+    if (!grant) throw new CliError("REPO_GRANT_NOT_FOUND", `No active grant for ${repo}.`, 1);
+    return { payload: await request("POST", `/api/v1/agents/${encode(agent)}/repo-grants/${encode(grant.id)}/revoke`, {}), human: "Repository grant revoked." };
+  }
+  throw new CliError("USAGE", `Unknown agent action: ${action}`, 2);
+}

package/dist/nodii-dev.js

@@ -27,7 +27,8 @@ import {
   deviceLogin,
   revokeOAuth,
 } from "./oauth.js";
-import { postHook, preHook, settingsSnippet } from "./hooks.js";
+import { heartbeatCurrentLane, postHook, preHook, settingsSnippet, workflowSuggestion } from "./hooks.js";
+import { setupCommand } from "./setup.js";
 import {
   ALIASES,
   GROUPS,
@@ -40,6 +41,14 @@ import {
   parseParams,
   readBody,
 } from "./api.js";
+import {
+  agentWorkflowCommand,
+  builtCommand,
+  laneCommand,
+  machineCommand,
+  nextCommand,
+  peopleCommand,
+} from "./lanes.js";
 
 const HELP = `nodii-dev ${VERSION}
 
@@ -54,6 +63,18 @@ Usage: nodii-dev <command> [options] [--json]
   design entries|entry|guide
   figma lock|check|log-write|submit|apply|published|abandon|release
   hook claude-figma-pre|claude-figma-post|print-settings
+  setup [--yes|--check]                 # dry-run by default
+
+  lane start <key> --title TEXT --kind KIND --side SIDE [--repo REPO] [--issue ISSUE]
+  lane step <key> --side SIDE --start|--done|--block <step>
+  lane evidence <key> --pr|--commit|--figma|--deploy|--dev-check REF
+  lane heartbeat|review|land|verify|prioritize|deprioritize|stop <key>
+  lane list [--kind KIND] [--status STATUS] [--mine] [--cursor CURSOR]
+  lane show <key> | next <key>
+  built list | built ack <key...>
+  machine list|show|set-coordinator|assign|report
+  agent lane-limit|grant|revoke
+  people reveal <id> --reason TEXT | people refresh-names
 
   api list [--tag TAG]
   api <operationId> [--param k=v] [--body @file|-|JSON]
@@ -272,6 +293,14 @@ async function main(argv = process.argv.slice(2)) {
     );
     return emit({ data: { ...c, agent: remote.data } }, json);
   }
+  const emitCommand = async (result) => emit(result.payload, json, result.human);
+  if (command === "setup") return emitCommand(await setupCommand(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));
+  if (command === "machine") return emitCommand(await machineCommand(action, rest, f));
+  if (command === "people" && ["reveal", "refresh-names"].includes(action))
+    return emitCommand(await peopleCommand(action, rest, f));
   if (command === "state" && action === "diff") {
     const [health, services, decisions, docs, requests, drift] = await Promise.all([
       hubRequest("GET", "/api/v1/health"), hubRequest("GET", "/api/v1/services"),
@@ -307,6 +336,8 @@ async function main(argv = process.argv.slice(2)) {
       (p) => p.data.map((x) => `${x.serviceId}/${x.docKey}\t${x.claimedByAgentId}`).join("\n") || "No active claims.");
   }
   if (command === "agent") {
+    if (["lane-limit", "grant", "revoke"].includes(action))
+      return emitCommand(await agentWorkflowCommand(action, rest, f));
     const c = await readConfig();
     if (action === "register") {
       const result = await hubRequest("POST", c.authProvider === "oauth" ? "/api/v1/agents/register" : "/api/v1/agents", {
@@ -529,7 +560,16 @@ async function main(argv = process.argv.slice(2)) {
         );
       }
     }
+    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.");
+    }
     const payload = JSON.parse(await stdinText());
+    if (action === "workflow-post") {
+      const suggestion = workflowSuggestion(payload);
+      if (suggestion) console.log(suggestion);
+      return;
+    }
     if (action === "claude-figma-post") {
       try {
         return emit(await postHook(payload), json, "logged");

package/dist/setup.js

@@ -0,0 +1,114 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { CliError, hubRequest } from "./core.js";
+
+export const SKILL_PATH = ".claude/skills/nodii-build-workflow/SKILL.md";
+const START = "<!-- nodii-dev build workflow:start -->";
+const END = "<!-- nodii-dev build workflow:end -->";
+
+export const workflowSkill = `---
+name: nodii-build-workflow
+description: Drive every Nodii build lane through nodii-dev from start to verified-on-dev and Built acknowledgement.
+---
+
+# Nodii build workflow
+
+Use \`nodii-dev\` as the control plane. The canonical policy is \`docs/planning/global/rulebook/build-workflow.md\` §§1–8 (operator rulings A-020/A-021). Never edit hub lane state by another route.
+
+1. Start: \`nodii-dev lane start KEY --title "..." --kind dev_fix|new_build|docs_change|uat_fix|prod_fix --side backend|frontend|both [--issue ISSUE]\`.
+2. Ask \`nodii-dev next KEY\`; start, complete, or block the reported API step with \`nodii-dev lane step\`.
+3. Record durable evidence with \`nodii-dev lane evidence KEY --pr|--commit|--figma|--deploy|--dev-check REF\` and heartbeat long-running work with \`nodii-dev lane heartbeat KEY --note "..."\` (notes are at most 500 characters).
+4. Record the review gate with \`nodii-dev lane review KEY\`. After merge, run \`nodii-dev lane land KEY\`. Done still means deployed and checked live on dev as the right user: \`nodii-dev lane verify KEY --dev-check REF\`.
+5. Use \`nodii-dev lane prioritize|deprioritize KEY --reason "..."\` when priority changes; the reason is required. The lane stays on Built until a staff login runs \`nodii-dev built ack KEY\`. Never treat acknowledgement as testing.
+
+## Steps
+
+- Dev fix, backend: identify/root cause → build and local test → deploy without CI → dev check.
+- Dev fix, frontend: approved Figma (unless the rulebook exception applies) → components → adopt and local test → deploy without CI → dev check.
+- Dev fix, both: run both API step tracks; neither side may be skipped.
+- New build: feature docs alongside Figma concepts → approvals → backend/design-system build → local test → deploy without CI → dev check.
+- Docs change: draft against code → operator review → land on main → publish in the hub.
+- UAT/prod fixes remain blocked until the hub/rulebook enables per-push green CI and promotion by commit.
+
+## Gates and landing
+
+Acquire the repo's heavy slot for heavy work. Run, in order: typecheck → lint and format → scoped touched tests on the real stack → review loop until CLEAN. A reviewer error is not CLEAN. On dev only, the approved no-CI hotfix path is DOOR B (\`[skip-ci-gate]\`) or DOOR C (weekly-cadence marker); still deploy and verify. UAT/prod never use that path. Land through a GitHub PR, never by merging a local/shared main. If the hub is down, merging may continue and the skipped lane gate must be recorded when service returns.
+
+Do not guess authorization locally: send the request and show the hub refusal unchanged. Stop and Built acknowledgement are staff-only. Machine create/update/coordinator changes are staff-only; coordinators assign agents with \`nodii-dev machine assign MACHINE AGENT --home-repo REPO\`. The target machine coordinator or staff may change lane limits and repository grants. Agents or coordinators report capacity with \`nodii-dev machine report MACHINE --host-facts JSON --memory-facts JSON --heavy-slot-total N\`. Agent registration never sets machine, role, home repo, or lane limit.
+`;
+
+export const managedBlock = `${START}
+## Nodii build workflow
+
+Follow [the nodii build workflow skill](${SKILL_PATH}) for all build work. Drive lane state, evidence, heartbeats, landing, dev verification, and Built acknowledgement through \`nodii-dev\`.
+${END}`;
+
+export const workflowHooks = () => ({
+  SessionStart: [{ hooks: [{ type: "command", command: "nodii-dev lane list --mine --json" }] }],
+  Stop: [{ hooks: [{ type: "command", command: "nodii-dev hook lane-heartbeat" }] }],
+  PostToolUse: [{ matcher: "Bash", hooks: [{ type: "command", command: "nodii-dev hook workflow-post" }] }],
+});
+
+const stable = (x) => JSON.stringify(x);
+function mergeHookList(current = [], additions = []) {
+  const out = [...current];
+  for (const item of additions) if (!out.some((x) => stable(x) === stable(item))) out.push(item);
+  return out;
+}
+
+export function mergeSettings(current = {}) {
+  const hooks = { ...(current.hooks ?? {}) };
+  for (const [event, entries] of Object.entries(workflowHooks())) hooks[event] = mergeHookList(hooks[event], entries);
+  return { ...current, hooks };
+}
+
+export function updateMarkedDocument(text = "") {
+  const block = new RegExp(`${START.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}[\\s\\S]*?${END.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}`);
+  if (block.test(text)) return `${text.replace(block, managedBlock).trimEnd()}\n`;
+  return `${text.trimEnd()}${text.trim() ? "\n\n" : ""}${managedBlock}\n`;
+}
+
+async function optional(path) {
+  try { return await readFile(path, "utf8"); } catch (error) { if (error.code === "ENOENT") return null; throw error; }
+}
+
+export async function setupPlan(root = process.cwd()) {
+  const settingsPath = join(root, ".claude/settings.json");
+  const existingSettings = await optional(settingsPath);
+  let parsed = {};
+  try { parsed = existingSettings ? JSON.parse(existingSettings) : {}; }
+  catch { throw new CliError("INVALID_SETTINGS", `${settingsPath} is not valid JSON; fix it before setup.`, 2); }
+  const claude = join(root, "CLAUDE.md");
+  const agents = join(root, "AGENTS.md");
+  const documentPath = (await optional(claude)) !== null ? claude : (await optional(agents)) !== null ? agents : claude;
+  const desired = new Map([
+    [join(root, SKILL_PATH), workflowSkill],
+    [settingsPath, `${JSON.stringify(mergeSettings(parsed), null, 2)}\n`],
+    [documentPath, updateMarkedDocument((await optional(documentPath)) ?? "")],
+  ]);
+  const changes = [];
+  for (const [path, content] of desired) {
+    const before = await optional(path);
+    if (before !== content) changes.push({ path, relative: path.slice(resolve(root).length + 1), before, content });
+  }
+  return changes;
+}
+
+export async function setupCommand(flags, { root = process.cwd(), authCheck = () => hubRequest("GET", "/api/v1/whoami") } = {}) {
+  const changes = await setupPlan(root);
+  let authenticated = true;
+  try { await authCheck(); } catch { authenticated = false; }
+  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`." };
+  }
+  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.` };
+  }
+  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`."}` };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nodii/dev",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "Agent CLI for the Nodii development hub",
   "type": "module",
   "bin": {
@@ -16,6 +16,8 @@
   },
   "scripts": {
     "build": "node build.mjs",
+    "lint": "node --check src/*.js && node --check test/*.test.js",
+    "format": "git diff --check",
     "test": "node --test test/*.test.js",
     "pack:smoke": "node scripts/pack-smoke.mjs",
     "openapi:snapshot": "curl -sf https://planning.dev.nucleus-cloud.in/openapi.json -o test/fixtures/devops-openapi.snapshot.json"