@workit-dev/core 0.0.1 → 1.0.0

package/src/hooks/skill-nudge.ts

@@ -0,0 +1,295 @@
+// Skill routing at the moment it matters. The session-start contract names a
+// trigger for each skill, but in a long or compacted session that table loses
+// weight and agents act without loading the skill. Three deterministic aids,
+// inside a Workit workspace only:
+//   - a prompt that asks for a skill's work in so many words gets one
+//     advisory line naming the skill;
+//   - a delivery command (push, PR create or merge, CI wait) gets one line
+//     naming workit-ship;
+//   - each skill load is recorded as a `skill.loaded` ledger row, so a nudge
+//     stops once the skill is loaded and workit-retro can count skill use.
+// A session is nudged about one skill at most once (a marker per session
+// in the workspace store), never in a subagent, never once it loaded the skill.
+// Every failure answers "no nudge": hooks fail open.
+import {
+  skillLoadWording,
+  WORKIT_METHOD_SKILLS,
+  WORKIT_SKILL_ALIASES,
+  type SkillHost,
+  type WorkitSkill,
+} from "../core/skill-manifests";
+import { appendHookObserved, readLedger } from "../ledger";
+import type { HookDecision, HookInput, HostId } from "./protocol";
+import { inWorkitWorkspace, rawDelivery, rawGitPre, workitInvocations } from "./raw-git";
+import { readSessionMarker, sessionMarkerFile, writeSessionMarker } from "./session-marker";
+import { segmentsOf, type ShellDialect } from "./shell-words";
+
+/** Skills the user starts; a nudge says to offer them, never to load them. */
+const USER_INVOKED: ReadonlySet<WorkitSkill> = new Set(["workit-retro", "workit-architecture"]);
+
+const SKILL_HOST: Record<HostId, SkillHost> = {
+  claude_code: "claude-code",
+  opencode: "opencode",
+  codex_cli: "codex",
+  codex_desktop: "codex",
+  cursor: "cursor",
+  pi: "pi",
+};
+
+/**
+ * Prompt phrasings that ask for a skill's work. The contract's single-word
+ * triggers (plan, build, merge, CI) are for the model's judgment; a hook
+ * cannot tell "plan the cache" from "what's in the plan?", so it matches
+ * phrases only. Ordered by precedence: a broken thing is debug work before
+ * it is a feature or a plan.
+ */
+const PROMPT_INTENTS: ReadonlyArray<readonly [WorkitSkill, RegExp]> = [
+  [
+    "workit-debug",
+    /\b(flaky|regressed|(?:is|introduced) a regression|regression (?:in|after|since|from)|(?:is|are|got|looks) broken|debug (?:this|it|the|why)|fix (?:the|this|a) bug)\b/i,
+  ],
+  [
+    "workit-continue",
+    /\b(pick up where|where (?:were|did) we|resume (?:the|this|my|our|work|where)|hand ?off)\b/i,
+  ],
+  [
+    "workit-review",
+    /\b(blast radius|code review|review (?:the|this|my|PR|pr|#\d+|branch|diff|changes))\b/i,
+  ],
+  [
+    "workit-ship",
+    /\b(ship (?:it|this|the)|babysit|open (?:a|the) (?:PR|pr|MR|mr)(?=\s*$|\s+(?:for|to|on|with|and|against|into|from|after|once)\b|[.!,;])|merge (?:the|this|my) (?:PR|pr|MR|mr|branch)|(?:get|until|make) CI (?:is )?green)\b/i,
+  ],
+  ["workit-bdd", /\b(BDD|TDD|acceptance criteria|Given\/When\/Then)(?![\w/])/],
+  ["workit-test-audit", /\b(test audit|audit the tests|tautolog\w*|weak tests)\b/i],
+  ["workit-deslop", /\b(deslop|slop|dead code)\b/i],
+  [
+    "workit-fanout",
+    /\b(fan(?: |-)?out|parallelize|parallel agents|agent swarm|swarm of agents)\b/i,
+  ],
+  ["workit-verify-app", /\b(verify the app|smoke test|prove it works)\b/i],
+  ["workit-retro", /\b((?:a|the) retro(?![-\w]|\.\w)|retrospective)/i],
+  ["workit-architecture", /\b(deepen (?:the )?modules|architecture (?:review|pass|audit))\b/i],
+  [
+    "workit-shape",
+    /\b(brainstorm\w*|grill me|should we|let'?s plan|plan (?:out|how|the|a|for)|(?:write|draft) (?:a|the) spec)\b/i,
+  ],
+  [
+    "workit-implement",
+    /\b(implement (?:the|this|a|it)|add (?:a|the) feature|build (?:a|an|the) (?:new )?(?:feature|command|verb|page|endpoint|component|cli|tool))\b/i,
+  ],
+];
+
+/** The workit skill a loaded name refers to (`workit:shape`, `workit-shape`, `wk-shape`). */
+export const workitSkillOf = (name: string): WorkitSkill | null => {
+  const bare = name.trim().replace(/^\//, "").toLowerCase();
+  const alias = (WORKIT_SKILL_ALIASES as Record<string, WorkitSkill>)[bare];
+  if (alias) return alias;
+  const skill = bare.replace(/^workit:/, "workit-");
+  return (WORKIT_METHOD_SKILLS as readonly string[]).includes(skill)
+    ? (skill as WorkitSkill)
+    : null;
+};
+
+/** The skill a prompt asks for, by precedence, with the phrase that did. */
+export const promptTrigger = (prompt: string): { skill: WorkitSkill; trigger: string } | null => {
+  // Code blocks and quoted output carry words the user did not ask with.
+  const text = prompt.replace(/```[\s\S]*?```/g, " ").slice(0, 4000);
+  for (const [skill, pattern] of PROMPT_INTENTS) {
+    const match = pattern.exec(text);
+    if (match) return { skill, trigger: match[1] ?? match[0] };
+  }
+  return null;
+};
+
+/** Skills this session already loaded, from its `skill.loaded` rows. */
+const loadedSkills = (cwd: string, session: string): Set<string> => {
+  const ledger = readLedger(cwd);
+  const loaded = new Set<string>();
+  if (!ledger.ok) return loaded;
+  for (const row of ledger.value.rows)
+    if (
+      row.type === "skill.loaded" &&
+      row.actor.session === session &&
+      typeof row.skill === "string"
+    )
+      loaded.add(row.skill);
+  return loaded;
+};
+
+const SKILL_FILE = /(?:^|[\\/])(workit-[a-z-]+)[\\/]SKILL\.md$/;
+
+/** The workit skill whose SKILL.md a path names (Pi's read tool). */
+export const skillFileIn = (file: string): string | null => SKILL_FILE.exec(file)?.[1] ?? null;
+
+/** Commands that read a file for the agent: a shell-loaded skill is one of these on its SKILL.md. */
+const READERS = new Set([
+  "cat",
+  "sed",
+  "head",
+  "tail",
+  "less",
+  "more",
+  "bat",
+  "nl",
+  "get-content",
+  "gc",
+  "type",
+]);
+
+/** The workit skill whose SKILL.md a shell command reads (Codex, Cursor); never git, grep or an editor. */
+export const skillReadIn = (command: string, dialect: ShellDialect = "posix"): string | null => {
+  for (const { words } of segmentsOf(command, dialect)) {
+    if (!READERS.has((words[0]?.split(/[\\/]/).at(-1) ?? "").toLowerCase())) continue;
+    // `sed -i` edits the file; it does not load it.
+    if (words.some((word) => /^(?:-i(?:\.\w+)?|--in-place(?:=.*)?)$/.test(word))) continue;
+    for (const word of words.slice(1)) {
+      const skill = skillFileIn(word);
+      if (skill) return skill;
+    }
+  }
+  return null;
+};
+
+/** Record that the session loaded a workit skill (`via`: the tool, a slash command, a file read). */
+export function recordSkillLoad(
+  input: HookInput,
+  name: string,
+  via: "tool" | "slash" | "read",
+): void {
+  try {
+    const skill = workitSkillOf(name);
+    const session = input.session.id;
+    if (!skill || !session) return;
+    if (!inWorkitWorkspace(input.cwd)) return;
+    const file = sessionMarkerFile(input, session);
+    if (!file) return;
+    const marker = readSessionMarker(file);
+    if (marker.loaded.includes(skill)) return;
+    writeSessionMarker(file, { ...marker, loaded: [...marker.loaded, skill] });
+    if (loadedSkills(input.cwd, session).has(skill)) return;
+    appendHookObserved(input.cwd, {
+      type: "skill.loaded",
+      actor: { host: input.host, session, agentId: input.session.agentId },
+      skill,
+      via,
+    });
+  } catch {
+    // Fail open: a lost row only means a later nudge or a retro miscount.
+  }
+}
+
+/** The nudge for `skill` once per session: null when it was nudged or loaded. */
+const nudgeOnce = (
+  input: HookInput,
+  session: string,
+  skill: WorkitSkill,
+  line: string,
+): string | null => {
+  const file = sessionMarkerFile(input, session);
+  if (!file) return null;
+  const marker = readSessionMarker(file);
+  if (marker.nudged.includes(skill) || marker.loaded.includes(skill)) return null;
+  if (loadedSkills(input.cwd, session).has(skill)) return null;
+  writeSessionMarker(file, { ...marker, nudged: [...marker.nudged, skill] });
+  return line;
+};
+
+const nudgeText = (input: HookInput, skill: WorkitSkill, why: string): string =>
+  USER_INVOKED.has(skill)
+    ? `Workit: ${why} looks like ${skill} work, which the user starts; offer it (/${skill.replace(/^workit-/, "wk-")}) rather than loading it.`
+    : `Workit: ${why} looks like ${skill} work; if it is, ${skillLoadWording(SKILL_HOST[input.host], skill)} first.`;
+
+/** A skill the prompt already loads: `/wk-shape`, `/workit:shape`, Pi's expanded
+ * `/skill:` block, or OpenCode's rewritten `/wk-*` command. */
+const promptLoads = (prompt: string): string | null =>
+  /^\s*\/(?:skill:)?([\w:-]+)/.exec(prompt)?.[1] ??
+  /^\s*<skill name="([\w:-]+)"/.exec(prompt)?.[1] ??
+  /^\s*Load the (workit-[a-z-]+) skill with the skill tool\b/.exec(prompt)?.[1] ??
+  null;
+
+/**
+ * A prompt that relays another agent's words, not the user's: Claude Code
+ * delivers subagent hand-backs, teammate messages and background-task
+ * notifications through UserPromptSubmit. A reviewer's report that says
+ * "regressed" is not a request for workit-debug.
+ */
+export const relayedMessage = (prompt: string): boolean =>
+  /^\s*(?:Another Claude session sent a message\b|<agent-message\s+from=|\[SYSTEM NOTIFICATION\b|<task-notification>)/.test(
+    prompt,
+  );
+
+/** A main session's prompt in a Workit workspace: one advisory line naming the skill it asks for. */
+export function promptNudge(input: HookInput, prompt: string | null | undefined): string | null {
+  try {
+    const session = input.session.id;
+    if (!prompt || !session || input.session.agentId || relayedMessage(prompt)) return null;
+    const loads = promptLoads(prompt);
+    if (loads) {
+      // The prompt already loads its skill; record it, never nudge.
+      recordSkillLoad(input, loads, "slash");
+      return null;
+    }
+    const hit = promptTrigger(prompt);
+    if (!hit || !inWorkitWorkspace(input.cwd)) return null;
+    return nudgeOnce(
+      input,
+      session,
+      hit.skill,
+      nudgeText(input, hit.skill, `this request ("${hit.trigger}")`),
+    );
+  } catch {
+    return null;
+  }
+}
+
+const WORKIT_DELIVERY = /^(?:pr (?:create|merge)|ci wait|git push)\b/;
+/** Does the command run a workit delivery verb (also inside `bash -c '…'`), never help or a dry run? */
+const runsWorkitDelivery = (command: string, dialect: ShellDialect): boolean =>
+  workitInvocations(command, dialect).some(
+    (args) =>
+      !args.some((arg) => arg === "--help" || arg === "-h" || arg === "--dry-run") &&
+      WORKIT_DELIVERY.test(args.join(" ")),
+  );
+
+/**
+ * Does the command deliver in a Workit workspace: a push, a PR/MR create or
+ * merge, or a CI wait (never help or a dry run)?
+ */
+export const isDeliveryCommand = (
+  cwd: string,
+  command: string,
+  dialect: ShellDialect = "posix",
+): boolean =>
+  rawDelivery(cwd, command, dialect) ||
+  (runsWorkitDelivery(command, dialect) && inWorkitWorkspace(cwd));
+
+/** A delivery command in a main session that has not loaded workit-ship. */
+export function shipNudge(input: HookInput, command: string): string | null {
+  try {
+    const session = input.session.id;
+    if (!session || input.session.agentId) return null;
+    const dialect = input.event.kind === "shell.pre" ? (input.event.dialect ?? "posix") : "posix";
+    if (!isDeliveryCommand(input.cwd, command, dialect)) return null;
+    return nudgeOnce(
+      input,
+      session,
+      "workit-ship",
+      nudgeText(input, "workit-ship", "this delivery step"),
+    );
+  } catch {
+    return null;
+  }
+}
+
+/** `decision` with `line` added: a context grows by a line, `none` becomes one. */
+export const withContextLine = (decision: HookDecision, line: string | null): HookDecision => {
+  if (!line) return decision;
+  if (decision.kind === "none") return { kind: "context", text: line };
+  if (decision.kind === "context") return { kind: "context", text: `${decision.text}\n${line}` };
+  return decision;
+};
+
+/** Hosts whose shell nudge rides on the tool result: the raw-git nudge plus the ship line. */
+export const shellNudge = (input: HookInput, command: string): HookDecision =>
+  withContextLine(rawGitPre(input, command), shipNudge(input, command));

package/src/hooks/spawn-gate.ts

@@ -0,0 +1,72 @@
+// The spawn gate (#432, #654), Claude Code's PreToolUse on the Agent tool.
+// No spawn runs under host isolation: Claude Code's worktree isolation refuses
+// every command that wraps git and cannot be turned off, so `isolation` is
+// stripped from every agent type (an implementer works in its brief's
+// WORKTREE); under auto mode, which refuses a rewritten spawn, the spawn is
+// denied with the same args without it (agent-model.ts). A `workit:implementer` spawn also carries a Workit brief: a
+// prompt with no WORKTREE line (no brief, or a brief rendered before the
+// worktree existed) is denied with the commands that make one. A pointer
+// prompt (its WORKER, TIER, TIMEBOX and WORKTREE lines plus "render
+// `workit fanout brief <slice>`") passes: it spares the lead's context, and
+// the launcher fast path (workit-hook.mjs) keeps this same WORKTREE test.
+import { agentModelDecision, type SpawnChange } from "./agent-model";
+import type { HostDescriptor } from "./descriptor";
+import type { HookDecision } from "./protocol";
+import { workitRole } from "./steering";
+
+/** A brief's WORKTREE line naming a made worktree (`fanout brief` says "not made yet" otherwise). */
+const MADE_WORKTREE = /^WORKTREE:[ \t]*(?!not made yet)\S(?![^\n]*not made yet)/mu;
+
+const UNBLOCK = "workit fanout worktree create <slice>";
+const BRIEF = "workit fanout brief <slice>";
+
+/** The gate on a Claude Code spawn: a deny, or the input it lets run and what it changed. */
+type Gate =
+  | { kind: "deny"; decision: HookDecision }
+  | { kind: "run"; input: Record<string, unknown>; change: SpawnChange };
+
+const gate = (descriptor: HostDescriptor, tool: Record<string, unknown>): Gate => {
+  const type = typeof tool.subagent_type === "string" ? tool.subagent_type : "";
+  const implementer = workitRole(descriptor, type) === "implementer";
+  if (implementer && (typeof tool.prompt !== "string" || !MADE_WORKTREE.test(tool.prompt)))
+    return {
+      kind: "deny",
+      decision: {
+        kind: "deny",
+        reason: `workit spawn gate: a ${type} spawn needs a Workit brief with a WORKTREE line, and this prompt has none. Even for one slice: run \`${UNBLOCK}\`, then \`${BRIEF}\`, and spawn again with its text as the prompt and the Agent args its SPAWN line names (a slice no plan registers needs \`workit fanout plan <plan.json>\` first).`,
+        unblock: UNBLOCK,
+      },
+    };
+  if (tool.isolation === undefined)
+    return { kind: "run", input: tool, change: { dropped: [], reasons: [], notes: [] } };
+  const { isolation: _dropped, ...input } = tool;
+  const why = `${
+    implementer
+      ? "it works in the brief's WORKTREE"
+      : "it runs in your checkout; for its own worktree run `workit fanout worktree create <slice>` and name it in the prompt"
+  } (Claude Code's isolation refuses wrapped git).`;
+  return {
+    kind: "run",
+    input,
+    change: {
+      dropped: ["isolation"],
+      reasons: [`Isolation goes: ${why}`],
+      notes: [`Workit removed isolation from this ${type || "general-purpose"} spawn: ${why}`],
+    },
+  };
+};
+
+/**
+ * The gate, then the role's model (agent-model.ts) on what it lets run: one
+ * `updatedInput` for both, or under auto mode one deny naming the exact args.
+ */
+export const spawnDecision = (
+  descriptor: HostDescriptor,
+  cwd: string,
+  tool: Record<string, unknown>,
+  permissionMode: string | null = null,
+): HookDecision => {
+  const checked = gate(descriptor, tool);
+  if (checked.kind === "deny") return checked.decision;
+  return agentModelDecision(cwd, checked.input, { change: checked.change, permissionMode });
+};

package/src/hooks/standing-signal.ts

@@ -0,0 +1,99 @@
+// The standing-order revision signal (#320). Every standing add or clear
+// writes the new row's id to `<store>/standing/rev`; each agent that a hook
+// has answered since keeps the revision it last saw in
+// `<store>/standing/seen/<key>.json`. A tool call whose agent already saw the
+// current revision costs two small reads and never loads the Workit runtime.
+// fs, path and crypto only: the Codex launcher imports this before the
+// runtime, and the Claude Code launcher (bin/workit-hook.mjs) keeps a copy
+// that test/workit-core/hooks/standing-signal.test.ts holds equal.
+import { createHash } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+
+export type StandingSeen = { rev: string | null; ids: string[] };
+
+/** `<git common dir>/workit` by fs reads alone, or null outside a repository. */
+export const gitStoreDir = (cwd: string): string | null => {
+  try {
+    for (let dir = path.resolve(cwd); ; dir = path.dirname(dir)) {
+      const dotGit = path.join(dir, ".git");
+      if (fs.existsSync(dotGit)) {
+        let gitDir = dotGit;
+        if (fs.statSync(dotGit).isFile()) {
+          const target = /^gitdir:\s*(.+)$/mu.exec(fs.readFileSync(dotGit, "utf8"))?.[1]?.trim();
+          if (!target) return null;
+          gitDir = path.resolve(dir, target);
+          const common = path.join(gitDir, "commondir");
+          if (fs.existsSync(common))
+            gitDir = path.resolve(gitDir, fs.readFileSync(common, "utf8").trim());
+        }
+        return path.join(gitDir, "workit");
+      }
+      if (path.dirname(dir) === dir) return null;
+    }
+  } catch {
+    return null;
+  }
+};
+
+export const standingRevFile = (store: string): string => path.join(store, "standing", "rev");
+
+/** One file per agent: a host session, or one subagent of it. */
+export const standingSeenFile = (store: string, session: string, agentId: string | null): string =>
+  path.join(
+    store,
+    "standing",
+    "seen",
+    `${createHash("sha256")
+      .update(`${session}\0${agentId ?? ""}`)
+      .digest("hex")
+      .slice(0, 32)}.json`,
+  );
+
+export const readStandingRev = (store: string): string | null => {
+  try {
+    return fs.readFileSync(standingRevFile(store), "utf8").trim() || null;
+  } catch {
+    return null;
+  }
+};
+
+export const readStandingSeen = (file: string): StandingSeen => {
+  try {
+    const value = JSON.parse(fs.readFileSync(file, "utf8")) as { rev?: unknown; ids?: unknown };
+    return {
+      rev: typeof value.rev === "string" ? value.rev : null,
+      ids: Array.isArray(value.ids)
+        ? value.ids.filter((id): id is string => typeof id === "string")
+        : [],
+    };
+  } catch {
+    return { rev: null, ids: [] };
+  }
+};
+
+/** Fails open: without the file the agent is offered the same delta again. */
+export const writeStandingSeen = (file: string, seen: StandingSeen): void => {
+  try {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, JSON.stringify(seen));
+  } catch {
+    // An unwritable store only repeats the delta.
+  }
+};
+
+export const bumpStandingRev = (store: string, rev: string): void => {
+  try {
+    fs.mkdirSync(path.join(store, "standing"), { recursive: true });
+    fs.writeFileSync(standingRevFile(store), `${rev}\n`);
+  } catch {
+    // Running workers miss the delta; briefs rendered later still carry it.
+  }
+};
+
+/** Has this agent not yet seen the store's current standing revision? */
+export const standingPending = (cwd: string, session: string, agentId: string | null): boolean => {
+  const store = gitStoreDir(cwd);
+  const rev = store ? readStandingRev(store) : null;
+  return rev !== null && readStandingSeen(standingSeenFile(store!, session, agentId)).rev !== rev;
+};