scip-query 0.23.0 → 0.26.0

package/docs/locality-analyzer-design.md

@@ -91,15 +91,15 @@ The output should include confidence, reasons, counterevidence, and the exact co
 
 The locality analyzer should not replace existing analyzers. It should complete their story.
 
-| Existing analyzer                                    | What it says today                                    | Locality companion question                                                                           |
-| ---------------------------------------------------- | ----------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
-| `react-large-component-pressure`                     | This React component is too large.                    | If pieces are extracted, which ones are private, feature-local, or shared?                            |
-| `vue-large-view-pressure`                            | This Vue SFC is too large.                            | Should extracted child components/composables live beside the view, in the feature, or in app shared? |
-| `extract-candidates`                                 | This function contains a possible extraction cluster. | Would the extracted helper have one real owner or a broader consumer set?                             |
-| `react-hook-candidates`, `vue-composable-candidates` | Several components repeat behavior.                   | Is the hook/composable local to one feature or reusable across domains?                               |
-| `recent-duplicates`, `echo`                          | New code duplicates older code.                       | Which existing owner should the new code reuse, and would reuse widen the wrong API?                  |
-| `incomplete-migration`                               | A helper extraction stopped halfway.                  | Is the helper in the right place for all remaining call sites?                                        |
-| `co-change`                                          | Files move together historically.                     | Does history imply a hidden shared owner or only a local synchronization point?                       |
+| Existing analyzer                                    | What it says today                               | Locality companion question                                                                           |
+| ---------------------------------------------------- | ------------------------------------------------ | ----------------------------------------------------------------------------------------------------- |
+| `react-large-component-pressure`                     | This React component is too large.               | If pieces are extracted, which ones are private, feature-local, or shared?                            |
+| `vue-large-view-pressure`                            | This Vue SFC is too large.                       | Should extracted child components/composables live beside the view, in the feature, or in app shared? |
+| `extract-candidates`                                 | This function has a region of exclusive callees. | Would the extracted helper have one real owner or a broader consumer set?                             |
+| `react-hook-candidates`, `vue-composable-candidates` | Several components repeat behavior.              | Is the hook/composable local to one feature or reusable across domains?                               |
+| `recent-duplicates`, `echo`                          | New code duplicates older code.                  | Which existing owner should the new code reuse, and would reuse widen the wrong API?                  |
+| `incomplete-migration`                               | A helper extraction stopped halfway.             | Is the helper in the right place for all remaining call sites?                                        |
+| `co-change`                                          | Files move together historically.                | Does history imply a hidden shared owner or only a local synchronization point?                       |
 
 ## Algorithm Sketch
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "scip-query",
-  "version": "0.23.0",
+  "version": "0.26.0",
   "description": "Evidence and verification for AI coding agents: map code, reuse concepts, finish migrations, and gate diffs.",
   "type": "module",
   "main": "dist/index.js",
@@ -21,7 +21,8 @@
     "scripts/verify-scip-windows.mjs",
     "skills/**/*.md",
     "skills/**/agents/*.yaml",
-    "skills/**/scripts/*.mjs"
+    "skills/**/scripts/*.mjs",
+    "scripts/record-review-coverage.mjs"
   ],
   "sideEffects": false,
   "exports": {
@@ -41,10 +42,6 @@
       "import": "./dist/queries/architecture.js",
       "types": "./dist/queries/architecture.d.ts"
     },
-    "./queries/anchors": {
-      "import": "./dist/queries/anchors.js",
-      "types": "./dist/queries/anchors.d.ts"
-    },
     "./queries/bottlenecks": {
       "import": "./dist/queries/bottlenecks.js",
       "types": "./dist/queries/bottlenecks.d.ts"
@@ -77,14 +74,6 @@
       "import": "./dist/queries/complexity.js",
       "types": "./dist/queries/complexity.d.ts"
     },
