@brainervirus/workit-core 8.17.1 → 8.18.0

package/package.json

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

package/skills/workit-bdd/SKILL.md

@@ -22,7 +22,7 @@ description: Turn requirements into Given/When/Then scenarios, agree the test se
    then take the next scenario. Any edit makes the observation stale; re-run
    before you claim it. A recorded "tests pass" is a note, and an ad-hoc
    `workit check -- <cmd>` never satisfies the gate: only the configured
-   `test` check does. No `test` detected? Create `workit.checks.json`, copying
+   `test` check does. No `test` detected? Create `.workit/checks.json`, copying
    in every check the repo already runs: once it exists it replaces the
    detected defaults.
 5. **Mock only at system boundaries:** network, clock, randomness, other

package/skills/workit-fanout/SKILL.md

@@ -37,8 +37,8 @@ units of ~100+ lines each. Coupled work stays with one owner. Workit never spawn
 6. **Retry once, then escalate.** A stuck or failed slice gets one retry with
    a fresh brief (`workit fanout brief <slice> --mode resume`, same branch);
    if that fails too, re-slice it, take it over, or report the gap. Never
-   chain resumes. A hard slice may race instead: N attempts, keep the best
-   verdict (`references/orchestration.md`).
+   chain resumes. A fix round and recheck that both fail: a decider, not a
+   third round; product choices go to the user (`references/orchestration.md`).
 7. **Verify by the workspace `verification` setting** (`workit grant show`).
    A report is a pointer, never evidence. `self`: a verifier that wrote none
    of the slices, or you if you wrote none. `independent` or high risk: a

package/skills/workit-fanout/references/orchestration.md

@@ -43,6 +43,27 @@ rulings). If the retry fails too, escalate instead of a third worker:
 re-slice it smaller (`workit fanout plan` again), take it over yourself, or
 report the gap to the user.
 
+## Stuck calls: the decider
+
+A failed review gets one fix round and one recheck (the changed hunks only).
+If the recheck fails, or a worker and a reviewer disagree, spawn a decider
+instead of a third round. A decider is a fresh read-only agent, not the author
+or the reviewer. It returns three things: the options, a pick by
+reversibility (the option cheapest to undo wins a tie), and the exact change
+list. The fixer applies that list once, then one focused recheck follows.
+
+- Hard call (shared contract, security, migration): two deciders on different
+  models (Claude Code: a different `model` on the Agent call; OpenCode: a
+  child session on another configured agent; Codex, Cursor and Pi: one
+  decider, since the host picks no model). If they disagree, you take the
+  more reversible option.
+- Record it: `workit ledger decision "<pick>" --by decider --why "<why it is
+  the more reversible>" --view "<decider A: view>" --view "<decider B: view>"`.
+  The row is listed as a decider call; it is never the user's answer to a
+  product choice and never a verdict.
+- A product choice, or authority nobody here has, is not a decider's call:
+  ask the user with your recommendation.
+
 ## Race a hard slice
 
 When a hard slice has an uncertain approach and a cheap VERIFY, run 2-3

package/skills/workit-retro/SKILL.md

@@ -32,7 +32,7 @@ proposes and stops. Nothing changes until the user approves.
    more cited occurrences**; a one-off is not a learning.
 4. **Name the strongest enforcer that works**, strongest first: architecture
    or types (the mistake cannot be written) > lint rule > configured check
-   (`workit.checks.json`, `workit check <name>`) or CI job > test >
+   (`.workit/checks.json`, `workit check <name>`) or CI job > test >
    `CODING_STANDARDS.md` (judgment the reviewer reads) > AGENTS.md pointer
    (navigation only). A mechanical rule gets a check, not prose: a check can
    fail, a sentence cannot. From types to test, the proof is that the new
@@ -60,7 +60,7 @@ Bad: "Agents seem lost in the build. Added 'read the build docs carefully' to
 AGENTS.md." One vague occurrence, no citation, a no-op line, auto-applied.
 
 Good: "Navigation, 3 occurrences (rulings 12, 19; PR #88 thread): agents sought
