@karajan-family/code 4.21.0

package/src/harden/stack-roots.js

@@ -0,0 +1,105 @@
+/**
+ * detectStackRoots — find every language root in a (possibly monorepo) tree
+ * for `kj harden` (KJC-TSK-0561).
+ *
+ * Walks the project up to a shallow depth and returns the shallowest
+ * directory where each language appears, e.g. a fullstack repo yields
+ * `[{dir:"frontend",language:"javascript"},{dir:"backend",language:"python"}]`
+ * so lint/format config is seeded on each side. Universal config (handled by
+ * the caller) stays at the project root. Noise dirs are never descended.
+ */
+
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join, relative } from "node:path";
+
+const IGNORE_DIRS = new Set([
+  "node_modules",
+  "dist",
+  "build",
+  "coverage",
+  "vendor",
+  "target",
+  "__pycache__",
+  "venv",
+  // Auxiliary code that isn't the app to harden (KJC-TSK-0564): demo/fixture
+  // dirs ship their own throwaway manifests and must not seed lint/CI config.
+  "examples",
+  "example",
+  "fixtures",
+  "samples",
+  "third_party",
+  "testdata",
+  "__fixtures__",
+]);
+const DEFAULT_MAX_DEPTH = 2;
+
+/**
+ * Minimal glob for harden scope flags — no dynamic RegExp (eslint security).
+ * Matches on exact equality, directory prefix (`wrappers` ⊇ `wrappers/python`)
+ * and `*` wildcards anchored at both ends unless the `*` is leading/trailing.
+ */
+export function matchesGlob(value, pattern) {
+  if (value === pattern || value.startsWith(`${pattern}/`)) return true;
+  if (!pattern.includes("*")) return false;
+  const pieces = pattern.split("*");
+  let idx = 0;
+  for (let i = 0; i < pieces.length; i += 1) {
+    const piece = pieces[i];
+    if (!piece) continue;
+    const at = value.indexOf(piece, idx);
+    if (at === -1 || (i === 0 && at !== 0)) return false;
+    idx = at + piece.length;
+  }
+  return pattern.endsWith("*") || value.length === idx;
+}
+
+/** Identify the language of a single directory by its manifest files. */
+export function languageAt(dir) {
+  if (existsSync(join(dir, "package.json"))) {
+    if (existsSync(join(dir, "tsconfig.json"))) return "typescript";
+    try {
+      const pkg = JSON.parse(readFileSync(join(dir, "package.json"), "utf8"));
+      const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+      if (deps.typescript || deps["ts-node"]) return "typescript";
+    } catch {
+      /* unreadable package.json → treat as plain JS */
+    }
+    return "javascript";
+  }
+  if (["pyproject.toml", "requirements.txt", "setup.py"].some((f) => existsSync(join(dir, f)))) return "python";
+  if (existsSync(join(dir, "go.mod"))) return "go";
+  if (existsSync(join(dir, "composer.json"))) return "php";
+  return null;
+}
+
+export function detectStackRoots(projectDir, { maxDepth = DEFAULT_MAX_DEPTH, only = [], exclude = [] } = {}) {
+  const found = [];
+  function walk(dir, depth) {
+    const language = languageAt(dir);
+    if (language) found.push({ dir: relative(projectDir, dir) || ".", language, depth });
+    if (depth >= maxDepth) return;
+    let entries;
+    try {
+      entries = readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const e of entries) {
+      if (e.isDirectory() && !e.name.startsWith(".") && !IGNORE_DIRS.has(e.name)) {
+        walk(join(dir, e.name), depth + 1);
+      }
+    }
+  }
+  walk(projectDir, 0);
+
+  // Keep only the shallowest directory per language.
+  const byLanguage = new Map();
+  for (const f of found) {
+    const cur = byLanguage.get(f.language);
+    if (!cur || f.depth < cur.depth) byLanguage.set(f.language, f);
+  }
+  let roots = [...byLanguage.values()].map(({ dir, language }) => ({ dir, language }));
+  if (only.length) roots = roots.filter((r) => only.some((o) => matchesGlob(r.dir, o)));
+  if (exclude.length) roots = roots.filter((r) => !exclude.some((g) => matchesGlob(r.dir, g)));
+  return roots.sort((a, b) => a.dir.localeCompare(b.dir));
+}

package/src/harden/test-on-push.js

