@ngockhoale/ukit 2.6.7 → 2.6.8

package/manifests/documentation.yaml

@@ -134,7 +134,8 @@ entries:
     load_policy: task-routed
     validation: [manual]
     archive_policy: never
-    budget: { max_lines: 250, enforcement: warning }
+    budget: { max_lines: 120, enforcement: warning }
+    notes: 'recalibrated TASK-217: actual 92 lines; 250 was >2.7× actual — 120 leaves ~30% headroom'
   - id: docs-improvement-roadmap
     path: docs/DOCUMENTATION_IMPROVEMENT_ROADMAP.md
     class: canonical
@@ -175,7 +176,8 @@ entries:
     load_policy: task-routed
     validation: [manual]
     archive_policy: never
-    budget: { max_lines: 200, enforcement: warning }
+    budget: { max_lines: 110, enforcement: warning }
+    notes: 'recalibrated TASK-217: actual 82 lines; 200 was ~2.4× actual — 110 leaves ~34% headroom'
   - id: docs-project
     path: docs/PROJECT.md
     class: canonical
@@ -186,6 +188,16 @@ entries:
     load_policy: on-demand
     validation: [manual]
     archive_policy: never
+  - id: docs-project-description
+    path: docs/PROJECT_DESCRIPTION.md
+    class: canonical
+    audience: [agent, maintainer]
+    owner: product
+    source_of_truth: docs/PROJECT_DESCRIPTION.md
+    merge_strategy: none
+    load_policy: on-demand
+    validation: [manual]
+    archive_policy: never
   - id: docs-project-important-spec
     path: docs/PROJECT_IMPORTANT_SPEC.md
     class: canonical
@@ -196,7 +208,8 @@ entries:
     load_policy: on-demand
     validation: [manual]
     archive_policy: replace-with-snapshot
-    notes: archived DOC-106 → docs/archive/specs/; live file is compact decision record
+    budget: { max_lines: 60, enforcement: warning }
+    notes: 'archived DOC-106 → docs/archive/specs/; live file is compact decision record. TASK-217: budget added (audit listed 44/150) — actual 44 lines, 60 leaves ~36% headroom'
   - id: docs-context-budget
     path: docs/CONTEXT_BUDGET.md
     class: canonical
@@ -271,7 +284,7 @@ entries:
     validation: [manual]
     archive_policy: date-rotate
     budget: { max_lines: 150, enforcement: error }
-    notes: enforcement flipped to error by TASK-005 (2026-09-19)
+    notes: enforcement flipped to error by TASK-005 (2026-09-19); TASK-217 audit — actual 83 lines (~55% headroom), value kept
   - id: docs-worklog
     path: docs/WORKLOG.md
     class: runtime
@@ -283,7 +296,7 @@ entries:
     validation: [manual]
     archive_policy: never
     budget: { max_lines: 600, enforcement: warning }
-    notes: rotation = DOC-105
+    notes: 'rotation = DOC-105; TASK-217 audit — actual 528 lines (~12% headroom), value kept pending rotation'
   - id: docs-ai-handoff
     path: docs/AI_HANDOFF/
     class: runtime
@@ -295,6 +308,17 @@ entries:
     validation: [manual]
     archive_policy: never
     notes: dir entry — covers all files beneath
+  - id: docs-ai-handoff-index
+    path: docs/AI_HANDOFF/INDEX.md
+    class: runtime
+    audience: [agent, maintainer]
+    owner: runtime
+    source_of_truth: docs/AI_HANDOFF/INDEX.md
+    merge_strategy: none
+    load_policy: task-routed
+    validation: [manual]
+    archive_policy: never
+    notes: handoff run cursor index; declared in context_layers.intents.handoff (DOC-201)
   - id: docs-archive
     path: docs/archive/
     class: archive
@@ -382,7 +406,7 @@ entries:
     validation: [manual]
     archive_policy: never
     budget: { max_lines: 160, enforcement: warning }
-    notes: canonical shared core; pre-shrink >160 is warning-only (DOC-104 shrinks)
+    notes: 'canonical shared core; TASK-217 shrink 210→157 lines — budget 160 kept per SPEC §14 (now obeyed, warning-only)'
   - id: tpl-omp-rules
     path: templates/.omp/RULES.md
     class: generated
@@ -660,3 +684,50 @@ entries:
     load_policy: on-demand
     validation: [manual]
     archive_policy: never