-    "./queries/complexity-hotspots": {
-      "import": "./dist/queries/complexity-hotspots.js",
-      "types": "./dist/queries/complexity-hotspots.d.ts"
-    },
-    "./queries/convergence": {
-      "import": "./dist/queries/convergence.js",
-      "types": "./dist/queries/convergence.d.ts"
-    },
     "./queries/coupling": {
       "import": "./dist/queries/coupling.js",
       "types": "./dist/queries/coupling.d.ts"
@@ -93,10 +82,6 @@
       "import": "./dist/queries/cycles.js",
       "types": "./dist/queries/cycles.d.ts"
     },
-    "./queries/dataflow": {
-      "import": "./dist/queries/dataflow.js",
-      "types": "./dist/queries/dataflow.d.ts"
-    },
     "./queries/dependence-slice": {
       "import": "./dist/queries/dependence-slice.js",
       "types": "./dist/queries/dependence-slice.d.ts"
@@ -113,18 +98,10 @@
       "import": "./dist/queries/decorative-checkers.js",
       "types": "./dist/queries/decorative-checkers.d.ts"
     },
-    "./queries/deep-chains": {
-      "import": "./dist/queries/deep-chains.js",
-      "types": "./dist/queries/deep-chains.d.ts"
-    },
     "./queries/entry-map": {
       "import": "./dist/queries/entry-map.js",
       "types": "./dist/queries/entry-map.d.ts"
     },
-    "./queries/system-map": {
-      "import": "./dist/queries/system-map.js",
-      "types": "./dist/queries/system-map.d.ts"
-    },
     "./queries/deps": {
       "import": "./dist/queries/deps.js",
       "types": "./dist/queries/deps.d.ts"
@@ -149,10 +126,6 @@
       "import": "./dist/queries/evidence.js",
       "types": "./dist/queries/evidence.d.ts"
     },
-    "./queries/extract-candidates": {
-      "import": "./dist/queries/extract-candidates.js",
-      "types": "./dist/queries/extract-candidates.d.ts"
-    },
     "./queries/fan": {
       "import": "./dist/queries/fan.js",
       "types": "./dist/queries/fan.d.ts"
@@ -185,10 +158,6 @@
       "import": "./dist/queries/index.js",
       "types": "./dist/queries/index.d.ts"
     },
-    "./queries/isolated": {
-      "import": "./dist/queries/isolated.js",
-      "types": "./dist/queries/isolated.d.ts"
-    },
     "./queries/locality-candidates": {
       "import": "./dist/queries/locality-candidates.js",
       "types": "./dist/queries/locality-candidates.d.ts"
@@ -213,10 +182,6 @@
       "import": "./dist/queries/passthrough-candidates.js",
       "types": "./dist/queries/passthrough-candidates.d.ts"
     },
-    "./queries/plan-context": {
-      "import": "./dist/queries/plan-context.js",
-      "types": "./dist/queries/plan-context.d.ts"
-    },
     "./queries/context": {
       "import": "./dist/queries/context.js",
       "types": "./dist/queries/context.d.ts"
@@ -229,30 +194,14 @@
       "import": "./dist/queries/redundant-reexports.js",
       "types": "./dist/queries/redundant-reexports.d.ts"
     },
-    "./queries/reference-neighborhood": {
-      "import": "./dist/queries/reference-neighborhood.js",
-      "types": "./dist/queries/reference-neighborhood.d.ts"
-    },
-    "./queries/reference-reachability": {
-      "import": "./dist/queries/reference-reachability.js",
-      "types": "./dist/queries/reference-reachability.d.ts"
-    },
     "./queries/refs": {
       "import": "./dist/queries/refs.js",
       "types": "./dist/queries/refs.d.ts"
     },
-    "./queries/self-audit": {
-      "import": "./dist/queries/self-audit.js",
-      "types": "./dist/queries/self-audit.d.ts"
-    },
     "./queries/similar": {
       "import": "./dist/queries/similar.js",
       "types": "./dist/queries/similar.d.ts"
     },