@@ -0,0 +1,38 @@
+/**
+ * Test-on-push policy (KJC-TSK-0647) — the full suite on every push is
+ * redundant when CI already runs it per PR, and a source of false reds
+ * (suites unstable under local parallelism). Field-reproduced.
+ *
+ * Policy: a CI workflow that runs tests ⇒ pre-push drops its test command
+ * (identity guard and chaining stay). Repos can force it back with
+ * `"kj": { "harden": { "test_on_push": true } }` in package.json. Repos
+ * without CI keep tests on push — there it IS the last safety net.
+ */
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+const TEST_STEP = /\b(npm (run )?test|vitest|jest|pytest|go test|phpunit|cargo test)\b/;
+
+export function ciRunsTests(projectDir) {
+  const dir = join(projectDir, ".github", "workflows");
+  if (!existsSync(dir)) return false;
+  try {
+    return readdirSync(dir)
+      .filter((f) => /\.ya?ml$/.test(f))
+      .some((f) => TEST_STEP.test(readFileSync(join(dir, f), "utf8")));
+  } catch {
+    return false;
+  }
+}
+
+export function resolveTestOnPush({ projectDir, repoCfg = {}, testCmd = null }) {
+  if (!testCmd) return { testCmd: null, reason: null };
+  if (repoCfg.test_on_push === true) return { testCmd, reason: null };
+  if (ciRunsTests(projectDir)) {
+    return {
+      testCmd: null,
+      reason: "CI already runs the suite per PR — pre-push keeps only the identity guard (opt back in with kj.harden.test_on_push: true in package.json)",
+    };
+  }
+  return { testCmd, reason: null };
+}

package/src/harden/workflow-engine.js

@@ -0,0 +1,116 @@
+/**
+ * workflow-engine — seeds CI quality workflows for `kj harden` (KJC-TSK-0557).
+ *
+ * Seed-if-absent into `.github/workflows/`: a workflow the user already wrote
+ * (no kj:managed marker) is left untouched and reported "skipped". kj-managed
+ * workflows refresh in place. Markers ride in YAML `#` comments.
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { fileURLToPath } from "node:url";
+import { dirname } from "node:path";
+
+import { upsertManagedBlock } from "../utils/managed-markers.js";
+import { extraWorkflowsFor, mutationWorkflowFor, qualityWorkflowFor, policyWorkflowFor, WORKFLOWS } from "./workflow-templates.js";
+
+// La versión del kj que corre harden — es la que se pinea en el fallback
+// npx del workflow de policy (jamás @latest en CI). Lectura LAZY: en el
+// bundle SEA no hay package.json junto al módulo y una lectura eager a
+// nivel de módulo tumbaba el binario entero al cargar (ENOENT /package.json).
+let _ownPkg;
+function ownPkg() {
+  if (_ownPkg === undefined) {
+    try {
+      _ownPkg = JSON.parse(
+        readFileSync(join(dirname(fileURLToPath(import.meta.url)), "..", "..", "package.json"), "utf8"),
+      );
+    } catch {
+      _ownPkg = null;
+    }
+  }
+  return _ownPkg;
+}
+
+const BLOCK_VERSION = 1;
+const WORKFLOWS_DIR = join(".github", "workflows");
+
+/** A package.json that ships code (not private, has bin or main) ⇒ publishable. */
+export function isPublishableNpm(projectDir) {
+  const pkgPath = join(projectDir, "package.json");
+  if (!existsSync(pkgPath)) return false;
+  try {
+    const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+    return pkg.private !== true && Boolean(pkg.bin || pkg.main);
+  } catch {
+    return false;
+  }
+}
+
+/** Lockfile-detected package manager (KJC-BUG-0131): npm ci kills pnpm/yarn CI. */
+export function detectPackageManager(projectDir) {
+  if (existsSync(join(projectDir, "pnpm-lock.yaml"))) return "pnpm";
+  if (existsSync(join(projectDir, "yarn.lock"))) return "yarn";
+  return "npm";
+}
+
+// KJC-BUG-0137: the JS quality workflow only carries a lint step when the
+// project HAS a lint script — and then it enforces (no --if-present).
+function hasLintScript(projectDir) {
+  try {
+    return Boolean(JSON.parse(readFileSync(join(projectDir, "package.json"), "utf8")).scripts?.lint);
+  } catch {
+    return false;
+  }
+}
+
+export function installWorkflows({
+  projectDir = process.cwd(),
+  language = null,
+  profile = "standard",
+  mutation = false,
+  dryRun = false,
+  kjVersion = null,
+} = {}) {
+  const dir = join(projectDir, WORKFLOWS_DIR);
+  const pm = detectPackageManager(projectDir);
+  const quality = qualityWorkflowFor(language, pm, hasLintScript(projectDir));
+  const extras = extraWorkflowsFor({ profile, publishable: isPublishableNpm(projectDir), pm });
+  const mut = mutation ? mutationWorkflowFor(language, pm) : null;
+  // PL-C: el tier C solo existe donde el proyecto DECLARA policy. Versión a
+  // pinear: la plumbeada por el CLI (SEA) o la propia; "latest" es último
+  // recurso inalcanzable en los caminos reales.
+  const pinned = kjVersion ?? ownPkg()?.version ?? "latest";
+  const policy = existsSync(join(projectDir, ".karajan", "policy.yml"))
+    ? { file: "kj-policy.yml", blockId: "wf-policy", body: policyWorkflowFor(pinned, ownPkg()?.name ?? "karajan-code") }
+    : null;
+  const all = [...WORKFLOWS, ...(quality ? [quality] : []), ...extras, ...(mut ? [mut] : []), ...(policy ? [policy] : [])];
+  const results = [];
+  for (const wf of all) {
+    const target = join(dir, wf.file);
+    const label = join(WORKFLOWS_DIR, wf.file);
+    const exists = existsSync(target);
+    const source = exists ? readFileSync(target, "utf8") : "";
+    if (exists && !source.includes(`kj:managed:${wf.blockId}`)) {
+      results.push({ file: label, action: "skipped" });
+      continue;
+    }
+    const { content, action } = upsertManagedBlock({
+      source,
+      blockId: wf.blockId,
+      version: BLOCK_VERSION,
+      body: wf.body,
+      style: "hash",
+    });
+    if (!dryRun && action !== "unchanged") {
+      mkdirSync(dir, { recursive: true });
+      // Newline final SIEMPRE: prettier (y POSIX) lo exigen y el bloque
+      // gestionado no lo garantiza — sin esto, el format-check del propio
+      // pre-commit rechaza el fichero recién generado.
+      writeFileSync(target, content.endsWith("\n") ? content : `${content}\n`);
+    }
+    results.push({ file: label, action });
+  }
+  return { dryRun, workflows: results };
+}

