codebaseiq 0.1.0

package/scripts/codebaseiq-windows-provenance.mjs

@@ -0,0 +1,364 @@
+import { createHash } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+export const WINDOWS_SIDECAR_PROVENANCE_KIND = 'codebaseiq-windows-sidecar-provenance';
+export const WINDOWS_SIDECAR_PROVENANCE_VERSION = 1;
+export const WINDOWS_SIDECAR_PROVENANCE_FILE = 'provenance.json';
+export const DEFAULT_SCIP_REPOSITORY = 'https://github.com/scip-code/scip.git';
+export const DEFAULT_SCIP_TAG = 'v0.8.1';
+export const PINNED_GO_VERSION = 'go1.26.4';
+
+export const WINDOWS_SIDECAR_BUILD = Object.freeze({
+  command: 'go build',
+  package: './cmd/scip',
+  flags: Object.freeze(['-trimpath', '-ldflags=-s -w']),
+  environment: Object.freeze({
+    CGO_ENABLED: '0',
+    GOOS: 'windows',
+  }),
+});
+
+export const WINDOWS_SIDECAR_TARGETS = Object.freeze([
+  Object.freeze({
+    goarch: 'amd64',
+    packageArch: 'x64',
+    filename: 'scip-win32-x64.exe',
+    peMachine: 'AMD64',
+    peMachineCode: 0x8664,
+  }),
+  Object.freeze({
+    goarch: 'arm64',
+    packageArch: 'arm64',
+    filename: 'scip-win32-arm64.exe',
+    peMachine: 'ARM64',
+    peMachineCode: 0xaa64,
+  }),
+]);
+
+export class WindowsSidecarProvenanceError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.name = 'WindowsSidecarProvenanceError';
+    this.code = code;
+  }
+}
+
+export function sha256(bytes) {
+  return createHash('sha256').update(bytes).digest('hex');
+}
+
+export function inspectPortableExecutable(bytes, filename = '<binary>') {
+  if (!Buffer.isBuffer(bytes) || bytes.length < 0x40) {
+    throw provenanceError('malformed-binary', `${filename} is too short to be a PE executable.`);
+  }
+  if (bytes[0] !== 0x4d || bytes[1] !== 0x5a) {
+    throw provenanceError('malformed-binary', `${filename} is missing the DOS MZ signature.`);
+  }
+
+  const peOffset = bytes.readUInt32LE(0x3c);
+  if (!Number.isSafeInteger(peOffset) || peOffset < 0x40 || peOffset + 26 > bytes.length) {
+    throw provenanceError('malformed-binary', `${filename} has an invalid PE header offset.`);
+  }
+  if (
+    bytes[peOffset] !== 0x50 ||
+    bytes[peOffset + 1] !== 0x45 ||
+    bytes[peOffset + 2] !== 0 ||
+    bytes[peOffset + 3] !== 0
+  ) {
+    throw provenanceError('malformed-binary', `${filename} is missing the PE signature.`);
+  }
+
+  const machineCode = bytes.readUInt16LE(peOffset + 4);
+  const target = WINDOWS_SIDECAR_TARGETS.find((candidate) => candidate.peMachineCode === machineCode);
+  if (!target) {
+    throw provenanceError(
+      'wrong-architecture',
+      `${filename} has unsupported PE machine 0x${machineCode.toString(16).padStart(4, '0')}.`,
+    );
+  }
+
+  const optionalHeaderMagic = bytes.readUInt16LE(peOffset + 24);
+  if (optionalHeaderMagic !== 0x20b) {
+    throw provenanceError(
+      'malformed-binary',
+      `${filename} is not a PE32+ executable (optional-header magic 0x${optionalHeaderMagic
+        .toString(16)
+        .padStart(4, '0')}).`,
+    );
+  }
+
+  return {
+    peMachine: target.peMachine,
+    peMachineCode: `0x${machineCode.toString(16).padStart(4, '0')}`,
+  };
+}
+
+export function inspectWindowsSidecarBinary(file, readFile = readFileSync) {
+  const bytes = readFile(file);
+  const pe = inspectPortableExecutable(bytes, file);
+  return {
+    size: bytes.length,
+    sha256: sha256(bytes),
+    ...pe,
+  };
+}
+
+export function createWindowsSidecarProvenance({
+  sidecarDir,
+  packageName,
+  packageVersion,
+  sourceRepository = DEFAULT_SCIP_REPOSITORY,
+  sourceTag = DEFAULT_SCIP_TAG,
+  sourceCommit,
+  goVersion = PINNED_GO_VERSION,
+  readFile = readFileSync,
+}) {
+  if (!isCommit(sourceCommit)) {
+    throw provenanceError('invalid-build-input', `Source commit must be a full 40-character Git commit.`);
+  }
+
+  return {
+    kind: WINDOWS_SIDECAR_PROVENANCE_KIND,
+    schemaVersion: WINDOWS_SIDECAR_PROVENANCE_VERSION,
+    package: {
+      name: packageName,
+      version: packageVersion,
+    },
+    source: {
+      repository: sourceRepository,
+      tag: sourceTag,
+      commit: sourceCommit,
+    },
+    toolchain: {
+      goVersion,
+    },
+    build: {
+      command: WINDOWS_SIDECAR_BUILD.command,
+      package: WINDOWS_SIDECAR_BUILD.package,
+      flags: [...WINDOWS_SIDECAR_BUILD.flags],
+      environment: {
+        ...WINDOWS_SIDECAR_BUILD.environment,
+      },
+    },
+    binaries: WINDOWS_SIDECAR_TARGETS.map((target) => {
+      const inspected = inspectWindowsSidecarBinary(join(sidecarDir, target.filename), readFile);
+      if (inspected.peMachine !== target.peMachine) {
+        throw provenanceError(
+          'wrong-architecture',
+          `${target.filename} declares ${target.packageArch} but contains ${inspected.peMachine}.`,
+        );
+      }
+      return {
+        filename: target.filename,
+        target: {
+          goos: 'windows',
+          goarch: target.goarch,
+          packageArch: target.packageArch,
+        },
+        size: inspected.size,
+        sha256: inspected.sha256,
+        peMachine: inspected.peMachine,
+        peMachineCode: inspected.peMachineCode,
+      };
+    }),
+  };
+}
+
+export function verifyWindowsSidecarProvenance({
+  sidecarDir,
+  expectedSourceRepository = DEFAULT_SCIP_REPOSITORY,
+  expectedSourceTag = DEFAULT_SCIP_TAG,
+  expectedGoVersion = PINNED_GO_VERSION,
+  readFile = readFileSync,
+}) {
+  const packageRecord = parseJsonFile(join(sidecarDir, 'package.json'), 'sidecar package', readFile);
+  const manifest = parseJsonFile(
+    join(sidecarDir, WINDOWS_SIDECAR_PROVENANCE_FILE),
+    'sidecar provenance manifest',
+    readFile,
+  );
+  const decoded = decodeWindowsSidecarProvenance(manifest);
+
+  requireEqual(decoded.package.name, packageRecord.name, 'package name');
+  requireEqual(decoded.package.version, packageRecord.version, 'package version');
+  requireEqual(decoded.source.repository, expectedSourceRepository, 'SCIP source repository');
+  requireEqual(decoded.source.tag, expectedSourceTag, 'SCIP source tag');
+  requireEqual(decoded.toolchain.goVersion, expectedGoVersion, 'pinned Go version');
+  requireBuildContract(decoded.build);
+
+  const entries = new Map(decoded.binaries.map((binary) => [binary.filename, binary]));
+  for (const target of WINDOWS_SIDECAR_TARGETS) {
+    const expected = entries.get(target.filename);
+    if (!expected) {
+      throw provenanceError('malformed-manifest', `Manifest is missing ${target.filename}.`);
+    }
+
+    requireEqual(expected.target.goos, 'windows', `${target.filename} GOOS`);
+    requireEqual(expected.target.goarch, target.goarch, `${target.filename} GOARCH`);
+    requireEqual(expected.target.packageArch, target.packageArch, `${target.filename} package arch`);
+    requireEqual(expected.peMachine, target.peMachine, `${target.filename} PE machine`);
+    requireEqual(
+      expected.peMachineCode,
+      `0x${target.peMachineCode.toString(16).padStart(4, '0')}`,
+      `${target.filename} PE machine code`,
+    );
+
+    let actual;
+    try {
+      actual = inspectWindowsSidecarBinary(join(sidecarDir, target.filename), readFile);
+    } catch (error) {
+      if (error?.code === 'ENOENT') {
+        throw provenanceError('missing-binary', `${target.filename} is missing.`);
+      }
+      throw error;
+    }
+    requireEqual(actual.peMachine, target.peMachine, `${target.filename} actual PE machine`);
+    requireEqual(actual.size, expected.size, `${target.filename} byte size`);
+    requireEqual(actual.sha256, expected.sha256, `${target.filename} SHA-256`);
+  }
+
+  return decoded;
+}
+
+export function decodeWindowsSidecarProvenance(value) {
+  const record = requireRecord(value, 'manifest');
+  requireEqual(record.kind, WINDOWS_SIDECAR_PROVENANCE_KIND, 'manifest kind');
+  if (record.schemaVersion !== WINDOWS_SIDECAR_PROVENANCE_VERSION) {
+    throw provenanceError(
+      'unsupported-manifest',
+      `Unsupported Windows sidecar provenance schema ${String(record.schemaVersion)}; expected ${WINDOWS_SIDECAR_PROVENANCE_VERSION}.`,
+    );
+  }
+
+  const packageRecord = requireRecord(record.package, 'package');
+  const source = requireRecord(record.source, 'source');
+  const toolchain = requireRecord(record.toolchain, 'toolchain');
+  const build = requireRecord(record.build, 'build');
+  if (!Array.isArray(record.binaries) || record.binaries.length !== WINDOWS_SIDECAR_TARGETS.length) {
+    throw provenanceError(
+      'malformed-manifest',
+      `binaries must contain exactly ${WINDOWS_SIDECAR_TARGETS.length} entries.`,
+    );
+  }
+
+  const binaries = record.binaries.map((value, index) => {
+    const binary = requireRecord(value, `binaries[${index}]`);
+    const target = requireRecord(binary.target, `binaries[${index}].target`);
+    requireNonEmptyString(binary.filename, `binaries[${index}].filename`);
+    requireNonEmptyString(target.goos, `binaries[${index}].target.goos`);
+    requireNonEmptyString(target.goarch, `binaries[${index}].target.goarch`);
+    requireNonEmptyString(target.packageArch, `binaries[${index}].target.packageArch`);
+    requirePositiveSafeInteger(binary.size, `binaries[${index}].size`);
+    if (typeof binary.sha256 !== 'string' || !/^[a-f0-9]{64}$/.test(binary.sha256)) {
+      throw provenanceError('malformed-manifest', `binaries[${index}].sha256 must be lowercase SHA-256.`);
+    }
+    requireNonEmptyString(binary.peMachine, `binaries[${index}].peMachine`);
+    if (typeof binary.peMachineCode !== 'string' || !/^0x[a-f0-9]{4}$/.test(binary.peMachineCode)) {
+      throw provenanceError(
+        'malformed-manifest',
+        `binaries[${index}].peMachineCode must be a four-digit hexadecimal code.`,
+      );
+    }
+    return binary;
+  });
+
+  requireNonEmptyString(packageRecord.name, 'package.name');
+  requireNonEmptyString(packageRecord.version, 'package.version');
+  requireNonEmptyString(source.repository, 'source.repository');
+  requireNonEmptyString(source.tag, 'source.tag');
+  if (!isCommit(source.commit)) {
+    throw provenanceError('malformed-manifest', `source.commit must be a full 40-character Git commit.`);
+  }
+  requireNonEmptyString(toolchain.goVersion, 'toolchain.goVersion');
+  requireNonEmptyString(build.command, 'build.command');
+  requireNonEmptyString(build.package, 'build.package');
+  if (!Array.isArray(build.flags) || !build.flags.every((flag) => typeof flag === 'string')) {
+    throw provenanceError('malformed-manifest', `build.flags must be an array of strings.`);
+  }
+  requireRecord(build.environment, 'build.environment');
+
+  const filenames = binaries.map((binary) => binary.filename);
+  if (new Set(filenames).size !== filenames.length) {
+    throw provenanceError('malformed-manifest', `binaries contains duplicate filenames.`);
+  }
+
+  return {
+    ...record,
+    package: packageRecord,
+    source,
+    toolchain,
+    build,
+    binaries,
+  };
+}
+
+function requireBuildContract(build) {
+  requireEqual(build.command, WINDOWS_SIDECAR_BUILD.command, 'build command');
+  requireEqual(build.package, WINDOWS_SIDECAR_BUILD.package, 'build package');
+  if (JSON.stringify(build.flags) !== JSON.stringify(WINDOWS_SIDECAR_BUILD.flags)) {
+    throw provenanceError(
+      'build-input-mismatch',
+      `Build flags do not match the pinned contract (${WINDOWS_SIDECAR_BUILD.flags.join(' ')}).`,
+    );
+  }
+  const environment = requireRecord(build.environment, 'build.environment');
+  requireEqual(environment.CGO_ENABLED, WINDOWS_SIDECAR_BUILD.environment.CGO_ENABLED, 'CGO_ENABLED');
+  requireEqual(environment.GOOS, WINDOWS_SIDECAR_BUILD.environment.GOOS, 'GOOS');
+}
+
+function parseJsonFile(file, label, readFile) {
+  let bytes;
+  try {
+    bytes = readFile(file);
+  } catch (error) {
+    if (error?.code === 'ENOENT') {
+      throw provenanceError(
+        label === 'sidecar provenance manifest' ? 'missing-manifest' : 'missing-package',
+        `${label} is missing at ${file}.`,
+      );
+    }
+    throw error;
+  }
+  try {
+    return JSON.parse(bytes.toString('utf8'));
+  } catch {
+    throw provenanceError('malformed-manifest', `${label} is not valid JSON at ${file}.`);
+  }
+}
+
+function requireRecord(value, field) {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+    throw provenanceError('malformed-manifest', `${field} must be an object.`);
+  }
+  return value;
+}
+
+function requireNonEmptyString(value, field) {
+  if (typeof value !== 'string' || value.trim().length === 0) {
+    throw provenanceError('malformed-manifest', `${field} must be a non-empty string.`);
+  }
+}
+
+function requirePositiveSafeInteger(value, field) {
+  if (typeof value !== 'number' || !Number.isSafeInteger(value) || value <= 0) {
+    throw provenanceError('malformed-manifest', `${field} must be a positive safe integer.`);
+  }
+}
+
+function requireEqual(actual, expected, field) {
+  if (actual !== expected) {
+    throw provenanceError(
+      'build-input-mismatch',
+      `${field} mismatch: expected ${JSON.stringify(expected)}, received ${JSON.stringify(actual)}.`,
+    );
+  }
+}
+
+function isCommit(value) {
+  return typeof value === 'string' && /^[a-f0-9]{40}$/.test(value);
+}
+
+function provenanceError(code, message) {
+  return new WindowsSidecarProvenanceError(code, message);
+}

