@ngockhoale/ukit 2.6.6 → 2.6.8

package/manifests/instructionRules.yaml

@@ -0,0 +1,383 @@
+version: 1
+generated: false
+description: >-
+  Canonical rule-ID catalog for the root instruction contracts. Marker comments
+  <!-- RULE: ID --> tag normative behavior; semantic tests prove delivery.
+# marker_in values are drawn from the fixed set of the four marker-bearing
+# contract files {templates/CLAUDE.md, templates/AGENTS.md, CLAUDE.md, AGENTS.md}.
+# templates/.omp/RULES.md and .omp/RULES.md are marker-free by SPEC §7.1 policy
+# and must never appear here.
+# DEVIATION from SPEC §7.2 table: OWN-01 is marker_in: AGENTS set only (not
+# SHARED) — its anchor `PROJECT_IMPORTANT.md` does not exist in the CLAUDE
+# files, and markers are comment-only (no prose edits allowed). AGENTS-set
+# coverage matches the HOST-OC-01/HOST-OWN-01 rows that tag the same overlay.
+# paths (optional, DOC-302): list of repo-relative glob strings naming the
+# work-tree scope a rule applies to. `**` = any depth, `*` = one segment,
+# `?` = one char; `/`-separated, no leading `/`, no `..`, no backslashes.
+# Absent = file-scoped only (marker_in governs rendered coverage; paths is
+# metadata for future router/doc tooling, consumed by rulesForPath).
+rules:
+  - id: CORE-01
+    title: One remembered command — ukit install
+    kind: critical
+    statement: >-
+      Human-facing UKit workflow collapses to one remembered command:
+      `ukit install`; after install, work in natural language inside the
+      supported harnesses.
+    marker_in: [templates/CLAUDE.md, templates/AGENTS.md, CLAUDE.md, AGENTS.md]
+    anchor: 'ukit install'
+  - id: CORE-02
+    title: Quality first, then speed, then token discipline
+    kind: supporting
+    statement: >-
+      Ordering of priorities for all work: quality first, then speed, then
+      token discipline.
+    marker_in: [templates/CLAUDE.md, templates/AGENTS.md, CLAUDE.md, AGENTS.md]
+  - id: CLS-01
+    title: Trivial lane acts directly
+    kind: critical
+    statement: >-
+      Trivial tasks (typo, label, small rename, spacing, toggle flag, obvious
+      config change) act directly — no doc reads, planning, index, or agents.
+    marker_in: [templates/CLAUDE.md, templates/AGENTS.md, CLAUDE.md, AGENTS.md]
+    anchor: 'Act directly'
+  - id: CLS-02
+    title: Simple lane pulls smallest useful context
+    kind: critical
+    statement: >-
+      Simple tasks (1-2 files, clear scope, existing pattern) are handled
+      directly, pulling only the smallest useful context.
+    marker_in: [templates/CLAUDE.md, templates/AGENTS.md, CLAUDE.md, AGENTS.md]
+    anchor: 'smallest useful context'
+  - id: CLS-03
+    title: Non-trivial lane verifies harder
+    kind: supporting
+    statement: >-
+      Non-trivial/risky tasks read deeper, verify harder, and use the
+      index-first loop then skill activation then targeted verification.
+    marker_in: [templates/CLAUDE.md, templates/AGENTS.md, CLAUDE.md, AGENTS.md]
+  - id: EXEC-01
+    title: Continue until write evidence or blocker
+    kind: critical
+    statement: >-
+      For explicit implement/apply/fix requests, continue until the actual edit
+      is made or a real blocker is found; never stop after read-only steps.
+    marker_in: [templates/CLAUDE.md, templates/AGENTS.md, CLAUDE.md, AGENTS.md]
+    anchor: 'actual edit is made'
+  - id: EXEC-02
+    title: No done-claims without Edit/Write evidence
+    kind: critical
+    statement: >-
+      Completion wording requires concrete Edit/Write evidence in the current
+      turn, plus verification when the scope is risky.
+    marker_in: [templates/CLAUDE.md, templates/AGENTS.md, CLAUDE.md, AGENTS.md]
+    anchor: 'concrete Edit/Write evidence'
+  - id: EXEC-03
+    title: Routed continuation is not a stopping point
+    kind: supporting
+    statement: >-
+      Routed states like pull-indexed-context or continuation-required are
+      internal continuation steps; finish the named milestone before widening.
+    marker_in: [templates/CLAUDE.md, templates/AGENTS.md, CLAUDE.md, AGENTS.md]
+  - id: EXEC-04
+    title: Every stop names its reason
+    kind: critical
+    statement: >-
+      When a turn ends on a user-only action, open the reply with a
+      `WAITING ON YOU:` line and schedule a one-shot wakeup when available.
+    marker_in: [templates/CLAUDE.md, templates/AGENTS.md, CLAUDE.md, AGENTS.md]
+    anchor: 'WAITING ON YOU'
+  - id: LONG-01
+    title: LAND one thing, DEFER the rest, DELEGATE broad work
+    kind: supporting
+    statement: >-
+      Near token-cap, land one in-flight item end-to-end, defer the rest into
+      docs/STATUS.md or bounded handoff tasks, delegate broad work to subagents.
+    marker_in: [templates/CLAUDE.md, templates/AGENTS.md, CLAUDE.md, AGENTS.md]
+  - id: LONG-02
+    title: Post-compact continuity from disk state
+    kind: supporting
+    statement: >-
+      After any compact or handoff, continue from persisted disk state without
+      rereading pre-compact context; delegate and keep replies short.
+    marker_in: [templates/CLAUDE.md, templates/AGENTS.md, CLAUDE.md, AGENTS.md]
+  - id: IDX-01
+    title: Check index freshness before code context
+    kind: critical
+    statement: >-
+      For tasks needing code context, check the index is fresh and refresh it
+      when stale or missing.
+    marker_in: [templates/CLAUDE.md, templates/AGENTS.md, CLAUDE.md, AGENTS.md]
+    anchor: 'index is fresh'
+  - id: IDX-02
+    title: Open top 1-3 suspect files first
+    kind: critical
+    statement: >-
+      Open only the top 1-3 suspect files first, then widen if needed; use the
+      outline block to jump straight to the relevant region.
+    marker_in: [templates/CLAUDE.md, templates/AGENTS.md, CLAUDE.md, AGENTS.md]
+    anchor: 'top 1-3 suspect files'
+  - id: IDX-03
+    title: Outlines locate code; code to be changed must still be read
+    kind: critical
+    statement: >-
+      The outline locates code but does not describe behaviour; any code about
+      to be changed must still be read.
+    marker_in: [templates/CLAUDE.md, templates/AGENTS.md, CLAUDE.md, AGENTS.md]
+    anchor: 'must still be read'
+  - id: SKILL-01
+    title: Auto-activate the matching skill
+    kind: critical
+    statement: >-
+      On every non-trivial task, inspect installed project-local skills and
+      auto-activate the matching skill immediately; end users should not need
+      to know skill names.
+    marker_in: [templates/CLAUDE.md, templates/AGENTS.md, CLAUDE.md, AGENTS.md]
+    anchor: 'auto-activate the matching skill'
+  - id: SKILL-02
+    title: Smallest effective skill set
+    kind: supporting
+    statement: >-
+      Use the smallest effective set of skills, usually 1-2.
+    marker_in: [templates/CLAUDE.md, templates/AGENTS.md, CLAUDE.md, AGENTS.md]
+  - id: SKILL-03
+    title: Upgrade skill choice on sharper evidence
+    kind: supporting
+    statement: >-
+      If evidence becomes more specific than the original prompt, upgrade the
+      active skill choice immediately.
+    marker_in: [templates/CLAUDE.md, templates/AGENTS.md, CLAUDE.md, AGENTS.md]
+  - id: HELP-01
+    title: Prefer internal helper commands for routing/context/verify
+    kind: supporting
+    statement: >-
+      Prefer the index helper scripts (route-task, resolve-context,
+      verify-context) for routing, related-file context, and verification.
+    marker_in: [templates/CLAUDE.md, templates/AGENTS.md, CLAUDE.md, AGENTS.md]
+  - id: HELP-02
+    title: Never ask contributors to run internal helpers
+    kind: critical
+    statement: >-
+      Do not ask normal contributors to run internal helper commands or
+      memorize maintainer commands; run them yourself or tell them to rerun
+      `ukit install`.
+    marker_in: [templates/CLAUDE.md, templates/AGENTS.md, CLAUDE.md, AGENTS.md]
+    anchor: 'Do not ask normal contributors'
+  - id: OWN-01
+    title: PROJECT_IMPORTANT.md is the canonical owner-instruction source
+    kind: critical
+    statement: >-
+      Read and follow the root PROJECT_IMPORTANT.md before project work; it is
+      the canonical project-owner instruction source.
+    marker_in: [templates/AGENTS.md, AGENTS.md]
+    anchor: 'PROJECT_IMPORTANT.md'
+  - id: SAFE-01
+    title: Preserve byte-level file details on edit
+    kind: critical
+    statement: >-
+      Preserve UTF-8 BOM/no-BOM and LF/CRLF for existing multilingual or
+      user-authored files.
+    marker_in: [templates/CLAUDE.md, templates/AGENTS.md, CLAUDE.md, AGENTS.md]
+    anchor: 'BOM/no-BOM'
+  - id: SAFE-02
+    title: Prefer unique current-file anchors for risky edits
+    kind: critical
+    statement: >-
+      For risky/shared/large edits, prefer unique current-file anchors over
+      line numbers or stale pasted blocks.
+    marker_in: [templates/CLAUDE.md, templates/AGENTS.md, CLAUDE.md, AGENTS.md]
+    anchor: 'unique current-file anchors'
+  - id: SAFE-03
+    title: Ask on missing or ambiguous stale specs
+    kind: supporting
+    statement: >-
+      Do not silently merge stale specs: if old_string is missing or ambiguous,
+      re-read current source and ask whether to apply, adapt, or skip.
+    marker_in: [templates/CLAUDE.md, templates/AGENTS.md, CLAUDE.md, AGENTS.md]
+  - id: CTX-01
+    title: Deterministic segment bytes
+    kind: critical
+    statement: >-
+      Keep prompt-segment bytes deterministic so provider prompt prefixes can
+      be reused.
+    marker_in: [templates/CLAUDE.md, templates/AGENTS.md, CLAUDE.md, AGENTS.md]
+    anchor: 'CTX-01'
+  - id: CTX-02
+    title: Keep roles and order
+    kind: critical
+    statement: >-
+      Keep message roles and order stable across calls.
+    marker_in: [templates/CLAUDE.md, templates/AGENTS.md, CLAUDE.md, AGENTS.md]
+    anchor: 'CTX-02'
+  - id: CTX-03
+    title: Keep tool IDs and continuation state
+    kind: critical
+    statement: >-
+      Keep tool IDs and continuation state stable for prefix reuse.
+    marker_in: [templates/CLAUDE.md, templates/AGENTS.md, CLAUDE.md, AGENTS.md]
+    anchor: 'CTX-03'
+  - id: CTX-04
+    title: No clock/random IDs in static blocks
+    kind: critical
+    statement: >-
+      Static prompt blocks must not contain clock values or random IDs.
+    marker_in: [templates/CLAUDE.md, templates/AGENTS.md, CLAUDE.md, AGENTS.md]
+    anchor: 'CTX-04'
+  - id: CTX-05
+    title: Compaction starts a new epoch
+    kind: critical
+    statement: >-
+      Compaction starts a new cache epoch; do not expect prefix reuse across it.
+    marker_in: [templates/CLAUDE.md, templates/AGENTS.md, CLAUDE.md, AGENTS.md]
+    anchor: 'CTX-05'
+  - id: CTX-06
+    title: Never change data to match a cache
+    kind: critical
+    statement: >-
+      Never mutate data to make it match a cache entry.
+    marker_in: [templates/CLAUDE.md, templates/AGENTS.md, CLAUDE.md, AGENTS.md]
+    anchor: 'CTX-06'
+  - id: CTX-07
+    title: No unconfirmed cache fields
+    kind: critical
+    statement: >-
+      Do not rely on cache fields that have not been confirmed for the route in
+      use.
+    marker_in: [templates/CLAUDE.md, templates/AGENTS.md, CLAUDE.md, AGENTS.md]
+    anchor: 'CTX-07'
+  - id: CTX-08
+    title: Tool-result reuse needs valid freshness
+    kind: critical
+    statement: >-
+      Reuse of tool results requires valid freshness.
+    marker_in: [templates/CLAUDE.md, templates/AGENTS.md, CLAUDE.md, AGENTS.md]
+    anchor: 'CTX-08'
+  - id: CTX-09
+    title: Missing usage is unknown, not zero
+    kind: critical
+    statement: >-
+      Missing cache-usage reporting means unknown, not zero savings.
+    marker_in: [templates/CLAUDE.md, templates/AGENTS.md, CLAUDE.md, AGENTS.md]
+    anchor: 'CTX-09'
+  - id: CTX-10
+    title: Never cut a required check to reduce calls
+    kind: critical
+    statement: >-
+      Never skip a required verification or check just to reduce call count.
+    marker_in: [templates/CLAUDE.md, templates/AGENTS.md, CLAUDE.md, AGENTS.md]
+    anchor: 'CTX-10'
+  - id: HAND-01
+    title: Handoff Quality Gate is opt-in via docs/AI_HANDOFF
+    kind: supporting
+    statement: >-
+      The handoff quality gate activates only when a task goes through
+      docs/AI_HANDOFF; daily prompts keep the old flow.
+    marker_in: [templates/CLAUDE.md, templates/AGENTS.md, CLAUDE.md, AGENTS.md]
+    paths: [docs/AI_HANDOFF/**]
+  - id: HAND-02
+    title: RUN.md is the authoritative handoff run cursor
+    kind: critical
+    statement: >-
+      docs/AI_HANDOFF/RUN.md is the authoritative run cursor; only the
+      HANDOFF FULLSTACK COMPLETE/BLOCKED markers after Phase done/blocked end
+      a run.
+    marker_in: [templates/CLAUDE.md, templates/AGENTS.md, CLAUDE.md, AGENTS.md]
+    anchor: 'RUN.md'
+    paths: [docs/AI_HANDOFF/**]
+  - id: BUDGET-01
+    title: Context budget per task class
+    kind: critical
+    statement: >-
+      Context + verification budget rows: Trivial reads no docs, Simple reads
+      MEMORY only, Non-trivial adds PROJECT and CODE_MAP.
+    marker_in: [templates/CLAUDE.md, templates/AGENTS.md, CLAUDE.md, AGENTS.md]
+    anchor: '**Trivial**: no docs'
+  - id: BUDGET-02
+    title: STATUS.md only for open-ended or continuation prompts
+    kind: supporting
+    statement: >-
+      docs/STATUS.md is used for open-ended status/continue prompts or
+      meaningful continuation context; stale status is orientation only.
+    marker_in: [templates/CLAUDE.md, templates/AGENTS.md, CLAUDE.md, AGENTS.md]
+  - id: BUDGET-03
+    title: WORKLOG recent entries only
+    kind: supporting
+    statement: >-
+      docs/WORKLOG.md is read for recent relevant entries only; archive oldest
+      entries when over limits.
+    marker_in: [templates/CLAUDE.md, templates/AGENTS.md, CLAUDE.md, AGENTS.md]
+  - id: STATUS-01
+    title: STATUS.md is not source truth
+    kind: supporting
+    statement: >-
+      docs/STATUS.md captures compact current state; it is not source truth and
+      must not replace source/index-first investigation.
+    marker_in: [templates/CLAUDE.md, templates/AGENTS.md, CLAUDE.md, AGENTS.md]
+  - id: SUBAG-01
+    title: Delegate only on meaningful context or parallel gains
+    kind: supporting
+    statement: >-
+      Keep direct execution as default for trivial/simple work; delegate only
+      when it shrinks context or enables useful parallel progress.
+    marker_in: [templates/CLAUDE.md, templates/AGENTS.md, CLAUDE.md, AGENTS.md]
+  - id: SUBAG-02
+    title: Small-task maintainer is a sidecar lane
+    kind: supporting
+    statement: >-
+      The ukit-small-task-maintainer subagent handles safe/reversible UKit
+      chores as a sidecar lane and hands risky work back to the main model.
+    marker_in: [templates/CLAUDE.md, templates/AGENTS.md, CLAUDE.md, AGENTS.md]
+  - id: AUTO-01
+    title: autonomy.level controls how much UKit acts without asking
+    kind: supporting
+    statement: >-
+      autonomy.level in .ukit/storage/config.json controls how much UKit acts
+      without asking first; end users should not need to change it.
+    marker_in: [templates/CLAUDE.md, templates/AGENTS.md, CLAUDE.md, AGENTS.md]
+  - id: TIER-01
+    title: Tiers bind through agent definitions
+    kind: critical
+    statement: >-
+      A model tier takes effect only when work is handed to an agent whose own
+      definition binds that model; the main session model never changes
+      mid-turn.
+    marker_in: [templates/CLAUDE.md, templates/AGENTS.md, CLAUDE.md, AGENTS.md]
+    anchor: 'model:'
+  - id: TIER-02
+    title: Escalate one tier after repeated failure
+    kind: supporting
+    statement: >-
+      When the same file or symbol fails debugLoopThreshold times in one
+      session, route the next attempt one tier higher, capped at smart.
+    marker_in: [templates/CLAUDE.md, templates/AGENTS.md, CLAUDE.md, AGENTS.md]
+  - id: HOST-OC-01
+    title: OpenCode must explicitly read the triggered SKILL.md
+    kind: critical
+    statement: >-
+      OpenCode reads AGENTS.md at session start only and does not auto-load
+      skills; the model must explicitly read the triggered SKILL.md.
+    marker_in: [templates/AGENTS.md, AGENTS.md]
+    anchor: 'read the triggered SKILL.md'
+  - id: HOST-OWN-01
+    title: Codex/OpenCode read the root owner instructions
+    kind: critical
+    statement: >-
+      When running in Codex or OpenCode, read and follow the root
+      PROJECT_IMPORTANT.md before doing project work.
+    marker_in: [templates/AGENTS.md, AGENTS.md]
+    anchor: 'read and follow the root'
+  - id: DURA-01
+    title: DuraOne skill activates only when installed
+    kind: supporting
+    statement: >-
+      The DuraOne skill is active only when the duraone pack is installed or
+      .claude/skills/duraone/SKILL.md exists; otherwise use generic standards.
+    marker_in: [templates/CLAUDE.md, templates/AGENTS.md, CLAUDE.md, AGENTS.md]
+  - id: FALLBACK-01
+    title: Missing/corrupt runtime → rerun ukit install
+    kind: critical
+    statement: >-
+      If the workspace needs a refresh or runtime files are missing or corrupt,
+      tell maintainers to rerun `ukit install`.
+    marker_in: [templates/CLAUDE.md, templates/AGENTS.md, CLAUDE.md, AGENTS.md]
+    anchor: 'rerun `ukit install`'

package/manifests/platform.full.yaml

@@ -246,6 +246,21 @@ items:
     packs:
       - core
 
+  # Shipped internal-orchestration detail (tier tables, subagent policy, sidecar review,
+  # small-task maintainer, helper/runtime/budget/status detail, DuraOne). Extracted from
+  # templates/instructions/core.md in DOC-104; `overwrite_with_backup` so `ukit update`
+  # refreshes it alongside the root contracts that point at it.
+  - id: docs-ukit-internals
+    type: config
+    sourceTemplate: docs/UKIT_INTERNALS.md
+    targetPath: docs/UKIT_INTERNALS.md
+    requires: []
+    mergeStrategy: overwrite_with_backup
+    variables: []
+    enabledByDefault: true
+    packs:
+      - core
+
   - id: core-skill-delivery
     type: skill
     sourceTemplate: .claude/skills/delivery/SKILL.md

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ngockhoale/ukit",
-  "version": "2.6.6",
+  "version": "2.6.8",
   "description": "Install/update an index-first AI workspace for Claude Code, OpenAI Codex, OpenCode, and omp (Oh My Pi).",
   "license": "MIT",
   "type": "module",
@@ -55,6 +55,8 @@
     "index:query": "node ./scripts/index/query-index.mjs",
     "bug:triage": "node ./scripts/bug/triage.mjs",
     "skill:audit": "node ./scripts/skill/audit-skill.mjs",
+    "docs:render": "node scripts/docs/render-instructions.mjs --write",
+    "docs:render:check": "node scripts/docs/render-instructions.mjs --check",
     "test:artifact": "vitest run tests/integration/packageArtifact.test.js tests/integration/artifactReferenceIntegrity.test.js",
     "test:release-core": "vitest run --exclude tests/integration/packageArtifact.test.js",
     "release:verify": "node ./scripts/release/verify-release.mjs",

package/scripts/bench/goldTasks.json

@@ -0,0 +1,38 @@
+[
+  {
+    "id": "gold-001-trivial-none",
+    "prompt": "fix typo in the header label",
+    "expectedMode": "none",
+    "expectedAnchors": [],
+    "maxTokens": 500
+  },
+  {
+    "id": "gold-002-peek",
+    "prompt": "peek src/cli/index.js",
+    "flags": { "mode": "peek" },
+    "expectedMode": "peek",
+    "expectedAnchors": ["src/cli/index.js"],
+    "maxTokens": 500
+  },
+  {
+    "id": "gold-003-targeted",
+    "prompt": "update src/cli/index.js to add a code command entry",
+    "expectedMode": "targeted",
+    "expectedAnchors": ["src/cli/index.js"],
+    "maxTokens": 2000
+  },
+  {
+    "id": "gold-004-impact",
+    "prompt": "build fails with TypeError in src/index/buildIndex.js",
+    "expectedMode": "impact",
+    "expectedAnchors": ["src/index/buildIndex.js"],
+    "maxTokens": 3000
+  },
+  {
+    "id": "gold-005-explore",
+    "prompt": "where is index freshness handled",
+    "expectedMode": "explore",
+    "expectedAnchors": [],
+    "maxTokens": 4000
+  }
+]

package/scripts/bench/runGold.mjs

@@ -0,0 +1,220 @@
+#!/usr/bin/env node
+// Gold-task benchmark harness skeleton (SPEC §10).
+// Loads a corpus of {id, prompt, expectedMode, expectedAnchors[], maxTokens}
+// cases, runs routeTask + compileContext per case, prints a scorecard with a
+// totals block, optionally writes an aggregated JSON scorecard (--json <path>),
+// and exits 0 only when every case passes. CI-3xx gates on the JSON summary.
+
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const REPO_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
+const DEFAULT_CORPUS = path.join(REPO_ROOT, 'scripts', 'bench', 'goldTasks.json');
+
+function parseArgs(argv) {
+  let corpusPath = DEFAULT_CORPUS;
+  let projectRoot = REPO_ROOT;
+  let jsonPath = null;
+  for (let i = 0; i < argv.length; i += 1) {
+    if (argv[i] === '--corpus') {
+      corpusPath = path.resolve(argv[i + 1] ?? corpusPath);
+      i += 1;
+    } else if (argv[i] === '--project') {
+      projectRoot = path.resolve(argv[i + 1] ?? projectRoot);
+      i += 1;
+    } else if (argv[i] === '--json') {
+      jsonPath = argv[i + 1] ? path.resolve(argv[i + 1]) : null;
+      i += 1;
+    }
+  }
+  return { corpusPath, projectRoot, jsonPath };
+}
+
+async function loadCorpus(corpusPath) {
+  const raw = await fs.readFile(corpusPath, 'utf8');
+  const cases = JSON.parse(raw);
+  if (!Array.isArray(cases)) {
+    throw new Error(`bench corpus must be a JSON array: ${corpusPath}`);
+  }
+  return cases;
+}
+
+function anchorPathsOf(packet) {
+  const fromAnchors = (packet.anchors ?? []).map((a) => a.path).filter(Boolean);
+  const fromEvidence = (packet.evidence ?? []).map((e) => e.path).filter(Boolean);
+  return new Set([...fromAnchors, ...fromEvidence]);
+}
+
+function normalizeMode(mode) {
+  return typeof mode === 'string' && mode.trim() !== '' ? mode.trim() : null;
+}
+
+export async function runGoldCase(projectRoot, testCase, { compileContext, routeTask }) {
+  const failures = [];
+  const expectedMode = normalizeMode(testCase.expectedMode);
+  const expectedAnchors = Array.isArray(testCase.expectedAnchors) ? testCase.expectedAnchors : [];
+  const maxTokens = typeof testCase.maxTokens === 'number' ? testCase.maxTokens : Infinity;
+
+  const routed = routeTask({
+    prompt: testCase.prompt ?? '',
+    hasError: testCase.hasError === true,
+    filesHinted: Array.isArray(testCase.filesHinted) ? testCase.filesHinted : undefined,
+    flags: testCase.flags && typeof testCase.flags === 'object' ? testCase.flags : {},
+  });
+
+  const packet = await compileContext(projectRoot, {
+    prompt: testCase.prompt ?? '',
+    hasError: testCase.hasError === true,
+    filesHinted: Array.isArray(testCase.filesHinted) ? testCase.filesHinted : undefined,
+    flags: testCase.flags && typeof testCase.flags === 'object' ? testCase.flags : {},
+  });
+
+  if (expectedMode && packet.task_type !== expectedMode) {
+    failures.push(`mode: expected ${expectedMode}, got ${packet.task_type || '(empty)'}`);
+  }
+
+  const anchorPaths = anchorPathsOf(packet);
+  const anchorHits = [];
+  const anchorMisses = [];
+  for (const expected of expectedAnchors) {
+    if (anchorPaths.has(expected)) {
+      anchorHits.push(expected);
+    } else {
+      anchorMisses.push(expected);
+      failures.push(`anchor missing: ${expected}`);
+    }
+  }
+
+  if (packet.budget?.used > maxTokens) {
+    failures.push(`budget: used ${packet.budget.used} > maxTokens ${maxTokens}`);
+  }
+
+  return {
+    id: testCase.id ?? '(unnamed)',
+    mode: packet.task_type,
+    expectedMode,
+    anchors: [...anchorPaths],
+    expectedAnchors,
+    anchorHits,
+    anchorMisses,
+    budgetUsed: packet.budget?.used ?? 0,
+    maxTokens,
+    routedMode: routed.mode,
+    pass: failures.length === 0,
+    failures,
+  };
+}
+
+export async function runGold({ projectRoot, corpusPath } = {}) {
+  const rootDir = projectRoot ?? REPO_ROOT;
+  const { compileContext } = await import(path.join(REPO_ROOT, 'src/core/codeintel/compiler.js'));
+  const { routeTask } = await import(path.join(REPO_ROOT, 'src/core/codeintel/router.js'));
+  const { buildCodeIndex } = await import(path.join(REPO_ROOT, 'src/index/buildIndex.js'));
+  const { INDEX_ARTIFACTS, getArtifactPath } = await import(path.join(REPO_ROOT, 'src/index/paths.js'));
+
+  // The bench needs an index to score anchors; build once when missing.
+  try {
+    await fs.stat(getArtifactPath(rootDir, INDEX_ARTIFACTS.files));
+  } catch {
+    console.log('[bench] index missing — building code index first');
+    await buildCodeIndex({ rootDir });
+  }
+
+  const cases = await loadCorpus(corpusPath ?? DEFAULT_CORPUS);
+  const results = [];
+  for (const testCase of cases) {
+    results.push(await runGoldCase(rootDir, testCase, { compileContext, routeTask }));
+  }
+  return { results, pass: results.every((r) => r.pass) };
+}
+
+/**
+ * Aggregate per-case results into a machine-readable summary for CI gating.
+ * Pooled anchor precision = hits/found, recall = hits/expected; cases with
+ * empty expectedAnchors contribute 0 to both denominators (excluded, not 1).
+ * @param {Array<object>} results per-case runGoldCase outputs
+ * @returns {{total:number, passed:number, passRate:number, modeAccuracy:number|null, anchorPrecision:number|null, anchorRecall:number|null, meanBudgetUsedPct:number|null}}
+ */
+export function summarizeResults(results) {
+  const total = results.length;
+  const passed = results.filter((r) => r.pass).length;
+  const passRate = total === 0 ? 0 : passed / total;
+
+  const withMode = results.filter((r) => r.expectedMode);
+  const modeCorrect = withMode.filter((r) => r.mode === r.expectedMode).length;
+  const modeAccuracy = withMode.length === 0 ? null : modeCorrect / withMode.length;
+
+  let hits = 0;
+  let found = 0;
+  let expected = 0;
+  for (const r of results) {
+    hits += Array.isArray(r.anchorHits) ? r.anchorHits.length : 0;
+    found += Array.isArray(r.anchors) ? r.anchors.length : 0;
+    expected += Array.isArray(r.expectedAnchors) ? r.expectedAnchors.length : 0;
+  }
+  const anchorPrecision = found === 0 ? null : hits / found;
+  const anchorRecall = expected === 0 ? null : hits / expected;
+
+  const budgeted = results.filter((r) => typeof r.maxTokens === 'number' && r.maxTokens > 0);
+  const meanBudgetUsedPct = budgeted.length === 0
+    ? null
+    : budgeted.reduce((acc, r) => acc + (r.budgetUsed ?? 0) / r.maxTokens, 0) / budgeted.length;
+
+  return { total, passed, passRate, modeAccuracy, anchorPrecision, anchorRecall, meanBudgetUsedPct };
+}
+
+/**
+ * Write { generatedAt, results, summary } scorecard JSON to `jsonPath` (pretty-printed).
+ * @param {string} jsonPath output file path
+ * @param {Array<object>} results per-case runGoldCase outputs
+ */
+export async function writeScorecardJson(jsonPath, results) {
+  const payload = {
+    generatedAt: new Date().toISOString(),
+    results,
+    summary: summarizeResults(results),
+  };
+  await fs.writeFile(jsonPath, `${JSON.stringify(payload, null, 2)}\n`, 'utf8');
+}
+
+function fmtPct(value) {
+  return value === null ? 'n/a' : `${(value * 100).toFixed(1)}%`;
+}
+
+export function printScorecard(results) {
+  console.log('id | mode | expected | anchors | budget | verdict');
+  console.log('---|------|----------|---------|--------|--------');
+  for (const r of results) {
+    console.log(
+      `${r.id} | ${r.mode || '-'} | ${r.expectedMode || '-'} | ${r.anchors.length} | ${r.budgetUsed}/${r.maxTokens === Infinity ? '∞' : r.maxTokens} | ${r.pass ? 'PASS' : 'FAIL'}`,
+    );
+    for (const failure of r.failures) {
+      console.log(`  ! ${failure}`);
+    }
+  }
+  const s = summarizeResults(results);
+  console.log(`scorecard: ${s.passed}/${s.total} passed`);
+  console.log(
+    `totals: passRate: ${fmtPct(s.passRate)} | modeAccuracy: ${fmtPct(s.modeAccuracy)} | anchorPrecision: ${fmtPct(s.anchorPrecision)} | anchorRecall: ${fmtPct(s.anchorRecall)} | meanBudgetUsedPct: ${fmtPct(s.meanBudgetUsedPct)}`,
+  );
+}
+
+const isMain = process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+if (isMain) {
+  const { corpusPath, projectRoot, jsonPath } = parseArgs(process.argv.slice(2));
+  try {
+    const { results, pass } = await runGold({ projectRoot, corpusPath });
+    printScorecard(results);
+    if (jsonPath) {
+      await writeScorecardJson(jsonPath, results);
+      console.log(`[bench] scorecard JSON written: ${jsonPath}`);
+    }
+    if (!pass) {
+      process.exitCode = 1;
+    }
+  } catch (error) {
+    console.error(`[bench] ${error?.message ?? error}`);
+    process.exitCode = 1;
+  }
+}