package/src/harden/workflow-templates.js

@@ -0,0 +1,285 @@
+/**
+ * CI workflow templates for `kj harden` (KJC-TSK-0557).
+ *
+ * Generic, language-agnostic GitHub Actions that `kj harden` seeds into a
+ * target repo's `.github/workflows/`. Bodies are plain strings (NOT template
+ * literals) so the `${{ … }}` GitHub expressions survive verbatim.
+ */
+
+// Blocks AI self-attribution in PR commit messages. Pure bash + grep, no Node.
+// Pins github.base_ref to an env var (never interpolated into the run block).
+// KJC-BUG-0136 (issue #1374): actions pinned to full commit SHAs — a
+// mutable tag lets its owner run arbitrary code inside EVERY hardened
+// repo's CI, with access to the workflow's secrets; 5 of this project's 7
+// audit findings came from files kj itself generated. The version rides in
+// a comment (the practice kj audit demands). To bump one:
+//   gh api repos/<owner>/<repo>/commits/<tag> --jq .sha
+export const PINNED_ACTIONS = {
+  checkout: "actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4",
+  setupNode: "actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4",
+  setupPython: "actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5",
+  setupGo: "actions/setup-go@40f1582b2485089dde7abd97c1529aa768e1baff # v5",
+  setupPhp: "shivammathur/setup-php@f3e473d116dcccaddc5834248c87452386958240 # v2",
+};
+
+export const NO_AI_ATTRIBUTION_WORKFLOW = [
+  "name: Block AI attribution",
+  "on:",
+  "  pull_request:",
+  "    branches: [main]",
+  "permissions:",
+  "  contents: read",
+  "jobs:",
+  "  scan:",
+  "    runs-on: ubuntu-latest",
+  "    steps:",
+  `      - uses: ${PINNED_ACTIONS.checkout}`,
+  "        with:",
+  "          fetch-depth: 0",
+  "      - name: Scan commit messages for AI attribution",
+  "        env:",
+  "          BASE_REF: ${{ github.base_ref }}",
+  "        run: |",
+  '          msgs=$(git log --format=%B "origin/${BASE_REF}...HEAD" || true)',
+  "          pat='co-authored-by:.*(claude|anthropic|openai|chatgpt|gpt-[0-9]|copilot|gemini|cursor|windsurf|codeium|deepseek)'",
+  "          pat=\"$pat|(generated|written|authored|assisted|powered) (by|with|using) .*(claude|anthropic|openai|copilot|gemini)\"",
+  '          if printf "%s" "$msgs" | grep -qiE "$pat"; then',
+  '            echo "::error::AI attribution detected in commit messages"; exit 1',
+  "          fi",
+  '          echo "AI attribution scan: clean"',
+].join("\n");
+
+/** Universal workflows (every stack). style:hash ⇒ marker in YAML comments. */
+export const WORKFLOWS = [
+  { file: "kj-no-ai-attribution.yml", blockId: "wf-no-ai", body: NO_AI_ATTRIBUTION_WORKFLOW },
+];
+
+// PL-C (KJC-TSK-0735) — tier C del ADR 0001: re-check merge-blocking en CI
+// (cubre el hook local manipulado). Solo se siembra con policy declarada;
+// npx PINEADO a la versión del kj que corrió harden — jamás @latest en CI.
+export const policyWorkflowFor = (kjVersion, kjName = "karajan-code") => [
+  "name: Policy",
+  "on:",
+  "  pull_request:",
+  "permissions:",
+  "  contents: read",
+  "jobs:",
+  "  policy-check:",
+  "    runs-on: ubuntu-latest",
+  "    steps:",
+  `      - uses: ${PINNED_ACTIONS.checkout}`,
+  "        with:",
+  "          fetch-depth: 0",
+  `      - uses: ${PINNED_ACTIONS.setupNode}`,
+  "        with:",
+  "          node-version: 22",
+  "      - name: kj policy check (strict) on the PR diff",
+  "        env:",
+  "          BASE_REF: ${{ github.base_ref }}",
+  "        run: |",
+  `          if [ -f bin/kj.js ]; then npm ci --ignore-scripts && KJ="node bin/kj.js"; else KJ="npx --yes ${kjName}@${kjVersion}"; fi`,
+  '          $KJ policy check --range "origin/${BASE_REF}...HEAD" --strict',
+  "", // línea en blanco pre-marcador: prettier la exige tras un block scalar
+].join("\n");
+
+const header = (steps) =>
+  [
+    "name: Quality",
+    "on:",
+    "  pull_request:",
+    "    branches: [main]",
+    "jobs:",
+    "  quality:",
+    "    runs-on: ubuntu-latest",
+    "    steps:",
+    `      - uses: ${PINNED_ACTIONS.checkout}`,
+    ...steps,
+  ].join("\n");
+
+// Per-package-manager commands (KJC-BUG-0131, issue #1330): `npm ci` in a
+// pnpm/yarn repo dies with EUSAGE (no package-lock.json). corepack ships with
+// Node 22 and resolves the right pnpm/yarn from `packageManager` — no
+// third-party action. Yarn scripts run through `npm run` (scripts don't touch
+// the lockfile). Lint ENFORCES — never --if-present: a step that passes when
+// its script is missing protects nothing (KJC-BUG-0137, issue #1357); the
+// engine omits the step instead when the project has no lint script.
+export const PM_COMMANDS = {
+  npm: { setup: [], install: "npm ci", lint: "npm run -s lint", test: "npm test" },
+  pnpm: {
+    setup: ["      - run: corepack enable"],
+    install: "pnpm install --frozen-lockfile",
+    lint: "pnpm run -s lint",
+    test: "pnpm test",
+  },
+  yarn: {
+    setup: ["      - run: corepack enable"],
+    install: "yarn install --frozen-lockfile",
+    lint: "npm run -s lint",
+    test: "yarn test",
+  },
+};
+
+const nodeSetupSteps = (pm) => [
+  `      - uses: ${PINNED_ACTIONS.setupNode}`,
+  "        with:",
+  "          node-version: 22",
+  ...(PM_COMMANDS[pm] || PM_COMMANDS.npm).setup,
+  `      - run: ${(PM_COMMANDS[pm] || PM_COMMANDS.npm).install}`,
+];
+
+const QUALITY_BY_LANGUAGE = {
+  python: header([
+    `      - uses: ${PINNED_ACTIONS.setupPython}`,
+    "        with:",
+    "          python-version: '3.12'",
+    "      - run: pip install ruff pytest",
+    "      - run: ruff check .",
+    "      - run: pytest",
+  ]),
+  go: header([
+    `      - uses: ${PINNED_ACTIONS.setupGo}`,
+    "        with:",
+    "          go-version: stable",
+    "      - run: go vet ./...",
+    "      - run: go test ./...",
+  ]),
+  php: header([
+    `      - uses: ${PINNED_ACTIONS.setupPhp}`,
+    "        with:",
+    "          php-version: '8.3'",
+    "      - run: composer install --no-interaction --no-progress",
+    "      - run: vendor/bin/phpstan analyse --no-progress",
+    "      - run: vendor/bin/phpunit",
+  ]),
+};
+/**
+ * Stack-aware Quality workflow entry, or null for an unknown language.
+ * `lint:false` drops the JS lint step entirely (project has no lint script,
+ * KJC-BUG-0137) — mirroring the local hook, which also omits it.
+ */
+export function qualityWorkflowFor(language, pm = "npm", lint = true) {
+  const c = PM_COMMANDS[pm] || PM_COMMANDS.npm;
+  const body =
+    language === "javascript" || language === "typescript"
+      ? header([...nodeSetupSteps(pm), ...(lint ? [`      - run: ${c.lint}`] : []), `      - run: ${c.test}`])
+      : QUALITY_BY_LANGUAGE[language];
+  return body ? { file: "kj-quality.yml", blockId: "wf-quality", body } : null;
+}
+
+// Caps the net LOC delta of a PR (strict profile only — it is opinionated).
+export const SHRINK_BUDGET_WORKFLOW = [
+  "name: Shrink budget",
+  "on:",
+  "  pull_request:",
+  "    branches: [main]",
+  "permissions:",
+  "  contents: read",
+  "jobs:",
+  "  budget:",
+  "    runs-on: ubuntu-latest",
+  '    env: { LOC_LIMIT: "200" }',
+  "    steps:",
+  `      - uses: ${PINNED_ACTIONS.checkout}`,
+  "        with:",
+  "          fetch-depth: 0",
+  "      - name: Net LOC delta within budget",
+  "        env:",
+  "          BASE_REF: ${{ github.base_ref }}",
+  "        run: |",
+  "          d=$(git diff --numstat \"origin/${BASE_REF}...HEAD\" -- . ':!**/*.md' ':!*.lock' ':!package-lock.json' || true)",
+  '          a=$(printf "%s\\n" "$d" | awk \'$1!="-"{s+=$1}END{print s+0}\')',
+  '          r=$(printf "%s\\n" "$d" | awk \'$2!="-"{s+=$2}END{print s+0}\')',
+  '          net=$((a - r)); echo "net=$net (limit=$LOC_LIMIT)"',
+  '          if [ "$net" -gt "$LOC_LIMIT" ]; then echo "::error::PR adds $net net lines (limit $LOC_LIMIT)"; exit 1; fi',
+].join("\n");
+
+// Packs the tarball and installs it clean — only for publishable npm packages.
+// `npm pack`/`npm install <tarball>` need no lockfile, so only the dependency
+// install step is package-manager-aware.
+export const packSmokeWorkflow = (pm = "npm") =>
+  [
+    "name: Pack smoke",
+    "on:",
+    "  pull_request:",
+    "    branches: [main]",
+    "permissions:",
+    "  contents: read",
+    "jobs:",
+    "  pack-smoke:",
+    "    runs-on: ubuntu-latest",
+    "    steps:",
+    `      - uses: ${PINNED_ACTIONS.checkout}`,
+    ...nodeSetupSteps(pm),
+    "      - name: Pack and install the tarball clean",
+    "        run: |",
+    "          tgz=$(npm pack --silent)",
+    "          dir=$(mktemp -d)",
+    '          npm install --prefix "$dir" "$PWD/$tgz" --no-audit --no-fund',
+    '          echo "Tarball installs clean: $tgz"',
+  ].join("\n");
+
+// Opt-in nightly/manual mutation audit (KJC-TSK-0589). NEVER a PR gate: it runs
+// on a weekly schedule + manual dispatch, and the mutate step is non-blocking
+// (continue-on-error) so a red run never nags. Only stacks whose `kj mutate`
+// yields a JSON report (stryker/mutmut/infection) get a workflow — no silent
+// scaffold for tools that can't report yet.
+const MUTATION_TOOLCHAIN = {
+  javascript: "node", // resolved per package manager in mutationWorkflowFor
+  python: [
+    `      - uses: ${PINNED_ACTIONS.setupPython}`,
+    "        with:",
+    "          python-version: '3.12'",
+    "      - run: pip install mutmut pytest",
+  ],
+  php: [
+    `      - uses: ${PINNED_ACTIONS.setupPhp}`,
+    "        with:",
+    "          php-version: '8.3'",
+    "      - run: composer install --no-interaction --no-progress",
+  ],
+};
+MUTATION_TOOLCHAIN.typescript = MUTATION_TOOLCHAIN.javascript;
+
+/** Opt-in mutation workflow entry, or null for a stack without a JSON report. */
+export function mutationWorkflowFor(language, pm = "npm") {
+  const entry = MUTATION_TOOLCHAIN[language];
+  if (!entry) return null;
+  const c = PM_COMMANDS[pm] || PM_COMMANDS.npm;
+  const toolchain = entry === "node" ? [...c.setup, `      - run: ${c.install}`] : entry;
+  const body = [
+    "name: Mutation (nightly)",
+    "on:",
+    "  schedule:",
+    "    - cron: '0 4 * * 1'",
+    "  workflow_dispatch:",
+    "permissions:",
+    "  contents: read",
+    "jobs:",
+    "  mutation:",
+    "    runs-on: ubuntu-latest",
+    "    steps:",
+    `      - uses: ${PINNED_ACTIONS.checkout}`,
+    "        with:",
+    "          fetch-depth: 0",
+    `      - uses: ${PINNED_ACTIONS.setupNode}`,
+    "        with:",
+    "          node-version: 22",
+    ...toolchain,
+    "      - name: Mutation testing (advisory, never blocks a PR)",
+    "        continue-on-error: true",
+    "        run: npx --yes --package karajan-code kj mutate --since HEAD~1",
+  ].join("\n");
+  return { file: "kj-mutation.yml", blockId: "wf-mutation", body };
+}
+
+/** Conditional workflows: shrink-budget on strict, pack-smoke when publishable. */
+export function extraWorkflowsFor({ profile = "standard", publishable = false, pm = "npm" } = {}) {
+  const extras = [];
+  if (profile === "strict") {
+    extras.push({ file: "kj-shrink-budget.yml", blockId: "wf-shrink", body: SHRINK_BUDGET_WORKFLOW });
+  }
+  if (publishable) {
+    extras.push({ file: "kj-pack-smoke.yml", blockId: "wf-pack-smoke", body: packSmokeWorkflow(pm) });
+  }
+  return extras;
+}