+
+  # ── Same-wave additions (DOC-201 batch; files authored by TASK-208/212) ────
+  - id: docs-host-capability-matrix
+    path: docs/HOST_CAPABILITY_MATRIX.md
+    class: canonical
+    audience: [maintainer, contributor]
+    owner: adapter
+    source_of_truth: docs/HOST_CAPABILITY_MATRIX.md
+    merge_strategy: none
+    load_policy: on-demand
+    validation: [manual]
+    archive_policy: never
+    notes: hand-authored from manifests/hostCapabilities.yaml (TASK-208 adds hostCapabilityMatrix.test.js enforcement)
+  - id: manifest-host-capabilities
+    path: manifests/hostCapabilities.yaml
+    class: canonical
+    audience: [maintainer]
+    owner: adapter
+    source_of_truth: manifests/hostCapabilities.yaml
+    merge_strategy: none
+    load_policy: on-demand
+    validation: [manual]
+    archive_policy: never
+    notes: machine-readable host capability states (DOC-202); matrix doc renders from it
+  - id: docs-prompt-caching-vendor-evidence
+    path: docs/research/PROMPT_CACHING_VENDOR_EVIDENCE.md
+    class: archive
+    audience: [maintainer]
+    owner: product
+    source_of_truth: docs/research/PROMPT_CACHING_VENDOR_EVIDENCE.md
+    merge_strategy: none
+    load_policy: never
+    validation: [manual]
+    archive_policy: immutable
+    notes: vendor evidence extracted from docs/PROMPT_CACHING.md (DOC-206, TASK-212)
+
+# Declared complexity→docs mapping consumed by the router's `docs=` summary segment
+# (src/index/taskRouting.js CONTEXT_LAYER_DOCS mirrors this block; DOC-201 FR-001/002).
+# queued-task intent omitted v1: docs/TASKS.md is optional per-repo (SPEC §14).
+context_layers:
+  task_types:
+    trivial: []
+    simple: [docs/MEMORY.md]
+    non-trivial: [docs/MEMORY.md, docs/PROJECT.md, docs/CODE_MAP.md]
+  intents:
+    open-ended: [docs/STATUS.md]
+    handoff: [docs/AI_HANDOFF/INDEX.md]

package/manifests/hostCapabilities.yaml

@@ -0,0 +1,49 @@
+# Host capability matrix (DOC-202 / FR-003).
+# Every host × capability cell carries a state:
+#   tested    — an automated test under tests/** exercises the shipped artifact (evidence required)
+#   observed  — shipped artifact exists and is reviewed by hand; no dedicated automated test (evidence/note required)
+#   unknown   — not verified in this repo
+# Human table mirror: docs/HOST_CAPABILITY_MATRIX.md
+# Consistency enforced by: tests/consistency/hostCapabilityMatrix.test.js
+version: 1
+hosts:
+  claude-code:
+    skills:                  { state: tested,    evidence: tests/integration/installPipeline.test.js }
+    subagents:               { state: tested,    evidence: tests/consistency/mappingFingerprint.test.js }
+    hooks:                   { state: tested,    evidence: tests/hooks/skillRouterHook.test.js }
+    session-start-injection: { state: tested,    evidence: tests/hooks/reinjectContextHook.test.js }
+    stop-gate:               { state: tested,    evidence: tests/hooks/stopCoordinator.test.js }
+    slash-commands:          { state: tested,    evidence: tests/integration/artifactReferenceIntegrity.test.js }
+    owner-file-injection:    { state: tested,    evidence: tests/consistency/instructionRender.test.js }
+    settings-env:            { state: tested,    evidence: tests/core/repairBrokenHooks.test.js }
+    context-files:           { state: tested,    evidence: tests/integration/installPipeline.test.js }
+  codex:
+    skills:                  { state: observed,  note: '.codex/skills mirror ships via install; no dedicated codex-skill test' }
+    subagents:               { state: unknown }
+    hooks:                   { state: unknown }
+    session-start-injection: { state: unknown }
+    stop-gate:               { state: unknown }
+    slash-commands:          { state: unknown }
+    owner-file-injection:    { state: observed,  note: 'AGENTS.md rendered for codex; parity asserted only at artifact level' }
+    settings-env:            { state: tested,    evidence: tests/integration/installPipeline.test.js }
+    context-files:           { state: tested,    evidence: tests/integration/installPipeline.test.js }
+  opencode:
+    skills:                  { state: observed,  note: 'reads .claude/skills via discovery; asserted indirectly by artifact tests' }
+    subagents:               { state: unknown }
+    hooks:                   { state: unknown }
+    session-start-injection: { state: unknown }
+    stop-gate:               { state: unknown }
+    slash-commands:          { state: observed,  note: 'ukit-* helper entrypoints declared in opencode.json' }
+    owner-file-injection:    { state: observed,  note: 'AGENTS.md loaded at session start; no injection test' }
+    settings-env:            { state: tested,    evidence: tests/integration/installPipeline.test.js }
+    context-files:           { state: observed,  note: 'AGENTS.md asserted by install pipeline; no opencode-specific parse test' }
+  omp:
+    skills:                  { state: observed,  note: 'omp reads .claude/skills via claude discovery provider' }
+    subagents:               { state: tested,    evidence: tests/consistency/ompAgentParity.test.js }
+    hooks:                   { state: tested,    evidence: tests/hooks/ompHookBridge.test.js }
+    session-start-injection: { state: tested,    evidence: tests/hooks/ompHookBridge.test.js }
+    stop-gate:               { state: unknown }
+    slash-commands:          { state: observed,  note: 'delegation parentheticals checked by tests/consistency/ompCommandParity.test.js' }
+    owner-file-injection:    { state: unknown }
+    settings-env:            { state: observed,  note: 'templates/.omp/config.yml modelRoles reviewed by ompAgentParity' }
+    context-files:           { state: observed,  note: 'omp consumes AGENTS.md/CLAUDE.md context layer; no dedicated test' }