-    "./queries/similar-chains": {
-      "import": "./dist/queries/similar-chains.js",
-      "types": "./dist/queries/similar-chains.d.ts"
-    },
     "./queries/similar-files": {
       "import": "./dist/queries/similar-files.js",
       "types": "./dist/queries/similar-files.d.ts"
@@ -285,9 +234,9 @@
       "import": "./dist/queries/similar-signatures.js",
       "types": "./dist/queries/similar-signatures.d.ts"
     },
-    "./queries/slice": {
-      "import": "./dist/queries/slice.js",
-      "types": "./dist/queries/slice.d.ts"
+    "./queries/slice-cohesion": {
+      "import": "./dist/queries/slice-cohesion.js",
+      "types": "./dist/queries/slice-cohesion.d.ts"
     },
     "./queries/source-inspection": {
       "import": "./dist/queries/source-inspection.js",
@@ -297,10 +246,6 @@
       "import": "./dist/queries/source-search.js",
       "types": "./dist/queries/source-search.d.ts"
     },
-    "./queries/stale-abstractions": {
-      "import": "./dist/queries/stale-abstractions.js",
-      "types": "./dist/queries/stale-abstractions.d.ts"
-    },
     "./queries/stats": {
       "import": "./dist/queries/stats.js",
       "types": "./dist/queries/stats.d.ts"
@@ -321,14 +266,6 @@
       "import": "./dist/queries/test-quality.js",
       "types": "./dist/queries/test-quality.d.ts"
     },
-    "./queries/trace": {
-      "import": "./dist/queries/trace.js",
-      "types": "./dist/queries/trace.d.ts"
-    },
-    "./queries/twin-ab": {
-      "import": "./dist/queries/twin-ab.js",
-      "types": "./dist/queries/twin-ab.d.ts"
-    },
     "./queries/twin-drift": {
       "import": "./dist/queries/twin-drift.js",
       "types": "./dist/queries/twin-drift.d.ts"
@@ -337,18 +274,10 @@
       "import": "./dist/queries/unused-params.js",
       "types": "./dist/queries/unused-params.d.ts"
     },
-    "./queries/value-flow": {
-      "import": "./dist/queries/value-flow.js",
-      "types": "./dist/queries/value-flow.d.ts"
-    },
     "./queries/unused-imports": {
       "import": "./dist/queries/unused-imports.js",
       "types": "./dist/queries/unused-imports.d.ts"
     },
-    "./queries/wrapper-candidates": {
-      "import": "./dist/queries/wrapper-candidates.js",
-      "types": "./dist/queries/wrapper-candidates.d.ts"
-    },
     "./reindex": {
       "import": "./dist/reindex.js",
       "types": "./dist/reindex.d.ts"
@@ -356,6 +285,10 @@
     "./runtime": {
       "import": "./dist/runtime.js",
       "types": "./dist/runtime.d.ts"
+    },
+    "./queries/review": {
+      "import": "./dist/queries/review.js",
+      "types": "./dist/queries/review.d.ts"
     }
   },
   "scripts": {
@@ -366,12 +299,12 @@
     "test": "vitest run --maxWorkers=2",
     "soak:cache-lifecycle": "npm run build && vite-node scripts/cache-lifecycle-soak.ts",
     "test:watch": "vitest",
-    "typecheck": "tsc --noEmit && tsc -p tests/fixtures/invocation-coverage-contract/tsconfig.json && tsc -p tests/fixtures/protocol-state-contract/tsconfig.json",
+    "typecheck": "tsc --noEmit && tsc -p tests/fixtures/invocation-coverage-contract/tsconfig.json && tsc -p tests/fixtures/protocol-state-contract/tsconfig.json && npm run test:properties:types",
     "audit:prod": "node scripts/audit-production-dependencies.mjs",
     "api:report": "node scripts/api-surface-contract.mjs report",
     "api:check": "npm run build && node scripts/api-surface-contract.mjs check && tsc -p tests/fixtures/public-api-consumer/tsconfig.json",
     "api:update": "npm run build && node scripts/api-surface-contract.mjs update",
-    "lint": "npm run format:check && eslint src tests tsup.config.ts scripts/api-surface-contract.mjs scripts/audit-production-dependencies.mjs scripts/benchmark-cold-reindex.ts scripts/benchmark-graph-literal.ts scripts/benchmark-query-service.ts scripts/benchmark-reindex-accounting.ts scripts/benchmark-source-search.ts scripts/build-scip-windows.mjs scripts/cache-lifecycle-soak.ts scripts/codex-exploration-sandbox.mjs scripts/codex-exploration-trial-core.mjs scripts/codex-exploration-trial.mjs scripts/compare-exploration-trials.mjs scripts/exploration-benchmark-core.mjs scripts/exploration-benchmark.mjs scripts/npm-release-state.ts scripts/npm-release.ts scripts/publish-scip-windows.ts scripts/release-npm-guard.ts scripts/release-npm.ts scripts/scip-windows-package-identity.ts scripts/scip-windows-provenance.mjs scripts/scip-windows-release.ts scripts/verify-identity-collision-cli.mjs scripts/verify-scip-windows.mjs scripts/verify-scip-windows-registry.ts skills/scip-explore/scripts/capture-evidence.mjs && npm run api:check && node scripts/check-skill-links.mjs",
+    "lint": "npm run format:check && eslint src tests tsup.config.ts scripts/api-surface-contract.mjs scripts/audit-production-dependencies.mjs scripts/benchmark-cold-reindex.ts scripts/benchmark-graph-literal.ts scripts/benchmark-query-service.ts scripts/benchmark-reindex-accounting.ts scripts/benchmark-source-search.ts scripts/build-scip-windows.mjs scripts/cache-lifecycle-soak.ts scripts/record-review-coverage.mjs scripts/change-benchmark-core.mjs scripts/codex-change-trial.mjs benchmarks/change/checks.mjs benchmarks/change/reference-patches.mjs scripts/codex-exploration-sandbox.mjs scripts/codex-exploration-trial-core.mjs scripts/codex-exploration-trial.mjs scripts/compare-exploration-trials.mjs scripts/exploration-benchmark-core.mjs scripts/exploration-benchmark.mjs scripts/npm-release-state.ts scripts/npm-release.ts scripts/publish-scip-windows.ts scripts/release-npm-guard.ts scripts/release-npm.ts scripts/scip-windows-package-identity.ts scripts/scip-windows-provenance.mjs scripts/scip-windows-release.ts scripts/score-detector-labels.ts scripts/verify-identity-collision-cli.mjs scripts/verify-scip-windows.mjs scripts/verify-scip-windows-registry.ts skills/scip-explore/scripts/capture-evidence.mjs scripts/test-properties.mjs && npm run api:check && node scripts/check-skill-links.mjs",
     "build:scip-windows": "node scripts/build-scip-windows.mjs",
     "verify:scip-windows": "node scripts/verify-scip-windows.mjs",
     "verify:identity-collision-cli": "node scripts/verify-identity-collision-cli.mjs",
@@ -394,7 +327,11 @@
     "postinstall": "node dist/postinstall.js || true",
     "publish:scip-windows": "vite-node scripts/publish-scip-windows.ts",
     "release:npm": "vite-node scripts/release-npm.ts",
-    "release:npm:dry-run": "vite-node scripts/release-npm.ts --dry-run"
+    "release:npm:dry-run": "vite-node scripts/release-npm.ts --dry-run",
+    "bench:change": "node scripts/codex-change-trial.mjs",
+    "test:properties": "node scripts/test-properties.mjs",
+    "test:properties:thorough": "node scripts/test-properties.mjs --thorough",
+    "test:properties:types": "tsc -p tests/properties/tsconfig.json"
   },
   "keywords": [
     "scip",
@@ -453,6 +390,7 @@
     "@types/better-sqlite3": "^7.6.12",
     "@types/node": "^22.10.0",
     "eslint": "^10.2.0",
+    "fast-check": "4.9.0",
     "globals": "^17.5.0",
     "prettier": "^3.8.4",
     "tsup": "^8.3.0",

package/scripts/evidence-product-contract.mjs

@@ -165,14 +165,14 @@ function parseArgs(argv) {
       parsed.warmIterations = positiveInteger(argv[++index], '--warm-iterations');
     } else if (arg === '--command') {
       const value = argv[++index];
-      if (!value) throw new Error('--command requires a value');
+      requireEvidenceArgumentValue(value, '--command');
       parsed.commands.push(splitCommand(value));
     } else if (arg === '--out') {
       parsed.out = argv[++index];
-      if (!parsed.out) throw new Error('--out requires a value');
+      requireEvidenceArgumentValue(parsed.out, '--out');
     } else if (arg === '--profile-out') {
       parsed.profileOut = argv[++index];
-      if (!parsed.profileOut) throw new Error('--profile-out requires a value');
+      requireEvidenceArgumentValue(parsed.profileOut, '--profile-out');
     } else if (arg === '--no-clear') {
       parsed.noClear = true;
     } else {
@@ -195,3 +195,7 @@ function splitCommand(value) {
     .filter(Boolean)
     .filter((part, index) => !(index === 0 && part === 'scip-query'));
 }
+
+function requireEvidenceArgumentValue(value, flag) {
+  if (!value) throw new Error(`${flag} requires a value`);
+}

package/scripts/record-review-coverage.mjs

@@ -0,0 +1,118 @@
+#!/usr/bin/env node
+import { createHash } from 'node:crypto';
+import { execFileSync, spawnSync } from 'node:child_process';
+import { existsSync, mkdirSync, readFileSync, realpathSync, statSync, writeFileSync } from 'node:fs';
+import { dirname, isAbsolute, relative, resolve, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const hash = (bytes) => createHash('sha256').update(bytes).digest('hex');
+
+/** Wrap an actual test run, proving its coverage was produced against unchanged source bytes. */
+export function recordReviewCoverage({ root, input, output, command, args = [] }) {
+  const inputPath = inside(root, input);
+  const outputPath = inside(root, output);
+  if (inputPath === outputPath) throw new Error('Coverage input and receipt output must be different files.');
+  const before = runStableCoverageCommand(root, command, args, inputPath);
+  const files = matchedCoverageFiles(root, inputPath, before);
+  mkdirSync(dirname(outputPath), { recursive: true });
+  writeFileSync(
+    outputPath,
+    JSON.stringify(
+      { schemaVersion: 1, recordedAt: new Date().toISOString(), command: [command, ...args], files },
+      null,
+      2,
+    ) + '\n',
+  );
+  return { output: outputPath, files: Object.keys(files).length };
+}
+
+function runStableCoverageCommand(root, command, args, inputPath) {
+  const before = sourceHashes(root);
+  const previous = existsSync(inputPath) ? statSync(inputPath, { bigint: true }) : null;
+  const started = BigInt(Date.now()) * 1_000_000n;
+  const result = spawnSync(command, args, { cwd: root, stdio: 'inherit', shell: false });
+  if (result.error) throw result.error;
+  if (result.status !== 0)
+    throw new Error(`Test command did not succeed (${result.signal ?? result.status}). Coverage was not recorded.`);
+  const current = statSync(inputPath, { bigint: true });
+  if (current.mtimeNs < started || (previous && previous.mtimeNs === current.mtimeNs && previous.ino === current.ino)) {
+    throw new Error('The test command did not produce a fresh coverage artifact.');
+  }
+  const after = sourceHashes(root);
+  if (JSON.stringify(before) !== JSON.stringify(after))
+    throw new Error('Source changed during the test run. Rerun against stable files.');
+  return before;
+}
+
+function matchedCoverageFiles(root, inputPath, before) {
+  const istanbul = JSON.parse(readFileSync(inputPath, 'utf8'));
+  const files = {};
+  for (const [key, coverage] of Object.entries(istanbul)) {
+    const file = relative(root, resolve(root, coverage.path ?? key))
+      .split(sep)
+      .join('/');
+    if (!before[file]) continue;
+    if (!coverage.statementMap || !coverage.s) throw new Error(`Missing Istanbul statement coverage for ${file}.`);
+    files[file] = { sourceHash: before[file], coverage };
+  }
+  if (Object.keys(files).length === 0) throw new Error('Coverage contains no source files matching this checkout.');
+  return files;
+}
+
+function sourceHashes(root) {
+  const paths = [
+    ...new Set(
+      execFileSync('git', ['ls-files', '-co', '--exclude-standard', '-z'], {
+        cwd: root,
+        encoding: 'utf8',
+        maxBuffer: 32 * 1024 * 1024,
+      }).split('\0'),
+    ),
+  ].sort();
+  const hashes = {};
+  for (const file of paths) {
+    if (!/\.[cm]?[jt]sx?$/.test(file) || /(^|\/)(node_modules|dist|build|coverage|\.scipquery)(\/|$)/.test(file))
+      continue;
+    const absolute = inside(root, file);
+    if (existsSync(absolute)) hashes[file] = hash(readFileSync(absolute));
+  }
+  return hashes;
+}
+
+function inside(root, file) {
+  const absolute = resolve(root, file);
+  const rel = relative(root, existsSync(absolute) ? realpathSync(absolute) : absolute);
+  if (rel === '..' || rel.startsWith('..' + sep) || isAbsolute(rel)) throw new Error(`Path escapes project: ${file}`);
+  return absolute;
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  try {
+    const argv = process.argv.slice(2);
+    const separator = argv.indexOf('--');
+    if (separator < 0 || !argv[separator + 1])
+      throw new Error(
+        'Usage: node record-review-coverage.mjs [--input coverage/coverage-final.json] [--output .scipquery/coverage.json] -- <test-command> [args...]',
+      );
+    const flags = argv.slice(0, separator);
+    let input = 'coverage/coverage-final.json';
+    let output = '.scipquery/coverage.json';
+    for (let i = 0; i < flags.length; i += 2) {
+      if (!flags[i + 1]) throw new Error(`Missing value for ${flags[i]}`);
+      if (flags[i] === '--input') input = flags[i + 1];
+      else if (flags[i] === '--output') output = flags[i + 1];
+      else throw new Error(`Unknown option: ${flags[i]}`);
+    }
+    const result = recordReviewCoverage({
+      root: realpathSync(process.cwd()),
+      input,
+      output,
+      command: argv[separator + 1],
+      args: argv.slice(separator + 2),
+    });
+    process.stdout.write(`Recorded source-matched coverage for ${result.files} files: ${result.output}\n`);
+  } catch (error) {
+    process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+    process.exitCode = 1;
+  }
+}

package/scripts/scip-windows-provenance.mjs

@@ -49,25 +49,7 @@ export function sha256(bytes) {
 }
 
 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 peOffset = portableExecutableHeaderOffset(bytes, filename);
 
   const machineCode = bytes.readUInt16LE(peOffset + 4);
   const target = WINDOWS_SIDECAR_TARGETS.find((candidate) => candidate.peMachineCode === machineCode);
@@ -94,6 +76,34 @@ export function inspectPortableExecutable(bytes, filename = '<binary>') {
   };
 }
 
+function portableExecutableHeaderOffset(bytes, filename) {
+  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.`);
+  }
+  validatePortableExecutableSignature(bytes, peOffset, filename);
+
+  return peOffset;
+}
+
+function validatePortableExecutableSignature(bytes, peOffset, filename) {
+  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.`);
+  }
+}
+
 export function inspectWindowsSidecarBinary(file, readFile = readFileSync) {
   const bytes = readFile(file);
   const pe = inspectPortableExecutable(bytes, file);

package/skills/scip-architecture-review/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: scip-architecture-review
+description: Evaluate architecture and maintainability for coding agents. Find ambiguous owners, duplicated rules, leaked coordination, misleading boundaries, and dependency problems; justify changes from behavior and consumers.
+---
+
+# SCIP Architecture and Maintainability Review
+
+Load `$scip-query` for mechanics. Use ordinary file tools for implementation reads and scip-query for the relationships and findings that guide the investigation. This workflow covers first-use assessment, later design reassessment, and the structural consequences of changes. Use `$scip-integrity-audit` when the issue is whether a feature fulfills its promise.
+
+Choose from the shared guide's [architecture and dependency commands](../scip-query/references/command-guide.md#architecture-and-dependencies), [simplification and cleanup commands](../scip-query/references/command-guide.md#simplification-and-cleanup), or [framework investigations](../scip-query/references/command-guide.md#framework-investigations) when a concrete concern calls for that analysis. Each row explains its question, index requirement and limits.
+
+A module assigns responsibility to a group of code, such as storing documents or calculating eligibility. Its interface is the operations and rules consumers must understand: inputs, results, errors, effects, and ordering. A dependency exists when one implementation relies on another's behavior or representation.
+
+Maintainability is the ability to change required behavior correctly without unnecessary discovery, duplicated decisions, or coordinated edits. Evaluate mistakes the structure would invite an agent to make and the facts it must discover to avoid them. File size, folder names, interface counts, and clean dependency rules do not establish design quality.
+
+## Orient without inventing owners
+
+Run `scip-query system --source` for current TS/JS module groups and imports, including groups without findings. It needs no index or architecture configuration. Group IDs distinguish declared boundaries from provisional directories. Read coverage and missing configuration before claiming whole-repository visibility.
+
+Use a printed group selector to investigate its files, dependencies, consumers, source interface evidence, findings, and limits. Use `health` for ranked cleanup candidates when useful and `architecture` for declared policy. Neither substitutes for behavior.
+
+For a large review, record groups inventoried, relationships investigated, concerns confirmed/rejected, and unresolved scopes. Follow important cross-group relations as well as directory children. A structural inventory of all files is not a behavioral review of all modules.
+
+## Evaluate maintenance consequences
+
+| Concern                                    | Evidence to seek                                                                        | Counterevidence                                                        |
+| ------------------------------------------ | --------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
+| Unclear owner or competing implementations | One rule is independently decided in live paths; fixes or thresholds disagree           | Different contracts, versions, platforms, or compatibility obligations |
+| Caller coordination                        | Consumers repeat preparation, transaction, ordering, or cleanup for one responsibility  | The consumer owns the broader operation or transaction                 |
+| Weak interface                             | Consumers require internal formats or undocumented ordering                             | Required control, performance, or interoperability                     |
+| Mixed responsibilities                     | Operations have separate state, consumers, dependencies, and reasons to change          | A shared lifecycle, invariant, or public capability                    |
+| Dependency direction                       | Independent policy imports delivery mechanisms; a cycle obstructs a required separation | Deliberate orchestration or a grouping-only cycle without a file cycle |
+| Unnecessary mechanisms                     | Copies, wrappers, registries, or pipelines require several updates for one decision     | An adapter isolates a real change boundary or distinct contract        |
+
+A deep module provides useful behavior while exposing relatively little implementation knowledge to callers. Examine required knowledge and coordination. One argument with dozens of interacting settings does not establish depth; adding implementation lines does not improve it.
+
+Read relevant implementations AND consumers. State: “When an agent changes X, it must also discover/change Y because Z; this proposal removes that obligation by …”. Name the strongest example that could invalidate the proposal. Similar syntax or names do not establish interchangeable behavior.
+
+For recurring bugs, trace mechanisms to a specific violated rule, test competing explanations, and investigate predicted instances elsewhere. A missed predicted instance does not by itself disprove the diagnosis or establish absence.
+
+## Preserve justified decisions
+
+A configured boundary maps files to a named policy group. An allowed-dependency row states which groups it may depend on; missing rows remain unknown. Record reasons for important directions in design documentation, not only current imports.
+
+Use existing `.scipquery.json` controls for membership, allowed directions, and relevant cycle/coverage constraints. Do not automatically bless all current edges, raise size limits, or widen allowances to clear a report. Counts locate candidates; they are not universal design laws.
+
+Later reassess responsibilities and allowances from present behavior and realistic changes. Report policy compliance separately from whether the policy still serves the project.
+
+## Recommend or implement
+
+Record exact code/consumers, the maintenance mistake invited, supporting evidence and limits, counterevidence, proposed owner/interface, preserved behavior, what disappears, and checks exposing a mistaken change.
+
+Combine symptoms of the same scattered rule. Compare alternative shapes when they materially change consumers or state ownership; do not require several designs for a trivial edit.
+
+For larger simplifications read [design checks](references/design-checks.md) and use `$scip-plan`. Carry authorized fixes through migration, retirement, behavioral checks, current-source review, and fresh impact analysis. Review-only work stops at an evidence-backed assessment.
+
+The result is supported decisions and specific unknowns, not a grade. Retaining the design is valid when a concern does not survive investigation.

package/skills/scip-architecture-review/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Architecture and Maintainability"
+  short_description: "Review owners, interfaces, and dependencies."
+  default_prompt: "Use $scip-architecture-review to identify concrete maintenance mistakes this design invites and assess changes using behavior and consumers."

package/skills/scip-architecture-review/references/design-checks.md

@@ -0,0 +1,17 @@
+# Design checks
+
+Load for concerns sharing a design cause or changes crossing owners.
+
+Look for one responsibility behind several mechanisms: repeated resource lifecycles, copied failure policy, separate registries/docs describing one command surface, or repeated eligibility calculations. Establish sameness from behavior, state, and consumers.
+
+A consolidation should remove duplicated knowledge or prevent inconsistent decisions. A wrapper accepting many callbacks may move coordination without removing it. Preserve grammar, protocol, platform, and compatibility differences when they change the contract.
+
+Consider removing a redundant layer, placing a repeated rule behind an existing owner, deriving repeated representations from an authoritative registry, or separating unrelated responsibilities. Choose a coherent mechanism preserving behavior; minimum file size and line count are not objectives.
+
+Use realistic product changes to test the benefit: alter eligibility, replace a storage representation, add an operation, or change retry policy. Identify the old places an agent must discover/coordinate and the proposed places. Explain remaining necessary cross-module edits.
+
+Read consumers capable of refuting the interface. Preserve incomplete consumer coverage; a simple caller does not prove every caller can use the same operation.
+
+For multi-step work keep concerns, owners, consumers, dispositions, dependency order, and checks in one plan. Link symptoms to their shared cause. Name obsolete implementations, routes, registrations, fallbacks, artifacts, and docs to retire. Preserve resource identity, state transitions, and observable ordering. Adding a new implementation beside an old live one does not complete consolidation.
+
+Evaluate the workflow using representative tasks with and without the tool/skill, the same model and constraints, and repeated trials where variability matters. Include coherent designs and intentional adapters alongside defects. Inspect actual patches and tests for missed consumers, duplicated rules, incorrect behavior, and unnecessary edits. Measure structural accuracy separately from design conclusions; fewer findings do not prove better agent-produced code.