package/scripts/evidence-product-contract.mjs

@@ -0,0 +1,197 @@
+#!/usr/bin/env node
+import { spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, rmSync, statSync, appendFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { performance } from 'node:perf_hooks';
+
+const DEFAULT_COMMANDS = [
+  ['dead', '--json'],
+  ['doc-drift', '--json'],
+  ['recent-duplicates', '--json'],
+  ['similar', '--json', '--full'],
+  ['health', '--json', '--full'],
+];
+
+const args = parseArgs(process.argv.slice(2));
+const projectRoot = process.cwd();
+const cliPath = resolve(projectRoot, 'dist/cli.js');
+const date = new Date().toISOString().slice(0, 10);
+const runHistoryPath = resolve(projectRoot, args.out ?? `docs/benchmarks/runs/${date}-evidence-products.jsonl`);
+const profilePath = resolve(
+  projectRoot,
+  args.profileOut ?? `docs/benchmarks/runs/${date}-evidence-products.profile.jsonl`,
+);
+const commands = args.commands.length > 0 ? args.commands : DEFAULT_COMMANDS;
+
+mkdirSync(dirname(runHistoryPath), { recursive: true });
+mkdirSync(dirname(profilePath), { recursive: true });
+
+const status = runCli(['status', '--json'], { profile: false });
+if (status.exitCode !== 0) {
+  process.stderr.write(status.stderr.toString());
+  process.exit(status.exitCode ?? 1);
+}
+
+const statusJson = JSON.parse(status.stdout.toString());
+const dbPath = statusJson.result?.dbPath;
+if (typeof dbPath !== 'string') {
+  throw new Error('status --json did not include result.dbPath');
+}
+
+const evidencePath = join(dirname(dbPath), 'evidence.db');
+if (!args.noClear) clearEvidence(evidencePath);
+
+const runId = new Date().toISOString();
+const records = [];
+for (let iteration = 1; iteration <= args.coldIterations; iteration += 1) {
+  for (const command of commands) {
+    records.push(recordCommand({ runId, phase: 'cold-fill', iteration, command, evidencePath }));
+  }
+}
+for (let iteration = 1; iteration <= args.warmIterations; iteration += 1) {
+  for (const command of commands) {
+    records.push(recordCommand({ runId, phase: 'warm-hit', iteration, command, evidencePath }));
+  }
+}
+
+const failed = records.filter((record) => record.exitCode !== 0 || record.signal || record.error);
+const summary = {
+  runId,
+  runHistoryPath,
+  profilePath,
+  evidencePath,
+  commands: commands.map((command) => command.join(' ')),
+  coldIterations: args.coldIterations,
+  warmIterations: args.warmIterations,
+  failed: failed.length,
+  records: records.map(
+    ({ phase, iteration, command, durationMs, exitCode, stdoutBytes, stderrBytes, evidenceBytes }) => ({
+      phase,
+      iteration,
+      command,
+      durationMs,
+      exitCode,
+      stdoutBytes,
+      stderrBytes,
+      evidenceBytes,
+    }),
+  ),
+};
+
+process.stdout.write(`${JSON.stringify(summary, null, 2)}\n`);
+if (failed.length > 0) process.exit(1);
+
+function recordCommand({ runId, phase, iteration, command, evidencePath }) {
+  const result = runCli(command, { profile: true });
+  const record = {
+    timestamp: new Date().toISOString(),
+    runId,
+    target: 'evidence-products',
+    phase,
+    iteration,
+    command: `codebaseiq ${command.join(' ')}`,
+    durationMs: result.durationMs,
+    exitCode: result.exitCode,
+    signal: result.signal,
+    error: result.error?.message,
+    stdoutBytes: result.stdout.length,
+    stderrBytes: result.stderr.length,
+    stdoutSha256: sha256(result.stdout),
+    evidenceBytes: fileSize(evidencePath),
+    profilePath,
+  };
+  appendFileSync(runHistoryPath, `${JSON.stringify(record)}\n`);
+  return record;
+}
+
+function runCli(command, opts) {
+  const started = performance.now();
+  const result = spawnSync(process.execPath, [cliPath, ...command], {
+    cwd: projectRoot,
+    env: opts.profile
+      ? {
+          ...process.env,
+          CODEBASEIQ_PROFILE: '1',
+          CODEBASEIQ_PROFILE_COMMAND: `codebaseiq ${command.join(' ')}`,
+          CODEBASEIQ_PROFILE_OUT: profilePath,
+        }
+      : process.env,
+    encoding: 'buffer',
+    maxBuffer: 100 * 1024 * 1024,
+  });
+  return {
+    durationMs: Math.round(performance.now() - started),
+    exitCode: result.status,
+    signal: result.signal,
+    error: result.error,
+    stdout: result.stdout ?? Buffer.alloc(0),
+    stderr: result.stderr ?? Buffer.alloc(0),
+  };
+}
+
+function clearEvidence(evidencePath) {
+  for (const path of [evidencePath, `${evidencePath}-wal`, `${evidencePath}-shm`]) {
+    if (existsSync(path)) rmSync(path, { force: true });
+  }
+}
+
+function fileSize(path) {
+  try {
+    return statSync(path).size;
+  } catch {
+    return 0;
+  }
+}
+
+function sha256(buffer) {
+  return createHash('sha256').update(buffer).digest('hex');
+}
+
+function parseArgs(argv) {
+  const parsed = {
+    coldIterations: 1,
+    warmIterations: 2,
+    commands: [],
+    noClear: false,
+    out: undefined,
+    profileOut: undefined,
+  };
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === '--cold-iterations') {
+      parsed.coldIterations = positiveInteger(argv[++index], '--cold-iterations');
+    } else if (arg === '--warm-iterations') {
+      parsed.warmIterations = positiveInteger(argv[++index], '--warm-iterations');
+    } else if (arg === '--command') {
+      const value = argv[++index];
+      if (!value) throw new Error('--command requires a value');
+      parsed.commands.push(splitCommand(value));
+    } else if (arg === '--out') {
+      parsed.out = argv[++index];
+      if (!parsed.out) throw new Error('--out requires a value');
+    } else if (arg === '--profile-out') {
+      parsed.profileOut = argv[++index];
+      if (!parsed.profileOut) throw new Error('--profile-out requires a value');
+    } else if (arg === '--no-clear') {
+      parsed.noClear = true;
+    } else {
+      throw new Error(`unknown option: ${arg}`);
+    }
+  }
+  return parsed;
+}
+
+function positiveInteger(value, flag) {
+  const parsed = Number(value);
+  if (!Number.isInteger(parsed) || parsed < 0) throw new Error(`${flag} must be a non-negative integer`);
+  return parsed;
+}
+
+function splitCommand(value) {
+  return value
+    .trim()
+    .split(/\s+/)
+    .filter(Boolean)
+    .filter((part, index) => !(index === 0 && part === 'codebaseiq'));
+}

