@brainervirus/workit-core 2.6.0 → 2.8.0

package/package.json

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

package/scripts/bundled-deps.json

@@ -12,6 +12,7 @@
   ],
   "workit-cli": [
     "@alcalzone/ansi-tokenize",
+    "@babel/parser",
     "@inkjs/ui",
     "@openclaw/fs-safe",
     "ansi-escapes",
@@ -87,6 +88,7 @@
   "workit-pi": ["@openclaw/fs-safe", "zod"],
   "workit-claude-code": [
     "@alcalzone/ansi-tokenize",
+    "@babel/parser",
     "@inkjs/ui",
     "@openclaw/fs-safe",
     "ansi-escapes",

package/skills/workit-bdd/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: workit-bdd
+description: Use when turning a requirement, issue or acceptance criterion into tests, or when tests should read as behavior (Given/When/Then, BDD, scenarios, acceptance tests, test names and seams)
+---
+
+# Behavior first: Given/When/Then
+
+Write each acceptance criterion as Given/When/Then before any code, then let
+it name the test and pick the seam. This skill shapes the scenarios; the
+RED/GREEN loop itself is workit-behavioral-tdd.
+
+## Method
+
+1. Write the scenarios. One behavior per scenario, in the user's or caller's
+   words: `Given <state>, When <action>, Then <observable result>`. Include the
+   unhappy paths a caller depends on (denied, empty, invalid, timeout).
+2. Agree the seams. Pick the highest stable interface the scenario can be
+   observed through: a CLI verb, a public function, an HTTP route. Ideally one
+   seam per feature. Write the seams down; do not test at an unagreed seam.
+3. Name the tests after the scenarios. The test name is the Given/When/Then
+   sentence; the body is arrange (Given), act (When), assert (Then). Expected
+   values come from the scenario (a literal from a worked example or the
+   spec), never from the code.
+4. Use Gherkin only where the repo already does (`.feature` files with
+   playwright-bdd, cucumber, jest-cucumber). Otherwise plain test names carry
+   the scenario; do not add a BDD framework.
+5. Build in vertical slices, one scenario at a time, with
+   workit-behavioral-tdd: run `workit check test` RED for the new scenario,
+   make the smallest change, run `workit check test` GREEN, then the next.
+6. Mock only at system boundaries: network, clock, randomness, other
+   processes, sometimes the filesystem. Never the unit or its internal
+   collaborators; use the real thing or an in-memory adapter behind a port.
+
+## Completion
+
+Every acceptance criterion maps to a named test at an agreed seam, each was
+seen RED then GREEN through `workit check test`, and the new tests have no
+tautologies:
+
+```sh
+workit test-audit --diff && workit check test
+```

package/skills/workit-behavioral-tdd/SKILL.md

@@ -16,12 +16,16 @@ Use this method when assessment selects the `testing` dimension.
 2. State one behavior and its observable result. Choose the narrowest stable
    boundary a caller or user depends on; avoid private helpers and incidental
    representations.
-3. Write one vertical RED slice that fails for the missing behavior, run it, and
-   preserve the actual failure as evidence. Implement the smallest change, then
-   run the same slice GREEN and record its result. Close enforces the order: a
-   testing requirement with GREEN but no preceding RED evidence stays unsatisfied.
-4. Add only another slice for a distinct behavior or risk. Reconcile stale
-   evidence if the candidate changes.
+3. Write one vertical RED slice that fails for the missing behavior and run it
+   through the CLI so the failure is observed: `workit check test` (the repo's
+   configured `test` check; `npx -y @brainervirus/workit-cli check test` when
+   `workit` is not on PATH). Implement the smallest change, then run the same
+   check GREEN. Close accepts only a fresh passing run of the configured check
+   that `workit check` observed; a recorded "tests pass" is a note, and an
+   ad-hoc `workit check -- <cmd>` never satisfies the gate. If no `test` check
+   is configured or detected, add `workit.checks.json` (committed) with it.
+4. Add only another slice for a distinct behavior or risk. Any edit makes the
+   observed check stale: re-run `workit check test` before closing.
 
 ## Reject noisy tests
 
@@ -35,9 +39,13 @@ Use this method when assessment selects the `testing` dimension.
   ghost loops (assert inside a possibly-empty loop), smoke-only renders,
   type-only or CSS-class coupling. If the test still passes when every
   imported function returns undefined, rewrite the assertion or delete it.
+  `workit test-audit --diff` flags these; triage them with workit-test-audit.
+  Turning acceptance criteria into scenarios and seams is workit-bdd.
 
-Use shared `evidence` operations for RED/GREEN results. Do not add a second
-lifecycle, approval chain, or test workflow outside the current task state.
+Run RED/GREEN through `workit check`, which records the observed result on the
+current task; shared `evidence` operations are for notes and non-test evidence.
+Do not add a second lifecycle, approval chain, or test workflow outside the
+current task state.
 
 ## Common mistakes
 
@@ -45,4 +53,4 @@ lifecycle, approval chain, or test workflow outside the current task state.
 | --- | --- |
 | "The pin changed, so assert the new string" | Exercise the affected consumer behavior. |
 | "The code is obvious" | A small vertical slice still proves the contract. |
-| Keeping a passing test after the boundary moved | Mark it stale and retest the current candidate. |
+| Keeping a passing test after the boundary moved | Re-run `workit check test` on the current tree. |

package/skills/workit-debug/SKILL.md

@@ -19,7 +19,8 @@ established root cause.
    inferences, and unknowns with references; trace the failing value and all
    relevant callers before editing.
 3. State the root-cause hypothesis and the smallest in-scope fix. Write a focused
-   regression at the boundary when practical, then run RED and GREEN checks.
+   regression at the boundary when practical, then run RED and GREEN through
+   `workit check <name>` so the results are observed, not reported.
 4. Acquire writer authority through `writer` before mutation. Reconcile the
    candidate, evidence, and findings after the change; investigate sibling paths
    and stale conclusions rather than assuming the first patch worked.

package/skills/workit-test-audit/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: workit-test-audit
+description: Use when tests may be tautological, low-value or noisy, before trusting a green suite, when reviewing tests an agent wrote, or when asked to clean up, prune or strengthen tests
+---
+
+# Audit tests for tautologies
+
+A tautological test recomputes its expected value the way the code does, so it
+passes by construction and can never disagree with the code. Find those and
+other low-value tests and triage each one. The audit is advice: never delete
+or weaken a test to make it quiet.
+
+## Method
+
+1. Run the audit on the change (or the paths you were asked about):
+   `workit test-audit --diff --json` or `workit test-audit <paths> --json`.
+   Each finding has file:line, rule, severity, confidence, why and a fix.
+   Prose checks are `info`; add `--min-severity info` to see them.
+2. Triage every finding with "Name the Break": which wrong production change
+   should make this test fail? Then choose one, and say which:
+   - Replace: keep the behavior, fix the oracle. Assert the public result
+     against an independent expected value (a literal from a worked example,
+     the spec, an external contract). Plant the bug you named, watch the new
+     test fail, then revert the plant.
+   - Keep with a reason: the value is an external contract or the finding is
+     wrong. Mark it `// workit-test-audit-ignore <rule> -- <reason>`.
+   - Remove: only `assertion-free` or `duplicate-body` tests, and only after
+     checking that no other test loses unique behavior with it.
+3. Check the replacements catch real breaks: `workit test-audit --mutate --diff`
+   (pass `--test-cmd "<runner> {files}"` to run only the related tests). A
+   surviving mutant names a change no test notices; add the missing case.
+4. Leave untouched tests outside the diff alone; propose that cleanup as its
+   own change.
+
+## Completion
+
+Every finding is triaged (replaced with a test that failed on a planted bug,
+kept with an ignore comment and reason, or removed as above) and the configured
+tests are green:
+
+```sh
+workit check test
+```

package/src/check-config.ts

@@ -0,0 +1,294 @@
+// Named checks (design §2.1 S9 `workit check`; D5, D14). A check is *named*
+// (configured) when its name is in the repo's check config and the argv run is
+// exactly the configured argv, run from the repository top. Only named checks
+// satisfy a gate that binds to them; `workit check -- true` is ad-hoc and
+// 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.)
+// 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`;
+//    pytest.ini or a pyproject.toml that mentions pytest → `pytest`; a Makefile
+//    `test:` target → `make test`. The first source to define a name wins.
+//
+// Gates: `testing` binds to `gates.testing` (default `test`), `verification`
+// to `gates.verification` (default: every configured check). Ad-hoc runs never
+// satisfy a gate; with nothing configured the gate says to add the file.
+//
+// Kept separate from checks.ts (the runner) because task evaluation, and so
+// every hook bundle, imports it. Plain TS over node built-ins.
+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. */
+export const SCRIPT_CHECKS = ["test", "lint", "typecheck", "check"] as const;
+export const CHECKS_FILE = "workit.checks.json";
+
+export type NamedCheck = {
+  name: string;
+  /** The argv `workit check <name>` runs. */
+  argv: string[];
+  /** Every argv that counts as this check (the run argv plus package-manager aliases). */
+  accepts: string[][];
+};
+
+export type CheckConfig = {
+  /** Where the config came from; `defaults` = detected ecosystem defaults, `none` = nothing. */
+  source: "workit.checks.json" | "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`). */
+  gates: Partial<Record<"testing" | "verification", string[]>>;
+  /** Set when the config exists but cannot be used; gates then fail closed. */
+  error: string | null;
+};
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === "object" && value !== null && !Array.isArray(value);
+
+const SHELL_META = /[|&;<>()$`\\*?[\]{}~!#]/u;
+
+/**
+ * Split a configured command string into argv: whitespace separated, with
+ * single or double quotes grouping. Shell syntax (pipes, globs, variables,
+ * redirects) is refused: configured checks never run through a shell.
+ */
+export function splitCommand(command: string): string[] | Error {
+  const argv: string[] = [];
+  let current = "";
+  let quote: '"' | "'" | null = null;
+  let started = false;
+  for (const char of command) {
+    if (quote) {
+      if (char === quote) quote = null;
+      else current += char;
+      continue;
+    }
+    if (char === '"' || char === "'") {
+      quote = char;
+      started = true;
+      continue;
+    }
+    if (/\s/u.test(char)) {
+      if (started) argv.push(current);
+      current = "";
+      started = false;
+      continue;
+    }
+    if (SHELL_META.test(char))
+      return new Error(`"${command}" uses shell syntax (${char}); configure an argv array instead`);
+    current += char;
+    started = true;
+  }
+  if (quote) return new Error(`"${command}" has an unterminated quote`);
+  if (started) argv.push(current);
+  return argv.length ? argv : new Error("empty command");
+}
+
+const git = (cwd: string, args: string[]): string | null => {
+  const run = spawnSync("git", args, {
+    cwd,
+    encoding: "utf8",
+    timeout: 20_000,
+    killSignal: "SIGKILL",
+    windowsHide: true,
+  });
+  const value = run.status === 0 ? (run.stdout ?? "").trim() : "";
+  return value || null;
+};
+
+/** The repository top for `cwd`, or `cwd` itself outside git. */
+export function checkRoot(cwd: string): string {
+  return path.resolve(git(cwd, ["rev-parse", "--show-toplevel"]) ?? cwd);
+}
+
+const packageManager = (root: string): "bun" | "pnpm" | "yarn" | "npm" => {
+  const has = (file: string) => fs.existsSync(path.join(root, file));
+  if (has("bun.lock") || has("bun.lockb")) return "bun";
+  if (has("pnpm-lock.yaml")) return "pnpm";
+  if (has("yarn.lock")) return "yarn";
+  return "npm";
+};
+
+const scriptCheck = (pm: ReturnType<typeof packageManager>, name: string): NamedCheck => {
+  const argv = [pm, "run", name];
+  const accepts = [argv];
+  // `bun test` is bun's own runner, not the script; npm only aliases `test`.
+  if (pm === "pnpm" || pm === "yarn" || (pm === "npm" && name === "test")) accepts.push([pm, name]);
+  return { name, argv, accepts };
+};
+
+const CHECK_NAME = /^[a-z0-9][a-z0-9:._-]{0,63}$/u;
+
+/** Built-in ecosystem defaults detected at `root` (see the header). */
+function detectedChecks(root: string): NamedCheck[] {
+  const read = (file: string): string | null => {
+    try {
+      return fs.readFileSync(path.join(root, file), "utf8");
+    } catch {
+      return null;
+    }
+  };
+  const checks: NamedCheck[] = [];
+  const add = (check: NamedCheck) => {
+    if (!checks.some((item) => item.name === check.name)) checks.push(check);
+  };
+  const manifestText = read("package.json");
+  if (manifestText !== null) {
+    let manifest: unknown = null;
+    try {
+      manifest = JSON.parse(manifestText);
+    } catch {
+      // An unparsable package.json defines no scripts.
+    }
+    const scripts = isRecord(manifest) && isRecord(manifest.scripts) ? manifest.scripts : {};
+    const pm = packageManager(root);
+    for (const name of SCRIPT_CHECKS) {
+      const script = scripts[name];
+      if (typeof script === "string" && script.trim() !== "") add(scriptCheck(pm, name));
+    }
+  }
+  const plain = (name: string, argv: string[]): NamedCheck => ({ name, argv, accepts: [argv] });
+  if (read("go.mod") !== null) add(plain("test", ["go", "test", "./..."]));
+  if (read("Cargo.toml") !== null) add(plain("test", ["cargo", "test"]));
+  if (read("pytest.ini") !== null || /\bpytest\b/u.test(read("pyproject.toml") ?? ""))
+    add(plain("test", ["pytest"]));
+  const makefile = read("Makefile") ?? read("makefile") ?? read("GNUmakefile");
+  if (makefile !== null && /^test\s*:(?!=)/mu.test(makefile)) add(plain("test", ["make", "test"]));
+  return checks;
+}
+
+const GATES = ["testing", "verification"] as const;
+
+/** The named checks for the repository containing `cwd` (see the header). */
+export function loadCheckConfig(cwd: string): CheckConfig {
+  const root = checkRoot(cwd);
+  const file = path.join(root, CHECKS_FILE);
+  const none = (error: string | null = null): CheckConfig => ({
+    source: error ? CHECKS_FILE : "none",
+    root,
+    checks: [],
+    gates: {},
+    error,
+  });
+  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}`);
+  }
+  if (text === null) {
+    const checks = detectedChecks(root);
+    return checks.length ? { source: "defaults", root, checks, gates: {}, error: null } : none();
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    return none(`${CHECKS_FILE} is not valid JSON`);
+  }
+  if (!isRecord(parsed) || !isRecord(parsed.checks))
+    return none(`${CHECKS_FILE} 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}`);
+    const argv =
+      typeof value === "string"
+        ? splitCommand(value)
+        : Array.isArray(value) &&
+            value.length > 0 &&
+            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}`);
+    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>",…]}`);
+    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 ")})`);
+      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`);
+      gates[gate as (typeof GATES)[number]] = names as string[];
+    }
+  }
+  return { source: CHECKS_FILE, root, checks, gates, error: null };
+}
+
+const sameArgv = (left: readonly string[], right: readonly string[]): boolean =>
+  left.length === right.length && left.every((item, index) => item === right[index]);
+
+/**
+ * Is a run of `argv` from `cwd` (relative to the repo top, posix) the named
+ * check `name`? Only an exact argv match from the repository top counts.
+ */
+export function matchesNamedCheck(
+  config: CheckConfig,
+  name: string | null,
+  argv: readonly string[],
+  cwd: string,
+): boolean {
+  if (config.error || name === null || cwd !== ".") return false;
+  const check = config.checks.find((item) => item.name === name);
+  return Boolean(check?.accepts.some((accepted) => sameArgv(accepted, argv)));
+}
+
+/**
+ * The named checks a gate of `dimension` binds to: `gates.<dimension>` when
+ * set, else `testing` → `test` (only when configured) and `verification` →
+ * every configured check. Empty means nothing can satisfy the gate: ad-hoc
+ * runs never do (D14).
+ */
+export function gateCheckNames(config: CheckConfig, dimension: string): string[] {
+  const explicit = config.gates[dimension as (typeof GATES)[number]];
+  if (explicit) return explicit;
+  const names = config.checks.map((check) => check.name);
+  if (dimension === "testing") return names.includes("test") ? ["test"] : [];
+  return names;
+}
+
+let workitOnPath: boolean | undefined;
+
+/** Is a `workit` executable on PATH (PATHEXT-aware on Windows)? Probed once per process. */
+export function workitAvailable(env: NodeJS.ProcessEnv = process.env): boolean {
+  if (workitOnPath !== undefined) return workitOnPath;
+  const windows = process.platform === "win32";
+  const exts = windows ? (env.PATHEXT ?? ".COM;.EXE;.BAT;.CMD").split(";").filter(Boolean) : [""];
+  const dirs = (env.PATH ?? env.Path ?? "").split(path.delimiter).filter(Boolean);
+  workitOnPath = dirs.some((dir) =>
+    exts.some((ext) => {
+      try {
+        return fs.statSync(path.join(dir, `workit${ext}`)).isFile();
+      } catch {
+        return false;
+      }
+    }),
+  );
+  return workitOnPath;
+}
+
+/**
+ * The command that runs `workit check <args>`: plain `workit` when it is on
+ * PATH, else a pinned `npx -y @brainervirus/workit-cli@<version>` fallback.
+ */
+export function checkCommand(args: string, version: string, onPath = workitAvailable()): string {
+  return onPath
+    ? `workit check ${args}`
+    : `npx -y @brainervirus/workit-cli@${version} check ${args}`;
+}