-check names in package.json, missing `workit.checks.json`. Enforcer: AGENTS.md
+check names in package.json, missing `.workit/checks.json`. Enforcer: AGENTS.md
 pointer, +74 bytes, minus the stale Commands paragraph (-210). Unstable check,
 2 occurrences (ledger rows 31, 44: `e2e` red then green on one SHA): a debug
 slice to fix the check. Approve?"

package/skills/workit-review/SKILL.md

@@ -36,7 +36,10 @@ independent; `type-check-only` never proves a behavior change.
 7. Record the verdict:
    `workit ledger verdict verified|failed|blocked --kind review --branch <b> --how "<what you ran and read>"`
    under your own session (the one the lead or the hook gave you).
-8. **Harness note** (optional): friction caused by the repo or harness, not
+8. **Bound the loop.** A failed verdict gets one fix round and one recheck of
+   the changed hunks. Still failing, or stuck: no third round; the lead spawns
+   a decider (workit-fanout). A product choice goes to the user.
+9. **Harness note** (optional): friction caused by the repo or harness, not
    the change (a flaky fixture, a missing check, a misleading doc or skill
    line), goes on its own `Harness note:` line in the report and any PR
    comment, never as a finding or in the verdict, so a later retro finds it.

package/skills/workit-ship/SKILL.md

@@ -30,7 +30,7 @@ once the verdict is accepted. `merged`: step 7. `null` (closed, not merged):
 stop and report. Stop early only for a new consequential choice, a host
 denial, a review comment that needs a product decision, a required update
 that repeats because the base keeps moving, or after 3 failed fix attempts on
-the same check.
+the same check. Fix round and recheck both failed: a decider (workit-fanout).
 
 1. **Open.** `workit git push`, then `workit pr create --title "<title>"
    --body-file <f|->` plus `--issue <#n|ID>` per issue (`--refs`: no close; idempotent;

package/skills/workit-verify-app/SKILL.md

@@ -35,7 +35,7 @@ way a user would.
    never run is a guess; do not hand it off.
 4. **Make the driver a named check** when it is cheap and deterministic. A
    named check is one command without shell syntax (put pipes and setup in a
-   script). Add `"verify": "<driver>"` to `checks` in `workit.checks.json`; if
+   script). Add `"verify": "<driver>"` to `checks` in `.workit/checks.json`; if
    the file does not exist yet, first copy in every check the repo already runs
    (test, lint, typecheck), because the file replaces the detected defaults.
    `workit check verify` then records it, and it joins the verification gate

package/src/check-config.ts

@@ -5,10 +5,11 @@
 // never does (design §0 #3).
 //
 // Config, first source that exists at the repository top:
-// 1. `workit.checks.json`: `{"checks":{"test":"bun test","lint":["bun","run","lint"]},
-//    "gates":{"testing":"test"}}`, committed and visible in review. (Not
-//    `.workit/checks.json`: the store directory is git-ignored, so a file there
-//    is never reviewed.)
+// 1. `.workit/checks.json`: `{"checks":{"test":"bun test","lint":["bun","run","lint"]},
+//    "gates":{"testing":"test"}}`. Per-repo workit config lives in the
+//    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.
 // 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`;
@@ -25,12 +26,30 @@ import { spawnSync } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
 
-/** The package.json scripts that count as named checks when no workit.checks.json exists. */
+/** The package.json scripts that count as named checks when no checks config exists. */
 export const SCRIPT_CHECKS = ["test", "lint", "typecheck", "check"] as const;
-export const CHECKS_FILE = "workit.checks.json";
+export const CHECKS_FILE = ".workit/checks.json";
+export const LEGACY_CHECKS_FILE = "workit.checks.json";
 