package/src/hu/acceptance-runner.js

@@ -0,0 +1,138 @@
+/**
+ * HU Acceptance Test Runner.
+ * Executes acceptance_tests commands for an HU and returns structured results.
+ * Brain uses this to determine if an HU is done (all pass) or needs fixing (with diagnostics).
+ */
+import { runCommand } from "../utils/process.js";
+
+/**
+ * Run a single acceptance test command.
+ * @param {string} cmd - Shell command to execute
+ * @param {string} cwd - Working directory
+ * @param {number} [timeoutMs=30000] - Timeout per test
+ * @returns {Promise<{cmd: string, passed: boolean, output: string, exitCode: number}>}
+ */
+async function runSingleTest(cmd, cwd, timeoutMs = 30000, env = null) {
+  try {
+    const result = await runCommand("bash", ["-c", cmd], {
+      timeout: timeoutMs,
+      cwd,
+      // PAR-H (KJC-TSK-0631): lane env (KJ_LANE_SLOT / KJ_PORT_OFFSET) so
+      // tests that start services can offset their ports. execa merges
+      // this on top of process.env.
+      ...(env ? { env } : {})
+    });
+    const output = (result.stdout || "") + (result.stderr || "");
+    return {
+      cmd,
+      passed: result.exitCode === 0,
+      output: output.slice(-500), // last 500 chars for diagnostics
+      exitCode: result.exitCode
+    };
+  } catch (err) {
+    return {
+      cmd,
+      passed: false,
+      output: err.message?.slice(-500) || "Command timed out or crashed",
+      exitCode: -1
+    };
+  }
+}
+
+/**
+ * Run all acceptance tests for an HU.
+ *
+ * Accepts two shapes:
+ *   - Legacy: plain string shell command.
+ *   - v2.7.5: { type: "shell" | "gherkin", content, file? }
+ *
+ * Shell entries execute immediately (exit code 0 = pass). Gherkin entries
+ * cannot be executed directly — that's Phase 3 of tests-first where the
+ * tester role translates them into real code tests. Until then, we report
+ * them as "pending" and skip rather than failing the whole gate.
+ *
+ * @param {Array<string|object>} tests - Array of shell commands OR structured entries
+ * @param {string} cwd - Working directory
+ * @returns {Promise<{allPassed: boolean, results: object[], summary: string, diagnostics: string|null, pending: number}>}
+ */
+export async function runAcceptanceTests(tests, cwd, { env = null } = {}) {
+  if (!tests || tests.length === 0) {
+    return { allPassed: false, results: [], summary: "No acceptance tests defined", diagnostics: null, pending: 0 };
+  }
+
+  const results = [];
+  let pending = 0;
+  for (const entry of tests) {
+    let type = "shell";
+    let cmd;
+    if (typeof entry === "string") {
+      cmd = entry;
+    } else if (entry && typeof entry === "object" && typeof entry.content === "string") {
+      type = entry.type === "gherkin" ? "gherkin" : "shell";
+      cmd = entry.content;
+    } else {
+      results.push({ cmd: JSON.stringify(entry), passed: false, output: "Malformed acceptance_test entry", exitCode: -2, type: "invalid" });
+      continue;
+    }
+    if (type === "gherkin") {
+      // Gherkin entries need a translator (Phase 3). Mark them pending
+      // so the coder/tester sees they haven't been validated yet —
+      // better than silently passing (would lie) or hard-failing
+      // (would block the whole pipeline).
+      pending += 1;
+      results.push({
+        cmd,
+        passed: false,
+        output: "Gherkin test not yet executable (awaits tester translation — Phase 3)",
+        exitCode: 0,
+        type: "gherkin",
+        pending: true,
+      });
+      continue;
+    }
+    const result = await runSingleTest(cmd, cwd, 30000, env);
+    results.push({ ...result, type: "shell" });
+  }
+
+  const executedResults = results.filter((r) => !r.pending);
+  const passed = executedResults.filter((r) => r.passed);
+  const failed = executedResults.filter((r) => !r.passed);
+  const allPassed = failed.length === 0;
+
+  const shellSummary = `${passed.length}/${executedResults.length} shell tests passed`;
+  const summary = pending > 0
+    ? `${shellSummary}, ${pending} gherkin test(s) pending translation`
+    : shellSummary;
+
+  let diagnostics = null;
+  if (!allPassed) {
+    diagnostics = failed.map((f) =>
+      `FAIL: ${f.cmd}\n  exit=${f.exitCode}\n  output: ${f.output.trim().split("\n").slice(-5).join("\n  ")}`
+    ).join("\n\n");
+  }
+
+  return { allPassed, results, summary, diagnostics, pending };
+}
+
+/**
+ * Build a concrete diagnostic prompt for Brain to send to the coder.
+ * Reads the failed test outputs and produces actionable instructions.
+ * @param {object[]} failedResults - Array of failed test results
+ * @returns {string} Prompt for the coder with concrete fix instructions
+ */
+export function buildDiagnosticPrompt(failedResults) {
+  if (!failedResults || failedResults.length === 0) return "";
+  const lines = ["The following acceptance tests FAILED. Fix each one:", ""];
+  for (const f of failedResults) {
+    lines.push(`❌ Command: ${f.cmd}`);
+    lines.push(`   Exit code: ${f.exitCode}`);
+    const lastLines = f.output.trim().split("\n").slice(-8);
+    lines.push(`   Last output:`);
+    for (const l of lastLines) {
+      lines.push(`     ${l}`);
+    }
+    lines.push("");
+  }
+  lines.push("Fix ALL failing tests. Run each command yourself to verify before finishing.");
+  return lines.join("\n");
+}