@brainervirus/workit-core 8.28.0 → 8.29.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brainervirus/workit-core",
-  "version": "8.28.0",
+  "version": "8.29.0",
   "private": false,
   "description": "Workit shared core — task, policy, evidence, review, decision, worker, and writer state for agentic coding workflows",
   "keywords": [

package/src/check-config.ts

@@ -10,6 +10,10 @@
 //    self-ignoring `.workit/`, never at the repo root. A legacy root
 //    `workit.checks.json` is still read when `.workit/checks.json` is absent,
 //    with a note that it moved.
+//    In a linked worktree (a fanout slice's, an agent's) that has neither
+//    file, the main checkout's is read: `.workit/` is git-ignored, so a new
+//    worktree never has one, and it shares the main checkout's checks
+//    (#426). Configured commands still run from the worktree's own top.
 // 2. Built-in ecosystem defaults detected from the repo: package.json scripts
 //    `test`, `lint`, `typecheck`, `check` (`<pm> run <script>`, pm from the
 //    lockfile); go.mod → `go test ./...`; Cargo.toml → `cargo test`;
@@ -216,10 +220,25 @@ function detectedChecks(root: string): NamedCheck[] {
 
 const GATES = ["testing", "verification"] as const;
 
+/**
+ * The checks config file for `root`: its own, else (in a linked worktree
+ * without one) the main checkout's, else the path a new config belongs at.
+ */
+function configFileFor(root: string): string {
+  const own = checksConfigFile(root);
+  if (fs.existsSync(own)) return own;
+  const common = git(root, ["rev-parse", "--path-format=absolute", "--git-common-dir"]);
+  if (!common || path.basename(common) !== ".git") return own;
+  const main = path.dirname(common);
+  if (path.resolve(main) === path.resolve(root)) return own;
+  const shared = checksConfigFile(main);
+  return fs.existsSync(shared) ? shared : own;
+}
+
 /** The named checks for the repository containing `cwd` (see the header). */
 export function loadCheckConfig(cwd: string): CheckConfig {
   const root = checkRoot(cwd);
-  const file = checksConfigFile(root);
+  const file = configFileFor(root);
   const legacy = path.basename(file) === LEGACY_CHECKS_FILE;
   const label = legacy ? LEGACY_CHECKS_FILE : CHECKS_FILE;
   const note = legacy

package/src/core/branch.ts

@@ -318,6 +318,16 @@ export const validateCommitMessagePolicy = (
   };
 };
 
+/**
+ * A TypeError or ReferenceError while resolving a policy is a bug in this
+ * runtime (or a host too old for it), not a config problem the user can
+ * repair: it propagates so the hook's failure decision applies instead of a
+ * misleading "repair or select a valid workspace policy".
+ */
+const rethrowRuntimeBug = (error: unknown): void => {
+  if (error instanceof TypeError || error instanceof ReferenceError) throw error;
+};
+
 export const validateBranchNameFor = (
   workspaceRoot: string,
   name: string,
@@ -326,6 +336,7 @@ export const validateBranchNameFor = (
     const resolved = branchPolicySnapshotFor(workspaceRoot);
     return validateBranchNamePolicy(name, resolved.namePolicy, resolved.source);
   } catch (error) {
+    rethrowRuntimeBug(error);
     const correction = "repair or select a valid workspace policy before creating a branch";
     return {
       ok: false,
@@ -347,6 +358,7 @@ export const validateCommitMessageFor = (
     const resolved = commitPolicySnapshotFor(workspaceRoot);
     return validateCommitMessagePolicy(message, resolved.policy, resolved.source);
   } catch (error) {
+    rethrowRuntimeBug(error);
     const correction = "repair or select a valid workspace policy before committing";
     return {
       ok: false,

package/src/core/operation-input.ts

@@ -184,9 +184,11 @@ export function flatOperationJsonSchema(
   // Reads advertise only what reads take: no revisions, and task reads only their filters.
   const readField = (name: string) =>
     name === "taskId" || (family === "task" ? READ_TASK_FIELDS.has(name) : family === "policy");
+  // Only advertise what some listed action takes (derived from the contract).
+  const taken = (name: string) =>
+    family === "policy" || actions.some((action) => actionKeys(family, action)?.accepted.has(name));
   for (const [name, field] of Object.entries({ ...COMMON, ...spec.fields }))
-    if (options.readOnly ? readField(name) : !(family === "state" && name === "expectedRevision"))
-      properties[name] = property(field);
+    if (options.readOnly ? readField(name) : taken(name)) properties[name] = property(field);
   return {
     $schema: "https://json-schema.org/draft/2020-12/schema",
     type: "object",
@@ -482,6 +484,129 @@ export function normalizeOperationInput(
   return request;
 }
 
+// ---------------------------------------------------------------------------
+// per-action keys, derived from the contract
+
+type ZodLike = {
+  _zod: { def: { type: string; shape?: Record<string, ZodLike>; innerType?: ZodLike } };
+};
+const defOf = (node: ZodLike) => node._zod.def;
+const unwrap = (node: ZodLike): ZodLike => {
+  let inner = node;
+  while (["optional", "nullable"].includes(defOf(inner).type) && defOf(inner).innerType)
+    inner = defOf(inner).innerType!;
+  return inner;
+};
+/** Contract keys the flat form renames. */
+const FLAT_NAME: Record<string, string> = {
+  authorityRefs: "refs",
+  contentRefs: "refs",
+  statedChoice: "choice",
+  reviewContext: "reviewSession",
+};
+const NOT_FLAT = new Set(["schemaVersion", "action", "workspaceId"]);
+
+export type ActionKeys = { accepted: Set<string>; required: string[] };
+
+/**
+ * What one action of a family takes, read from the advertised contract:
+ * every top-level key, the keys of its nested objects (flat form, renamed per
+ * FLAT_NAME), and the required scalars. Lists, scopes and nullables are
+ * defaulted by normalization, so they are accepted but never required.
+ */
+export function actionKeys(family: OperationFamily, action: string): ActionKeys | null {
+  const options = (advertisedOperationSchemas[family] as unknown as { options: ZodLike[] }).options;
+  const option = options.find((item) => {
+    const literal = defOf(item).shape?.action as unknown as { _zod: { def: { values: string[] } } };
+    return literal._zod.def.values.includes(action);
+  });
+  if (!option) return null;
+  const out: ActionKeys = { accepted: new Set(), required: [] };
+  const walk = (shape: Record<string, ZodLike>, nested: boolean): void => {
+    for (const [key, node] of Object.entries(shape)) {
+      if (NOT_FLAT.has(key) || (nested && key === "taskId")) continue;
+      const inner = unwrap(node);
+      const type = defOf(inner).type;
+      const needed = !["optional", "nullable"].includes(defOf(node).type);
+      if (key === "scope")
+        for (const name of ["scope", "paths", "exclusions"]) out.accepted.add(name);
+      else if (type === "object" && key !== "bundle" && !(key in FLAT_NAME)) {
+        out.accepted.add(key);
+        walk(defOf(inner).shape!, true);
+      } else {
+        const name = FLAT_NAME[key] ?? key;
+        out.accepted.add(name);
+        if (needed && type !== "array" && type !== "record" && !out.required.includes(name))
+          out.required.push(name);
+      }
+    }
+  };
+  walk(defOf(option).shape!, false);
+  return out;
+}
+
+/** A minimal valid flat payload for one action: required scalars with placeholders. */
+export function exampleOperation(family: OperationFamily, action: string): Record<string, unknown> {
+  const keys = actionKeys(family, action);
+  const example: Record<string, unknown> = { action };
+  for (const name of keys?.required ?? [])
+    example[name] = FLAT[family].fields[name]?.enum?.[0] ?? `<${name}>`;
+  if (family === "policy" && !keys?.required.length && action !== "explain")
+    example.riskTier = "normal";
+  return example;
+}
+
+const oneOf = (values: readonly string[]): string => values.join(" | ");
+
+/** Every invalid_input the hosts return: the exact fix for this family and action. */
+function invalidOperation(
+  family: OperationFamily,
+  input: unknown,
+  error: ZodErrorLike,
+): Result<never> {
+  const request = isObject(input) ? input : {};
+  const action = typeof request.action === "string" ? request.action : "";
+  const actions = OPERATION_ACTIONS[family];
+  if (!actions.includes(action))
+    return failure("invalid_input", `${family}: action must be one of ${oneOf(actions)}`, {
+      fields: [{ path: "action", reason: `got ${JSON.stringify(request.action ?? null)}` }],
+    });
+  const own = actionKeys(family, action)!;
+  const fields: { path: string; reason: string }[] = [];
+  const sentence: string[] = [];
+  for (const issue of error.issues) {
+    if (issue.code === "unrecognized_keys") {
+      for (const key of issue.keys) {
+        const home = actions.find(
+          (other) => other !== action && actionKeys(family, other)!.accepted.has(key),
+        );
+        const reason = home
+          ? `${key} belongs to action: ${home}`
+          : `${key} is not a field of ${family} ${action}; it takes ${[...own.accepted].join(", ")}`;
+        fields.push({ path: key, reason });
+        sentence.push(reason);
+      }
+      continue;
+    }
+    const last = String(issue.path.at(-1) ?? "");
+    const name = Object.entries(FLAT_NAME).find(([contract]) => contract === last)?.[1] ?? last;
+    const missing = issue.code === "invalid_type" && /received undefined/.test(issue.message);
+    // A nested container (binding, intent, ...) is absent because its flat fields are.
+    const absent = own.required.filter((key) => !(key in request));
+    const needs = missing && issue.path.length === 1 && absent.length ? absent.join(", ") : name;
+    const reason = missing ? `${family} ${action} requires ${needs}` : `${name}: ${issue.message}`;
+    fields.push({ path: issue.path.join("."), reason });
+    sentence.push(reason);
+  }
+  const example = JSON.stringify(exampleOperation(family, action));
+  return failure("invalid_input", `${[...new Set(sentence)].join("; ")}. Example: ${example}`, {
+    fields,
+  });
+}
+type ZodErrorLike = {
+  issues: { code: string; keys: string[]; path: PropertyKey[]; message: string }[];
+};
+
 /**
  * Host-side validation before the engine runs: normalize, then parse against
  * the advertised contract (taskId optional: the engine resolves the branch's
@@ -497,10 +622,5 @@ export function parseAdvertisedOperation(
     return failure("unsupported_version", "unsupported schema version", { operation: family });
   const parsed = advertisedOperationSchemas[family].safeParse(request);
   if (parsed.success) return success(null, null, request);
-  return failure("invalid_input", "operation input is invalid", {
-    fields: parsed.error.issues.map((issue) => ({
-      path: issue.code === "unrecognized_keys" ? issue.keys.join(".") : issue.path.join("."),
-      reason: issue.message,
-    })),
-  });
+  return invalidOperation(family, request, parsed.error as unknown as ZodErrorLike);
 }

package/src/fanout-worktree.ts

@@ -255,9 +255,56 @@ export type CreateOutcome = {
   created: boolean;
   /** node_modules linked from the main checkout (worktree-deps.ts); null when none were. */
   dependencies: LinkedDependencies | null;
+  /** The install command to run in the worktree when its lockfile differs from the main checkout's. */
+  install: string | null;
   notes: string[];
 };
 
+/** Lockfiles in the order a package manager is picked, with its frozen install for a directory. */
+const LOCKFILES: ReadonlyArray<[string, (dir: string) => string]> = [
+  ["bun.lock", (dir) => `bun install --frozen-lockfile --cwd ${dir}`],
+  ["bun.lockb", (dir) => `bun install --frozen-lockfile --cwd ${dir}`],
+  ["pnpm-lock.yaml", (dir) => `pnpm install --frozen-lockfile --dir ${dir}`],
+  ["yarn.lock", (dir) => `yarn install --frozen-lockfile --cwd ${dir}`],
+  ["package-lock.json", (dir) => `npm ci --prefix ${dir}`],
+];
+
+const readBytes = (file: string): Buffer | null => {
+  try {
+    return fs.readFileSync(file);
+  } catch {
+    return null;
+  }
+};
+
+/**
+ * Link the main checkout's node_modules into `worktree` only when every
+ * lockfile is byte-identical in both: a stale main checkout would otherwise
+ * hand the worktree the wrong dependency versions (#426). When one differs,
+ * nothing is linked and `install` is the command the worker runs instead.
+ */
+function worktreeDependencies(
+  main: string,
+  worktree: string,
+): { linked: LinkedDependencies | null; install: string | null; notes: string[] } {
+  for (const [name, install] of LOCKFILES) {
+    const ours = readBytes(path.join(main, name));
+    const theirs = readBytes(path.join(worktree, name));
+    if (ours === null && theirs === null) continue;
+    if (ours !== null && theirs !== null && ours.equals(theirs)) continue;
+    if (fs.existsSync(path.join(worktree, "node_modules"))) break;
+    const command = install(worktree);
+    return {
+      linked: null,
+      install: command,
+      notes: [
+        `${name} differs from the main checkout's (${main}), so its node_modules was not linked; install dependencies first: ${command}`,
+      ],
+    };
+  }
+  return { ...linkWorktreeDependencies(main, worktree), install: null };
+}
+
 function ensureScratch(worktree: string): string {
   const scratch = path.join(worktree, SCRATCH_DIR);
   fs.mkdirSync(scratch, { recursive: true });
@@ -303,7 +350,7 @@ export function createSliceWorktree(
         `remove it yourself (git worktree remove ${target}) once you know what it holds`,
       );
     excludeScratch(cwd);
-    const deps = linkWorktreeDependencies(mainCheckout(cwd), target);
+    const deps = worktreeDependencies(mainCheckout(cwd), target);
     return {
       ok: true,
       data: {
@@ -313,6 +360,7 @@ export function createSliceWorktree(
         mode: resolveRef(cwd, localRef) ? "resume" : "new",
         created: false,
         dependencies: deps.linked,
+        install: deps.install,
         notes: [
           deps.linked
             ? "the worktree already exists; only its missing dependencies were linked"
@@ -392,7 +440,7 @@ export function createSliceWorktree(
   }
   excludeScratch(cwd);
   const scratch = ensureScratch(target);
-  const deps = linkWorktreeDependencies(mainCheckout(cwd), target);
+  const deps = worktreeDependencies(mainCheckout(cwd), target);
   notes.push(...deps.notes);
   const head = gitRun(target, ["rev-parse", "HEAD"]).stdout.trim();
   const baseSha = mode === "new" ? head : null;
@@ -415,7 +463,16 @@ export function createSliceWorktree(
   });
   return {
     ok: true,
-    data: { ...base, scratch, head, mode, created: true, dependencies: deps.linked, notes },
+    data: {
+      ...base,
+      scratch,
+      head,
+      mode,
+      created: true,
+      dependencies: deps.linked,
+      install: deps.install,
+      notes,
+    },
   };
 }