-/** Where the repo's checks config lives under the repository top `root` (the one path resolver). */
-export const checksConfigFile = (root: string): string => path.join(root, CHECKS_FILE);
+/**
+ * Where the repo's checks config lives under the repository top `root` (the
+ * one path resolver): `.workit/checks.json`, else the legacy root file when
+ * only that exists, else the `.workit/` path a new config belongs at.
+ */
+export function checksConfigFile(root: string): string {
+  const current = path.join(root, CHECKS_FILE);
+  const legacy = path.join(root, LEGACY_CHECKS_FILE);
+  return !fs.existsSync(current) && fs.existsSync(legacy) ? legacy : current;
+}
+
+/** Create `<root>/.workit/` with its self-ignoring `.gitignore` (idempotent) and return the dir. */
+export function ensureWorkitDir(root: string): string {
+  const dir = path.join(root, ".workit");
+  fs.mkdirSync(dir, { recursive: true });
+  const ignore = path.join(dir, ".gitignore");
+  if (!fs.existsSync(ignore)) fs.writeFileSync(ignore, "*\n");
+  return dir;
+}
 
 /**
  * `resources.heavyCommands` of the repo's checks config under `root`, read
@@ -59,15 +78,17 @@ export type NamedCheck = {
 
 export type CheckConfig = {
   /** Where the config came from; `defaults` = detected ecosystem defaults, `none` = nothing. */
-  source: "workit.checks.json" | "defaults" | "none";
+  source: typeof CHECKS_FILE | typeof LEGACY_CHECKS_FILE | "defaults" | "none";
   /** The directory configured commands run in (the repository top). */
   root: string;
   checks: NamedCheck[];
-  /** Explicit gate bindings from workit.checks.json (`gates.testing`, `gates.verification`). */
+  /** Explicit gate bindings from the checks config (`gates.testing`, `gates.verification`). */
   gates: Partial<Record<"testing" | "verification", string[]>>;
   /** Set when the config exists but cannot be used; gates then fail closed. */
   error: string | null;
-  /** The raw `resources` block of workit.checks.json (heavy-check limits; core/resources.ts reads it). */
+  /** One line for the user when the config was read from the legacy root file. */
+  note?: string;
+  /** The raw `resources` block of the checks config (heavy-check limits; core/resources.ts reads it). */
   resources?: unknown;
 };
 