package/manifests/instructionRules.yaml

@@ -11,6 +11,11 @@ description: >-
 # 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
@@ -268,6 +273,7 @@ rules:
       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
@@ -277,6 +283,7 @@ rules:
       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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ngockhoale/ukit",
-  "version": "2.6.7",
+  "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",

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;
+  }
+}

package/scripts/release/verify-release.mjs

@@ -45,6 +45,12 @@ const steps = [
     args: ['test:artifact'],
     env: process.env,
   },
+  {
+    label: 'Doc contracts',
+    command: 'yarn',
+    args: ['vitest', 'run', 'tests/consistency/docContracts.test.js'],
+    env: process.env,
+  },
   {
     label: 'Core test suite',
     command: 'yarn',

package/src/cli/commands/code.js

@@ -0,0 +1,182 @@
+import { compileContext } from '../../core/codeintel/compiler.js';
+import { packetToText, validatePacket } from '../../core/codeintel/packet.js';
+import { IndexFileSyntaxProvider } from '../../core/codeintel/providers.js';
+
+// `ukit code` — CLI surface over the codeintel plane (SPEC §11).
+// Every subcommand emits a Context Packet v1: `--json` prints the raw packet,
+// default prints `packetToText`. Unknown/missing subcommand → help + non-zero.
+
+const HELP_FLAGS = new Set(['--help', '-h', 'help']);
+const SUBCOMMANDS = new Set(['peek', 'search', 'context', 'impact']);
+
+function extractFlag(args, flag) {
+  const index = args.indexOf(flag);
+  if (index < 0) return { value: null, rest: args };
+  return {
+    value: args[index + 1] ?? null,
+    rest: [...args.slice(0, index), ...args.slice(index + 2)],
+  };
+}
+
+function hasFlag(args, flag) {
+  return args.includes(flag);
+}
+
+function parsePositiveInt(value, fallback) {
+  const parsed = Number.parseInt(value ?? '', 10);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
+}
+
+function printPacket(packet, { json }) {
+  if (json) {
+    console.log(JSON.stringify(packet, null, 2));
+    return;
+  }
+  console.log(packetToText(packet));
+  const validation = validatePacket(packet);
+  if (!validation.ok) {
+    console.log(`[UKit] packet validation warnings: ${validation.errors.join('; ')}`);
+  }
+}
+
+async function printFileOutline(projectRoot, filePath) {
+  try {
+    const provider = new IndexFileSyntaxProvider({ rootDir: projectRoot });
+    if (!provider.supports(filePath)) {
+      return;
+    }
+    const symbols = await provider.symbols(filePath);
+    if (!Array.isArray(symbols) || symbols.length === 0) {
+      return;
+    }
+    console.log('');
+    console.log(`## Outline (${filePath})`);
+    for (const item of symbols) {
+      console.log(`${item.line ?? '?'}: ${item.name ?? item.kind ?? ''}${item.kind ? ` [${item.kind}]` : ''}`);
+    }
+  } catch {
+    // Outline is best-effort decoration; never fail the packet print for it.
+  }
+}
+
+export async function runCode({ projectRoot, argv = [] }) {
+  const [subcommandRaw, ...rest] = argv;
+  const subcommand = (subcommandRaw ?? '').toLowerCase();
+
+  if (!subcommand || HELP_FLAGS.has(subcommand)) {
+    printCodeHelp();
+    if (!subcommand) {
+      process.exitCode = 1;
+    }
+    return;
+  }
+
+  if (!SUBCOMMANDS.has(subcommand)) {
+    console.error(`[UKit] Unknown code subcommand: ${subcommand}`);
+    printCodeHelp();
+    process.exitCode = 1;
+    return;
+  }
+
+  const json = hasFlag(rest, '--json');
+  const withoutJson = rest.filter((arg) => arg !== '--json');
+
+  if (subcommand === 'peek') {
+    const { value: lines, rest: args } = extractFlag(withoutJson, '--lines');
+    const filePath = args[0];
+    if (!filePath) {
+      console.error('[UKit] Missing file path. Usage: ukit code peek <path> [--lines a-b] [--json]');
+      process.exitCode = 1;
+      return;
+    }
+    const packet = await compileContext(projectRoot, {
+      prompt: filePath,
+      filesHinted: [filePath],
+    }, { mode: 'peek' });
+    printPacket(packet, { json });
+    if (!json) {
+      await printFileOutline(projectRoot, filePath);
+      if (lines) {
+        console.log(`(note: --lines ${lines} accepted; v1 outline prints full symbol list)`);
+      }
+    }
+    return;
+  }
+
+  if (subcommand === 'search') {
+    const { value: limitArg, rest: args } = extractFlag(withoutJson, '--limit');
+    const limit = parsePositiveInt(limitArg, 20);
+    const query = args.join(' ').trim();
+    if (!query) {
+      console.error('[UKit] Missing query. Usage: ukit code search "<query>" [--limit n] [--json]');
+      process.exitCode = 1;
+      return;
+    }
+    const packet = await compileContext(projectRoot, query);
+    if (packet.evidence.length > limit) {
+      const dropped = packet.evidence.splice(limit);
+      for (const item of dropped) {
+        packet.omitted.push({ what: item.path ?? 'evidence', why: 'limit' });
+      }
+    }
+    if (packet.anchors.length > limit) {
+      packet.anchors = packet.anchors.slice(0, limit);
+    }
+    printPacket(packet, { json });
+    return;
+  }
+
+  if (subcommand === 'context') {
+    const { value: mode, rest: afterMode } = extractFlag(withoutJson, '--mode');
+    const { value: budgetArg, rest: afterBudget } = extractFlag(afterMode, '--budget');
+    const budget = budgetArg !== null ? parsePositiveInt(budgetArg, null) : undefined;
+    const diagnostics = hasFlag(afterBudget, '--diagnostics');
+    const args = afterBudget.filter((arg) => arg !== '--diagnostics');
+    const task = args.join(' ').trim();
+    if (!task) {
+      console.error('[UKit] Missing task. Usage: ukit code context "<task>" [--mode m] [--budget n] [--diagnostics] [--json]');
+      process.exitCode = 1;
+      return;
+    }
+    const packet = await compileContext(projectRoot, task, {
+      mode: mode ?? undefined,
+      budget: budget ?? undefined,
+      diagnostics: diagnostics || undefined,
+    });
+    printPacket(packet, { json });
+    return;
+  }
+
+  // subcommand === 'impact'
+  const { value: depthArg, rest: impactArgs } = extractFlag(withoutJson, '--depth');
+  const depth = depthArg !== null ? parsePositiveInt(depthArg, null) : undefined;
+  const target = impactArgs[0];
+  if (!target) {
+    console.error('[UKit] Missing target. Usage: ukit code impact <path|symbol> [--depth N] [--json]');
+    process.exitCode = 1;
+    return;
+  }
+  const packet = await compileContext(projectRoot, {
+    prompt: target,
+    filesHinted: target.includes('/') || /\.[a-z0-9]+$/i.test(target) ? [target] : [],
+  }, { mode: 'impact', depth: depth ?? undefined });
+  printPacket(packet, { json });
+}
+
+export function printCodeHelp() {
+  console.log('UKit Code Commands (codeintel plane)');
+  console.log('Usage: ukit code <peek|search|context|impact> [args]');
+  console.log('');
+  console.log('Subcommands:');
+  console.log('  peek <path> [--lines a-b]   L0 outline-only packet + file outline');
+  console.log('  search "<query>" [--limit n]  Routed retrieval packet over the index');
+  console.log('  context "<task>" [--mode m] [--budget n] [--diagnostics]  Compiled context packet for a task');
+  console.log('  impact <path|symbol> [--depth N]  L2 packet with multi-hop reverse-import edges');
+  console.log('');
+  console.log('Options:');
+  console.log('  --json              Print raw Context Packet JSON (default: text render)');
+  console.log('  --mode <m>          Force router mode: none|peek|targeted|explore|impact|deep_flow|analogy');
+  console.log('  --budget <n>        Override routed token budget');
+  console.log('  --depth <N>         Impact-mode hop depth (clamped 1..codeIntel.impact.maxDepth)');
+  console.log('  --diagnostics       Include post-edit diagnostics in next_actions');
+}