package/scripts/verify-codebaseiq-windows.mjs

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import {
+  DEFAULT_SCIP_REPOSITORY,
+  DEFAULT_SCIP_TAG,
+  PINNED_GO_VERSION,
+  verifyWindowsSidecarProvenance,
+} from './codebaseiq-windows-provenance.mjs';
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const sidecarDir = resolve(root, 'packages', 'codebaseiq-windows');
+
+try {
+  const manifest = verifyWindowsSidecarProvenance({
+    sidecarDir,
+    expectedSourceRepository: process.env.SCIP_REPO_URL ?? DEFAULT_SCIP_REPOSITORY,
+    expectedSourceTag: process.env.SCIP_VERSION ?? DEFAULT_SCIP_TAG,
+    expectedGoVersion: process.env.SCIP_GO_VERSION ?? PINNED_GO_VERSION,
+  });
+  console.log(
+    `Verified ${manifest.package.name}@${manifest.package.version}: ${manifest.source.tag} (${manifest.source.commit.slice(0, 12)}), ${manifest.toolchain.goVersion}, ${manifest.binaries.length} PE binaries.`,
+  );
+} catch (error) {
+  console.error(
+    `Windows sidecar provenance check FAILED:\n  - ${error instanceof Error ? error.message : String(error)}`,
+  );
+  process.exitCode = 1;
+}