@@ -192,19 +213,27 @@ const GATES = ["testing", "verification"] as const;
 export function loadCheckConfig(cwd: string): CheckConfig {
   const root = checkRoot(cwd);
   const file = checksConfigFile(root);
+  const legacy = path.basename(file) === LEGACY_CHECKS_FILE;
+  const label = legacy ? LEGACY_CHECKS_FILE : CHECKS_FILE;
+  const note = legacy
+    ? {
+        note: `${LEGACY_CHECKS_FILE} is deprecated; move it to ${CHECKS_FILE} (workit doctor --fix)`,
+      }
+    : {};
   const none = (error: string | null = null): CheckConfig => ({
-    source: error ? CHECKS_FILE : "none",
+    source: error ? label : "none",
     root,
     checks: [],
     gates: {},
     error,
+    ...note,
   });
   let text: string | null = null;
   try {
     text = fs.readFileSync(file, "utf8");
   } catch (error) {
     if ((error as NodeJS.ErrnoException).code !== "ENOENT")
-      return none(`cannot read ${CHECKS_FILE}: ${(error as Error).message}`);
+      return none(`cannot read ${label}: ${(error as Error).message}`);
   }
   if (text === null) {
     const checks = detectedChecks(root);
@@ -214,14 +243,14 @@ export function loadCheckConfig(cwd: string): CheckConfig {
   try {
     parsed = JSON.parse(text);
   } catch {
-    return none(`${CHECKS_FILE} is not valid JSON`);
+    return none(`${label} is not valid JSON`);
   }
   if (!isRecord(parsed) || !isRecord(parsed.checks))
-    return none(`${CHECKS_FILE} must be {"checks":{"<name>":"<command>"|["argv",…]}}`);
+    return none(`${label} must be {"checks":{"<name>":"<command>"|["argv",…]}}`);
   const checks: NamedCheck[] = [];
   for (const [name, value] of Object.entries(parsed.checks)) {
     if (!CHECK_NAME.test(name))
-      return none(`${CHECKS_FILE}: check name "${name}" must match ${CHECK_NAME.source}`);
+      return none(`${label}: check name "${name}" must match ${CHECK_NAME.source}`);
     const argv =
       typeof value === "string"
         ? splitCommand(value)
@@ -230,27 +259,27 @@ export function loadCheckConfig(cwd: string): CheckConfig {
             value.every((item) => typeof item === "string" && item.length > 0)
           ? (value as string[])
           : new Error("expected a command string or a non-empty argv array");
-    if (argv instanceof Error) return none(`${CHECKS_FILE}: check "${name}": ${argv.message}`);
+    if (argv instanceof Error) return none(`${label}: check "${name}": ${argv.message}`);
     checks.push({ name, argv, accepts: [argv] });
   }
   const gates: CheckConfig["gates"] = {};
   if (parsed.gates !== undefined) {
     if (!isRecord(parsed.gates))
-      return none(`${CHECKS_FILE}: gates must be {"testing":"<name>"|["<name>",…]}`);
+      return none(`${label}: gates must be {"testing":"<name>"|["<name>",…]}`);
     for (const [gate, value] of Object.entries(parsed.gates)) {
       if (!(GATES as readonly string[]).includes(gate))
-        return none(`${CHECKS_FILE}: unknown gate "${gate}" (use ${GATES.join(" or ")})`);
+        return none(`${label}: unknown gate "${gate}" (use ${GATES.join(" or ")})`);
       const names = typeof value === "string" ? [value] : value;
       if (
         !Array.isArray(names) ||
         names.length === 0 ||
         !names.every((name) => typeof name === "string" && checks.some((c) => c.name === name))
       )
-        return none(`${CHECKS_FILE}: gates.${gate} must name configured checks`);
+        return none(`${label}: gates.${gate} must name configured checks`);
       gates[gate as (typeof GATES)[number]] = names as string[];
     }
   }
-  return { source: CHECKS_FILE, root, checks, gates, error: null, resources: parsed.resources };
+  return { source: label, root, checks, gates, error: null, ...note, resources: parsed.resources };
 }
 
 const sameArgv = (left: readonly string[], right: readonly string[]): boolean =>

package/src/core/policy/derive.ts

@@ -196,7 +196,7 @@ export const ledgerView = (root: string): LedgerView => {
 export type RuleStatus = { met: boolean; reason: string; decisionIds: string[] };
 
 /** A user decision recorded on the task, or a ledger decision on this branch since the task began. */
-const productDecision = (task: TaskRecord, ledger: LedgerView): RuleStatus => {
+export const productDecision = (task: TaskRecord, ledger: LedgerView): RuleStatus => {
   const decisions = task.decisions.filter(
     (entry) =>
       entry.data.revoked === null &&
@@ -217,6 +217,7 @@ const productDecision = (task: TaskRecord, ledger: LedgerView): RuleStatus => {
     .findLast(
       (item) =>
         item.type === "decision" &&
+        item.by !== "decider" &&
         !item.superseded &&
         (item.branch ?? null) === branch &&
         Date.parse(item.at) >= since,

package/src/core/resources.ts

@@ -13,7 +13,7 @@
 //
 // Settings: built-in defaults (derived from total RAM and CPUs), then
 // `resources` in the matching workspaces.json entry (the machine owner's
-// word), then `resources` in workit.checks.json, which can only tighten them.
+// word), then `resources` in .workit/checks.json, which can only tighten them.
 // Only the CLI imports this module; hooks never do.
 import { randomUUID } from "node:crypto";
 import fs from "node:fs";
@@ -103,7 +103,7 @@ function cpuValue(value: unknown, host: HostShape): number | Error {
 
 /**
  * Where a `resources` block comes from. `machine` (the user's workspaces.json)
- * sets anything. `repo` (a committed workit.checks.json) can only tighten: it
+ * sets anything. `repo` (the repo's .workit/checks.json) can only tighten: it
  * adds heavy checks, lowers memoryMax and cpuQuota, and sets its own wait; it
  * cannot raise the machine's slots or turn the scope off.
  */

package/src/core/task-evaluation.ts

@@ -684,7 +684,7 @@ function evaluateObservedGate(
       reason:
         requirement.dimension === "testing" && config.checks.length
           ? `no \`test\` check is configured; add one (or gates.testing) to ${CHECKS_FILE}, then run ${checkCommand("test", runtimeVersion())}`
-          : `no checks are configured or detected; add ${CHECKS_FILE} (committed, so it shows in the diff), e.g. {"checks":{"test":"<your test command>"}}, then run ${checkCommand("test", runtimeVersion())}`,
+          : `no checks are configured or detected; add ${CHECKS_FILE}, e.g. {"checks":{"test":"<your test command>"}}, then run ${checkCommand("test", runtimeVersion())}`,
     };
   const satisfied = fresh.filter(named);
   if (satisfied.length)

package/src/fanout-brief.ts

@@ -113,6 +113,7 @@ const rules = (
       : "  3. Commit with `workit git commit -m <msg> -- <paths in SCOPE>`; push only if this brief says so.",
     "  4. Never record a verdict on your own work.",
     "  5. Run tests, lint, typecheck and builds only through `workit check` (a named check, or `workit check --heavy -- <cmd>`): one machine-wide lease queues every agent, so never a hand-made flock; `workit lock status` shows who holds it.",
+    "  6. A failed review gets one fix round and one recheck. Still failing: stop and report the open finding, never a third round (the lead spawns a decider). A product choice is the user's: report it, do not decide it.",
   ];
 };
 

package/src/ledger.ts

@@ -130,6 +130,10 @@ export type DecisionRow = RowCommon & {
   what: string;
   why: string;
   refs: string[];
+  /** A tie-breaker agent's call (`--by decider`): never the user's answer, never a verdict. */
+  by?: "decider";
+  /** Each decider's view when the call was recorded after weighing more than one. */
+  views?: string[];
 };
 export type RulingRow = RowCommon & {
   type: "ruling";
@@ -1702,8 +1706,12 @@ function checkSupersede(
 
 export function recordDecision(
   context: RecordContext,
-  input: { what?: string; why?: string; refs?: string[] },
+  input: { what?: string; why?: string; refs?: string[]; by?: string; views?: string[] },
 ): LedgerResult<DecisionRow> {
+  if (input.by !== undefined && input.by !== "decider")
+    return err("invalid_input", `--by takes "decider", got "${input.by}"`);
+  if (input.by === undefined && input.views?.length)
+    return err("invalid_input", "--view needs --by decider");
   const what = required(input.what, "<what>");
   if (!what.ok) return what;
   const why = required(input.why, "--why");
@@ -1718,6 +1726,8 @@ export function recordDecision(
       what: what.value,
       why: why.value,
       refs: input.refs ?? [],
+      ...(input.by === "decider" ? { by: "decider" as const } : {}),
+      ...(input.views?.length ? { views: input.views } : {}),
     },
     { now: context.now },
   );
@@ -2023,7 +2033,7 @@ export type RowSummary = {
   branch: string | null;
   summary: string;
   /** Why a reader should discount the row: superseded, ignored (by the trust rules), self. */
-  labels: Array<"superseded" | "ignored" | "self">;
+  labels: Array<"superseded" | "ignored" | "self" | "decider">;
 };
 
 /** Row types that count only when an observing verb wrote them. */
@@ -2040,6 +2050,7 @@ export function rowLabels(row: ReadRow): RowSummary["labels"] {
   if (row.supersedeIgnored || (OBSERVED_ONLY.has(row.type) && row.observer !== "workit_cli"))
     labels.push("ignored");
   if (row.type === "verdict" && row.self === true) labels.push("self");
+  if (row.type === "decision" && row.by === "decider") labels.push("decider");
   return labels;
 }
 
@@ -2047,9 +2058,11 @@ export function summarizeRow(row: ReadRow): RowSummary {
   const text = (key: string): string => str(row[key]) ?? "";
   let summary: string;
   switch (row.type) {
-    case "decision":
-      summary = `${text("what")} (why: ${text("why")})`;
+    case "decision": {
+      const views = Array.isArray(row.views) ? row.views.map(String) : [];
+      summary = `${row.by === "decider" ? "[decider] " : ""}${text("what")} (why: ${text("why")}${views.length ? `; views: ${views.join(" | ")}` : ""})`;
       break;
+    }
     case "ruling":
       summary = `${text("what")} (why: ${text("why")}; cost if wrong: ${text("costIfWrong")})`;
       break;