package/skills/codebaseiq/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: codebaseiq
+description: Use FIRST for codebase work when compiler-resolved identity, runtime boundaries, callers, dependencies, consumers, architecture, change impact, or cleanup relationships can affect the answer. It exposes exact referents, explicit typed-graph projections, and source evidence; it does not infer task relevance.
+commands:
+  - template: 'codebaseiq search <text>'
+    when: 'Locate exact repository text, a runtime key, or a compiler symbol; use `codebaseiq search -- <text>` when the literal starts with a dash.'
+  - template: 'codebaseiq outline <file>'
+    when: 'Locate compiler-owned constructs in a known file.'
+  - template: 'codebaseiq entrypoints <text>'
+    when: 'Locate an external callable root when its entry surface is known.'
+  - template: 'codebaseiq evidence --symbol <symbol> --edge <family> --direction <direction> --depth <n> --max-edges <n>'
+    when: 'Project explicitly selected typed relationships from one exact root.'
+  - template: 'codebaseiq inspect --at <file:line> --view behavior'
+    when: 'Read connected behavior for a named implementation gap.'
+  - template: 'codebaseiq code <selector>'
+    when: 'Read exact source only when syntax itself can change the decision.'
+  - template: 'codebaseiq diff-impact'
+    when: 'Map changed symbols and downstream consumers after an edit.'
+  - template: 'codebaseiq architecture'
+    when: 'Validate declared structural boundaries.'
+  - template: 'codebaseiq health --full'
+    when: 'Run configured cleanup and quality detectors.'
+---
+
+# codebaseiq
+
+<!-- BEGIN GENERATED SKILL COMMANDS -->
+## Commands for this skill
+
+| Command | When |
+| --- | --- |
+| `codebaseiq search <text>` | Locate exact repository text, a runtime key, or a compiler symbol; use \`codebaseiq search -- <text>\` when the literal starts with a dash. |
+| `codebaseiq outline <file>` | Locate compiler-owned constructs in a known file. |
+| `codebaseiq entrypoints <text>` | Locate an external callable root when its entry surface is known. |
+| `codebaseiq evidence --symbol <symbol> --edge <family> --direction <direction> --depth <n> --max-edges <n>` | Project explicitly selected typed relationships from one exact root. |
+| `codebaseiq inspect --at <file:line> --view behavior` | Read connected behavior for a named implementation gap. |
+| `codebaseiq code <selector>` | Read exact source only when syntax itself can change the decision. |
+| `codebaseiq diff-impact` | Map changed symbols and downstream consumers after an edit. |
+| `codebaseiq architecture` | Validate declared structural boundaries. |
+| `codebaseiq health --full` | Run configured cleanup and quality detectors. |
+
+Use this shortlist first. Run a command's `--help` only when a named uncertainty needs another option.
+<!-- END GENERATED SKILL COMMANDS -->
+
+<!-- BEGIN GENERATED EXPLORATION MANUAL -->
+### Choose a relationship deliberately
+
+| Question | Evidence family | Direction |
+|---|---|---|
+| Who can call or reach this? | `execution` | `incoming` |
+| What can this call or reach? | `execution` | `outgoing` |
+| Where can this value come from? | `dataflow` | `incoming` |
+| Where can this value go? | `dataflow` | `outgoing` |
+| Which producer and consumer rendezvous? | `runtime` | `both` |
+| What resource is observed or changed? | `state` | `both` |
+| What occurs before or after this? | `temporal` | `both` |
+| What interface constrains this? | `contract` | `both` |
+| Are these observations the same entity? | `identity` | `both` |
+| What contains or owns this? | `ownership` | `both` |
+| What does this statically rely on? | `dependencies` | `outgoing` |
+
+Use exact evidence as an observed fact only within its coverage. Derived evidence is deterministically computed; candidate evidence is a lead; mixed evidence must retain its constituent strengths; unknown evidence cannot support a stronger claim. Missing output is not evidence of absence.
+
+The controls above are complete for ordinary exploration. Run `codebaseiq capabilities --matrix` only when a named claim depends on uncertain provider support; do not run it for routine orientation.
+<!-- END GENERATED EXPLORATION MANUAL -->
+
+codebaseiq is a repository exploration surface: an indexed code reader that joins exact current text to compiler-owned constructs, typed relationships, compressed behavior, exact source, and recoverable omissions. It performs the graph or read operation the agent selects; it does not infer task relevance, choose a subsystem, or decide that the user's question is complete.
+
+Privately name the material facts the answer requires. Locate the smallest owner or entry with `search`, `outline`, or `entrypoints`; choose the relationship and direction that can establish each fact; batch compatible roots into `evidence`; then use one batched `inspect` or exact `code` read only for named implementation gaps. There is no anchor-discovery phase or mandatory map. Do not locate every ledger row independently: a symbol or file/line returned by the first successful locator is already a graph root. When the question supplies several exact literals or independent participants, pass repeated `--search`, `--symbol`, or `--at` selectors directly to one `evidence` command. Do not run `capabilities` or command help merely to orient yourself; the command table and templates above are the normal operating manual.
+
+Read request, observed facts, calibration, coverage, and recovery together. A completed bounded projection is not a completed user task. Continue while a material fact remains unresolved and an exact in-scope recovery path exists; query count is never a correctness cutoff. Before every new query, check whether the missing fact is already present in an earlier packet; if it is, update the ledger or draft instead of querying again. Treat rendered source as already read, batch independent gaps, and run an unchanged `Continue exactly:` command until transport completes. Do not inspect tests, documentation, or examples after current implementation source has established the fact unless a named ambiguity specifically requires corroboration.
+
+Before answering, compare the draft to the selected statement-complete behavior—not merely to a remembered narrative. Preserve every observed behavior-changing predicate, returned default, separately merged field, cache invalidation, and cleanup effect that is material to the question. When two named fields use different merge or lifecycle operations, do not collapse them into a generic word such as “properties.” If the evidence already contains a missing detail, repair the answer; do not reopen exploration.
+
+Use codebaseiq rather than a parallel grep/read workflow for tracked text. Native tools are for edits, checks, binary content, or an explicitly reported unsupported gap. After edits, use `diff-impact` when consumers matter, `architecture` for declared boundaries, and `health` for quality or cleanup analysis.

package/skills/codebaseiq/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "CodebaseIQ"
+  short_description: "Map code relationships before nonlocal work"
+  default_prompt: "Use $codebaseiq to map compiler-resolved relationships that can affect this task, then keep ownership of the plan and implementation."