diff --git a/.env.example b/.env.example index 40cc72e20..9d28c508e 100644 --- a/.env.example +++ b/.env.example @@ -285,3 +285,110 @@ # Current user — used as an agent-name fallback. USERNAME is the Windows form. # USER=you # USERNAME=you + +# Node's process options and native coverage directory. The e2e harness can +# select a separate coverage destination for child processes. +# NODE_OPTIONS= +# NODE_V8_COVERAGE= +# INTERLINKED_E2E_V8_DIR= + +# Platform temp directory on Unix; Windows user-local application data is also +# consulted when locating installed browser binaries. +# TMPDIR= +# LOCALAPPDATA= +# PLAYWRIGHT_BROWSERS_PATH= + +# Git honors these standard overrides when selecting the working tree and +# the global and system configuration files. Tests use isolated config files. +# GIT_WORK_TREE= +# GIT_CONFIG_GLOBAL= +# GIT_CONFIG_SYSTEM= + +# GitHub Actions sets the event identity and payload file for CI selection. +# The remaining files receive step outputs, environment updates and summaries. +# GITHUB_ACTIONS= +# GITHUB_SHA= +# GITHUB_EVENT_NAME= +# GITHUB_EVENT_PATH= +# GITHUB_OUTPUT= +# GITHUB_ENV= +# GITHUB_STEP_SUMMARY= + +# Override Biome's config selection; the check runner respects an explicit +# path when deciding whether to generate a temporary overlay. +# BIOME_CONFIG_PATH= +# Codex configuration directory used when installing a named network profile. +# CODEX_HOME= +# Model cache directory for the optional local semantic index. +# INTERLINKED_MODEL_CACHE= +# Resident memory ceiling for the harness daemon, expressed in MiB. +# INTERLINKED_HARNESS_RSS_CEILING_MB= +# The detached e2e launcher sets this flag so its worker rechecks the project's +# automatic-run policy before executing a queued request. +# INTERLINKED_AUTO_RUN= + +# Optional evaluation runners: choose a temporary directory or override the +# model selected for an explicitly requested evaluation. +# EVALS_TMPDIR= +# EVALS_CLAUDE_MODEL= +# EVALS_CODEX_MODEL= +# The opt-in decision-metrics service reads this credential at runtime. +# Supply it through the process environment or local, untracked configuration. +# TYPESAFE_API_KEY= + +# Replay and capture. The proxy uses the upstream URL and capture directory. +# Cloud replay evaluation reads its Anthropic credential from the environment. +# ANTHROPIC_REAL_BASE_URL= +# INTERLINKED_REPLAY_DIR= +# ANTHROPIC_API_KEY= +# Opt in to Git tree snapshots at replay event boundaries. +# INTERLINKED_REPLAY_TREE_SNAPSHOTS= +# Replay can select the recorded event timestamp as the harness clock. +# INTERLINKED_REPLAY_CLOCK= +# Label captured records by origin (test, probe or imported). +# INTERLINKED_CAPTURE_ORIGIN= + +# Plugin runners supply the Cowork plugin installation directory. +# CLAUDE_PLUGIN_ROOT= +# Unix cache directory used to locate local semantic models. +# XDG_CACHE_HOME= +# Git stops searching for a repository above these directories. +# GIT_CEILING_DIRECTORIES= + +# External research integrations read credentials from the process at runtime. +# Optional Cloudflare evaluation jobs use the account identity and API token. +# The R2 SQL data-lab command uses a separate Wrangler authentication token. +# CLOUDFLARE_ACCOUNT_ID= +# CLOUDFLARE_API_TOKEN= +# WRANGLER_R2_SQL_AUTH_TOKEN= + +# Go checker subprocesses cap concurrency and can set build flags and a cache +# directory. GOCACHE is the Go toolchain's own cache setting. +# GOMAXPROCS= +# INTERLINKED_GOFLAGS= +# INTERLINKED_GOCACHE= +# GOCACHE= +# Cargo's per-user registry and configuration directory. +# CARGO_HOME= + +# Test and CI controls. Vitest supplies its own run marker. The test harness +# uses the project root to prevent fixture writes to the real capture store. +# VITEST= +# INTERLINKED_TEST_PROJECT_ROOT= +# The property runner reads the per-edit example budget; Stryker's Vitest +# configuration accepts a comma-separated list of test globs. +# INTERLINKED_PROPERTY_NUMRUNS= +# INTERLINKED_MUTATION_TESTS= +# Enable the Vitest event reporter for the live visualization. +# INTERLINKED_VIZ= +# Opt in to the long-running daemon stability and coverage-overlay tests. +# E2E_STABILITY= +# INTERLINKED_RUN_COVERAGE_OVERLAY_E2E= + +# Pre-push and scheduled coverage runs write scope receipts to these paths. +# The pre-push reporter accepts comma-separated target files. +# INTERLINKED_PRE_PUSH_COVERAGE_SCOPE= +# INTERLINKED_COVERAGE_SCOPE_FILE= +# INTERLINKED_PRE_PUSH_COVERAGE_TARGETS= +# The CI selection comparison script can run against another checkout. +# SELECT_COMPARE_ROOT= diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index a947e23ce..23cf6c58d 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -62,13 +62,12 @@ jobs: - name: Install dependencies run: npm ci - # Runner images ship no ripgrep; without it the grep-accelerator's real-rg - # paths diverge from every dev machine (finding 2026-06: that shipped a red - # run). A unit test could still reach an rg path, so install it here too. - - name: Install ripgrep (CI/dev environment parity) + # The completion tests load the generated scripts in a real shell. + - name: Install ripgrep and zsh for unit tests run: | - sudo apt-get update -q && sudo apt-get install -y -q ripgrep + sudo apt-get update -q && sudo apt-get install -y -q ripgrep zsh rg --version + zsh --version - name: Typecheck run: npm run typecheck:stable @@ -119,6 +118,9 @@ jobs: sudo apt-get update -q && sudo apt-get install -y -q ripgrep rg --version + - name: Test Python sidecar protocol + run: python3 -B -m unittest discover -s test -p 'test_*.py' + - name: Test (integration lane) run: npm run test:integration -- --reporter=default --reporter=github-actions --reporter=json --outputFile.json=test-report/integration.json diff --git a/.github/workflows/e2e-release-matrix.yml b/.github/workflows/e2e-release-matrix.yml index a572a88e4..0342c1cc4 100644 --- a/.github/workflows/e2e-release-matrix.yml +++ b/.github/workflows/e2e-release-matrix.yml @@ -19,7 +19,7 @@ on: jobs: matrix: name: release matrix (Linux / Node 22 / Python 3 / Rust stable / Chromium) - runs-on: ubuntu-latest + runs-on: ubuntu-24.04 timeout-minutes: 40 steps: - uses: actions/checkout@v4 diff --git a/.gitignore b/.gitignore index abfd4c25a..afbc7a318 100644 --- a/.gitignore +++ b/.gitignore @@ -168,6 +168,8 @@ src/lib/_write_integration/ # blocks NEW additions. Drop a `!scripts/foo.mjs` carve-out below if a # new file in this directory needs to ship to the repo. scripts/* +!scripts/generate-docs.test.mts +!scripts/semantic-study-drivers.test.mjs # Maintained evidence qualification and advisory audit entry points. !scripts/evidence-deep-audit.mts !scripts/evidence-deep-audit.test.mts @@ -193,6 +195,8 @@ scripts/internal/* !scripts/generate-managed-push-manifest.mjs !scripts/build-atomic.mjs !scripts/build-atomic-cli.mjs +!scripts/cli-reference-help.ts +!scripts/cli-reference-help.test.mts !scripts/build-atomic.test.mjs !scripts/build-input-fingerprint.mjs !scripts/e2e-*.mjs diff --git a/.gitleaks.toml b/.gitleaks.toml index 251adddd2..5acd51bd2 100644 --- a/.gitleaks.toml +++ b/.gitleaks.toml @@ -3,6 +3,9 @@ title = "interlinked-cli gitleaks config" +[extend] + useDefault = true + [allowlist] description = "Known false positive paths and patterns" paths = [ diff --git a/AGENTS.md b/AGENTS.md index 553ff77b3..f5891dfc4 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,67 +1,183 @@ -# Repository Guidelines - -## Project Structure & Module Organization -This package is the TypeScript source for **Interlinked CLI**. -- **Interlinked MCP Server** refers to the remote Cloudflare Worker system that the CLI optionally talks to. -- **Interlinked CLI** refers to this package. -- `src/index.ts`: CLI entry point and command registration. -- `src/commands/*.ts`: command handlers (`enable`, `status`, `doctor`, `workspace`, etc.). -- `src/lib/*.ts`: shared logic (auth, config, hooks, API client, formatting). -- `src/templates/`: generated/template assets used by setup flows. -- `src/**/*.test.ts` and `src/commands/__tests__/`: Vitest unit/regression tests. -- `docs/architecture.md`: architecture notes. -- `dist/`: build output (generated). - -## Build, Test, and Development Commands -- `npm run dev`: run the CLI directly with `tsx` for local development. -- `npm run build`: bundle `src/index.ts` to `dist/` with type declarations (`tsup`). -- `npm run typecheck`: run TypeScript checks with `tsgo` (`tsgo --noEmit`). -- `npm run typecheck:stable`: run the stable TypeScript compiler (`tsc --noEmit`). -- `npm run test`: run tests once (`vitest run`). -- `npm run test:watch`: run tests in watch mode. -- `npm run docs`: regenerate generated CLI/harness reference docs. - -Example: +# Interlinked CLI: agent guide + +Loaded every turn by every coding agent (Claude Code through `CLAUDE.md`, Codex +directly). Keep it under 200 lines: rules only, no dates, status labels, counts, +or history. Subtree rules live in `.claude/rules/*.md` (Claude loads them when a +matching file is touched; other runners: read the matching rule file before you +edit a subtree). Procedures live in `skills/*/SKILL.md`, history in `docs/`. + +## What this is for + +Interlinked is a portable, per-tool-call quality and security standard for +agent-written code. A local daemon (`src/harness/`) judges each tool call over a +Unix socket: PreToolUse returns block/allow, PostToolUse returns warnings, Stop +returns reflection nudges; every event is appended to JSONL under +`.interlinked/`. Offline-first, one required dependency (`commander`). Goals, in +priority order: judge code at the moment it is written in ANY codebase (this repo +is an unrepresentative fixture); ratchet the quality of whatever codebase it runs +in, diff-scoped by default; catch each problem at the earliest phase its evidence +exists; double as a step-level training signal for other agents. + +Consequences that bind every change to a check, gate, or threshold: + +- **Fire rate measures the AGENT, not the check.** A check that never fires here + is the part of the standard this agent already clears. Never retire or demote a + check for being quiet. +- **Never calibrate a threshold against this repo alone, nor against fixtures.** + Calibrate against real trees. +- **Blocking and scoring have different precision bars.** `pre_block` is reserved + for fully deterministic, zero-false-positive errors; everything else warns or + scores, tagged `[proven]` or `[heuristic]`. +- **More checks are a cost**, and gates will be Goodharted once they are a + training signal; the gated agent can write the water-lines it is judged by. +- **Checks are deterministic.** No model sits in the check pipeline or in + `interlinked verify`. Jev / Haiku signals are opt-in, warn-only, fail-open, and + only rank or propose. +- **Registry-wide rework waits** until the harness has run against a genuinely + different codebase; the vision is validated at N=1. + +The remote "Interlinked MCP Server" surface (`src/lib/api-client.ts`, server-backed +commands, event sync) is dormant and not the system of record; the local harness is +the product. Leave it alone unless the task is about it. + +## Layout and commands + +`src/commands/` (CLI, `commander`, shared logic in `src/lib/`), `src/harness/` +(daemon: `server.ts`, `evaluator/`, `checks/.ts` + `check-registry/` + +`check-metadata.ts`, `quality-checks/`, `project-e2e/`, `kill-proof/`), +`skills/*/SKILL.md` (procedures; `interlinked/` is the router), `docs/harness.md` +and `docs/generated/` (reference), `.interlinked/` (runtime data and baselines; +`INDEX.md` is the catalog). + ```bash -npm run dev -- status --short +npm run build | typecheck | test # tsup → dist/ · tsgo --noEmit · vitest (background the full suite) +npx vitest run # one file +npx tsx src/index.ts # CLI from source +interlinked harness status|restart # daemon pid + rules; restart rebuilds a stale dist/ +interlinked verify [--all-checks] # default set must run clean; --all-checks adds advisory +interlinked query --since 7d --where k=v # bounded reads of .interlinked/ +npm run docs && npm run docs:build # regenerate reference docs + gen-markered counts (CI: docs:check) ``` -## Agent Notes -- `QuentinCody/interlinked-cli` is the source of truth for the CLI. -- Keep the exact product terms distinct: **Interlinked CLI** is this package; **Interlinked MCP Server** is the remote Worker/Durable Objects system used by server-backed commands. -- Harness phase split: PreToolUse handles deterministic pre-execution blocks and warnings (destructive commands, file reservations, secrets-in-content, grep acceleration). PostToolUse handles checks that need files on disk or project context (type/lint/security/structure), and should report only new findings through diff-aware filtering. -- Zero-FP contract: `pre_block` error checks must be fully deterministic. Heuristic smell/taste/coverage checks belong as warnings or in `verify --all-checks`. When changing advisory policy, update `DEFAULT_ADVISORY_SKIPS` and its regression tests together. -- Adding an agent-quality check usually touches `src/harness/generic-checks.ts`, the check registry entries, `src/harness/check-metadata.ts`, `src/harness/check-registry/` entry files, `src/commands/verify*`, and parity/advisory tests. Land those coupled changes together. -- Hook scripts generated by the CLI must stay self-contained. PostToolUse is intentionally scoped to mutating tools, and `PostToolUseFailure` is intentionally not registered to avoid duplicate hook-count/output issues; see `docs/investigation-posttooluse-hook-count.md` before changing hook matchers. -- Rule/check metadata changes require `npm run docs`; do not hand-edit stale generated counts. -- Major changes in this repository MUST include a skill-impact review. This includes user-visible CLI commands/options/output, harness behavior or policy, configuration schemas/defaults, supported-client behavior, baseline semantics, and architecture or operator workflows. Update every affected `skills/*/SKILL.md` in the same change; code or design-doc updates alone are not complete when agent guidance changed. If no skill is affected, state why in the final handoff. -- Keep the skill router and focused skills aligned: update `skills/interlinked/SKILL.md` when a capability's routing changes, and update the relevant focused skill with the current command/config contract and operational gotchas. Treat `.agents/skills/` as an installed/generated copy, not the source of truth. Validate every touched skill folder with the skill validator before handoff. -- Supported coding clients (`interlinked enable --clients `): `claude`, `copilot`, `gemini`, `codex`, `cursor`, `opencode`, `pi`. Native hook contracts live in `src/harness/adapters/`; legacy/per-client migration helpers live in `src/lib/hook-installers*.ts`; `src/lib/hooks.ts` is the orchestrator that wires them through `CLIENT_INSTALL_REGISTRY`. The generated `.mjs` script disambiguates Codex (Claude-shaped payloads) from Claude via the `INTERLINKED_CLIENT` env var set by the installed hook command. OpenCode and Pi use managed bridge files rather than the generated `.mjs` runtime. -- Codex CLI hook gating: `installCodexHooks` writes `.codex/hooks.json` AND ensures `[features] hooks = true` in `.codex/config.toml`. Without that flag Codex silently ignores the hooks.json file. Uninstall leaves config.toml untouched to avoid clobbering user-managed Codex configuration. - -## Coding Style & Naming Conventions -- Language: TypeScript (ESM, strict mode). -- Style in this repo: 4-space indentation, double quotes, semicolons. -- File names: use descriptive kebab-case where practical (for example, `activity-utils.ts`). -- Exports: use `camelCase` for functions and `PascalCase` for types/interfaces. -- Command handlers should stay in `src/commands/`; reusable logic belongs in `src/lib/`. - -## Testing Guidelines -- Framework: Vitest (`environment: node`, configured in `vitest.config.ts`). -- Test file pattern: `src/**/*.test.ts`. -- Prefer colocated regression tests for command behavior under `src/commands/__tests__/`. -- Add tests for bug fixes, especially around config merging, auth flows, and CLI output modes. - -## Commit & Pull Request Guidelines -- Follow conventional commit style seen in history: `feat: ...`, `fix: ...`, `refactor: ...` (optional scope is fine). -- Keep commit subjects short and imperative. -- PRs should include: - - What changed and why. - - Commands run (`npm run typecheck`, `npm run test`). - - Linked issue/task, if applicable. - - Terminal output snippets when user-facing CLI behavior changes. - -## Security & Configuration Tips -- Never commit secrets from `.interlinked/config.local.json` (tokens are local-only). -- Prefer environment variables for automation (for example, `INTERLINKED_ACCESS_TOKEN`). -- Treat `clean`/`reset` operations as destructive; validate target workspace/project context first. +## Working rules + +**Edits.** Change code files only with Edit/Write (bash redirects into code files +are blocked); prefer Edit over Write; land a same-file change as one coherent +patch; several tool calls in one message are not a transaction. Write the +companion test before a new source file. Keep unfiltered `cat`/`head`/`tail` +reads bounded; the gate caps them. Verify after substantive edits (about one +typecheck/test/build run per code edit; the Stop nudge fires far below that). +Fix pre-existing issues in files you touch. Extract helpers for responsibility, +never to dodge a per-call metric. + +**Git.** Never commit or push unless the user asks in the current turn. Commit +subjects are conventional (`feat:`, `fix:`, `refactor:`), short, imperative. +Background `git push`; its pre-push gates run for minutes. + +**Scratch.** Temporary agent-authored code goes in `/scratch/` +(`interlinked scratch init`), never the host scratchpad; the guard blocks and +redirects. Secrets never go to any temp path. A hand-rolled patch applier is +blocked everywhere. Before long work, keep a numbered plan with a status column +in `scratch/CAMPAIGN-.md`. + +**Data.** Query `.interlinked/` before raw transcripts. Never full-read +`collection.jsonl`, `activity.jsonl`, or `timeline.jsonl` (hundreds of MB); +use `interlinked query` or `tail -n`. + +**A blocked edit is a stale-daemon suspect first.** The daemon serves the build +it started with; editing `src/` changes nothing until a rebuild. Check with +`interlinked harness status`; fix with `interlinked harness restart` (rebuilds a +stale `dist/`). Daemons also hand over to a newer settled build on their own +within about a minute. `npm run build:e2e` overwrites `dist/` with the e2e build: +run `npm run build` after the e2e lane. After editing an e2e boundary file, run +`npm run build:e2e && npm run test:e2e`; the Stop reminder for it reaches no model. +After a completed change to agent-facing daemon behavior passes its relevant tests, +rebuild/reload with `interlinked harness restart` and confirm a responding, current +build with `interlinked harness status`. Do this at each such milestone, not only +at the end of a campaign; untested intermediate edits are not reload milestones. + +**Keep cwd at the repo root.** The hook resolves its project by walking up to +the nearest `.interlinked/` that holds a project marker; a stray `.interlinked/` +under `scratch/` or `src/` cold-allows every call made from below it. Delete +strays; `interlinked harness calls` lists unjudged calls. + +**A dry run must not move the gate.** `interlinked harness test --write/--edit` +sets `dry_run: true`; every evaluator that persists must honor `event.dry_run`. + +**Human-only actions.** Package approval (`interlinked allowlist add`, `--force`, +`INTERLINKED_DISABLE_PACKAGE_GUARD`), water-line resets +(`INTERLINKED_DISABLE_BASELINE_GUARD`), and `harness taint clear` are the +operator's calls; ask, do not run them. + +**Skill impact.** A change to a CLI command, option, output, harness policy, +config schema or default, or baseline semantics updates every affected +`skills/*/SKILL.md` (and the router) in the same change, or states why none is +affected. `.claude/skills/` and `.agents/skills/` are installed copies. + +**Privacy.** `docs/design`, `docs/plans`, `docs/external-pulse`, +`docs/codex-reviews`, marketing and upstream-bug notes are real files here but +gitignored from the public repo (operator overlay git-dir); `.ignore` negations +keep them searchable. Competitive, strategy, and unfixed-gap analyses never go in +tracked files. Before "what can we do with X?" about an external tool or paper, +fill `docs/external-pulse/INTAKE.md`. + +**Style.** TypeScript ESM strict; tabs (the biome formatter is off); double +quotes, semicolons; kebab-case files, `camelCase` functions, `PascalCase` types. +Commands support `--json | --short | --full` via `getOutputMode` + `output(...)`, +degrade to local on server failure (`Promise.allSettled`), and take +`--dry-run` / `--force` when they mutate. The generated hook program stays +self-contained (no imports from the CLI package). + +## Gates you will meet + +Values live in `.interlinked/metric-caps.json`, the baselines beside it, and +`interlinked caps status`; never in prose. The block message names the fix. + +- **Water-lines only tighten.** `evaluator/baseline-integrity-gate.ts` BLOCKS an + edit that loosens any baseline JSON under `.interlinked/` (coverage, mutation, + line cap, untested files, metric caps, complexity ledger, lint, skipped tests), + a tsconfig strictness flag, or a vitest `coverage.include/exclude` array. Meet + the bar instead. The ratchets' own raises use internal `fs` writes. +- **Cyclomatic, cognitive, coverage, CRAP.** A new over-cap function, over-cap + growth, an uncovered added line, or a per-file coverage drop blocks; holding or + shrinking existing debt never does (the ledger, written only by + `interlinked caps ratchet`, records what may hold). The block carries a + `↳ plan:` line. Unknown coverage is not 0%. +- **Line cap is advisory.** Growing a hand-written module past + 500 lines warns; it never blocks. + `DEFAULT_MAX_LINES` and the baseline's `max_lines` are pinned equal, so ratchet + both. Codegen data is exempt via a `@codegen-data` header; the grandfather list + is empty. When a parent is over cap, helpers go to a NEW sibling module + (companion test, module, then the parent import). +- **Checks.** `pre_block` findings are introduced-only (`pre-block-gate.ts`); + pre-existing ones warn. Suppress with `// interlinked-ignore: — reason` + or `.interlinked/verify-suppressions.json`; a suppression comment without a + reason is its own loud warning. Built-in guard rules cannot be modified, only + disabled via `disabled_rules` in `.interlinked/guard-rules.local.json`. +- **Supply chain.** Package installs are default-deny across shell, manifest + edits, and the cold path; grants live in `.interlinked/package-allowlist.json`. + URL/tarball/`file:` specs and custom registries are blocked unconditionally. + +## Adding or changing a check + +Detector in `src/harness/checks/.ts` (never the `generic-checks.ts` +barrel), registry entry in `check-registry/entries-*.ts`, metadata in +`check-metadata.ts`, labeled MUST-FIRE / MUST-NOT-FIRE cases per the Check +Evidence Contract (`src/harness/check-evidence/`; no grandfathering for new +checks). Low-FP and catches real bugs: default gate. Heuristic: add to +`DEFAULT_ADVISORY_SKIPS` in `src/commands/verify/advisory.ts` with a rationale +and update its regression test. Noisy in production: refine the detector before +demoting it; measure precision with an independent census, never the builder's +sample. Fix a review bug once, then ship the check that catches the class. +Procedure: `.claude/rules/checks.md`. + +## Where the detail lives + +| Topic | Read | +|---|---| +| guard blocks, verify, ratchets, setup, supply chain, data | `skills/interlinked-*/SKILL.md` (router: `skills/interlinked/SKILL.md`) | +| harness internals, file reference, guard flow | `docs/harness.md` | +| project e2e; mutation-grounded test proof | `docs/project-e2e.md`; `docs/mutation-grounded-test-proof.md` | +| review logs, campaigns, measured results | `docs/reviews/`, `docs/campaigns/`, `docs/design/` | +| instruction packets (`interlinked packets compile\|status\|calibrate\|budget\|release\|restore`; default OFF; release only at warn/cosign) | `docs/design/instruction-jev-evaluator.md`; `.claude/rules/packets.md` | +| subtree invariants (load on demand) | `.claude/rules/{checks,quality-checks,evaluator,project-e2e,kill-proof,shadow-protocol,viz,packets}.md` | diff --git a/CLAUDE.md b/CLAUDE.md index 345738bf8..69a2d4fc9 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,1803 +1,14 @@ # CLAUDE.md -This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. - -## What this is for (read before changing any check, gate, or threshold) - -**Interlinked is a portable, per-tool-call quality and security standard for -agent-written code.** A local daemon sits in front of an agent's tool calls and -judges each one — ideally before it reaches disk. Four goals, in priority order: - -1. **Judge agent-written code at the moment it is written, in ANY codebase.** - This repo is one instance, and an unrepresentative one: single language, - agent-hardened, no human legacy. Portability is the product; this tree is the - test fixture. -2. **Ratchet the quality and security of whatever codebase it runs in.** Default - scope is the DIFF — the edited region of this tool call, not the file. Opt-in - wider scopes: whole-file ("fix the file you touched") and whole-codebase - ("bring this repo up to standard": tests, types, coverage, low complexity). -3. **Catch problems at the earliest point the evidence exists.** PreToolUse when - the proposed content is enough; PostToolUse when the file on disk or a - compiler is required; trajectory when the pattern spans several calls; Stop - when the only observable is "they finished without doing X". A check should - declare the earliest phase its evidence supports, and sit there. -4. **Double as a step-level training signal for other coding agents**, especially - small/local ones. An agent that clears the strictest per-tool-call gates is - demonstrably good — closer to rewarding every step than rewarding the final - diff. - -### The consequence that reverses the obvious reading - -**A check that never fires in this repo is not dead weight, and must not be -retired or demoted for being quiet.** It is the part of the standard this -particular (strong) agent already clears. Point it at a 7B local model or at -human-written legacy code and it earns its keep. - -> **Fire rate measures the AGENT, not the check.** - -Two corollaries that bind day-to-day work: - -- **Never calibrate a threshold against this repo alone.** It is hardened and - atypical. `halstead_difficulty` was tuned to 25 against unit-test fixtures; - the real tree said 25 was the *75th percentile* and it fired 2,226 times. - Fixtures and a hardened tree fail in opposite directions, and both mislead. -- **Blocking and scoring have different precision bars.** A wrong block stops - real work, so blocking needs high precision. Scoring does not block and can - record low-confidence findings weighted by confidence. The existing - `[proven]` / `[heuristic]` determinism tag is that axis — use it rather than - forcing every check to be blockable. - -Treat **more checks as a cost, not a win**: a gate nobody reads is a gate that -is not running. And expect Goodharting — once gates are a training signal, -gaming them is the optimal policy, which is why `baseline_integrity_gate` -exists (the agent being gated can write the water-lines it is judged against). - -**Status: this vision is validated at N=1.** Registry-wide rework — explicit -scope/phase fields, the UBS class port, tier recalibration — waits until the -harness has run against a genuinely different codebase (other language, human -legacy, not agent-hardened) and shown where the abstraction is wrong. - -## Project Overview - -`interlinked-cli` is the whole system today: a Node daemon (`src/harness/`, ~795 -source files) plus a CLI (`src/commands/`, ~111). Agent hooks connect to a Unix -socket per PreToolUse/PostToolUse/Stop event; the daemon returns a block/allow -decision and warnings, and every event is appended to local JSONL under -`.interlinked/`. It is offline-first and has one required runtime dependency -(`commander`). - -**On the "Interlinked MCP Server":** a remote Worker/DO system was the original -center of this project, and ~17 commands still import `src/lib/api-client.ts`. -That surface is **dormant** — no non-test source path calls the MCP tool proxy, -server sync is deliberately unimplemented, and the `active_server` entry in a -working config today points at a LAN mutation-runner broker, not an MCP server. -Do not treat the server as the system of record, and do not describe the CLI as -its companion; the local harness is the product. Leave the dormant code alone -unless the task is specifically about it. - -Source of truth for the CLI is `QuentinCody/interlinked-cli`; current installs run from a linked source checkout. It has a single **required** runtime dependency (`commander`) and zero external dependencies for formatting/output. Two **optionalDependencies** (installed by default; the CLI's core hooks/activity work without them): `typescript` — the JS compiler API the AST-accurate cyclomatic/CRAP gate parses with (the `tsgo` native-port binary has **no importable JS API**, so it can't substitute; TS 7's replacement is an out-of-process gRPC API, stable ~7.1) — and `@typescript/native-preview` (`tsgo`), which accelerates `npm run typecheck`. When `typescript` is absent (`--omit=optional`), the complexity gate degrades to the regex walker and says so loudly (`astComplexityAvailable()`; daemon-startup warning); the `self_import` pre_block check has NO regex fallback and is NOT MEASURED in that state — it reports no findings, and every JS/TS edit carries a `[interlinked:self_import] NOT MEASURED` warning (`checks/self-import-scan.ts`; a pre_block check never blocks on a guess). - -## Working effectively in this repo (best-model profile) - -These four habits are **measured, not asserted** — derived from the best released -models' actual behavior on this repo (17 Fable-5 sessions + Opus-4-8; the per-edit -cyclomatic hit-rate is identical across them at ~0.015/edit, so the profile is -model-agnostic). Full analysis and numbers: `docs/design/fable-corpus-extraction.md`. -The harness gates already nudge toward these; adopting them pre-emptively skips the -block→retry round-trip. - -- **Use coherent patches and cohesive helpers.** Group a logical same-file change - into one patch when possible. Extract helpers when they clarify responsibility - or keep a function within its effective cap. Sequence dependent changes deliberately; - sending multiple tools in one message does not create a transaction. Avoid forwarding - helpers or splitting edits solely to manipulate a per-call metric increment. -- **Prefer `Edit` over `Write`** when changing existing code — surgical edits, not - file rewrites (best-model Edit:Write ≈ 6:1). Full rewrites lose context and trip - the read/edit-balance and blast-radius detectors. -- **Verify after substantive edits.** Run the project's test / typecheck / build at - ~0.5–1.0 verifier runs per code edit (the best-model floor; the anti-pattern is - ~0). The Stop-event nudge fires when a session's verify-to-edit ratio runs far - below this floor. -- **Concise out, deep in.** Terse user-facing messages; deep private reasoning. The - best model thought ~6× more than it spoke and still shipped ~580-char messages. - -## Commands - -```bash -npm run dev # Run CLI directly via tsx (no build step) -npm run build # Build to dist/ via tsup (ESM) -npm run typecheck # TypeScript type checking (tsgo --noEmit; native Go port) -npm run test # Run tests (vitest) -npm run test:watch # Watch mode tests -``` - -Run the CLI in development: -```bash -npx tsx src/index.ts # e.g. npx tsx src/index.ts status -npx tsx src/index.ts enable --dry-run -``` - -Run a single test file: -```bash -npx vitest run src/commands/__tests__/cli-bugs.test.ts -``` - -## `interlinked verify` — two-tier mode - -`interlinked verify` runs in two modes: - -| Mode | Flag | Purpose | -|------|------|---------| -| **Default (high-signal gate)** | *(none)* | Tsc/biome/oxlint/gitleaks/semgrep/dep-audit + check-FP-safe generic checks. Intended to run clean; failures are actionable. | -| **Deep audit** | `--all-checks` | Adds heuristic smell/taste checks (complexity, magic numbers, data clumps, test-coverage signals, etc.) and the `tseslint-types` row — typescript-eslint's type-CHECKED rules via `eslint.interlinked-types.config.mjs` (`no-unnecessary-condition` = dead branches / impossible states, inert `as` casts, redundant union members). Checker-proven, but 620 open findings on landing (2026-09-01), so advisory until the backlog clears. Intended for periodic review, not as a gate. | - -ESLint ≥ 10 removed the built-in `unix` formatter; every eslint invocation here uses -`--format json` parsed by `check-engine/output-parsers-eslint-json.ts` (the old -`--format unix` rows exited 2 and reported nothing — found 2026-09-01). - -The demoted list lives in `DEFAULT_ADVISORY_SKIPS` in `src/commands/verify/advisory.ts` (re-exported from `verify.ts` for back-compat) and is pinned by a regression test so policy changes show up in diffs. Edit both together. Each entry has a rationale comment explaining why it's advisory. - -**When adding a new check**: if false-positive rate is low and the check catches real bugs, leave it in the default set. If it's heuristic (style, complexity, coverage, smell), add it to `DEFAULT_ADVISORY_SKIPS` with a one-line rationale and update the regression test. - -**When an existing check produces noise in production**: prefer refining the check's detection logic over demoting it. Demotion should be a last resort when the check can't cleanly separate true positives from legitimate patterns. - -## Per-file line cap (`large-file-policy.ts`) - -Hand-written code modules are capped at **500 lines** -(`DEFAULT_MAX_LINES`; ratcheted 1500 → 1000 → 800 → 500 across 2026-06, -decomposing each over-cap module into a re-exporting public entry + sibling -helpers as the cap dropped). `src/harness/large-file-policy.ts` is the single -source of truth — the threshold, the `isCappableFile` predicate (`.interlinked/` -tool-state / root `scratch/` probe dir / generated / `@codegen-data` / test / -`.d.ts` / non-code files are exempt; `isCappableFile` is also the ONE -product-code domain definition the coverage-targeting and debt-focus gates -consult, added 2026-07-17 after two gates disagreed about `scratch/`), the -baseline loader, the one canonical line counter (`countLines`; the -comment-aware `countCodeLines` lives in `code-line-count.ts`, re-exported), and -the ratchet verdict. The number above is gen-markered: `extract-doc-facts.mjs` -reads `DEFAULT_MAX_LINES` and `npm run docs:check` (CI) fails if this prose -drifts from it — run `npm run docs:build` after ratcheting to refresh it. - -**The cap is ONE number.** `DEFAULT_MAX_LINES` (code) and `max_lines` in -`.interlinked/large-files-baseline.json` (config) are kept identical by a -regression test in `large-file-policy.test.ts` (`DEFAULT_MAX_LINES === committed -baseline.max_lines`). `maxLinesFor()` returns the baseline value when present -and falls back to the constant when absent — keeping them equal means the -fallback is never a *different* cap (the old footgun: a missing baseline -silently raised the cap). All enforcement surfaces and tests derive from this -constant; tests build fixtures as `DEFAULT_MAX_LINES ± n` rather than hardcoding, -so ratcheting is a one-place change. - -Three enforcement surfaces, one policy: -- **PreToolUse block** — `checkLargeFileLineCountWrite` (`pre-checks.ts`) - blocks a Write/Edit that would grow a cappable file past the cap. It is a - pure before/after delta against live file state — shrinking or holding an - over-cap file is always allowed (the refactor-down path). -- **`interlinked verify`** — the `large_files` check (default gate, no - longer in `DEFAULT_ADVISORY_SKIPS`) reports any cappable file over the cap. -- **PostToolUse nudge** — the `[interlinked:file-size]` warning on write/read. - -The cap and the grandfather list live in `.interlinked/large-files-baseline.json` -(committed — carved out of the `.interlinked/*` gitignore). The grandfather list -(`files`) records a high-water line count per offender: a listed file may shrink -or hold but not grow past its recorded count. Drop each entry once its file falls -below `max_lines` (decompose it, or let it become `@codegen-data`-exempt) — the -goal end-state is an empty list (reached 2026-09-02: 0 files over cap, list -empty; keep it that way). Codegen DATA — the `.mjs` hook script carried as -template strings under `src/lib/hook-template-chunks/`, large embedded data -tables — is exempt via a `@codegen-data` header marker, NOT grandfathered; the -marker is scoped to the line cap only (tsc/lint still run). Ratchet the cap down -(500 → …) by editing BOTH `max_lines` (baseline) and `DEFAULT_MAX_LINES` (code) -together — the pinning test enforces they match, so it surfaces in one diff. The -cap is a coarse proxy; the `complexity` / `cyclomatic` checks do the fine-grained -"is this file bad" work, which is why the enforced line number sits well above -the ~300–500-line aspirational module size. - -## History & relational metrics (added 2026-07-24) - -Beyond the capped metrics, `interlinked metrics ` computes relationship -and change-over-time metrics on demand (never on the hook path — they shell to -git / walk the graph). Spec + phase status: -`docs/design/history-relational-metrics.md`; deferred cloud lanes: -`docs/plans/06-cloud-metrics-program.md`. - -| Subcommand | Metric | Source | -|---|---|---| -| `metrics coupling` | Tornhill co-change pairs; no-import-edge pairs flagged `hidden` | git log + project-graph | -| `metrics arch` | Martin Ca/Ce/instability per dir + propagation cost | project-graph | -| `metrics rework` | share of changed lines whose prior version was < `--window` days old | git blame | - -Cognitive complexity runs on two surfaces with two thresholds (deliberate): -the advisory `cognitive_complexity` registry check at the Sonar-default 15, -and the `cognitive` metric cap (`interlinked caps`, `max_cognitive`, -tighten-only under the baseline-integrity gate) whose PreToolUse companion -(`evaluator/cognitive-write-guard.ts`) **BLOCKS** an edit that leaves a -function over the cap — promoted from warn-only 2026-08-01 once measurement -answered the FP-calibration hedge (p99 = 26 against a cap of 30, and the -over-cap set overlaps heavily with what cyclomatic already refuses). Delta -semantics, so holding or shrinking an already-over function never blocks; see -*Monotonic metric ratchet* for the cap policy. `cognitiveWriteWarning` remains -in the same module as the legacy warn-only signal. Captured per-edit telemetry -also carries `cogΣ` and `astΔ` -(AST semantic-delta: a rename is astΔ 0; a rewritten conditional is not). - -## Scratchpad governance (added 2026-07-09) - -The host session scratchpad (`/claude-///scratchpad`) -is allowed by repo-confinement (the June triad carve-out) but governed by intent: - -| Intent | Policy | Where | -|---|---|---| -| Agent-authored CODE (probes, drafts) | **Block-with-redirect to `/scratch/`** (default; `scratchpad_guard.code_write_mode: "warn"\|"off"` softens; `INTERLINKED_DISABLE_SCRATCH_GUARD=1` one-command bypass). Covers Write/Edit AND bash redirect/tee — bash targets are resolved through same-command `VAR=` assignments and `cd` hops (`resolveBashWriteTarget`). | `evaluator/scratchpad-write-guard.ts`, steer in `evaluator/pre-tool-rules.ts` | -| Secrets to ANY ephemeral temp path | **Block unconditionally** (`builtin-tmp-secrets`; temp paths sit outside protected-file globs but are the classic exfil-staging surface). Escape hatch does NOT apply. | same guard | -| Hand-rolled PATCH APPLIER (script that writes into repo source) | **Block** (`builtin-patch-applier`) in the scratchpad AND in `/scratch/`. Two required signals: a filesystem-write call plus a target outside its own sandbox (`src/**`-shaped literal, `process.cwd()`, `..`). Bypass: `INTERLINKED_DISABLE_PATCH_APPLIER_GUARD=1`. | `evaluator/patch-applier-guard.ts` | -| Downloads / extractions / non-code bulk | Allowed — belongs out-of-repo (in-tree it would poison rg + the trigram index) | — | -| Captured EXTERNAL-AGENT output (review/audit/report `.md`) | Allowed, but warned toward `/.interlinked/agent-output/` — hours-long Codex/Sol runs are the artifacts least able to afford archival roulette | `evaluator/scratchpad-write-guard.ts` | -| Every ephemeral write, ANY extension | **Recorded** to `.interlinked/ephemeral-writes.jsonl` (`ts/session/tool/path/ext/bytes/kind/blocked`); manifest-ish and unclassified kinds also warn. Closes the pre-2026-08 blind spot where the guard only inspected CODE extensions, so `.json` gate-workaround manifests left no trace at all. | `ephemeral-write-log.ts` | -| Everything left at session end | **Archived** into `.interlinked/scratchpad-archive/` (content-addressed blobs + per-session manifest; caps + excludes recorded, no silent truncation; `scratchpad_archive` config, default ON) | `scratchpad-archive.ts`, wired in `server/lifecycle-events.ts` SessionEnd | - -`interlinked scratch init|status` provisions `scratch/` in any repo (README + -`.gitignore` carve-out + `.ignore` search negation — `src/commands/scratch.ts`). -Both config sections are locally overridable (classified in `rules/merge.ts` + -pinned by `merge-parity.test.ts`). - -**The archive skips FOREIGN PROJECT ROOTS** (2026-08-04). A scratchpad -subdirectory carrying `.git` / `package.json` / `Cargo.toml` / `go.mod` / -`pyproject.toml` is a clone or extraction, not the session's work, and its whole -subtree is skipped with reason `vendored-tree`; `scratchpad_archive.archive_excludes` -takes extra globs for bulk that carries no marker. This is not hygiene — it is -the difference between an archive and nothing: before the rule, a single cloned -repo spent the entire 2000-file cap, so both surviving manifests read -`truncated: true` and every agent-authored artifact was evicted, including the -`plm/apply.mjs` patch applier that motivated the row above. The scratchpad ROOT -is never treated as foreign, so a lone `package.json` repro still archives. - -**A dry run must not move the gate.** `interlinked harness test --write/--edit` -sets `dry_run: true` on its synthetic event and every evaluator that PERSISTS -must honor it (`transient-debt-guard.ts`, `ephemeral-write-log.ts`). Found the -hard way 2026-08-04: three simulated writes opened a real TS2305 transient debt -against a file they never touched, which then blocked an unrelated edit. When -adding an evaluator that writes to a ledger, thread `event.dry_run` or the -read-only probe becomes a state mutation. - -## Harness (Guard + Lifecycle + Auto-Reservation) - -The CLI includes a **local harness server** (`src/harness/`) that runs on Node.js and evaluates agent actions via a Unix socket. Full documentation: `docs/harness.md`. Auto-generated reference docs: `docs/generated/`. - -**Key commands:** -```bash -node dist/harness/server.js --verbose # Start harness (pre-compiled) -npx tsx src/harness/server.ts --verbose # Start harness (dev mode) -interlinked harness start # Start as daemon -interlinked harness stop # Stop daemon -interlinked harness status # Show status + loaded rules -interlinked harness checks # Authoritative check inventory (per-family counts + total) -interlinked harness test "rm -rf /" # Test command against rules -npm run docs # Regenerate reference docs -``` - -### A blocked edit is a stale-daemon suspect first - -**The running daemon serves the build it started with.** `interlinked harness -start` loads `dist/harness/server.js`; editing `src/harness/**` changes nothing -about the process currently answering the socket. So when a gate blocks an edit -that *should* pass — or a fix you just wrote fails to take effect — the first -hypothesis is not "the guard is misconfigured", it is **"the daemon is older -than the fix"**. Two sessions were spent diagnosing correctly-configured gates -that were simply not the code running. - -Check freshness before theorising: - -```bash -find src -name '*.ts' -newer dist/harness/server.js -print -quit # any output => build is stale -interlinked harness status # pid + loaded rules -npm run build && interlinked harness restart # the actual fix -``` - -(Scope the freshness probe to all of `src` — the daemon bundles `src/lib` and -`src/commands` too, so a `src/harness`-only probe misses ~100 importer files.) - -`~/.claude/hooks/interlinked-gate-status.sh` runs this at SessionStart and -prints a warning, so the staleness should be in context before the first edit. -Orphan daemons from other sessions can't steal the socket (the PID-aware -anti-stomp guard owns that), but multi-session restart churn can briefly leave -NO daemon answering — tool calls then fail closed until the auto-restart wins; -`interlinked harness start` reaps orphans and reports what it reaped. A rebuild -here also does NOT reach other repos' daemons: each guarded repo (e.g. -mcp-client-bio) runs its own copy of this build — restart those daemons too -after a harness change that matters to them. - -The gate semantics themselves are documented where they are enforced — the line -cap in *Per-file line cap* above, installs in *Supply-chain allowlist*, the -water-lines in *Baseline-integrity gate*. Do not restate their thresholds here; -duplicated policy numbers drift, which is a class this repo's own -`duplicated_policy_constant` check exists to catch. - -**Harness source files (core):** -| File | Purpose | -|------|---------| -| `src/harness/types.ts` | All type definitions | -| `src/harness/server.ts` | Node.js Unix socket server (main entry, `node:net`) | -| `src/harness/evaluator.ts` | Guard evaluation: PreToolUse blocking + PostToolUse feedback | -| `src/harness/rules-loader.ts` | 124 built-in rules + JSON config + hot-reload | -| `src/harness/session-state.ts` | Per-session trajectory tracking | -| `src/harness/cohort.ts` | Agent cohort manager | -| `src/harness/reservations.ts` | Auto file reservation with optimistic locking | -| `src/harness/quality-checks.ts` | PostToolUse: 34 checks across 8+ languages (tsc, biome, cargo, rustfmt, mypy, ruff, etc.) | -| `src/harness/quality-checks/tsc-scheduler.ts` | E21 tsc scheduler, `quality_checks.typescript.scheduler` (DEFAULT OFF, local only, calibrated on this repo alone): defers a predicted-clean synchronous tsc run; drained at the next kept run, Stop, SubagentStop, SessionEnd and commit (`server/tsc-scheduler-phase.ts`); errors and unavailable checks survive restart; rows carry `scheduler` (`query checks --where scheduler.deferred=true`) | -| `src/harness/server-bridge.ts` | Server coordination: reservation sync, guard event reporting | -| `src/harness/trigram-index.ts` | Trigram search index: build, query, serialize, dirty layer | -| `src/harness/regex-trigrams.ts` | Regex → trigram decomposition, rg command parsing | -| `src/harness/grep-accelerator.ts` | PreToolUse grep acceleration: index query + block-and-answer | -| `src/harness/large-file-policy.ts` | Per-file line cap: threshold, `isCappableFile` predicate, baseline loader, ratchet verdict | -| `src/harness/mutation/` | Per-edit mutation gate (spec `docs/design/per-edit-cloud-mutation-testing.md`): stable mutant identity, `mutation-manifest.json` + receipts, survivor-diff invariant, ChangeSet overlays, cloud runner client. Config `per_edit_mutation` (default off; `budget_ms` caps the runner round-trip). Engine scaffolding: root `stryker.conf.json` (MUST ignore `.interlinked/` — Stryker's tree-copy crashes on the harness socket) + `vitest.stryker.config.ts`. Live engine test: `npm run test:integration -- gate-live`. The older per-file score ratchet (`mutation-gate.ts`, `interlinked mutation check`) is a separate, coarser system. | -| `src/harness/shadow/protocol/` | Public client contract and local reference implementation for remote shadow execution: strict parsers, byte grammars, overlays, changeset identity, provenance, and binding comparison. Cross-repository fixtures and schema metadata live in `protocol/shadow-v1/`; see its README for the public/private boundary and vendor workflow. After changing contract source or corpus data, regenerate the digest with `npx tsx scripts/gen-shadow-contract-digest.mts`; use `--check` to verify freshness. Regenerate schemas with `npx tsx scripts/gen-shadow-schema.mts` when contract shapes change. | -| `src/harness/check-inventory.ts` | **Single source of truth for "how many checks."** `getCheckInventory()` derives per-family counts (inline `CHECK_REGISTRY` / sequence / structural / tool-quality / suggestion / behavioral — disjoint) live from each registry; pinned by `check-inventory.test.ts`; surfaced by `interlinked harness checks`. `GENERIC_CHECK_META` is the doc-view of a subset of the inline family, NOT a count — never sum it. Guard rules (`BUILTIN_RULES`) are a separate primitive, pinned by docs-freshness. | -| `src/harness/evaluator/complexity-pulse.ts` | Ambient per-edit cyclomatic telemetry: the strict gate's observer stashes its already-paid before/after parses at PreToolUse; PostToolUse emits one `[interlinked:cyclomatic]` line per edited code file (ΣCC + max + per-fn Δ; absolutes on stash miss). Same population as the gate (cappable files). Isolated hook test: `npm run build:e2e && npm run test:e2e -- pulse`. | -| `src/harness/agent-metrics.ts` | Per-subagent cost + activity, summed off the agent's OWN transcript (2026-08-08): tokens (input/output/cache read/creation), models, per-tool call counts, `tool_use_ids`, turn counts, duration, thinking-block counts. The stop payload carries NO usage (0/1507 measured), so this is the only capture point. `tool_use_ids` is the attribution key — a subagent's tool calls reach the guard under the PARENT session id with no agent marker, so joining activity.jsonl rows back to their agent requires this list. | -| `src/harness/server/agent-event-context.ts` | Label + metrics resolution for one agent event. `SubagentStart` carries `agent_type`, `SubagentStop` usually does not (1439/1507 unlabeled), so the daemon remembers the start label and re-attaches it; `agent_type_source` records payload-vs-remembered. Empty-string labels normalize to null. | -| `src/harness/background-task-log.ts` | Background-agent roster capture (2026-08-08, found by the census): Stop/SubagentStop carry `background_tasks: [{id,type,status,description,agent_type}]`. A background agent fires NO per-agent hook — its result reaches the parent over a queue notification — so this array is the only report that it exists. One row per observed STATE CHANGE to `.interlinked/background-tasks.jsonl`; honors `dry_run`. | -| `src/harness/payload-key-census.ts` | **The "are we capturing everything" backstop.** Every hook invocation diffs the raw runner payload's top-level keys against `CONSUMED_PAYLOAD_KEYS` and records the leftovers — with a TYPE + MEMBER-NAME shape, never values — to `.interlinked/payload-keys.json`. The conversion to the harness event copies a fixed whitelist, so a field a runner starts sending is otherwise dropped in silence; this is how the subagent token/label gaps stayed invisible. When you add a reader for a field, add it to `CONSUMED_PAYLOAD_KEYS` in the same change. | -| `src/harness/server/agent-event-capture.ts` | Subagent/parallel-agent result capture (2026-07): SubagentStart/SubagentStop/TaskCompleted → `agent_event` records in collection.jsonl. The final message comes from the hook payload or a bounded tail-read of the agent's transcript (scrubbed, 64KB cap) — SubagentStop is the ONLY hook carrying a background agent's result (the queue-notification delivery fires no hook). Also one-shot drains the agent's own transcript into timeline.jsonl (`agent_id`-attributed) with a 750ms re-drain covering the runner's post-Stop flush race. Surfaced by `interlinked logs --type subagent_stop`. | - -**Harness source files (analysis):** -| File | Purpose | -|------|---------| -| `src/harness/structural-checks.ts` | 25 dependency-aware checks (export surface, import resolution, cycles, blast radius) | -| `src/harness/checks/.ts` | 50+ inline code analysis checks split by family (SQL injection, complexity, async/await, PII, secrets, etc.). New detectors go here. | -| `src/harness/generic-checks.ts` | Compatibility barrel re-exporting from `checks/.ts`. Do not add new detectors here; import from `checks/.js` directly. | -| ~~`src/harness/check-registry.ts`~~ | **Removed 2026-08-17** — the flat-file compatibility shim had zero importers. Import from `check-registry/index.js`. | - -**Stop-event reflection helpers** (formatters returning `string | null`, called from the `server.ts` Stop / SessionEnd branch; never block — all stderr warnings only): -| File | Purpose | -|------|---------| -| `src/harness/commit-cadence.ts` | Stop nudge when too many uncommitted code-file edits this session + mid-session backstop. Escalates wording by session token band. Says "Don't push." | -| `src/harness/verification-stop-checks.ts` | Three nudges: unverified code (no tsc/test/lint/build), UI not interacted (no dev-server / browser MCP), stubs introduced (TODO/FIXME/disabled-test/throw-not-impl). Signal capture lives in `session-state.ts` (trajectory signals) and `evaluator/post-tool.ts` (content scan). See `docs/design/stop-event-checks.md` for the Tier 2 / 3 backlog. | - -### Agent-quality checks (added 2026-04) - -Ten new cold-agent-clarity checks landed as part of the agent-quality rollout -(see `docs/design/harness-agent-quality-checks-plan.md`). Each is registered -through `check-registry/entries-warnings.ts` (or `entries-errors.ts` for -`promise_reject_non_error`) and surfaces in `interlinked verify`. - -| Check | Phase | Severity | Gate | -|-------|-------|----------|------| -| `floating_promises` | pre_warn | warning | default | -| `non_null_assertion_ratchet` (metric) | post | warning | default | -| `broad_object_types` | pre_warn | warning | default | -| `boolean_trap` | post | warning | advisory | -| `magic_literal_in_conditional` | post | warning | advisory | -| `promise_reject_non_error` | pre_block | error | default | -| `unvalidated_json_boundary` | post | warning | advisory | -| `dead_exports` (generic variant) | post | warning | advisory | -| `circular_imports` | post | warning | advisory | -| `lifecycle_cleanup` | post | warning | advisory | -| `default_export` | post | warning | advisory | -| `positional_optional_boolean` | post | warning | advisory | -| `many_optional_params` | post | warning | advisory | - -Advisory checks only run under `verify --all-checks`; default-gate ones run -on every edit. Non-null-assertion enforcement is a ratchet metric alongside -`as any` and suppression directives: the pre-edit count is baselined and any -post-edit increase is flagged. - -E18 false-positive filter for `[heuristic]` PostToolUse findings (default OFF, local tier, calibrated on this repo only): `src/harness/fp-filter.ts` + `fp-filter-weights.json`, wired in `server/fp-filter-phase.ts`; `verify --fp-filter` reports would-suppress counts; audit with `interlinked query checks --where fp_filter_suppressed=true` (docs/harness.md). - -### Bug-class checks generalized from review findings (added 2026-06) - -Four detectors generalized from concrete review bugs so the harness catches the -same CLASS in any guarded repo. Detectors live in their own `checks/` family -files; the first three are registered (PostToolUse + verify), `gitignored_written_config` -is verify-only (its 3-arg signature can't satisfy the registry's -`(content, filePath) => InlineMatch[]` contract — it needs a `git check-ignore` -resolver, so it sits in `VERIFY_ONLY_CHECKS`). - -| Check | File | Phase | Gate | Catches | -|-------|------|-------|------|---------| -| `nan_coercion_guard` | `checks/nan-coercion.ts` | post | **default** | `Date.parse`/`Number`/`parseInt`/`parseFloat` result used in a `< > <= >=` comparison with no `Number.isFinite`/`isNaN` guard — NaN reads as false → fail-open. (Found + fixed 2 real instances in `sponsor/types.ts` on landing.) | -| `write_without_mkdir` | `checks/fs-write-safety.ts` | post | advisory | `writeFileSync`/`appendFileSync`/`writeFile`/`createWriteStream` to a nested path with no prior `mkdirSync(…, {recursive})` / `existsSync` guard → ENOENT. | -| `duplicated_policy_constant` | `checks/policy-constant-drift.ts` | post | advisory | a bare numeric literal duplicating a same-file `DEFAULT_*`/`*_CAP`/`*_THRESHOLD` constant's value (drift — the literal won't follow the constant). | -| `gitignored_written_config` | `checks/gitignored-write.ts` | (verify-only) | advisory | code writes a statically-resolvable config path that `.gitignore` excludes with no `!` carve-out → never committable. | - -**Test-quality (from external-pulse intake):** `introverted_test` (`checks/introverted-test.ts`, post, advisory) flags `it()/test()` blocks whose assertions never trace to a non-mocked system-under-test call/read — the static-dataflow layer beneath `mock_only_test` (matcher kind) and `test_missing_sut_import` (the import). SUT = the companion module only; it does not fire when the SUT is exercised in the body (directly or via a file-local factory helper). Ported from Uncle Bob's deintroverter4clj; intake at `docs/external-pulse/deintroverter.md`. Dogfood: 0/791 test files on landing. - -**Test-discrimination family (2026-09-06/07):** fourteen advisory `post` -checks, also surfaced by `verify --all-checks`; none blocks. Registry: -`check-registry/entries-warnings/test-discrimination.ts`. Every detector entry -module has CLASS / FIRES WHEN / DOES NOT FIRE / CALIBRATION / KNOWN GAPS / -HOW TO EXTEND sections. Reproduce fire rates with -`npx tsx scripts/scan-test-discrimination.ts [corpus-root] [check-id ...]`. -The operator design note is `docs/design/test-discrimination-checks.md`. - -| check | review target | -|---|---| -| `fallback_only_assertion` | default-only outcomes without same-file/same-SUT sibling pins | -| `duplicate_expected_literal_pos_neg` | invariant literals across positive/negative cases | -| `spy_call_unpinned_args` | call counts without argument/value evidence | -| `wildcard_in_observable` | wildcard-only observables; excludes imported-export smoke | -| `in_tree_temp_fixture` | fixture roots without recognized OS-temp provenance | -| `duplicate_throw_message_assertion` | repeated error messages in the resolved callee | -| `catch_without_assertion_guard` | catch-only assertions without recognized guards | -| `fixed_port_in_test` | fixed ports in recognized network contexts | -| `vacuous_loop_assertion` | loop-only assertions; mapped equality pins recognized | -| `mock_return_echo` | literal overlap with mock returns; coarse literals require one discovered mock | -| `duplicate_test_body` | repeated bodies under equivalent setup, including late hooks | -| `spy_without_restore` | missing applicable cleanup, considering runner config and test-local objects | -| `export_existence_smoke_test` | imported export existence/function-type assertions only | -| `commented_out_assertion` | actual disabled assertions, excluding strings/prose/skip fixtures | - -Review corrections: negation and throwing evidence are not mock echoes; quoted keys -are not mock return values. Setup normalization preserves literal whitespace. -The original vacuous-loop 8/8 precision claim included two known false positives -and supports at most 6/8. Fire rates and builder samples are not independent precision. - -Two lessons that bind future checks: the builder's own 8-sample precision read was -wrong by 70 points on two detectors (posneg read 87% TP, independent adjudication -said 86% FP) — measure precision with an independent census or adjudication, never -the builder's sample; and four scoped detector fixes removed 514 hits where a -165-unit agent wave had removed 153 — fix the detector before fixing the tests. -`test_name_matcher_mismatch` is built and deliberately UNREGISTERED (0/8 precision -three times: title claims are verified through literals the title cannot see). - -Shared patterns when adding another agent-quality check (verified -against current code, May 2026): -1. Detector in `src/harness/checks/.ts` (a new family file or - an existing one — e.g. `iteration-safety.ts`, `b-series.ts`, `pii.ts`). - The barrel `src/harness/generic-checks.ts` re-exports automatically; - do not add new detectors directly to the barrel. -2. Canonical registry entry in `src/harness/check-registry/entries-warnings.ts` - (or `entries-errors.ts` for `pre_block` errors). Phase contract is in - `src/harness/check-registry/types.ts` — `pre_block` is reserved for - fully-deterministic, zero-FP errors only. -3. Metadata entry in `src/harness/check-metadata.ts`. -4. ~~Legacy-mirror entry~~ — the flat `src/harness/check-registry.ts` shim is - deleted (2026-08-17). No manual sync step. Skip. -5. Verify wiring is split across `src/commands/verify/`: - - `advisory.ts` — `DEFAULT_ADVISORY_SKIPS`, skip-set helpers - - `file-checks.ts` — per-file check orchestration - - `tool-results.ts` / `tool-results-types.ts` — tool result aggregation - - `section-table.ts` / `output-json.ts` — formatters - - `streaming-output.ts` — `streamCqSection` and friends - The orchestrator `src/commands/verify.ts` still holds `VerifyOpts` / - `ToolSpec` and re-exports `DEFAULT_ADVISORY_SKIPS`. Touch only the - subfile your check actually surfaces in. -6. Update `AGGREGATED_IN_JSON` in `__tests__/check-pipeline-parity.test.ts` - and `DEFAULT_ADVISORY_SKIPS` in `src/commands/verify/advisory.ts` + - its regression test when demoting to advisory. -7. Each new check ships with labeled MUST-FIRE and MUST-NOT-FIRE cases - meeting its **phase-scaled** obligation under the Check Evidence - Contract (below) — not a flat count. - -### Check Evidence Contract (added 2026-07-26) - -The checks are what everything else trusts, and they used to be the least -verified code in the tree: the old "≥3 positive / ≥3 negative" rule was prose -with no pin, and **13 of 100** check test files followed it. `src/harness/check-evidence/` -replaces it with a measured, phase-scaled contract. Spec: -`docs/design/verification-density-program.md`. - -A flat count was always a proxy for the real question — *does every -distinguishable behavior of the detector have a case in both directions?* One -case is **complete** if it covers the only branch; three is negligent if there -are twelve. So the obligation scales by phase, and Phase 3 will derive it from -the detector's own branch structure. - -| Tier | Min +/− cases | Branch cov | Corpus | Mutation | Adversarial | -|---|---|---|---|---|---| -| `pre_block` | 3 / 3 | 100% | required | required | required | -| `pre_warn` | 2 / 2 | 100% | required | required | — | -| `post` (default gate) | 2 / 2 | 90% | required | — | — | -| `post` (advisory) | 1 / 1 | 80% | — | — | — | - -Only the case counts and test-file presence are **enforced** today; the later -columns are recorded on the tier and enforced in Phases 2–4 (reporting them as -shortfalls now would fail every check on landing and teach the agent to ignore -the pin). - -| File | Purpose | -|---|---| -| `check-evidence/types.ts` | Evidence record, tier, verdict, baseline shapes | -| `check-evidence/obligations.ts` | The four tiers + `tierFor` / `evaluateEvidence` | -| `check-evidence/case-parser.ts` | Extracts labeled cases from test source (two conventions) | -| `check-evidence/resolve.ts` | Detector-name → source file + exercising test files | -| `check-evidence/extract.ts` | Registry-wide sweep producing records + verdicts | -| `check-evidence/baseline.ts` | Loads the shrink-only grandfather list | -| `check-evidence/contract.test.ts` | **The pin.** Fails on any ungrandfathered violation | - -Labeling conventions the parser recognizes — either is enough: -- a `describe()` whose title names a direction (`"— positive (must fire)"` / - `"— negative (must not fire)"`); every `it()` inside inherits it -- a per-test prefix (`it("P1: …")` / `it("N3: …")`), which overrides the - enclosing describe - -Four evidence dimensions exist (`cases`, `corpus`, `derived_cases`, `mutation`, -`adversarial`); enforcement is **staged** via the baseline's `enforced` field, -which is GROW-ONLY under `baseline_integrity_gate`. At landing only `cases` -fails the pin — the rest are measured and reported so turning one on later is a -ratchet step with a known backlog, not a guess. Supporting modules: -`corpus.ts` / `corpus-scan.ts` (dogfood runs + adjudication, -`.interlinked/check-corpus.json`), `recall.ts` (case floors derived from the -detector's own branch structure; detector mutation scores), `adversarial.ts` -(independent FP hunt, bound to a source hash so rewriting the detector re-opens -the review). - -**A check earns per-edit latency by catching defects, not by expressing taste.** -Both checks added by this program (`halstead_difficulty` — Halstead density, -the dimension the control-flow metrics cannot see; `property_test_candidate` — -pure algorithmic functions with no property test) are **verify-only**, decided -on measurement: the property check reads companion test files so it is not the -pure `(content, filePath)` function the registry contract requires, and the -Halstead check's full TS parse pushed `determinism-conformance` past its 30s -budget on the inline path. Both are advisory and fire ~17 / ~62 times -repo-wide — deep-audit cadence. They live in `VERIFY_ONLY_CHECKS` alongside -`gitignored_written_config` and `readme_script_drift`. - -**The corpus obligation is not ceremony.** `halstead_difficulty` was calibrated -on unit-test fixtures at a difficulty ceiling of 25; the corpus run over 9023 -real functions showed that is the *75th percentile* and produced 2226 findings. -Recalibrated to 80 it produces 17. Calibrate new checks against the tree, never -against fixtures. - -Compliance (2026-08-04): **151/252 checks pass; 101 grandfathered** in -`.interlinked/check-evidence-baseline.json` (committed, carved out of the -`.interlinked/*` ignore). The list is **shrink-only** and enforced by -`baseline_integrity_gate` (`check-evidence` kind) — adding an id there exempts a -check from having to prove it works, so it blocks. New checks get no -grandfathering. Worst tier is still the strictest one: `pre_block` hard rails -sit at 54% (20/37), so backfill those first. Re-derive these numbers with -`npx tsx scratch/evidence-tier-census.mts` rather than trusting the prose. - -| `src/harness/project-graph.ts` | Multi-project file dependency graph with caching | -| `src/harness/impact-analysis.ts` | Cross-file dependency tracking and breaking change detection | -| `src/harness/change-propagation.ts` | Side-effect tracking across edits | -| `src/harness/error-history.ts` | Error pattern memory with optional embeddings support | -| `src/harness/language-profiles.ts` | Language-specific checks for 12+ languages | -| `src/harness/taint-tracker.ts` | Sensitivity and flow tracking. Step budgets bind the calling actor's own count (`actorStepCount`, `actor_tool_calls`, keyed by `actorKeyOf`), not the sum of sibling calls. Known subagents use the configured limit at their own sensitivity; unknown actors retain the session limit. Per-actor lineage (`taint-lineage.ts`, H3 B3+B5) raises the reader and its ancestors, including for the optional model-backed content scanner. New children inherit their parent's current sensitivity; already-running clean siblings retain theirs. The session level remains the root/max for display. Every network decision uses the acting actor's level. Files written above Public carry their level (`taint-file-lineage.ts`, bounded 2048, snapshot `taint_files`) and ratchet later readers before network checks, including read-and-send commands. Legacy snapshots without `taint_actors` hydrate at the stored session level. `harness taint status` lists actor levels; operator-only `harness taint clear` lowers every actor, or `--actor ` one on a live daemon. Exhausted budgets advise handoff, not a commit the guard would block. | -| `src/harness/pattern-detector.ts` | Cross-cutting pattern detection | -| `src/harness/suggestion-scorer.ts` | Weighted finding scoring and ranking | -| `src/harness/registry-parity.ts` | Configurable drift detector for paired registries / exception lists. Reads `.interlinked/registry-parity.json`; runs as part of `interlinked verify` and surfaces drift in both streaming and `--json` output. | -| `src/harness/suppressions.ts` | Inline suppression directives | -| `src/harness/check-metadata.ts` | Structural check metadata for docs generation | -| `src/harness/check-engine/` | Unified caching/memoization layer for checks | - -**Harness source files (artifact structure):** -| File | Purpose | -|------|---------| -| `src/harness/structure/types.ts` | All structure type definitions (determinism, provenance, artifact kinds, graph shapes, config schemas) | -| `src/harness/structure/schema-validator.ts` | Validates `structure.json` and all 9 artifact file schemas (unknown-key rejection) | -| `src/harness/structure/structure-loader.ts` | Loads `interlinked/structure.json`, resolves mode defaults, loads artifact files | -| `src/harness/structure/artifact-graph.ts` | ArtifactGraph: node/edge CRUD, companion traversal, incremental refresh, serialization | -| `src/harness/structure/cache-manager.ts` | Read/write `.interlinked/structure-cache/` files, staleness detection, manifest hashing | -| `src/harness/structure/structure-checks.ts` | PostToolUse entry point: graph build, incremental refresh, declared artifact layering, rule evaluation | -| `src/harness/structure/structure-formatter.ts` | Human-readable `[interlinked:structure]` warnings, verify JSON output builder | -| `src/harness/structure/adoption.ts` | Coverage calculation per category (0.0–1.0) | -| `src/harness/structure/baseline.ts` | Baseline suppression matching, SHA-256 context hashing | -| `src/harness/structure/extractors/` | 7 generic extractors: module, package, env, config, test, docs, examples | -| `src/harness/structure/rules/` | 7 built-in rule families: public symbol companions, public symbol test-case, env/config key companions, layer/package boundaries, glossary residue | - -**Auto-generated reference docs** (run `npm run docs` to regenerate): -| File | Contents | -|------|----------| -| `docs/generated/guard-rules.md` | All 124 built-in guard rules by category | -| `docs/generated/quality-checks.md` | All 34 PostToolUse quality checks | -| `docs/generated/structural-checks.md` | All 26 structural checks by tier | -| `docs/generated/configuration.md` | Default config: diff-aware filtering + structural check settings | - -**How guard evaluation works:** -1. Hook script connects to `/.interlinked/harness.sock` on PreToolUse -2. Harness evaluates event against rules + reservations + trajectory state -3. For Grep/Bash-grep calls: queries trigram index for candidate files, runs rg on candidates -4. Returns `{decision: "block"|"allow", reason?, warnings?}` -5. If blocked: hook outputs decision to stdout, agent sees reason -6. If warnings: hook writes to stderr, agent sees on next turn -7. If harness unavailable: inline fallback patterns (sleep, rm -rf, force push, DROP) - -**Grep acceleration (OPT-IN, off unless an index exists — 2026-09-10):** -- Build index: `interlinked index build` (0.1-10s depending on repo size). - `interlinked enable` no longer builds it: the in-process build walks every - tracked file and ran a 50k-file prose corpus out of heap mid-enable, leaving - hooks installed but no daemon. Nothing on the hook path needs the index. -- Harness loads an existing index on startup, refreshes incrementally on each SessionStart -- Intercepts Grep tool calls AND Bash rg/grep commands (including from subagents) -- Queries index in ~10-50μs, narrows to candidate files, runs rg on candidates only -- Agent sees results via block-and-answer pattern (formatted like normal grep output) -- Dirty layer tracks file edits in-memory so agent's own writes are immediately searchable - -**Important patterns:** -- Guard rules are in `.interlinked/guard-rules.json` (team-shared) + `.interlinked/guard-rules.local.json` (personal overrides) -- Built-in rules cannot be modified, only disabled via `disabled_rules` in local config -- The evaluator uses OR logic for patterns within a rule (any pattern match fires the rule) -- Negated patterns (`negate: true`) act as exceptions (if matched, rule does NOT fire) -- Quality checks (tsc, lint, etc.) run on PostToolUse only — they need the file on disk and full project context -- Structural checks (export surface, import resolution, etc.) also run on PostToolUse -- Diff-aware filtering suppresses pre-existing findings, only reporting issues introduced by the current edit -- `pre_block` registry checks are likewise **introduced-only** at both write gates (shared semantics in `src/harness/pre-block-gate.ts`): a finding blocks only when the edit adds it vs the on-disk baseline (multiset over normalized line text); pre-existing findings surface as warnings instead of bricking the file for unrelated edits. Inline `// interlinked-ignore: — reason` directives and `.interlinked/verify-suppressions.json` entries are honored at pre-block time (same grammar as PostToolUse/verify; ratcheted, auditable) -- Secrets detection runs on BOTH PreToolUse (in file content) and PostToolUse (re-check) -- The hook finds its project by walking up from the TOOL CALL's cwd (`lib/interlinked-root.ts findRepoRoot`) to the - nearest `.interlinked/` that holds a project marker (`config.json`, `guard-rules.json`, `harness.pid`) or a - socket; a folder holding only hook-written files (payload census, receipts, prediction state) is passed. Before - 2026-10-22 the nearest `.interlinked/` won, and the payload census wrote `/.interlinked/` for any folder - the session had `cd`-ed into — so every later call from below that folder found no socket and was cold-allowed - without the daemon (one session: 135 of 734 calls, 47 of them edits; the transcript says "daemon socket not - found; evaluator skipped"). The census now writes only under the project root, and `guard-prediction.ts` keys - its state, receipts and file keys to the same root (keyed to the cwd, it also skipped every edit outside the - session's current folder as "outside the project"). Scale on 2026-10-22: 663 of the tree's 730 `.interlinked/` - folders were such strays (618 under `scratch/`, 17 under `src/` — `.gitignore` `src/**/.interlinked/` had - hidden them), and their own receipts show 21,283 cold hook calls since 2026-09-24 (5,917 PreToolUse). - `interlinked verify` run from a subfolder still writes `/.interlinked/verify-runs.jsonl` (harmless for - the guard now; the CLI's data paths are cwd-relative by convention). `interlinked harness calls [--since 7d] - [--session id] [--strict]` (`harness/call-coverage.ts`) joins the transcript timeline to the collection log by - `[session, tool_use_id]` and lists observed calls without a matching daemon judgment, - by tool and working folder. Missing or rotated capture remains a measurement gap. - -## Findings carry a determinism tag - -Every warning the harness sends to the agent is prefixed with a `[proven]` -or `[heuristic]` tag derived from the check's `Determinism`: -`fully_deterministic` → `[proven]` (compiler / linter / scanner / parser -ran the actual code); everything else → `[heuristic]` (regex / AST shape, -not behavior-verified). Unknown check ids get no tag rather than a -guessed one. The classifier lives in -`src/harness/quality-checks.ts::classifyDeterminism`; the proven -allow-list for tool-based checks is in -`src/harness/quality-checks/instructions.ts::PROVEN_TOOL_CHECKS`. - -When adding a new tool-based check (one that wraps an external -verifier), add its id to `PROVEN_TOOL_CHECKS`. Inline checks in -`CHECK_REGISTRY` use their existing `determinism` field — no parallel -maintenance. - -Suppression comments (`// @ts-ignore`, `// eslint-disable-next-line`, -`// biome-ignore`, and since 2026-09-04 the coverage-ignore pragmas -`v8 ignore` / `c8 ignore` / `istanbul ignore` / `node:coverage ignore`, which -shrink the coverage denominator and were previously invisible to every -surface) are split into two warnings: `suppressions-unjustified` -(loud, line-numbered) and `suppressions` (soft, fired only when every -disable on the file carries a reason). Justification conventions: any -text after `@ts-ignore`/`@ts-expect-error`; ` -- ` for ESLint; `:` for -Biome; ` -- ` for coverage pragmas (`/* v8 ignore next -- child -process only */` — measured against ast-v8-to-istanbul 1.0.3: trailing text -is tolerated, the `next N` count is NOT honored, so one node is suppressed -regardless of N). `@ts-nocheck` is exempt (file-level, no per-line -convention). The same token list drives the delta `suppression_ratchet` -(`quality-checks/ratchet-metrics.ts`); both surfaces mirror the provider's -ignore-hint grammar verbatim. - -## Querying the local data (`.interlinked/`) — check it BEFORE raw transcripts - -`.interlinked/INDEX.md` (generated, point-in-time) maps every entry in the data -directory — schemas, sizes, live/dead status, and bounded shell recipes. The -local logs are richer than `~/.claude/projects/*.jsonl` transcripts: they carry -cross-runner tool events (`collection.jsonl`), guard verdicts with rule ids -(`activity.jsonl`), per-check outcomes (`check-results.jsonl`), and token costs -(`costs.jsonl` — dormant since 2026-06-01). Query them first; fall back to raw -transcripts only for something genuinely absent locally. - -`interlinked query` is the read verb (added 2026-07-24): `interlinked query` -with no args prints the source catalog; `query blocks`, `query checks --by -checks.id --since 7d`, `query costs --by session_id --sum output_tokens`, or -any `.jsonl` path with `--where k=v`. Scans are bounded by default (newest 20k -records / 64 MB tail) and the footer always states how much was scanned. -**Never full-read `collection.jsonl`, `activity.jsonl`, or `timeline.jsonl`** — -they are hundreds of MB; bound every read (`tail -n` / `interlinked query`). - -## Recurrence — repeating-pattern aggregation - -`interlinked recurrence` surfaces patterns that recur across sessions, -files, or agents. Three observation kinds, all stored in one -append-only JSONL log at `.interlinked/recurrences.jsonl`: - -| Kind | Source | Suggested action | -|------|--------|------------------| -| `harness_caught` | Wired into `server.ts` after `errorHistory.recordError(...)` — fires automatically on every PostToolUse check failure | Ratchet (advisory → default → block) | -| `harness_missed` | Manual: `interlinked recurrence flag ` for patterns the harness should have caught | Scaffold a new rule entry | -| `codebase_existing` | `interlinked recurrence scan [--record]` walks the working tree with the same inline detectors used at edit time | Cleanup PR | - -```bash -interlinked recurrence list # Top rows by count -interlinked recurrence list --kind harness_caught # Filter -interlinked recurrence detail # All events for one row -interlinked recurrence flag raw-sql-concat \ - --message "spotted in db.ts" --file src/db.ts # Manual harness_missed -interlinked recurrence scan --record # Append codebase_existing -interlinked recurrence propose # Suggested action -``` - -All deterministic — counting + grouping over the JSONL, no LLM-as-judge -in the aggregator (per `feedback_harness_deterministic_only.md`). -Aggregation is computed on demand from the log; no separate cache. - -Source files: -- `src/harness/recurrence.ts` — types, storage, aggregation, `proposeAction`, `recordHarnessCaught` / `recordHarnessMissed` wrappers -- `src/harness/recurrence-scanner.ts` — `scanCodebaseForRecurrences` (walks the working tree, runs `buildAgentSafetyChecks` per file) -- `src/commands/recurrence.ts` — CLI subcommands (list/detail/flag/scan/propose) - -The existing `non_null_assertion_ratchet` and `as any` ratchets are a -specialized form of `harness_caught` recurrence response. Future -unification: subsume them under the recurrence model (one place to -declare "this is a recurring shape; ratchet over time"). - -## Reservations are a single-source-of-truth state machine - -`src/harness/reservations.ts` declares its state changes as one -`ReservationTxn` discriminated union and applies them through one -`applyTransition(state, txn)` function — Bitar's "edge-defined-once" -pattern adapted for TS. Both live execution and `replayTransitions(events)` -go through the same dispatch, so live state and replay can't drift. - -Optimistic local grant + async server confirm: the server-confirm -rejection path now rolls back the local grant and emits a -`conflict` event with `conflict_reason: "server-rejected"` (was a -silent `.catch(() => {})` before — the silent-double-allocation bug -class). The conflict event carries the rollback reason for log -consumers (`reservation-events.jsonl`, `interlinked recurrence` -aggregation). - -Property tests in `src/harness/__tests__/reservations.test.ts` use -`fast-check` to assert: replay==live, no double-grant, release -ownership-respecting + idempotent, evict_remote local-safe, -release_all targets exactly the named agent. - -## Architecture - -### Relationship to the MCP Server - -The server (`Interlinked MCP Server`) is the remote Worker/DO system. Communication is strictly one-directional: CLI → server via HTTP. Key server endpoints consumed: - -| Endpoint | Purpose | -|----------|---------| -| `POST /api/hooks/activity` | Single event (fire-and-forget from hook script) | -| `POST /api/hooks/activity/batch` | Batch sync of buffered events | -| `POST /api/ui/call` | MCP tool proxy (used by `status`, `activity`, `doctor`, `workspace`) | -| `GET /api/workspaces` | List workspaces (registry endpoint) | -| `POST /register`, `POST /token` | OAuth dynamic client registration and token exchange | - -### Entry Point and Command Registration - -`src/index.ts` registers all commands via `commander`. When invoked with no arguments, `handleImplicitEntry()` from `src/commands/first-run.ts` runs an interactive wizard (TTY) or non-interactive bootstrap (non-TTY). If already configured, it falls through to `statusCommand`. - -### Key Source Files - -| File | Purpose | -|------|---------| -| `src/lib/config.ts` | Two-tier config system: `config.json` (shared/committed) + `config.local.json` (personal/gitignored). `resolveConfig()` merges both and resolves multi-server entries. | -| `src/lib/auth.ts` | Token resolution (CLI token → Claude Code credentials fallback) + OAuth PKCE flow | -| `src/lib/hooks.ts` | Orchestrator: hook script generation + per-client install/uninstall delegation through `CLIENT_INSTALL_REGISTRY`. Generates `.interlinked/hooks/interlinked-activity.mjs` (self-contained, zero imports). | -| `src/lib/hook-installers.ts` | Per-client install/uninstall implementations (Claude Code, GitHub Copilot CLI, Gemini CLI, OpenAI Codex CLI). Each `installXxxHooks` writes a settings file and tags commands with `INTERLINKED_CLIENT=""` so the .mjs runtime can disambiguate clients with overlapping payload shapes. Codex additionally writes `.codex/config.toml` to set `[features] hooks = true` (legacy `codex_hooks` is recognized and auto-migrated; the writer lives at `src/lib/codex-feature-flag.ts`). | -| `src/lib/api-client.ts` | HTTP client wrapping `POST /api/ui/call` for MCP tool proxying | -| `src/lib/local-activity.ts` | JSONL append-only log, session state, sync cursor (byte-offset), merge/dedup | -| `src/lib/activity-utils.ts` | Shared `ActivityEvent` type, `parseDuration()`, `formatActivitySummary()` | -| `src/lib/formatter.ts` | ANSI colors, tables, timestamps — hand-coded, no external deps. Respects `NO_COLOR`/`CI`. | -| `src/lib/output.ts` | Output mode abstraction: `json`, `short`, `normal`, `full` | -| `src/lib/settings.ts` | Client detection and settings file paths for claude/copilot/gemini/codex (registry consumed by `interlinked enable`/`disable`) | -| `src/lib/viz/` | The loopback dashboard (`interlinked viz serve`). `feeds.ts` is the seam: each live lens is ONE `VizFeed` descriptor (route + seed + subscribe) and `server.ts` hosts them all through one generic SSE path — add a lens there, not by copying the plumbing. `agent-roster.ts` folds the activity stream into per-actor presence lanes (a subagent gets its OWN lane keyed `/`, never merged into its parent's counters) and assigns each actor a stable hue — the ONE hashing rule for actor colour, reused by every surface that attributes work to an agent. Dashboard vocabulary is deliberately literal: dot = source file, line = import, lane = agent session, frame = one judged tool call. Feeds: activity, `check-results.jsonl`, `test-events.jsonl` (TESTS), `mutation-manifest.json` (MUTANTS). `reporter-vitest.ts` is the shipped producer for the test feed, published as the `interlinked-cli/viz-reporter` export and duck-typed against vitest so it never imports it. `status-file.ts` publishes `.interlinked/viz.status` so the statusline renders a `◈ viz` link only while a server is actually alive. Every feed renders an honest empty state when its file is absent — nothing is repo-specific. | - -### Activity Event Pipeline - -``` -AI Agent hook fires → stdin JSON → hook script (.interlinked/hooks/interlinked-activity.mjs) - ├── Connect to harness socket (if available, 500ms timeout) - │ ├── PreToolUse: harness returns {decision: block/allow} → stdout - │ └── PostToolUse: harness returns {warnings} → stderr - ├── Local write (always, sync, ~0.1ms) → activity.jsonl + sessions/{id}.json - ├── Fire-and-forget POST /api/hooks/activity (if sync_mode != "local", 3s timeout) - └── Batch sync on session end (if sync_mode == "realtime", cursor-based, 100-event chunks) -``` - -Three sync modes: `realtime` (default), `local` (offline-only), `manual` (POST per event, no batch at session end). - -### Two-Tier Config System - -| File | Git | Contains | -|------|-----|----------| -| `.interlinked/config.json` | Committed | `server_url`, `default_project`, `version` | -| `.interlinked/config.local.json` | Gitignored | `access_token`, `agent_name`, `workspace_id`, `sync_mode`, `servers` map | - -Multi-server isolation: `config.local.json` has an `active_server` key and `servers` map. Each server entry holds its own `server_url`, `workspace_id`, and `mcp_prefix`. - -Environment variable overrides: `INTERLINKED_SERVER_URL`, `INTERLINKED_ACCESS_TOKEN`, `INTERLINKED_AGENT_NAME`, `INTERLINKED_WORKSPACE_ID`, `INTERLINKED_SYNC_MODE`. - -### Auth Token Resolution - -`resolveAuthToken()` priority: -1. CLI's own `access_token` from `config.local.json` (checks `token_expires_at`) -2. Claude Code credentials fallback from `~/.claude/.credentials.json` → `mcpOAuth`, matched by `mcp_prefix` key prefix or `serverName` containing "interlinked" - -Dev mode bypass: when `server_url` is localhost/127.0.0.1, auth is skipped entirely. - -## Three-tier policy enforcement (Tier 1 shipped 2026-05, Tier 2/3 designed) - -`/enforce` runs three passes over agent-instruction markdown (AGENTS.md, -SKILL.md, CLAUDE.md, .clinerules/, etc.) and emits artifacts for three -enforcement tiers: - -| Tier | Layer | Consumer | Artifact | Cadence | -|---|---|---|---|---| -| 1 | Local deterministic | Interlinked harness (sub-10ms) | `.interlinked/distilled-rules.json` | Every tool call | -| 2 | Cloud LLM policy gate | gpt-oss-safeguard-120b (~3-6s) | `.interlinked/policies/.policy.md` + `.cedar` + `.interlinked.cedar` | Most tool calls (post-filter) | -| 3 | Cloud architectural review | Sonnet/Opus on staged commits (~30-120s) | `.interlinked/policies/.prose.md` | Pre-push / on-demand `/review` / `/security-review` | -| — | Audit | Humans | `.interlinked/policies/skipped.report.md` | After /enforce runs | - -The Cedar emission is Sondera-compatible by default (drops into Sondera's -`policies/` directory). Policies needing skill-scope or trajectory state -get a sibling `.interlinked.cedar` file using extensions documented at -`docs/design/interlinked-cedar-extensions.cedarschema`. Pass 3 prose -artifacts are consumed by the Tier 3 cloud agent during pre-push review -for after-the-fact evaluation against principles the deterministic layers -can't enforce. See `skills/enforce/SKILL.md` §15 for the full routing -contract and `docs/examples/policies/disk-forensics/` for a worked example. - -Tier 2 and Tier 3 are designed but not built — full design memos at -`docs/design/tier-2-llm-policy-gate.md` (architecture, provider selection, -prompt caching, pre-filter, cost model, rollout cadence) and -`docs/design/tier-3-async-deep-review.md` (trigger model, scope, model -selection, prose-policy evaluation pipeline, warn-only contract). Only -Tier 1 (and the artifact-emission side of /enforce) is shipped. Local-only -mode (no cloud): policy and prose artifacts load as agent context but -aren't enforced; Cedar files work for self-hosted Sondera. - -## Supply-chain allowlist (fail-closed package installs) - -Built 2026-05 in response to the surge of malicious npm / PyPI packages. -**Default stance: any new dep is potentially malicious.** Three gates, -one allowlist, every ecosystem: - -| Vector | Gate | File | -|---|---|---| -| Shell `npm install `, `pip install `, `cargo add`, `go get`, … | PreToolUse Bash gate | `src/harness/evaluator/package-install-guard.ts` | -| Edit/Write to `package.json` / `requirements.txt` / `pyproject.toml` / `Cargo.toml` / `Gemfile` / `go.mod` that adds a new dep | PreToolUse Write gate | `src/harness/evaluator/manifest-edit-guard.ts` | -| Same shell commands when the daemon is unreachable | Cold-fallback gate | `src/hook-entry-cold-gates.ts::coldPackageInstallBlockReason` (allowlist-aware) + `src/lib/hook-template-chunks/package-install-cold-guard.ts::checkPackageInstallCold` (the .mjs copy: refuses every install verb — it cannot reach the parser or the allowlist) | - -Coverage: **npm / pnpm / yarn / bun + pip / pip3 / pipx / poetry / uv + -cargo + gem / bundle + go**. URL-based specs (`git+`, tarball, `file:`) -are blocked unconditionally — they bypass registry signing entirely. -Custom `--registry` / `--index-url` overrides are likewise blocked. - -The allowlist lives at `.interlinked/package-allowlist.json` (committed). -Two grant kinds: -- **Per-package** — exact name match, ecosystem-keyed. -- **Lockfile snapshot** — sha256 of a manifest or lockfile, approving its - entire resolved state. Re-snapshot whenever the file changes. - -Bypass for one command: `INTERLINKED_DISABLE_PACKAGE_GUARD=1` (logged, -intended for documented bootstrap flows only). - -```bash -interlinked allowlist add npm lodash --by qcody --reason utility -interlinked allowlist snapshot --by qcody # hash all manifests + lockfiles in cwd -interlinked allowlist snapshot --lockfile package-lock.json --by qcody -interlinked allowlist list # human-readable -interlinked allowlist list --json -interlinked allowlist verify # diff manifest deps vs allowlist -interlinked allowlist remove npm lodash -``` - -**Approving a bad package is the worst failure mode** (after which install -proceeds silently), so `allowlist add` runs three admission screens and -refuses unless `--force` is passed (added 2026-06, adapted from cargo-deny's -CI role — see `docs/external-pulse/sondera-coding-agent-hooks.md`): -1. **Typosquat** — Levenshtein distance against popular names - (`src/harness/checks/supply-chain.ts::findTyposquatMatch`); npm only (the - popular-package list is npm-specific). -2. **License** — registry-declared SPDX expression vs the committed - `license_allowlist` array in `package-allowlist.json` (default: permissive - seed in `src/harness/license-policy.ts::DEFAULT_LICENSE_ALLOWLIST`). The - license is recorded on the entry; manifest-edit-guard re-checks the - RECORDED field per-edit (warning only, zero network on the hook path) so - `--force`-admitted grants and later policy tightening stay visible. -3. **Advisories** — OSV query (`api.osv.dev`) for vulns affecting the latest - published version. -Screens 2–3 fetch registry metadata (`src/harness/registry-metadata.ts`) — -network is acceptable at admission (human-invoked) and never on the hook -path; both fail open with a loud "screen skipped" note when offline. -`allowlist verify` exits non-zero on unapproved deps (CI-gateable). - -Source files (added 2026-05): -- `src/harness/package-install-parser.ts` — pure-function parser for ten - install verbs (npm/pnpm/yarn/bun/pip/pipx/poetry/uv/cargo/gem/bundle/go), - classifies each positional spec as registry / git_url / tarball_url / - local_path / file_url. -- `src/harness/package-allowlist.ts` — file I/O, sha256 snapshotting, - per-spec `isPackageAllowed` decision, `effectiveLicenseAllowlist`. -- `src/harness/license-policy.ts` — SPDX allowlist seed + `isLicenseAllowed` - (exact ids, WITH exceptions, top-level OR/AND; parens/`+` → conservative - false). -- `src/harness/registry-metadata.ts` — admission-time-only network module: - registry latest-version/license fetch + OSV advisory query (both fail open - to null). -- `src/harness/evaluator/package-install-guard.ts` — daemon-side - PreToolUse Bash gate combining parser + allowlist. -- `src/harness/evaluator/manifest-edit-guard.ts` — daemon-side - PreToolUse Write gate; diffs the manifest's dep entries before/after - the edit and blocks if any newly-added entry is not on the allowlist. -- `src/commands/allowlist.ts` — `interlinked allowlist` subcommand. - -Tests pin every ecosystem path (positive + negative cases). The pre-2026-05 -`builtin-npm-no-ignore-scripts` warn-only rule still fires for -defense-in-depth on allowlisted installs (a stale `--ignore-scripts`-less -install of a package that's been updated since approval is still risky). - -## Sponsor slots - -Opt-in sponsored row 3 on the statusline, driven by an Ed25519-signed feed -(fail-closed: unsigned/tampered/expired ⇒ no render; control bytes stripped -at the daemon). Client-side code is public: `src/harness/sponsor/`, -`src/commands/sponsor.ts`, `src/lib/sponsor-spinner.ts`, -`src/registrars/sponsor.ts`, row-3 render in -`src/lib/hook-installers-statusline.ts`. `interlinked sponsor -enable|status|disable` manages opt-in. Intake, review tooling, and the -Worker live in the private `interlinked-cloud` repo; operator notes in -`CLAUDE.local.md` (gitignored). - -## Jev-backed semantic checks (opt-in, added 2026-09-16) - -Three checks ask TypeSafe's Jev model (System One: typed probabilities, no -text, ~200 ms, ~$0.00005/call) a question the deterministic registry cannot -answer. They live under `src/harness/jev/` behind `jev.enabled` in -`guard-rules.local.json` (default OFF) with `TYPESAFE_API_KEY` in -`config.local.json`; every one is warn-only and fail-open, and NONE sits in -the registry or `interlinked verify` — `feedback_harness_deterministic_only` -still governs the check pipeline. Each module header carries its measured -operating point (blind-labeled evals, k/n; run-book -`scratch/CAMPAIGN-jev-checks.md`, intake `docs/external-pulse/typesafe-jev.md`). - -| Check | Surface | Question | -|---|---|---| -| `claim-evidence.ts` | Stop nudge `[interlinked:jev-claims]` (`server/lifecycle-stop-jev.ts`) | Is each claim in the final message backed by a tool call in this turn? | -| `test-title-body.ts` | `interlinked jev test-titles ` | Does the test body test what its title claims? (the semantic half the retired `test_name_matcher_mismatch` lacked) | -| `doc-claim-liveness.ts` | `interlinked jev doc-claims ` | Does a doc paragraph claim a module is live that nothing imports? | - -A Jev verdict is a scoring signal merged tighten-only, never a lone block: it -cannot write a block reason, and its probabilities are calibrated per group, -not per call. Re-measure before moving any threshold; the eval drivers and -labeled datasets are under `scratch/2026-09-16-jev-checks/`. - -### Semantic graph (opt-in, 2026-10-27) - -`src/harness/semantic-graph/` builds typed edges between code units (functions, -doc comments, tests, markdown sections): deterministic candidate rules -(`candidates.ts`) bound each packet, Jev judges it as one Choice plus `none` -(`judge.ts`), Haiku 5.5 confirms the top slice (`confirm.ts`), and the -append-only store under `.interlinked/semantic-graph/` keeps every judgment -(`store.ts`; `build.ts` skips any packet hash with a live edge, `refresh.ts` -marks changed sources stale first). Relationship types live in -`.interlinked/semantic-relationships.json` (three seed types written on the -first build; strict parser, unknown keys refused). Jev/Haiku actions run only -on the internal runner — `node --import tsx scripts/internal/jev.mjs -semantic-graph build|refresh|confirm` (`commands/semantic-graph-internal.ts`); -the public `interlinked semantic-graph metrics|status|edges` is read-only. -The rule: the graph ranks and proposes, never gates, never in `verify`. - -## External-pulse intake - -Before "what can we do with X?" on a tool, paper, or repo found on the -internet, fill in the rubric at `docs/external-pulse/INTAKE.md` (six lanes -+ determinism filter + smallest-spike + which surface ships it). Output -goes to `docs/external-pulse/.md`, one page per project — PRIVATE -(2026-08-17: `docs/design`, `docs/plans`, `docs/external-pulse`, reviews, -marketing, and upstream-bug notes are real files here but gitignored from -this public repo and versioned by the operator overlay repo instead; -`.ignore` negations keep them searchable and @-mentionable. Competitive -intake, strategy, and unfixed-gap analyses do not belong in the public -tree. Overlay mechanics live in CLAUDE.local.md). -Skip the rubric for drive-by curiosity — it's specifically for the things -that would otherwise become a paste-and-ask. See `docs/external-pulse/codewiki.md` -for a worked example, including the "marketing-vs-reality" failure mode -(read the load-bearing function in source, not the README). - -## Baseline-integrity gate (ratchet water-lines may only tighten) - -Spec: `docs/design/baseline-integrity-gate.md`. Every ratchet (coverage / mutation / -per-edit-coverage / cyclomatic-slew / CRAP / line-cap / untested-file floor) decides -by reading a committed water-line JSON under `.interlinked/`. The agent being gated -has write access to those files, so lowering one is the canonical gate-gaming move — -it defeats every ratchet at once. `src/harness/evaluator/baseline-integrity-gate.ts` -(PreToolUse `block`, `rule_id: baseline_integrity_gate`, wired in `pre-tool.ts` via -`evaluateBaselineIntegrityGate` in `pre-tool-guards.ts`) blocks a Write/Edit/MultiEdit -that loosens any of `coverage-baseline.json`, `coverage-edit-baseline.json`, -`mutation-baseline.json`, `large-files-baseline.json`, `untested-files-baseline.json`, -`metric-caps.json`. **Direction is per-file and non-uniform** (see the doc's table): -coverage/mutation values may only rise; caps (`max_*`/`crap_threshold`) may only -tighten and `min_coverage` may only rise; `untested-files.files` is an *exemption -list* so it may only shrink; `large-files` grandfather counts may only shrink. -Compares against the **current on-disk** water-line (not git HEAD — most baselines are -gitignored), which the hook sees pre-write. The harness's own ratchet raises go through -internal `fs` writes (`coverage-ratchet.ts` etc.), never the edit tools, so they never -hit the gate. Bypass an intentional reset with `INTERLINKED_DISABLE_BASELINE_GUARD=1`. -**tsconfig strictness is a water-line too** (2026-09-01): `evaluator/config-loosening-gate.ts` -BLOCKS a Write/Edit that flips any tracked strictness flag off relative to git HEAD -(`strict` and its implied family, `noUncheckedIndexedAccess`, `exactOptionalPropertyTypes`, -`noImplicitOverride`, `noUnusedLocals`, `noUnusedParameters`, and the inverted-polarity -`allowUnreachableCode: false`). Same bypass env as above. `package.json` / biome loosening -stays ask-mode. The `tsconfig_strictness` check *demands* only four flags from any repo; the -three dead-code flags are advisory there — the gate ratchets them once a repo turns them on. -**The vitest coverage denominator is a water-line too** (2026-09-04, coverage-campaign -pre-work): the same gate routes `vitest.config.*` / `vitest..config.*` / `vite.config.*` -to `evaluator/vitest-coverage-water-line.ts`, which BLOCKS a Write/Edit whose -`coverage.exclude` gains a member or whose `coverage.include` loses one relative to git HEAD -(set semantics; reorder/dedupe/format allowed). It compares only when BOTH sides declare the -array as string literals; a spread, identifier, template-with-expression, second `coverage:` -object, parse failure, `typescript` unavailable, or present-vs-absent array is UNDECIDABLE and -allows with a warning naming the member — a block needs ~zero FP, and a declared array -replaces vitest's defaults so absent-vs-present is not comparable. One line in that array -used to remove a file from every coverage ratchet forever, silently (the ratchet iterates the -REPORT and copies a vanished file's baseline entry forward). - -A **commit-gate backstop** (`evaluator/commit-baseline-gate.ts`, wired in -`pre-tool-pipeline.ts` before `runCommitGate`) closes the `apply_patch`/sub-agent hole -for the 3 git-tracked/stageable baselines (large-files, untested-files, metric-caps): -on a real `git commit` it diffs `git show HEAD:` vs the staged blob through the same -`detectBaselineGaming` detector. A sibling test-integrity check, `snapshot_hygiene` -(`checks/snapshot-hygiene.ts`, advisory), blocks writing a `*.snap.new` / `*.pending-snap` -snapshot-review artifact (the snapshot analog of leaving an `.only`/`.skip` behind). - -## Monotonic metric ratchet (effective caps and retained debt) - -The historical design is `docs/design/monotonic-metric-ratchet.md`. Current policy -uses effective caps and grandfather identities, without sub-cap edit-size limits. -Read `.interlinked/metric-caps.json` and `interlinked caps status` for this repo's values. -- **Cyclomatic** — `complexity-write-guard.ts`: new over-cap functions and over-cap - growth block. Under-cap changes can land in one coherent patch. Existing debt may - hold or shrink according to the grandfather ledger; splitting cannot relax the cap. -- **Coverage** — `coverage-write-decision.ts` (pre-existing): blocks an uncovered - added line or a per-file coverage drop vs `coverage-baseline.json` (high-water). -- **Cognitive** — `cognitive-write-guard.ts`: the former +4-per-edit block is removed. - Cap crossing, over-cap growth and grandfather identity rules remain enforced. - Flatten nesting with guard clauses or cohesive helper responsibilities when useful. -- **CRAP** — implied: CRAP = cyclo²·(1−cov)³+cyclo is ↑ in cyclo, ↓ in cov, so the - cyclomatic and coverage changes can both affect it. There is **no** separate sub-cap CRAP - ratchet: every CRAP gate (`decideCrap` block, `computeCrapRisers` advisory) - fires only at/over cap 25, which bounds new/touched functions and is the - end-state backstop. A function whose coverage is UNKNOWN (no report entry) - yields no CRAP finding at all — unknown is not 0%, and treating it as 0% drove - CRAP to its ceiling and false-blocked edits to fully-covered code. - -Endgame seam (mutation, not built this session): the per-edit run returns the -FULL `MetricRegression[]` (all metrics at once) so an agent fixes them in one -pass; a parallel mutation suite slots in as "another metric" over the same -scoped overlay + affected-test set, kept ≤25s by small files. - -## Complexity-campaign tooling (added 2026-09-02) - -Built for whole-repo burn-downs (cyclomatic / cognitive / LoC-per-file) so the -gates HELP the campaign instead of blocking the refactor they demanded. Ten -lanes, every one a deterministic local surface; numbers live in -`.interlinked/metric-caps.json` and the ledger, never in this prose. - -| Lane | Surface | What it does | -|---|---|---| -| Grandfather ledger | `interlinked caps ratchet --to [--dry-run]`, `caps status`; `.interlinked/function-complexity-baseline.json` (committed; `function-complexity-baseline.ts`, gate `evaluator/function-complexity-baseline-gate.ts`) | Tightens the cap and records every function over it as `{file,name,line,value}`. A listed function may HOLD or shrink at its recorded value; an unlisted over-cap function blocks even when held. Shrink-only under `baseline_integrity_gate` (a value may fall, an entry may drop, nothing may be added except by `caps ratchet` on a tightening; Write-tool creation of the ledger is refused — only the ratchet writes it). `caps set cyclomatic\|cognitive` delegates to the ratchet whenever a section exists, so cap and ledger cannot drift; the commit-gate backstop covers it as a tracked baseline. | -| Census + proposals | `interlinked metrics complexity [--metric …] [--top n]`, `interlinked caps propose` (`commands/metrics-complexity.ts`) | Percentile ladder, histograms, hotspots, per-file mass, and "the smallest cap whose ledger stays under budget". Calibrate against the TREE, never fixtures. | -| Decomposition plan | `harness/decomposition-plan.ts`, wired as `planFor` on the cyclomatic spec (`evaluator/metric-gate-plan-hints.ts`) | The cyclomatic block now carries a `↳ plan:` sub-line per named over-cap function: the fewest arm extractions that bring it under the cap. Anonymous units and held/grandfathered functions get no plan. | -| Moved-line coverage | **NOT LANDED** (2026-09-04 audit: `evaluator/coverage-moved-lines.ts` was never added to git; no `classifyEditedLines` symbol exists; the only trace is an agent lane record in `scratch/build-lanes.json`) | Designed behavior: per-edit coverage would split edited lines by PROVENANCE (multiset diff of normalized text) so a relocated uncovered line is not a NEW uncovered line. Today the added-line block has no such exemption; `per_edit_coverage` is OFF locally so nothing observes the gap. | -| Survivor moves | `mutation/survivor-moves.ts` (`priorContent` on `evaluateMutation`, `movedSurvivors` on the verdict) | Per-edit mutation reconciles a survivor that moved into an extracted helper against its vanished same-content twin instead of charging it as new. A vanished NON-accepted twin (killed/uncovered) never excuses an arrival. | -| Assertion moves | `checks/assertion-move.ts`, `harness/assertion-waiver-log.ts`; `INTERLINKED_ASSERTION_MOVE_WAIVER=1` (logged) | `mutation_directed_assertion_removal` distinguishes an assertion MOVED to a new test file from one deleted; the waiver is an audited one-command escape, never silent. | -| Characterize-first | `evaluator/characterize-campaign-target.ts`; `structural_checks.characterize_mode: block\|warn\|off` (default `warn`) | In `block`, an edit to a ledger-listed function requires an observed test run covering that file first (per-file, directory, or `.`). Covers Write/Edit/MultiEdit AND apply_patch. | -| Helper hygiene | `checks/helper-hygiene.ts` → `new_export_without_importer`, `extracted_helper_duplicate` (pre_warn, advisory) | Edit-time nudges for the two decomposition footguns: exporting a helper nobody imports, and re-extracting a helper a sibling already has (≥0.90 shingle-Jaccard). Diff-vs-baseline checks, so they have no verify surface by design. | -| Split plan | `interlinked metrics split-plan [--max-clusters 2..4]` (`commands/metrics-split-plan*.ts`) | Intra-file reference graph → 2–4 cohesive modules with line count, ΣCC, imports, a filename each, and the cross-module references the split creates. | - -A per-file "no ΣCC regression" guard was designed and REJECTED: extraction -raises the file's ΣCC by construction (each helper adds 1), so it would block -the burn-down itself. Campaign run-book: `scratch/CAMPAIGN-cc16.md`. - -**First live run (cyclomatic 22 → 16, 2026-09-02):** 105 file units, 219 -agents (decompose → adversarial verify → one fix round), 0 units failed; every -function ended ≤ 16 and the ledger regenerated empty. What the gates taught -(all fixed the same day — the campaign is the calibration corpus a check -cannot get from fixtures): -- The 500-line **no-growth** rule is the dominant force: ~40 units could not - add a single line to an over-cap parent, so helpers went to a NEW sibling - module (companion test first, module, then the parent import). Expect the - exporter-first order, not in-place extraction, whenever the parent is over cap. -- `stale_read_then_write` / `file_overwrite_after_other_agent` attributed a - subagent's OWN writes to "another agent" (~30 times): activity rows carry - the parent session id with a per-subagent `agent_name`, and the trajectory - pins the first agent_name it saw. Same session id is now self. -- The characterize signal lived in the 100-entry `commands_run` ring, so a - test run at the start of a long unit expired behind typechecks and greps - (8 forced re-runs). Test-runner commands now go to a durable - `test_commands_run` list (500 entries, 2000 chars). -- `dead_type_exports` and `public_api_leaks_internal_type` contradicted each - other on a type named only in an exported signature; the dead-type side now - exempts signature-referenced types. -- `extracted_helper_duplicate` read a verbatim MOVE (sibling written first, - originals deleted next edit) as six re-extractions; ≥0.99 similarity or a - new file now yields ONE "move in progress" note. -- `ubs_string_concat_in_loop` fired on `cursor.offset += n`; numeric-named - targets / numeric RHS evidence are now exempt. - -**Second live run (lines per file, 2026-09-02):** 30 over-cap files → 0, the -grandfather list emptied, 56 new modules, 0 units failed. Each unit used -`metrics split-plan` for the cut and a verify probe that ran -`circular_imports` + `dead_exports` + `dead_type_exports` per file plus a -whole-repo `interlinked deadcode` diff against a pre-campaign baseline: 0 new -dead exports, 0 new unreachable files. Lessons: -- **Exporter-first splits are inherently transient-noisy.** Between "sibling - written" and "parent block deleted" every duplicate detector fires - (`duplicate_type_declaration`, `code_clones`, `extracted_helper_duplicate`, - TS2323 redeclare). The move-in-progress classification now covers types as - well as functions; expect one note per sibling, not one per symbol. -- **A probe that calls a 3-arg detector with 2 args reports `undefined` - findings.** Three units lost time to `checkDeadTypeExports(content, file)` - missing its `cwd`. A verify probe is code too: run it against a known-clean - file before trusting a red result. -- **Concurrent units see each other's transient breakage** through the - project-wide tsc pass and `vitest related`. Verifiers must attribute a red - result to a file in their own unit before rejecting; the campaign's falsifier - prompt now requires file:line evidence for exactly that reason. -- `write_without_mkdir` fired on writes directly inside a `mkdtempSync` dir; - fixed to recognize mkdtemp-created directories. - -**Deletion wave (2026-09-02, after the two campaigns):** what the deterministic -detectors could and could not decide, measured: -- `interlinked deadcode` dead exports: 41 → 0 (26 un-exported, 12 deleted); - typed dead branches 18 → 0 (5 impossible branches deleted, 8 were TYPES THAT - LIED — `Node.parent`, sparse-array holes, a null session a test proves — - where the guard stayed and the type was widened). Re-export shims left by - the splits: every test-only shim removed and the tests re-pointed. -- Test-hygiene detectors were mostly wrong at the deletion decision: - `duplicate_test_names` 10 → 1 true duplicate (names match, bodies differ: - rename, not delete); `test_missing_sut_import` 87 → 0 orphans (it keys on - the filename stem, and black-box CLI/daemon tests import no module by - design); `assertion_free_test` 2 → 0 (assertion in a helper / two lines - down). They locate candidates; they do not adjudicate. -- Product files with no non-test importer: 43 → 3 real orphans. The rest were - entry points (bin/exports/setupFiles/build entries/evals) or designed-but- - unwired modules. SEVEN carried a commit message or design doc claiming the - feature was live (`git log -S` showed six were never imported, one was - reverted and never re-landed). Decisions: Stop-phase self-heal, CRAP - telemetry, and `public_symbol_test_case` wired; agent-io primitives deleted - (spec kept); dead-code-signal, retrieval-cost, graph-prediction harvester - left as is. The generalizable check: "commit/doc says X now runs, nothing - imports X" — a claim-vs-import-graph detector, not yet built. -- `interlinked deadcode`'s `testOnlyImporterFiles` lane over-reports ~3x - (147 vs 43): it does not count `export … from` barrels or dynamic imports - as importers. Fix before trusting it. - -**Third live run (cognitive 30 → 20, 2026-09-02):** 127 functions in 110 -files, 0 failed, ledger regenerated empty; distribution afterwards p95 12, -p99 17, max 20, 293 over the advisory 15 (was 406). The cognitive planner -(`cognitive-plan.ts`, wired as the `↳ plan:` line) was consulted before every -edit: followed verbatim on 47 units, in substance on 15. Where agents deviated -they were right to: a loop body that mutates caller state or carries -`break`/`continue` cannot become a bare helper call, so they extracted the -DEEPEST sub-block instead (the next rung on the same ladder). The estimator's -residual-guard correction holds (delta 0 on hand-applied plans) but it does -not price loop-local state that must be threaded through a helper's -signature — the remaining source of 3–9 point over-estimates. 106 blocks, -16 judged false positives, all transient exporter-first noise or -cross-unit tsc attribution. - -## Conventions - -- **Output mode pattern**: All commands support `--json`, `--short`, `--full` via `getOutputMode(opts)` and `output(mode, data, { json, short, normal, full })`. -- **Graceful degradation**: Commands use `Promise.allSettled` for local+server parallel fetches, falling back to local-only when server is unavailable. -- **Dry-run support**: `enable`, `sync`, `clean` support `--dry-run` / `--force` patterns. -- **Hook script is self-contained**: The generated `.mjs` has no imports from the CLI package — it must work standalone even if the CLI is uninstalled. -- **Hook uninstall walks to git root**: `uninstallAllHooks()` checks ancestor directories via `findProjectRoot()` to clean `.claude/settings.json` files above CWD. -- **CWD-relative paths**: All `.interlinked/` paths are resolved relative to `process.cwd()`. - -## Testing - -```bash -npx vitest run # Full suite (~20k tests; count drifts — don't pin it here) -npx vitest run src/harness/__tests__/evaluator.test.ts # Harness guard tests -npx vitest run src/commands/__tests__/cli-bugs.test.ts # CLI regression tests -``` - -Test files: -- `src/harness/__tests__/evaluator.test.ts` — destructive command blocking, sleep detection, protected files, curl-to-MCP, auto-reservations, safe command allowlist -- `src/harness/__tests__/trigram-index.test.ts` — trigram index, regex decomposition, grep accelerator -- `src/harness/__tests__/structural-checks-extended.test.ts` — structural check validation -- `src/harness/__tests__/generic-checks-extended.test.ts` — generic code analysis checks -- `src/harness/__tests__/impact-analysis.test.ts` — cross-file impact analysis -- `src/harness/__tests__/project-graph.test.ts` — project dependency graph -- `src/harness/__tests__/taint-tracker.test.ts` — sensitivity classification -- `src/harness/__tests__/diff-aware-checks.integration.test.ts` — diff-aware filtering -- `src/harness/__tests__/command-guard-parity.test.ts` — guard rule parity with inline fallback -- `src/harness/__tests__/docs-freshness.test.ts` — validates generated docs match source -- `src/harness/__tests__/hook-conflicts.test.ts` — hook installation conflict detection -- `src/commands/__tests__/cli-bugs.test.ts` — regression tests for numbered bugs (Bug 4, 5, 10, 14, 18, 21, 23, 24, 26) -- `src/commands/__tests__/activity-workspace-regressions.test.ts` — activity feed API contract and workspace switch tests - -Tests heavily mock the file system and network. The test infrastructure uses vitest with `vi.mock()` for module-level mocking. - -Manual harness testing via Unix socket: -```bash -node dist/harness/server.js --verbose & -echo '{"hook_event":"PreToolUse","session_id":"t","agent_source":"claude","tool_name":"Bash","tool_input":{"command":"rm -rf /"},"timestamp":"2026-03-17T00:00:00Z"}' | nc -U .interlinked/harness.sock -# Expected: {"decision":"block","reason":"BLOCKED: Recursive deletion..."} -``` - -## Project e2e enforcement (plan 31, Unit A landed 2026-09-23, Unit B 2026-09-24) - -`src/harness/project-e2e/` is the host-project feature the Interlinked-only -E2E lane below is NOT: a repository declares behavioral scenarios in -`.interlinked/e2e-policy.json` (projects → suites → scenarios → portable -contract cases in `.interlinked/behavioral-contracts.json`) and the daemon -turns observed edits into scenario obligations that only a supervised run can -clear. Spec: `docs/plans/31-project-e2e-enforcement.md`; run-book -`scratch/CAMPAIGN-project-e2e.md`. Unit A ships: strict policy parser -(`policy.ts`), expectation lifecycle proposed → accepted / disputed / -superseded bound to exact revision digests (`expectations.ts`, file side in -`store.ts`), per-scenario input generation (`generation.ts`), append-only -ledger + pure reducer (`ledger.ts`, `.interlinked/e2e-obligations.jsonl`), -change reconciliation (`reconcile.ts`), the ONE qualification predicate with -reason codes and the 0/1/2 exit contract (`qualify.ts`), write-once receipts -(`receipt.ts`, `.interlinked/test-runs/e2e//receipt.json`), the -supervised managed-process runner (`run.ts`, reuses `contracts/runner.ts` -under the project heavy-process lease) and the hook surfaces (`hooks.ts`: -PostToolUse `[interlinked:e2e]` lines, Stop summary). CLI: `interlinked tests -e2e status|plan|run|check` and `tests e2e expectations -propose|review|accept|replace|dispute`. Fixtures under -`project-e2e/__fixtures__/` (TypeScript CLI, Python CLI, Rust CLI) share no -code with the engine; `lifecycle.test.ts` is the Unit A acceptance run and -`dogfood.test.ts` drives the built `dist/index.js` from a disposable host. - -Rules that bind (hardened by the 2026-09-23 review, findings R1–R12 in -`scratch/review-project-e2e-unit-a/REVIEW.md`, each pinned in -`review-regressions.test.ts`): a scenario is satisfied only for the exact -generation a receipt names — policy digest, affected files, manifest, -`contract-policy.json`, each case's cited requirement, declared inputs and -the bytes of any path-shaped executable in argv (so revoked acceptance, a -rewritten requirement or a swapped candidate binary all go `stale`); -collection limits (>8 MiB, symlinks, file cap) are gaps ⇒ `unavailable`, -never `scope=complete`; the receipt reader is a constructing parser (an -unknown case state ⇒ `RECEIPT_INVALID`); receipts bind the canonical -worktree root and the ledger's runId; the policy parser refuses -`boundary.entry: "http"` and any `real` component other than `application` -until a managed service adapter exists, and an `http` runner is -`BOUNDARY_UNSUPPORTED`; expectation revisions are recomputed from content on -load and on every decision; runs copy the project into a disposable snapshot -(private HOME) before prepare/cases, so the live tree is only read; -compiled executables travel byte-for-byte; a bound PROPOSED expectation is an -advisory unless `gates.review: "require"` (disputed/superseded always block); -mapping gaps in a required-mode project make `check` exit 1; expectation -binding is project-scoped. Round 2 (2026-09-24, F1–F6 in -`REVIEW-round2.md`, pinned in `review-regressions-round2.test.ts`): the -manifest and acceptance are frozen before preparation and restored after, -declared inputs are re-hashed in the snapshot after preparation (any drift ⇒ -no case runs), executed case digests must equal the live contract digests, -symlinks are never copied into the snapshot and a link covering a declared -input is a scope gap, every argv file (prepare and case), every bound -expectation's cited document and each input's mode bits are part of the -generation, protected-inventory capture gaps gate required projects, a -project with zero scenarios still owes its protected inputs, and nested -projects accept into their own `contract-policy.json`. Round 3 (G1–G3, -`review-regressions-round3.test.ts`): the ABSENCE of a control file is -frozen too, wildcard globs detect symlinked ancestors segment-wise, and -expectation citations resolve under the project root everywhere. A green run never accepts an unaccepted contract; -`.interlinked/e2e-policy.json` absent ⇒ every hook path returns early at -zero cost, and `tests e2e check` exits 2 UNCONFIGURED (never a pass). The -TypeScript fixture compiles `src/cli.ts` with Node's built-in type stripping. -`src/e2e/project-e2e.e2e.test.ts` runs the lifecycle through a real daemon -and the built CLI. Status is precise: Unit A is reviewed and locally -validated with TypeScript and Python; the compiled Rust route is -UNVERIFIED here (cargo absent) and owes a run on a Cargo-equipped CI runner. - -Unit B (2026-09-24) is the adoption workflow, `tests e2e -discover|surfaces|adopt|doctor` (`commands/tests-e2e-adopt.ts`): `discover.ts` -inspects a repository read-only (manifests to depth 4, a `__main__`-guarded -`.py` directory counts as a project, nested `package.json` without a declared -workspace is an ambiguity, a nested project is named by its directory) and -proposes an ADVISORY policy with one scenario per process-runner contract case -plus gaps; `surfaces.ts` inventories bins / scripts / OpenAPI JSON operations -in document order and maps them to scenario `surfaceIds` (explicit / -unresolved / dangling; YAML and code-registered routes are limits, never an -empty complete inventory); `adopt.ts` writes only the selected projects and -scenarios, forces advisory unless `--mode required`, strips every expectation -(inferred behavior is never adopted), and refuses to overwrite without -`--replace`; `doctor.ts` diagnoses prerequisites without running (exit 1 -fail, 2 invalid policy). TypeScript and Python are the pilots; the policy, -discovery report and qualification rules carry no language-specific field. -Unit B review (2026-09-24, B1–B6 in `scratch/review-project-e2e-unit-b/REVIEW.md`, -pinned in `review-regressions-unit-b.test.ts`): the protected scope is derived -from the ACTUAL layout (`src/**`, python packages, top-level source files, the -executable's own file), never a nonexistent default; `adopt --mode required` -refuses a project with no scenarios or whose protected globs match no file; -discovery binds the build's script files as shared inputs and infers artifacts -from path literals in the script plus contract paths absent from the tree (an -uninferable build is a named `suites[].artifacts` gap); a project-level -`surfaces` list (`{id, kind: cli|http|other, address}`) is the -language-independent declaration that binds through `surfaceIds` (the -`cli:`/`http:` id shape admits `:`, `/`, space and braces); OpenAPI path-item -`$ref`s resolve locally with bounded hops and an unresolved one is a named -limit; a `[project.scripts]` console entry is invoked as its declared callable -(never substituted by `-m`) and becomes a `python-entry` surface, or a gap when -its module has no file; subtrees under the depth bound are recorded in -`limits.omittedSubtrees` and a gap. Round 2 (C1–C3, `REVIEW-round2.md`): -build commands are word-split with quote and backslash handling (no -expansion) and a script word that resolves to no file, or a `$VAR`, is an -unresolved build-input gap; an artifact directory needs WRITE evidence -(`mkdir`/`writeFile`/`rm`/`outDir`/`--out` argument, or a contract path -absent from the tree) — a directory the script only reads is never an -artifact, and an inferred artifact glob covering an existing declared input -is a conflict gap; the console-entry wrapper is `sys.exit(callable())`, so -None/int/str returns keep console-script exit semantics. Round 3 (D1): a -conflict is RESOLVED conservatively, not just printed — the inferred glob is -dropped from the proposal so the existing input stays in freshness tracking -(`build.conflicts` is the structured record, echoed in the adoption notes), -unless the script names that exact path as a write target (a pre-built -`dist/cli.js` stays an artifact); `adopt --mode required` re-runs the same -evidence-aware check on any policy and refuses an artifact glob that covers -an existing bound input the build does not provably write. Round 4 (E1–E2): -write evidence is POSITIONAL — `writeFile`/`createWriteStream` first -argument, `copyFile`/`cpSync`/`rename` SECOND argument, `outfile`/`--out` -option value; a copy SOURCE or a variable destination proves nothing — and -the evidence text comes from the suite's declared `prepare` argv (an -`npm run ` alias resolves one level into package.json), so an explicit -`node build.mjs` policy adopts without any npm script. Round 5 (F1–F2) made -the invariant STRUCTURAL: an artifact-covered case input that already -EXISTS is still hashed into the generation (`generation.ts` -`addDeclaredInput`; listed in `ScenarioInputs.regenerated` so the -post-preparation drift check tolerates the build rewriting it), so an edit -goes stale no matter how the glob was inferred — textual write evidence is a -SIGN for proposing/accepting a glob, never proof and never load-bearing for -freshness; that evidence now strips comments, requires the literal to be the -complete argument, and is judged per SELECTED suite (a writer in a suite no -scenario runs proves nothing). Round 6 (G1): input ROLES are preserved — a -path collected as source (protectedInputs, a scenario's `affects`, -sharedInputs, build scripts, citations) is never listed as `regenerated` -even when an artifact glob also covers it, so preparation replacing the code -under test in the snapshot is still drift; required adoption refuses an -artifact glob that covers a protected source outright. Round 7 (H1–H2): the -drift exemption is computed across the WHOLE run (`run.ts driftExempt`: a -path exempt only if no scenario of the run holds it as source), and prepare -argv script files are always captured as source inputs whatever artifact -glob covers them (adoption refuses that overlap too). -Unit C (durable state, structured runner, scheduling; landed 2026-09-24, -UNCOMMITTED) makes the evidence survive concurrency and restarts. A suite may -be `adapter: "structured-runner"` (`run` argv + `report {format: json|junit, -path}`; scenarios declare `caseIds` and still bind `contractIds`): the runner -deletes any pre-existing report, runs the command in the snapshot, and -`structured-report.ts` parses a versioned JSON protocol (v1: `{version, -cases:[{id,status}]}`) or a documented JUnit subset (no DOCTYPE/entities, -`tests=` must match, nested suites refused); `skipped`/`todo` never pass and a -missing or malformed report leaves every declared case `CASE_NOT_RUN` -(exit 1). Every run writes `attempt.json` (pid, host, keys, generations) -before executing; the receipt is published temp→rename exactly once; and -`recoverOrphanedRuns` (run start, daemon SessionStart via -`hooks.ts recoverProjectE2eOrphans`) turns a dead-pid / other-host attempt -into an explicit `unavailable` attempt under an `orphaned.json` one-writer -marker. PostToolUse opens one durable request per pending key per session in -`.interlinked/e2e-requests.jsonl`; a run serves only the requests whose -key+generation its receipt certifies (`receipt.requestIds`), so two sessions -share one qualifying run and an unrelated key stays open. The policy's -`scheduling {autoRun, quietMs, minIntervalMs, budgetMs}` block (bounded, -`autoRun` default OFF) drives the pure `decideAutoRun` and the daemon-side -`AutoRunner`, which spawns `tests e2e run` DETACHED after the quiet period, at -most one job per project and one start per interval, retaining work that -arrives mid-run; nothing ever runs a suite inside the daemon. -`RunE2eOptions.signal` cancels: an aborted prepare or run is `ok: false` -"cancelled", the cases stay not-run, the attempt is `unavailable`. Pins: -`structured-report.test.ts`, `structured-runner.test.ts`, `attempts.test.ts`, -`requests.test.ts`, `scheduler.test.ts`, `review-regressions-unit-c.test.ts`. -Unit C review round 1 (2026-09-24, C1–C6 in -`scratch/review-project-e2e-unit-c/REVIEW.md`, pinned in -`review-regressions-unit-c-round1.test.ts`): the snapshot is re-verified -after EVERY writing stage (`run.ts stageIntact`: frozen controls restored, -declared inputs re-hashed against the generation, artifacts re-bound from -the bytes now present), so a native test command that rewrites protected -source in the snapshot leaves the run incomplete and no contract runs (C1); -a nonzero test-command exit is `execution.ok: false` and is explained only by -a failed/error case the report itself records, otherwise the run is -incomplete (C2); cancellation is checked before admission, threaded into -`runContractsUnderLease` (`RunContractsOptions.signal`; a case observed after -abort is unavailable, never a verdict) and re-checked after the contracts so -a cancelled run never publishes a complete result (C3); a policy that turns -`scheduling.autoRun` off, disappears or fails to parse DISARMS the project's -lane (`AutoRunner.disarm`), and the detached child re-validates the current -policy (`RunE2eOptions.automatic`, `INTERLINKED_AUTO_RUN=1`) before running -(C4); orphan recovery is per (run, key) — a crash between the per-scenario -publication rows recovers exactly the missing keys, and `orphaned.json` is -written AFTER the rows so it means completed, not claimed (C5); reconcile -reports `affected` (unresolved at the current generation) beside `pending` -(newly opened), and requests plus scheduling key off `affected`, so a second -session observing a generation another session opened gets its own request -and the shared receipt attributes both (C6). One regression the fix itself -introduced: importing `scheduler.ts` from `run.ts` moved it into a -`dist/chunk-*.js` shared with `dist/index.js`, and `resolveCliEntry` (which -took `../index.js` relative to its own bundle) silently found nothing, so -the detached child never spawned; it now verifies each candidate root by -its sibling daemon entry, and `src/e2e/project-e2e.e2e.test.ts` pins the -real detached child both enabled and disabled-before-timer. -Round 2 (D1–D2, `REVIEW-round2.md`, pinned in -`review-regressions-unit-c-round2.test.ts`): request attribution is frozen -at PUBLICATION and `serveRequests` serves exactly the ids the receipt names, -so a request arriving during execution is listed and served while one -arriving after publication stays open; orphan recovery is serialized per run -by `recovery.lock` (live same-host holder ⇒ skip, dead or foreign holder ⇒ -take over), the missing keys are re-derived under the lock, and two real -recoverer processes released at the same instant produce one row. -Round 3 (E1, `REVIEW-round3.md`): the hand-rolled lock published its owner -after exclusive creation, so an empty lock file read as abandoned; it is -deleted, and recovery runs under the repository's `withFileMutationLock` -(`src/lib/file-mutation-lock.ts`, keyed on the run's `orphaned.json`, -`waitMs: 0` so contention defers the orphan), which publishes ownership -atomically, recovers dead owners and never releases a successor's lock. -Unit D (managed HTTP services, native test layouts, proof modes; landed -2026-09-24, UNCOMMITTED). A managed-contracts suite may declare -`services[] {id, argv, env, ready {kind: http, path, status}}`; `{port}` is -allowed only there. `services.ts` allocates a loopback port, REFUSES it if -anything already answers (PE-19), spawns the argv in its own process group -inside the snapshot, calls it ready only while the OWNED child is alive and -answers the declared status, and on stop kills the group and proves the -port silent — a port that still answers belonged to something else, so the -run cannot qualify (PE-26). Contract cases may be service-bound -(`runner {kind: http, service, path, method, body?}`) with workflow -`steps [{kind: restart, service}]` (create → restart → read-back, §5.3); the -standalone contract runner marks such cases unavailable without the -supervisor. A scenario's `boundary {entry: http, service, real}` must name -an owned service; `fixture-store` is real only when that service's env -binds `{fixture-directory}`. The receipt carries `services[]` and each http -case's `service`; qualification grants `boundary: http-driver` only against -an owned, ready, cleanly stopped service, and a literal-URL case is never a -boundary. Fixture `__fixtures__/ts-http` (TypeScript HTTP service with -disposable persistence; PE-20 defect) is pinned by `http-services.test.ts`; -`py-native.test.ts` qualifies a pytest layout through the structured-runner -route plus portable contracts (pytest reports the fixture's extra unit test -too: undeclared native cases are observed, never required). Proof modes -(§9.4): a scenario may declare `proof {mode: old-new | controlled-fault | -characterization, revision | fault, designated}`; `sensitivity.ts` builds -the comparison side as a SECOND disposable snapshot (a `git archive` export -of the pinned commit run from the project directory, or the candidate with -exactly one recorded fault applied) with the candidate's frozen manifest and -acceptance, runs it through the same prepare → services → contracts stage, -and classifies per the §9.4 table (both-pass is NOT_DEMONSTRATED for -old-new, an unrelated failure before the designated case is not -demonstrated, a comparison that cannot be built or a non-passing candidate -is INCONCLUSIVE, characterization both-pass is preserved). The receipt -records `sensitivity[scenarioId]` (with `faults: [...]` instead of `fault`, -one comparison per recorded fault, demonstrated only when EVERY fault is, -per-fault records + `killFraction` in the receipt, `aggregateFaultProofs`; -dropping a base fault is `proof-dropped` — 2026-10-21, from E64c: one -violation under-samples a requirement), the attempt is `unavailable` unless -demonstrated/preserved, and qualification adds the `sensitivity` dimension -with `SENSITIVITY_NOT_DEMONSTRATED` / `SENSITIVITY_INCONCLUSIVE`. The live -worktree is only ever read (`proof-modes.test.ts` pins it byte-identical). -Not in Unit D: the MCP/Worker profile (§10.3), remote profiles. -Unit D review round 1 (2026-09-25, D1–D5 in -`scratch/review-project-e2e-unit-d/REVIEW.md`, pinned in -`review-regressions-unit-d.test.ts` + `services.test.ts` N5): a comparison -must ESTABLISH THE ACTION before its failure counts — the contract runner -records which DECLARED observables `matched` / `mismatched` per case, and a -failed designated case is a behavioral red only when it produced primary -output, exited 0, answered below 500, or ended with the declared exit code / -status; an undeclared abnormal end with no output (a missing import) is -INCONCLUSIVE `setup-build-dependency-failure`, never a demonstrated red. The -comparison's own lifecycle is evidence: `runComparison` carries -`contractsStage`'s completion, reasons and service records into -`sensitivity[id].lifecycle`, and an incomplete one (a leaked responder that -outlived teardown) is INCONCLUSIVE `comparison-lifecycle-failure` in the -classifier AND in qualify, whatever the cases said. A proof revision is -resolved to its commit at GENERATION time (`resolveProofRevision`, `git -rev-parse ^{commit}`): the sha is part of the generation and of -`QualifyInput.generation.comparison`, so a moved ref makes the receipt stale -(`STALE_GENERATION` + `SENSITIVITY_INCONCLUSIVE` "now resolves to …") and an -unresolvable ref is `SCOPE_INCOMPLETE`. A service's argv executable gets the -case-executable treatment — bytes in the generation, `regenerated` when an -artifact glob covers it, a source role only through another declaration — -so a prebuilt `dist/server.js` plus a harmless source edit runs and passes -while `dist/**` also in `affects` still turns the rebuild into drift. -`stopService` polls the whole OWNED process group (`kill(-pgid, 0)`), -escalates to SIGKILL while any member survives, and reports clean shutdown -only once the group is gone; a port squatter is still reported, never -killed. -Round 2 (R1, `REVIEW-round2.md`): output presence is not action evidence — -a startup banner before a missing import and a 500 "dependency unavailable" -body both look like output. A counterfactual proof now DECLARES its -evidence: `designated: [{id, outcome?, action?}]` is required for old-new / -controlled-fault (a plain id is refused). `outcome` names the observables -that ARE the designated outcome; every other observable the case declares -must hold on the comparison side. `action` names cases that must pass there -first (the workflow's create before its read-back). `classifySensitivity` -reads only the runner's per-case `matched` / `mismatched` sets: evidence -that did not hold ⇒ INCONCLUSIVE `setup-build-dependency-failure`, no -declared evidence (an outcome covering every observable, an undeclared key, -a record without observations) ⇒ INCONCLUSIVE `action-evidence-undeclared`; -exit codes, status classes and stdout are recorded, never decisive. A failed -action case is never an "unrelated" failure. Characterization takes no -split (every designated observation must hold on both sides). The CLI -fixtures' `orders.invalid` contract now declares its usage line on stderr as -the action evidence behind its exit-code outcome. -Round 3 (R1, `REVIEW-round3.md`): an action case establishes an observation -only if it EXECUTED before it. Sides are recorded in execution order, so -`misordered` checks the action's index precedes the designated case's on the -candidate (`preconditions`) and on the comparison (`unestablished`) — -otherwise INCONCLUSIVE `action-evidence-undeclared`; and because the runner -follows manifest order, `generation.ts actionOrderGaps` makes a reversed -manifest a scope gap (`SCOPE_INCOMPLETE`) before anything runs. -Unit E (stability cohorts, Playwright, quality feedback, runtime -observations; landed 2026-09-25, UNCOMMITTED). E1 (§9.5): a scenario may -declare `stability {qualificationRuns 1–5, seed?, clock?}`; `tests e2e -qualify --scenario [--runs n]` runs N INDEPENDENT supervised attempts -(own snapshot each; seed derived per attempt, `INTERLINKED_E2E_SEED/COHORT/ -ATTEMPT[/CLOCK]` reach prepare, services AND contract case processes), -publishes every attempt, records the cohort under -`.interlinked/test-runs/e2e/cohorts/.json` and a ledger `cohort` txn; -mixed ⇒ a quarantine row in `.interlinked/e2e-quarantine.jsonl` keyed by -generation (an unchanged rerun cannot erase it; a repair is a new -generation); budget exhausted ⇒ deferred, resumable; qualify dimension -`stability` + `STABILITY_*` codes (`stability.ts`, `cohort.ts`, -`policy-stability.ts`). E2 (§10.2): a `playwright` suite OWNS its app as a -`services` entry; the run fronts it with the supervisor's recording proxy -(`proxy.ts`, `INTERLINKED_E2E_BASE_URL`), forces `--reporter=json ---workers=1`, normalizes Playwright's JSON (`playwright-report.ts`: id = -`file › titlePath [project]`, the FIRST attempt decides, PE-27; skipped / -fixme / fail never pass) and credits each declared case exactly the requests -the proxy saw inside its attempt window (`browser-stage.ts`; receipt -`runnerKind: "browser"` + `boundaryRequests`; qualify `browser-driver` only -against an owned, ready, cleanly stopped service with ≥1 request). -`@playwright/test` absent in the project ⇒ cases `unavailable` with install -guidance and a `::playwright` doctor failure — never an -install (PE-24); the browser cache is passed as `PLAYWRIGHT_BROWSERS_PATH` -from the REAL home because the run's HOME is private. Fixture -`__fixtures__/ts-browser` (`.mjs` config/spec so the repo tsconfig never -sees `@playwright/test`); the LIVE route is asserted only where this -checkout carries `@playwright/test` and is UNVERIFIED here (`playwright.test.ts` -P2 skipped). Policy parsing was split: `policy-primitives.ts`, -`policy-suites.ts`. E3 (§12.3, §14): `quality-feedback.ts` turns the rule -table into `[interlinked:e2e-quality] /: at -:` advisories on PostToolUse (removed assertion/test block, -`.only`/`.skip`, truthiness replacement, raised timeout/retry, `force: -true`, timing wait, brittle locator, intercepted app endpoint, test with no -assertion) — net-new multiset diff so a moved line is silent, ≤3 lines, -never a verdict; `tests e2e scaffold [--suite] [--write]` proposes a -scenario (required: false, placeholder contract id) plus a skeleton whose -only assertion FAILS deliberately, never edits the policy, never overwrites. -E4 (§7.4, PE-85/86): `projects[].observations.runtimeCoverage: -off|node|node-required` sets `NODE_V8_COVERAGE=/coverage` on owned -services and contract case processes (never prepare or the test runner); -`runtime-observations.ts` folds V8 output into RUN-level `RuntimeEdge` -rows (`caseId: null` — shared servers get no per-case attribution) in -`/runtime-observations.jsonl`, the receipt carries the summary, and -`node-required` makes an incomplete collection `OBSERVATIONS_INCOMPLETE` -(missing child output is incomplete, never zero; a service must exit -normally on SIGTERM for V8 to flush — the fixtures do). Unit E review -round 1 (2026-09-25, E1–E5 in `scratch/review-project-e2e-unit-e/REVIEW.md`, -pinned in `review-regressions-unit-e.test.ts`): under a browser boundary the -portable contracts are SUPPORT cases judged by their own mechanism (an http -support case still through the declared service) and only a browser case -establishes the entry — none evaluated ⇒ `BOUNDARY_UNSUPPORTED`; a browser -boundary REQUIRES `requests: [{method, path}]`, the proxy records each -case's `boundaryObservations`, and the boundary holds only when every -required request was observed with a 1xx–4xx answer (GET / alone, a health -check or an intercepted API earns nothing); `tests e2e qualify` judges each -attempt by the shared predicate minus `STABILITY_*` and its exit is the -evaluation's whenever the cohort is qualified or the evaluation says 1 -(two green runs with unaccepted contracts exit 1); coverage completeness -reconciles an expected-process inventory — every service spawn's pid -(`ServiceRecord.pids`, restarts included) must have a `coverage--…` -file and contract processes are counted — so one flushing service never -hides another; and contract processes' `interlinked-contract-*` workspace -copies map back to project-relative paths, so a supervised CLI run yields -`dist/cli.js` edges. Round 2 (R1–R2): `receipt.services` is append-only -across stages and each record carries its `stage` (`browser` | `contracts`), -so a browser-stage lifetime that never flushed stays required and a browser -case is judged against the instance that served it; the process runner -records each case's own pid (`observations.pid`) and coverage is reconciled -by identity — a neighbour's helper file never discharges a case whose own -process wrote nothing. Composite-boundary pins run through a reporter double -(fake `@playwright/test` + a script driving the proxy). The LIVE controls -are verified (2026-09-25): `@playwright/test@1.59.1` (allowlisted; its -chromium 1217 matches the cached browsers) installed `--no-save`, the fixture -runs the package-local `node node_modules/playwright/cli.js test` (npm's -`.bin` shim breaks when copied), the browser cache is found under the -ACCOUNT home even when HOME is a sandbox, and `playwright.test.ts` P2 -(real Chromium ⇒ browser-driver) and N3 (`page.route` intercepts the API ⇒ -`BOUNDARY_UNSUPPORTED`) pass 6/6; they skip only where the package is -absent. -Unit F (completion gates and installed-package behavior; landed -2026-09-25, UNCOMMITTED). Hooks CHECK, the supervised lane EXECUTES. F1 -snapshot identity (`target.ts`): `tests e2e check --staged | --revision -` exports the INDEX (`git write-tree` + `checkout-index`) or a commit -(`git archive`) into a disposable directory and computes every generation -from those bytes, so a worktree receipt certifies a target only when the -generation digest is identical — an unstaged fix never certifies broken -staged bytes (PE-35); the evaluation records `target {mode, commit?, -tree?}`; a policy not in the target is UNCONFIGURED, an unknown revision -UNAVAILABLE (exit 2). F2 `scripts/smoke-tarball-e2e.mjs` runs the whole -lane from the packed tarball's own bin. F3 base-policy comparison -(`policy-diff.ts`, `policy-base.ts`, `policy-changes.ts`): `check --base -` compares the judged policy with the TRUSTED base's policy (distinct -from `proof.revision`, PE-74) and reports weakening kinds (removed/demoted -scenario or project, loosened gate/observations/boundary/proof/stability, -narrowed scope, unbound contract/case) as `POLICY_WEAKENED` (exit 1) unless -a §13 record in `.interlinked/e2e-policy-changes.jsonl` — written by -`tests e2e policy replace --base --project [--scenario] --rationale` — -binds the exact base and head digests; refactors and reorders are not -findings; a base without a policy is a bootstrap (PE-38); an unresolvable -base is UNAVAILABLE, never HEAD (PE-37). F4 git hooks (`gate.ts`, `tests -e2e gate install|status|uninstall`): pre-commit runs `check --gate commit ---staged --base HEAD`, pre-push runs one `check --gate ci --revision ---base ` per pushed ref (deleted ref skipped, new ref a -bootstrap); an existing hook is backed up and chained through a wrapper, -never replaced; only the BUILT `dist/index.js` is baked in (a `tsx` source -entry resolves from the hook cwd), else `interlinked` on PATH, else exit 2 -UNAVAILABLE; `--gate` honours `gates.commit/ci` (absent on a required -project ⇒ require; warn/off/advisory ⇒ reported, exit 0). F5 `tests e2e -ci` (`ci.ts`): a FRESH supervised run then the same check, base from the CI -event (GitHub pull-request base ref / push `before`, GitLab merge-request -diff base / `CI_COMMIT_BEFORE_SHA`, zero sha = bootstrap) or `--base`; no -base ⇒ UNAVAILABLE and nothing runs; a satisfied verdict whose receipt this -invocation did not produce is `CI_RECEIPT_NOT_FRESH` (exit 1); §13 trust -limits are printed (receipts, base, checker path — pin the CLI in CI). F6 -(`stop-summary.ts`): the Stop reminder is bounded per session (3 identical -reminders, one pause note, silence until the open set changes, PE-39), an -all-unavailable set is a handoff (no "run it again"), a quarantined -required scenario stays visible with the qualify path; with the daemon down -the cold Stop says the obligations were NOT CHECKED -(`hook-entry-cold-gates.ts coldProjectE2eStopNotice`); `interlinked verify` -gains an `e2e` section (`verify/project-e2e-section.ts`, JSON key -`project_e2e`) with the same codes as `check`, failing under verify's exit -convention; absent policy ⇒ no section at zero cost. Pins: `target.test.ts`, -`policy-diff.test.ts`, `policy-base.test.ts`, `gate.test.ts` (real `git -commit`/`git push` into a bare remote), `ci.test.ts`, -`stop-summary.test.ts`, `project-e2e-section.test.ts`, -`hook-entry-cold-e2e-stop.test.ts`. Unit F review round 1 (2026-09-25, -F-R1–F-R7 in `scratch/review-project-e2e-unit-f/REVIEW.md`, every -counterexample re-run by its `probe.ts` and pinned in -`review-regressions-unit-f.test.ts`): the chained hook's gate program is a -separate file (`.interlinked-e2e-gate`) fed the SAME captured stdin as -the original — a heredoc on the gate's stdin had replaced git's ref rows and -let an unqualified push through (R1); `--gate` decisions read the judged -TARGET's own policy (`E2eEvaluation.projects`) for the failing projects -only, and `POLICY_WEAKENED` is never waived by the candidate's gate setting -(R2); `tests e2e ci` exports the CANDIDATE COMMIT (`--revision`, else -`GITHUB_SHA` / `CI_COMMIT_SHA`, else HEAD) into a disposable directory with a -fresh `.interlinked` state and runs everything there — plain runs and every -adopted stability cohort — through `gitRoot` threading (run / reconcile / -cohort / evaluate resolve refs in the real repository), so a working-tree -fix, a workstation receipt, an old cohort or a local record can never reach -the verdict; evidence is copied to `.interlinked/test-runs/e2e/ci//` -(R3, R7); §13 replacement records are read from the judged target (the -export for `--staged` / `--revision`, `PolicyEvaluation.recordsFrom`), so a -record must be COMMITTED — carve `.interlinked/e2e-policy-changes.jsonl` out -of `.gitignore` (R4); a revision is exported as its exact tree via -`read-tree` into a private index plus `checkout-index`, never `git archive` -(`export-ignore` hid the committed base policy) (R5); an omitted gate compares -as its effective default (`GATE_DEFAULTS`: commit/ci require, stop warn, -review advisory), so `require (default) → off` is `gate-loosened` (R6). -Round 2 (F2-1–F2-3, `REVIEW-round2.md`, pinned in the same file): a target -is materialized straight from the OBJECT STORE (`target.ts materializeTree`: -`ls-tree -r` for membership and modes, `cat-file --batch` for bytes; the -index is frozen with `write-tree` first) — `checkout-index` applied smudge -filters, so a configured filter repaired a committed defect on export -(F2-1); the CI export's execution state (ledger, requests, quarantine, -`test-runs/`) is EMPTIED before anything runs and freshness is the set of -receipts written under that emptied directory, so a committed deferred -cohort or quarantine row is never resumed or counted (F2-2); the proof -comparison side is exported from the REAL repository's project directory -(`exportRevision(join(gitRoot, project.root), …)`, also via -`materializeTree` of the `:` subtree), so characterization -and old-new proofs resolve inside CI (F2-3). Round 3: a committed symlink is -a blob whose bytes are the link target — every blob is fetched and links are -recreated without being followed, in both export modes (a documentation -symlink outside any input scope had made the whole export fail). Round 4: CI -checks every segment of `.interlinked` and its execution-state paths in the -export for a symlink BEFORE cleanup or any state write (a committed link at -`.interlinked/test-runs` had let cleanup delete a file outside the export) — -a link there is UNAVAILABLE, nothing runs; evidence retention applies the same -rule to its destination under the checkout and is refused, never followed. -Unit G (migration, guidance, release matrix, dogfood; landed 2026-09-25, -UNCOMMITTED). §15 migration: the Interlinked-only boundary reminder -(`e2e-obligation-stop-check.ts`) and `interlinked e2e scaffold` are confined -to the Interlinked checkout (`e2e-boundary.ts isInterlinkedCheckout`, package -name `interlinked-cli`); a host repository never sees the reminder, and the -scaffold refuses there with a pointer to `tests e2e scaffold` unless -`--developer-preset`. Guidance: `docs/project-e2e.md` is the operator guide -(files, schema, commands, reason codes, targets, base comparison, hooks, CI, -proof limits, stability, Stop, recovery); `docs/e2e-testing.md` is scoped to -the self-test lane; the `interlinked-verify` skill and the router carry the -gate/CI/replace/target/boundary rules. Release matrix: `npm run e2e:matrix` -runs every fixture (TS CLI, Python CLI, Rust CLI, TS HTTP, TS browser) -through the common route — toolchain present, valid run accepted, injected -fault rejected, stale input rejected — into `docs/e2e-release-matrix.md`; a -missing toolchain is an explicit gap row, never a skip (Rust is a gap on the -dev Mac), and `.github/workflows/e2e-release-matrix.yml` provisions Python, -Rust and Chromium and fails on gaps. The matrix found a real hole: the -browser fixture's page-only spec passed with broken persistence (PE-20), so -the spec now reads the stored order back through the page and -`playwright.test.ts` N4 pins the faulted run at CASE_FAILED. Dogfood: `npm -run e2e:dogfood` bundles the built CLI into one executable with esbuild (a -case workspace holds ≤128 declared inputs; the live bundle reaches 409 -chunks), declares the public `scratch init | status --json` workflow as -portable contracts (exact stdout, exact `.gitignore` / `.ignore` / -`scratch/README.md` bytes) and proves valid → stale → fault with supervisor -and candidate sha256 recorded; the first contract asserted only the -"created" line and let the fault through until the README file itself was -asserted. Gotcha: `npm run build:e2e` overwrites `dist/` with the e2e build — -run `npm run build` after the e2e lane. Explicit gaps: the MCP/Worker -profile (§10.3) is not built; real-project pilots need user-selected -repositories — until then adoption defaults to advisory. The browser -case window is ORDER-based (`browser-stage.ts orderedWindows`): from a -case's reported start to the next report case's start, `--retries=0` forced. -Playwright's reported `duration` is timeout-slot time, not wall time, so the -old `[start, start + duration]` window ended before the test body and, under -full-suite load, credited no request at all (the 2026-09-25 flake); each -browser case's details now carry its window and the proxy log as offsets. cargo is absent on the dev Mac, so the Rust fixture's compiled route -is asserted only where cargo exists; locally it proves the `unavailable` -path. - -## fail-before-fix (plan 32 item 6, added 2026-10-21) - -`interlinked tests fail-before-fix [--session ] [--strict] [--json]` -(`src/harness/fail-before-fix/`, command `src/commands/tests-fail-before-fix.ts`): -each file the session touched is replayed from `git show HEAD:` through -every applied edit in the collection log since HEAD's commit (any session; raw -`apply_patch` envelopes split per file; archives read when the live log does not -reach back), and the replay must reproduce the current bytes — otherwise the -file is `unavailable` (a code file blocks the run; docs/data/`scratch/` are a -note). The session's changed test files run in the live tree and in a -git-visible copy (`git ls-files -co --exclude-standard`, node_modules linked — -never the gigabytes of ignored bulk) whose code holds the pre-session bytes; -each changed test also runs its pre-session twin there, so "new" means "the old -file did not report this name". Verdicts: `fails-before-fix` (the test's own -check failed on the old code: an assertion, or a plain error whose FIRST stack -frame is the test file — a wait-until or "should have thrown" helper, -`classify.ts failedByOwnCheck`; it pins the change), `passes-before-fix`, -`inconclusive` (a crash, an error thrown by product code or vitest's own -timeout, or a load failure on the old code — a missing new export proves -nothing), `not-passing-now`. Advisory: exit 0, `--strict` exits 1 only -for a new test whose SUBJECT changed (its companion module, or a module it -imports at runtime; a changed sibling it never imports is not its subject) -and that passes on the old code, 2 when no evidence exists. On this repo's -2026-10-22 session the old same-directory rule gave 16 such concerns; the -import rule gives 2, both deliberate preservation tests (the command cannot -tell a preservation test from a weak one). Measured motivation: E66 (56/58 review-regression tests fail -on the real pre-fix code; partial reverts crash), and on the session that built -it the replay reproduced every `src/` file. A call the collection log missed (a -lost post event, or no row at all: the hook client cold-fallback-allows while -the daemon stalls) is filled from the transcript-derived `timeline.jsonl` when -no collection post row carries its `tool_use_id` and its tool_result reports -success; the report counts these as `recovered`. Edits made by scripts stay -unavailable (no log has them). - -## Requirement faults (plan 32 items 7–8, added 2026-10-21) - -`interlinked tests faults run [--corpus ] [--ids a,b] [--json]` -(`src/harness/requirement-faults/`): a corpus of recorded violations -(`.interlinked/requirement-faults.json`, strict v1: the plan 31 fault shape -`id, path, find, replace, rationale` plus `requirement {id, text?, source?}`, -`tests: [...]` and `origin: authored | edit-log | revision`) is applied one -fault at a time to a git-visible copy (anchor exactly once), each fault's test -files run with vitest's JSON reporter, and the bytes are restored. A kill is a -test that passes live and fails by its own check under the fault (the -fail-before-fix rule above); a crash, a product-code error or a load failure is -inconclusive, and the report keeps each inconclusive test's first failure line -(`inconclusiveReasons`; E47a-exec 2026-10-22 lost a `waitFor` helper's real -detection to the old assertion-only rule); an absent anchor is invalid. Output: per fault, and -per requirement the kill fraction killed / (killed + survived) — the plan 32 -test-value score, never a gate. The run is saved to -`.interlinked/test-runs/faults/latest.json`, and each fault's newest outcome -per corpus goes to `outcomes.json` beside it (`requirement-faults/store.ts`: a -complete run drops the corpus's faults it no longer holds, `--ids` only adds), -so running another corpus no longer erases clause evidence. `interlinked tests faults clauses -[--detectors ]` parses each detector header (`check-evidence/clauses.ts`: -FIRES WHEN = k1, each DOES NOT FIRE item of the first sentence = k2…; a -qualifier in parentheses may precede the colon) and joins the stored outcomes by -requirement id `clause::k`: a clause is pinned when every conclusive -fault recorded for it was killed. It is a measured view; it is NOT yet a Check -Evidence Contract dimension (no `EVIDENCE_DIMENSIONS` entry, no pin). Fault -authors must be blind to the tests and to project instructions (this file names -the test that pins each review fix). - -## E2E lane - -`npm run build:e2e && npm run test:e2e` exercises real hook processes and -isolated raw/framed/dual daemons through `src/e2e/fixture.ts`. Fixtures opt into -graph prediction explicitly and require a fresh daemon transport receipt plus -PID ownership. `src/harness/e2e-boundary.ts` defines which product files incur -the advisory Stop obligation. Run the lane from the editing session. - -Use `interlinked e2e scaffold ` to start a test; replace its deliberate -failure with a behavioral assertion. `npm run test:e2e:coverage` measures child -V8 coverage after the source-mapped build. Compare with -`node dist/index.js coverage check --lane e2e --strict --require-measured`. -`E2E_STABILITY=1 npm run test:e2e` includes the 5,000-event stress case. -The real Stryker library probe lives in -`src/harness/mutation/gate-live.integration.test.ts`; daemon mutation -availability is covered in `src/e2e/mutation-gate.e2e.test.ts`. - -See `docs/e2e-testing.md` for collection, baseline transactions and diagnostics. +@AGENTS.md + +## Claude Code specifics + +- Skills load from `.claude/skills/` (installed copy of `skills/`); path-scoped + rules in `.claude/rules/*.md` load when you read or edit a matching file. +- Subagents receive this file and the rules, not your conversation. Brief them + with the goal, what is ruled out, and the files to read; forbid git state + mutations in every subagent prompt. Keep parallel agents to about six, and run + deterministic scans before any agent wave. +- Separate **Verified** (ran this session, output shown) from **Assumed** in every + summary. Report times in America/New_York and counts as numerator / denominator. diff --git a/README.md b/README.md index 6184b9033..4d079f263 100644 --- a/README.md +++ b/README.md @@ -209,6 +209,13 @@ for `setup` or `init` only when you need the login and workspace steps they add. biome, cargo, mypy, …) and 26 structural checks (export surface, import resolution, cycles, blast radius) are eligible after mutating events; capacity-bounded external work can explicitly defer with `NOT CHECKED`. +- **Mutation-grounded test proof.** `interlinked tests prove-kill` checks a + claim like "this test catches that bug" by running it. In disposable copies of + the project, the named tests must pass unmutated and fail, by their own + assertion, with one fault applied. A `killed` verdict writes a receipt bound + to the source, test, config and runtime bytes. `interlinked tests kill-proofs + --verify` reports each receipt as fresh, uncommitted or stale. + vitest only; see `docs/mutation-grounded-test-proof.md`. - **Offline activity log.** Delivered events handled by the running harness append to `.interlinked/activity.jsonl`; this is local evidence, not proof that an unavailable integration observed an event. diff --git a/docs/architecture.md b/docs/architecture.md index 15663674f..f36eb8933 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -407,3 +407,103 @@ remain deferred while the feature is experimental. See ## 10. Relationship to Entire CLI The local-first, hook-driven architecture draws inspiration from Entire CLI. Both projects share the philosophy that AI agent activity should be captured locally, durably, and transparently. The key divergence is scope: Entire captures session transcripts for single-agent, single-repo workflows; Interlinked MCP Server + Interlinked CLI capture activity events for multi-agent, multi-workspace orchestration. + +> Moved from CLAUDE.md on 2026-11-05 + +Append to docs/architecture.md. + +## Dormant MCP-server surface + +**On the "Interlinked MCP Server":** a remote Worker/DO system was the original +center of this project, and ~17 commands still import `src/lib/api-client.ts`. +That surface is **dormant** — no non-test source path calls the MCP tool proxy, +server sync is deliberately unimplemented, and the `active_server` entry in a +working config today points at a LAN mutation-runner broker, not an MCP server. +Do not treat the server as the system of record, and do not describe the CLI as +its companion; the local harness is the product. Leave the dormant code alone +unless the task is specifically about it. + +Source of truth for the CLI is `QuentinCody/interlinked-cli`; current installs run from a linked source checkout. It has a single **required** runtime dependency (`commander`) and zero external dependencies for formatting/output. Two **optionalDependencies** (installed by default; the CLI's core hooks/activity work without them): `typescript` — the JS compiler API the AST-accurate cyclomatic/CRAP gate parses with (the `tsgo` native-port binary has **no importable JS API**, so it can't substitute; TS 7's replacement is an out-of-process gRPC API, stable ~7.1) — and `@typescript/native-preview` (`tsgo`), which accelerates `npm run typecheck`. When `typescript` is absent (`--omit=optional`), the complexity gate degrades to the regex walker and says so loudly (`astComplexityAvailable()`; daemon-startup warning); the `self_import` pre_block check has NO regex fallback and is NOT MEASURED in that state — it reports no findings, and every JS/TS edit carries a `[interlinked:self_import] NOT MEASURED` warning (`checks/self-import-scan.ts`; a pre_block check never blocks on a guess). + +### Relationship to the MCP Server + +The server (`Interlinked MCP Server`) is the remote Worker/DO system. Communication is strictly one-directional: CLI → server via HTTP. Key server endpoints consumed: + +| Endpoint | Purpose | +|----------|---------| +| `POST /api/hooks/activity` | Single event (fire-and-forget from hook script) | +| `POST /api/hooks/activity/batch` | Batch sync of buffered events | +| `POST /api/ui/call` | MCP tool proxy (used by `status`, `activity`, `doctor`, `workspace`) | +| `GET /api/workspaces` | List workspaces (registry endpoint) | +| `POST /register`, `POST /token` | OAuth dynamic client registration and token exchange | + + +### Activity Event Pipeline + +``` +AI Agent hook fires → stdin JSON → hook script (.interlinked/hooks/interlinked-activity.mjs) + ├── Connect to harness socket (if available, 500ms timeout) + │ ├── PreToolUse: harness returns {decision: block/allow} → stdout + │ └── PostToolUse: harness returns {warnings} → stderr + ├── Local write (always, sync, ~0.1ms) → activity.jsonl + sessions/{id}.json + ├── Fire-and-forget POST /api/hooks/activity (if sync_mode != "local", 3s timeout) + └── Batch sync on session end (if sync_mode == "realtime", cursor-based, 100-event chunks) +``` + +Three sync modes: `realtime` (default), `local` (offline-only), `manual` (POST per event, no batch at session end). + + +### Auth Token Resolution + +`resolveAuthToken()` priority: +1. CLI's own `access_token` from `config.local.json` (checks `token_expires_at`) +2. Claude Code credentials fallback from `~/.claude/.credentials.json` → `mcpOAuth`, matched by `mcp_prefix` key prefix or `serverName` containing "interlinked" + +Dev mode bypass: when `server_url` is localhost/127.0.0.1, auth is skipped entirely. + + +## Key source files and config (moved from CLAUDE.md on 2026-11-05) +### Entry Point and Command Registration + +`src/index.ts` registers all commands via `commander`. When invoked with no arguments, `handleImplicitEntry()` from `src/commands/first-run.ts` runs an interactive wizard (TTY) or non-interactive bootstrap (non-TTY). If already configured, it falls through to `statusCommand`. + +### Key Source Files + +| File | Purpose | +|------|---------| +| `src/lib/config.ts` | Two-tier config system: `config.json` (shared/committed) + `config.local.json` (personal/gitignored). `resolveConfig()` merges both and resolves multi-server entries. | +| `src/lib/auth.ts` | Token resolution (CLI token → Claude Code credentials fallback) + OAuth PKCE flow | +| `src/lib/hooks.ts` | Orchestrator: hook script generation + per-client install/uninstall delegation through `CLIENT_INSTALL_REGISTRY`. Generates `.interlinked/hooks/interlinked-activity.mjs` (self-contained, zero imports). | +| `src/lib/hook-installers.ts` | Per-client install/uninstall implementations (Claude Code, GitHub Copilot CLI, Gemini CLI, OpenAI Codex CLI). Each `installXxxHooks` writes a settings file and tags commands with `INTERLINKED_CLIENT=""` so the .mjs runtime can disambiguate clients with overlapping payload shapes. Codex additionally writes `.codex/config.toml` to set `[features] hooks = true` (legacy `codex_hooks` is recognized and auto-migrated; the writer lives at `src/lib/codex-feature-flag.ts`). | +| `src/lib/api-client.ts` | HTTP client wrapping `POST /api/ui/call` for MCP tool proxying | +| `src/lib/local-activity.ts` | JSONL append-only log, session state, sync cursor (byte-offset), merge/dedup | +| `src/lib/activity-utils.ts` | Shared `ActivityEvent` type, `parseDuration()`, `formatActivitySummary()` | +| `src/lib/formatter.ts` | ANSI colors, tables, timestamps — hand-coded, no external deps. Respects `NO_COLOR`/`CI`. | +| `src/lib/output.ts` | Output mode abstraction: `json`, `short`, `normal`, `full` | +| `src/lib/settings.ts` | Client detection and settings file paths for claude/copilot/gemini/codex (registry consumed by `interlinked enable`/`disable`) | +| `src/lib/viz/` | The loopback dashboard (`interlinked viz serve`). `feeds.ts` is the seam: each live lens is ONE `VizFeed` descriptor (route + seed + subscribe) and `server.ts` hosts them all through one generic SSE path — add a lens there, not by copying the plumbing. `agent-roster.ts` folds the activity stream into per-actor presence lanes (a subagent gets its OWN lane keyed `/`, never merged into its parent's counters) and assigns each actor a stable hue — the ONE hashing rule for actor colour, reused by every surface that attributes work to an agent. Dashboard vocabulary is deliberately literal: dot = source file, line = import, lane = agent session, frame = one judged tool call. Feeds: activity, `check-results.jsonl`, `test-events.jsonl` (TESTS), `mutation-manifest.json` (MUTANTS). `reporter-vitest.ts` is the shipped producer for the test feed, published as the `interlinked-cli/viz-reporter` export and duck-typed against vitest so it never imports it. `status-file.ts` publishes `.interlinked/viz.status` so the statusline renders a `◈ viz` link only while a server is actually alive. Every feed renders an honest empty state when its file is absent — nothing is repo-specific. | + +### Activity Event Pipeline (dormant server path, moved from CLAUDE.md) + +``` +AI Agent hook fires → stdin JSON → hook script (.interlinked/hooks/interlinked-activity.mjs) + ├── Connect to harness socket (if available, 500ms timeout) + │ ├── PreToolUse: harness returns {decision: block/allow} → stdout + │ └── PostToolUse: harness returns {warnings} → stderr + ├── Local write (always, sync, ~0.1ms) → activity.jsonl + sessions/{id}.json + ├── Fire-and-forget POST /api/hooks/activity (if sync_mode != "local", 3s timeout) + └── Batch sync on session end (if sync_mode == "realtime", cursor-based, 100-event chunks) +``` + +Three sync modes: `realtime` (default), `local` (offline-only), `manual` (POST per event, no batch at session end). + +### Two-Tier Config System + +| File | Git | Contains | +|------|-----|----------| +| `.interlinked/config.json` | Committed | `server_url`, `default_project`, `version` | +| `.interlinked/config.local.json` | Gitignored | `access_token`, `agent_name`, `workspace_id`, `sync_mode`, `servers` map | + +Multi-server isolation: `config.local.json` has an `active_server` key and `servers` map. Each server entry holds its own `server_url`, `workspace_id`, and `mcp_prefix`. + +Environment variable overrides: `INTERLINKED_SERVER_URL`, `INTERLINKED_ACCESS_TOKEN`, `INTERLINKED_AGENT_NAME`, `INTERLINKED_WORKSPACE_ID`, `INTERLINKED_SYNC_MODE`. diff --git a/docs/decision-metrics.md b/docs/decision-metrics.md index 8f86a11a5..c4ce52c65 100644 --- a/docs/decision-metrics.md +++ b/docs/decision-metrics.md @@ -13,8 +13,9 @@ equivalence, passing tests, or calibrated defect risk. Install ThinkThen and Ollama separately; this feature downloads nothing. The local defaults are `clef-flash:9b` and the full `embeddinggemma-2:740m-bf16`. Qwen3 Embedding -4B remains an explicit comparison model. ThinkThen 0.1.2 was exercised -during implementation. Use an explicit executable path if it is not on PATH. +4B remains an explicit comparison model. The adapter targets the ThinkThen 0.2 +command line (`thinkthen annotate --json`); the 0.1 command line is +not supported. Use an explicit executable path if it is not on PATH. ```bash interlinked metrics decisions init @@ -28,7 +29,8 @@ interlinked metrics decisions labels run.json --output labels.json The output files are immutable: use a new filename for a different observation. Manual commands are explicit inference requests even when automatic hooks are off. -`--plan` asks the installed ThinkThen CLI to print its requests without inference. +`--plan` runs the installed ThinkThen CLI with its offline stub backend: it validates +the question file and each record, and sends no request. `--fresh` performs new inference without replacing the first cached observation. A small illustrative input is in @@ -143,9 +145,17 @@ Runs, per-record inputs/question sets, exact request/response bodies, and native results live under `.interlinked/decision-metrics/runs//`. Files are private. Answer and embedding caches are separate. HTTP credentials are excluded from exchange records. `requestHashes` identify exact wire bodies; `questionKey` is -ThinkThen's separate question-cache key. Batch composition is retained. -ThinkThen retries and its own cache are disabled so this layer owns the deadline, -cache interpretation and research observations. +ThinkThen's identity of the question set. Batch composition is retained. +ThinkThen 0.2 has no cache and no retry option: it repeats a 429 or 5xx reply up to +three times, and every attempt is kept as its own exchange. This layer owns the +deadline, cache interpretation and research observations. `servedModel` is the model +the backend names in its reply, not the model that was requested. + +The ThinkThen child always addresses the local recorder as a System One backend and +holds only a placeholder key; the recorder holds the upstream credential and forwards +to the configured backend. A 0.2 question reads one record field, so a contract that +reads several evidence fields reads one derived field, `interlinked.evidence:`, +that holds those fields as one object. `replay` is offline and changes only interpretation. A cache hit is reproducible replay, not evidence of fresh-run stability. `diff` reports changed probabilities @@ -296,7 +306,10 @@ for executable behavior. This feature adds semantic review evidence. ## Implementation validation and remaining qualification Local implementation checks on October 6 used ThinkThen 0.1.2, Clef Flash 9B -digest `9f411549…`, and Qwen3 Embedding 4B digest `df5bd2e3…`. +digest `9f411549…`, and Qwen3 Embedding 4B digest `df5bd2e3…`. The adapter now +targets ThinkThen 0.2, which quotes the evidence in each question as a JSON string +where 0.1 embedded a JSON object. Observations recorded with 0.1 and with 0.2 +therefore come from different request text; do not pool them. - Clef passed ThinkThen's four-request `check`: zero critical findings, three documented Ollama description-object warnings. Rubrics use plain strings. diff --git a/docs/examples/policies/disk-forensics/README.md b/docs/examples/policies/disk-forensics/README.md index 82837e0f0..3e7578761 100644 --- a/docs/examples/policies/disk-forensics/README.md +++ b/docs/examples/policies/disk-forensics/README.md @@ -55,5 +55,5 @@ session); Sondera's vanilla schema can't express it, so it lives in the (P5 — refuse tampering, refuse unauthorized device access) have no concrete regex; they live in `policy.md` only and are evaluated by the LLM Tier 2 gate. -See `../../../skills/enforce/SKILL.md` §15 for the routing logic and +See `../../../skills/enforce/references/companion-artifacts.md` §15 for the routing logic and `docs/design/interlinked-cedar-extensions.cedarschema` for the schema delta. diff --git a/docs/examples/policies/disk-forensics/skill-disk-forensics.policy.md b/docs/examples/policies/disk-forensics/skill-disk-forensics.policy.md index 0a4f8253b..1e23a179a 100644 --- a/docs/examples/policies/disk-forensics/skill-disk-forensics.policy.md +++ b/docs/examples/policies/disk-forensics/skill-disk-forensics.policy.md @@ -9,7 +9,7 @@ when the active skill is `disk-forensics`. Each entry below carries a structured signal that the model evaluates against the current tool call + recent trajectory. The model returns `{decision, violated_policies[], violation_signature, reasoning}` per the Tier 2 contract — see -`skills/enforce/SKILL.md` §15. +`skills/enforce/references/companion-artifacts.md` §15. --- diff --git a/docs/file-size-and-guard-prediction.md b/docs/file-size-and-guard-prediction.md index b41bc5cc2..1b4f55f1c 100644 --- a/docs/file-size-and-guard-prediction.md +++ b/docs/file-size-and-guard-prediction.md @@ -83,4 +83,4 @@ Native cold fallback runs the same oracle. Self-contained generated hooks cannot load an AST parser without the daemon and report NOT CHECKED. Arbitrary shell mutation, cross-file moves, deleted/changed statements, loops, switches and exception dominance remain outside this oracle. See the canonical -[harness skill](../skills/interlinked-harness/SKILL.md) for receipt recovery guidance. +[harness skill](../skills/interlinked-harness/references/guard-prediction.md) for receipt recovery guidance. diff --git a/docs/finding-review.md b/docs/finding-review.md new file mode 100644 index 000000000..68f4e2192 --- /dev/null +++ b/docs/finding-review.md @@ -0,0 +1,255 @@ +# Advisory review of code findings + +`interlinked metrics decisions findings` supports explicit advisory review of frozen +code evidence. Discovery, preparation, plan inspection and saved-result viewing run +locally. `assess` dispatches selected requests through an optional provider. The +deterministic CLI, hooks and verification remain provider-independent. + +```bash +interlinked metrics decisions findings catalog --json +interlinked metrics decisions findings discover files.json --output candidates.json +interlinked metrics decisions findings prepare cases.json --output bundle.json +interlinked metrics decisions findings plan bundle.json --select parser-1 --output plan.json --json +interlinked metrics decisions findings show plan.json --json +interlinked metrics decisions findings labels plan.json --output labels.json +interlinked metrics decisions findings assess plan.json --dry-run --json +interlinked metrics decisions findings assess plan.json --approve-plan PLAN_ID --output run.json --max-calls 50 +interlinked metrics decisions findings show run.json --json +interlinked metrics decisions findings review run.json --labels labels.json --output review.json +``` + +All commands support `--cwd`, `--json`, `--short`, `--full`, `--output`, and +`--dry-run`. Output artifacts are immutable and created with mode 0600. Use a fresh +output path for each assessment. Preparation, discovery, label creation and review +need no credential. Saved `show`, `labels` and `review` operations invoke no provider. +`show --short` returns one line with artifact identity and entry count. +TypeSafe assessment resolves `TYPESAFE_API_KEY` through the existing client and pins +`jev-1.14.0` by default. `--timeout-ms` bounds each request. Existing v1 saved runs +remain readable and reviewable. Public assessment of a bundle uses the same frozen +plan and authorization path as assessment of a saved plan. + +## Provider and request preview + +`--provider` selects `typesafe`, `ollama`, `liquid`, `openrouter` or `perplexity`. +TypeSafe uses the existing direct HTTP client. Other providers use the installed +ThinkThen adapter and an existing decision configuration supplied with `--config`. +`--url`, `--command`, `--model` and `--model-identity` explicitly override plan inputs. +Local planning reads the selected installed model's digest through Ollama metadata +unless an explicit identity is supplied. This lookup performs no inference or model +download. Local assessment verifies the digest and existing residency policy. + +The immutable plan retains complete selected state, questions, criteria, source and +policy identities, endpoint, declared model identity and adapter checksum. TypeSafe +plans include the exact public HTTP JSON body and its UTF-8 byte count. Other adapters +expose exact semantic inputs and question definitions, with provider wire bytes +marked unavailable until actual exchange receipts are retained. Provider-internal +prompts and tokenization remain outside the public request preview. + +`--select` replans an explicit comma-separated case subset. Omitted cases remain +visible as unassessed scope. For narrower context, prepare a new bundle with explicit +symbols or line ranges, then compare its new state and estimate. Reducing caller, +test or policy evidence can limit a judgment or change its outcome. Oversized requests +fail visibly under `--max-request-bytes`. Every admitted request retains its supplied +context completely. Plans also obey the existing 32 MB artifact read budget. + +The separate `metrics decisions prepare` extractor `semantic-evidence-v4` retains +attached function comments and retrieves functions changed only through those +comments. It binds cyclomatic and cognitive complexity to each declaration’s syntax node, including functions that share a line. File-purpose and full caller context still need explicit source spans or +declared missing evidence in a finding packet. Inspect the frozen state before +judging context completeness. + +## Cost admission and reuse + +The preview's token count uses UTF-8 JSON bytes divided by four. This heuristic +supplies an estimate. TypeSafe's list-price estimate uses $0.042 per million input +tokens with free output tokens. The public API supplies billable input usage after +execution and exposes model listing and System One endpoints. Its published +interface supplies no preflight token count or monetary quote. Plans retain +`exactInputTokens: null` and `quoteUsd: null`. Other cloud prices remain unknown, and +local service-charge estimates exclude hardware costs. +[TypeSafe models and pricing](https://docs.typesafe.ai/models), +[System One API](https://docs.typesafe.ai/api/system-one), +[published OpenAPI](https://api.typesafe.ai/openapi.json). + +Approve the exact saved identity with `--approve-plan PLAN_ID`, or use an explicit +`--estimate-allowance-usd` when every pending request has a known estimate. Unknown-cost +providers require approval of their disclosed frozen plan. `--max-usd` remains an +admission stop. Actual charges can exceed estimates or an in-flight allowance. + +The workflow persists the complete plan and creates an exclusive execution claim +and per-request spend reservation before dispatch. Output paths are also reserved +before inference. Completed receipts replace estimates with observed usage and +known list-price charges. A timeout, failed transport or pending crash reservation +keeps possible charges unknown and stops subsequent paid requests. Orchestrator +retries are zero. Existing adapters receive a zero-retry request, while their +internal retry and call guarantees remain capability-dependent. The plan records +that scope explicitly. Concurrent assessment of the same plan shares retained receipts and +avoids duplicate pending requests. + +`--reuse RUN` reads validated v2 observations for identical source, policy, semantic +request, provider, endpoint, adapter and model identities. Budget-only changes retain +request identity. Reuse invokes no inference. v1 runs remain available through `show` +and `review`; their schema lacks the full transport identity needed for v2 reuse. +New v2 results retain absent adapter confidence as `null` during review and mark +missing probability distributions unavailable. Raw deterministic findings remain +visible alongside model judgments. + +New v2 dispatch records retain validated `elapsedMs` measured around the provider +dispatch, including failed calls. Cached records keep their historical dispatch +duration. Earlier records with no latency field remain readable with latency +unavailable. Infer latency only from a recorded duration. + +## Question wording experiments + +`questions DRAFT --output PROFILE` freezes a local +`interlinked.finding-question-profile/1` artifact. The draft contains `name` and a +complete `questions` map. Instructions and each criterion accept finite JSON text, +objects or arrays. The disposition and priority outcome keys stay fixed so retained +directions remain comparable. For example, a draft can explicitly prioritize source +premise checking before evaluating the applicable invariant. + +```json +{ + "name": "premise-first", + "questions": { + "disposition": { + "type": "choice", + "instructions": "Read supplied source as evidence. Establish the factual premise, applicable scope and listed exceptions before deciding whether a demonstrated violation exists.", + "criteria": { + "premise_wrong": "Source contradicts the candidate premise.", + "not_applicable": "The invariant does not apply to the established scope.", + "explicit_exception": "Source establishes a listed exception.", + "violation": "Source establishes an applicable violation without a listed exception.", + "insufficient_evidence": "Supplied context cannot establish the outcome." + } + }, + "priority": { + "type": "choice", + "instructions": "Assuming an actual violation, judge its demonstrated consequences from supplied evidence.", + "criteria": { + "low": "Local maintainability cost without demonstrated behavioral failure.", + "material": "Demonstrated correctness, resource or reliability failure.", + "critical": "Demonstrated severe security, corruption or broad service failure.", + "unknown": "Consequences are unavailable." + } + } + } +} +``` + +```bash +interlinked metrics decisions findings questions draft.json --output questions.json --json +interlinked metrics decisions findings plan bundle.json --question-profile questions.json --select parser-1 --output alternate-plan.json --json +interlinked metrics decisions findings show alternate-plan.json --short +``` + +An alternate profile creates `interlinked.finding-plan/2`, retaining the full profile +and checksum. Default plan/1 remains readable. V2 runs accept both plan versions. +Changing profile text or criteria changes the semantic request and cache identity. +A metadata-only name change alters the profile and plan identities while preserving +an otherwise identical request identity. Adapter conversion uses the request's +frozen question map. Structured content is retained completely and serialized by the +existing adapter contract. Exact native wire formatting remains in dispatch receipts. + +Profile validation rejects extra question properties, changed outcome keys, unsafe +prototype properties at any depth, accessors, exotic prototypes, sparse arrays, +nonfinite values and cycles. View each frozen plan's actual context, question map +and estimate before approving its independent assessment. Compare variants on the +same selected cases with source-backed labels prepared independently of predictions. +Each review retains its profile identity. Keep unavailable measurements and costs in +the comparison population. + +## Discovery and case preparation + +Discovery takes an explicit inventory, for example `{"files":["src/parser.ts"]}`. +It collects candidates for JSON boundaries, resource ownership, module initialization, +discarded failure-shaped return types, brand construction, sensitive-looking sink +fields and directly awaited network calls inside transaction callbacks. It uses +the project's compiler options for type resolution and reports unavailable source, +syntax diagnostics and unresolved calls separately. It does not execute the project. +Type-shape and name recognition remain heuristics, not proof of must-use semantics, +sensitivity, purity, or ownership. Boolean sink fields are excluded. Custom wrappers, +aliases and indirect effects can require manual source review. + +Review discovery output before preparation: select a bounded cohort, attach relevant +callee bodies, callers, tests and adopted policy, and retain omitted/unresolved counts. +The discovery result's `cases` array is the preparation input shape. A case can also +be authored directly, without a detector candidate: + +```json +{ + "cases": [{ + "id": "parser-1", + "family": "parser_result", + "origin": "direct", + "claim": "The parsed input reaches domain consumption before its shape is established.", + "sources": [{ + "id": "parser", + "file": "src/parser.ts", + "symbol": "parseInput", + "purpose": "Complete parser implementation" + }], + "missing": [] + }] +} +``` + +Sources must stay within the chosen root, including symlink targets. Select a unique +top-level function, class, interface, type or variable using `symbol`, or an explicit +inclusive `startLine`/`endLine` range. Omit both to capture the file. Source `revision` +accepts `HEAD` or a complete Git commit hash; HEAD is resolved before capture. Each +span records its line range, complete source hash, resolved revision and redaction +status. Working-tree evidence is frozen as supplied, not reread during assessment. +Named-symbol selection includes syntactically adjacent leading comments and excludes +separated file headers and sibling trailing comments. Supply explicit file-body, +caller and policy spans for broader purpose or interaction claims. +Discovery supplies `expectedHash`; preparation marks changed source unavailable +instead of silently applying old locations to new code. +Inspect packets: a valid line range can still omit the behavior being reviewed. + +Preparation permits at most 200 cases and 12 source spans per case. File reads are +bounded to 1 MB; spans to 48 KB; combined source evidence to 96 KB per case. Missing +or oversized source remains explicitly unavailable. Known secret signatures are +scrubbed before freezing source and case text; this is not general data classification. +Keep private source and review artifacts in an appropriate ignored directory. + +The catalog provides contracts for test quality, cast soundness, abstraction value, +error handling, parser results, domain states, core effects, initialization, resource +ownership, transaction scope, replay/retry behavior, secret flow, brand ownership, +documentation and API boundaries. Each records its invariant, needed evidence and +permitted exceptions. Core effects, secret flow, brand ownership and retry behavior +require explicit `policy: {"invariant":"...","scope":"...","exceptions":[]}`. +The workflow records that supplied policy; it does not install it or establish its +authority. Reuse existing architecture policy rather than inventing a second registry. + +## Assessment and reference review + +Jev selects one disposition: `premise_wrong`, `not_applicable`, `explicit_exception`, +`violation`, or `insufficient_evidence`. A separate question estimates priority +conditional on an actual violation. A clear disposition does not make conditional +priority actionable. Full distributions, confidence, response model, usage, latency, +question set and request/evidence identities remain in the retained run. + +Declared missing evidence or required policy prevents inference for that case. +Missing credentials, exhausted budgets, service failures and invalid responses stay +unassessed or failed. Assessment exits 2 when any case is unavailable; this reports +measurement completeness and never affects the deterministic code gate. A fully +answered run can still contain uncertain or incorrect judgments. Invalid input exits 1. + +Complete the blind label template from source before inspecting predictions where +possible. Each row needs acceptable dispositions, a rationale and evidence IDs; name +the reviewer accurately. An Astra review is model-reference judgment, not independent +ground truth. Revised labels or evidence should be new artifacts with the reason for +the revision retained. Never erase a previous disagreement by overwriting its run. + +Review accepts categorical agreement and separately reports the same clear direction +with a different rationale. Concern/clear disagreements, uncertainty and unavailable +measurements remain distinct. Confidence percentage differences do not invalidate +directional agreement. Confidence summarizes a distribution; it does not establish +accuracy, and no universal confidence cutoff is imposed. Validate candidate recall +separately using direct source review: good judgments on retrieved candidates cannot +measure missed defects. Before/after pairs and repeated cases are dependent evidence. + +Keep raw deterministic findings visible even when Jev disagrees. Use source-backed +reference review and executable failure evidence to resolve material disagreements. +No model decision in this workflow is a zero-false-positive proof. diff --git a/docs/generated/cli-reference.md b/docs/generated/cli-reference.md index c746f8c69..e6de3a827 100644 --- a/docs/generated/cli-reference.md +++ b/docs/generated/cli-reference.md @@ -64,6 +64,7 @@ Commands: multi-edit [options] [path] Apply N old/new string edits atomically to one or more files. Gate runs once on final content. Ambiguity evaluated after prior edits. mutation Mutation testing: report-score ratchet, local runner measurement, and experimental durable cloud jobs network Diagnose command-network access and prepare host permission profiles + packets Instruction packets: instruction-file rules compiled into Jev-evaluated hook questions (shadow by default; warn/cosign only on a measured holdout) plan Show agent-emitted plans captured from TaskCreate / ExitPlanMode / structured prompts query [options] [source] Bounded query over .interlinked JSONL logs (blocks/checks/recurrences/costs/… or a .jsonl path) recurrence Surface repeating agent behaviors (harness_caught / harness_missed / codebase_existing / tool_failure) @@ -714,7 +715,7 @@ Build or refresh local generated artifact catalogs Options: --full Force full rescan - --incremental Only refresh changed categories + --incremental Request incremental extraction (currently unavailable) --json Machine-readable output -h, --help display help for command ``` @@ -776,31 +777,38 @@ Run the default high-signal external catalog plus diff-safe inline checks. Target can be a local path, GitHub URL, or any git remote URL. Options: - --only Run one named external check (for example: tsc, - biome, oxlint, eslint, semgrep, gitleaks, knip, - docs-check, sca) - --suggestions Also run scored regex heuristics (sql-injection, - perf, quality) - --json Machine-readable output - --details Show per-file details for all findings - --cwd Project root (default: current directory) - --branch Branch, tag, or commit to check (remote repos) - --subdir Only scan a subdirectory (useful for monorepos) - --skip Skip specific checks (comma-separated: - semgrep,knip,complexity,silent_catches,...) - --suppress Suppress a finding: file:check or file:check:reason - --show-suppressions List all active suppressions - --structure Include generic artifact structure checks - --structure-only Run only structure checks - --adoption-gate Fail when adopted categories drop below thresholds - --all-checks Include broad advisory smell checks and dead-code - scans in addition to the default high-signal audit - --dead-code Run Supermodel's cloud dead-code analysis (opt-in; - requires the `supermodel` CLI) - --fp-filter Report per check how many [heuristic] findings the - E18 fp_filter would suppress (also on when - fp_filter.enabled) - -h, --help display help for command + --only Run one named external check (e.g. tsc, biome, + gitleaks, sca). Semgrep requires --only semgrep. + --timeout Whole command deadline in milliseconds (default: no + deadline; 0 disables) + --tool-timeout External analyzer deadline in milliseconds + (default: no deadline; 0 disables) + --gitleaks-scope Secret scan inputs: working-tree includes ignored + files; git-visible excludes them (default: + working-tree) (choices: "working-tree", + "git-visible") + --suggestions Also run scored regex heuristics (sql-injection, + perf, quality) + --json Machine-readable output + --details Show per-file details for all findings + --cwd Project root (default: current directory) + --branch Branch, tag, or commit to check (remote repos) + --subdir Only scan a subdirectory (useful for monorepos) + --skip Skip specific checks (comma-separated: + gitleaks,knip,complexity,silent_catches,...) + --suppress Suppress a finding: file:check or file:check:reason + --show-suppressions List all active suppressions + --structure Include generic artifact structure checks + --structure-only Run only structure checks + --adoption-gate Fail when adopted categories drop below thresholds + --all-checks Include broad advisory smell checks and dead-code + scans in addition to the default high-signal audit + --dead-code Run Supermodel's cloud dead-code analysis (opt-in; + requires the `supermodel` CLI) + --fp-filter Report per check how many [heuristic] findings the + E18 fp_filter would suppress (also on when + fp_filter.enabled) + -h, --help display help for command ``` ## Lint @@ -900,7 +908,7 @@ complexity, and CRAP Options: --cwd Project root (default: current directory) --top Number of function/file token and CRAP - hotspots to show (default: 25) + hotspots to show, 1 to 200 (default: 25) --include-tests Include test/spec functions as advisory token measurements --json Machine-readable output (full per-file + @@ -937,10 +945,15 @@ Commands: score [options] Explained 0–100 quality burden with explicit evidence completeness; no model calls + standards [options] Measure pinned source guidance with + explicit syntax, detector, candidate and + unknown coverage jit [options] [ref] Just-in-time commit risk (Kamei 2013): score one commit or the staged diff and rank it against the repo's own recent commits + policies Inspect, export and evaluate data-only + metric and detector profiles expressions [options] [target] Measure JS/TS expression tokens, callbacks and presentation; advisory findings @@ -1074,9 +1087,98 @@ Options: --json Full measurements, profile, hashes and explicit evidence gaps --short One-line score and evidence status + --full Complete local action evidence and next steps + -h, --help display help for command +``` + +### metrics standards + +``` +Usage: interlinked metrics standards [options] + +Measure pinned source guidance with explicit syntax, detector, candidate and +unknown coverage + +Options: + --profile Guidance profile (dmmulroy-typescript) (default: + "dmmulroy-typescript") + --scope Measured source roles: all or product (default: "all") + --cwd Repository root + --json Complete source-bound report + --short One-line measurement summary + --full Complete structured report with every occurrence and + context gap -h, --help display help for command ``` +### metrics policies + +``` +Usage: interlinked metrics policies [options] [command] + +Inspect, export and evaluate data-only metric and detector profiles + +Options: + -h, --help display help for command + +Commands: + export [options] Export configured metric entries as a shareable + profile without changing settings + inspect [options] Validate known references and inspect an + integrity-checked structural proposal + evaluate [options] [profile] Evaluate a local profile or configured metric + policies with retained raw measurements + help [command] display help for command +``` + +### metrics policies export + +``` +Usage: interlinked metrics policies export [options] + +Export configured metric entries as a shareable profile without changing +settings + +Options: + --cwd Repository root + --json Complete machine-readable evidence + --short Compact summary + --full All policy evidence and limitations + --id Stable profile identity (default: "current-repository") + -h, --help display help for command +``` + +### metrics policies inspect + +``` +Usage: interlinked metrics policies inspect [options] + +Validate known references and inspect an integrity-checked structural proposal + +Options: + --cwd Repository root + --json Complete machine-readable evidence + --short Compact summary + --full All policy evidence and limitations + -h, --help display help for command +``` + +### metrics policies evaluate + +``` +Usage: interlinked metrics policies evaluate [options] [profile] + +Evaluate a local profile or configured metric policies with retained raw +measurements + +Options: + --cwd Repository root + --json Complete machine-readable evidence + --short Compact summary + --full All policy evidence and limitations + -h, --help display help for command +``` + ### metrics diagnostics ``` @@ -1088,8 +1190,10 @@ Options: --cwd Repository root --json Machine-readable result --short Compact summary - --profile js-ts (default) or python; separate - counting contracts + --profile auto (default: by product-file languages: + js-ts, python, or one report per language + for a mixed tree), js-ts, or python; + separate counting contracts -h, --help display help for command Commands: @@ -1365,6 +1469,8 @@ Commands: relations Experimental invariant, coupling, and before/after judgments over pinned graph evidence + findings Experimental advisory review of frozen code + evidence; never gates edits init [options] Write a disabled, local-first decision configuration catalog [options] Show versioned metric contracts and the @@ -1401,6 +1507,223 @@ Commands: help [command] display help for command ``` +### metrics decisions findings + +``` +Usage: interlinked metrics decisions findings [options] [command] + +Experimental advisory review of frozen code evidence; never gates edits + +Options: + -h, --help display help for command + +Commands: + catalog [options] Show explicit semantic finding contracts + discover [options] Collect advisory parser, resource, + initialization and typed discarded-outcome + candidates from an explicit files array + prepare [options] Freeze a JSON case plan into bounded, redacted + source evidence locally + questions [options] Freeze versioned alternative question + instructions and criteria locally + plan [options] Preview selected frozen requests, exact semantic + context, provider identity and labeled cost + estimates + assess [options] Assess an explicitly approved or + estimate-authorized frozen plan through an + optional provider + show [options] View a saved bundle, plan or assessment locally + without inference + labels [options] Create a blind reviewer template from an + evidence bundle + review [options] Compare a retained run against reviewer labels + by direction + help [command] display help for command +``` + +### metrics decisions findings discover + +``` +Usage: interlinked metrics decisions findings discover [options] + +Collect advisory parser, resource, initialization and typed discarded-outcome +candidates from an explicit files array + +Options: + --cwd Project root + --output Write immutable JSON; required for assessment + --dry-run Prepare output without inference or writes + --json Machine-readable output + --short One-line summary + --full Full retained evidence + -h, --help display help for command +``` + +### metrics decisions findings prepare + +``` +Usage: interlinked metrics decisions findings prepare [options] + +Freeze a JSON case plan into bounded, redacted source evidence locally + +Options: + --cwd Project root + --output Write immutable JSON; required for assessment + --dry-run Prepare output without inference or writes + --json Machine-readable output + --short One-line summary + --full Full retained evidence + -h, --help display help for command +``` + +### metrics decisions findings questions + +``` +Usage: interlinked metrics decisions findings questions [options] + +Freeze versioned alternative question instructions and criteria locally + +Options: + --cwd Project root + --output Write immutable JSON; required for assessment + --dry-run Prepare output without inference or writes + --json Machine-readable output + --short One-line summary + --full Full retained evidence + -h, --help display help for command +``` + +### metrics decisions findings plan + +``` +Usage: interlinked metrics decisions findings plan [options] + +Preview selected frozen requests, exact semantic context, provider identity and +labeled cost estimates + +Options: + --cwd Project root + --output Write immutable JSON; required for assessment + --dry-run Prepare output without inference or writes + --json Machine-readable output + --short One-line summary + --full Full retained evidence + --provider typesafe (default), ollama, liquid, openrouter or + perplexity + --config Existing decision adapter configuration + --model Pinned provider model identity (TypeSafe default + jev-1.14.0) + --model-identity Explicit model identity; local model digest is + otherwise read without inference + --url Provider API base URL + --command Existing ThinkThen adapter executable + --select Explicit comma-separated case IDs; omitted cases + remain unassessed + --question-profile Immutable alternate question profile; exact text + and criteria are bound to request identity + --max-request-bytes Reject oversized requests visibly; never truncate + context + --timeout-ms Per-request deadline, 1..60000 (default 10000) + -h, --help display help for command +``` + +### metrics decisions findings assess + +``` +Usage: interlinked metrics decisions findings assess [options] + +Assess an explicitly approved or estimate-authorized frozen plan through an +optional provider + +Options: + --cwd Project root + --output Write immutable JSON; required for assessment + --dry-run Prepare output without inference or writes + --json Machine-readable output + --short One-line summary + --full Full retained evidence + --provider typesafe (default), ollama, liquid, openrouter + or perplexity + --config Existing decision adapter configuration + --model Pinned provider model identity (TypeSafe + default jev-1.14.0) + --model-identity Explicit model identity; local model digest is + otherwise read without inference + --url Provider API base URL + --command Existing ThinkThen adapter executable + --select Explicit comma-separated case IDs; omitted + cases remain unassessed + --question-profile Immutable alternate question profile; exact + text and criteria are bound to request identity + --max-request-bytes Reject oversized requests visibly; never + truncate context + --timeout-ms Per-request deadline, 1..60000 (default 10000) + --max-calls Request admission budget, 0..200 (default 50); + external adapter retries remain + capability-dependent + --max-usd Admission spend stop, 0..10 (default 0.25); + estimates cannot guarantee a monetary ceiling + --approve-plan Authorize the exact frozen plan identity, + including its disclosed unknown costs + --estimate-allowance-usd Explicitly accept estimated-cost admission, + 0..10; no provider quote or hard ceiling + --reuse Reuse validated matching observations from a + saved v2 run without inference + -h, --help display help for command +``` + +### metrics decisions findings show + +``` +Usage: interlinked metrics decisions findings show [options] + +View a saved bundle, plan or assessment locally without inference + +Options: + --cwd Project root + --output Write immutable JSON; required for assessment + --dry-run Prepare output without inference or writes + --json Machine-readable output + --short One-line summary + --full Full retained evidence + -h, --help display help for command +``` + +### metrics decisions findings labels + +``` +Usage: interlinked metrics decisions findings labels [options] + +Create a blind reviewer template from an evidence bundle + +Options: + --cwd Project root + --output Write immutable JSON; required for assessment + --dry-run Prepare output without inference or writes + --json Machine-readable output + --short One-line summary + --full Full retained evidence + -h, --help display help for command +``` + +### metrics decisions findings review + +``` +Usage: interlinked metrics decisions findings review [options] + +Compare a retained run against reviewer labels by direction + +Options: + --cwd Project root + --output Write immutable JSON; required for assessment + --dry-run Prepare output without inference or writes + --json Machine-readable output + --short One-line summary + --full Full retained evidence + --labels Complete source-backed reviewer labels + -h, --help display help for command +``` + ### metrics decisions init ``` @@ -2385,45 +2708,67 @@ Usage: interlinked tests [options] [command] Explain and run affected tests with bounded scheduling and snapshot validation Options: - -h, --help display help for command + -h, --help display help for command Commands: - contracts Inspect provenance or explicitly execute - portable behavioral contracts - e2e Project-aware end-to-end scenarios: declared - policy, supervised runs, receipts and one - qualification verdict - trace [options] Explain one verification request (the newest - push by default) from the stage ledger: - owners, phase costs, the wall-clock wait, the - handoff fallback cause, and every check that - ran fresh or produced no verdict - opacity [options] Rank the modules whose unhashed reads or - unresolved imports make test results - non-reusable, by the recorded execution time - of the tests that reach them, with one import - chain each - review [options] [paths...] Review changed source, behavioral obligations - and bounded simplification candidates without - running tests - fail-before-fix [options] Run the tests a session changed against that - session's pre-change code, rebuilt from the - harness edit log; advisory - faults Requirement faults: recorded violations of - stated requirements, run against the tests - that must notice them - readiness [options] Inspect test prerequisites without - installing; Python also reports approved - provisioning argv - suite [options] Run a bounded project suite: typescript, - javascript, python, rust or go - plan [options] [paths...] Explain the union of affected tests without - running assertions - run [options] [paths...] Run pending and affected tests; retain newer - edits for another run - status [options] [paths...] Show pending requests and the last observed - test job - help [command] display help for command + contracts Inspect provenance or explicitly + execute portable behavioral contracts + e2e Project-aware end-to-end scenarios: + declared policy, supervised runs, + receipts and one qualification verdict + trace [options] Explain one verification request (the + newest push by default) from the stage + ledger: owners, phase costs, the + wall-clock wait, the handoff fallback + cause, and every check that ran fresh + or produced no verdict + opacity [options] Rank the modules whose unhashed reads + or unresolved imports make test results + non-reusable, by the recorded execution + time of the tests that reach them, with + one import chain each + review [options] [paths...] Review changed source, behavioral + obligations and bounded simplification + candidates without running tests + fail-before-fix [options] Run the tests a session changed against + that session's pre-change code, rebuilt + from the harness edit log; advisory + faults Requirement faults: recorded violations + of stated requirements, run against the + tests that must notice them + prove-kill [options] Prove that the named tests pass now and + fail under ONE mutant: a manifest + survivor (--mutant) or an explicit + fault (--file/--find/--replace); or + under EVERY manifest survivor of --file + (--all-survivors, one shared baseline). + A killed proof writes a receipt bound + to the source, test and runtime bytes. + edit-protection [options] [tests...] Re-prove every kill a kill-proof + receipt recorded for each edited test + file against its CURRENT bytes: kept, + lost, retired (the source no longer + holds the mutant) or undecided. A lost + kill in a source this change did not + touch, that no other test still kills, + is a finding (saturation testing's + requirement-change path). + kill-proofs [options] List recorded kill proofs. With + --verify, check each against the bytes + and runtime on disk. + readiness [options] Inspect test prerequisites without + installing; Python also reports + approved provisioning argv + suite [options] Run a bounded project suite: + typescript, javascript, python, rust or + go + plan [options] [paths...] Explain the union of affected tests + without running assertions + run [options] [paths...] Run pending and affected tests; retain + newer edits for another run + status [options] [paths...] Show pending requests and the last + observed test job + help [command] display help for command ``` ### tests plan @@ -2731,6 +3076,8 @@ Options: --reason Why this state is approved --lockfile Snapshot a specific file only (e.g. package-lock.json) --cwd Project root + --dir Hash another directory's files into this project's + allowlist, keyed by path -h, --help display help for command ``` diff --git a/docs/harness.md b/docs/harness.md index 0c41bdad4..6cc82e1bf 100644 --- a/docs/harness.md +++ b/docs/harness.md @@ -173,6 +173,24 @@ launch TypeScript, Biome, or another external tool. - Lint checks — need full project context - Results use each provider's model-visible post-tool channel when one exists; Copilot remains stderr-only - Capacity or tool unavailability produces an explicit `NOT CHECKED` no-verdict result, never a clean result +- Failed calls take the same path. Claude Code reports a failed Bash call only as + `PostToolUseFailure` (no `PostToolUse`), so the installer subscribes that event with + the `PostToolUse` matcher. The daemon reads `exit_code` from the `Exit code N` first + line of the error text, and a test, typecheck or lint command gets an + `outcome: "fail"` row in `tests.jsonl`. If one call arrives both as a folded + `PostToolUse` and as `PostToolUseFailure`, the daemon keeps the first and drops the + second before any ledger, check or error-history work (`claimToolCompletion` in + `src/harness/event-dedup.ts`) +- The shell's exit status is a check's verdict only when it belongs to the check + (`isOutcomeAttributable` in `src/harness/test-outcome-evidence.ts`). After a pipe or a + later command (`vitest run … | tail`, `tsc …; echo done`) it is another command's + status. A test run is then decided by the runner's own summary line, and with no + summary the result is unknown in both directions. The `tests.jsonl` row + (`basis`, `exit_attributable`), the per-file TDD cycle, the red/green state for the + Stop `unresolved-red` nudge and the deferred-coverage discharge all use this one + rule. `set -o pipefail` before the check makes a piped status count again. A + typecheck, build or lint run with a hidden status returns an + `[interlinked:check-evidence]` warning **Why not PreToolUse for type checking?** Running `tsc` on PreToolUse would mean: @@ -328,56 +346,89 @@ The rules are loaded at harness startup and hot-reloaded when files change. Buil ## File Reference -**Core:** +> Moved from CLAUDE.md on 2026-11-05 + +Replaces docs/harness.md lines 329-380 (the "## File Reference" section up to the blank line before "## Grep Acceleration"), whose paths use the dead `cli/src/...` prefix (27 occurrences, lines 334-368 plus generated-docs rows). + +**Harness source files (core):** | File | Purpose | |------|---------| -| `cli/src/harness/types.ts` | All type definitions: events, decisions, rules, cohort, reservations, config | -| `cli/src/harness/server.ts` | Node.js Unix socket server — the main entry point (`node:net`) | -| `cli/src/harness/evaluator.ts` | Guard evaluation — PreToolUse blocking + PostToolUse feedback | -| `cli/src/harness/rules-loader.ts` | Rule loading: 124 built-in + team JSON + personal overrides + hot-reload | -| `cli/src/harness/session-state.ts` | Per-session trajectory tracking (files, commands, tool counts) | -| `cli/src/harness/cohort.ts` | Agent cohort manager (join/leave/lost detection, file tracking) | -| `cli/src/harness/reservations.ts` | Auto file reservation (optimistic lock, 30s release, server sync) | -| `cli/src/harness/quality-checks.ts` | PostToolUse runners: 34 checks across 8+ languages | -| `cli/src/harness/server-bridge.ts` | Server coordination: reservation sync, guard event reporting | -| `cli/src/harness/trigram-index.ts` | Trigram search index: build, query, serialize, dirty layer, incremental git update | -| `cli/src/harness/regex-trigrams.ts` | Regex → trigram decomposition, ripgrep command parsing, shell tokenizer | -| `cli/src/harness/grep-accelerator.ts` | PreToolUse grep acceleration: intercept search tools, query index, block-and-answer | - -**Analysis subsystems:** +| `src/harness/types.ts` | All type definitions | +| `src/harness/server.ts` | Node.js Unix socket server (main entry, `node:net`) | +| `src/harness/evaluator.ts` | Guard evaluation: PreToolUse blocking + PostToolUse feedback | +| `src/harness/rules-loader.ts` | 124 built-in rules + JSON config + hot-reload | +| `src/harness/session-state.ts` | Per-session trajectory tracking | +| `src/harness/cohort.ts` | Agent cohort manager | +| `src/harness/reservations.ts` | Auto file reservation with optimistic locking | +| `src/harness/quality-checks.ts` | PostToolUse: 34 checks across 8+ languages (tsc, biome, cargo, rustfmt, mypy, ruff, etc.) | +| `src/harness/quality-checks/tsc-scheduler.ts` | E21 tsc scheduler, `quality_checks.typescript.scheduler` (DEFAULT OFF, local only, calibrated on this repo alone): defers a predicted-clean synchronous tsc run; drained at the next kept run, Stop, SubagentStop, SessionEnd and commit (`server/tsc-scheduler-phase.ts`); errors and unavailable checks survive restart; rows carry `scheduler` (`query checks --where scheduler.deferred=true`) | +| `src/harness/server-bridge.ts` | Server coordination: reservation sync, guard event reporting | +| `src/harness/trigram-index.ts` | Trigram search index: build, query, serialize, dirty layer | +| `src/harness/regex-trigrams.ts` | Regex → trigram decomposition, rg command parsing | +| `src/harness/grep-accelerator.ts` | PreToolUse grep acceleration: index query + block-and-answer | +| `src/harness/large-file-policy.ts` | Per-file line cap: threshold, `isCappableFile` predicate, baseline loader, ratchet verdict | +| `src/harness/mutation/` | Per-edit mutation gate (spec `docs/design/per-edit-cloud-mutation-testing.md`): stable mutant identity, `mutation-manifest.json` + receipts, survivor-diff invariant, ChangeSet overlays, cloud runner client. Config `per_edit_mutation` (default off; `budget_ms` caps the runner round-trip). Engine scaffolding: root `stryker.conf.json` (MUST ignore `.interlinked/` — Stryker's tree-copy crashes on the harness socket) + `vitest.stryker.config.ts`. Live engine test: `npm run test:integration -- gate-live`. The older per-file score ratchet (`mutation-gate.ts`, `interlinked mutation check`) is a separate, coarser system. | +| `src/harness/shadow/protocol/` | Public client contract and local reference implementation for remote shadow execution: strict parsers, byte grammars, overlays, changeset identity, provenance, and binding comparison. Cross-repository fixtures and schema metadata live in `protocol/shadow-v1/`; see its README for the public/private boundary and vendor workflow. After changing contract source or corpus data, regenerate the digest with `npx tsx scripts/gen-shadow-contract-digest.mts`; use `--check` to verify freshness. Regenerate schemas with `npx tsx scripts/gen-shadow-schema.mts` when contract shapes change. | +| `src/harness/check-inventory.ts` | **Single source of truth for "how many checks."** `getCheckInventory()` derives per-family counts (inline `CHECK_REGISTRY` / sequence / structural / tool-quality / suggestion / behavioral — disjoint) live from each registry; pinned by `check-inventory.test.ts`; surfaced by `interlinked harness checks`. `GENERIC_CHECK_META` is the doc-view of a subset of the inline family, NOT a count — never sum it. Guard rules (`BUILTIN_RULES`) are a separate primitive, pinned by docs-freshness. | +| `src/harness/evaluator/complexity-pulse.ts` | Ambient per-edit cyclomatic telemetry: the strict gate's observer stashes its already-paid before/after parses at PreToolUse; PostToolUse emits one `[interlinked:cyclomatic]` line per edited code file (ΣCC + max + per-fn Δ; absolutes on stash miss). Same population as the gate (cappable files). Isolated hook test: `npm run build:e2e && npm run test:e2e -- pulse`. | +| `src/harness/agent-metrics.ts` | Per-subagent cost + activity, summed off the agent's OWN transcript (2026-08-08): tokens (input/output/cache read/creation), models, per-tool call counts, `tool_use_ids`, turn counts, duration, thinking-block counts. The stop payload carries NO usage (0/1507 measured), so this is the only capture point. `tool_use_ids` is the attribution key — a subagent's tool calls reach the guard under the PARENT session id with no agent marker, so joining activity.jsonl rows back to their agent requires this list. | +| `src/harness/server/agent-event-context.ts` | Label + metrics resolution for one agent event. `SubagentStart` carries `agent_type`, `SubagentStop` usually does not (1439/1507 unlabeled), so the daemon remembers the start label and re-attaches it; `agent_type_source` records payload-vs-remembered. Empty-string labels normalize to null. | +| `src/harness/background-task-log.ts` | Background-agent roster capture (2026-08-08, found by the census): Stop/SubagentStop carry `background_tasks: [{id,type,status,description,agent_type}]`. A background agent fires NO per-agent hook — its result reaches the parent over a queue notification — so this array is the only report that it exists. One row per observed STATE CHANGE to `.interlinked/background-tasks.jsonl`; honors `dry_run`. | +| `src/harness/payload-key-census.ts` | **The "are we capturing everything" backstop.** Every hook invocation diffs the raw runner payload's top-level keys against `CONSUMED_PAYLOAD_KEYS` and records the leftovers — with a TYPE + MEMBER-NAME shape, never values — to `.interlinked/payload-keys.json`. The conversion to the harness event copies a fixed whitelist, so a field a runner starts sending is otherwise dropped in silence; this is how the subagent token/label gaps stayed invisible. When you add a reader for a field, add it to `CONSUMED_PAYLOAD_KEYS` in the same change. | +| `src/harness/server/agent-event-capture.ts` | Subagent/parallel-agent result capture (2026-07): SubagentStart/SubagentStop/TaskCompleted → `agent_event` records in collection.jsonl. The final message comes from the hook payload or a bounded tail-read of the agent's transcript (scrubbed, 64KB cap) — SubagentStop is the ONLY hook carrying a background agent's result (the queue-notification delivery fires no hook). Also one-shot drains the agent's own transcript into timeline.jsonl (`agent_id`-attributed) with a 750ms re-drain covering the runner's post-Stop flush race. Surfaced by `interlinked logs --type subagent_stop`. | + + +**Harness source files (analysis):** | File | Purpose | |------|---------| -| `cli/src/harness/structural-checks.ts` | 26 dependency-aware checks (export surface, imports, cycles, blast radius) | -| `cli/src/harness/generic-checks.ts` | 50+ inline code analysis checks (SQL injection, complexity, async/await, etc.) | -| `cli/src/harness/project-graph.ts` | Multi-project file dependency graph with caching | -| `cli/src/harness/impact-analysis.ts` | Cross-file dependency tracking and breaking change detection | -| `cli/src/harness/change-propagation.ts` | Side-effect tracking across edits | -| `cli/src/harness/error-history.ts` | Error pattern memory with optional embeddings support | -| `cli/src/harness/language-profiles.ts` | Language-specific checks for 12+ languages | -| `cli/src/harness/taint-tracker.ts` | Sensitivity classification and flow tracking | -| `cli/src/harness/pattern-detector.ts` | Cross-cutting pattern detection | -| `cli/src/harness/suggestion-scorer.ts` | Weighted finding scoring and ranking | -| `cli/src/harness/suppressions.ts` | Inline suppression directives | -| `cli/src/harness/check-metadata.ts` | Structural check metadata for docs generation | -| `cli/src/harness/check-engine/` | Unified caching/memoization layer for checks | - -**CLI commands and config:** +| `src/harness/structural-checks.ts` | 25 dependency-aware checks (export surface, import resolution, cycles, blast radius) | +| `src/harness/checks/.ts` | 50+ inline code analysis checks split by family (SQL injection, complexity, async/await, PII, secrets, etc.). New detectors go here. | +| `src/harness/generic-checks.ts` | Compatibility barrel re-exporting from `checks/.ts`. Do not add new detectors here; import from `checks/.js` directly. | +| ~~`src/harness/check-registry.ts`~~ | **Removed 2026-08-17** — the flat-file compatibility shim had zero importers. Import from `check-registry/index.js`. | + +| `src/harness/project-graph.ts` | Multi-project file dependency graph with caching | +| `src/harness/impact-analysis.ts` | Cross-file dependency tracking and breaking change detection | +| `src/harness/change-propagation.ts` | Side-effect tracking across edits | +| `src/harness/error-history.ts` | Error pattern memory with optional embeddings support | +| `src/harness/language-profiles.ts` | Language-specific checks for 12+ languages | +| `src/harness/taint-tracker.ts` | Sensitivity and flow tracking. Step budgets bind the calling actor's own count (`actorStepCount`, `actor_tool_calls`, keyed by `actorKeyOf`), not the sum of sibling calls. Known subagents use the configured limit at their own sensitivity; unknown actors retain the session limit. Per-actor lineage (`taint-lineage.ts`, H3 B3+B5) raises the reader and its ancestors, including for the optional model-backed content scanner. New children inherit their parent's current sensitivity; already-running clean siblings retain theirs. The session level remains the root/max for display. Every network decision uses the acting actor's level. Files written above Public carry their level (`taint-file-lineage.ts`, bounded 2048, snapshot `taint_files`) and ratchet later readers before network checks, including read-and-send commands. Legacy snapshots without `taint_actors` hydrate at the stored session level. `harness taint status` lists actor levels; operator-only `harness taint clear` lowers every actor, or `--actor ` one on a live daemon. Exhausted budgets advise handoff, not a commit the guard would block. | +| `src/harness/pattern-detector.ts` | Cross-cutting pattern detection | +| `src/harness/suggestion-scorer.ts` | Weighted finding scoring and ranking | +| `src/harness/registry-parity.ts` | Configurable drift detector for paired registries / exception lists. Reads `.interlinked/registry-parity.json`; runs as part of `interlinked verify` and surfaces drift in both streaming and `--json` output. | +| `src/harness/suppressions.ts` | Inline suppression directives | +| `src/harness/check-metadata.ts` | Structural check metadata for docs generation | +| `src/harness/check-engine/` | Unified caching/memoization layer for checks | + +**Harness source files (artifact structure):** | File | Purpose | |------|---------| -| `cli/src/commands/harness.ts` | CLI commands: `interlinked harness start/stop/status/test` | -| `cli/src/commands/index-cmd.ts` | CLI commands: `interlinked index build/update/status/query` | -| `cli/scripts/generate-docs.ts` | Auto-generates reference docs from source code | -| `.interlinked/guard-rules.json` | Default team-shared guard rules configuration | -| `.interlinked/index/trigram.bin` | Binary trigram index (generated by `interlinked index build`) | -| `.interlinked/index/meta.json` | Index metadata: file count, trigram count, base commit, build time | +| `src/harness/structure/types.ts` | All structure type definitions (determinism, provenance, artifact kinds, graph shapes, config schemas) | +| `src/harness/structure/schema-validator.ts` | Validates `structure.json` and all 9 artifact file schemas (unknown-key rejection) | +| `src/harness/structure/structure-loader.ts` | Loads `interlinked/structure.json`, resolves mode defaults, loads artifact files | +| `src/harness/structure/artifact-graph.ts` | ArtifactGraph: node/edge CRUD, companion traversal, incremental refresh, serialization | +| `src/harness/structure/cache-manager.ts` | Read/write `.interlinked/structure-cache/` files, staleness detection, manifest hashing | +| `src/harness/structure/structure-checks.ts` | PostToolUse entry point: graph build, incremental refresh, declared artifact layering, rule evaluation | +| `src/harness/structure/structure-formatter.ts` | Human-readable `[interlinked:structure]` warnings, verify JSON output builder | +| `src/harness/structure/adoption.ts` | Coverage calculation per category (0.0–1.0) | +| `src/harness/structure/baseline.ts` | Baseline suppression matching, SHA-256 context hashing | +| `src/harness/structure/extractors/` | 7 generic extractors: module, package, env, config, test, docs, examples | +| `src/harness/structure/rules/` | 7 built-in rule families: public symbol companions, public symbol test-case, env/config key companions, layer/package boundaries, glossary residue | + + +**Stop-event reflection helpers** (formatters returning `string | null`, called from the `server.ts` Stop / SessionEnd branch; never block — all stderr warnings only): +| File | Purpose | +|------|---------| +| `src/harness/commit-cadence.ts` | Stop nudge when too many uncommitted code-file edits this session + mid-session backstop. Escalates wording by session token band. Says "Don't push." | +| `src/harness/verification-stop-checks.ts` | Three nudges: unverified code (no tsc/test/lint/build), UI not interacted (no dev-server / browser MCP), stubs introduced (TODO/FIXME/disabled-test/throw-not-impl). Signal capture lives in `session-state.ts` (trajectory signals) and `evaluator/post-tool.ts` (content scan). See `docs/design/stop-event-checks.md` for the Tier 2 / 3 backlog. | + **Auto-generated reference docs** (run `npm run docs` to regenerate): | File | Contents | |------|----------| -| `cli/docs/generated/guard-rules.md` | All 124 built-in guard rules by category | -| `cli/docs/generated/quality-checks.md` | All 34 PostToolUse quality checks | -| `cli/docs/generated/structural-checks.md` | All 26 structural checks by tier | -| `cli/docs/generated/configuration.md` | Default config: diff-aware filtering + structural check settings | +| `docs/generated/guard-rules.md` | All 124 built-in guard rules by category | +| `docs/generated/quality-checks.md` | All 34 PostToolUse quality checks | +| `docs/generated/structural-checks.md` | All 26 structural checks by tier | +| `docs/generated/configuration.md` | Default config: diff-aware filtering + structural check settings | ## Grep Acceleration — Trigram Search Index @@ -924,3 +975,85 @@ Simulated `harness test` events (`dry_run`) make no call and write no row. - **Auto-checkpointing** — harness triggers git checkpoints before destructive operations or after N tool calls - **Server-pushed team rules** — workspace owners configure rules via dashboard, harness pulls them - **Agent loop enforcement** — detect when agent hasn't called `wait_for_work` in 5+ minutes, alert human + +> Moved from CLAUDE.md on 2026-11-05 + +Append to docs/harness.md. Editor note: docs/harness.md:396 ("On every Grep/rg call ...") describes interception as unconditional and never says the index is opt-in; the paragraph below (since 2026-09-10) says it is OPT-IN and `interlinked enable` no longer builds it. Reconcile when applying. + +## Testing and guard flow + +## Testing + +```bash +npx vitest run # Full suite (~20k tests; count drifts — don't pin it here) +npx vitest run src/harness/__tests__/evaluator.test.ts # Harness guard tests +npx vitest run src/commands/__tests__/cli-bugs.test.ts # CLI regression tests +``` + +Test files: +- `src/harness/__tests__/evaluator.test.ts` — destructive command blocking, sleep detection, protected files, curl-to-MCP, auto-reservations, safe command allowlist +- `src/harness/__tests__/trigram-index.test.ts` — trigram index, regex decomposition, grep accelerator +- `src/harness/__tests__/structural-checks-extended.test.ts` — structural check validation +- `src/harness/__tests__/generic-checks-extended.test.ts` — generic code analysis checks +- `src/harness/__tests__/impact-analysis.test.ts` — cross-file impact analysis +- `src/harness/__tests__/project-graph.test.ts` — project dependency graph +- `src/harness/__tests__/taint-tracker.test.ts` — sensitivity classification +- `src/harness/__tests__/diff-aware-checks.integration.test.ts` — diff-aware filtering +- `src/harness/__tests__/command-guard-parity.test.ts` — guard rule parity with inline fallback +- `src/harness/__tests__/docs-freshness.test.ts` — validates generated docs match source +- `src/harness/__tests__/hook-conflicts.test.ts` — hook installation conflict detection +- `src/commands/__tests__/cli-bugs.test.ts` — regression tests for numbered bugs (Bug 4, 5, 10, 14, 18, 21, 23, 24, 26) +- `src/commands/__tests__/activity-workspace-regressions.test.ts` — activity feed API contract and workspace switch tests + +Tests heavily mock the file system and network. The test infrastructure uses vitest with `vi.mock()` for module-level mocking. + +Manual harness testing via Unix socket: +```bash +node dist/harness/server.js --verbose & +echo '{"hook_event":"PreToolUse","session_id":"t","agent_source":"claude","tool_name":"Bash","tool_input":{"command":"rm -rf /"},"timestamp":"2026-03-17T00:00:00Z"}' | nc -U .interlinked/harness.sock +# Expected: {"decision":"block","reason":"BLOCKED: Recursive deletion..."} +``` + + +**How guard evaluation works:** +1. Hook script connects to `/.interlinked/harness.sock` on PreToolUse +2. Harness evaluates event against rules + reservations + trajectory state +3. For Grep/Bash-grep calls: queries trigram index for candidate files, runs rg on candidates +4. Returns `{decision: "block"|"allow", reason?, warnings?}` +5. If blocked: hook outputs decision to stdout, agent sees reason +6. If warnings: hook writes to stderr, agent sees on next turn +7. If harness unavailable: inline fallback patterns (sleep, rm -rf, force push, DROP) + + +**Grep acceleration (OPT-IN, off unless an index exists — 2026-09-10):** +- Build index: `interlinked index build` (0.1-10s depending on repo size). + `interlinked enable` no longer builds it: the in-process build walks every + tracked file and ran a 50k-file prose corpus out of heap mid-enable, leaving + hooks installed but no daemon. Nothing on the hook path needs the index. +- Harness loads an existing index on startup, refreshes incrementally on each SessionStart +- Intercepts Grep tool calls AND Bash rg/grep commands (including from subagents) +- Queries index in ~10-50μs, narrows to candidate files, runs rg on candidates only +- Agent sees results via block-and-answer pattern (formatted like normal grep output) +- Dirty layer tracks file edits in-memory so agent's own writes are immediately searchable + + +## Project root resolution + +(Bullet from CLAUDE.md "Important patterns".) + +- The hook finds its project by walking up from the TOOL CALL's cwd (`lib/interlinked-root.ts findRepoRoot`) to the + nearest `.interlinked/` that holds a project marker (`config.json`, `guard-rules.json`, `harness.pid`) or a + socket; a folder holding only hook-written files (payload census, receipts, prediction state) is passed. Before + 2026-10-22 the nearest `.interlinked/` won, and the payload census wrote `/.interlinked/` for any folder + the session had `cd`-ed into — so every later call from below that folder found no socket and was cold-allowed + without the daemon (one session: 135 of 734 calls, 47 of them edits; the transcript says "daemon socket not + found; evaluator skipped"). The census now writes only under the project root, and `guard-prediction.ts` keys + its state, receipts and file keys to the same root (keyed to the cwd, it also skipped every edit outside the + session's current folder as "outside the project"). Scale on 2026-10-22: 663 of the tree's 730 `.interlinked/` + folders were such strays (618 under `scratch/`, 17 under `src/` — `.gitignore` `src/**/.interlinked/` had + hidden them), and their own receipts show 21,283 cold hook calls since 2026-09-24 (5,917 PreToolUse). + `interlinked verify` run from a subfolder still writes `/.interlinked/verify-runs.jsonl` (harmless for + the guard now; the CLI's data paths are cwd-relative by convention). `interlinked harness calls [--since 7d] + [--session id] [--strict]` (`harness/call-coverage.ts`) joins the transcript timeline to the collection log by + `[session, tool_use_id]` and lists observed calls without a matching daemon judgment, + by tool and working folder. Missing or rotated capture remains a measurement gap. diff --git a/docs/hook-normalization.md b/docs/hook-normalization.md index 809aa3a09..6072aca00 100644 --- a/docs/hook-normalization.md +++ b/docs/hook-normalization.md @@ -58,8 +58,9 @@ serve. Existing legacy installs remain compatibility paths. Build an unbuilt che then refresh hooks with `interlinked install-hooks --refresh --preserve-mode`. Claude FileChanged has no static matcher; dynamic `watchPaths` are returned at -SessionStart, CwdChanged and FileChanged. PostToolUseFailure remains parse-only to -preserve the existing duplicate-hook-output policy. PostToolBatch cancels the loop +SessionStart, CwdChanged and FileChanged. PostToolUseFailure is installed with the +PostToolUse matcher: Claude Code 2.1.325 reports a failed Bash call only on that event. +The daemon processes one completion per `tool_use_id`. PostToolBatch cancels the loop before another model request; it does not undo any tool. FileChanged and PostCompact are observational. Copilot responses are phase-specific, and Gemini receives its own JSON contract, including a valid empty response. Unsupported approval requests diff --git a/docs/mutation-grounded-test-proof.md b/docs/mutation-grounded-test-proof.md new file mode 100644 index 000000000..8f2abbac9 --- /dev/null +++ b/docs/mutation-grounded-test-proof.md @@ -0,0 +1,626 @@ +# Mutation-grounded test proof + +`interlinked tests prove-kill` answers one question with local execution: + +> Does this test pass on the current implementation **and** fail, by its own +> check, when exactly one specified mutant or fault is applied — for the exact +> source bytes, test bytes and runtime being certified? + +It writes a receipt when the answer was decided by running code. It never +infers a kill from coverage, from a `test-contract` marker, from a plausible +assertion, from an older receipt, or from a surviving-mutant count. + +**What a `killed` verdict is.** It is executed evidence that the named test +distinguishes the two implementations it ran against: the current source and +the source with that one fault. Three claims hide in "this test protects the +behaviour", and the proof establishes only the first: + +1. the test distinguishes these two implementations — **established by running**; +2. the distinction is a violation of an intended requirement — the fault's + author decides that, not the proof; +3. the assertion detects the violation for a meaningful reason — a test that + hashes the source, snapshots its text or reads `fn.toString()` also "kills"; + `kill-proof/degenerate-test.ts` recognises several such shapes and is NOT + wired into the verdict (round 6). + +`FRESH` likewise means exactly: the inputs the receipt RECORDED are unchanged +(source, tests, bound helpers, config and setup files, node and vitest). The +inputs it does not record are listed under Limits; a change there keeps a +receipt FRESH that no longer describes the test. + +## Quick start + +Nothing to install beyond interlinked: any git repository with vitest works. +Commit first if you can: a proof of uncommitted bytes is reported `UNCOMMITTED`. + +```console +$ interlinked tests prove-kill --test test/clamp.test.ts --file src/math.ts \ + --find 'if (value > max) return max;' --replace 'if (value > max) return value;' +mutant: explicit fault @ src/math.ts:3 "if (value > max) return max;" → "if (value > max) return value;" +tests: test/clamp.test.ts (2 case(s) pass in the isolated copy, 615 ms) +verdict: KILLED (570 ms under the mutant) + survived test/clamp.test.ts › clamps below the range + killed test/clamp.test.ts › clamps above the range +receipt: /tmp/kp-demo/.interlinked/test-runs/kill-proofs/d9fa203ce7d2b6e8.json +Proof recorded. It holds while source, tests and runtime are unchanged; check with `interlinked tests kill-proofs --verify`. + +$ interlinked tests kill-proofs --verify +d9fa203ce7d2b6e8 KILLED 2026-11-05T03:49:20.430Z explicit fault @ src/math.ts:3 "if (value > max) return max;" → "if (value > max) return value;" + tests: test/clamp.test.ts + FRESH +1 KILLED proof(s): 1 fresh, 0 uncommitted, 0 stale. Only KILLED proofs count as evidence. +``` + +A manifest survivor works the same way by id (list ids with +`interlinked mutation survivors --file `): +`interlinked tests prove-kill --test src/harness/server/anti-stomp.test.ts --mutant 575ddae6cc2946f9`. + +Every survivor of a file at once — the batch loop. One baseline run is shared +by every mutant (the unmutated copy is identical for all of them), then one +mutant copy per survivor, one receipt each, and a table: + +```console +$ interlinked tests prove-kill --file src/harness/recurrence-time.ts \ + --test src/harness/recurrence-time.mutation-kill.test.ts --test src/harness/recurrence-time.test.ts --all-survivors +file: src/harness/recurrence-time.ts (9 open survivor(s) in the manifest, generation 1; 9 run) +tests: src/harness/recurrence-time.mutation-kill.test.ts, src/harness/recurrence-time.test.ts (11 case(s) pass in the isolated copy, 912 ms, shared by every mutant) + mutant line mutation verdict killed cases + 3f05efd38cd5e4af 16 "SECONDS_PER_MINUTE * MS_PER_SECO… → "SECONDS_PER_MINUTE / MS_PER_SECO… SURVIVED none — every case still passes + 532dcc0c1ccefed5 24 "/^\\s*(\\d+)\\s*([smhdw])\\s*$/i" → "/^\\s*(\\d+)\\s*([smhdw])\\s*/i" SURVIVED none — every case still passes + … + 80af77afb7085336 67 "ms > lastMs" → "ms >= lastMs" SURVIVED none — every case still passes +summary: 0 killed / 9 survived / 0 inconclusive / 0 unavailable of 9 (45.6 s) +9 survivor(s) still pass these tests. Assert the value each surviving line changes, then re-run the same command. +``` + +(Measured 2026-11-05 on this repo against a fresh Stryker manifest: the nine +survivors Stryker left under the same two test files all survive the proof +too, as they must. The batch took 63 s wall; the same nine as single `--mutant` +runs took 99 s, with identical receipt ids and verdicts.) + +Exit 0 only when every survivor that ran is killed; 1 when any survived or a +test is not-passing-now; 2 when nothing could run (no manifest, the file is +not measured, no open survivor). `--max ` (default 50) caps the batch in +source order and the summary says how many were skipped. `--json` returns +`{file, tests, survivors, skipped, results: [...per-mutant results, each with +its mutantId...], summary, elapsedMs}`; each entry in `results` is exactly +what the single-mutant command returns for that id. + +Reading the verdict (add `--json` for a machine-readable result). The last line +of the human output always says what to do next. + +- `KILLED` (exit 0): a named test failed by its own check. A receipt is written. +- `SURVIVED` (exit 1): every test still passed. Assert the value the fault changes. +- `NOT-PASSING-NOW` (exit 1): a test fails before any mutation. Fix it first. +- `INCONCLUSIVE` (exit 2): the mutant did not parse, a test crashed or timed + out, or the kill did not repeat on a clean copy. Nothing is proven. +- `UNAVAILABLE` (exit 2): the proof could not be set up. The reason names the + cause, such as a missing test, an ignored fixture, a mock, or a workspace root. + +Two flags fix most `UNAVAILABLE` runs. `--run-timeout ` raises the budget +for each vitest run (default 300000). `--vitest-config ` picks the config +when the test is outside the default one's `include`. + +Keeping the receipt fresh: `interlinked tests kill-proofs --verify` re-hashes the +source, tests, vitest config and setup files, and compares node and vitest. Any +change marks a `KILLED` receipt `STALE` and exits 1. Re-run the same +`prove-kill` command to renew it. +The renewed receipt retires the stale one (see *Receipt retirement*), so the +check is green again as soon as the newest proof of that source × mutant × test +set holds. + +## When to use it + +- An agent or a developer says "I added a regression test for this bug" or + "this test kills mutant `575ddae6cc2946f9`". Prove it before trusting it. +- `interlinked mutation survivors --file ` listed a survivor and someone + wrote a test for it. The per-file measurement (`mutation measure`) takes + minutes and needs a runner; a proof takes seconds and needs only vitest. +- A `[interlinked:kill-proof]` PostToolUse line appeared after editing a + `*.mutation-kill.*`, `*.mutation-hardening.*` or `*.survivors?.*` test file. + +## Usage + +```bash +# A manifest survivor by stable id (ids: interlinked mutation survivors --file ) +interlinked tests prove-kill --mutant 575ddae6cc2946f9 --test src/harness/server/anti-stomp.test.ts + +# An explicit fault — works in ANY git repository with vitest, no manifest needed +interlinked tests prove-kill --file src/defu.ts \ + --find 'if (value === null || value === undefined) {' \ + --replace 'if (value === undefined) {' \ + --test test/defu.test.ts + +# Every open manifest survivor of one file: one shared baseline, one receipt per mutant, a table +# Add --max 20 to run at most 20 survivors. +interlinked tests prove-kill --file src/defu.ts --test test/defu.test.ts --all-survivors + +# Machine-readable +interlinked tests prove-kill ... --json + +# Receipts and freshness +interlinked tests kill-proofs # list, newest first (200 rows; --json lists every receipt) +interlinked tests kill-proofs --verify # re-hash, re-resolve, exit 1 if the newest receipt of any proof is stale +interlinked tests kill-proofs --prune [--dry-run] # remove receipts whose source or test file no longer exists + +# After a test edit: re-prove each kill the old test bytes proved (no receipt written) +interlinked tests edit-protection [tests...] [--base HEAD] [--source ] [--max 50] [--json] +``` + +`tests edit-protection` is the requirement-change half of saturation testing. A +stale killed receipt whose test bytes (or test-only helper bytes) changed is the +"before" evidence. The command re-proves the mutant with the current test and +classifies each row `kept`, `lost`, `retired` (the source no longer holds the +mutant) or `undecided`. A `lost` row is a finding when its source is outside the +change-set and no other test file holds a fresh killed receipt for it. Exit 0 no +finding, 1 a finding, 2 an undecided row or a bad argument. + +`--test` is repeatable. `--run-timeout ` bounds EACH vitest run (the baseline +copy, the mutant copy, then the repeat or canary copies; default 300000) — in a +batch too, per run, while `--timeout` bounds the whole batch. +`--vitest-config ` passes a config to vitest — absolute, relative to the +shell's cwd or relative to the project, in that order, recorded repo-relative; +a file outside the project is refused. Without it the `-c`/`--config` that +`scripts.test` names is used, else `vitest.config.*` then `vite.config.*` in +vitest's own order. `--timeout ` +is a different flag: the CLI's resource supervisor reads it as the whole +command's deadline (default and maximum 3600000), and a value below a few seconds +stops the CLI before any verdict (exit 75). The deadline is a SIGTERM to the +command, which handles it: the running vitest group is killed, every copy made +so far is removed, `[interlinked:kill-proof] interrupted by SIGTERM: copies +removed, no verdict, no receipt written` is printed and the exit is 75 (round 5, +R5-7; the supervisor SIGKILLs a child that has not exited one second after the +SIGTERM, so a copy whose removal takes longer than that can still be left +behind). `prove-kill` accepts the flag itself +too, so it never surfaces as a usage error; a usage error (an unknown option, a +non-numeric timeout) exits 2 like every other undecided run, never 1. + +Every vitest run the proof makes is private: `--no-cache` (vitest's results +cache is never written — it would land in the live `node_modules` through the +copy's link and reorder test files between runs) and a fresh temp directory per +run (`TMPDIR`/`TMP`/`TEMP`, removed with the run), so `os.tmpdir()` state cannot +cross from one run to the next. Every vitest process runs in its own process +group; a run that passes `--run-timeout` is stopped as a group, worker included, +and the proof continues only once the group is gone — the wait is a referenced +timer, so the command always ends in a verdict (`inconclusive` or `unavailable`, +exit 2) with its copies removed, never in Node's exit 13 for an unsettled +top-level await (round 5, R5-1). A copy over 256 MiB of +git-visible files — allocated blocks, not apparent size, so a sparse file does +not count (R5-12) — adds a warning (`[interlinked:kill-proof] copy is N MiB; large +tracked files slow every proof`, `warnings` in `--json`); it changes no verdict. +===== + +## What happens + +1. **Resolve the mutant.** A manifest id is re-located in the *current* source + through the manifest identity (symbol, operator, lexeme, ordinal). If the + source drifted so the identity no longer resolves, the run is `unavailable`; + so is a re-location the ordinal cannot settle (the symbol's body changed and + the lexeme now occurs a different number of times in it — see Limits). + An explicit `--find` must occur exactly once in `--file`. +2. **Freeze, then baseline.** The project as git sees it (tracked plus + untracked-not-ignored files, `node_modules` linked) is copied ONCE into a + disposable FROZEN copy; the live tree is read exactly once per proof (per + file in a batch) and never again. Every later copy — baseline, mutant, + repeats, canary, control — is a clone of the frozen copy, and every hash the + receipt records (source, tests, helpers, config, setup files) is taken from + it, so the only difference between the compared runs is the mutant and the + receipt binds exactly the bytes that ran. An edit that lands in the live + tree mid-proof (another agent, a human) reaches no copy; it makes the + receipt STALE against the live tree instead of silently entering one run + (round 6). The named test files then run UNMUTATED in the first clone. + Every case must pass. A case that fails because the + copy lacks a file the live tree has (an ignored fixture named in the failure) + makes the run `unavailable`; any other failure is `not-passing-now`. Nothing + ever runs on the live tree: a live run writes tool caches there. Each run + gets `--no-cache` and its own temp directory (see Usage), so neither + vitest's results cache nor `os.tmpdir()` carries anything between runs. +3. **Mutant.** A SECOND clone of the frozen copy receives the one mutated + source file, so nothing the baseline run left behind (a marker file, a snapshot, a log) can + fail the second run. A replacement that does not parse is `inconclusive` + without running: a compile error is not behaviour. The same tests run in the + copy with vitest's JSON reporter. +4. **Repeat baseline, twice** (only when a case was killed). Two more fresh, + unmutated copies run the tests again, so a kill is the sequence pass, FAIL, + pass, pass. A killed case must pass in both; one that fails again was + broken by state a run left OUTSIDE the copies (`$HOME`, `/var`, a path + beside the project — the copies' temp directory and vitest cache are + already private) and is `inconclusive` ("not repeatable"), never a kill. + One repeat accepted state that flips on every run (a counter that forbids + its second reading, a marker the next run deletes): with the mutant always + in run 2 of 3, period-2 state lined up with it. Two repeats reject every + period-2 pattern; see Limits for what remains. +5. **Canary** (only when every case survived). A further copy holds a + module-level `throw` in the mutated file's place, and the survivor stands + only when three things hold. The canary run completed — a canary that times + out or fails to launch is `unavailable` ("canary run did not complete; + cannot show the tests load the copy"), never `survived`. Per named file, + every baseline-passing case stopped passing — a case still passing never + loaded the copy's file (a mock, an absolute import, an alias or a link into + the live tree) or caught its own import error; the run is `unavailable` and + names the cases. And the break is the tests' doing: a test whose static + relative imports reach the mutated file is evidence by itself (a relative + import resolves inside the copy); for any other named test a **control** + copy — the canary plus every named test replaced by one trivial case — must + pass. If the control breaks too, a `setupFiles` entry or the config loads + the file, not the tests, and the run is `unavailable` with that reason; if + the control's stand-in case never ran at all (vitest's `testNamePattern`, in + the config or on the command line, filters it), the reason names the filter + instead (round 5, R5-10). +6. **Verdict per case**, then overall. In a batch (`--all-survivors`) steps 1–5 + run per survivor against ONE shared baseline (step 2 runs once; the canary + and control of step 5 run once per file); the per-mutant repeats of step 4 + stay per mutant, so a kill is still pass, FAIL, pass, pass around that + mutant run. The work-list is the manifest's open survivors for the file — + `mutation survivors --file` semantics, dispositions applied; nothing is + inferred from the tree — in source order; a survivor that no longer + re-locates is an `unavailable` row, never skipped silently. + +| Verdict | Meaning | Exit | +|---|---|---| +| `killed` | at least one named case failed **by its own check** (an assertion, a snapshot mismatch, a plain error thrown from the test file, or a property-test report wrapping one of those) | 0 | +| `survived` | every case still passed with the mutant applied; these tests do not detect it | 1 | +| `not-passing-now` | a named case fails on the live tree; the proof cannot start | 1 | +| `inconclusive` | no case failed by its own check, and at least one crashed, failed to load, or the runner timed out — nothing is proven | 2 | +| `unavailable` | the mutant does not resolve, a test file is missing, not a git work tree, or the runner could not run | 2 | + +A crash in product code under the mutant (`TypeError`, a stack overflow) is +`inconclusive`, not a kill. The tests noticed *something*, but no assertion +about the intended behaviour fired; this is the same rule `tests +fail-before-fix` and `tests faults run` apply. A property-based test +(fast-check) is judged by the error its counterexample report wraps — the +report's `cause`, captured by a sidecar reporter beside the JSON report, since +the report itself is thrown from `node_modules` whatever the predicate did — +so an `expect` or a predicate that returned false inside the property is the +test's own check while a product `TypeError` inside it stays `inconclusive`. + +## The receipt + +`.interlinked/test-runs/kill-proofs/.json`, with `index.json` beside it as +the small read model. A receipt binds: + +- the mutated source path and sha256 of its bytes; +- the mutant: file, offset, line, lexeme, replacement, and for a manifest + mutant its `mutantId`, `siteId`, `symbolId`, `qualifiedName`, `mutator`, + `ordinalWithinSymbol`, manifest generation and recorded status; +- every named test file's path and sha256; +- `boundImports`: every file in the named tests' local STATIC import closure + (helpers, shared fixture modules, re-export barrels), each with its sha256 + and `importedBy`, the named tests whose closure reaches it. The walk follows + `import … from`, side-effect `import "…"` and `export … from` with relative + specifiers, transitively, inside the project, plus the `__mocks__` twin of + every factory-less `vi.mock("./x")` / `vi.doMock("./x")` (beside the mocked + module; a bare specifier's twin under `/__mocks__/`) when one exists + (round 5, R5-4); it skips type-only imports, + bare specifiers (packages and tsconfig aliases), and anything under + `node_modules` or outside the root. The mutated source itself is bound as + the source and never listed as a helper, but its OWN imports are walked and + bound through it, credited to the tests that reach it (round 6: test → + target → helper is the ordinary shape, and a helper that decides the + target's behaviour used to change without staling the receipt when the test + reached it only through the target). The config's `setupFiles` / + `globalSetup` files are walked too, as roots that run before every test: + what they reach is bound with `importedBy` = every named test (R5-5). A + changed helper stales the + certification of every test that imports it, and only those; `--verify` names + it as `helper changed since the proof`. The walk stops at 200 files; + a receipt whose walk was cut carries `boundImportsTruncated: true` and + certifies NOTHING — `--verify` reports it `STALE: bound-import closure + truncated at 200 files; …`, the Stop check and the nudge refuse it — since an + edit that changes the proof may sit in a file it did not bind (R5-3); +- node version, vitest version, platform, the sha256 of the vitest config in + use, the sha256 of every other file vitest loads to configure the run + (`configFiles`: each `test.projects` config and the configs' static local + import closure — a `test: testOptions` imported from a helper), and the sha256 + of every `setupFiles` / `globalSetup` file any of them declares, resolved as + vitest resolves them (against the project root for the root config, against + the config's directory for a project config, against a static `test.root` + when one is declared). The values are read from the config's AST: arrays, + string literals and expression-free template literals bind; a computed value + (a spread, a call, an identifier, a template with `${}`), a path that is not + a project file, or a config read without `typescript` installed is recorded + under `unresolvable` and shown by `--verify` as `LIMIT (not bound)` — the + receipt never drops a declaration silently; +- the per-case outcomes on both sides, durations, the verdict, and + `killedTests`: the named test files with at least one killed case, the only + files the receipt certifies. A case is recorded under vitest's full name + (` › `); two cases that share a + full name (a duplicated `it("…")`, an `it.each` title without a placeholder) + are judged one by one, paired by their position among the same-named rows in + report order, so a weak duplicate of a strong case records `survived` beside + the strong case's `killed`; +- a `digest` over every other field, so an edited outcome no longer matches. + +New receipts use version 2. Version 1 records remain readable history, but freshness +checks mark them stale because they were produced before the target-helper closure +was complete. Re-run the proof to produce version 2; editing an old receipt's version +cannot supply the missing execution evidence. Version 2 is part of the receipt id, +so renewal preserves the old record and supersedes it through the existing proof key. + +The id is a hash of the inputs (bytes, bound helpers, mutant, runtime), so re-running the same +proof on the same bytes overwrites rather than duplicates. `kill-proofs --verify` +re-checks the digest, re-hashes the files, compares the runtime, and re-resolves +the mutant; any difference is `STALE` with the reasons named. A `survived` or +`inconclusive` receipt is kept (it records what was tried) but never counts as +evidence of a kill. Every decision (the Stop check, the nudge, the list) reads +the receipt FILE; `index.json` is only a locator. It is rebuilt from the receipt +files under a short exclusive lock, so concurrent writers cannot drop each +other's rows; a writer that cannot take the lock still writes its receipt and +leaves the index to the next writer's rebuild. The harness refuses Write, Edit and +NotebookEdit tool calls under `.interlinked/test-runs/kill-proofs/` (a +`protected_files` rule matched against the write's REAL path, so a symlinked +receipts folder does not slip past): only the command writes there. A receipt +file is only the receipt whose `id` it names: a copy under another valid name +is unreadable, never a second receipt. `--verify` lists a receipt as +`UNCOMMITTED` (exit 0) when the sha256 a bound source, test or helper was +proven at is not the sha256 of that path's blob in HEAD and in the index: the +proof is about work-tree bytes, and a commit-time reader must know they are not +the committed ones. The comparison reads git's blobs, never `git status`, so an +index flag (`--skip-worktree`, `--assume-unchanged`) cannot hide modified bytes. +Receipts are tamper-evident, not tamper-proof: the digest is unkeyed, so a +receipt rewritten from scratch with recomputed hashes passes. They are evidence +of execution on this machine, not a security boundary. + +### Receipt retirement + +A receipt's id binds the exact bytes, so every re-proof after an edit writes a +NEW receipt. The proof it renews is identified by its *proof key*: the source +path, the mutant's identity (a manifest id, or for an explicit fault its file, +`--find` lexeme and `--replace` text — the offset is not part of it, so a proof +renewed after an edit above the fault is the same proof) and the named test +set. Every index rebuild (each write) marks every receipt that is not the +newest of its key with `supersededBy: `. Superseded receipts stay on +disk as history, are never read as evidence (the Stop check, the nudge and +`freshKillsForTest` skip them even when their bytes come back), and +`kill-proofs` lists them with `SUPERSEDED by `. `--verify` judges only the +newest receipt per key; a superseded receipt never fails it. Proving the same +bytes again rewrites the same id with a newer `provedAt`, which makes it the +current receipt once more. A different test set or a different fault is a +different proof and is never superseded by another. + +**Orphans.** A receipt whose source or named test file no longer exists can never be +re-proved, so it would keep `--verify` at exit 1. `kill-proofs --prune` removes only +those receipts (`--dry-run` lists them) and rebuilds the index. It never removes a +stale receipt whose files exist (re-prove it) or an unreadable receipt (it may record +a hand edit; remove it yourself after you read it). + +**Survivor anchoring.** When the survivors sidecar +(`.interlinked/mutation-survivors-index.json`) knows manifest survivors for a +mutation-directed file's companion source, only a receipt for a manifest mutant +(`--mutant` or `--all-survivors`) of that source certifies the file for the nudge and +the Stop check. An explicit `--find/--replace` kill is still a valid receipt, but it does +not show that the file kills the survivors it claims (review round 3 §d.11). With no +known survivors, an explicit fault certifies. + +## Where the harness uses it + +- **PostToolUse** (model-visible on Claude Code and Codex): writing a + mutation-directed test file that no receipt certifies now prints + `[interlinked:kill-proof] : no executed kill proof covers this + mutation-directed test file … prove it: interlinked tests prove-kill …`. + A receipt is FRESH for a file when it killed THROUGH that file and the source, + that test file, the helpers it imports and the runtime are unchanged. The + fresh receipts of a file are then judged TOGETHER (round 6): every newly + added case must be covered by the killed cases of at least one fresh receipt + — the mutant that receipt binds is the fault the case detected — and two + cases may be covered by two different receipts (a lower-bound case proven + against fault A, an upper-bound case against fault B). A fresh receipt that + covers no new case certifies nothing on its own. Parameterized families apply + this rule to each expanded name: different names may be proven by different + receipts, but one receipt must kill every recorded duplicate of a given name. + Cost: one index read plus + the hashes of the matching receipts. +- **Stop** (human-visible stderr): `[interlinked:mutation-kill-evidence]` + accepts the fresh receipts as measurement evidence only when EVERY newly + added case is covered by the killed cases of some fresh receipt (the same + judged-together rule as the nudge); an old strong case, one strong new case, + or the strong twin of a weak duplicate never certifies a case that killed + nothing. + The PostToolUse nudge applies the same rule against `HEAD`. A missing + `test-contract` marker still fires. +- **`interlinked verify`** (default gate, streaming and `--json`): when + `.interlinked/test-runs/kill-proofs/` holds at least one receipt, verify + gains a `kill_proofs` section (JSON key `kill_proofs`) listing every receipt + — verdict, source, test file(s), and the SAME freshness + `interlinked tests kill-proofs --verify` reports (`fresh` / `uncommitted` / + `stale` / `unreadable`, with reasons; one implementation, `listKillProofs`). + A STALE or UNREADABLE **killed** receipt is a `kill_proof_stale` finding + (`[proven]`: hashes and a parser decided it) that fails verify under its + exit convention, with the fix being the receipt's own command — `--mutant + ` for a manifest mutant, `--file/--find/--replace` (shell-quoted) for an + explicit fault (round 6; it used to print `--mutant ` for both); + `uncommitted` is reported, never a finding; `survived` and + `inconclusive` receipts are listed, never findings. No receipt ⇒ no section + and no git call (one directory probe). `--skip kill_proof_stale` keeps the + listing and drops the finding. +- `interlinked mutation survivors --file ` names the command. +- **Which command the nudge and the Stop check print**: when the manifest's + survivors sidecar (`.interlinked/mutation-survivors-index.json`) knows more + than one survivor of the test file's companion source (`src/a.mutation-kill.test.ts` + → `src/a.ts`), both print the batch form, `interlinked tests prove-kill + --file --test --all-survivors`; with one or no known survivor, + or no sidecar, the single-mutant form. The choice changes only the printed + command, never when either surface fires (`kill-proof/prove-command.ts`). + +### How a new case is derived and matched + +Both surfaces read the cases from the TypeScript AST of the test file +(`kill-proof/source-cases.ts`), before (the git baseline) and after the edit: + +- A case is a call whose callee chain starts at a bare `it` or `test` (so + `/re/.test("…")` or `obj.test(…)` is never one), optionally through `.only`, + `.skip`, `.todo`, `.concurrent`, `.sequential`, `.fails` and the configuring + calls `.each(...)`, `` .each`…` ``, `.for(...)`, `.skipIf(...)`, `.runIf(...)`; + `const t = test.extend(...)` makes `t(...)` a case. `describe` / `suite` + ancestors contribute their titles, space-joined, exactly as vitest's full name. +- A string title is its cooked value (`"says \"max\""` is matched as + `says "max"`); an identifier bound once to a string literal in the file + resolves to it. Matching is EXACT on the full name — never a suffix: a new + `it("max")` is not certified by an old `describe("caps") it("at max")`. +- An `.each` / `.for` title with a `%i` / `%s` / `%d` / `%j` / `%o` / `%#` / + `$prop` placeholder, or a template literal with substitutions, is a *prefix + family*: the literal text before the first placeholder (a `%%` before it is + a literal percent). The family is certified when EVERY recorded case of that + file whose name starts with the prefix killed, and at least one exists. + Residual limit: an old case that happens to share the prefix is part of the + family, so a surviving old `caps at max` blocks a fully killed + `it.each([5, 6])("caps %i")`; name the family distinctly. +- A computed title (a call, an ambiguous identifier, an empty prefix, a case + under `describe.each` or under a non-literal `describe`) is *unresolvable*: + it counts as a new case and can never be certified by name, so the file stays + flagged until the title is literal. +- Identity is a MULTISET: a weak duplicate of an existing title is one more + case, and it is certified only when every recorded case of that name killed. +- A case whose title is new but whose body (its `.each` table and callback + text, whitespace collapsed) equals a removed case's is a RENAME and makes no + claim. A new title with a new body is a new case whether or not the file + grew: swapping a strong case for a weak one opens the gap on both surfaces. +- Without `typescript` installed the walk degrades to a literal-title regex + (bare `it`/`test` head, no ancestors, no renames) and matches titles exactly. + +Stop-time warnings reach no agent as context on any runner (Claude Code, Codex, +Factory Droid, Copilot, Gemini all put them on stderr with exit 0). The agent +sees the PostToolUse line; the human sees the Stop line. + +## Limits (v1) + +- vitest only. A jest or ava project gets `unavailable` with the reason + `vitest is not installed in this project (this project declares jest) …`. +- Helper binding follows static relative imports only (from the named tests, + through the mutated source, and from the config's `setupFiles` / + `globalSetup`), and stops after 200 files — + a receipt whose walk was cut says so and certifies nothing; re-prove with a + shallower helper tree. When a static runtime import or re-export uses a + literal key from an inline root `resolve.alias` or `test.alias` object, + verification reports the unresolved input and the receipt cannot certify + the affected test. The config may export the object directly or through + `defineConfig`. An unused alias or a whole-clause `import type` or + `export type` leaves the receipt eligible. An inline-only declaration such + as `import { type T } from "@helpers/types"` can still load the module + with `verbatimModuleSyntax`, so verification reports that uncertainty. + Dynamic imports, `require()`, computed or array alias maps, project-specific + aliases and tsconfig `paths` remain outside this check. A helper changed + solely through those routes can leave an inapplicable receipt marked FRESH. + A `vi.mock` with a + factory is bound through the file that holds the factory; a factory-less one + binds its `__mocks__` twin; a mock that vitest resolves another way (a + package's `__mocks__` outside the root, an alias) is not followed. Data files + a test reads (JSON fixtures, snapshots) are not bound. + (A helper still cannot be named as a `--test` file: it reports no cases and + the run is `unavailable`.) +- The copies link the live `node_modules`. vitest's own results cache is + disabled for every run (`--no-cache`, accepted by vitest 2.1.9, 3.2.7 and + 4.1.11) and each run has a private temp directory, but any OTHER write a test + or tool makes under `node_modules` still lands in the live tree. +- Repeats lower the odds of a false kill from state and flakiness; they do not + end them. The kill sequence pass, FAIL, pass, pass rejects state that flips + on every run (period 2); state that fails on exactly the second of every + three runs (period 3) still passes, as does state kept where the proof does + not look (`$HOME`, `/var`) — also when a custom `sequence.sequencer` reads it + and reorders the files on exactly that run (round 5, R5-9). A repeat can only + catch state that misbehaves on an UNMUTATED run: ADAPTIVE state — a store of + seen source hashes beside the project that fails exactly when the bytes are + new — produces the kill sequence pass, FAIL, pass, pass for any mutant, a + comment-only one included, whatever the repeat count; its second proof then + reads `survived`, because the verdict depends on history (R5-8). The test did + read the mutated file and fail by its own check, so the proof's claim holds; + the lesson is that a receipt is one measurement — run a doubtful proof + twice, and keep test state inside the project. A test with failure rate f gives a false kill + with probability (1−f)³·f per proof (one repeat: (1−f)²·f, at most 14.8 %), + and `sequence.shuffle` makes order-dependent tests exactly that. Run the + proof twice when in doubt; a receipt is one measurement. +- A test that catches its own import of the mutated file (`try { await + import("../src/x") } catch {}`) swallows the canary and is reported + `unavailable` ("never load … or catch its import error"), by design: a + survivor needs evidence that the tests observed the copy's file, and a + swallowed import gives none. Assert on the import's result instead. +- A `setupFiles` entry or a vitest config that imports the mutated source makes + the canary break every case without the tests' involvement. A test that also + imports the source by a relative path is still attributed; one that reaches + it only through an alias, a mock or a dynamic import is `unavailable` + (the control copy breaks too). Import the source from the test. + +- A test that reaches the source through an absolute path, an alias or a + mock runs against the live, unmutated code; the canary turns that into + `unavailable` (the tests do not load the file from the copy). A named test + file whose real path is outside the project is refused; links that resolve + inside the project are rewritten to the copy. +- Keep test fixtures tracked. The proof reports `unavailable` when the copy + lacks a file named by a read failure, or when a named test checks a literal + project-relative path with Node's ESM-imported `existsSync` in a top-level + variable initializer or its ternary condition and that path exists only live. + The latter check uses the optional TypeScript parser. Indirect or computed + optional reads can still pass vacuously in the copy and yield `survived`. +- A monorepo root without its own `vitest` is `unavailable`; run with `--cwd + `. +- The copy is a git-visible copy, not an OS sandbox: a test that writes + outside its project does so for real, as it does under `vitest run`. A + timed-out run is killed as a process GROUP, so a grandchild that starts a + new session (`setsid`, `detached` + `unref`) escapes it and can outlive the + proof — a new session is outside any process group by definition; only a + cgroup or namespace sandbox stops it (round 5, R5-11). Windows has no + process groups at all: only the direct vitest child is killed there. +- Workspaces: `vitest` is found where `npx vitest` would find it — the + project's own `node_modules`, else the nearest ancestor's up to the git root + (a hoisted npm/pnpm/yarn install) — and the copy places the package under + the same relative path below a link to that `node_modules`, so `--cwd + ` works for a hoisted member. A workspace root whose own vitest is + absent and that declares no hoisted one is `unavailable`. Cross-package + imports (`import … from "@mono/b"`) resolve through + `node_modules/@mono/b → ../../packages/b`, a link into the LIVE tree: a + mutant in another package is never loaded from the copy and the canary + reports `unavailable`. Prove a package's own files from that package. +- Module-system semantics are vitest's, not Node's: vitest's module runner + shims `require`, `module.exports` and `__dirname` inside an `.mjs` source and + accepts `export` in a `.cjs` file, so a mutant that introduces one of them + runs and is judged by the tests (often `survived`) although Node's own loader + would refuse the file. The parse check models the dialect by extension only + (JS / TS / JSX); a `.js` or `.ts` file that already holds JSX (a CRA-era + layout the project's vitest transforms) is proven like any other, and only a + mutant that INTRODUCES JSX into a JSX-free file is refused as a compile error. +- The receipt does not bind environment variables: a config that reads + `process.env.X` runs a different setup under a different shell, and two such + proofs share one id (the second overwrites the first). Receipts are evidence + of execution on this machine, not of the shell it ran in. +- A manual mock (`__mocks__/x.ts`) is refused as a target: a proof over a mock + proves nothing about the module it stands in for. +- A run that produces no case rows is explained by vitest's own words: a + startup failure keeps the first 2 KB of stderr (`failed to load config … + Could not resolve …`) and a file that reports no case carries its file-level + message (`Failed to load url ./x.js …`, `Vitest cannot be imported in a + CommonJS module …`) in the `unavailable` or `inconclusive` reason. +- No model is involved anywhere. The differential-fuzz engine (which can + propose a counterexample input) is a separate, manual tool and executes + target code in-process; it is not on this path. +- Neither the proof nor vitest type-checks: a replacement that parses but + fails the type check runs, and the tests judge it like any other mutant. A + binder-level early error (a redeclared `let`) is not caught before the run + either; a syntax error in the file's own dialect is. +- A receipt rewritten from scratch with a recomputed digest, through the shell + rather than the edit tools, is not detectable from its bytes. +- **`--mutant` re-location is an ordinal rule.** A manifest mutant is the + N-th occurrence (ascending offset) of its lexeme, under its operator, inside + its symbol — never a line or an offset. The manifest records a `symbolHash` + per symbol (identity.ts's normalized-token hash of the function body) and an + ordinal per mutant, but no site count; the proof reads the measured count + back off the symbol's own ordinals (highest ordinal + 1 over the records + sharing operator and lexeme). Re-location then goes one of three ways: + - symbol hash unchanged → the ordinal is trusted (an inserted comment, or an + edit elsewhere in the file, lands here); + - symbol hash changed, same count → the ordinal is still trusted (an + unrelated statement added to the body); the ordinal rule cannot tell this + from a rewrite that kept the count, so re-measure when the body changed + around the site; + - symbol hash changed AND the count changed → `unavailable` with + `ambiguous re-location: now occurs N times in (was M); + re-measure the file`. No ordinal is picked. An identical lexeme + inserted earlier in the body took ordinal 0 — and with it the mutant id — + so the proof mutated the new dead-code site and wrote `survived` under an + id that had been killed. A lexeme that no longer occurs in the symbol is + plain drift (`no site among …`), and a symbol that no longer exists is + `source drift: symbol not found (mutant )`. + `interlinked mutation measure ` re-measures; the ids then rank against + the current body. +- A prefix family (`it.each`, template titles) also covers older cases that + share the prefix; a case under `describe.each` or with a computed title can + only be certified after it is given a literal title. diff --git a/evals/claim-verification/graph-lab-fixtures.test.mts b/evals/claim-verification/graph-lab-fixtures.test.mts index b5c504b87..8fe6903ef 100644 --- a/evals/claim-verification/graph-lab-fixtures.test.mts +++ b/evals/claim-verification/graph-lab-fixtures.test.mts @@ -13,6 +13,22 @@ test("provenance controls include support, stale inputs, capture gaps and poison assert.equal(actual.status === "supported", c.expected, c.id); } }); +test("a failure, stale source and missing input produce distinct provenance outcomes", () => { + const expected = { + failure: ["contradicted", "current"], + dependency_edit: ["unsupported", "stale"], + missing_input: ["not_assessable", "unknown"], + }; + const cases = provenanceCases(); + for (const [variant, outcome] of Object.entries(expected)) { + const entry = cases.find(item => item.variant === variant); + assert.ok(entry, `missing provenance control ${variant}`); + const receipt = entry.receipts.find(item => item.id === entry.target); + assert.ok(receipt, `missing target receipt for ${variant}`); + const assessment = assessTestProvenance(receipt.graph, "claim", receipt.current); + assert.deepEqual([assessment.status, assessment.freshness], outcome); + } +}); test("extraction references point to complete source clauses and retain their qualifiers", () => { for (const c of extractionCases()) { assert.equal(c.annotation.claims.length, 3); diff --git a/evals/claim-verification/mutation-pool.mts b/evals/claim-verification/mutation-pool.mts index 722453f61..13d5bed16 100644 --- a/evals/claim-verification/mutation-pool.mts +++ b/evals/claim-verification/mutation-pool.mts @@ -1,7 +1,7 @@ import { createHash } from "node:crypto"; import { spawn } from "node:child_process"; import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs"; -import { dirname, resolve, relative } from "node:path"; +import { dirname, isAbsolute, resolve, relative, sep } from "node:path"; import { fileURLToPath } from "node:url"; import ts from "typescript"; @@ -31,9 +31,12 @@ export function enumeratePool(source: string): PoolMutant[] { walk(file); return [...new Map(mutants.map(m => [m.id, m])).values()]; } -export function copyClosure(path: string, root: string, seen = new Set()): void { - const absolute = resolve(path); if (seen.has(absolute)) return; seen.add(absolute); - const rel = relative(process.cwd(), absolute); if (rel.startsWith("..")) throw new Error("Dependency escaped repository"); +export function copyClosure(path: string, root: string, seen = new Set(), sourceRoot = process.cwd()): void { + const absolute = resolve(sourceRoot, path); + if (seen.has(absolute)) return; + const rel = relative(sourceRoot, absolute); + if (rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel)) throw new Error("Dependency escaped repository"); + seen.add(absolute); const text = readFileSync(absolute, "utf8"); const destination = resolve(root, rel); mkdirSync(dirname(destination), { recursive: true }); writeFileSync(destination, text); const file = ts.createSourceFile(path, text, ts.ScriptTarget.Latest, true); @@ -43,7 +46,8 @@ export function copyClosure(path: string, root: string, seen = new Set() if (!statement.moduleSpecifier || !ts.isStringLiteral(statement.moduleSpecifier)) continue; const spec = statement.moduleSpecifier.text; if (!spec.startsWith(".")) continue; const base = resolve(dirname(absolute), spec); const target = [base.replace(/\.js$/, ".ts"), base, base + ".ts"].find(existsSync); - if (!target) throw new Error(`Missing dependency ${spec}`); copyClosure(target, root, seen); + if (!target) throw new Error(`Missing dependency ${spec}`); + copyClosure(target, root, seen, sourceRoot); } } diff --git a/evals/claim-verification/mutation-pool.test.mts b/evals/claim-verification/mutation-pool.test.mts index 183119588..49af412f1 100644 --- a/evals/claim-verification/mutation-pool.test.mts +++ b/evals/claim-verification/mutation-pool.test.mts @@ -1,7 +1,8 @@ import test from "node:test"; import assert from "node:assert/strict"; import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs"; -import { join, relative } from "node:path"; +import { tmpdir } from "node:os"; +import { join } from "node:path"; import { copyClosure, enumeratePool, runBoundedProcess } from "./mutation-pool.mjs"; test("mutation sites exclude comments, imports and type literals while including conventional operators", () => { @@ -22,12 +23,14 @@ test("timed-out mutation processes terminate and preserve captured output", asyn }); test("isolated dependency copies follow runtime re-exports", () => { - const fixture = mkdtempSync(join(process.cwd(), "scratch/mutation-closure-")); + const fixture = mkdtempSync(join(tmpdir(), "mutation-closure-")); try { const entry = join(fixture, "entry.ts"), leaf = join(fixture, "leaf.ts"), out = join(fixture, "copy"); writeFileSync(entry, 'export { value } from "./leaf.js";'); writeFileSync(leaf, "export const value = 3;"); - copyClosure(entry, out); - assert.equal(readFileSync(join(out, relative(process.cwd(), leaf)), "utf8"), "export const value = 3;"); + copyClosure(entry, out, undefined, fixture); + assert.equal(readFileSync(join(out, "leaf.ts"), "utf8"), "export const value = 3;"); + writeFileSync(entry, 'export { absent } from "./missing.js";'); + assert.throws(() => copyClosure(entry, out, undefined, fixture), /Missing dependency/); } finally { rmSync(fixture, { recursive: true, force: true }); } }); diff --git a/evals/claim-verification/run.test.mts b/evals/claim-verification/run.test.mts index 37c6f7047..aafb710d6 100644 --- a/evals/claim-verification/run.test.mts +++ b/evals/claim-verification/run.test.mts @@ -1,16 +1,18 @@ import assert from "node:assert/strict"; import { execFileSync } from "node:child_process"; -import { mkdtempSync, readFileSync, writeFileSync } from "node:fs"; +import { createHash } from "node:crypto"; +import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs"; import { tmpdir } from "node:os"; import { join } from "node:path"; import test from "node:test"; -test("offline pilot writes measured results and preserves an explicit not-run model status", () => { +test("offline pilot writes measured results and preserves an explicit not-run model status", { timeout: 60_000 }, t => { const root = mkdtempSync(join(tmpdir(), "claim-pilot-test-")); + t.after(() => rmSync(root, { recursive: true, force: true })); const dataset = join(root, "turns.jsonl"); writeFileSync(dataset, JSON.stringify({ id: "s:1", session: "s", final_text: "Tests pass. Build failed.", claims: [], tools: [] }) + "\n"); const out = join(root, "results"); - execFileSync(process.execPath, ["--import", "tsx", "evals/claim-verification/run.mts", "--dataset", dataset, "--out", out]); + execFileSync(process.execPath, ["--import", "tsx", "evals/claim-verification/run.mts", "--dataset", dataset, "--out", out], { timeout: 30_000 }); const summary = JSON.parse(readFileSync(join(out, "summary.json"), "utf8")); assert.equal(summary.historical.turns, 1); assert.equal(summary.historical.sessions, 1); @@ -18,5 +20,5 @@ test("offline pilot writes measured results and preserves an explicit not-run mo assert.equal(summary.historical.spanCandidates, 2); assert.equal(summary.historical.exactSpans, 2); assert.equal(summary.jev.status, "not_run"); - assert.equal(summary.datasetSha256.length, 64); + assert.equal(summary.datasetSha256, createHash("sha256").update(readFileSync(dataset)).digest("hex")); }); diff --git a/evals/lib/fixture-ops.mjs b/evals/lib/fixture-ops.mjs index b384bcf4a..cb5091318 100644 --- a/evals/lib/fixture-ops.mjs +++ b/evals/lib/fixture-ops.mjs @@ -55,7 +55,7 @@ export function parseJsonFile(filePath) { try { return JSON.parse(fs.readFileSync(filePath, "utf8")); } catch (err) { - throw new Error(`${filePath}: unreadable JSON (${err.message})`); + throw new Error(`${filePath}: unreadable JSON (${err.message})`, { cause: err }); } } @@ -157,6 +157,7 @@ export async function loadMetricsModule() { throw new Error( "cannot load eval-metrics: no dist/harness/eval-metrics.js (current `npm run build` does not emit it) and the " + `tsx fallback failed — run npm install so the repo's tsx devDependency can load src/harness/eval-metrics.ts (${err.message})`, + { cause: err }, ); } } diff --git a/evals/tool-output-efficiency/classify.py b/evals/tool-output-efficiency/classify.py index 4cd192f05..dac955f7c 100644 --- a/evals/tool-output-efficiency/classify.py +++ b/evals/tool-output-efficiency/classify.py @@ -1,13 +1,13 @@ """Conservative tool-family classification; mixed shell calls stay mixed.""" import ast, json, re from tokens import serialize -def arguments(value): +def _arguments(value): if isinstance(value, str): try: return json.loads(value) except ValueError: return value return value def commands(name, value): - value = arguments(value) + value = _arguments(value) if isinstance(value, dict): return [str(value.get("cmd") or value.get("command") or "")] text = str(value) pattern = r"""(?:["']?cmd["']?|["']?command["']?)\s*:\s*("(?:\\.|[^"\\])*"|'(?:\\.|[^'\\])*'|\x60[^\x60]*\x60)""" @@ -17,7 +17,7 @@ def commands(name, value): try: found.append(literal[1:-1] if literal[0] == chr(96) else ast.literal_eval(literal)) except (ValueError, SyntaxError): found.append(literal[1:-1]) return found or [text] -def shell_category(command): +def _shell_category(command): cats = set() pattern = r"(?:^|[;\n|&])\s*(?:(?:[A-Za-z_]\w*=\S+|command|env)\s+)*(?:[^\s;|&]*/)?(cat|rg|grep|head|tail|ls|find|wc|stat|sed|awk|git|npm|pnpm|yarn|bun|npx|vitest|pytest|jest|tsgo|tsc|eslint|gitleaks|apply_patch|tee|rm|mv|cp|mkdir|touch|jq)\b([^\n;|&]*)" for match in re.finditer(pattern, command): @@ -41,14 +41,14 @@ def category(name, value): if name in ("grep", "glob", "search_files", "list_directory"): return "search" if name in ("edit", "write", "multiedit", "multi_edit", "apply_patch", "edit_file", "write_file"): return "edits" if name in ("exec", "bash", "exec_command", "shell", "shell_command", "run_command"): - cats = {shell_category(c) for c in commands(name, value)} + cats = {_shell_category(c) for c in commands(name, value)} if "tools.apply_patch" in str(value): cats.add("edits") return next(iter(cats)) if len(cats) == 1 else "mixed" if any(word in name for word in ("read", "search", "fetch", "query", "get_")): return "structured_data" return "other" def edited_paths(name, value): from tokens import paths - data = arguments(value) + data = _arguments(value) if name.lower() in ("edit", "write", "multiedit", "multi_edit", "edit_file", "write_file"): return paths(serialize(data)) text = value if isinstance(value, str) else serialize(value) if "apply_patch" in name or "*** Update File:" in text or "*** Add File:" in text: diff --git a/evals/tool-output-efficiency/cli.test.mts b/evals/tool-output-efficiency/cli.test.mts index 390db60f8..971ba2eab 100644 --- a/evals/tool-output-efficiency/cli.test.mts +++ b/evals/tool-output-efficiency/cli.test.mts @@ -4,12 +4,15 @@ import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs"; import { tmpdir } from "node:os"; import { join } from "node:path"; import { spawnSync } from "node:child_process"; -test("CLI retains exact bytes and supports full recovery without a model",()=>{ +test("CLI retains exact bytes and supports full recovery without a model", { timeout: 60_000 }, () => { const dir=mkdtempSync(join(tmpdir(),"output-cli-")); try { const input=join(dir,"input.txt"); const text="😀\r\n"+"sample line\n".repeat(100); writeFileSync(input,text); - const run=(args:string[])=>spawnSync(process.execPath,["--import","tsx","evals/tool-output-efficiency/cli.mts",...args],{encoding:"utf8"}); + const run = (args: string[]) => spawnSync(process.execPath, ["--import", "tsx", "evals/tool-output-efficiency/cli.mts", ...args], { + encoding: "utf8", + timeout: 15_000, + }); const captured=run(["capture","--store",dir,"--input",input,"--source","fixture","--version","v1","--call-id","c","--budget-chars","100"]); assert.equal(captured.status,0,captured.stderr); const view=JSON.parse(captured.stdout); @@ -17,6 +20,8 @@ test("CLI retains exact bytes and supports full recovery without a model",()=>{ const expanded=run(["expand","--store",dir,"--id",view.receiptId]); assert.equal(expanded.status,0,expanded.stderr); assert.equal(expanded.stdout,readFileSync(input,"utf8")); const bad=run(["expand","--store",dir,"--id","../input"]); - assert.notEqual(bad.status,0); + assert.ifError(bad.error); + assert.equal(bad.status, 1); + assert.match(bad.stderr, /Invalid receipt ID/); } finally { rmSync(dir,{recursive:true,force:true}); } }); diff --git a/evals/tool-output-efficiency/native.py b/evals/tool-output-efficiency/native.py index 5eb519c32..ad9d7aa5f 100644 --- a/evals/tool-output-efficiency/native.py +++ b/evals/tool-output-efficiency/native.py @@ -2,7 +2,7 @@ import collections, json, re from classify import category from tokens import digest, serialize, text_of -def records(item, audit): +def _records(item, audit): with open(item["path"], "rb") as handle: remaining = item["bytes"] while remaining: @@ -13,7 +13,7 @@ def records(item, audit): try: value = json.loads(raw) except (ValueError, UnicodeError): audit["malformed"] += 1; continue if isinstance(value, dict): yield value -class NativeEventReader: +class _NativeEventReader: def __init__(self): self.audit = collections.Counter(); self.seen = set(); self.calls = {}; self.cells = {}; self.procs = {} self.usage = {}; self.fallback = {}; self.epoch = 0; self.model = "unknown" @@ -101,8 +101,8 @@ def summary(self, provider): return {"kind":"end", "usage":dict(totals), "peak_input":peak, "audit":dict(self.audit), "compactions":self.epoch} def events(item): - reader = NativeEventReader() - for line_number, row in enumerate(records(item, reader.audit), 1): + reader = _NativeEventReader() + for line_number, row in enumerate(_records(item, reader.audit), 1): emitted = reader.codex_row(row, line_number) if item["provider"] == "codex" else reader.claude_row(row) for event in emitted: yield {**event, "epoch":reader.epoch, "timestamp":row.get("timestamp", ""), "line":line_number} diff --git a/evals/tool-output-efficiency/tokens.py b/evals/tool-output-efficiency/tokens.py index fe6bb31b0..e22334352 100644 --- a/evals/tool-output-efficiency/tokens.py +++ b/evals/tool-output-efficiency/tokens.py @@ -39,6 +39,6 @@ def shingles(text): value = " ".join(words[i:i+8]) if len(value) >= 32: yield hashlib.blake2b(value.encode(), digest_size=8).digest() -PATH = re.compile(r"(?:[A-Za-z0-9_@.()+-]+/)*[A-Za-z0-9_@()+-]+\.(?:[cm]?[jt]sx?|py|rs|go|java|json|md|toml|ya?ml|sh|txt|css|html)\b") +_PATH = re.compile(r"(?:[A-Za-z0-9_@.()+-]+/)*[A-Za-z0-9_@()+-]+\.(?:[cm]?[jt]sx?|py|rs|go|java|json|md|toml|ya?ml|sh|txt|css|html)\b") def paths(text): - return {p.split("interlinked-cli/",1)[-1] for p in PATH.findall(text)} + return {p.split("interlinked-cli/",1)[-1] for p in _PATH.findall(text)} diff --git a/protocol/mutation-v3/contract-digest.json b/protocol/mutation-v3/contract-digest.json index 1c72c46fc..3ea0abe84 100644 --- a/protocol/mutation-v3/contract-digest.json +++ b/protocol/mutation-v3/contract-digest.json @@ -19,5 +19,5 @@ "src/harness/mutation/protocol-v3/verify.ts" ], "files": 26, - "digest": "b6b38a69932db3fa930299bc59c78c3a6888f5938cd707451a3730164cbdd7b3" + "digest": "ed007addda7c8d50916686f563811d159346b220b9493973077cdbba5503f6a4" } diff --git a/scripts/build-atomic.test.mjs b/scripts/build-atomic.test.mjs index 4d4e046fd..a363850d2 100644 --- a/scripts/build-atomic.test.mjs +++ b/scripts/build-atomic.test.mjs @@ -399,17 +399,21 @@ describe("runtime-preserving distribution build", () => { await entered; const second = buildAtomically({ root, - leaseOptions, + leaseOptions: { + ...leaseOptions, + async sleep() { + // The second builder reached the occupied lease. + resumeFirst(); + await first; + }, + }, populateStage: (_projectRoot, stage) => { populateCalls += 1; writeNested(stage, "hook-entry.js", `${NODE_SHEBANG}\n// duplicate compiler\n`, 0o755); }, validateStage: () => {}, }); - await new Promise((resolveDelay) => setTimeout(resolveDelay, 20)); - resumeFirst(); - - const [firstResult, secondResult] = await Promise.all([first, second]); + const [firstResult, secondResult] = await Promise.all([first, second.finally(resumeFirst)]); expect(firstResult).toEqual({ coalesced: false }); expect(secondResult).toEqual({ coalesced: true }); expect(populateCalls).toBe(1); diff --git a/scripts/check-docs.mjs b/scripts/check-docs.mjs index de005b202..ebaa8b327 100755 --- a/scripts/check-docs.mjs +++ b/scripts/check-docs.mjs @@ -48,6 +48,7 @@ const DOCS = [ join(ROOT, "landing/public/index.html"), join(ROOT, "README.md"), join(ROOT, "CLAUDE.md"), + join(ROOT, "AGENTS.md"), join(ROOT, "docs/harness.md"), ]; diff --git a/scripts/cli-reference-help.test.mts b/scripts/cli-reference-help.test.mts new file mode 100644 index 000000000..03673f99b --- /dev/null +++ b/scripts/cli-reference-help.test.mts @@ -0,0 +1,57 @@ +import { readFileSync } from "node:fs"; +import { Command } from "commander"; +import { describe, expect, it } from "vitest"; +import { registerNetworkCommands } from "../src/registrars/network.js"; +import { cliReferenceHelp } from "./cli-reference-help.js"; + +function commandTree(write: (text: string) => void): Command { + const root = new Command("example").exitOverride() + .configureOutput({ writeOut: write, getOutHelpWidth: () => 80 }) + .configureHelp({ showGlobalOptions: true }) + .option("--global", "Root option") + .addHelpText("afterAll", "\nInterface boundaries:\nShared footer"); + const group = root.command("group").alias("g").option("--parent", "Group option"); + group.command("show").alias("s").description("Show the current project") + .addHelpText("after", () => `Project directory: ${process.cwd()}`) + .action(() => { throw new Error("help executed the command"); }); + return root; +} + +describe("CLI reference help", () => { + it("reproduces the published network group and two leaf help blocks byte for byte", () => { + const reference = readFileSync(new URL("../docs/generated/cli-reference.md", import.meta.url), "utf8"); + const tree = new Command("interlinked"); + registerNetworkCommands(tree); + for (const path of [["network"], ["network", "check"], ["network", "codex-profile"]]) { + const heading = path.length === 1 ? "## Network" : "### " + path.join(" "); + const block = reference.split(heading + "\n\n```\n")[1]?.split("\n```")[0]; + expect(cliReferenceHelp(tree, path)).toBe(block); + } + }); + + it("matches parsed CLI help for root, nested commands and aliases across repeated renders", () => { + let leaked = ""; + const tree = commandTree(text => { leaked += text; }); + for (const path of [[], ["group"], ["g", "s"], ["group", "show"], []]) { + let raw = ""; + const cli = commandTree(text => { raw += text; }); + expect(() => cli.parse([...path, "--help"], { from: "user" })).toThrow("(outputHelp)"); + const expected = raw.split("\nInterface boundaries:")[0]!.trim().replaceAll(process.cwd(), ""); + expect(cliReferenceHelp(tree, path)).toBe(expected); + } + const nested = cliReferenceHelp(tree, ["g", "s"]); + expect(nested).toContain("--global"); + expect(nested).toContain("--parent"); + expect(nested).toContain("Project directory: "); + expect(leaked).toBe(""); + tree.outputHelp(); + expect(leaked).toContain("Shared footer"); + }); + + it("reports the entire unknown path, even when a parent or leaf exists", () => { + const tree = commandTree(() => {}); + for (const path of [["missing"], ["g", "missing"], ["group", "show", "missing"]]) { + expect(() => cliReferenceHelp(tree, path)).toThrow(`Unknown documentation command: example ${path.join(" ")}`); + } + }); +}); diff --git a/scripts/cli-reference-help.ts b/scripts/cli-reference-help.ts new file mode 100644 index 000000000..f6cfb5a88 --- /dev/null +++ b/scripts/cli-reference-help.ts @@ -0,0 +1,23 @@ +import type { Command } from "commander"; + +/** Render a documented command without parsing argv or executing its action. */ +export function cliReferenceHelp(program: Command, path: readonly string[]): string { + let command = program; + for (const token of path) { + const child = command.commands.find(candidate => candidate.name() === token || candidate.aliases().includes(token)); + if (!child) throw new Error(`Unknown documentation command: ${[program.name(), ...path].join(" ")}`); + command = child; + } + + const previous = { ...command.configureOutput() }; + let raw = ""; + try { + // The published reference uses Commander's 80-column non-terminal layout. + command.configureOutput({ writeOut: text => { raw += text; }, getOutHelpWidth: () => 80 }); + command.outputHelp(); + } finally { + command.configureOutput(previous); + } + const footer = raw.indexOf("\nInterface boundaries:"); + return (footer < 0 ? raw : raw.slice(0, footer)).trim().replaceAll(process.cwd(), ""); +} diff --git a/scripts/gen-shadow-corpus-rows.test.mts b/scripts/gen-shadow-corpus-rows.test.mts index 9d0780837..9da2ebcd6 100644 --- a/scripts/gen-shadow-corpus-rows.test.mts +++ b/scripts/gen-shadow-corpus-rows.test.mts @@ -13,6 +13,11 @@ describe("PROJECTION_ROWS — positive (must hold)", () => { }); it("P2: no row lists the same path as both touched and omitted", () => { + expect(PROJECTION_ROWS).toContainEqual(expect.objectContaining({ + id: "apply-patch-move-destination-omitted-rejects", + omits: ["src/renamed.ts"], + touches: ["src/keep.ts"], + })); for (const item of PROJECTION_ROWS) { expect(item.omits.filter((path) => item.touches.includes(path))).toEqual([]); } diff --git a/scripts/generate-docs.test.ts b/scripts/generate-docs.test.mts similarity index 78% rename from scripts/generate-docs.test.ts rename to scripts/generate-docs.test.mts index ff00d56f7..3a4246a36 100644 --- a/scripts/generate-docs.test.ts +++ b/scripts/generate-docs.test.mts @@ -2,7 +2,7 @@ import { describe, expect, it } from "vitest"; import { STRUCTURAL_CHECK_META } from "../src/harness/check-metadata.js"; import { getBuiltinRules, getDefaultConfig } from "../src/harness/rules-loader.js"; -// `scripts/generate-docs.ts` is a one-shot code-generation script run via +// `scripts/generate-docs.ts` is a code-generation script run via // `npm run docs`. It reads live data from the harness registry // (getBuiltinRules, STRUCTURAL_CHECK_META, getDefaultConfig) and writes // markdown under `docs/generated/`. These tests pin the shape of the data @@ -23,10 +23,16 @@ describe("scripts/generate-docs — input-shape invariants", () => { it("getDefaultConfig has quality_checks + structural_checks + diff_aware sections", () => { const cfg = getDefaultConfig(); - expect(cfg).toBeTruthy(); - expect(cfg.quality_checks).toBeTruthy(); - expect(cfg.structural_checks).toBeTruthy(); - expect(Object.keys(cfg.quality_checks).length).toBeGreaterThan(0); + expect(cfg.quality_checks.typescript).toMatchObject({ + severity: "error", + file_types: expect.arrayContaining([".ts", ".tsx"]), + }); + expect(cfg.structural_checks.export_surface).toBe(true); + expect(cfg.diff_aware).toMatchObject({ + complexity: "edit_region", + no_test_file: "new_files_only", + undefined_env_vars: "edit_content", + }); }); it("STRUCTURAL_CHECK_META entries have name+description+tier", () => { diff --git a/scripts/generate-docs.ts b/scripts/generate-docs.ts index 336fbc909..a39530198 100644 --- a/scripts/generate-docs.ts +++ b/scripts/generate-docs.ts @@ -11,10 +11,12 @@ import { existsSync, mkdirSync, writeFileSync } from "node:fs"; import { join } from "node:path"; +import packageJson from "../package.json" with { type: "json" }; +import { buildProgram } from "../src/cli-program.js"; +import { cliReferenceHelp } from "./cli-reference-help.js"; import { STRUCTURAL_CHECK_META } from "../src/harness/check-metadata.js"; import { METRIC_DEFS } from "../src/harness/metric-caps.js"; import { renderDataCatalogMarkdown } from "../src/lib/data/catalog.js"; -import { isJsonObject } from "../src/lib/json-types.js"; // Import data structures from the harness import { getBuiltinRules, getDefaultConfig } from "../src/harness/rules-loader.js"; import { ALL_SEQUENCE_DETECTORS } from "../src/harness/sequence-checks/registry.js"; @@ -304,49 +306,14 @@ function generateConfigReference(): string { // CLI Command Reference (from commander --help output) // =========================================== -import { execFileSync } from "node:child_process"; - -function getHelpOutput(args: string[]): string { - let raw: string; - try { - raw = execFileSync( - process.execPath, - ["--import", "tsx", join(import.meta.dirname, "..", "src", "index.ts"), ...args, "--help"], - { - encoding: "utf-8", - timeout: 10_000, - env: { ...process.env, INTERLINKED_SKIP_IMPLICIT_ENTRY: "1" }, - }, - ).trim(); - } catch (err) { - // Commander writes help to stdout and exits with code 0, but execFileSync - // may throw if the process exits before consuming all stdin. Try stderr fallback. - raw = helpOutputFromError(err); - } - // Strip the repeated "Interface boundaries" / "Quick start" footer that commander appends - const footerIdx = raw.indexOf("\nInterface boundaries:"); - const withoutFooter = footerIdx >= 0 ? raw.slice(0, footerIdx).trimEnd() : raw; - return sanitizeHelpOutput(withoutFooter); -} - -function helpOutputFromError(error: unknown): string { - if (!isJsonObject(error)) return ""; - const stdout = typeof error.stdout === "string" ? error.stdout : ""; - const stderr = typeof error.stderr === "string" ? error.stderr : ""; - return (stdout || stderr).trim(); -} - -function sanitizeHelpOutput(output: string): string { - return output.split(process.cwd()).join(""); -} - // Commands with subcommands — mirror the groups registered in src/index.ts. const CLI_COMMAND_SUBCOMMANDS: Record = { network: ["check", "codex-profile"], data: ["catalog", "health", "status", "index", "scan", "lab", "search", "show", "investigate", "sessions", "files", "checks", "usage", "schema", "suggestions", "recurrence-inventory", "configure", "maintain", "audit"], structure: ["init", "scan", "status", "accept", "doctor", "baseline"], lint: ["scan", "import", "check"], - metrics: ["coupling", "arch", "rework", "complexity", "split-plan", "score", "diagnostics", "diagnostics compare", "catalog", "explain", "compare", "corpus", "gates", "deletions", "deletions validate", "evidence", "evidence status", "evidence identity", "evidence import", "evidence run", "coverage", "coverage status", "coverage warm", "decisions", + metrics: ["coupling", "arch", "rework", "complexity", "split-plan", "score", "standards", "policies", "policies export", "policies inspect", "policies evaluate", "diagnostics", "diagnostics compare", "catalog", "explain", "compare", "corpus", "gates", "deletions", "deletions validate", "evidence", "evidence status", "evidence identity", "evidence import", "evidence run", "coverage", "coverage status", "coverage warm", "decisions", + "decisions findings", ...["discover", "prepare", "questions", "plan", "assess", "show", "labels", "review"].map(action => `decisions findings ${action}`), ...["init", "catalog", "prepare", "snapshot", "candidates", "retrieve", "pilot", "labels", "join-labels", "probe", "measure", "review", "embed", "geometry", "audit", "replay", "diff"].map(action => `decisions ${action}`)], simplify: ["scan", "review", "audit", "status"], tests: ["plan", "run", "status", "suite", "readiness", "review", "contracts", "contracts import", "contracts inspect", "contracts run"], @@ -367,6 +334,7 @@ const CLI_COMMAND_SUBCOMMANDS: Record = { }; function generateCliReference(): string { + const program = buildProgram(packageJson.version); const lines: string[] = [ "", "# Interlinked CLI Command Reference", @@ -374,7 +342,7 @@ function generateCliReference(): string { ]; // Top-level help - const topHelp = getHelpOutput([]); + const topHelp = cliReferenceHelp(program, []); lines.push("## Overview", "", "```", topHelp, "```", ""); // Extract top-level command names from help output @@ -401,7 +369,7 @@ function generateCliReference(): string { ]; for (const cmd of commandNames) { - const cmdHelp = getHelpOutput([cmd]); + const cmdHelp = cliReferenceHelp(program, [cmd]); if (!cmdHelp) continue; const title = cmd.charAt(0).toUpperCase() + cmd.slice(1); @@ -410,7 +378,7 @@ function generateCliReference(): string { const subs = CLI_COMMAND_SUBCOMMANDS[cmd]; if (subs) { for (const sub of subs) { - const subHelp = getHelpOutput([cmd, ...sub.split(" ")]); + const subHelp = cliReferenceHelp(program, [cmd, ...sub.split(" ")]); if (!subHelp) continue; lines.push(`### ${cmd} ${sub}`, "", "```", subHelp, "```", ""); } @@ -424,7 +392,7 @@ function generateCliReference(): string { ]; lines.push("## Other Commands", ""); for (const cmd of standaloneCommands) { - const cmdHelp = getHelpOutput([cmd]); + const cmdHelp = cliReferenceHelp(program, [cmd]); if (!cmdHelp) continue; lines.push(`### ${cmd}`, "", "```", cmdHelp, "```", ""); } diff --git a/scripts/git-hooks/pre-push b/scripts/git-hooks/pre-push index 89b363f99..c51d5d387 100755 --- a/scripts/git-hooks/pre-push +++ b/scripts/git-hooks/pre-push @@ -233,6 +233,12 @@ run_gate() { elif (cd "$gate_dir" && node -e 'process.exit((require("./package.json").scripts||{}).build?0:1)'); then (cd "$gate_dir" && bounded npm run build) || return 1 fi + if [ -f "$gate_dir/test/test_opf_sidecar.py" ]; then + (cd "$gate_dir" && python3 -B -m unittest discover -s test -p 'test_*.py') || { + report_gate_failure "Python sidecar protocol" + return 1 + } + fi cov_files="$(printf '%s\n' "$changed_paths" | grep -E '^src/.*\.(ts|tsx|js|mjs|cjs)$' | LC_ALL=C sort -u | paste -sd, - || true)" if [ -z "$cov_files" ]; then (cd "$gate_dir" && CI=1 bounded npm test -- --maxWorkers="$test_workers") || { diff --git a/scripts/semantic-study-drivers.test.mjs b/scripts/semantic-study-drivers.test.mjs new file mode 100644 index 000000000..44ab424cb --- /dev/null +++ b/scripts/semantic-study-drivers.test.mjs @@ -0,0 +1,74 @@ +import { spawnSync } from "node:child_process"; +import { existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs"; +import { tmpdir } from "node:os"; +import { join } from "node:path"; +import { fileURLToPath } from "node:url"; +import { afterEach, expect, it } from "vitest"; + +const roots = []; +const fresh = () => { + const directory = mkdtempSync(join(tmpdir(), "study-driver-")); + roots.push(directory); + return directory; +}; +afterEach(() => { + for (const path of roots.splice(0)) rmSync(path, { recursive: true, force: true }); +}); + +function run(driver, action, runDir, cwd = fresh()) { + const path = fileURLToPath(new URL(`../semantic-relations/${driver}.ts`, import.meta.url)); + return spawnSync(process.execPath, ["--import", import.meta.resolve("tsx"), path, action, runDir], + { cwd, encoding: "utf8", timeout: 35000 }); +} + +it("describes both runtime recipes without creating a study or invoking a model", () => { + const root = fresh(); + for (const driver of ["runtime-evaluation", "runtime-probes"]) { + const result = run(driver, "--help", root); + expect(result.stderr).toBe(""); + expect(result.status).toBe(0); + expect(result.stdout).toContain("RUN_DIR"); + } + expect(readdirSync(root)).toEqual([]); +}); + +it("requires the fresh run's inputs before copying source or initializing a capture repository", () => { + const root = fresh(); + const result = run("runtime-evaluation", "prepare", root); + expect(result.status).not.toBe(0); + expect(result.stderr).toContain(join(root, "heap-measurements.json")); + expect(existsSync(join(root, "repo"))).toBe(false); + writeFileSync(join(root, "heap-measurements.json"), "{}"); + writeFileSync(join(root, "engines.json"), "{}"); + const malformed = run("runtime-evaluation", "prepare", root); + expect(malformed.stderr).toContain("array of engine definitions"); + expect(existsSync(join(root, "repo"))).toBe(false); +}); + +it("preserves an existing probe result and refuses an unsafe run label before launching children", () => { + const root = fresh(), study = join(root, "study"); + mkdirSync(study); + const resultFile = join(study, "runtime-probes-local.json"); + writeFileSync(resultFile, "previous evidence"); + for (const label of ["local", "../outside"]) { + const result = run("runtime-probes", label, root); + expect(result.status).not.toBe(0); + expect(result.stderr).toContain(label === "local" ? "already exists" : "Invalid probe label"); + } + expect(readFileSync(resultFile, "utf8")).toBe("previous evidence"); + expect(readdirSync(root)).toEqual(["study"]); +}); + +it("writes observed local child outcomes into the selected run directory", () => { + const root = fresh(); + const repository = fileURLToPath(new URL("../", import.meta.url)); + const result = run("runtime-probes", "local", root, repository); + expect(result.status, result.stderr).toBe(0); + const report = JSON.parse(readFileSync(join(root, "study/runtime-probes-local.json"), "utf8")); + const reports = new Map(report.results.map(row => [row.name, JSON.parse(row.stdout.trim())])); + expect(reports.get("success").report).toMatchObject({ exitCode: 0, verdict: "exit" }); + expect(reports.get("failure").report).toMatchObject({ exitCode: 3, verdict: "exit" }); + expect(reports.get("external-signal").report).toMatchObject({ exitCode: 75, verdict: "interrupted" }); + expect(reports.get("own-75").report).toMatchObject({ exitCode: 75, verdict: "exit" }); + expect(readdirSync(join(root, "probes"))).toHaveLength(1); +}, 45000); diff --git a/semantic-relations/README.md b/semantic-relations/README.md index 1ed8b8eb0..ca5119757 100644 --- a/semantic-relations/README.md +++ b/semantic-relations/README.md @@ -101,8 +101,14 @@ truth. No learned threshold, deployment qualification or automatic alert is impl ## Reproduce the exploratory study -From a source checkout, run `node --import tsx semantic-relations/run-experiments.ts -prepare `, then `assess fixtures|A|B`. +From the repository root, set `STUDY_DIR` to a new directory for this run, then +run `node --import tsx semantic-relations/run-experiments.ts prepare "${STUDY_DIR:?}"`. +Use the same directory for `assess fixtures|A|B`. +Preparation reads the decision-metrics `ollamaUrl` and records it in the frozen +engine configuration. It resolves the `claude` executable through `PATH` and +records its reported version in the engine identity. +Finishing preparation also requires the original canary, model listing and two +preflight JSON files under `scratch/semantic-relations-implementation/`. The script freezes 16 executed mechanism fixtures and 200 cases each for A and B, with named backends and bounded spend. The local study retains the frozen inputs, blind Astra references, actual backend outputs, candidate coverage and failure records. @@ -120,11 +126,20 @@ Source is always read from the pinned revision; `--exploratory` only changes pol loading. The runtime study captures dirty source in a separate Git repository without committing or staging the developer's working tree. -The completed study also includes `run-haiku-arm.ts`, `run-targeted-coupling.ts`, -`run-comparison-controls.ts`, `run-haiku-comparison.ts` and `run-neutral-controls.ts`. +The supplemental drivers below read earlier stages from the same study directory. +They can call the configured model providers. Run each only when its prerequisites +are present in your own study and its inference budget is available. + +| Driver, run from the repository root | Required inputs and purpose | +|---|---| +| `node --import tsx semantic-relations/run-targeted-coupling.ts "${STUDY_DIR:?}"` | Reads `A-plan.json` and the independently prepared `B-targeted-cases.json` to freeze and assess the targeted cohort. | +| `node --import tsx semantic-relations/run-haiku-arm.ts "${STUDY_DIR:?}" A` | Reads the frozen input and labels for one cohort. Choose `A`, `B`, `fixtures` or `B-targeted`. | +| `node --import tsx semantic-relations/run-comparison-controls.ts "${STUDY_DIR:?}"` | Requires completed A and B runs and the fixture plan. Records paired controls and repeat observations. | +| `node --import tsx semantic-relations/run-haiku-comparison.ts "${STUDY_DIR:?}"` | Requires both Haiku arm results, the comparison protocol and paired inputs. Writes the Haiku comparison and repeats. | +| `node --import tsx semantic-relations/run-neutral-controls.ts "${STUDY_DIR:?}" fixtures` | Runs the neutral-ID fixture arm. The alternative `C` mode consumes existing Haiku and comparison inputs. | + The neutral control preserves source/scenario bytes while removing descriptive fixture -IDs from model-visible metadata; original cue-exposed results remain separate. Supplemental runs preserve -their own input freezes and protocol amendments. Regenerate the numerical tables +IDs from model-visible metadata. Regenerate the numerical tables without making model calls with `node --import tsx semantic-relations/summarize-experiments.ts`. Do not rerun a study into an existing immutable input/result directory; use a new destination and preserve failed attempts alongside any full-cohort retry. diff --git a/semantic-relations/run-experiments.ts b/semantic-relations/run-experiments.ts index eff7e38ae..4f26742fe 100644 --- a/semantic-relations/run-experiments.ts +++ b/semantic-relations/run-experiments.ts @@ -12,16 +12,19 @@ import { auditRelations } from "../src/lib/decision-metrics/relation-audit.js"; import { fixtureRelationPlan } from "../src/lib/decision-metrics/relation-fixtures.js"; import { naturalRelationStudies, compactBlindReview } from "../src/lib/decision-metrics/relation-study.js"; import { haikuIdentity } from "../src/lib/decision-metrics/relation-haiku.js"; +import { readDecisionConfig } from "../src/lib/decision-metrics/config.js"; import { RELATION_CONTRACTS } from "../src/lib/decision-metrics/relation-contracts.js"; import type { EngineSpec } from "../src/harness/semantic-graph/relation-types.js"; const root = resolve(process.cwd()), action = process.argv[2] ?? "prepare", study = resolve(process.argv[3] ?? "semantic-relations/studies/2026-10-27-exploratory"); mkdirSync(study, { recursive: true }); if (action === "prepare") { + const haikuCommand = "claude"; + const ollamaEndpoint = readDecisionConfig(root).ollamaUrl; const engines: EngineSpec[] = [ - { id: "D", backend: "ollama", model: "clef-flash:9b", identity: "unavailable:not-installed", command: "thinkthen", endpoint: "http://127.0.0.1:11434", effort: null, maxCalls: 450, maxUsd: 1, timeoutMs: 30000, band: [.2,.8] }, + { id: "D", backend: "ollama", model: "clef-flash:9b", identity: "unavailable:not-installed", command: "thinkthen", endpoint: ollamaEndpoint, effort: null, maxCalls: 450, maxUsd: 1, timeoutMs: 30000, band: [.2,.8] }, { id: "J", backend: "typesafe", model: "jev-1.14.0", identity: "jev-1.14.0", command: null, endpoint: "https://api.typesafe.ai/v1/systemone", effort: null, maxCalls: 450, maxUsd: 2, timeoutMs: 20000, band: [.2,.8] }, - { id: "H", backend: "haiku", model: "claude-haiku-5-5", identity: haikuIdentity("/Users/quentincody/.local/bin/claude", "claude-haiku-5-5"), command: "/Users/quentincody/.local/bin/claude", endpoint: null, effort: "low", maxCalls: 450, maxUsd: 8, timeoutMs: 90000, band: [.2,.8] }, + { id: "H", backend: "haiku", model: "claude-haiku-5-5", identity: haikuIdentity(haikuCommand, "claude-haiku-5-5"), command: haikuCommand, endpoint: null, effort: "low", maxCalls: 450, maxUsd: 8, timeoutMs: 90000, band: [.2,.8] }, ]; writeArtifactFile(join(study, "engines.json"), engines); const revision = gitText(root, ["rev-parse", "HEAD"]), until = gitText(root, ["show", "-s", "--format=%cI", revision]); diff --git a/semantic-relations/runtime-evaluation.ts b/semantic-relations/runtime-evaluation.ts index 476e0bf23..0ff6dd89c 100644 --- a/semantic-relations/runtime-evaluation.ts +++ b/semantic-relations/runtime-evaluation.ts @@ -4,14 +4,18 @@ import { dirname, join, resolve } from "node:path"; import { hash, textHash } from "../src/harness/semantic-graph/relation-core.js"; import { haikuIdentity } from "../src/lib/decision-metrics/relation-haiku.js"; import { loadRelationArtifact } from "../src/harness/semantic-graph/relation-freeze.js"; -import { parseRelationRun } from "../src/harness/semantic-graph/relation-codec.js"; -import type { EngineSpec, InvariantDefinition, RelationPlan } from "../src/harness/semantic-graph/relation-types.js"; +import { parseEngine, parseRelationRun } from "../src/harness/semantic-graph/relation-codec.js"; +import type { InvariantDefinition, RelationPlan } from "../src/harness/semantic-graph/relation-types.js"; const root = resolve(process.cwd()); -const study = join(root, "semantic-relations/studies/2026-10-27-runtime"); -const repo = join(root, "scratch/semantic-relations-runtime/repo"); const action = process.argv[2] ?? "prepare"; -mkdirSync(study, { recursive: true }); +if (action === "--help") { + console.log("Usage: runtime-evaluation.ts ACTION [RUN_DIR]\nA custom RUN_DIR needs heap-measurements.json and engines.json. The recipe writes its study and source capture in study/ and repo/. Assessment actions can call configured model providers."); + process.exit(0); +} +const runDir = process.argv[3] ? resolve(process.argv[3]) : undefined; +const study = runDir ? join(runDir, "study") : join(root, "semantic-relations/studies/2026-10-27-runtime"); +const repo = runDir ? join(runDir, "repo") : join(root, "scratch/semantic-relations-runtime/repo"); const save = (name: string, value: unknown) => writeFileSync(join(study, name), `${JSON.stringify(value, null, 2)}\n`); const read = (name: string): T => JSON.parse(readFileSync(join(study, name), "utf8")) as T; const cli = join(root, "dist/index.js"); @@ -67,8 +71,16 @@ const definitions: InvariantDefinition[] = [ }, ]; if (action === "prepare") { + if (runDir && (existsSync(repo) || existsSync(join(study, "protocol.json")) || existsSync(join(study, "engines.json")))) { + throw new Error(`Runtime capture or study inputs already exist in ${runDir}`); + } if (existsSync(join(repo, ".git"))) throw new Error("runtime capture already exists; do not overwrite its baseline"); - mkdirSync(repo, { recursive: true }); + const heap = readFileSync(join(runDir ?? join(root, "scratch/semantic-relations-runtime"), "heap-measurements.json")); + const engines: unknown = JSON.parse(readFileSync(join(runDir ?? join(root, "semantic-relations/studies/2026-10-27-exploratory"), "engines.json"), "utf8")); + if (!Array.isArray(engines)) throw new Error("engines.json must contain an array of engine definitions"); + const available = engines.map(parseEngine).filter(e => e.id === "J" || e.id === "H").map(e => ({ ...e, maxCalls: 100, maxUsd: e.id === "J" ? 1 : 2, ...(e.id === "H" ? { identity: haikuIdentity(e.command!, e.model) } : {}) })); + mkdirSync(study, { recursive: true }); + mkdirSync(repo, { recursive: runDir === undefined }); const sources = new Set([ "src/harness/resource-command.ts", "src/harness/resource-cli.ts", "src/harness/resource-budget.ts", "src/harness/resource-wait.ts", "src/harness/resource-watch.ts", "src/harness/node-heap-limit.ts", "src/harness/test-execution.ts", "src/harness/verification-stages.ts", "src/harness/check-engine/spawn-async.ts", "scripts/run-resource-bounded.ts", ]); @@ -79,7 +91,7 @@ if (action === "prepare") { return { file, hash: textHash(readFileSync(join(root, file), "utf8")) }; }); mkdirSync(join(repo, "runtime"), { recursive: true }); - copyFileSync(join(root, "scratch/semantic-relations-runtime/heap-measurements.json"), join(repo, "runtime/heap-measurements.json")); + writeFileSync(join(repo, "runtime/heap-measurements.json"), heap); mkdirSync(join(repo, "semantic-relations"), { recursive: true }); writeFileSync(join(repo, "semantic-relations/invariants.json"), JSON.stringify(definitions)); writeFileSync(join(repo, "semantic-relations/scenarios.json"), "[]\n"); @@ -87,8 +99,6 @@ if (action === "prepare") { git("init", "-q"); git("add", "src", "scripts", "runtime", "semantic-relations"); git("-c", "core.hooksPath=/dev/null", "-c", "user.name=Interlinked evaluation", "-c", "user.email=evaluation@localhost", "commit", "-qm", "Capture current source for isolated runtime evaluation"); const revision = git("rev-parse", "HEAD"), until = git("show", "-s", "--format=%cI", "HEAD"); - const engines = readFileSync(join(root, "semantic-relations/studies/2026-10-27-exploratory/engines.json"), "utf8"); - const available = (JSON.parse(engines) as EngineSpec[]).filter(e => e.id === "J" || e.id === "H").map(e => ({ ...e, maxCalls: 100, maxUsd: e.id === "J" ? 1 : 2, ...(e.id === "H" ? { identity: haikuIdentity(e.command!, e.model) } : {}) })); save("engines.json", available); save("protocol.json", { exploratory: true, objective: "Does the actual CLI add actionable information to ordinary code inspection and executable runtime checks?", sourceCapture: { root: repo, revision, baseRepositoryCommit: execFileSync("git", ["rev-parse", "HEAD"], { cwd: root, encoding: "utf8" }).trim(), captured, digest: hash(captured) }, beforeModelBaseline: { known: ["The earlier five failing test files pass all 76 tests under Node 22.", "Actual V8 heap differs by 144 MiB between installed Node 22 and 25 for the same old-space cap.", "Ordinary Astra review has proposed checking missing executable and external child signal handling; these are not model-discovered findings.", "Current relation workflow requires committed source, custom registry, engines, prepare, freeze, assess and manual JSON inspection."], successCriterion: "Credit a model only for a new verified finding, new necessary test, or materially narrower inspection scope absent from the prior baseline.", limits: "Single-agent sequential dogfood, not randomized timing or independent correctness qualification." }, threshold: .8, until, historySince: "2026-01-01T00:00:00Z", kinds: "invariant_membership,invariant_compatibility,invariant_group", D: "Unavailable adapter/model; no automatic download", noAutomaticGate: true }); } diff --git a/semantic-relations/runtime-probes.ts b/semantic-relations/runtime-probes.ts index eb5838e93..684846281 100644 --- a/semantic-relations/runtime-probes.ts +++ b/semantic-relations/runtime-probes.ts @@ -1,12 +1,23 @@ import { spawn } from "node:child_process"; -import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs"; +import { existsSync, mkdirSync, mkdtempSync, readFileSync, writeFileSync } from "node:fs"; import { join, resolve } from "node:path"; import { pathToFileURL } from "node:url"; -const root = resolve(process.cwd()), study = join(root, "semantic-relations/studies/2026-10-27-runtime"); -const directory = join(root, "scratch/semantic-relations-runtime/probes"); -mkdirSync(directory, { recursive: true }); const suffix = process.argv[2] ?? "before"; +if (suffix === "--help") { + console.log("Usage: runtime-probes.ts LABEL [RUN_DIR]\nRuns local child-process and supervisor probes. A custom RUN_DIR receives probes/ and study/runtime-probes-LABEL.json."); + process.exit(0); +} +if (!/^[a-zA-Z0-9][a-zA-Z0-9_-]*$/.test(suffix)) throw new Error("Invalid probe label"); +const root = resolve(process.cwd()); +const runDir = process.argv[3] ? resolve(process.argv[3]) : undefined; +const study = runDir ? join(runDir, "study") : join(root, "semantic-relations/studies/2026-10-27-runtime"); +const probeRoot = join(runDir ?? join(root, "scratch/semantic-relations-runtime"), "probes"); +const reportPath = join(study, `runtime-probes-${suffix}.json`); +if (existsSync(reportPath)) throw new Error(`Probe report already exists: ${reportPath}`); +mkdirSync(study, { recursive: true }); +mkdirSync(probeRoot, { recursive: true }); +const directory = mkdtempSync(join(probeRoot, `${suffix}-`)); async function run(name: string, source: string) { const ledger = join(directory, `${name}-${suffix}-ledger.jsonl`); const runner = join(directory, `${name}-${suffix}-runner.mjs`); @@ -41,5 +52,5 @@ for (const [name, text] of [["supervised-external-signal", "process.kill(process const fixture = join(directory, `${name}.mjs`); writeFileSync(fixture, text); results.push(await run(name, `import {superviseResourceCli} from ${JSON.stringify(supervisor)}; console.log(JSON.stringify({supervised:await superviseResourceCli([process.execPath,${JSON.stringify(fixture)},'verify','--timeout','3000']),exitCode:process.exitCode}));`)); } -writeFileSync(join(study, `runtime-probes-${suffix}.json`), `${JSON.stringify({ node: process.version, results }, null, 2)}\n`); +writeFileSync(reportPath, `${JSON.stringify({ node: process.version, results }, null, 2)}\n`, { flag: "wx" }); for (const r of results) console.log(JSON.stringify({ name: r.name, code: r.code, timedOut: r.timedOut, stdout: r.stdout, stderr: r.stderr, ledgerRows: (r.ledger as unknown[]).length })); diff --git a/semantic-relations/studies/2026-10-27-runtime/REPORT.md b/semantic-relations/studies/2026-10-27-runtime/REPORT.md index be1ae56e6..9e0793d84 100644 --- a/semantic-relations/studies/2026-10-27-runtime/REPORT.md +++ b/semantic-relations/studies/2026-10-27-runtime/REPORT.md @@ -208,7 +208,17 @@ Regenerate the derived numerical summary without inference: node --import tsx semantic-relations/summarize-runtime.ts ``` -`runtime-evaluation.ts` and `runtime-probes.ts` retain the executed recipes. Their -study destinations are fixed and existing inputs/results must not be overwritten. -For a new run, copy the recipe and set fresh study and source-capture directories before executing -prepare → assess → cache → repair → repair-assess → compare, then the two controls. +The original recipes used this study and a fixed source-capture directory. To +reproduce them from the repository root, set `RUN_DIR` to a fresh directory. +For the evaluation, place the engine configuration in `RUN_DIR/engines.json` +and the independent heap measurements in `RUN_DIR/heap-measurements.json`. +Build the CLI, then run +`node --import tsx semantic-relations/runtime-evaluation.ts prepare "${RUN_DIR:?}"`. +Use the same run directory for assess, cache, repair, repair-assess, compare and +the controls. Assessment stages can call configured providers. The source capture +lives in `repo/` and the results live in `study/` inside the run directory. + +Run the model-free child-process probes with +`node --import tsx semantic-relations/runtime-probes.ts before "${RUN_DIR:?}"`. +Each label writes a separate `study/runtime-probes-LABEL.json`; a repeat needs +a new label. Pass `--help` to either recipe to inspect the arguments. diff --git a/skills/enforce/SKILL.md b/skills/enforce/SKILL.md index 0b75fc17b..8dda6a256 100644 --- a/skills/enforce/SKILL.md +++ b/skills/enforce/SKILL.md @@ -1,6 +1,6 @@ --- name: enforce -description: "Distill imperative markdown guidance (AGENTS.md, CLAUDE.md, .clinerules/, GEMINI.md, SKILL.md with hard imperatives) into deterministic Interlinked harness hook rules with verbatim source provenance. Invoke as /enforce followed by a local path, directory, GitHub shorthand, or URL — or with no arguments to walk the project. Lexical strength is binding: never/MUST NOT/forbidden distill to block; should not/avoid to ask; should/prefer to advisory; hedged language is skipped. Output goes to .interlinked/distilled-rules.json plus .interlinked/distilled-rules.overrides.json. Lifecycle ops: /enforce list, show, remove, disable, enable, modify, add, reset, --review, --accept. Description-match invocation: make my AGENTS.md enforced, distill rules from this file. Manual invocation only — never auto-fires." +description: "Distill imperative guidance in AGENTS.md, CLAUDE.md, .clinerules/, GEMINI.md, or SKILL.md into deterministic Interlinked guard rules with verbatim source provenance. Invoke as /enforce [path | dir | owner/repo/path | URL], or with no argument to walk the project. Lifecycle: /enforce list|show|remove|disable|enable|modify|add|reset|--review|--accept. Use for: make my AGENTS.md enforced, distill rules from this file. Strength is binding: never/MUST NOT to block, should not/avoid to ask, should/prefer to advisory, hedged skipped. Output: .interlinked/distilled-rules.json. Manual invocation only." --- # /enforce — Make markdown guidance into enforced harness rules @@ -25,60 +25,23 @@ description: "Distill imperative markdown guidance (AGENTS.md, CLAUDE.md, .cline **Where output goes.** Live rules: `.interlinked/distilled-rules.json` (pristine, regenerated each run). User mods: `.interlinked/distilled-rules.overrides.json` (removals, disables, modifications — survives re-distillation). The harness watches both files via `watchFile` and reloads automatically within ~2s — there is no `interlinked harness reload` command. If a daemon is in a degraded state and not picking up changes, `interlinked harness restart` is the only recourse. -**Execution order** (distill path; lifecycle verbs jump straight to §14): - -1. Pre-flight (§11) → 2. Parse args (§1) → 3. Read overrides (§9) → 4. Read prior `distilled-rules.json` (§3) → 5. Discover / resolve targets (§2) → 6. Read each file once (§3) → 7. Classify paragraphs (§4) → 8. Lexical ladder (§5) → 9. Triggers (§6) → 10. Build rule object (§7) → 11. Apply user modifications (§9) → 12. Resolve conflicts (§10) → 13. Self-checks (§12) → 14. Write output (§8) → 15. Print summary (§13). - ---- - -## Common workflows - -### First-time setup on a project - -``` -/enforce # walk the tree, distill what's there, print a report -/enforce list # confirm the rule set looks right - # harness reloads automatically within ~2s (watchFile) -``` - -### Adopt a remote skill (review-first) - -``` -/enforce gh:mattpocock/skills/tdd # fetched, distilled to review-mode by default -/enforce list # inspect what would activate -/enforce --accept # promote review → live -``` - -### A rule is too noisy - -``` -/enforce show # see what fired and why -/enforce modify --action ask --severity medium # downgrade -# or, to keep it on disk but stop enforcing entirely: -/enforce disable -``` - -### Reject a whole source forever - -``` -/enforce remove --source gh:someone/skills/qa -``` - -Adds the group to `removed_groups[]`; stays gone across re-distillation. Undo with `/enforce add --source `. - -### A .md file changed; re-distill - -``` -/enforce # unchanged files skipped via hash; user mods preserved - # harness reloads automatically within ~2s -``` - -### Throw it all away and start fresh - -``` -rm .interlinked/distilled-rules.json .interlinked/distilled-rules.overrides.json -/enforce -``` +**Execution order** (distill path; lifecycle verbs jump straight to [step 14]): + +1. [Run the pre-flight checks][step 11] +2. [Parse arguments][step 1] +3. [Read overrides][step 9] +4. [Read the prior `distilled-rules.json`][step 3] +5. [Discover and resolve targets][step 2] +6. [Read each file once][step 3] +7. [Classify paragraphs][step 4] +8. [Apply the lexical strength ladder][step 5] +9. [Extract triggers][step 6] +10. [Build each rule object][step 7] +11. [Apply user modifications][step 9] +12. [Resolve conflicts][step 10] +13. [Run self-checks][step 12] +14. [Write the output][step 8] +15. [Print the summary][step 13] --- @@ -86,11 +49,11 @@ rm .interlinked/distilled-rules.json .interlinked/distilled-rules.overrides.json Agent-instruction markdown files (AGENTS.md, CLAUDE.md, .clinerules/, .windsurf/rules/, GEMINI.md, etc.) are loaded into the model's context window as hopeful prose. Today the model may or may not follow them. This skill walks the source tree (or just the targets the user named), extracts every concrete imperative from those files, and distills them into typed `GuardRule` entries that the Interlinked harness enforces deterministically at runtime — meaning the agent literally cannot bypass them, regardless of which underlying coding agent is running. -**Distillation, not strict compilation.** The §5 lexical ladder + §6 trigger inference + §12 validation are deterministic — typed inputs, typed outputs, no LLM calls. But §4 paragraph classification (is this prose a hard imperative, soft preference, hedged statement, descriptive context?) requires LLM judgment because there's no formal grammar for "is this an imperative." So the operation is honest extraction-and-codification with provenance, not parser-style mechanical translation. The earlier name "compile" was a generous shorthand; "distill" reflects what's actually happening. The lexical ladder is the deterministic gate: if a paragraph contains no §5 marker, the classifier MUST drop it. The distiller never invents a rule from unmarked prose, and every rule carries a verbatim `source.quote` so the entire pipeline is auditable. +**Distillation, not strict compilation.** The [step 5] lexical ladder + [step 6] trigger inference + [step 12] validation are deterministic — typed inputs, typed outputs, no LLM calls. But [step 4] paragraph classification (is this prose a hard imperative, soft preference, hedged statement, descriptive context?) requires LLM judgment because there's no formal grammar for "is this an imperative." So the operation is honest extraction-and-codification with provenance, not parser-style mechanical translation. The earlier name "compile" was a generous shorthand; "distill" reflects what's actually happening. The lexical ladder is the deterministic gate: if a paragraph contains no [step 5] marker, the classifier MUST drop it. The distiller never invents a rule from unmarked prose, and every rule carries a verbatim `source.quote` so the entire pipeline is auditable. The harness fans rules out across every configured runner via `src/harness/adapters/`. Your job is to produce one canonical artifact at `.interlinked/distilled-rules.json` plus an overrides file at `.interlinked/distilled-rules.overrides.json`. The harness handles distribution. -**Coupling and scope.** This skill produces an artifact whose schema (`GuardRule`, defined at `src/harness/types.ts` in `interlinked-cli`) is Interlinked's. Enforcement at runtime requires a hook engine that understands that schema — Interlinked is the canonical one, and currently the only one expressive enough to encode regex on `tool_input` fields, the six action types, severity, keyword quick-reject, role scoping, and exception patterns. The skill does NOT ship multi-backend adapters (Claude Code permissions, Cursor `.mdc`, Codex deny configs) because every alternative is strictly less expressive — lossy translation creates user confusion ("why doesn't my rule work in X?"). However, distillation itself does not require Interlinked installed: the artifact is a standalone JSON file you can audit, version-control, share, or wire into any compatible engine. See §11 for fallback-mode behavior when `.interlinked/` is missing. +**Coupling and scope.** This skill produces an artifact whose schema (`GuardRule`, defined at `src/harness/types.ts` in `interlinked-cli`) is Interlinked's. Enforcement at runtime requires a hook engine that understands that schema — Interlinked is the canonical one, and currently the only one expressive enough to encode regex on `tool_input` fields, the six action types, severity, keyword quick-reject, role scoping, and exception patterns. The skill does NOT ship multi-backend adapters (Claude Code permissions, Cursor `.mdc`, Codex deny configs) because every alternative is strictly less expressive — lossy translation creates user confusion ("why doesn't my rule work in X?"). However, distillation itself does not require Interlinked installed: the artifact is a standalone JSON file you can audit, version-control, share, or wire into any compatible engine. See [step 11] for fallback-mode behavior when `.interlinked/` is missing. ## Invocation patterns (what `/enforce ` means) @@ -102,7 +65,7 @@ The harness fans rules out across every configured runner via `src/harness/adapt | `/enforce .claude/skills/tdd/` | Distill every .md under the directory | | `/enforce mattpocock/skills/tdd` | Treat as `gh:mattpocock/skills/tdd` — fetch + distill (review-mode) | | `/enforce https://raw.githubusercontent.com/.../SKILL.md` | Fetch + distill (review-mode) | -| `/enforce list` | Lifecycle: print rules grouped by source — see §13 | +| `/enforce list` | Lifecycle: print rules grouped by source — see [step 13] | | `/enforce show ` | Lifecycle: full detail for one rule | | `/enforce remove --source ` | Lifecycle: bulk-remove from one source | | `/enforce remove ` | Lifecycle: remove a single rule | @@ -114,14 +77,14 @@ The harness fans rules out across every configured runner via `src/harness/adapt | `/enforce --review` | Distill-then-pause: write to `.interlinked/distilled-rules.review.json`, no activation until accepted | | `/enforce --accept` | Activate review-mode output | -If the first argument is one of `list`, `show`, `remove`, `disable`, `enable`, `modify`, `add`, `reset`, treat it as a lifecycle verb (jump to §14). Otherwise treat arguments as distill targets. +If the first argument is one of `list`, `show`, `remove`, `disable`, `enable`, `modify`, `add`, `reset`, treat it as a lifecycle verb (jump to [step 14]). Otherwise treat arguments as distill targets. ## Operating principles (NON-NEGOTIABLE) 1. **Manual invocation only.** This skill runs only when the user (or an agent acting on the user's explicit request) types `/enforce ...`. Do not wire it into SessionStart, PreCompact, file watchers, hook events, scheduled jobs, or any other auto-trigger. Surprise enforcement — the model suddenly being unable to do something it could yesterday because a doc changed — is the failure mode this rule prevents. 2. **Verbatim source provenance is required.** Every distilled rule must carry the source file path, line range, and exact verbatim quote. A rule whose `source.quote` does not appear in `source.file` at `source.lines` is hallucination — drop it. -3. **Lexical strength is binding** (see §5 ladder). Don't soften, don't escalate. -4. **Deterministic at evaluation time; semi-deterministic at distill time.** The harness must remain deterministic at runtime — never generate rules that require LLM evaluation to check. The distill step itself is partly LLM-driven (paragraph classification in §4 needs a model to decide "is this prose a hard imperative, soft preference, hedged, or descriptive"), but the lexical ladder (§5) is the deterministic gate: if a paragraph contains no §5 marker, the classifier must drop it. The distiller never invents a rule from unmarked prose. Provenance (§7 `source.quote` verbatim) is what makes the distill-time step auditable rather than opaque. +3. **Lexical strength is binding** (see [step 5] ladder). Don't soften, don't escalate. +4. **Deterministic at evaluation time; semi-deterministic at distill time.** The harness must remain deterministic at runtime — never generate rules that require LLM evaluation to check. The distill step itself is partly LLM-driven (paragraph classification in [step 4] needs a model to decide "is this prose a hard imperative, soft preference, hedged, or descriptive"), but the lexical ladder ([step 5]) is the deterministic gate: if a paragraph contains no [step 5] marker, the classifier must drop it. The distiller never invents a rule from unmarked prose. Provenance ([step 7] `source.quote` verbatim) is what makes the distill-time step auditable rather than opaque. 5. **Default-skip when uncertain.** Far better to skip a borderline imperative than to emit a wrong one. 6. **Never overwrite hand-curated rules.** Output goes only to `.interlinked/distilled-rules.json` and `.interlinked/distilled-rules.overrides.json`. The user's hand-curated rules live in `guard-rules.json` and `guard-rules.local.json`. Never touch those. 7. **Idempotent across runs.** Hash inputs; skip unchanged files; preserve user overrides. @@ -131,7 +94,7 @@ If the first argument is one of `list`, `show`, `remove`, `disable`, `enable`, ` ## Step 1 — Argument parsing -Parse the invocation arguments. The first arg, if it's one of the lifecycle verbs (`list`, `show`, `remove`, `disable`, `enable`, `modify`, `add`, `reset`), routes to §14. Otherwise: +Parse the invocation arguments. The first arg, if it's one of the lifecycle verbs (`list`, `show`, `remove`, `disable`, `enable`, `modify`, `add`, `reset`), routes to [step 14]. Otherwise: For each remaining argument, classify it: @@ -161,59 +124,7 @@ Print the resolved target list before doing any work. Form: `Distilling: AGENTS. When no argument is given, walk these locations and record each file's absolute path, kind, and SHA-256 hash. -### 2a — Project tree (CWD upward to git root) - -For each ancestor directory from CWD up to the repo root (the directory containing `.git/`), look for: - -| Filename / pattern | Kind | Notes | -|---|---|---| -| `AGENTS.override.md` | imperative | Highest project precedence | -| `*.local.md` (e.g. `CLAUDE.local.md`) | imperative | Personal, gitignored, beats shared | -| `AGENTS.md` | imperative | Cross-tool source of truth | -| `AGENT.md` | imperative | Singular variant (Amp/community) | -| `CLAUDE.md` | imperative | Claude Code | -| `GEMINI.md` | imperative | Gemini CLI | -| `WARP.md` | imperative | Warp legacy | -| `.github/copilot-instructions.md` | imperative | Repo-wide Copilot | -| `.github/instructions/*.instructions.md` | imperative | Path-scoped via frontmatter `applyTo` | -| `.cursor/rules/*.mdc` | imperative | Cursor; frontmatter `globs`/`description` is machine-readable | -| `.cursorrules` | imperative | Cursor legacy | -| `.clinerules` | imperative | Cline single-file legacy | -| `.clinerules/*.md` | imperative | Cline modular | -| `.windsurfrules` | imperative | Windsurf legacy | -| `.windsurf/rules/*.md` | imperative | Windsurf modular | -| `.continue/rules/*.md` | imperative | Continue.dev — frontmatter `globs`/`alwaysApply` | -| `.augment/rules/*.md` | imperative | Augment | -| `.tabnine/guidelines/*.md` | imperative | Tabnine | -| `.tabnine/guidelines.md` | imperative | Tabnine single-file | -| `.kilocoderules` | imperative | Kilo Code | -| `.claude/skills/*/SKILL.md` | scan-only | See §2c | -| `.agents/skills/*/SKILL.md` | scan-only | Shared native skill location used by Codex and other runners; see §2c | -| `~/.claude/skills/*/SKILL.md` | scan-only | See §2c | -| `CONVENTIONS.md` | imperative-likely | Aider-style | -| `code_review.md` | imperative-likely | Often referenced from AGENTS.md | -| `CONTRIBUTING.md` | mixed (scan only) | Pull only paragraphs with hard imperatives | -| `SECURITY.md` | mixed (scan only) | Pull only paragraphs with hard imperatives | -| `STYLEGUIDE.md` | mixed (scan only) | Pull only paragraphs with hard imperatives | -| `PLANS.md` | scan only | Mostly procedural | - -### 2b — User home (global rules) - -Look in `~/.claude/`, `~/.codex/`, `~/.gemini/`, `~/.config/copilot/`, `~/.continue/`, `~/.windsurf/` for the same patterns. Treat global rules as **lower precedence** than project rules unless they appear in `*.override.md` form. - -### 2c — Skills as scan-only sources - -SKILL.md files are mostly procedural (capability bundles). They are scan-only: extract paragraphs that hit the §4a/§4b lexical markers (`MUST NOT`, `bans`, `forbids`, `never`, `MUST`, `always`); ignore the rest. Every rule from a skill body has its `group_id` formed as `skill:` (extracted from the SKILL.md frontmatter `name` field) instead of `local:` or `gh:`. - -**Skill rules ARE scope-gated at runtime** via `active_when.skill`. The harness's `SessionTrajectory.active_skills` map is populated by `interlinked skill enter ` (called from a slash-command preamble) and read by the active-when evaluator. A distilled skill rule with `active_when.skill = ""` is **dormant** unless that skill is currently active in the session. This means: - -- **Distill at full strength** — a skill imperative phrased `Never X` distills to `action: "block"` per §5a, not the previous safety-downgrade to `ask`. The runtime scope makes the strength safe. -- **Composes with §10 conflict resolution** — scope-disjoint rules don't conflict; importing N skill rules without scope used to yield O(N²) collisions, with `active_when.skill` populated they only collide within the same skill or with always-on rules. -- **Skill-author opt-in cost is one line** — the slash-command preamble adds `interlinked skill enter ` (and a matching `leave` on completion). Skills that don't opt in still distill correctly but their rules are always-on (`active_when` omitted), which is the pre-active_when behavior. - -See `docs/design/harness-active-when-scoping.md` for the full design and §7 below for distiller population rules. - -The `skill:` group_id is also used for lifecycle ops (`/enforce remove --source skill:migrate-to-shoehorn`). +Sections 2a (project tree), 2b (user home) and 2c (skills as scan-only sources) are in [references/discovery.md](references/discovery.md). Read that file before a no-argument run or a directory walk. ### 2d — Skip list (DO NOT extract from these — confirm kind, then skip) @@ -226,7 +137,7 @@ The `skill:` group_id is also used for lifecycle ops (`/enforce remove --source | `PRD.md`, `SPEC.md`, `ROADMAP.md`, `TASKS.md`, `TODO.md` | Forward-looking. | | `README.md` | Human-facing overview. | | `TOOLS.md` | Tool inventory. | -| `.agent.md`, `.prompt.md`, `*.prompt`, `.github/agents/*.agent.md`, `.github/prompts/*.prompt.md` | Capability bundles — same treatment as SKILL.md per §2c. `*.prompt` covers bare-extension role/capability prompts (e.g. SwarmForge `.prompt`). | +| `.agent.md`, `.prompt.md`, `*.prompt`, `.github/agents/*.agent.md`, `.github/prompts/*.prompt.md` | Capability bundles — same treatment as SKILL.md per [step 2c]. `*.prompt` covers bare-extension role/capability prompts (e.g. SwarmForge `.prompt`). | | Any `SKILL.md` whose frontmatter `name` is `enforce` | Self-reference. The distiller must not distill its own imperatives — they describe how to distill, not what the agent should do. Drop the file silently regardless of which install path it lives at (`skills/`, `.claude/skills/`, `.agents/skills/`, `.interlinked/skills/`, `.gemini/skills/`, `.github/skills/`, `.cursor/skills/`, etc.). | | Any `SKILL.md` whose frontmatter `name` is `tdd`, starts with `tdd-`, or ends with `-tdd`; any path matching `**/tdd/SKILL.md` or `**/*-tdd/SKILL.md` | TDD enforcement is owned by the harness's native primitives — `tdd_new_file_gate`, `tdd_cycle_violation`, `tdd_regression`, `tdd_commit_gate`, `tdd_green_confirmation` — driven by the deterministic `tdd_cycles` state machine in `SessionTrajectory`. Distilling a competing TDD skill (Matt Pocock's, gstack's, anyone else's) would either over-fire (always-on rules duplicating our gates) or shadow (action downgraded to `ask`). Drop these files silently. If a project legitimately needs a different TDD policy, edit `structural_checks.test_first_mode` in `guard-rules.local.json`, not via /enforce. | @@ -240,7 +151,7 @@ Use the Read tool with the full path. Cache contents. SHA-256 each file. If `.interlinked/distilled-rules.json` already exists, compare each file's hash to the previous run's `source_hashes` map. **Unchanged files: skip extraction; copy their previous distilled rules verbatim into the new output.** Only re-extract files whose hash changed or which are new. -**Subset distillation preserves other sources.** When the user runs `/enforce ` (a path, a directory, a remote URL), the distiller MUST merge with the prior `distilled-rules.json`: rules from sources NOT in the current invocation are copied through unchanged, with their original `source_hashes` entries preserved. This is the natural extension of the unchanged-files rule: out-of-scope sources are unchanged by definition. Only `/enforce` (no arg, project walk) is allowed to fully regenerate. If you need a hard rebuild from a subset invocation, the user must `rm .interlinked/distilled-rules.json` first — the §"Throw it all away and start fresh" workflow. +**Subset distillation preserves other sources.** When the user runs `/enforce ` (a path, a directory, a remote URL), the distiller MUST merge with the prior `distilled-rules.json`: rules from sources NOT in the current invocation are copied through unchanged, with their original `source_hashes` entries preserved. This is the natural extension of the unchanged-files rule: out-of-scope sources are unchanged by definition. Only `/enforce` (no arg, project walk) is allowed to fully regenerate. If you need a hard rebuild from a subset invocation, the user must `rm .interlinked/distilled-rules.json` first — the [“Throw it all away and start fresh”][restart distillation] workflow. For files with frontmatter, parse it and use machine-readable fields directly: @@ -356,7 +267,7 @@ interface RulePattern { } ``` -Distilled rules ALSO carry a `source` sidecar field — see §7. The harness ignores unknown fields; the CLI lifecycle ops use them. +Distilled rules ALSO carry a `source` sidecar field — see [step 7]. The harness ignores unknown fields; the CLI lifecycle ops use them. ### Pattern semantics (binding) @@ -381,7 +292,7 @@ Practical consequence: **you cannot AND two positive patterns together.** If you | MCP tool prohibition | `trigger: "PreToolUse"`, `tool_match: [""]`, `patterns: []` (exact `tool_match` alone fires the rule via the vacuous-OR; `field: "*"` + `.*` would fail self-check #3) | | Tool-class prohibition | `tool_match: ["Bash"]`, `keywords: []`, `patterns: [{ field: "command", regex: "" }]` | -‡ Sequential preconditions ("Always X before Y") are not directly representable in `GuardRule`. Emit a Pass 2 `policy.md` entry (see §15.2) where `trigger_signal` describes the precondition in natural language; the Tier 2 LLM gate evaluates it from trajectory. Do NOT downgrade to `ask` in `distilled-rules.json` — `ask` is removed per §15.1 (PreToolUse user-prompts created fatigue; the Tier 2 gate handles the same job without interrupting). +‡ Sequential preconditions ("Always X before Y") are not directly representable in `GuardRule`. Emit a Pass 2 `policy.md` entry (see [step 15.2]) where `trigger_signal` describes the precondition in natural language; the Tier 2 LLM gate evaluates it from trajectory. Do NOT downgrade to `ask` in `distilled-rules.json` — `ask` is removed per [step 15.1] (PreToolUse user-prompts created fatigue; the Tier 2 gate handles the same job without interrupting). ### Pattern hygiene (mandatory) @@ -428,185 +339,9 @@ TDD state remains owned by the harness's native test-first policy. --- -## Step 7 — Build the distilled rule (one entry per imperative) - -The distilled rule object is a real `GuardRule` with a `source` sidecar field added. The harness ignores `source`; the CLI uses it for lifecycle operations. - -```json -{ - "id": "enforce--", - "enabled": true, - "trigger": "PreToolUse", - "tool_match": ["Bash"], - "action": "block", - "patterns": [ - { "field": "command", "regex": "^git\\s+push\\b.*\\bmain\\b" } - ], - "reason": "BLOCKED by AGENTS.md:42 — \"Never push to main without code review.\"", - "suggestion": "Open a PR and request review, then merge through the standard flow.", - "severity": "critical", - "category": "distilled-from-md", - "keywords": ["git"], - "source": { - "group_id": "local:AGENTS.md", - "group_label": "AGENTS.md", - "file": "AGENTS.md", - "lines": [42, 42], - "quote": "Never push to main without code review.", - "lexical_marker": "Never", - "marker_class": "block-direct" - }, - "distilled_action_reason": "lexical 'Never' → action=block per §5a", - "confidence": 0.95 -} -``` - -**ID slug rule:** `enforce--`. Group-stem is derived from `group_id` (drop scheme prefix, replace `/`/`.`/`:` with `-`, lowercase). Summary is ≤6 words from the imperative's intent, kebab-case. - -**`group_id` schemes:** - -| Scheme | Format | Example | -|---|---|---| -| `local:` | `local:` — repo-relative when a git root exists, otherwise CWD-relative | `local:AGENTS.md`, `local:.clinerules/style.md` | -| `home:` | `home:` | `home:.claude/CLAUDE.md` | -| `gh:` | `gh://` | `gh:mattpocock/skills/tdd` | -| `url:` | `url:` | `url:example.com/foo.md` | -| `skill:` | `skill:` (from SKILL.md frontmatter) | `skill:tdd`, `skill:grill-me` | - -Skill-sourced rules ALWAYS use the `skill:` scheme; they carry their physical install path in `source.file` but are grouped by skill-name so cross-install moves don't fragment the group. - -**`confidence`:** 0.95 for clean direct-prohibition. 0.85 for positive-form. 0.7 for cases where the trigger required interpretation. Below 0.7 → downgrade to advisory. - -**`active_when` population (binding):** every distilled rule with a known scope MUST carry an `active_when` field per the table below. Rules from project-wide imperative sources (root CLAUDE.md, AGENTS.md, etc.) omit `active_when` (always-on). Rules from skill bodies, model-overlay files, or path-scoped sources populate it deterministically. Population is purely structural — no LLM judgment. - -| Source location | `active_when` populated as | -|---|---| -| `/AGENTS.md`, `/CLAUDE.md`, `/AGENTS.override.md`, `*.local.md`, `.clinerules/`, `.cursor/rules/`, `.continue/rules/`, `.windsurf/rules/`, `.augment/rules/`, `.tabnine/`, `.kilocoderules` | omitted (always-on) — these are the project-wide gates | -| `/SKILL.md` body (any install path) | `{ skill: "" }` — skill-name from frontmatter | -| `model-overlays/.md` (or any sibling persona-by-runner directory) | `{ overlay: "" }` | -| `.github/instructions/.instructions.md` with frontmatter `applyTo: ""` | `{ file_scope: "" }` | -| `.cursor/rules/*.mdc` with frontmatter `globs: [...]` | `{ file_scope: "" }` | -| `.continue/rules/*.md` with frontmatter `alwaysApply: false` + `globs: [...]` | `{ file_scope: "" }` | -| Skill body imperative referencing "after running /" or "after the user invoked X" | merge `{ after_command: { pattern: "^/\\b", window_steps: 20 } }` into the existing scope | -| Skill body imperative referencing TDD state | **not emitted** — TDD is owned by harness primitives; rule is dropped per §2d skip list | - -When multiple axes are inferred from one source (e.g., a skill body that also mentions "after /ship"), all axes are AND-ed in `active_when`. The distiller emits the union; `confidence` drops by 0.05 per inferred axis beyond the first. - -**`applies_to_roles` population (binding).** A source file is *role-scoped* when its basename is `.prompt` / `.agent.md`, or its body opens with `You are the .`. The harness `AgentRole` type (`src/harness/types.ts`) is exactly `"lead" | "worker" | "subagent" | "unknown"`: - -- If `` is one of those four, set `applies_to_roles: [""]` on every rule distilled from that file. -- If `` is NOT — e.g. a bespoke multi-agent cohort such as SwarmForge's `architect` / `coder` / `refactorer` / `reviewer` / `specifier` — the harness has no axis to scope the rule, so a Pass 1 rule from one role's prompt applies to *every* agent. That is a correctness bug, not noise: `refactorer.prompt`'s "Do not run mutation tests" emitted globally directly contradicts `reviewer.prompt`'s "Run … mutation tests." Such imperatives MUST NOT be written to `distilled-rules.json`. Route them to Pass 2 (`policy.md`) with the role named in `trigger_signal` ("…when the acting agent's role is `refactorer`"); the Tier-2 gate resolves role from trajectory. If Pass 2 is unavailable (local-only mode), log to `skipped.report.md` with skip class `skip-role-unmodellable`. §10 conflict resolution does NOT catch this — only the prohibition carries a lexical marker, so the contradicting permission never distills and no conflict pair forms. - -**Schema attribution.** The shape above is the Interlinked harness's `GuardRule`, defined at `src/harness/types.ts` in the `interlinked-cli` package. The four sidecar fields (`source`, `distilled_action_reason`, `confidence`, `user_modified`) are the only additions this skill makes; the harness ignores them at evaluation. The `active_when` field is a real `GuardRule` field (added 2026-04 alongside the active-when scoping work) — the harness reads and evaluates it at runtime via `evaluator/active-when.ts`. Other hook engines that want to consume the same artifact must implement matching evaluation semantics — regex on `tool_input` fields, the six action types (`block` / `warn` / `rewrite` / `soft_block` / `ask` / advisory), severity, keyword quick-reject, role scoping, exception patterns, AND active_when scope evaluation. The skill targets `GuardRule` because it's the most expressive open enforcement primitive today; downgrading to a less-expressive runtime (Claude Code's `permissions.deny[]`, Cursor `.mdc` globs, Codex deny configs) would lose the regex/PostToolUse/severity/active_when dimensions, so this skill does not ship multi-backend adapters. If you want to use the artifact outside Interlinked, write your own evaluator against this schema. - ---- - -## Step 8 — Output schema +## Steps 7 to 10: rule, schema, overrides, conflicts -Write `.interlinked/distilled-rules.json`: - -```json -{ - "version": 1, - "distilled_at": "2026-04-27T18:30:00Z", - "distiller": "skill:enforce@1", - "source_hashes": { - "AGENTS.md": "sha256:abc123…", - "CLAUDE.md": "sha256:def456…", - ".clinerules/style.md": "sha256:789abc…" - }, - "rules": [ /* distilled rule objects per §7 */ ], - "skipped": [ - { - "file": "CLAUDE.md", - "lines": [78, 80], - "quote": "We usually try to write tests before code.", - "reason": "hedged: 'usually try to'", - "marker_class": "skip-hedged" - } - ], - "conflicts": [ - { - "id": "enforce-agents-no-force-push", - "winning_source": "AGENTS.override.md:12", - "overridden_sources": ["AGENTS.md:42"], - "resolution": "AGENTS.override.md > AGENTS.md per precedence stack" - } - ], - "removed": [ - { - "id": "enforce-claude-no-cypress", - "reason": "source quote no longer present in CLAUDE.md as of 2026-04-27" - } - ], - "stats": { - "files_scanned": 9, - "imperatives_found": 28, - "distilled_block": 12, - "distilled_ask": 4, - "distilled_advisory": 7, - "skipped_hedged": 5, - "conflicts": 1, - "removed": 0 - } -} -``` - -The harness's `rules-loader.ts` reads this file alongside `guard-rules.json` and `guard-rules.local.json` and applies the overrides file (next section). The harness's `watchRulesFiles()` polls both distilled paths every ~2s, so changes are picked up automatically — no manual reload command exists. If the daemon appears stuck, confirm with `interlinked harness status` before guessing: it round-trips the socket and reports `ZOMBIE` when a live PID is answering nothing (the state that looks exactly like "rules stopped reloading"). `.interlinked/daemon-events.jsonl` records why the last daemon left — a pre-listen startup failure exits 78 with `reason: "startup-failed"` — and `.interlinked/logs/daemon.log` holds any crash output. Either way the fix is `interlinked harness restart`. - -For `--review` mode: write to `.interlinked/distilled-rules.review.json` instead. The harness does not load `.review.json`; the user must run `/enforce --accept` to promote it. - ---- - -## Step 9 — Overrides file (the user's mods) - -`.interlinked/distilled-rules.overrides.json` survives re-distillation: - -```json -{ - "version": 1, - "removed_groups": ["gh:mattpocock/skills/qa"], - "removed_rule_ids": ["enforce-claude-no-cypress"], - "disabled_rule_ids": ["enforce-agents-prefer-named-exports"], - "modifications": { - "enforce-skill-tdd-no-bulk-tests": { - "action": "ask", - "severity": "medium", - "note": "downgraded — too noisy on legacy tests/ dir" - } - } -} -``` - -The harness applies these on every load. Removed groups stay removed across re-distillation (so deleted things don't whack-a-mole back). Modifications layer on top of the pristine distilled rule. - -**On distill, the skill MUST read this file before extracting** and: -- Skip any source whose `group_id` is in `removed_groups[]`. Never even fetch a removed group. -- Skip any rule whose `id` is in `removed_rule_ids[]`. The pristine rule still appears in the output but with `enabled: false` and a note. -- Apply `modifications{}` after distillation and mark those rules with `user_modified: true` for the report. - ---- - -## Step 10 — Conflict resolution - -Precedence stack (highest to lowest): - -1. `AGENTS.override.md` -2. `*.local.md` (CLAUDE.local.md, etc.) -3. Project rule-folder files (`.claude/rules/`, `.continue/rules/`, `.windsurf/rules/`, `.augment/rules/`, `.clinerules/`, `.cursor/rules/`) -4. `AGENTS.md` / `CLAUDE.md` / `GEMINI.md` / `WARP.md` -5. Path-scoped frontmatter files (`.github/instructions/*.instructions.md`) -6. SKILL.md bodies (group_id `skill:`; no runtime scope — collisions are real but resolved by precedence here) -7. `CONTRIBUTING.md` / `SECURITY.md` / `STYLEGUIDE.md` / `CONVENTIONS.md` -8. `~/` global counterparts of any of the above - -When two distilled rules collide on `(trigger, tool_match, patterns[].regex)`: - -- If actions differ: take the strictest (`block` > `ask` > `soft_block` > `warn`). -- Always merge: keep the higher-precedence source as `winning_source`; record the lower-precedence ones in `overridden_sources[]`. -- Never silently drop the loser — surface in `conflicts[]`. - ---- +Read [references/rule-schema.md](references/rule-schema.md) before you write output on a distill run. It holds Step 7 (build the distilled rule), Step 8 (output schema), Step 9 (overrides file) and Step 10 (conflict resolution). ## Step 11 — Pre-flight checks (run BEFORE writing anything) @@ -614,10 +349,10 @@ When two distilled rules collide on `(trigger, tool_match, patterns[].regex)`: - **Preferred path** (Interlinked installed): `.interlinked/` exists. Output goes to `.interlinked/distilled-rules.json`; the harness watches the file and picks up changes within ~2s automatically. - **Fallback path** (Interlinked not installed): `.interlinked/` is missing. **Warn — do not abort.** Write the artifact to `./distilled-rules.json` next to the user's CWD (the same location for the overrides file: `./distilled-rules.overrides.json`). Print a clear message: - > No `.interlinked/` directory found. Distilled rules written to `./distilled-rules.json`. To enforce them, install Interlinked (`npm install -g github:QuentinCody/interlinked-cli && interlinked enable`) — Interlinked's harness reads exactly this file from `.interlinked/`. Or wire the JSON into your own hook engine using the `GuardRule` schema documented in §7. Distillation does NOT require Interlinked; enforcement does. + > No `.interlinked/` directory found. Distilled rules written to `./distilled-rules.json`. To enforce them, install Interlinked (`npm install -g github:QuentinCody/interlinked-cli && interlinked enable`) — Interlinked's harness reads exactly this file from `.interlinked/`. Or wire the JSON into your own hook engine using the `GuardRule` schema in the enforce skill’s `references/rule-schema.md`. Distillation does NOT require Interlinked; enforcement does. This separates **producing the artifact** (this skill's scope, no runtime dependency) from **enforcing it** (Interlinked's scope, runtime dependency). Users without the harness still get a tangible, version-controllable, auditable file they can share or migrate later. -- The directory is a git repo. If not, warn but continue — treat CWD itself as the project root for both the §1 outside-CWD check and the §7 `local:` relative-path computation. +- The directory is a git repo. If not, warn but continue — treat CWD itself as the project root for both the [step 1] outside-CWD check and the [step 7] `local:` relative-path computation. - Read `.interlinked/config.json` if present; warn if `version < 2` (distilled rules may not load on older harness builds). - **Never** write to `.interlinked/guard-rules.json` or `.interlinked/guard-rules.local.json`. - **Never** modify any source `.md` file. Read-only. @@ -646,618 +381,32 @@ If any check fails, abort and report the specific failure with the offending rul ## Step 13 — Final summary (REQUIRED, print to user at end of run) -End every run with this tabular summary: - -``` -Distilled-rules report - -Sources scanned 9 files - imperative-bearing 6 - scan-only 2 - persona/skipped 1 - -Imperatives found 28 - -Distilled to: - block 12 (criticals from MUST NOT / never / forbidden / shall not) - ask 4 (should not / avoid) - advisory 7 (should / prefer / consider) - -Skipped: - hedged 5 (we usually try / ideally) - no trigger 0 - out-of-scope 0 - -Conflicts 1 (AGENTS.override.md beat AGENTS.md on git-push-main) -Removed 0 -User-disabled 0 -User-modified 1 - -Output: .interlinked/distilled-rules.json -Run `/enforce list` to inspect. The harness picks up the new rules within ~2s automatically. - -Top distilled rules: - ✗ enforce-agents-override-no-push-this-week AGENTS.override.md:12 block - ✗ enforce-claude-no-prod-deletes CLAUDE.md:88 block - ✗ enforce-clinerules-no-cypress .clinerules/style.md:5 block - ⚠ enforce-claude-prefer-named-exports CLAUDE.md:152 advisory - … -``` - -For `--review` mode: replace "Output:" with "Review-mode output:" and add: "Run `/enforce --accept` to activate, or edit `.interlinked/distilled-rules.review.json` first." - ---- - -## Step 14 — Lifecycle operations (`/enforce `) - -When the first argument is a lifecycle verb, run that operation instead of distilling. - -### `/enforce list` - -Read `.interlinked/distilled-rules.json` + `.interlinked/distilled-rules.overrides.json`. Print: - -``` -Source Rules Block Ask Advisory Disabled -──────────────────────────────────────────────── ──── ───── ──── ─────── ──────── -local:AGENTS.md 8 5 1 2 0 -local:AGENTS.override.md 2 2 0 0 0 -local:CLAUDE.md 5 2 1 2 1 -local:.clinerules/style.md 3 2 0 1 0 -gh:mattpocock/skills/tdd 2 2 0 0 0 -skill:tdd 2 2 0 0 0 -──────────────────────────────────────────────── ──── ───── ──── ─────── ──────── -Total 22 14 2 6 1 - -Removed groups: gh:mattpocock/skills/qa (3 rules suppressed) - -Run `/enforce list ` to drill in. -Run `/enforce remove --source ` to bulk-remove from a source. -``` - -### `/enforce list ` - -Drill into a single source: - -``` -Source: gh:mattpocock/skills/tdd - -✗ enforce-skill-tdd-no-bulk-tests block high - Source: gh:mattpocock/skills/tdd:23-25 - Quote : "explicitly bans the horizontal anti-pattern" - Rule : trigger=PreToolUse, tool_match=[Edit,Write], patterns=[command~/^...$/] - Lexical: bans → block-direct - -✗ enforce-skill-tdd-test-before-source block high - Source: gh:mattpocock/skills/tdd:30-31 - … -``` - -### `/enforce show ` - -Print one rule's full JSON, plus its source-file context (3 lines before, the quote, 3 lines after). - -### `/enforce remove --source ` - -Read overrides; add `` to `removed_groups[]`. Save. Print: `Removed group (N rules suppressed). Run /enforce add --source to undo.` - -### `/enforce remove ` - -Read overrides; add `` to `removed_rule_ids[]`. Save. Print confirmation. - -### `/enforce disable ` - -Read overrides; add `` to `disabled_rule_ids[]`. Save. Rule stays in distilled-rules.json but loads with `enabled: false`. - -### `/enforce enable ` - -Read overrides; remove `` from `disabled_rule_ids[]`. Save. - -### `/enforce modify --action ask --severity medium` - -Read overrides; set `modifications[] = { action: "ask", severity: "medium", note: }`. Save. - -Allowed flags: `--action `, `--severity `, `--note `. - -### `/enforce add --source ` - -Read overrides; remove `` from `removed_groups[]`. Save. Print: `Group restored. Run /enforce to re-distill and pull rules from it.` - -### `/enforce reset ` - -Read overrides; clear all entries for ``: remove from `removed_rule_ids`, `disabled_rule_ids`, and `modifications{}`. Save. - -### `/enforce --review` - -Distill-with-pause: write to `.interlinked/distilled-rules.review.json` instead of `distilled-rules.json`. The harness does not load `.review.json`. Default mode for remote sources. - -### `/enforce --accept` - -Promote `distilled-rules.review.json` → `distilled-rules.json`. Validate first; abort if validation fails. +Print the [distillation report](references/report-format.md) after every run, including review-only runs. --- -## Step 15 — Companion artifacts: policy gate + cloud review - -Added 2026-05. The single-pass model (every imperative → one GuardRule in -`distilled-rules.json`) was too lossy. Imperatives whose triggers couldn't -be expressed as `tool_input` regex were either downgraded to `ask` (noisy) -or skipped (lost). Skills that are mostly methodology (Matt Pocock's -`improve-codebase-architecture`, most audit-style cybersecurity skills, etc.) -yielded ~5-15% coverage at best. - -`/enforce` now runs **three passes** over the same source markdown and emits -artifacts for the three enforcement tiers of the Interlinked architecture: - -| Tier | Layer | Consumer | Artifact | Cadence | -|---|---|---|---|---| -| 1 | Local deterministic | Interlinked harness (~sub-10ms) | `distilled-rules.json` | Every tool call | -| 2 | Cloud LLM policy gate | gpt-oss-safeguard-120b (~3-6s) | `policies/.policy.md` + Cedar companions | Most tool calls (post-filter) | -| 3 | Cloud architectural review | Sonnet/Opus on staged commits (~30-120s) | `policies/.prose.md` | Pre-push / on-demand `/review` / `/security-review` | -| — | Audit | Humans tightening source markdown | `policies/skipped.report.md` | After /enforce runs | - -### 15.1 — Three-pass routing (binding) - -For each imperative extracted under §4-§6, the distiller routes it to ONE or -MORE of the four artifact families based on trigger shape and FP risk: - -| Imperative shape | Pass 1 (deterministic) | Pass 2 (LLM gate) | Pass 3 (prose) | Skipped | -|---|---|---|---|---| -| Concrete regex-shape trigger, low FP | ✓ block/warn | (mirror, for trajectory context) | — | — | -| Concrete trigger + skill-scoped | ✓ block/warn | (mirror) | — | — | -| Concrete trigger + sequential precondition | — | ✓ warn (LLM evaluates trajectory) | — | — | -| Abstract / intent / semantic trigger | — | ✓ block/warn | — | — | -| Quality-of-output rule (vocabulary, required fields) | (optional content regex, FP-prone) | ✓ warn | rationale → prose | — | -| Definition / methodology / principle | — | — | ✓ | — | -| §5e SKIP (hedged, no signal, no imperative) | — | — | — | ✓ | - -A single source imperative can route to multiple passes. Example: the -`disk-forensics` "Never modify source evidence" imperative routes to Pass 1 -(file_path regex on `*.E01`/etc.) AND Pass 2 (LLM-side mirror for trajectory -context AND the residual intent rule "Never suggest evidence tampering"). - -**Critical: §6 ‡ ask-downgrade is removed.** Previously, sequential -preconditions ("Always X before Y") downgraded to `action: "ask"` because the -harness couldn't model the precondition. With Tier 2, the LLM evaluates the -precondition from trajectory. Emit a Pass 2 entry instead — no `ask`. - -### 15.2 — Pass 2: Policy doc format (`.policy.md`) - -Markdown with structured per-imperative entries. The Tier 2 LLM loads this -file as system-prompt context when its `active_when` scope matches. - -```markdown -# Policy: - -**Source:** -**Active when:** -**Generated by:** `/enforce` Pass 2, - -## P — - -- **id**: `enforce--` -- **severity**: critical | high | medium | low -- **active_when**: -- **action_on_violation**: block | warn -- **trigger_signal**: -- **source**: : — "" -- **lexical_marker**: -- **rationale**: -- **deterministic_companion**: -- **cedar_companion**: -- **suggested_remediation**: "" -``` - -Per-entry id format matches GuardRule ids: `enforce--`. -Action vocabulary is `block` or `warn` only — `ask` is removed (15.1). -PostToolUse warns and PreToolUse blocks are the only two states. - -### 15.3 — Pass 2: Cedar transpilation - -Two flavors of Cedar emitted per group, both derived from the policy entries -in `.policy.md`: - -**`.cedar` — Sondera-compatible** (default; drops into Sondera's -`policies/` directory without modification). Uses only fields in Sondera's -`base.cedarschema`: - -- Actions: `ShellCommand`, `ShellCommandOutput`, `FileRead/Write/Edit/Delete`, - `WebFetch`, `WebFetchOutput`, `Prompt`, `ToolOutput` -- Context fields: `command`, `path`, `operation`, `url`, `signature.*`, - `policy.*`, `label`, `workspace.*` -- Resource fields: `Trajectory.step_count`, `Trajectory.label`, - `Trajectory.taints`, `File.label` - -**`.interlinked.cedar` — Interlinked-extended** (only emitted when at -least one policy entry needs extensions). Adds: - -- `context.skill_active: String` — current skill scope -- `Trajectory.commands_run: Set` — accumulated shell commands -- `Trajectory.files_read: Set` — accumulated file reads -- `@action_on_violation("warn"|"block")` annotation (extends Cedar's - binary permit/forbid) -- `@requires_extension("")` annotation (engines without the - extension must reject the file) - -See `docs/design/interlinked-cedar-extensions.cedarschema` for the full -schema delta. - -**Regex → `like` translation.** Cedar `like` is glob-only, not regex. The -distiller best-effort expands: - -- `^pattern$` → `pattern` (Cedar `like` is implicitly anchored if no `*`) -- `\bword\b` → `* word *` and `word *` and `* word` (drops boundary precision) -- Negative lookahead → ANDed `like` exclusions (loses some precision) -- Character classes → enumerated alternations (e.g., `[ab]` → `*a*` || `*b*`) -- `+` / `?` quantifiers → drop (covered by `*`) - -When translation is lossy, emit the policy with `@confidence("approximate")` -and rely on `distilled-rules.json`'s actual-regex GuardRule as the precise -floor. The Cedar version is for portability + Sondera compatibility. - -When translation is impossible (e.g., trajectory state references on Sondera -side), emit a comment block in the `.cedar` file explaining why and pointing -to the `.interlinked.cedar` or `.policy.md` companion. - -### 15.4 — Pass 3: Prose artifact format (`.prose.md`) - -Pass 3 captures imperatives that aren't gates at all — definitions, -methodologies, principles — but that should inform the **after-the-fact -review** of staged commits by the Tier 3 cloud agent. - -Tier 3 has wider scope than Tier 2: it sees the full repo, the staged -commits, the agent's session log, and the prose artifacts for every skill -that was active during the session. It evaluates the staged work against -the principles in `prose.md` using full context. - -```markdown -# Prose policies: - -This file is consumed by the Tier 3 cloud review agent (pre-push, /review, -/security-review). The agent evaluates staged commits against these -principles using full repo context — NOT single-tool-call trajectory. - -## Definitions (canonical vocabulary) - - - -## Principles - -### - - - -**Tier 3 evaluation:** - -## Methodology checkpoints - - - -## Source - - -``` - -Pass 3 entries are **not enforced at edit time**. They're context for -the cloud reviewer. The distiller never blocks or warns on Pass 3 content. +## Step 14: lifecycle operations -### 15.5 — Skipped report (`skipped.report.md`) +If the first argument is a lifecycle verb, read [references/lifecycle.md](references/lifecycle.md) and follow it. That file also holds the common workflows. -Anything that didn't route to any of Passes 1-3. One file shared across -all groups distilled in a run. Format per existing §8 `skipped[]` array, -serialized as Markdown: +## Step 15: companion artifacts -```markdown -# Skipped imperatives — +On a distill run, read [references/companion-artifacts.md](references/companion-artifacts.md). It holds the three-pass routing, the policy, Cedar and prose formats, the skipped report and local-only mode. Its sections 15.7 to 15.10 add rules to Steps 6, 8, 11 and 13. -## - -### L — "" - -- **Lexical marker:** -- **Skip class:** `skip-hedged` | `skip-no-trigger` | `skip-abstract-trigger` - | `skip-no-imperative` | `skip-out-of-scope` | `skip-role-unmodellable` -- **Skip reason:** -- **Could be enforced if:** -``` - -Use this report to tighten source markdown — adding a concrete trigger or -stronger lexical marker would move an entry into one of the enforced passes. - -### 15.6 — Local-only mode (no cloud Tier 2 or Tier 3) - -For users who never touch our cloud or self-host Sondera: - -| Artifact | Local-only role | -|---|---| -| `distilled-rules.json` | Tier 1 floor — works as today, deterministic enforcement | -| `policy.md` | Loaded into agent context (advisory, not enforced) | -| `.cedar` (Sondera-compatible) | Drop into self-hosted Sondera installation | -| `.interlinked.cedar` | Inactive unless the Interlinked harness adds Cedar evaluation in v1.1+ | -| `prose.md` | Loaded into agent context (definitions, principles) | -| `skipped.report.md` | Human audit, identical to cloud mode | - -The deterministic floor + advisory loading covers ~30-40% of what cloud -adds. Cloud unlocks the LLM-evaluable trajectory rules (Pass 2) and the -wide-scope after-the-fact review (Pass 3). - -### 15.7 — Updated §6 ‡ (binding) - -§6 ‡ previously read: *"Sequential preconditions (Always X before Y) are -not directly representable in `GuardRule`. Distill to a single PreToolUse -rule on Y with `severity: "medium"` and `action: "ask"`."* - -This is **removed**. New rule: - -- Sequential preconditions distill to a Pass 2 `policy.md` entry, not a - Pass 1 `ask` rule. -- The policy entry's `trigger_signal` describes the precondition in - natural language; the Tier 2 LLM evaluates from trajectory. -- For local-only users (no Tier 2), the policy entry loads as agent - context — advisory, not enforced. This is strictly weaker than `ask` - was, but the FP cost of `ask` (user fatigue) outweighed the benefit. - -The trigger cookbook in §6 stays. Just the ‡ footnote is rewritten: - -> ‡ Sequential preconditions ("Always X before Y") are not directly -> representable in `GuardRule`. Emit a Pass 2 `policy.md` entry where -> `trigger_signal` describes the precondition. The Tier 2 LLM gate -> evaluates from trajectory. - -### 15.8 — Stats update for §13 summary - -The §13 final-summary table grows by one section to reflect three-pass -routing: - -``` -Distilled to: - Pass 1 — deterministic 12 (block/warn in distilled-rules.json) - Pass 2 — LLM policy gate 8 (block/warn in .policy.md) - ├── Sondera-compat .cedar 5 (translates to vanilla Cedar) - └── Interlinked .cedar 3 (requires schema extensions) - Pass 3 — prose for review 4 (definitions / principles for Tier 3) - Skipped 5 (hedged / no trigger / not imperative) -``` - -### 15.9 — Output schema additions - -The existing `distilled-rules.json` v1 schema (§8) gains an optional -`companions` sidecar on each rule, naming its Pass 2 / Pass 3 siblings: - -```json -"companions": { - "policy_md": ".interlinked/policies/.policy.md#", - "cedar": ".interlinked/policies/.cedar#", - "interlinked_cedar": ".interlinked/policies/.interlinked.cedar#", - "prose_md": ".interlinked/policies/.prose.md#" -} -``` - -And new top-level keys: - -```json -"policies_emitted": [".interlinked/policies/.policy.md", ...], -"prose_emitted": [".interlinked/policies/.prose.md", ...], -``` +## Worked examples -Schema version stays at 1 — additions are backward-compatible (existing -consumers ignore unknown fields). - -### 15.10 — Pre-flight additions for §11 - -When emitting Pass 2 or Pass 3 artifacts, ensure `.interlinked/policies/` -exists. Create it on first emission. Never overwrite a `.local.cedar` -file the user has hand-authored — these are the user's extension layer -and live alongside generated `.cedar` files. - -In fallback mode (no `.interlinked/` directory), Pass 2/3 artifacts land -at `./policies/.{policy.md,cedar,interlinked.cedar,prose.md}` at -the user's CWD. Same fallback message as §11 for `distilled-rules.json`. - -### 15.11 — Worked example - -See `docs/examples/policies/disk-forensics/` for a complete worked -example: one source SKILL.md, three deterministic rules, five policy -entries (3 mirror + 2 LLM-only), 2 Cedar files (Sondera + Interlinked), -and a skipped report. The example also demonstrates the Pass 3 prose -output for the skill's "Evidence Handling Principles" methodology -section. - ---- - -## Worked examples (apply these patterns mechanically) - -### Example 1 — Direct prohibition - -**Source (AGENTS.md:42):** "Never push to main without code review." - -```json -{ - "id": "enforce-local-agents-md-no-push-main", - "enabled": true, - "trigger": "PreToolUse", - "tool_match": ["Bash"], - "action": "block", - "patterns": [{ "field": "command", "regex": "^git\\s+push\\b.*\\bmain\\b" }], - "reason": "BLOCKED by AGENTS.md:42 — \"Never push to main without code review.\"", - "severity": "critical", - "category": "distilled-from-md", - "keywords": ["git"], - "source": { - "group_id": "local:AGENTS.md", - "group_label": "AGENTS.md", - "file": "AGENTS.md", - "lines": [42, 42], - "quote": "Never push to main without code review.", - "lexical_marker": "Never", - "marker_class": "block-direct" - } -} -``` - -### Example 2 — Positive imperative downgraded to ask (no session-state primitive) - -**Source (CLAUDE.md:88):** "Always run `npm test` before committing." - -```json -{ - "id": "enforce-local-claude-md-test-before-commit", - "enabled": true, - "trigger": "PreToolUse", - "tool_match": ["Bash"], - "action": "ask", - "patterns": [{ "field": "command", "regex": "^git\\s+commit\\b" }], - "reason": "CLAUDE.md:88 — \"Always run `npm test` before committing.\" The harness can't verify a recent test run; please confirm.", - "severity": "medium", - "category": "distilled-from-md", - "keywords": ["git"], - "source": { ... "lexical_marker": "Always", "marker_class": "block-positive" }, - "distilled_action_reason": "positive imperative, no session-state primitive → downgraded block→ask" -} -``` - -### Example 3 — Path-scoped block - -**Source (.clinerules/style.md:5):** "MUST NOT edit files under `db/migrations/` directly." - -```json -{ - "id": "enforce-local-clinerules-style-md-no-direct-migrations", - "enabled": true, - "trigger": "PreToolUse", - "tool_match": ["Edit", "Write", "MultiEdit", "apply_patch"], - "action": "block", - "patterns": [{ "field": "file_path", "regex": "(^|/)db/migrations/" }], - "reason": "BLOCKED by .clinerules/style.md:5 — \"MUST NOT edit files under db/migrations/ directly.\"", - "suggestion": "Use `npm run migrate:create` instead.", - "severity": "critical", - "category": "distilled-from-md", - "source": { ... "lexical_marker": "MUST NOT", "marker_class": "block-direct" } -} -``` - -### Example 4 — Soft preference → advisory (`warn`) - -**Source (CLAUDE.md:152):** "Prefer named exports over default exports for new modules." - -```json -{ - "id": "enforce-local-claude-md-prefer-named-exports", - "enabled": true, - "trigger": "PostToolUse", - "tool_match": ["Edit", "Write", "MultiEdit", "apply_patch"], - "action": "warn", - "patterns": [ - { "field": "content", "regex": "^export\\s+default\\b", "flags": "m" } - ], - "reason": "CLAUDE.md:152 prefers named exports over default exports.", - "severity": "low", - "category": "distilled-from-md", - "source": { ... "lexical_marker": "Prefer", "marker_class": "advisory" } -} -``` - -Note: an earlier draft of this example carried a second positive pattern on `file_path` (`\.tsx?$`) intended as an AND-style scope filter. Per §6 "Pattern semantics", positive patterns OR — that filter would have made the rule fire on every `.tsx` edit regardless of content. Single-pattern advisory rules are usually right; the verify pipeline gates noisy advisories at the report layer, not the rule layer. - -### Example 5 — Hedged → SKIP - -**Source (CLAUDE.md:201):** "We usually try to keep PRs small." - -→ Skipped entry only: -```json -{ "file": "CLAUDE.md", "lines": [201, 201], "quote": "We usually try to keep PRs small.", "reason": "hedged: 'usually try to'", "marker_class": "skip-hedged" } -``` - -### Example 6 — MCP tool prohibition - -**Source (AGENTS.md:71):** "Never use the `railway-mcp__volumeDelete` tool from agent sessions." - -```json -{ - "id": "enforce-local-agents-md-no-railway-volume-delete", - "enabled": true, - "trigger": "PreToolUse", - "tool_match": ["railway-mcp__volumeDelete"], - "action": "block", - "patterns": [], - "reason": "BLOCKED by AGENTS.md:71 — \"Never use railway-mcp__volumeDelete from agent sessions.\"", - "severity": "critical", - "category": "distilled-from-md", - "source": { ... "marker_class": "block-direct" } -} -``` - -### Example 7 — Skill-sourced rule with active_when scope - -**Source (`.claude/skills/migrate-to-shoehorn/SKILL.md:12`):** "**Test code only.** Never use shoehorn in production code." - -```json -{ - "id": "enforce-skill-migrate-to-shoehorn-no-prod-shoehorn", - "enabled": true, - "trigger": "PreToolUse", - "tool_match": ["Edit", "Write", "MultiEdit", "apply_patch"], - "action": "block", - "patterns": [ - { "field": "content", "regex": "from\\s+[\"']@total-typescript/shoehorn[\"']" }, - { "field": "file_path", "regex": "\\.test\\.|\\.spec\\.|/__tests__/|/__fixtures__/", "negate": true } - ], - "reason": "BLOCKED by migrate-to-shoehorn skill: shoehorn is a test-only library — never import it from production code paths.", - "severity": "high", - "category": "distilled-from-md", - "active_when": { - "skill": "migrate-to-shoehorn" - }, - "source": { - "group_id": "skill:migrate-to-shoehorn", - "group_label": "skill:migrate-to-shoehorn", - "file": ".claude/skills/migrate-to-shoehorn/SKILL.md", - "lines": [12, 12], - "quote": "Never use shoehorn in production code.", - "lexical_marker": "Never", - "marker_class": "block-direct" - }, - "distilled_action_reason": "lexical 'Never' + concrete content+file_path triggers (positive on import line, negate on test paths) → action=block per §5a; scope-gated to skill:migrate-to-shoehorn per §7 active_when population — rule is dormant until `interlinked skill enter migrate-to-shoehorn` fires" -} -``` - -Three things to notice about this example: - -1. **`active_when.skill` is populated automatically** because the source is `/SKILL.md`. The distiller doesn't ask; per §7's source-location table, every skill body rule gets `active_when.skill = ""`. -2. **Action stays `block`, not downgraded to `ask`**. With pre-active-when distillation, skill rules had to soften because they were always-on and would over-fire outside their domain. With scope, full-strength enforcement is safe — the rule simply doesn't fire when the skill isn't active. -3. **The skill author still has to opt in.** A user running this skill must include `interlinked skill enter migrate-to-shoehorn` in the slash-command preamble (and `leave` on completion). Skills that don't opt in distill correctly but their `active_when.skill` marker is never set, so the rule stays dormant. This is intentional — it makes activation explicit. - -Note: TDD-themed skills (Matt Pocock's `tdd/SKILL.md`, gstack's TDD prose, etc.) are **not** distilled by /enforce — see §2d skip list. TDD enforcement is owned by the harness's native primitives. This example uses a non-TDD skill so the worked example doesn't conflict with that policy. - -### Example 8 — Conflict between AGENTS.override.md and AGENTS.md - -**`AGENTS.md:42`:** "Never push to main without code review." -**`AGENTS.override.md:12`:** "MUST NOT push to ANY remote branch this week — release freeze." - -The override is strictly broader. Output: -- `rules[]` contains the override-derived rule with `tool_match=["Bash"]` + `command~/^git\s+push\b/`. -- The narrower AGENTS.md rule is suppressed. -- `conflicts[]` records `winning_source: "AGENTS.override.md:12"`, `overridden_sources: ["AGENTS.md:42"]`. - ---- +[references/examples.md](references/examples.md) holds eight worked examples. Read them when a pattern is not clear. ## Failure modes to guard against | Failure | Detection | Fix | |---|---|---| | Hallucinated rule | `source.quote` does not appear verbatim in `source.file` | Drop the rule; log to `extraction_errors[]`. | -| Hedged distilled to block | marker is `usually`/`prefer`/`try` but `action=block` | Re-classify per §5. | +| Hedged distilled to block | marker is `usually`/`prefer`/`try` but `action=block` | Re-classify per [step 5]. | | Trigger too broad | regex is `.*` with no anchors | Reject; downgrade to advisory. | | Trigger too narrow | matches only literal command without escaping | Add `\b` boundaries. | -| Persona file got distilled | source path matches §2d skip list | Drop everything from that file. | -| Same imperative in two files | both distilled with same trigger | Merge per §10. | +| Persona file got distilled | source path matches [step 2d] skip list | Drop everything from that file. | +| Same imperative in two files | both distilled with same trigger | Merge per [step 10]. | | Out-of-date previous distillation | source hash mismatch | Re-extract that file; preserve unchanged. | | User-removed group reappeared | overrides not applied | Always read overrides BEFORE extracting. | | Catastrophic-backtracking regex | nested unbounded quantifiers | Reject; rewrite. | @@ -1289,12 +438,40 @@ If the user wants per-runner overrides ("only enforce this in Codex, not Claude" ## Final reminders (read before writing output) - Verbatim source quotes are non-negotiable. -- Lexical strength is binding (§5 ladder). +- Lexical strength is binding ([step 5] ladder). - `never` / `MUST NOT` / `forbidden` / `shall not` → **block**, no exceptions. -- `active_when` population is binding (§7 source-location table). Skill-body rules ALWAYS carry `active_when.skill = ""`. Project-wide rules (CLAUDE.md, AGENTS.md, etc.) ALWAYS omit `active_when` (always-on). Skip is always safer than mis-scoping. -- TDD-themed skills are skipped (§2d). Don't distill them — TDD enforcement is owned by harness primitives. +- `active_when` population is binding ([step 7] source-location table). Skill-body rules ALWAYS carry `active_when.skill = ""`. Project-wide rules (CLAUDE.md, AGENTS.md, etc.) ALWAYS omit `active_when` (always-on). Skip is always safer than mis-scoping. +- TDD-themed skills are skipped ([step 2d]). Don't distill them — TDD enforcement is owned by harness primitives. - Skip is always safer than mis-distill. - Output goes only to `.interlinked/distilled-rules.json` (or `.review.json`) and `.interlinked/distilled-rules.overrides.json`. - Read the overrides file BEFORE extracting; honor `removed_groups`, `removed_rule_ids`, `disabled_rule_ids`, and `modifications`. -- End every run with the §13 summary table. +- End every run with the [step 13] summary table. - Every rule has provenance, or it doesn't exist. + +## References + +- [references/discovery.md](references/discovery.md): Steps 2a to 2c, where to look for sources. +- [references/rule-schema.md](references/rule-schema.md): Steps 7 to 10. Every distill run needs it. +- [references/companion-artifacts.md](references/companion-artifacts.md): Step 15. Every distill run needs it. +- [references/lifecycle.md](references/lifecycle.md): common workflows and the Step 14 lifecycle verbs. +- [references/examples.md](references/examples.md): eight worked examples. + +[restart distillation]: references/lifecycle.md#throw-it-all-away-and-start-fresh +[step 1]: #step-1--argument-parsing +[step 2]: #step-2--discover-sources-no-arg-or-directory-walk +[step 2c]: references/discovery.md#2c--skills-as-scan-only-sources +[step 2d]: #2d--skip-list-do-not-extract-from-these--confirm-kind-then-skip +[step 3]: #step-3--read-each-file-once +[step 4]: #step-4--per-paragraph-classification +[step 5]: #step-5--lexical-strength--action-ladder-binding +[step 6]: #step-6--trigger-extraction-real-guardrule-schema +[step 7]: references/rule-schema.md#step-7--build-the-distilled-rule-one-entry-per-imperative +[step 8]: references/rule-schema.md#step-8--output-schema +[step 9]: references/rule-schema.md#step-9--overrides-file-the-users-mods +[step 10]: references/rule-schema.md#step-10--conflict-resolution +[step 11]: #step-11--pre-flight-checks-run-before-writing-anything +[step 12]: #step-12--self-checks-run-before-writing-output +[step 13]: #step-13--final-summary-required-print-to-user-at-end-of-run +[step 14]: #step-14-lifecycle-operations +[step 15.1]: references/companion-artifacts.md#151--three-pass-routing-binding +[step 15.2]: references/companion-artifacts.md#152--pass-2-policy-doc-format-groupidpolicymd diff --git a/skills/enforce/references/companion-artifacts.md b/skills/enforce/references/companion-artifacts.md new file mode 100644 index 000000000..38c1e8f66 --- /dev/null +++ b/skills/enforce/references/companion-artifacts.md @@ -0,0 +1,303 @@ +# enforce: companion artifacts (Step 15) + +Reference for [SKILL.md](../SKILL.md). Read it on a distill run. Sections 15.7 to 15.10 add rules to Steps 6, 8, 11 and 13. +A § number names a step of /enforce: Steps 1 to 6.5 and 11 to 13 are in SKILL.md, and the +other steps are in the sibling files of this directory. + +## Step 15 — Companion artifacts: policy gate + cloud review + +Added 2026-05. The single-pass model (every imperative → one GuardRule in +`distilled-rules.json`) was too lossy. Imperatives whose triggers couldn't +be expressed as `tool_input` regex were either downgraded to `ask` (noisy) +or skipped (lost). Skills that are mostly methodology (Matt Pocock's +`improve-codebase-architecture`, most audit-style cybersecurity skills, etc.) +yielded ~5-15% coverage at best. + +`/enforce` now runs **three passes** over the same source markdown and emits +artifacts for the three enforcement tiers of the Interlinked architecture: + +| Tier | Layer | Consumer | Artifact | Cadence | +|---|---|---|---|---| +| 1 | Local deterministic | Interlinked harness (~sub-10ms) | `distilled-rules.json` | Every tool call | +| 2 | Cloud LLM policy gate | gpt-oss-safeguard-120b (~3-6s) | `policies/.policy.md` + Cedar companions | Most tool calls (post-filter) | +| 3 | Cloud architectural review | Sonnet/Opus on staged commits (~30-120s) | `policies/.prose.md` | Pre-push / on-demand `/review` / `/security-review` | +| — | Audit | Humans tightening source markdown | `policies/skipped.report.md` | After /enforce runs | + +### 15.1 — Three-pass routing (binding) + +For each imperative extracted under §4-§6, the distiller routes it to ONE or +MORE of the four artifact families based on trigger shape and FP risk: + +| Imperative shape | Pass 1 (deterministic) | Pass 2 (LLM gate) | Pass 3 (prose) | Skipped | +|---|---|---|---|---| +| Concrete regex-shape trigger, low FP | ✓ block/warn | (mirror, for trajectory context) | — | — | +| Concrete trigger + skill-scoped | ✓ block/warn | (mirror) | — | — | +| Concrete trigger + sequential precondition | — | ✓ warn (LLM evaluates trajectory) | — | — | +| Abstract / intent / semantic trigger | — | ✓ block/warn | — | — | +| Quality-of-output rule (vocabulary, required fields) | (optional content regex, FP-prone) | ✓ warn | rationale → prose | — | +| Definition / methodology / principle | — | — | ✓ | — | +| §5e SKIP (hedged, no signal, no imperative) | — | — | — | ✓ | + +A single source imperative can route to multiple passes. Example: the +`disk-forensics` "Never modify source evidence" imperative routes to Pass 1 +(file_path regex on `*.E01`/etc.) AND Pass 2 (LLM-side mirror for trajectory +context AND the residual intent rule "Never suggest evidence tampering"). + +**Critical: §6 ‡ ask-downgrade is removed.** Previously, sequential +preconditions ("Always X before Y") downgraded to `action: "ask"` because the +harness couldn't model the precondition. With Tier 2, the LLM evaluates the +precondition from trajectory. Emit a Pass 2 entry instead — no `ask`. + +### 15.2 — Pass 2: Policy doc format (`.policy.md`) + + + +Markdown with structured per-imperative entries. The Tier 2 LLM loads this +file as system-prompt context when its `active_when` scope matches. + +```markdown +# Policy: + +**Source:** +**Active when:** +**Generated by:** `/enforce` Pass 2, + +## P — + +- **id**: `enforce--` +- **severity**: critical | high | medium | low +- **active_when**: +- **action_on_violation**: block | warn +- **trigger_signal**: +- **source**: : — "" +- **lexical_marker**: +- **rationale**: +- **deterministic_companion**: +- **cedar_companion**: +- **suggested_remediation**: "" +``` + +Per-entry id format matches GuardRule ids: `enforce--`. +Action vocabulary is `block` or `warn` only — `ask` is removed (15.1). +PostToolUse warns and PreToolUse blocks are the only two states. + +### 15.3 — Pass 2: Cedar transpilation + +Two flavors of Cedar emitted per group, both derived from the policy entries +in `.policy.md`: + +**`.cedar` — Sondera-compatible** (default; drops into Sondera's +`policies/` directory without modification). Uses only fields in Sondera's +`base.cedarschema`: + +- Actions: `ShellCommand`, `ShellCommandOutput`, `FileRead/Write/Edit/Delete`, + `WebFetch`, `WebFetchOutput`, `Prompt`, `ToolOutput` +- Context fields: `command`, `path`, `operation`, `url`, `signature.*`, + `policy.*`, `label`, `workspace.*` +- Resource fields: `Trajectory.step_count`, `Trajectory.label`, + `Trajectory.taints`, `File.label` + +**`.interlinked.cedar` — Interlinked-extended** (only emitted when at +least one policy entry needs extensions). Adds: + +- `context.skill_active: String` — current skill scope +- `Trajectory.commands_run: Set` — accumulated shell commands +- `Trajectory.files_read: Set` — accumulated file reads +- `@action_on_violation("warn"|"block")` annotation (extends Cedar's + binary permit/forbid) +- `@requires_extension("")` annotation (engines without the + extension must reject the file) + +See `docs/design/interlinked-cedar-extensions.cedarschema` for the full +schema delta. + +**Regex → `like` translation.** Cedar `like` is glob-only, not regex. The +distiller best-effort expands: + +- `^pattern$` → `pattern` (Cedar `like` is implicitly anchored if no `*`) +- `\bword\b` → `* word *` and `word *` and `* word` (drops boundary precision) +- Negative lookahead → ANDed `like` exclusions (loses some precision) +- Character classes → enumerated alternations (e.g., `[ab]` → `*a*` || `*b*`) +- `+` / `?` quantifiers → drop (covered by `*`) + +When translation is lossy, emit the policy with `@confidence("approximate")` +and rely on `distilled-rules.json`'s actual-regex GuardRule as the precise +floor. The Cedar version is for portability + Sondera compatibility. + +When translation is impossible (e.g., trajectory state references on Sondera +side), emit a comment block in the `.cedar` file explaining why and pointing +to the `.interlinked.cedar` or `.policy.md` companion. + +### 15.4 — Pass 3: Prose artifact format (`.prose.md`) + +Pass 3 captures imperatives that aren't gates at all — definitions, +methodologies, principles — but that should inform the **after-the-fact +review** of staged commits by the Tier 3 cloud agent. + +Tier 3 has wider scope than Tier 2: it sees the full repo, the staged +commits, the agent's session log, and the prose artifacts for every skill +that was active during the session. It evaluates the staged work against +the principles in `prose.md` using full context. + +```markdown +# Prose policies: + +This file is consumed by the Tier 3 cloud review agent (pre-push, /review, +/security-review). The agent evaluates staged commits against these +principles using full repo context — NOT single-tool-call trajectory. + +## Definitions (canonical vocabulary) + + + +## Principles + +### + + + +**Tier 3 evaluation:** + +## Methodology checkpoints + + + +## Source + + +``` + +Pass 3 entries are **not enforced at edit time**. They're context for +the cloud reviewer. The distiller never blocks or warns on Pass 3 content. + +### 15.5 — Skipped report (`skipped.report.md`) + +Anything that didn't route to any of Passes 1-3. One file shared across +all groups distilled in a run. Format per existing §8 `skipped[]` array, +serialized as Markdown: + +```markdown +# Skipped imperatives — + +## + +### L — "" + +- **Lexical marker:** +- **Skip class:** `skip-hedged` | `skip-no-trigger` | `skip-abstract-trigger` + | `skip-no-imperative` | `skip-out-of-scope` | `skip-role-unmodellable` +- **Skip reason:** +- **Could be enforced if:** +``` + +Use this report to tighten source markdown — adding a concrete trigger or +stronger lexical marker would move an entry into one of the enforced passes. + +### 15.6 — Local-only mode (no cloud Tier 2 or Tier 3) + +For users who never touch our cloud or self-host Sondera: + +| Artifact | Local-only role | +|---|---| +| `distilled-rules.json` | Tier 1 floor — works as today, deterministic enforcement | +| `policy.md` | Loaded into agent context (advisory, not enforced) | +| `.cedar` (Sondera-compatible) | Drop into self-hosted Sondera installation | +| `.interlinked.cedar` | Inactive unless the Interlinked harness adds Cedar evaluation in v1.1+ | +| `prose.md` | Loaded into agent context (definitions, principles) | +| `skipped.report.md` | Human audit, identical to cloud mode | + +The deterministic floor + advisory loading covers ~30-40% of what cloud +adds. Cloud unlocks the LLM-evaluable trajectory rules (Pass 2) and the +wide-scope after-the-fact review (Pass 3). + +### 15.7 — Updated §6 ‡ (binding) + +§6 ‡ previously read: *"Sequential preconditions (Always X before Y) are +not directly representable in `GuardRule`. Distill to a single PreToolUse +rule on Y with `severity: "medium"` and `action: "ask"`."* + +This is **removed**. New rule: + +- Sequential preconditions distill to a Pass 2 `policy.md` entry, not a + Pass 1 `ask` rule. +- The policy entry's `trigger_signal` describes the precondition in + natural language; the Tier 2 LLM evaluates from trajectory. +- For local-only users (no Tier 2), the policy entry loads as agent + context — advisory, not enforced. This is strictly weaker than `ask` + was, but the FP cost of `ask` (user fatigue) outweighed the benefit. + +The trigger cookbook in §6 stays. Just the ‡ footnote is rewritten: + +> ‡ Sequential preconditions ("Always X before Y") are not directly +> representable in `GuardRule`. Emit a Pass 2 `policy.md` entry where +> `trigger_signal` describes the precondition. The Tier 2 LLM gate +> evaluates from trajectory. + +### 15.8 — Stats update for §13 summary + +The §13 final-summary table grows by one section to reflect three-pass +routing: + +``` +Distilled to: + Pass 1 — deterministic 12 (block/warn in distilled-rules.json) + Pass 2 — LLM policy gate 8 (block/warn in .policy.md) + ├── Sondera-compat .cedar 5 (translates to vanilla Cedar) + └── Interlinked .cedar 3 (requires schema extensions) + Pass 3 — prose for review 4 (definitions / principles for Tier 3) + Skipped 5 (hedged / no trigger / not imperative) +``` + +### 15.9 — Output schema additions + +The existing `distilled-rules.json` v1 schema (§8) gains an optional +`companions` sidecar on each rule, naming its Pass 2 / Pass 3 siblings: + +```json +"companions": { + "policy_md": ".interlinked/policies/.policy.md#", + "cedar": ".interlinked/policies/.cedar#", + "interlinked_cedar": ".interlinked/policies/.interlinked.cedar#", + "prose_md": ".interlinked/policies/.prose.md#" +} +``` + +And new top-level keys: + +```json +"policies_emitted": [".interlinked/policies/.policy.md", ...], +"prose_emitted": [".interlinked/policies/.prose.md", ...], +``` + +Schema version stays at 1 — additions are backward-compatible (existing +consumers ignore unknown fields). + +### 15.10 — Pre-flight additions for §11 + +When emitting Pass 2 or Pass 3 artifacts, ensure `.interlinked/policies/` +exists. Create it on first emission. Never overwrite a `.local.cedar` +file the user has hand-authored — these are the user's extension layer +and live alongside generated `.cedar` files. + +In fallback mode (no `.interlinked/` directory), Pass 2/3 artifacts land +at `./policies/.{policy.md,cedar,interlinked.cedar,prose.md}` at +the user's CWD. Same fallback message as §11 for `distilled-rules.json`. + +### 15.11 — Worked example + +See `docs/examples/policies/disk-forensics/` for a complete worked +example: one source SKILL.md, three deterministic rules, five policy +entries (3 mirror + 2 LLM-only), 2 Cedar files (Sondera + Interlinked), +and a skipped report. The example also demonstrates the Pass 3 prose +output for the skill's "Evidence Handling Principles" methodology +section. + +--- diff --git a/skills/enforce/references/discovery.md b/skills/enforce/references/discovery.md new file mode 100644 index 000000000..340a694ba --- /dev/null +++ b/skills/enforce/references/discovery.md @@ -0,0 +1,59 @@ +# enforce: source discovery (Steps 2a to 2c) + +Reference for [SKILL.md](../SKILL.md). Read it before a no-argument run or a directory walk. Step 2d, the skip list, stays in SKILL.md. +A § number names a step of /enforce: Steps 1 to 6.5 and 11 to 13 are in SKILL.md, and the +other steps are in the sibling files of this directory. + +### 2a — Project tree (CWD upward to git root) + +For each ancestor directory from CWD up to the repo root (the directory containing `.git/`), look for: + +| Filename / pattern | Kind | Notes | +|---|---|---| +| `AGENTS.override.md` | imperative | Highest project precedence | +| `*.local.md` (e.g. `CLAUDE.local.md`) | imperative | Personal, gitignored, beats shared | +| `AGENTS.md` | imperative | Cross-tool source of truth | +| `AGENT.md` | imperative | Singular variant (Amp/community) | +| `CLAUDE.md` | imperative | Claude Code | +| `GEMINI.md` | imperative | Gemini CLI | +| `WARP.md` | imperative | Warp legacy | +| `.github/copilot-instructions.md` | imperative | Repo-wide Copilot | +| `.github/instructions/*.instructions.md` | imperative | Path-scoped via frontmatter `applyTo` | +| `.cursor/rules/*.mdc` | imperative | Cursor; frontmatter `globs`/`description` is machine-readable | +| `.cursorrules` | imperative | Cursor legacy | +| `.clinerules` | imperative | Cline single-file legacy | +| `.clinerules/*.md` | imperative | Cline modular | +| `.windsurfrules` | imperative | Windsurf legacy | +| `.windsurf/rules/*.md` | imperative | Windsurf modular | +| `.continue/rules/*.md` | imperative | Continue.dev — frontmatter `globs`/`alwaysApply` | +| `.augment/rules/*.md` | imperative | Augment | +| `.tabnine/guidelines/*.md` | imperative | Tabnine | +| `.tabnine/guidelines.md` | imperative | Tabnine single-file | +| `.kilocoderules` | imperative | Kilo Code | +| `.claude/skills/*/SKILL.md` | scan-only | See §2c | +| `.agents/skills/*/SKILL.md` | scan-only | Shared native skill location used by Codex and other runners; see §2c | +| `~/.claude/skills/*/SKILL.md` | scan-only | See §2c | +| `CONVENTIONS.md` | imperative-likely | Aider-style | +| `code_review.md` | imperative-likely | Often referenced from AGENTS.md | +| `CONTRIBUTING.md` | mixed (scan only) | Pull only paragraphs with hard imperatives | +| `SECURITY.md` | mixed (scan only) | Pull only paragraphs with hard imperatives | +| `STYLEGUIDE.md` | mixed (scan only) | Pull only paragraphs with hard imperatives | +| `PLANS.md` | scan only | Mostly procedural | + +### 2b — User home (global rules) + +Look in `~/.claude/`, `~/.codex/`, `~/.gemini/`, `~/.config/copilot/`, `~/.continue/`, `~/.windsurf/` for the same patterns. Treat global rules as **lower precedence** than project rules unless they appear in `*.override.md` form. + +### 2c — Skills as scan-only sources + +SKILL.md files are mostly procedural (capability bundles). They are scan-only: extract paragraphs that hit the §4a/§4b lexical markers (`MUST NOT`, `bans`, `forbids`, `never`, `MUST`, `always`); ignore the rest. Every rule from a skill body has its `group_id` formed as `skill:` (extracted from the SKILL.md frontmatter `name` field) instead of `local:` or `gh:`. + +**Skill rules ARE scope-gated at runtime** via `active_when.skill`. The harness's `SessionTrajectory.active_skills` map is populated by `interlinked skill enter ` (called from a slash-command preamble) and read by the active-when evaluator. A distilled skill rule with `active_when.skill = ""` is **dormant** unless that skill is currently active in the session. This means: + +- **Distill at full strength** — a skill imperative phrased `Never X` distills to `action: "block"` per §5a, not the previous safety-downgrade to `ask`. The runtime scope makes the strength safe. +- **Composes with §10 conflict resolution** — scope-disjoint rules don't conflict; importing N skill rules without scope used to yield O(N²) collisions, with `active_when.skill` populated they only collide within the same skill or with always-on rules. +- **Skill-author opt-in cost is one line** — the slash-command preamble adds `interlinked skill enter ` (and a matching `leave` on completion). Skills that don't opt in still distill correctly but their rules are always-on (`active_when` omitted), which is the pre-active_when behavior. + +See `docs/design/harness-active-when-scoping.md` for the full design and §7 below for distiller population rules. + +The `skill:` group_id is also used for lifecycle ops (`/enforce remove --source skill:migrate-to-shoehorn`). diff --git a/skills/enforce/references/examples.md b/skills/enforce/references/examples.md new file mode 100644 index 000000000..743d79296 --- /dev/null +++ b/skills/enforce/references/examples.md @@ -0,0 +1,181 @@ +# enforce: worked examples + +Reference for [SKILL.md](../SKILL.md). Read it when a classification or trigger pattern is not clear. +A § number names a step of /enforce: Steps 1 to 6.5 and 11 to 13 are in SKILL.md, and the +other steps are in the sibling files of this directory. + +## Worked examples (apply these patterns mechanically) + +### Example 1 — Direct prohibition + +**Source (AGENTS.md:42):** "Never push to main without code review." + +```json +{ + "id": "enforce-local-agents-md-no-push-main", + "enabled": true, + "trigger": "PreToolUse", + "tool_match": ["Bash"], + "action": "block", + "patterns": [{ "field": "command", "regex": "^git\\s+push\\b.*\\bmain\\b" }], + "reason": "BLOCKED by AGENTS.md:42 — \"Never push to main without code review.\"", + "severity": "critical", + "category": "distilled-from-md", + "keywords": ["git"], + "source": { + "group_id": "local:AGENTS.md", + "group_label": "AGENTS.md", + "file": "AGENTS.md", + "lines": [42, 42], + "quote": "Never push to main without code review.", + "lexical_marker": "Never", + "marker_class": "block-direct" + } +} +``` + +### Example 2 — Positive imperative downgraded to ask (no session-state primitive) + +**Source (CLAUDE.md:88):** "Always run `npm test` before committing." + +```json +{ + "id": "enforce-local-claude-md-test-before-commit", + "enabled": true, + "trigger": "PreToolUse", + "tool_match": ["Bash"], + "action": "ask", + "patterns": [{ "field": "command", "regex": "^git\\s+commit\\b" }], + "reason": "CLAUDE.md:88 — \"Always run `npm test` before committing.\" The harness can't verify a recent test run; please confirm.", + "severity": "medium", + "category": "distilled-from-md", + "keywords": ["git"], + "source": { ... "lexical_marker": "Always", "marker_class": "block-positive" }, + "distilled_action_reason": "positive imperative, no session-state primitive → downgraded block→ask" +} +``` + +### Example 3 — Path-scoped block + +**Source (.clinerules/style.md:5):** "MUST NOT edit files under `db/migrations/` directly." + +```json +{ + "id": "enforce-local-clinerules-style-md-no-direct-migrations", + "enabled": true, + "trigger": "PreToolUse", + "tool_match": ["Edit", "Write", "MultiEdit", "apply_patch"], + "action": "block", + "patterns": [{ "field": "file_path", "regex": "(^|/)db/migrations/" }], + "reason": "BLOCKED by .clinerules/style.md:5 — \"MUST NOT edit files under db/migrations/ directly.\"", + "suggestion": "Use `npm run migrate:create` instead.", + "severity": "critical", + "category": "distilled-from-md", + "source": { ... "lexical_marker": "MUST NOT", "marker_class": "block-direct" } +} +``` + +### Example 4 — Soft preference → advisory (`warn`) + +**Source (CLAUDE.md:152):** "Prefer named exports over default exports for new modules." + +```json +{ + "id": "enforce-local-claude-md-prefer-named-exports", + "enabled": true, + "trigger": "PostToolUse", + "tool_match": ["Edit", "Write", "MultiEdit", "apply_patch"], + "action": "warn", + "patterns": [ + { "field": "content", "regex": "^export\\s+default\\b", "flags": "m" } + ], + "reason": "CLAUDE.md:152 prefers named exports over default exports.", + "severity": "low", + "category": "distilled-from-md", + "source": { ... "lexical_marker": "Prefer", "marker_class": "advisory" } +} +``` + +Note: an earlier draft of this example carried a second positive pattern on `file_path` (`\.tsx?$`) intended as an AND-style scope filter. Per §6 "Pattern semantics", positive patterns OR — that filter would have made the rule fire on every `.tsx` edit regardless of content. Single-pattern advisory rules are usually right; the verify pipeline gates noisy advisories at the report layer, not the rule layer. + +### Example 5 — Hedged → SKIP + +**Source (CLAUDE.md:201):** "We usually try to keep PRs small." + +→ Skipped entry only: +```json +{ "file": "CLAUDE.md", "lines": [201, 201], "quote": "We usually try to keep PRs small.", "reason": "hedged: 'usually try to'", "marker_class": "skip-hedged" } +``` + +### Example 6 — MCP tool prohibition + +**Source (AGENTS.md:71):** "Never use the `railway-mcp__volumeDelete` tool from agent sessions." + +```json +{ + "id": "enforce-local-agents-md-no-railway-volume-delete", + "enabled": true, + "trigger": "PreToolUse", + "tool_match": ["railway-mcp__volumeDelete"], + "action": "block", + "patterns": [], + "reason": "BLOCKED by AGENTS.md:71 — \"Never use railway-mcp__volumeDelete from agent sessions.\"", + "severity": "critical", + "category": "distilled-from-md", + "source": { ... "marker_class": "block-direct" } +} +``` + +### Example 7 — Skill-sourced rule with active_when scope + +**Source (`.claude/skills/migrate-to-shoehorn/SKILL.md:12`):** "**Test code only.** Never use shoehorn in production code." + +```json +{ + "id": "enforce-skill-migrate-to-shoehorn-no-prod-shoehorn", + "enabled": true, + "trigger": "PreToolUse", + "tool_match": ["Edit", "Write", "MultiEdit", "apply_patch"], + "action": "block", + "patterns": [ + { "field": "content", "regex": "from\\s+[\"']@total-typescript/shoehorn[\"']" }, + { "field": "file_path", "regex": "\\.test\\.|\\.spec\\.|/__tests__/|/__fixtures__/", "negate": true } + ], + "reason": "BLOCKED by migrate-to-shoehorn skill: shoehorn is a test-only library — never import it from production code paths.", + "severity": "high", + "category": "distilled-from-md", + "active_when": { + "skill": "migrate-to-shoehorn" + }, + "source": { + "group_id": "skill:migrate-to-shoehorn", + "group_label": "skill:migrate-to-shoehorn", + "file": ".claude/skills/migrate-to-shoehorn/SKILL.md", + "lines": [12, 12], + "quote": "Never use shoehorn in production code.", + "lexical_marker": "Never", + "marker_class": "block-direct" + }, + "distilled_action_reason": "lexical 'Never' + concrete content+file_path triggers (positive on import line, negate on test paths) → action=block per §5a; scope-gated to skill:migrate-to-shoehorn per §7 active_when population — rule is dormant until `interlinked skill enter migrate-to-shoehorn` fires" +} +``` + +Three things to notice about this example: + +1. **`active_when.skill` is populated automatically** because the source is `/SKILL.md`. The distiller doesn't ask; per §7's source-location table, every skill body rule gets `active_when.skill = ""`. +2. **Action stays `block`, not downgraded to `ask`**. With pre-active-when distillation, skill rules had to soften because they were always-on and would over-fire outside their domain. With scope, full-strength enforcement is safe — the rule simply doesn't fire when the skill isn't active. +3. **The skill author still has to opt in.** A user running this skill must include `interlinked skill enter migrate-to-shoehorn` in the slash-command preamble (and `leave` on completion). Skills that don't opt in distill correctly but their `active_when.skill` marker is never set, so the rule stays dormant. This is intentional — it makes activation explicit. + +Note: TDD-themed skills (Matt Pocock's `tdd/SKILL.md`, gstack's TDD prose, etc.) are **not** distilled by /enforce — see §2d skip list. TDD enforcement is owned by the harness's native primitives. This example uses a non-TDD skill so the worked example doesn't conflict with that policy. + +### Example 8 — Conflict between AGENTS.override.md and AGENTS.md + +**`AGENTS.md:42`:** "Never push to main without code review." +**`AGENTS.override.md:12`:** "MUST NOT push to ANY remote branch this week — release freeze." + +The override is strictly broader. Output: +- `rules[]` contains the override-derived rule with `tool_match=["Bash"]` + `command~/^git\s+push\b/`. +- The narrower AGENTS.md rule is suppressed. +- `conflicts[]` records `winning_source: "AGENTS.override.md:12"`, `overridden_sources: ["AGENTS.md:42"]`. + +--- diff --git a/skills/enforce/references/lifecycle.md b/skills/enforce/references/lifecycle.md new file mode 100644 index 000000000..71c6585f7 --- /dev/null +++ b/skills/enforce/references/lifecycle.md @@ -0,0 +1,144 @@ +# enforce: common workflows and lifecycle operations (Step 14) + +Reference for [SKILL.md](../SKILL.md). Read it when the first argument is a lifecycle verb. +A § number names a step of /enforce: Steps 1 to 6.5 and 11 to 13 are in SKILL.md, and the +other steps are in the sibling files of this directory. + +## Common workflows + +### First-time setup on a project + +``` +/enforce # walk the tree, distill what's there, print a report +/enforce list # confirm the rule set looks right + # harness reloads automatically within ~2s (watchFile) +``` + +### Adopt a remote skill (review-first) + +``` +/enforce gh:mattpocock/skills/tdd # fetched, distilled to review-mode by default +/enforce list # inspect what would activate +/enforce --accept # promote review → live +``` + +### A rule is too noisy + +``` +/enforce show # see what fired and why +/enforce modify --action ask --severity medium # downgrade +# or, to keep it on disk but stop enforcing entirely: +/enforce disable +``` + +### Reject a whole source forever + +``` +/enforce remove --source gh:someone/skills/qa +``` + +Adds the group to `removed_groups[]`; stays gone across re-distillation. Undo with `/enforce add --source `. + +### A .md file changed; re-distill + +``` +/enforce # unchanged files skipped via hash; user mods preserved + # harness reloads automatically within ~2s +``` + +### Throw it all away and start fresh + +``` +rm .interlinked/distilled-rules.json .interlinked/distilled-rules.overrides.json +/enforce +``` + +--- + +## Step 14 — Lifecycle operations (`/enforce `) + +When the first argument is a lifecycle verb, run that operation instead of distilling. + +### `/enforce list` + +Read `.interlinked/distilled-rules.json` + `.interlinked/distilled-rules.overrides.json`. Print: + +``` +Source Rules Block Ask Advisory Disabled +──────────────────────────────────────────────── ──── ───── ──── ─────── ──────── +local:AGENTS.md 8 5 1 2 0 +local:AGENTS.override.md 2 2 0 0 0 +local:CLAUDE.md 5 2 1 2 1 +local:.clinerules/style.md 3 2 0 1 0 +gh:mattpocock/skills/tdd 2 2 0 0 0 +skill:tdd 2 2 0 0 0 +──────────────────────────────────────────────── ──── ───── ──── ─────── ──────── +Total 22 14 2 6 1 + +Removed groups: gh:mattpocock/skills/qa (3 rules suppressed) + +Run `/enforce list ` to drill in. +Run `/enforce remove --source ` to bulk-remove from a source. +``` + +### `/enforce list ` + +Drill into a single source: + +``` +Source: gh:mattpocock/skills/tdd + +✗ enforce-skill-tdd-no-bulk-tests block high + Source: gh:mattpocock/skills/tdd:23-25 + Quote : "explicitly bans the horizontal anti-pattern" + Rule : trigger=PreToolUse, tool_match=[Edit,Write], patterns=[command~/^...$/] + Lexical: bans → block-direct + +✗ enforce-skill-tdd-test-before-source block high + Source: gh:mattpocock/skills/tdd:30-31 + … +``` + +### `/enforce show ` + +Print one rule's full JSON, plus its source-file context (3 lines before, the quote, 3 lines after). + +### `/enforce remove --source ` + +Read overrides; add `` to `removed_groups[]`. Save. Print: `Removed group (N rules suppressed). Run /enforce add --source to undo.` + +### `/enforce remove ` + +Read overrides; add `` to `removed_rule_ids[]`. Save. Print confirmation. + +### `/enforce disable ` + +Read overrides; add `` to `disabled_rule_ids[]`. Save. Rule stays in distilled-rules.json but loads with `enabled: false`. + +### `/enforce enable ` + +Read overrides; remove `` from `disabled_rule_ids[]`. Save. + +### `/enforce modify --action ask --severity medium` + +Read overrides; set `modifications[] = { action: "ask", severity: "medium", note: }`. Save. + +Allowed flags: `--action `, `--severity `, `--note `. + +### `/enforce add --source ` + +Read overrides; remove `` from `removed_groups[]`. Save. Print: `Group restored. Run /enforce to re-distill and pull rules from it.` + +### `/enforce reset ` + +Read overrides; clear all entries for ``: remove from `removed_rule_ids`, `disabled_rule_ids`, and `modifications{}`. Save. + +### `/enforce --review` + +Distill-with-pause: write to `.interlinked/distilled-rules.review.json` instead of `distilled-rules.json`. The harness does not load `.review.json`. Default mode for remote sources. + +### `/enforce --accept` + +Promote `distilled-rules.review.json` → `distilled-rules.json`. Validate first; abort if validation fails. + +--- diff --git a/skills/enforce/references/report-format.md b/skills/enforce/references/report-format.md new file mode 100644 index 000000000..03b83b797 --- /dev/null +++ b/skills/enforce/references/report-format.md @@ -0,0 +1,41 @@ +# Distillation report + +End every run with this tabular summary: + +``` +Distilled-rules report + +Sources scanned 9 files + imperative-bearing 6 + scan-only 2 + persona/skipped 1 + +Imperatives found 28 + +Distilled to: + block 12 (criticals from MUST NOT / never / forbidden / shall not) + ask 4 (should not / avoid) + advisory 7 (should / prefer / consider) + +Skipped: + hedged 5 (we usually try / ideally) + no trigger 0 + out-of-scope 0 + +Conflicts 1 (AGENTS.override.md beat AGENTS.md on git-push-main) +Removed 0 +User-disabled 0 +User-modified 1 + +Output: .interlinked/distilled-rules.json +Run `/enforce list` to inspect. The harness picks up the new rules within ~2s automatically. + +Top distilled rules: + ✗ enforce-agents-override-no-push-this-week AGENTS.override.md:12 block + ✗ enforce-claude-no-prod-deletes CLAUDE.md:88 block + ✗ enforce-clinerules-no-cypress .clinerules/style.md:5 block + ⚠ enforce-claude-prefer-named-exports CLAUDE.md:152 advisory + … +``` + +For `--review` mode: replace "Output:" with "Review-mode output:" and add: "Run `/enforce --accept` to activate, or edit `.interlinked/distilled-rules.review.json` first." diff --git a/skills/enforce/references/rule-schema.md b/skills/enforce/references/rule-schema.md new file mode 100644 index 000000000..80f4857a5 --- /dev/null +++ b/skills/enforce/references/rule-schema.md @@ -0,0 +1,185 @@ +# enforce: rule build, output schema, overrides, conflicts (Steps 7 to 10) + +Reference for [SKILL.md](../SKILL.md). Read it before you write output on a distill run. +A § number names a step of /enforce: Steps 1 to 6.5 and 11 to 13 are in SKILL.md, and the +other steps are in the sibling files of this directory. + +## Step 7 — Build the distilled rule (one entry per imperative) + +The distilled rule object is a real `GuardRule` with a `source` sidecar field added. The harness ignores `source`; the CLI uses it for lifecycle operations. + +```json +{ + "id": "enforce--", + "enabled": true, + "trigger": "PreToolUse", + "tool_match": ["Bash"], + "action": "block", + "patterns": [ + { "field": "command", "regex": "^git\\s+push\\b.*\\bmain\\b" } + ], + "reason": "BLOCKED by AGENTS.md:42 — \"Never push to main without code review.\"", + "suggestion": "Open a PR and request review, then merge through the standard flow.", + "severity": "critical", + "category": "distilled-from-md", + "keywords": ["git"], + "source": { + "group_id": "local:AGENTS.md", + "group_label": "AGENTS.md", + "file": "AGENTS.md", + "lines": [42, 42], + "quote": "Never push to main without code review.", + "lexical_marker": "Never", + "marker_class": "block-direct" + }, + "distilled_action_reason": "lexical 'Never' → action=block per §5a", + "confidence": 0.95 +} +``` + +**ID slug rule:** `enforce--`. Group-stem is derived from `group_id` (drop scheme prefix, replace `/`/`.`/`:` with `-`, lowercase). Summary is ≤6 words from the imperative's intent, kebab-case. + +**`group_id` schemes:** + +| Scheme | Format | Example | +|---|---|---| +| `local:` | `local:` — repo-relative when a git root exists, otherwise CWD-relative | `local:AGENTS.md`, `local:.clinerules/style.md` | +| `home:` | `home:` | `home:.claude/CLAUDE.md` | +| `gh:` | `gh://` | `gh:mattpocock/skills/tdd` | +| `url:` | `url:` | `url:example.com/foo.md` | +| `skill:` | `skill:` (from SKILL.md frontmatter) | `skill:tdd`, `skill:grill-me` | + +Skill-sourced rules ALWAYS use the `skill:` scheme; they carry their physical install path in `source.file` but are grouped by skill-name so cross-install moves don't fragment the group. + +**`confidence`:** 0.95 for clean direct-prohibition. 0.85 for positive-form. 0.7 for cases where the trigger required interpretation. Below 0.7 → downgrade to advisory. + +**`active_when` population (binding):** every distilled rule with a known scope MUST carry an `active_when` field per the table below. Rules from project-wide imperative sources (root CLAUDE.md, AGENTS.md, etc.) omit `active_when` (always-on). Rules from skill bodies, model-overlay files, or path-scoped sources populate it deterministically. Population is purely structural — no LLM judgment. + +| Source location | `active_when` populated as | +|---|---| +| `/AGENTS.md`, `/CLAUDE.md`, `/AGENTS.override.md`, `*.local.md`, `.clinerules/`, `.cursor/rules/`, `.continue/rules/`, `.windsurf/rules/`, `.augment/rules/`, `.tabnine/`, `.kilocoderules` | omitted (always-on) — these are the project-wide gates | +| `/SKILL.md` body (any install path) | `{ skill: "" }` — skill-name from frontmatter | +| `model-overlays/.md` (or any sibling persona-by-runner directory) | `{ overlay: "" }` | +| `.github/instructions/.instructions.md` with frontmatter `applyTo: ""` | `{ file_scope: "" }` | +| `.cursor/rules/*.mdc` with frontmatter `globs: [...]` | `{ file_scope: "" }` | +| `.continue/rules/*.md` with frontmatter `alwaysApply: false` + `globs: [...]` | `{ file_scope: "" }` | +| Skill body imperative referencing "after running /" or "after the user invoked X" | merge `{ after_command: { pattern: "^/\\b", window_steps: 20 } }` into the existing scope | +| Skill body imperative referencing TDD state | **not emitted** — TDD is owned by harness primitives; rule is dropped per §2d skip list | + +When multiple axes are inferred from one source (e.g., a skill body that also mentions "after /ship"), all axes are AND-ed in `active_when`. The distiller emits the union; `confidence` drops by 0.05 per inferred axis beyond the first. + +**`applies_to_roles` population (binding).** A source file is *role-scoped* when its basename is `.prompt` / `.agent.md`, or its body opens with `You are the .`. The harness `AgentRole` type (`src/harness/types.ts`) is exactly `"lead" | "worker" | "subagent" | "unknown"`: + +- If `` is one of those four, set `applies_to_roles: [""]` on every rule distilled from that file. +- If `` is NOT — e.g. a bespoke multi-agent cohort such as SwarmForge's `architect` / `coder` / `refactorer` / `reviewer` / `specifier` — the harness has no axis to scope the rule, so a Pass 1 rule from one role's prompt applies to *every* agent. That is a correctness bug, not noise: `refactorer.prompt`'s "Do not run mutation tests" emitted globally directly contradicts `reviewer.prompt`'s "Run … mutation tests." Such imperatives MUST NOT be written to `distilled-rules.json`. Route them to Pass 2 (`policy.md`) with the role named in `trigger_signal` ("…when the acting agent's role is `refactorer`"); the Tier-2 gate resolves role from trajectory. If Pass 2 is unavailable (local-only mode), log to `skipped.report.md` with skip class `skip-role-unmodellable`. §10 conflict resolution does NOT catch this — only the prohibition carries a lexical marker, so the contradicting permission never distills and no conflict pair forms. + +**Schema attribution.** The shape above is the Interlinked harness's `GuardRule`, defined at `src/harness/types.ts` in the `interlinked-cli` package. The four sidecar fields (`source`, `distilled_action_reason`, `confidence`, `user_modified`) are the only additions this skill makes; the harness ignores them at evaluation. The `active_when` field is a real `GuardRule` field (added 2026-04 alongside the active-when scoping work) — the harness reads and evaluates it at runtime via `evaluator/active-when.ts`. Other hook engines that want to consume the same artifact must implement matching evaluation semantics — regex on `tool_input` fields, the six action types (`block` / `warn` / `rewrite` / `soft_block` / `ask` / advisory), severity, keyword quick-reject, role scoping, exception patterns, AND active_when scope evaluation. The skill targets `GuardRule` because it's the most expressive open enforcement primitive today; downgrading to a less-expressive runtime (Claude Code's `permissions.deny[]`, Cursor `.mdc` globs, Codex deny configs) would lose the regex/PostToolUse/severity/active_when dimensions, so this skill does not ship multi-backend adapters. If you want to use the artifact outside Interlinked, write your own evaluator against this schema. + +--- + +## Step 8 — Output schema + +Write `.interlinked/distilled-rules.json`: + +```json +{ + "version": 1, + "distilled_at": "2026-04-27T18:30:00Z", + "distiller": "skill:enforce@1", + "source_hashes": { + "AGENTS.md": "sha256:abc123…", + "CLAUDE.md": "sha256:def456…", + ".clinerules/style.md": "sha256:789abc…" + }, + "rules": [ /* distilled rule objects per §7 */ ], + "skipped": [ + { + "file": "CLAUDE.md", + "lines": [78, 80], + "quote": "We usually try to write tests before code.", + "reason": "hedged: 'usually try to'", + "marker_class": "skip-hedged" + } + ], + "conflicts": [ + { + "id": "enforce-agents-no-force-push", + "winning_source": "AGENTS.override.md:12", + "overridden_sources": ["AGENTS.md:42"], + "resolution": "AGENTS.override.md > AGENTS.md per precedence stack" + } + ], + "removed": [ + { + "id": "enforce-claude-no-cypress", + "reason": "source quote no longer present in CLAUDE.md as of 2026-04-27" + } + ], + "stats": { + "files_scanned": 9, + "imperatives_found": 28, + "distilled_block": 12, + "distilled_ask": 4, + "distilled_advisory": 7, + "skipped_hedged": 5, + "conflicts": 1, + "removed": 0 + } +} +``` + +The harness's `rules-loader.ts` reads this file alongside `guard-rules.json` and `guard-rules.local.json` and applies the overrides file (next section). The harness's `watchRulesFiles()` polls both distilled paths every ~2s, so changes are picked up automatically — no manual reload command exists. If the daemon appears stuck, confirm with `interlinked harness status` before guessing: it round-trips the socket and reports `ZOMBIE` when a live PID is answering nothing (the state that looks exactly like "rules stopped reloading"). `.interlinked/daemon-events.jsonl` records why the last daemon left — a pre-listen startup failure exits 78 with `reason: "startup-failed"` — and `.interlinked/logs/daemon.log` holds any crash output. Either way the fix is `interlinked harness restart`. + +For `--review` mode: write to `.interlinked/distilled-rules.review.json` instead. The harness does not load `.review.json`; the user must run `/enforce --accept` to promote it. + +--- + +## Step 9 — Overrides file (the user's mods) + +`.interlinked/distilled-rules.overrides.json` survives re-distillation: + +```json +{ + "version": 1, + "removed_groups": ["gh:mattpocock/skills/qa"], + "removed_rule_ids": ["enforce-claude-no-cypress"], + "disabled_rule_ids": ["enforce-agents-prefer-named-exports"], + "modifications": { + "enforce-skill-tdd-no-bulk-tests": { + "action": "ask", + "severity": "medium", + "note": "downgraded — too noisy on legacy tests/ dir" + } + } +} +``` + +The harness applies these on every load. Removed groups stay removed across re-distillation (so deleted things don't whack-a-mole back). Modifications layer on top of the pristine distilled rule. + +**On distill, the skill MUST read this file before extracting** and: +- Skip any source whose `group_id` is in `removed_groups[]`. Never even fetch a removed group. +- Skip any rule whose `id` is in `removed_rule_ids[]`. The pristine rule still appears in the output but with `enabled: false` and a note. +- Apply `modifications{}` after distillation and mark those rules with `user_modified: true` for the report. + +--- + +## Step 10 — Conflict resolution + +Precedence stack (highest to lowest): + +1. `AGENTS.override.md` +2. `*.local.md` (CLAUDE.local.md, etc.) +3. Project rule-folder files (`.claude/rules/`, `.continue/rules/`, `.windsurf/rules/`, `.augment/rules/`, `.clinerules/`, `.cursor/rules/`) +4. `AGENTS.md` / `CLAUDE.md` / `GEMINI.md` / `WARP.md` +5. Path-scoped frontmatter files (`.github/instructions/*.instructions.md`) +6. SKILL.md bodies (group_id `skill:`; no runtime scope — collisions are real but resolved by precedence here) +7. `CONTRIBUTING.md` / `SECURITY.md` / `STYLEGUIDE.md` / `CONVENTIONS.md` +8. `~/` global counterparts of any of the above + +When two distilled rules collide on `(trigger, tool_match, patterns[].regex)`: + +- If actions differ: take the strictest (`block` > `ask` > `soft_block` > `warn`). +- Always merge: keep the higher-precedence source as `winning_source`; record the lower-precedence ones in `overridden_sources[]`. +- Never silently drop the loser — surface in `conflicts[]`. + +--- diff --git a/skills/interlinked-coordination/SKILL.md b/skills/interlinked-coordination/SKILL.md index 33d944b91..532e84f04 100644 --- a/skills/interlinked-coordination/SKILL.md +++ b/skills/interlinked-coordination/SKILL.md @@ -1,6 +1,6 @@ --- name: interlinked-coordination -description: "Coordinate with other agents/humans via the optional Interlinked MCP Server, and use local checkpoints & file reservations. Load this when picking up or handing off work (`tasks`, `send`, `inbox`, `handoff`), switching workspace context (`workspace`, `attach`), when a write is blocked because a file is \"reserved by\" another agent, when creating/restoring a local checkpoint (`checkpoint`, `rewind`, `resume`), installing the git-hook reservation guard (`interlinked guard`), or checking CI failure rates (`ci-status`). IMPORTANT: `checkpoint`/`rewind`/`resume` MUTATE git state (stash, checkout, clean -fd) and must not be run without explicit per-turn user authorization." +description: "Coordinate with other agents and humans through the optional Interlinked MCP Server, local checkpoints, and file reservations. Load to pick up or hand off work (`tasks`, `send`, `inbox`, `handoff`), switch workspace (`workspace`, `attach`), when a write is blocked as \"reserved by\" another agent, for `interlinked guard` (git-hook reservations), CI failure rates (`ci-status`), or `checkpoint`/`rewind`/`resume`. WARNING: those three change git state (stash, checkout, clean -fd); run them only with explicit per-turn user authorization." --- # interlinked-coordination — multi-agent server surface & local checkpoints @@ -29,14 +29,13 @@ The whole server half is opt-in. Auth resolution: explicit `--token` → `access ## ⚠️ Git-safety (read before any checkpoint/rewind/resume) `checkpoint`, `rewind`, `resume`, and `git link-checkpoint --apply` **mutate git state** — -`git stash`, `git checkout ` (detaches HEAD), `git checkout -- . && git clean -fd` +`git stash`, detached HEAD updates, `git restore --staged` / `--worktree`, and `git clean -fd` (discards uncommitted changes + deletes untracked files), or commit amend. Under the standing rule that **each commit/push/reset/stash/checkout is an independent per-turn ask**, an agent must **not** run these autonomously — describe and recommend, don't execute, unless the user -explicitly authorizes it this turn. Also note **`rewind` rarely restores the working tree** -(the checkpoint stash is popped at creation, so the message-based lookup usually finds nothing) -— its reliable effect is detaching HEAD to the base commit with a "changes may be missing" -warning. Don't rely on it as an undo. +explicitly authorizes it this turn. Checkpoint creation retains a snapshot object +and restores the captured index/worktree. Restore verifies its snapshot and base +before forced cleanup. ## Server-backed commands `tasks`/`send`/`inbox`/`handoff`/`workspace` are auth-gated (`!isAuthenticated && @@ -111,8 +110,11 @@ client wired in, reservations are a purely local optimistic lease shared across still useful, just no cross-machine truth. ## Local checkpoints (git-mutating — see the warning above) -Metadata in `.interlinked/checkpoints.json`; working-tree state via a transient git stash. -A checkpoint captures HEAD SHA, changed files, and a stash ref. +Metadata lives in `.interlinked/checkpoints.json` or the configured data directory. +A checkpoint captures HEAD SHA, changed files and a stash object ID. Snapshots are +pinned by `refs/interlinked/checkpoints/` and also retain their ordinary stash +entry. Clearing the ordinary stash list leaves the pinned object available. +Metadata pruning and archiving retain snapshot objects and refs. An absent metadata file starts an empty history. An existing unreadable file, invalid JSON or malformed checkpoint record instead stops the operation with its @@ -120,15 +122,40 @@ path; it is never treated as empty. Creation validates metadata before stashing, and prune/archive cannot overwrite a malformed ledger. Preserve and repair the existing metadata before retrying rather than deleting it to clear the error. +Restoration stops when Git cannot determine the working-tree status or check out +the checkpoint's base commit. `rewind` reports the error before applying a stash. +Archiving beyond the active-checkpoint capacity retires the oldest checkpoints +first, retaining the newest eligible checkpoints. +Stored base commits used by restore/compare must be full SHA-1 or SHA-256 object +IDs. Inventory and retention commands preserve existing metadata for repair. +Restore verifies the commit object before forced cleanup. Input-bearing Git +operations pass literal argument arrays, including structured stash messages. +It also verifies snapshot/index/untracked trees, their paths and matching base. Legacy stored object +IDs and message-based lookup remain supported. Missing or inconsistent data fails +before forced cleanup. Capture, source-tree restoration and untracked cleanup +exclude owned state in both the index and worktree, including tracked configuration +and checkpoint history. Detaching HEAD preserves the original branch tip. +`checkpoint prune --older-than` and `--keep-latest` require positive safe integers. +Invalid explicit values fail before metadata mutation. + | Command | Effect | |---|---| -| `interlinked checkpoint [message]` | **Creates** a checkpoint (runs `git stash push --include-untracked` then immediately `git stash pop` — a stash/pop; a pop conflict can leave changes stashed). | +| `interlinked checkpoint [message]` | Captures source changes with `git stash push`, pins the object, and restores captured worktree/index trees while excluding owned state. A clean source tree creates metadata-only history and preserves older user stashes. Git discovery failures stop before writing history. | | `checkpoint list` / `show ` / `compare ` | Metadata/diff-stat only — **no git mutation**. | | `checkpoint prune [--older-than --keep-latest]` / `archive` | Rewrite metadata only (stash cleanup deliberately skipped). | -| `interlinked rewind [id] [--force]` | On a dirty tree refuses without `--force`; with `--force` runs `git checkout -- . && git clean -fd` (**discards changes**), then `git checkout ` (detaches HEAD). | +| `interlinked rewind [id] [--force]` | Refuses a dirty tree without `--force`. Preflights the base and snapshot trees, detaches HEAD without moving the original branch, and restores source index/worktree/untracked paths. Forced cleanup preserves tracked and untracked owned state. | | `interlinked resume [id]` | Non-destructive on a dirty tree, **but still `git checkout ` (detaches HEAD) on a clean tree**; then best-effort server work-context. | | `interlinked git link-checkpoint --apply` | **Amends HEAD** to link a server checkpoint (rewrites the commit). | +Git link apply resolves its selected commit and HEAD before server work and +rechecks them before local mutation. The selected commit must resolve to HEAD. +Amend and notes subprocesses use literal arguments. Required message/identity +discovery failures and incomplete writes exit nonzero with `applied:false`. +JSON includes `apply_error` when a local apply step fails. A notes failure after +amending leaves the new commit identity in the result for recovery. +Explicit checkpoint IDs must be complete positive safe integers. Omitting the +ID retains the latest-checkpoint lookup, and an explicit blank ID fails. + ## `interlinked guard` — git-hook reservation enforcement A separate git pre-commit/pre-push hook (not the PreToolUse daemon guard): ```bash @@ -143,6 +170,9 @@ be outdated. - `interlinked ci-status [--limit --branch]` — shells out to `gh run list` (needs the GitHub `gh` CLI, **not** the Interlinked server); aggregates per-workflow failure rate. "This step failed 7 of the last 10 pushes" before you push. + A failed gh process or malformed response exits nonzero. A successful empty array + remains an empty run collection. Limit text must be a complete safe integer, and + accepted integers retain the existing 1–100 clamping. - `interlinked reminder add --glob

--message [--ops Edit,Write,Read] [--team]` / `reminder list` / `reminder remove` — file-touch reminders that warn when a matching file is edited. @@ -150,6 +180,9 @@ be outdated. spawns a real stdio MCP server and records its JSON-RPC traffic for observability. **There is no `mcp serve`; it does not expose Interlinked's own tools.** The real MCP Server is the remote Worker reached over HTTP by the server-backed commands above. + Set `--inline-limit ` to a non-negative decimal integer through + 9007199254740991. Zero sends every nonempty payload to blob storage. Invalid + values fail before the server starts. ## Common workflows - **Pick up a task:** `tasks list --status open` → `tasks claim ` → work → `tasks complete `. diff --git a/skills/interlinked-cowork/SKILL.md b/skills/interlinked-cowork/SKILL.md index 9d4ec78ec..bb9f3208f 100644 --- a/skills/interlinked-cowork/SKILL.md +++ b/skills/interlinked-cowork/SKILL.md @@ -9,6 +9,11 @@ Cowork uses an uploaded plugin, separately from Claude Code settings. Ordinary D ## Native evidence and limitations +To check the hook's malformed-input response from the CLI source checkout, run +`node --import tsx src/cowork-hook.ts --event PreToolUse` from the repository +root and send EOF on empty stdin. Stdout should contain a JSON verdict with +`permissionDecision` equal to `deny`. The native installation has its own probe below. + Run `interlinked cowork capabilities --json`. Dated native evidence is distinct from the current installation, which remains unmeasured until probed. On Desktop 1.49585.0 cloud mode, native deny, ask, input rewrite, and post-tool context were observed. Hook crashes and provider timeouts allowed synthetic writes. The guard launcher converts child failures, missing Node, and a 12-second internal deadline to explicit denial before the 15-second native deadline. If the provider never launches or kills the entire hook, this wrapper cannot enforce anything. The ordinary plugin installs six lifecycle/tool hooks. A separate `--probe` package registers the larger Claude Code event catalog, including failure/subagent events, to measure availability; registration does not establish emission or enforcement. Keep fault injection confined to synthetic tasks, then disable the probe plugin. Do not retry denied actions through another tool. diff --git a/skills/interlinked-harness/SKILL.md b/skills/interlinked-harness/SKILL.md index 2b5cf93ee..406e7c63d 100644 --- a/skills/interlinked-harness/SKILL.md +++ b/skills/interlinked-harness/SKILL.md @@ -1,183 +1,10 @@ --- name: interlinked-harness -description: "Understand and respond to the Interlinked PreToolUse guard — the local daemon that BLOCKS dangerous tool calls before they run. Load this when a Bash command or file edit was refused with \"BLOCKED: … Suggestion: …\", when you see an `[interlinked:check-id]` warning tagged `[proven]` or `[heuristic]`, when a destructive command / force-push / protected-file / secret / repo-confinement rule fired, when a grep was answered by the index, or when you need to know how to legitimately suppress a false positive or disable a guard rule. Covers what blocks, how to read the reason, suppression grammar, determinism tags, and the degraded cold fallback." +description: "Respond to the Interlinked PreToolUse guard, the local daemon that BLOCKS dangerous tool calls before they run. Load when a Bash command or edit was refused with \"BLOCKED: … Suggestion: …\", when an `[interlinked:check-id]` warning tagged `[proven]` or `[heuristic]` appears, when a destructive-command, force-push, protected-file, secret, or repo-confinement rule fired, when the index answered a grep, or to suppress a false positive or disable a guard rule legitimately. Covers suppression grammar, determinism tags, and the degraded cold fallback." --- # interlinked-harness — the guard: what blocks you & how to respond -Commit-time function-token diagnostics compare against `HEAD` and name their scope: -staged index, tracked working tree, selected constructed paths, or a conservative -worktree scan. They do not identify the writer or when the changes were made. -Only the first eight findings are displayed; the full set still determines the block. -For unresolved compound staging scope, stage first and commit in a separate tool call -to check the exact index. This changes the observed scope, not the cap or enforcement. - -`INTERLINKED_RUNTIME_POLICY=local-restricted` opts into a packaged local runtime -policy shared by the CLI, daemon and generated cold fallback. It denies network -calls and selected external commands, and refuses recognized agent reads of -`.interlinked/config.local.json`; internal configuration readers still work. -It is application policy, not a sandbox for arbitrary child code or computed paths. -Unavailable tools remain unmeasured; this mode does not certify skipped checks. - -Remote-pipe detection permits interpreter inline programs preceded by bare flags -(for example, `curl URL | python3 -I -c '...'`), where stdin is data. Shell sinks -retain their existing remote-execution block. - -For recognized protected pushes in this repository, Codex and Claude can receive a -native command replacement that makes Git's exact-revision pre-push hook the sole -owner of typecheck and test execution. The replacement pins Git/Node, verifies a -private snapshot of the recognized hook and its helper runtime, and forces Git to -use that hook. Git still supplies the actual ref updates and pushed SHAs. This is -not a cached passing verdict, and every other pre-tool guard remains active. - -Recognition is intentionally narrow: a plain `git push ` -from the repository root, with supported literal output redirection. Compound -commands, environment/config overrides, unsupported clients, custom/missing/changed -hooks or unavailable snapshots retain legacy checks. A prepared command whose -snapshot or execution context changes refuses the push. Do not weaken guards or -use bypass flags to force the handoff. See `docs/verification-efficiency.md`. - -Every fallback of a recognized push is typed and visible (2026-11-05). The daemon -writes a `pre-tool:managed-push` row with status `fallback` and -`reuse_denied_reason: handoff-fallback:` to the stage ledger, and the agent -sees one `[interlinked:managed_push_fallback] … (: )` warning. Causes: -`environment-override` (the detail names the variable keys, never values), -`repository-mismatch`, `hook-mismatch`, `stale-trust-map` (regenerate the map after -reviewing the change), `executable-identity`, `snapshot-failure`. A command or client -the handoff never covers (`unsupported-*`) leaves no fallback row; the legacy rows are -its record. The IDE prompt helpers `GIT_ASKPASS` and `GIT_EDITOR` are allowed at -preparation and execution (VS Code exports both in every terminal; neither selects -a repository, configuration, hook, exec path, transport or loader). Every other -`GIT_*` variable except `GIT_PAGER` still refuses the handoff. Explain a real push -from one trace with `interlinked tests trace` (see **interlinked-verify**). -For a recognized fallback on a client supporting command replacement, the response -adds only the trace environment assignment to the original push; the legacy checks -still run. If the client disconnects before receiving that response, the plain push -has a separate hook trace: do not infer a complete daemon/hook join. Unknown failures -use a bounded operation/error-code detail, never arbitrary exception or file contents. - -A hook client that times out (240 s PreToolUse in the installed settings) and -cold-allows the push no longer leaves the daemon's legacy test gate holding the host -slot: both socket transports abort a request's signal when its client disconnects, -and the pre-tool git gate kills its child on it, recording `interrupted`. -Queued framed requests retain that aborted signal after disconnect as well. - -Once the frozen hook is selected, it clears the launcher's command-scoped Git -configuration before verification. This keeps the forced `core.hooksPath` from -overriding nested fixture repositories; the outer push still executes its pinned -protected hook. Ordinary pushes retain their own command-scoped Git settings. - -When maintaining this repository's gate or its helper runtime, regenerate the -reviewed trust map with `node scripts/generate-managed-push-manifest.mjs` and run -the same command with `--check`. A stale map disables recognition; it does not -authorize skipping the legacy checks. Native client approval policies still apply. - -`[interlinked:decision-metrics]` is opt-in PostToolUse semantic advice. It can report -an adverse judgment, uncertainty, failure or missing evidence, but it never sets a -pre-execution block or authorizes an action. Both flags in -`.interlinked/decision-metrics.json` default off. The short inference deadline can -be followed by up to five seconds of local-model unload verification. Load -**interlinked-quality-gates** for configuration, replay and calibration; do not -weaken deterministic policy to satisfy a model's judgment. - -## Predict changes to guards - -The prediction phase includes a local JS/TS `if`-ownership oracle, independent of -Supermodel and `graph_prediction.enabled`. Its default mode is `shadow`; -`harness.guard_prediction.mode` in shared `.interlinked/config.json` accepts -`enforced`, `shadow` (record/reveal without refusing), or `off`. - -In the default shadow mode, review concise scope-change advice and relevant tests; -no declaration receipt is required. Repeated unchanged advice is deduplicated. -Only with explicit `enforced` policy, before intentionally changing which `if` -guards an existing `return` or `throw`, declare the expected ownership change. -The raw before/after AST comparison runs -before content checks; do not brace or format away an unexpected change. -Unpredicted changes block as protocol mismatches, not proven bugs. Correct the -proposal, or reconcile the exact revealed change with a rationale and behavioral -validation. A matching prediction does not prove correctness. - -Receipts are JSON at `.interlinked/predictions/guards//.json`. -Fields: `version: 1`, `session`, `id`, `file` (canonical repository-relative path), -`beforeSha256`, `afterSha256`, `nonce` (nonempty declaration identifier), and -`changes`: an array of `{owner, statement, before, after}`. Statement and condition -strings use parser token spellings joined by spaces. Each guard is -`{condition, branch: "then" | "else"}`; arrays list outer to inner guards. The ID is -SHA-256 of `JSON.stringify([1, file, beforeSha256, afterSha256])`, with UTF-8 hashes -of the exact source bytes. Use the native session identity printed in a reveal. -The reveal includes the measured fields and receipt path. After a reveal, include -`reconcile: id` and a nonempty `rationale`; a late prediction alone cannot pass. -Identical retries retain their declaration; changed bytes, file or session require -a matching receipt. Never use a wildcard acknowledgment. - -The append-only `predictions/guard-events.jsonl` retains `reveal`, `predicted`, and -`reconciled` evidence; acceptance never erases a surprise. Dry runs do not persist -events. Invalid or inaccessible protocol state cannot authorize a changed proposal. -This is local intent bookkeeping, not an adversarial security boundary. - -The initial oracle handles unique existing statements in identifiable function -scopes, plus unchanged complete function bodies. Changed ambiguous/anonymous -scopes and changed statement text produce partial/NOT CHECKED evidence. It does not -establish loop/switch/exception dominance, semantic predicate equivalence, deleted -statements, cross-file moves, or arbitrary shell effects. Native cold fallback runs -the same oracle; a standalone generated hook without the daemon reports NOT CHECKED -because it has no AST runtime. Restore the daemon or use `interlinked-hook` for -that check. Single-line guards remain valid code; brace style is a separate policy. - -Claude's demonstrated native `PostToolBatch` boundary coalesces TypeScript checks for -declared single-file edits. The final tree is checked before the next model request; -security guards remain per edit; metric caps advise unless `harness.edit_metrics.mode` -is explicitly `enforced`. Final compiler findings are -repair context, with unresolved work enforced at Stop/commit. See **interlinked-verify** -for fallback and recovery behavior. Merely using multiple Edit calls is not evidence -of a retry: correlate their emission time and assistant message with hook feedback. - -Repeated pre-edit content advice, test-evidence limitations, and unchanged coverage -gaps are deduplicated for model delivery. Full observations remain in local evidence. -Deep-audit style/design findings are retained in raw check evidence and available -through `verify --all-checks`; ordinary hook feedback announces this once instead -of sending every finding. Errors and blocking decisions remain visible. A persistent -warning never becomes a proven error merely because it repeats. -Changing coverage counts alone do not repeat the same instruction; a recovered gap -that recurs or a different unavailable-check reason is announced again. - -Claude and Codex Stop/SubagentStop advisories remain operator diagnostics on stderr. -Only explicit blocking repair decisions request another model turn. Source guidance is -sent during editing. File-size advice and per-function gates share native edit/patch content -projection; unreadable or invalid updates stay unmeasured. Shell effects remain -post-execution evidence unless a supported pre-write path is used. - -PostToolUse classifies recognized untracked Python environments, installed Node dependency -trees and named harness outputs before authored-source checks. Explicit edits, tracked files, -protected policy and unsafe/symlink paths do not receive this exemption. Security scope stays -separate; excluded files are not passes and runtime-input fingerprints are not narrowed. -The same source role separates recovery batches. Repeated unavailable-check diagnostics are -deduplicated for delivery; raw findings and unresolved evidence remain. Retry when prerequisites -change, not merely because the same diagnostic repeats. Missing evidence cannot yield “all clean.” - -For edits outside the guarded repository, both command-based and named external checks -(affected tests and dependency audit) skip this repository's runner. Inline content checks -remain available. Security findings on excluded dependency files retain normal severity and -enforcement; source-quality exclusion is not a security exemption. - -The built-in generic `rm` prior-inspection rule is advisory. A recent literal `Read` event -does not prove inspection of the deletion targets, and clients may expose different read tools. -Inspect the intended targets using the available tools; this heuristic does not require a -particular invocation. Deterministic destructive-command, reservation and protected-file -decisions still apply. Do not infer safe deletion merely from a recent unrelated read. - -The legacy `same_command_thrice_no_observe` advisory excludes simple read commands -such as `tail`, `rg`, and `git status`: polling their output is observation. Compound -commands, shell expansion and output redirection remain eligible. The advisory reports -matching command observations in session history; hook events do not prove distinct -executions or whether the agent read the output. This exception changes no execution gates. - -Guard audit records retain references for repeated warning text. Use `interlinked data search ---source warning-occurrences` to inspect full first/changed messages, hashes and occurrence -counts; `data show ID` opens their raw evidence. This bounds repetition in the activity mirror -without changing the guard decision or the warning returned by the evaluator. A later -`not-reported` observation does not prove that the underlying issue was fixed. - Interlinked runs a **local daemon** that evaluates each pre-execution event the installed runner exposes to its hook surface (PreToolUse). It is **default-permit with targeted forbid**: it allows everything except known-dangerous shapes, which it refuses with an @@ -199,79 +26,6 @@ Host file policies require explicit bridge mapping and matching file snapshots. bash-redirect-bypass rule fired. - You need to legitimately suppress a check false-positive, or disable a wrong guard rule. -## Mental model -- Each installed hook event ships its payload to the daemon over a Unix socket. The daemon runs an - ordered set of phases; **the first phase that returns a terminal decision wins**. -- Framed daemon RPC validates each method's request shape, including nested hook metadata - and administrative arguments, before dispatch. The client accepts only matching-id responses - with the expected method result shape. Malformed frames do not become successful decisions; - the existing timeout and fallback behavior still applies. -- Local quality-check overrides validate each supplied field before merging it. Malformed - fields are ignored while valid fields and sibling checks survive; new checks require the - complete mandatory configuration. Team overrides affect existing checks only. Default - configuration copies preserve non-JSON values such as an unlimited (`Infinity`) step limit. -- Content-scanner allowlists skip malformed entries. Known entry kinds require their declared - string fields; an unrecognized scanner runtime cannot select a backend. These checks apply - to these boundaries and do not imply that every legacy configuration section has a schema. -- Decisions: `block` (tool refused, you see the reason), `ask` (human confirmation — Claude and - supported Cursor gates can ask natively; interactive Pi calls `ctx.ui.confirm`; headless Pi, - OpenCode's stable tool gate, Codex `PreToolUse`, Copilot, and Gemini deny instead; - Claude/Codex `PermissionRequest` allow/ask abstain so the provider retains authority), - or `allow` (may still carry non-blocking `warnings`, or an `updated_input` rewrite). -- Built-in rules are regex patterns on the command/tool-input. Use `interlinked harness checks` - for the authoritative current inventory. Patterns are **ORed over positive entries; - `negate:true` patterns are exceptions.** `executed_only` masks - quoted/heredoc/comment text, so *mentioning* `rm -rf /` in an `echo` is allowed while the - bare command blocks. A quote around ONE shell word is an operand, not a mention: it stays - visible, so `truncate -s 0 "src/app.ts"` blocks like its unquoted twin, while a quoted body - with whitespace or a metacharacter (`git commit -m 'rm -rf /'`) stays masked. A quoted - argument of `eval` (or of `bash -c`, `python -c`, `node -e`) is code and is scanned. Compound - commands (`&&`, `||`, `;`, `|`, newline) are decomposed and each part checked. -- If a stopping rule matches only data, you get `[interlinked:guard] rule matched inside a - string literal (…); not blocked` instead of a block. Data here is a `harness test` argument, a - grep/rg pattern, an echo/printf argument, or a string in a `node -e`/`python3 -c` program with - no `child_process`/`subprocess`/`system`/`exec`. If the text can reach `sh`, `bash`, `eval`, - `xargs`, or a script that the same command runs, the block stands. -- Python `open(...)` checks inspect executable calls and recognize write and append modes; - read-only calls and quoted examples do not establish a file write. Keep malformed tool - input tests at the raw hook-input boundary rather than passing invalid normalized events. -- The log-output guard measures ordinary single-file `head`/`tail` windows of up to 200 - lines before rejecting a file over 100 KiB. Small windows pass on large logs; a selected - line over the byte budget still blocks. Signed counts and unfamiliar option combinations - retain the file-size gate. Daemon and generated-hook paths use the same bounded reader. - -> **Two unrelated things are called "guard".** This skill is the **PreToolUse guard** (the -> daemon, operated via `interlinked harness …`). `interlinked guard` is a separate **git -> pre-commit/pre-push hook** that checks staged files against file reservations — see -> **interlinked-coordination**. - -## What gets blocked (with concrete examples) - -| Category | Blocks (examples) | Allows (examples) | -|---|---|---| -| **Destructive fs** | `rm -rf /`, `rm -rf *`, `rm node_modules`, `sudo rm …`, `dd`, `mkfs`, `shred`, `chmod 777` | `rm -rf /tmp/x`, `rm -rf dist/`, `rm -rf .wrangler/cache` | -| **Process killing** | `pkill node`, `killall wrangler`, `kill -9 1234`, `kill $(pgrep …)`, `… \| xargs kill` | `pkill -f 'wrangler dev'`, `grep -rn "kill -9" src/` | -| **Git** | `git push --force`/`-f`, `git reset --hard`, `git clean -fd`, `git checkout -- .`, `git branch -D`, `git stash drop`/`clear`, agent-created worktrees (`git worktree add`; Claude `WorktreeCreate`) | `git push --force-with-lease`; `git worktree list/remove/prune` | -| **DB / cloud / IaC / containers** | `DROP DATABASE`/`TRUNCATE`/`DELETE`-without-WHERE, `docker … prune`/`rm -f`, `kubectl delete`, `terraform destroy`, `pulumi destroy` | — | -| **Info-flow / persistence** | env exfil (`env \| curl …`, `printenv \| nc …`), `.npmrc`/`.yarnrc` writes, `nohup curl … &`, `crontab -e`, `systemctl enable`, writes to `/etc/cron.d/`, `*.service` | — | -| **Protected files** | Read/Write of `*.pem`/`*.key`; Write of `*.env*` **only if secrets detected**; **Delete** of CI configs, `migrations/**`, `.gitignore`, lockfiles, `Dockerfile` | `.env.example` / `.sample` | -| **Sensitive-file read** | `Read` of `.env`, `credentials.json`, `service-account*.json`, `*.pem`/`*.key` | `.env.example` | -| **Repo confinement** | any Write/Edit whose real (symlink-resolved) target is outside the repo root | paths under the allowlist / session scratchpad | -| **Package installs** | any un-allowlisted `npm/pip/cargo/go/…` install; URL/git/tarball specs — see **interlinked-supply-chain** | allowlisted + exact-pinned | -| **Bash-routed write bypass** | a `>` / `tee` redirect, `sed -i` / `perl -pi` / `gawk -i inplace` / `ex` / `ed` in-place edit, `patch` / working-tree `git apply`, or a wrapped form (`xargs`, `find -exec`, `timeout`) writing a tracked source file (dodges the content gate) | Write/Edit, `interlinked write`, or index-only `git apply --cached ` | -| **Applier-script execution** (`builtin-patch-applier`) | running an interpreter on a pre-existing throwaway script that writes into repo source | route the edit through Write/Edit; committed codegen belongs in `scripts/` | -| **Bash-edit obligation** (`bash-edit-obligation`) | a bash-channel edit left an INTRODUCED `pre_block`-class finding on disk; the owning session's write-class calls to OTHER files are refused until it is fixed (edits to the flagged file and reads stay allowed; the gate re-checks and self-releases) | fix the flagged file first; unknown-writer findings do not acquire a guessed session owner | -| **Hand-rolled patch applier** | a throwaway script in the scratchpad or `scratch/` that calls `writeFileSync`/`appendFileSync`/`write_text` on a path outside its sandbox (`"src/…"`, `process.cwd()`, `../`) — a re-implementation of Edit with the gates removed | probes that only READ repo source; scripts writing beside themselves; committed codegen under `scripts/` | -| **Content pre_block** (introduced-only) | edit that *introduces* merge-conflict markers, `eval()`, and other zero-FP checks | pre-existing instances (warn, not block) | - -Inline interpreter writes (`builtin-interpreter-write`) require evidence about the -write's own destination: a literal source path or a simple variable binding to it. -Reading or hashing a source file while writing a JSON ledger does not establish a -source edit. The guard does not pair unrelated filenames with writes elsewhere in -the program. Reassigned, shadowed or otherwise unresolved destinations are not -grounds for this hard block; computed-write warnings remain advisory. Actual -source writes still belong in Write/Edit or the supported Interlinked write flow. - ## When you're BLOCKED: what to do Distinguish a hook rejection from a command that executed and then failed. OS `EPERM`, @@ -300,6 +54,10 @@ newline continues the same command and retains its interactive restrictions. A n the file already had** (multiset over whitespace-normalized text — moving a pre-existing finding doesn't count; a brand-new file counts everything). Fix the line(s) you *added*, then retry. + The `ubs_hardcoded_localhost` check distinguishes Git's `-c user.email=…` + identity argument from a remote endpoint passed to the same command. + When the daemon is unavailable, the inline strong-typing check also scans + production `.mts` and `.cts` files and recognizes their test counterparts. 4. **Legitimate suppression** — only when a flagged line is genuinely deliberate: - Inline, on the line **above** the finding: `// interlinked-ignore: — ` (reason separator ` — `, ` -- `, or `–`; comma-separate multiple check ids). @@ -372,74 +130,86 @@ An agent must not create a Git worktree to route around shared-workspace policy. current workspace. If isolation is genuinely required, ask a human operator to provision an approved worktree; listing and cleanup of existing worktrees remain allowed. -## Warnings: `[proven]` vs `[heuristic]` +## What gets blocked (with concrete examples) + +| Category | Blocks (examples) | Allows (examples) | +|---|---|---| +| **Destructive fs** | `rm -rf /`, `rm -rf *`, `rm node_modules`, `sudo rm …`, `dd`, `mkfs`, `shred`, `chmod 777` | `rm -rf /tmp/x`, `rm -rf dist/`, `rm -rf .wrangler/cache` | +| **Process killing** | `pkill node`, `killall wrangler`, `kill -9 1234`, `kill $(pgrep …)`, `… \| xargs kill` | `pkill -f 'wrangler dev'`, `grep -rn "kill -9" src/` | +| **Git** | `git push --force`/`-f`, `git reset --hard`, `git clean -fd`, `git checkout -- .`, `git branch -D`, `git stash drop`/`clear`, agent-created worktrees (`git worktree add`; Claude `WorktreeCreate`) | `git push --force-with-lease`; `git worktree list/remove/prune` | +| **DB / cloud / IaC / containers** | `DROP DATABASE`/`TRUNCATE`/`DELETE`-without-WHERE, `docker … prune`/`rm -f`, `kubectl delete`, `terraform destroy`, `pulumi destroy` | — | +| **Info-flow / persistence** | env exfil (`env \| curl …`, `printenv \| nc …`), `.npmrc`/`.yarnrc` writes, `nohup curl … &`, `crontab -e`, `systemctl enable`, writes to `/etc/cron.d/`, `*.service` | — | +| **Protected files** | Read/Write of `*.pem`/`*.key`; Write of `*.env*` **only if secrets detected**; **Delete** of CI configs, `migrations/**`, `.gitignore`, lockfiles, `Dockerfile` | `.env.example` / `.sample` | +| **Sensitive-file read** | `Read` of `.env`, `credentials.json`, `service-account*.json`, `*.pem`/`*.key` | `.env.example` | +| **Repo confinement** | any Write/Edit whose real (symlink-resolved) target is outside the repo root | paths under the allowlist / session scratchpad | +| **Package installs** | any un-allowlisted `npm/pip/cargo/go/…` install; URL/git/tarball specs — see **interlinked-supply-chain** | allowlisted + exact-pinned | +| **Bash-routed write bypass** | a `>` / `tee` redirect, `sed -i` / `perl -pi` / `gawk -i inplace` / `ex` / `ed` in-place edit, `patch` / working-tree `git apply`, or a wrapped form (`xargs`, `find -exec`, `timeout`) writing a tracked source file (dodges the content gate) | Write/Edit, `interlinked write`, or index-only `git apply --cached ` | +| **Applier-script execution** (`builtin-patch-applier`) | running an interpreter on a pre-existing throwaway script that writes into repo source | route the edit through Write/Edit; committed codegen belongs in `scripts/` | +| **Bash-edit obligation** (`bash-edit-obligation`) | a bash-channel edit left an INTRODUCED `pre_block`-class finding on disk; the owning session's write-class calls to OTHER files are refused until it is fixed (edits to the flagged file and reads stay allowed; the gate re-checks and self-releases) | fix the flagged file first; unknown-writer findings do not acquire a guessed session owner | +| **Hand-rolled patch applier** | a throwaway script in the scratchpad or `scratch/` that calls `writeFileSync`/`appendFileSync`/`write_text` on a path outside its sandbox (`"src/…"`, `process.cwd()`, `../`) — a re-implementation of Edit with the gates removed | probes that only READ repo source; scripts writing beside themselves; committed codegen under `scripts/` | +| **Content pre_block** (introduced-only) | edit that *introduces* merge-conflict markers, `eval()`, and other zero-FP checks | pre-existing instances (warn, not block) | + +Inline interpreter writes (`builtin-interpreter-write`) require evidence about the +write's own destination: a literal source path or a simple variable binding to it. +Reading or hashing a source file while writing a JSON ledger does not establish a +source edit. The guard does not pair unrelated filenames with writes elsewhere in +the program. Reassigned, shadowed or otherwise unresolved destinations are not +grounds for this hard block; computed-write warnings remain advisory. Actual +source writes still belong in Write/Edit or the supported Interlinked write flow. + +## Mental model +- Each installed hook event ships its payload to the daemon over a Unix socket. The daemon runs an + ordered set of phases; **the first phase that returns a terminal decision wins**. +- Framed daemon RPC validates each method's request shape, including nested hook metadata + and administrative arguments, before dispatch. The client accepts only matching-id responses + with the expected method result shape. Malformed frames do not become successful decisions; + the existing timeout and fallback behavior still applies. +- Raw hook events also validate consumed field shapes before dispatch. The generated + hook's documented null optional fields normalize to absence; malformed identities, + controls and collections still fail closed. Future provider names and extra fields + remain supported. Replay records retain their stricter captured-record contract. +- Local quality-check overrides validate each supplied field before merging it. Malformed + fields are ignored while valid fields and sibling checks survive; new checks require the + complete mandatory configuration. Team overrides affect existing checks only. Default + configuration copies preserve non-JSON values such as an unlimited (`Infinity`) step limit. +- Content-scanner allowlists skip malformed entries. Known entry kinds require their declared + string fields; an unrecognized scanner runtime cannot select a backend. These checks apply + to these boundaries and do not imply that every legacy configuration section has a schema. +- Decisions: `block` (tool refused, you see the reason), `ask` (human confirmation — Claude and + supported Cursor gates can ask natively; interactive Pi calls `ctx.ui.confirm`; headless Pi, + OpenCode's stable tool gate, Codex `PreToolUse`, Copilot, and Gemini deny instead; + Claude/Codex `PermissionRequest` allow/ask abstain so the provider retains authority), + or `allow` (may still carry non-blocking `warnings`, or an `updated_input` rewrite). +- Gemini CLI's native `run_shell_command` receives the same Bash-family guard rules + as other shell runners. Rules can also target its native tool name directly. +- Built-in rules are regex patterns on the command/tool-input. Use `interlinked harness checks` + for the authoritative current inventory. Patterns are **ORed over positive entries; + `negate:true` patterns are exceptions.** `executed_only` masks + quoted/heredoc/comment text, so *mentioning* `rm -rf /` in an `echo` is allowed while the + bare command blocks. A quote around ONE shell word is an operand, not a mention: it stays + visible, so `truncate -s 0 "src/app.ts"` blocks like its unquoted twin, while a quoted body + with whitespace or a metacharacter (`git commit -m 'rm -rf /'`) stays masked. A quoted + argument of `eval` (or of `bash -c`, `python -c`, `node -e`) is code and is scanned. Compound + commands (`&&`, `||`, `;`, `|`, newline) are decomposed and each part checked. +- If a stopping rule matches only data, you get `[interlinked:guard] rule matched inside a + string literal (…); not blocked` instead of a block. Data here is a `harness test` argument, a + grep/rg pattern, an echo/printf argument, or a string in a `node -e`/`python3 -c` program with + no `child_process`/`subprocess`/`system`/`exec`. If the text can reach `sh`, `bash`, `eval`, + `xargs`, or a script that the same command runs, the block stands. +- Python `open(...)` checks inspect executable calls and recognize write and append modes; + read-only calls and quoted examples do not establish a file write. Keep malformed tool + input tests at the raw hook-input boundary rather than passing invalid normalized events. +- The log-output guard measures ordinary single-file `head`/`tail` windows of up to 200 + lines before rejecting a file over 100 KiB. Small windows pass on large logs; a selected + line over the byte budget still blocks. Signed counts and unfamiliar option combinations + retain the file-size gate. Daemon and generated-hook paths use the same bounded reader. + +> **Two unrelated things are called "guard".** This skill is the **PreToolUse guard** (the +> daemon, operated via `interlinked harness …`). `interlinked guard` is a separate **git +> pre-commit/pre-push hook** that checks staged files against file reservations — see +> **interlinked-coordination**. -### Filesystem observations and native control limits - -The daemon watches protected policy files and literal in-workspace reservation -paths, then reconciles content identities periodically and at delivery boundaries. -Writes by a shell, editor or agent can create durable pending verification entries. -Writer identity is `unknown`; a reservation is not proof that its holder performed -the write. Glob reservations, symbolic links, inaccessible or oversized files -remain explicitly unmeasured. A stopped or unavailable observer cannot certify coverage. - -`harness coverage status --progress --json` reads cached observation time, generation -and recovery counts without reconciling files or returning receipt history. Use it for -progress, not to certify current bytes. Plain `harness coverage status --json` still -reconciles and returns full evidence. Neither status command starts recovery. -Starting verification returns a compact job acknowledgement. The waiting CLI refreshes -current pending versions and the matching job's detailed results before declaring success, -without copying historical receipts into each recovery response. An unmeasured check is -not a successful verification, even if no findings or pending versions remain. -While waiting, transient control outages are retried read-only for up to two -minutes per outage (plus an in-flight RPC deadline), rather than failing after -three timeouts. Terminal stderr reports the outage; JSON stdout remains one final -document. A responsive report resets that outage window. Host permission denial -and invalid control responses stop immediately; verification mutations are never -automatically resubmitted after an ambiguous response. -Receipts with nonempty `unavailable` retain completed checks as partial evidence while -keeping the version pending. Retrying is not made unnecessary merely by having a receipt; -safe cross-run reuse needs the relevant check input identities. - -Background coverage recovery runs ShellCheck and Taplo in file mode, sequentially -under one project lease, with at most 32 inputs and a 30-second shared deadline -per tool. Interactive multi-file requests still defer these file-only runners. -Missing tools, truncated output, process failures and unparsed nonzero exits -remain unavailable evidence; they cannot clear a pending version. Recovery may -finish with pending versions when native test scopes or tools are missing, or -when an observed file was deleted. Inspect the retained reasons before retrying; -a completed job is not a claim that every version was checked. -If a nested project's imported lint policy belongs to an ancestor project, -background recovery waits for that policy project's lease within the existing -tool deadline. Foreground checks still report contention immediately. Time spent -waiting reduces the analyzer's remaining budget; it does not extend the job. - -`harness coverage accept-policy ` records an explicitly reviewed current -policy identity. It neither runs checks nor restores old policy bytes. A later -Claude ConfigChange can refuse application of a differing identity, after the disk -write has happened. This is not an immutable trust anchor or a universal policy -reload interlock. Do not describe watcher readiness as baseline-integrity enforcement. - -Native translations are recorded in `.interlinked/hook-translations.jsonl` by the -compiled entry point. A post-tool refusal may become context, continuation or batch -cancellation; observational events cannot enforce a denial. Copilot/Gemini approval -requests conservatively deny where native approval is not certified. Experimental -Antigravity uses `force_ask`; Antigravity and Windsurf refuse a required input rewrite -that their hook cannot apply. Read translation status separately from native enforcement. -Harness-disable trajectory detection reads executable command positions, so a mutation-test -filename containing `kill` is not a process-kill event. Failed commands do not establish a -successful disable. A later event served by the daemon retires process/socket-outage suspicion; -it does not retire a recorded weakening of `disabled_rules`. Shadow verdicts remain advisory -and do not include a misleading `BLOCKED:` prefix. - -The optional-chain check uses syntax grouping: passing `value?.field` to a function and then -accessing that function's result is different from `(value?.field).name`. Without optional -TypeScript syntax support it cannot establish this finding; silence is not a clean verdict. -SQL migration checks likewise cannot prove a column absent from an interpolated column list. -For `it.each(table)(name, callback)`, assertion checks inspect the callback, not functions -inside the data table. An unparsed callback cannot prove assertion absence; table assertions -also cannot satisfy an assertion-free callback. A call to a same-file helper that asserts -(directly or through another such helper), or to an `assertX(...)` function, counts as an assertion. +## Warnings: `[proven]` vs `[heuristic]` Every warning is tagged. `[proven]` = a real compiler/linter/scanner/parser/test-runner produced it — authoritative, fix it. `[heuristic]` = regex/AST-shape match that could be a @@ -477,7 +247,7 @@ calls multiplied that into unusable noise. Outage visibility is phase- and runti | Daemon unavailable, packaged PreToolUse runtime | an explicit `evaluator skipped` diagnostic; code edits also report function-token enforcement as not measured | | Daemon unavailable, generated PostToolUse runtime | may remain model-silent while recording local `no_harness` status | | `typescript` unresolvable (`--omit=optional` install) | a `[interlinked:self_import] NOT MEASURED` warning on every JS/TS edit — that pre_block check ran no scan and never guesses; the cyclomatic gate degrades to the regex walker; the daemon startup warning names both | -| `self_import` cannot place the file in ONE project | the same `NOT MEASURED` warning on that edit only, naming the cause: a tsconfig on the walk (nearest config, its `extends`, its `references`, its sibling `tsconfig*.json` files) could not be parsed; two projects both claim the file; the reference walk hit its 32-project bound with projects unvisited; no config in reach claims the file by a `files`/`include` pattern (a `.js`/`.jsx`/`.mjs`/`.cjs` importer is matched by pattern even when the project never enables `allowJs` — a JS self-import is a runtime fact); or the importer's directory is not on disk yet. The check resolves with the project's own compiler options and caches nothing, so fixing the config applies on the next edit. In a batch (`write --batch`, `multi-edit`, `verify-changeset`) it sees the whole proposed batch, and the baseline is judged against the disk | +| `self_import` cannot place the file in ONE project | the same `NOT MEASURED` warning on that edit only (for a probe under the repo-root `scratch/` it is a one-line notice with no remedy, because no tsconfig includes `scratch/` by design), naming the cause: a tsconfig on the walk (nearest config, its `extends`, its `references`, its sibling `tsconfig*.json` files) could not be parsed; two projects both claim the file; the reference walk hit its 32-project bound with projects unvisited; no config in reach claims the file by a `files`/`include` pattern (a `.js`/`.jsx`/`.mjs`/`.cjs` importer is matched by pattern even when the project never enables `allowJs` — a JS self-import is a runtime fact); or the importer's directory is not on disk yet. The check resolves with the project's own compiler options and caches nothing, so fixing the config applies on the next edit. In a batch (`write --batch`, `multi-edit`, `verify-changeset`) it sees the whole proposed batch, and the baseline is judged against the disk | | a batch rewrites a file of the project's configuration graph — the selected tsconfig, any file its `extends` chain reaches (whatever it is called, `base.json` included), or any `tsconfig*.json` / `jsconfig.json` / `package.json` | each TypeScript entry of that batch carries a `type checker cannot see the proposed configuration` row (error for transactional callers) — the checker reads the disk's config; land the configuration change first, then the sources | | a batch includes a member whose bytes equal the disk beside members that differ | the unchanged member is still type-checked, against the proposed siblings (a changed exporter can break an untouched consumer); `multi-edit` validates every manifest member and writes only the changed ones. Only a batch whose members are ALL unchanged skips the check. A config member whose bytes equal the disk is not a configuration rewrite | | the type checker cannot place the file in ONE project | `type checker unavailable (project_orphan: …)` or `(project_ambiguous: …)` on that edit — a warning on the hook path, an error for transactional callers. The compiler judges each file under the SAME project `self_import` selects (nearest config, `references`, sibling `tsconfig*.json`, membership by pattern; one program per governing config) and never under the project root's config by guess. Its disk baseline is recomputed on every check, so a dependency repaired or broken on disk is reflected the next time the file is judged. A warm compiler service is rebuilt when the CONTENT of any file of its configuration graph (the tsconfig or an `extends` target) changes on disk, re-reads the project's root files on every reuse (a declaration file added or removed on disk joins or leaves the program), sees a dependency rewritten on disk by its compiler TEXT (every UTF-16 code unit is preserved, including lone surrogates; a touch that changes no text does not count; each check reads a file once, so what it compiles is what it fingerprinted), forgets a proposal the moment its check ends (a refused proposal never colours a later check), and a configured project with no source on disk yet still measures the first source written into it | @@ -519,55 +289,57 @@ module/suite arrays, shared aliases, and prototype methods still need restoratio Source headers and `docs/design/test-discrimination-checks.md` describe limits and calibration. A corpus hit count is not precision or proof of a surviving mutant. -## Bash effects and sandbox evidence - -Do not trust a tool name as proof that no file changed. For Bash and other potentially mutating -tools, the daemon snapshots Git-visible files plus standalone ignored local files (for example -`.env`, while collapsing bulk ignored directory trees) before the call and attaches the observed -created/modified/deleted ChangeSet after it. PostToolUse file checks prefer those observed paths over -command text or runner-declared paths. - -**A read-only tool contributes no observed paths.** The ChangeSet is a diff of the window the call -occupied, not a record of what the call did, so on `Read` / `Glob` / `Grep` / `WebFetch` / -`WebSearch` / `TodoRead` / `NotebookRead` / `ListFiles` every path in it was written by somebody -else — another agent on the same tree, a background test run, a watcher. Those calls are charged -nothing and run no file checks. `Bash` is NOT in that set and keeps its ChangeSet (it is the -bash-edit obligation channel), and neither is an unknown tool, so a new writer cannot open the -bypass by using an unfamiliar name. The list is one definition, at -`src/lib/hook-read-only-tools.ts`. Claude Code's PostToolUse hook is also registered only for -`Write|Edit|MultiEdit|NotebookEdit|Bash`; Codex keeps the all-tools matcher because `apply_patch` -arrives through it. Reservation handling parses every `apply_patch` section destination and move -source once; PreToolUse grants and PostToolUse idle-release scheduling consume the same ordered, -de-duplicated path list. It preflights that full list before granting, so a later blocking path -cannot strand an earlier lease when the tool never runs and therefore has no PostToolUse. - -A Stop-time `[interlinked:effect-residue]` warning means a -PostToolUse was missing/unreconciled; the observed files were added to the touched-file rescan. -Effects reconciled by another actor are excluded (the warning reports the excluded count) — this -includes another session and a sibling subagent that shares the same Codex session id, so one -parallel actor is not charged for another's work. Actor identity is evidence-bounded: Interlinked -uses the stable subagent id when Codex supplies one and otherwise stays at root-session scope. -Persisted pre-upgrade rows with no actor field remain conservatively session-scoped; new rows -distinguish a known root from a known child across daemon restarts. -The noisy `.interlinked/` runtime tree stays collapsed, but its exact local policy/control files are -observed and cannot be silenced by `skip_paths`. - -Interpret `[interlinked:sandbox]` as evidence visible to the hook: - -- `attested` — the runner marked this call sandboxed; -- `configured` — restrictive client config was found, but a CLI/profile override may differ; -- `disabled` — the call/config explicitly selected unsandboxed/escalated execution; or -- `unknown` — no trustworthy evidence reached the hook. - -A workspace-write sandbox limits blast radius but still writes the real project, so it is -defense-in-depth, not rollback. Do not rerun or rewrite a command to evade this warning. For changes -that require rejection before disk, use Edit/Write or gated `interlinked write`/`multi-edit`. -The transactional commands share the content gate and commit lock. They capture target state -before checking, abort on target drift, preserve modes, and refuse rollback over newer edits. -Unavailable Biome or TypeScript checks abort a transaction. Re-read and re-gate a conflicted -proposal; consult **interlinked-verify** for the command contracts and transaction limits. -The observer is bounded ordinary-process evidence: concurrent writers can cause conservative extra -attribution, and an incomplete snapshot is never proof of absence. +## Instruction packets: `[interlinked:packet]` (opt-in; warn, or ask at cosign) + +An instruction-file rule that no regex can decide alone (CLAUDE.md, AGENTS.md, +memory) can be compiled into a *packet*: a deterministic trigger, a regex +decider for what IS decidable, and one Jev yes/no question for the residue +(`docs/design/instruction-jev-evaluator.md`). Off unless `packets.enabled` and +`jev.enabled` are set in `guard-rules.local.json` with an explicit +`evidence_consent`. Nothing a packet says ever blocks; only a `cosign` packet can turn an allow into an ask. + +A delivered line looks like: + +``` +[interlinked:packet] [heuristic] prefer-rg p=0.91 ≥ τ 0.85 — "Prefer `rg` over `grep`/`find` …" (CLAUDE.md) + ↳ evidence: grep -rn "foo" src + ↳ adjudicate: interlinked packets adjudicate prefer-rg:3f9a1c2e:248:1a2b3c4d:5e6f7a8b true|false|unsure +``` + +It appears only for a packet at `warn` or `cosign` whose judgment crossed its +measured tau on THIS runner and model, or whose deterministic `violated` +pattern matched. A trajectory finding (a rule over a whole turn, judged at Stop; +the line names the call by seq) rides the NEXT tool call's warnings, because a +Stop warning reaches no agent. Read it as a `[heuristic]` finding: follow the quoted rule if +it applies; if the warning is wrong, say so with the printed adjudicate command +(`true` = the rule was violated, `false` = false positive). Adjudications feed +`interlinked packets calibrate score` as a labeler and demote a packet whose +precision falls. A packet promoted to `cosign` (explicit, after enough +adjudications) can turn an `allow` into an `ask` before a call runs, but only while one of its +`cosignals` names a rule the guard runs here (the rule whose allow it tightens; the ask names that +rule). `interlinked packets status` shows each cosign packet's pair, or `UNPAIRED`, with its asks +delivered and withheld. A cosign packet never turns anything into a block, and never loosens a block or an ask. Do not edit `.interlinked/instruction-packets.json` by hand: +it is a water-line; `packets compile`, `packets calibrate score --apply`, +`packets release` and `packets restore` are the only writers. + +A line of the form `[interlinked:packet ] not live here (); instruction released from , verbatim:` followed by +rule text means that rule's words were RELEASED from the instruction file (`interlinked packets release `, allowed only +for a packet at warn/cosign, never from a global `~/` file) and the packet is not enforcing it in this session (Jev off, no key, the file changed since +compile, demoted, another runner, daemon down, spend cap). Follow the quoted text exactly as if it were still in the file. It arrives at SessionStart on Claude Code, Codex and Factory Droid, and +on the first model-visible tool call of the session on Copilot, Gemini, Cursor, OpenCode and Pi (their SessionStart hook is not model-visible). +It arrives again on a later tool call when a packet stops being live mid-session (spend cap, Jev outage, a slow judgment), +and on every model-visible PostToolUse with the daemon down (and at every SessionStart) until the hook records that the model received it +(`.interlinked/packet-fallback-delivered.jsonl`; the hook writes a receipt only when the line reached a model-visible channel whole). +`interlinked packets budget [--runner ]` shows, per instruction file, what is held by Pass 1 rules, by live packets +(net releasable characters, or 0 with the reason the release would refuse), by releases (live, or `released_fallback` when not live +for that runner), and by shadow packets; `interlinked packets restore ` puts released text back byte-for-byte. +If release or restore reports an interrupted run, run `interlinked packets restore `: the words are always in at least one place. +If release, restore, `packets compile` or `packets calibrate score --apply` reports that another run holds `.interlinked/instruction-packets.json.lock`, or is taking over a stale lock, run it again when that run ends; a dead holder's lock is taken over. +If one reports that a killed run left a takeover guard (`…lock.takeover-`) and no packet command is running, delete that file and run again. +If release or restore reports that the instruction file is not valid UTF-8, fix the bytes first; neither command changes a file it cannot decode exactly. +If a release reports that a span holds another packet's pointer line, restore that packet first, then release. +A write that clears a release while the instruction file still holds only its pointer is refused (`release-removed`): run `interlinked packets restore ` instead. +Judgment ids carry an 8-hex token of the whole session id; labels saved under the older session-prefix form still join where unambiguous. ## Compiler acceleration @@ -685,6 +457,9 @@ never inferred read-only from their text. Restore the runtime before relying on Neither has dedicated native MCP, subagent, or worktree lifecycle events. Do not infer an absent event from silence; the shared `git worktree add` shell block still applies. - **PII content scanner** is separate and opt-in: `interlinked scanner on|off|toggle|status|review`. + Toggle commands fail and preserve malformed or non-object local guard rules for repair. + Review selects the newest pending item when `--key` is omitted. Explicit empty or + whitespace-only keys fail before writing a decision. - **Decision shadows** (opt-in `decision_shadow` in guard-rules.local.json) log a model's second opinion and never change a verdict. A `guard_block` row means a shell block was asked "is this destructive as written?": `would_release` (p < 0.1476) says the model saw @@ -708,54 +483,20 @@ interlinked index query "" # what the grep accelerator would interlinked harness restart # reload everything (clears trajectory) ``` +## References + +Read a reference file only when the task needs it. + +- [references/guard-prediction.md](references/guard-prediction.md): the guard-prediction oracle, its receipts and reveals, `PostToolBatch` check coalescing, Stop advisories, external-path checks and warning-occurrence records. +- [references/managed-push.md](references/managed-push.md): the managed push handoff for protected pushes, its typed fallbacks and the trace variables. +- [references/guard-notes.md](references/guard-notes.md): commit-time function-token diagnostics, `INTERLINKED_RUNTIME_POLICY=local-restricted`, remote-pipe detection and `[interlinked:decision-metrics]` advice. +- [references/filesystem-observations.md](references/filesystem-observations.md): watched policy files, `harness coverage status`, background coverage recovery, `accept-policy`, native translations and the optional-chain check. +- [references/bash-effects.md](references/bash-effects.md): Bash effect ChangeSets, `[interlinked:effect-residue]` and `[interlinked:sandbox]` evidence. +- [references/permission-proposals.md](references/permission-proposals.md): permission-learner proposals, dormant `active_when` predicates, the baseline-effect guard and NOT CHECKED detector failures. +- [references/typescript-history.md](references/typescript-history.md): the opt-in `session_tsc_history` Stop check. + ## Related skills - **interlinked-verify** — the check catalog behind the warnings, `interlinked verify`, and how to land edits through the gates. - **interlinked-quality-gates** — advisory file size and the coverage/complexity/function-token ratchets. - **interlinked-supply-chain** — the package-install gate in detail. - **interlinked-setup** — starting/restarting the daemon, `doctor`, config. - -## Permission proposals and unavailable checks - -The permission learner is suggestion-only. Crossing an observation threshold does not write Claude permissions or guard rules. Proposals retain the observed command and conservative pattern; observations do not prove approval or execution. Interpreter-wide and compound-command proposals are withheld. Cross-session `learned-rules.json` is observational proposal history, including its legacy `decision: allow` field; it is not effective authorization. Existing explicit permissions remain operator-owned. - -Unknown `active_when` session predicates leave a distilled rule dormant with a diagnostic. The registered predicate is `active_agent_count_at_least` with `count`; do not substitute invented predicates or the legacy top-level `session_predicate` shape. See **enforce** for supported typed conditions. - -Existing top-level `session_predicate` fields retain their historical unconditional matching and the operator's enabled setting, with a migration diagnostic. They are not evaluated conditions. Migrate them explicitly to supported `active_when` rather than silently disabling existing guards. - -The baseline-effect guard compares bounded pre-call snapshots with the files after a tool -call and restores the WHOLE pre-call file when a protected water-line loosened. Reapply any -legitimate tightening that shared the same file. Restore audits live in -`.interlinked/baseline-undo/restored/`; a failed restore leaves recovery evidence and a warning. -Mutation-manifest changes and first-time seeding of an absent complexity metric are record-only: -review and restore inappropriate changes yourself. Intentional resets require the operator's -`INTERLINKED_DISABLE_BASELINE_GUARD=1` in the daemon environment; putting it in tool text -does not authorize a reset. Dry runs neither restore nor record. - -Snapshots do not cover unbracketed background writes, oversized files, or an absent prior -water-line. A concurrent write inside another call's bracket may be attributed to that call. -Unresolvable Vitest denominator/config comparisons report NOT CHECKED, not a guessed restore. -This local guard is not an immutable security boundary. Explicit edit aliases, including -VS Code replacement arrays, are normalized per target file; shell wrappers retain their cwd -when checking commits and baseline writes. Read-only shell examples are not edits. - -A thrown sequence detector or failed Stop scan records NOT CHECKED evidence while healthy detectors continue. Stop rescans are confined to the selected repository, including resolved symlink targets. External memory/config writes retained in session history are reported out of scope; they cannot launch another project's scan or receive repository check receipts. Project-aware detectors receive absolute paths in that repository. Endpoint checks build a project graph only when a finding requires reachability annotation. An instrumentation failure is not a source violation or a clean scan. LTL remains shadow-only: its event-clock.v1 counts PreToolUse and PostToolUse separately, including a paired tool-use ID. Open finite-trace obligations remain unknown at Stop; predicate exceptions taint that property and cannot manufacture violations. No local control-file guard is an immutable security boundary. - -Each throwing trajectory rule produces unavailable shadow telemetry while peer rules and the LTL monitor continue. Adapter failures also retain unavailable telemetry without changing the enforcement decision. - -## Opt-in TypeScript history at Stop - -`verification_stop_checks.session_tsc_history` defaults to `false`. Setting it -to `true` appends advisory context only when the existing unverified-code Stop -warning already fires. It reads up to the final 8 MiB of this repository's -`.interlinked/check-results.jsonl`, using only the same session's executed -TypeScript outcomes strictly before Stop and within the preceding hour. -At least three valid runs and `(finding runs + 1) / (runs + 2) >= 0.5` are -required; the latest valid run must still report a finding. Counted outcomes -must carry a nonempty invocation ID; repeated IDs count only once. Missing, skipped, -deferred, timeout and process/resource failure evidence does not count as a -clean run. A later no-reported-findings result suppresses the addendum. - -This is a reported-finding history hint, not proof of full compile failure or -success, not a per-edit risk score, and never a hard block. It does not change -the TypeScript scheduler. Partial or unavailable log history can suppress the -hint. Continue to use actual verification evidence for the final outcome. diff --git a/skills/interlinked-harness/references/bash-effects.md b/skills/interlinked-harness/references/bash-effects.md new file mode 100644 index 000000000..8bb9af06b --- /dev/null +++ b/skills/interlinked-harness/references/bash-effects.md @@ -0,0 +1,65 @@ +# interlinked-harness: Bash effects and sandbox evidence + +Reference for [SKILL.md](../SKILL.md). Read it for `[interlinked:effect-residue]` or `[interlinked:sandbox]` output. + +## Bash effects and sandbox evidence + +Do not trust a tool name as proof that no file changed. For Bash and other potentially mutating +tools, the daemon snapshots Git-visible files plus standalone ignored local files (for example +`.env`, while collapsing bulk ignored directory trees) before the call and attaches the observed +created/modified/deleted ChangeSet after it. PostToolUse file checks prefer those observed paths over +command text or runner-declared paths. + +**A read-only tool contributes no observed paths.** The ChangeSet is a diff of the window the call +occupied, not a record of what the call did, so on `Read` / `Glob` / `Grep` / `WebFetch` / +`WebSearch` / `TodoRead` / `NotebookRead` / `ListFiles` every path in it was written by somebody +else — another agent on the same tree, a background test run, a watcher. Those calls are charged +nothing and run no file checks. `Bash` is NOT in that set and keeps its ChangeSet (it is the +bash-edit obligation channel), and neither is an unknown tool, so a new writer cannot open the +bypass by using an unfamiliar name. The list is one definition, at +`src/lib/hook-read-only-tools.ts`. Claude Code's PostToolUse hook is also registered only for +`Write|Edit|MultiEdit|NotebookEdit|Bash`; Codex keeps the all-tools matcher because `apply_patch` +arrives through it. Reservation handling parses every `apply_patch` section destination and move +source once; PreToolUse grants and PostToolUse idle-release scheduling consume the same ordered, +de-duplicated path list. It preflights that full list before granting, so a later blocking path +cannot strand an earlier lease when the tool never runs and therefore has no PostToolUse. + +A shell call whose command line is provably read-only owns none of the changes seen while it +ran. The test is a fail-closed allowlist (`rg`, `grep`, `cat`, `head`, `ls`, `wc`, a `sed -n` +line print, `git status|log|diff|show`, and similar) with no file redirect, substitution, or +background job; any other command keeps the window rule. Those changes are shadows +(`shadow_reason: read-only-command`): they are not recorded as the call's writes, and the call +runs no per-file checks on them. A shadow of any kind gets no per-file check from that call. + +A Stop-time `[interlinked:effect-residue]` warning means a +PostToolUse was missing/unreconciled; the observed files were added to the Stop rescan as +observed-only: no tool call of the session declared them, so the writer is unknown. The rescan +reports their findings on a separate `unknown writer` line (detail: `interlinked query stop-digest +--where kind=unknown-writer`), never under "file(s) you touched", and `subagent_diverged_edit` +ignores them. Do not edit a file that you did not write. A later declared write by the session +makes the path its own. +Effects reconciled by another actor are excluded (the warning reports the excluded count) — this +includes another session and a sibling subagent that shares the same Codex session id, so one +parallel actor is not charged for another's work. Actor identity is evidence-bounded: Interlinked +uses the stable subagent id when Codex supplies one and otherwise stays at root-session scope. +Persisted pre-upgrade rows with no actor field remain conservatively session-scoped; new rows +distinguish a known root from a known child across daemon restarts. +The noisy `.interlinked/` runtime tree stays collapsed, but its exact local policy/control files are +observed and cannot be silenced by `skip_paths`. + +Interpret `[interlinked:sandbox]` as evidence visible to the hook: + +- `attested` — the runner marked this call sandboxed; +- `configured` — restrictive client config was found, but a CLI/profile override may differ; +- `disabled` — the call/config explicitly selected unsandboxed/escalated execution; or +- `unknown` — no trustworthy evidence reached the hook. + +A workspace-write sandbox limits blast radius but still writes the real project, so it is +defense-in-depth, not rollback. Do not rerun or rewrite a command to evade this warning. For changes +that require rejection before disk, use Edit/Write or gated `interlinked write`/`multi-edit`. +The transactional commands share the content gate and commit lock. They capture target state +before checking, abort on target drift, preserve modes, and refuse rollback over newer edits. +Unavailable Biome or TypeScript checks abort a transaction. Re-read and re-gate a conflicted +proposal; consult **interlinked-verify** for the command contracts and transaction limits. +The observer is bounded ordinary-process evidence: concurrent writers can cause conservative extra +attribution, and an incomplete snapshot is never proof of absence. diff --git a/skills/interlinked-harness/references/filesystem-observations.md b/skills/interlinked-harness/references/filesystem-observations.md new file mode 100644 index 000000000..48f888468 --- /dev/null +++ b/skills/interlinked-harness/references/filesystem-observations.md @@ -0,0 +1,70 @@ +# interlinked-harness: filesystem observations and native control limits + +Reference for [SKILL.md](../SKILL.md). Read it for `[interlinked:hook-coverage]` status, recovery or policy acceptance. + +### Filesystem observations and native control limits + +The daemon watches protected policy files and literal in-workspace reservation +paths, then reconciles content identities periodically and at delivery boundaries. +Writes by a shell, editor or agent can create durable pending verification entries. +Writer identity is `unknown`; a reservation is not proof that its holder performed +the write. Glob reservations, symbolic links, inaccessible or oversized files +remain explicitly unmeasured. A stopped or unavailable observer cannot certify coverage. + +`harness coverage status --progress --json` reads cached observation time, generation +and recovery counts without reconciling files or returning receipt history. Use it for +progress, not to certify current bytes. Plain `harness coverage status --json` still +reconciles and returns full evidence. Neither status command starts recovery. +Starting verification returns a compact job acknowledgement. The waiting CLI refreshes +current pending versions and the matching job's detailed results before declaring success, +without copying historical receipts into each recovery response. An unmeasured check is +not a successful verification, even if no findings or pending versions remain. +While waiting, transient control outages are retried read-only for up to two +minutes per outage (plus an in-flight RPC deadline), rather than failing after +three timeouts. Terminal stderr reports the outage; JSON stdout remains one final +document. A responsive report resets that outage window. Host permission denial +and invalid control responses stop immediately; verification mutations are never +automatically resubmitted after an ambiguous response. +Receipts with nonempty `unavailable` retain completed checks as partial evidence while +keeping the version pending. Retrying is not made unnecessary merely by having a receipt; +safe cross-run reuse needs the relevant check input identities. + +Background coverage recovery runs ShellCheck and Taplo in file mode, sequentially +under one project lease, with at most 32 inputs and a 30-second shared deadline +per tool. Interactive multi-file requests still defer these file-only runners. +Missing tools, truncated output, process failures and unparsed nonzero exits +remain unavailable evidence; they cannot clear a pending version. Recovery may +finish with pending versions when native test scopes or tools are missing, or +when an observed file was deleted. Inspect the retained reasons before retrying; +a completed job is not a claim that every version was checked. +If a nested project's imported lint policy belongs to an ancestor project, +background recovery waits for that policy project's lease within the existing +tool deadline. Foreground checks still report contention immediately. Time spent +waiting reduces the analyzer's remaining budget; it does not extend the job. + +`harness coverage accept-policy ` records an explicitly reviewed current +policy identity. It neither runs checks nor restores old policy bytes. A later +Claude ConfigChange can refuse application of a differing identity, after the disk +write has happened. This is not an immutable trust anchor or a universal policy +reload interlock. Do not describe watcher readiness as baseline-integrity enforcement. + +Native translations are recorded in `.interlinked/hook-translations.jsonl` by the +compiled entry point. A post-tool refusal may become context, continuation or batch +cancellation; observational events cannot enforce a denial. Copilot/Gemini approval +requests conservatively deny where native approval is not certified. Experimental +Antigravity uses `force_ask`; Antigravity and Windsurf refuse a required input rewrite +that their hook cannot apply. Read translation status separately from native enforcement. +Harness-disable trajectory detection reads executable command positions, so a mutation-test +filename containing `kill` is not a process-kill event. Failed commands do not establish a +successful disable. A later event served by the daemon retires process/socket-outage suspicion; +it does not retire a recorded weakening of `disabled_rules`. Shadow verdicts remain advisory +and do not include a misleading `BLOCKED:` prefix. + +The optional-chain check uses syntax grouping: passing `value?.field` to a function and then +accessing that function's result is different from `(value?.field).name`. Without optional +TypeScript syntax support it cannot establish this finding; silence is not a clean verdict. +SQL migration checks likewise cannot prove a column absent from an interpolated column list. +For `it.each(table)(name, callback)`, assertion checks inspect the callback, not functions +inside the data table. An unparsed callback cannot prove assertion absence; table assertions +also cannot satisfy an assertion-free callback. A call to a same-file helper that asserts +(directly or through another such helper), or to an `assertX(...)` function, counts as an assertion. diff --git a/skills/interlinked-harness/references/guard-notes.md b/skills/interlinked-harness/references/guard-notes.md new file mode 100644 index 000000000..a46858292 --- /dev/null +++ b/skills/interlinked-harness/references/guard-notes.md @@ -0,0 +1,33 @@ +# interlinked-harness: guard notes + +Reference for [SKILL.md](../SKILL.md). Read it for commit-time function-token diagnostics, the restricted runtime policy, remote-pipe detection or decision-metrics advice. + +## Commit-time diagnostics, runtime policy and remote pipes + +Commit-time function-token diagnostics compare against `HEAD` and name their scope: +staged index, tracked working tree, selected constructed paths, or a conservative +worktree scan. They do not identify the writer or when the changes were made. +Only the first eight findings are displayed; the full set still determines the block. +For unresolved compound staging scope, stage first and commit in a separate tool call +to check the exact index. This changes the observed scope, not the cap or enforcement. + +`INTERLINKED_RUNTIME_POLICY=local-restricted` opts into a packaged local runtime +policy shared by the CLI, daemon and generated cold fallback. It denies network +calls and selected external commands, and refuses recognized agent reads of +`.interlinked/config.local.json`; internal configuration readers still work. +It is application policy, not a sandbox for arbitrary child code or computed paths. +Unavailable tools remain unmeasured; this mode does not certify skipped checks. + +Remote-pipe detection permits interpreter inline programs preceded by bare flags +(for example, `curl URL | python3 -I -c '...'`), where stdin is data. Shell sinks +retain their existing remote-execution block. + +## Decision-metrics advice + +`[interlinked:decision-metrics]` is opt-in PostToolUse semantic advice. It can report +an adverse judgment, uncertainty, failure or missing evidence, but it never sets a +pre-execution block or authorizes an action. Both flags in +`.interlinked/decision-metrics.json` default off. The short inference deadline can +be followed by up to five seconds of local-model unload verification. Load +**interlinked-quality-gates** for configuration, replay and calibration; do not +weaken deterministic policy to satisfy a model's judgment. diff --git a/skills/interlinked-harness/references/guard-prediction.md b/skills/interlinked-harness/references/guard-prediction.md new file mode 100644 index 000000000..ecccfa0a3 --- /dev/null +++ b/skills/interlinked-harness/references/guard-prediction.md @@ -0,0 +1,105 @@ +# interlinked-harness: guard prediction + +Reference for [SKILL.md](../SKILL.md). Read it for guard-prediction advice, receipts or reveals, or the related advisories. + +## Predict changes to guards + +The prediction phase includes a local JS/TS `if`-ownership oracle, independent of +Supermodel and `graph_prediction.enabled`. Its default mode is `shadow`; +`harness.guard_prediction.mode` in shared `.interlinked/config.json` accepts +`enforced`, `shadow` (record/reveal without refusing), or `off`. + +In the default shadow mode, review concise scope-change advice and relevant tests; +no declaration receipt is required. Repeated unchanged advice is deduplicated. +Only with explicit `enforced` policy, before intentionally changing which `if` +guards an existing `return` or `throw`, declare the expected ownership change. +The raw before/after AST comparison runs +before content checks; do not brace or format away an unexpected change. +Unpredicted changes block as protocol mismatches, not proven bugs. Correct the +proposal, or reconcile the exact revealed change with a rationale and behavioral +validation. A matching prediction does not prove correctness. + +Receipts are JSON at `.interlinked/predictions/guards//.json`. +Fields: `version: 1`, `session`, `id`, `file` (canonical repository-relative path), +`beforeSha256`, `afterSha256`, `nonce` (nonempty declaration identifier), and +`changes`: an array of `{owner, statement, before, after}`. Statement and condition +strings use parser token spellings joined by spaces. Each guard is +`{condition, branch: "then" | "else"}`; arrays list outer to inner guards. The ID is +SHA-256 of `JSON.stringify([1, file, beforeSha256, afterSha256])`, with UTF-8 hashes +of the exact source bytes. Use the native session identity printed in a reveal. +The reveal includes the measured fields and receipt path. After a reveal, include +`reconcile: id` and a nonempty `rationale`; a late prediction alone cannot pass. +Identical retries retain their declaration; changed bytes, file or session require +a matching receipt. Never use a wildcard acknowledgment. + +The append-only `predictions/guard-events.jsonl` retains `reveal`, `predicted`, and +`reconciled` evidence; acceptance never erases a surprise. Dry runs do not persist +events. Invalid or inaccessible protocol state cannot authorize a changed proposal. +This is local intent bookkeeping, not an adversarial security boundary. + +The initial oracle handles unique existing statements in identifiable function +scopes, plus unchanged complete function bodies. Changed ambiguous/anonymous +scopes and changed statement text produce partial/NOT CHECKED evidence. It does not +establish loop/switch/exception dominance, semantic predicate equivalence, deleted +statements, cross-file moves, or arbitrary shell effects. Native cold fallback runs +the same oracle; a standalone generated hook without the daemon reports NOT CHECKED +because it has no AST runtime. Restore the daemon or use `interlinked-hook` for +that check. Single-line guards remain valid code; brace style is a separate policy. + +Claude's demonstrated native `PostToolBatch` boundary coalesces TypeScript checks for +declared single-file edits. The final tree is checked before the next model request; +security guards remain per edit; metric caps advise unless `harness.edit_metrics.mode` +is explicitly `enforced`. Final compiler findings are +repair context, with unresolved errors enforced at Stop/commit and work that could not +be checked enforced at commit (Stop reports it NOT CHECKED). See **interlinked-verify** +for fallback and recovery behavior. Merely using multiple Edit calls is not evidence +of a retry: correlate their emission time and assistant message with hook feedback. + +Repeated pre-edit content advice, test-evidence limitations, and unchanged coverage +gaps are deduplicated for model delivery. Full observations remain in local evidence. +Deep-audit style/design findings are retained in raw check evidence and available +through `verify --all-checks`; ordinary hook feedback announces this once instead +of sending every finding. Errors and blocking decisions remain visible. A persistent +warning never becomes a proven error merely because it repeats. +Changing coverage counts alone do not repeat the same instruction; a recovered gap +that recurs or a different unavailable-check reason is announced again. + +Claude and Codex Stop/SubagentStop advisories remain operator diagnostics on stderr. +Only explicit blocking repair decisions request another model turn. The Stop advice to +run the full `interlinked verify` suite counts product code files only: an edit under the +repo-root `scratch/` directory does not cause it, because the suite mirrors CI and CI +does not see `scratch/`. Source guidance is +sent during editing. File-size advice and per-function gates share native edit/patch content +projection; unreadable or invalid updates stay unmeasured. Shell effects remain +post-execution evidence unless a supported pre-write path is used. + +PostToolUse classifies recognized untracked Python environments, installed Node dependency +trees and named harness outputs before authored-source checks. Explicit edits, tracked files, +protected policy and unsafe/symlink paths do not receive this exemption. Security scope stays +separate; excluded files are not passes and runtime-input fingerprints are not narrowed. +The same source role separates recovery batches. Repeated unavailable-check diagnostics are +deduplicated for delivery; raw findings and unresolved evidence remain. Retry when prerequisites +change, not merely because the same diagnostic repeats. Missing evidence cannot yield “all clean.” + +For edits outside the guarded repository, both command-based and named external checks +(affected tests and dependency audit) skip this repository's runner. Inline content checks +remain available. Security findings on excluded dependency files retain normal severity and +enforcement; source-quality exclusion is not a security exemption. + +The built-in generic `rm` prior-inspection rule is advisory. A recent literal `Read` event +does not prove inspection of the deletion targets, and clients may expose different read tools. +Inspect the intended targets using the available tools; this heuristic does not require a +particular invocation. Deterministic destructive-command, reservation and protected-file +decisions still apply. Do not infer safe deletion merely from a recent unrelated read. + +The legacy `same_command_thrice_no_observe` advisory excludes simple read commands +such as `tail`, `rg`, and `git status`: polling their output is observation. Compound +commands, shell expansion and output redirection remain eligible. The advisory reports +matching command observations in session history; hook events do not prove distinct +executions or whether the agent read the output. This exception changes no execution gates. + +Guard audit records retain references for repeated warning text. Use `interlinked data search +--source warning-occurrences` to inspect full first/changed messages, hashes and occurrence +counts; `data show ID` opens their raw evidence. This bounds repetition in the activity mirror +without changing the guard decision or the warning returned by the evaluator. A later +`not-reported` observation does not prove that the underlying issue was fixed. diff --git a/skills/interlinked-harness/references/managed-push.md b/skills/interlinked-harness/references/managed-push.md new file mode 100644 index 000000000..0baa262a0 --- /dev/null +++ b/skills/interlinked-harness/references/managed-push.md @@ -0,0 +1,52 @@ +# interlinked-harness: managed push handoff + +Reference for [SKILL.md](../SKILL.md). Read it when a protected push is handed off or falls back. + +For recognized protected pushes in this repository, Codex and Claude can receive a +native command replacement that makes Git's exact-revision pre-push hook the sole +owner of typecheck and test execution. The replacement pins Git/Node, verifies a +private snapshot of the recognized hook and its helper runtime, and forces Git to +use that hook. Git still supplies the actual ref updates and pushed SHAs. This is +not a cached passing verdict, and every other pre-tool guard remains active. + +Recognition is intentionally narrow: a plain `git push ` +from the repository root, with supported literal output redirection. Compound +commands, environment/config overrides, unsupported clients, custom/missing/changed +hooks or unavailable snapshots retain legacy checks. A prepared command whose +snapshot or execution context changes refuses the push. Do not weaken guards or +use bypass flags to force the handoff. See `docs/verification-efficiency.md`. + +Every fallback of a recognized push is typed and visible (2026-11-05). The daemon +writes a `pre-tool:managed-push` row with status `fallback` and +`reuse_denied_reason: handoff-fallback:` to the stage ledger, and the agent +sees one `[interlinked:managed_push_fallback] … (: )` warning. Causes: +`environment-override` (the detail names the variable keys, never values), +`repository-mismatch`, `hook-mismatch`, `stale-trust-map` (regenerate the map after +reviewing the change), `executable-identity`, `snapshot-failure`. A command or client +the handoff never covers (`unsupported-*`) leaves no fallback row; the legacy rows are +its record. The IDE prompt helpers `GIT_ASKPASS` and `GIT_EDITOR` are allowed at +preparation and execution (VS Code exports both in every terminal; neither selects +a repository, configuration, hook, exec path, transport or loader). Every other +`GIT_*` variable except `GIT_PAGER` still refuses the handoff. Explain a real push +from one trace with `interlinked tests trace` (see **interlinked-verify**). +For a recognized fallback on a client supporting command replacement, the response +adds only the trace environment assignment to the original push; the legacy checks +still run. If the client disconnects before receiving that response, the plain push +has a separate hook trace: do not infer a complete daemon/hook join. Unknown failures +use a bounded operation/error-code detail, never arbitrary exception or file contents. + +A hook client that times out (240 s PreToolUse in the installed settings) and +cold-allows the push no longer leaves the daemon's legacy test gate holding the host +slot: both socket transports abort a request's signal when its client disconnects, +and the pre-tool git gate kills its child on it, recording `interrupted`. +Queued framed requests retain that aborted signal after disconnect as well. + +Once the frozen hook is selected, it clears the launcher's command-scoped Git +configuration before verification. This keeps the forced `core.hooksPath` from +overriding nested fixture repositories; the outer push still executes its pinned +protected hook. Ordinary pushes retain their own command-scoped Git settings. + +When maintaining this repository's gate or its helper runtime, regenerate the +reviewed trust map with `node scripts/generate-managed-push-manifest.mjs` and run +the same command with `--check`. A stale map disables recognition; it does not +authorize skipping the legacy checks. Native client approval policies still apply. diff --git a/skills/interlinked-harness/references/permission-proposals.md b/skills/interlinked-harness/references/permission-proposals.md new file mode 100644 index 000000000..cdfc9f305 --- /dev/null +++ b/skills/interlinked-harness/references/permission-proposals.md @@ -0,0 +1,31 @@ +# interlinked-harness: permission proposals and unavailable checks + +Reference for [SKILL.md](../SKILL.md). Read it for permission-learner proposals or NOT CHECKED detector evidence. + +## Permission proposals and unavailable checks + +The permission learner is suggestion-only. Crossing an observation threshold does not write Claude permissions or guard rules. Proposals retain the observed command and conservative pattern; observations do not prove approval or execution. Interpreter-wide and compound-command proposals are withheld. Cross-session `learned-rules.json` is observational proposal history, including its legacy `decision: allow` field; it is not effective authorization. Existing explicit permissions remain operator-owned. + +Unknown `active_when` session predicates leave a distilled rule dormant with a diagnostic. The registered predicate is `active_agent_count_at_least` with `count`; do not substitute invented predicates or the legacy top-level `session_predicate` shape. See **enforce** for supported typed conditions. + +Existing top-level `session_predicate` fields retain their historical unconditional matching and the operator's enabled setting, with a migration diagnostic. They are not evaluated conditions. Migrate them explicitly to supported `active_when` rather than silently disabling existing guards. + +The baseline-effect guard compares bounded pre-call snapshots with the files after a tool +call and restores the WHOLE pre-call file when a protected water-line loosened. Reapply any +legitimate tightening that shared the same file. Restore audits live in +`.interlinked/baseline-undo/restored/`; a failed restore leaves recovery evidence and a warning. +Mutation-manifest changes and first-time seeding of an absent complexity metric are record-only: +review and restore inappropriate changes yourself. Intentional resets require the operator's +`INTERLINKED_DISABLE_BASELINE_GUARD=1` in the daemon environment; putting it in tool text +does not authorize a reset. Dry runs neither restore nor record. + +Snapshots do not cover unbracketed background writes, oversized files, or an absent prior +water-line. A concurrent write inside another call's bracket may be attributed to that call. +Unresolvable Vitest denominator/config comparisons report NOT CHECKED, not a guessed restore. +This local guard is not an immutable security boundary. Explicit edit aliases, including +VS Code replacement arrays, are normalized per target file; shell wrappers retain their cwd +when checking commits and baseline writes. Read-only shell examples are not edits. + +A thrown sequence detector or failed Stop scan records NOT CHECKED evidence while healthy detectors continue. Stop rescans are confined to the selected repository, including resolved symlink targets. External memory/config writes retained in session history are reported out of scope; they cannot launch another project's scan or receive repository check receipts. Project-aware detectors receive absolute paths in that repository. Endpoint checks build a project graph only when a finding requires reachability annotation. An instrumentation failure is not a source violation or a clean scan. LTL remains shadow-only: its event-clock.v1 counts PreToolUse and PostToolUse separately, including a paired tool-use ID. Open finite-trace obligations remain unknown at Stop; predicate exceptions taint that property and cannot manufacture violations. No local control-file guard is an immutable security boundary. + +Each throwing trajectory rule produces unavailable shadow telemetry while peer rules and the LTL monitor continue. Adapter failures also retain unavailable telemetry without changing the enforcement decision. diff --git a/skills/interlinked-harness/references/typescript-history.md b/skills/interlinked-harness/references/typescript-history.md new file mode 100644 index 000000000..fb08cd4b4 --- /dev/null +++ b/skills/interlinked-harness/references/typescript-history.md @@ -0,0 +1,21 @@ +# interlinked-harness: opt-in TypeScript history at Stop + +Reference for [SKILL.md](../SKILL.md). Read it before you enable `session_tsc_history`. + +## Opt-in TypeScript history at Stop + +`verification_stop_checks.session_tsc_history` defaults to `false`. Setting it +to `true` appends advisory context only when the existing unverified-code Stop +warning already fires. It reads up to the final 8 MiB of this repository's +`.interlinked/check-results.jsonl`, using only the same session's executed +TypeScript outcomes strictly before Stop and within the preceding hour. +At least three valid runs and `(finding runs + 1) / (runs + 2) >= 0.5` are +required; the latest valid run must still report a finding. Counted outcomes +must carry a nonempty invocation ID; repeated IDs count only once. Missing, skipped, +deferred, timeout and process/resource failure evidence does not count as a +clean run. A later no-reported-findings result suppresses the addendum. + +This is a reported-finding history hint, not proof of full compile failure or +success, not a per-edit risk score, and never a hard block. It does not change +the TypeScript scheduler. Partial or unavailable log history can suppress the +hint. Continue to use actual verification evidence for the final outcome. diff --git a/skills/interlinked-observability/SKILL.md b/skills/interlinked-observability/SKILL.md index e7e3e141f..75e830957 100644 --- a/skills/interlinked-observability/SKILL.md +++ b/skills/interlinked-observability/SKILL.md @@ -6,76 +6,40 @@ description: "Investigate agent activity and JSONL/gzip evidence. Load for data # interlinked-observability — inspect what agents did -For internal claim-verification research, `node --import tsx scripts/internal/jev.mjs claims - --receipt-shadow ` adds default-off, log-only -deterministic comparisons to `.interlinked/claim-receipt-shadow.jsonl`. It does not run from -public Stop hooks or change Jev's decision. Links explicitly bind a claim to receipt/source/ -selection identities; missing or duplicate links remain not assessable. Only four narrow -receipt predicates are supported; see `docs/internal/jev.md`. A missing Jev score is unmeasured, -including short claims omitted by the legacy splitter. Separate replay statistics from live -usage, and inspect `receiptShadowFailures()` before treating an absent row as no claim. - -Ordinary hook delivery omits deep-audit style/design messages after one review -notice, while raw check results remain intact. This applies to synchronous responses -and the late-warning spool; their deduplication state is separate so preparing a -fallback cannot consume the synchronous notice. Repeated guard-scope advice is -deduplicated per session. Compare native delivered feedback separately from raw -finding counts; fewer delivered warnings do not imply fewer findings or clean code. -Interactive ChangeSet batches defer project-wide Gitleaks to explicit verification -or background recovery, with an explicit non-verdict. Confirm actual tool timings -and completion before claiming latency or security-coverage improvements. - -For Claude compiler batching, distinguish tool calls, scheduled checks, compiler -executions and delivered diagnostics. `hook-observation.v1` rows record scheduled -TypeScript work; batch results and timing are in `check-results.jsonl`. Pending work -survives in `.interlinked/compiler-batches/`. Coverage observations are retained even -when repeated model warnings are suppressed. Silence does not mean coverage is complete. -Measure a repeated-edit problem by assistant-message/tool-use identity and timestamps: -an edit emitted before an earlier hook's feedback cannot be attributed to that feedback. - -`check-executions.jsonl` also carries `hook-observation.v1`: scheduled external overlays, -normal complexity/token measurements, and shadow trajectory observations. These are telemetry, -not check passes or confirmed model delivery. `check-results.jsonl` retains full findings, -including `novelty`, `findingCount` and server-computed `writeAttribution` where available. -Newly observed means report novelty, not proven causation. Repeated advisories may be hidden -from model feedback while remaining in each call's records; hidden findings prevent all-clean. - -Use `evals/compare-builds.mjs` for paired explicit-build agent pilots. It retains fixtures, -native streams, usage categories, settings, daemon status, final diffs and evaluator-owned -functional checks. Activity warning counts are ledger metrics. Missing native delivery/token -data remains unknown; do not infer billed savings from shorter commands or compressed rows. - -`repeated_implementation` check results retain each current AST-matched group with -a `group=` detail identity, even when unchanged agent-facing warnings are -suppressed. Compare these identities rather than line numbers across formatting edits. -Post-tool suppression is session-local and resets with the daemon; Stop uses its -existing digest state. NOT CHECKED means missing analysis, not zero clones. Findings -are review candidates, not proven defects or evidence that an extraction helped. - - -`hook-reentry.jsonl` records Stop/SubagentStop re-entry suppressed before daemon evaluation. -Translation receipts now include advisory context representation as well as denials and -rewrites. Operator-only Stop diagnostics are not model-context delivery. Audit native -completion messages by unique ID; streaming chunks and daemon Stop counts are insufficient -to count continuations. The SlopCodeBench exporter retains these receipts and registrations. - -Shared hook-check receipts may include `scopes` with a batch ID, check name, configuration -hash and captured request-file identities. `kind: request-inputs` is historical execution -evidence, not a complete runtime/dependency closure or reusable cache key. Nonempty -`unavailable` preserves partial evidence and leaves the obligation pending. Keep those states -separate from clean results when comparing recovered check counts or latency. - -`source-scan-scope.v1` capture rows record dependency/runtime exclusions from authored-source -quality, with `excluded_not_checked` status. `source-scan-security.v1` retains the separate -security findings and request-input evidence. Neither row authenticates a writer or certifies -runtime-input closure. Repeated unavailable-check messages are deduplicated for delivery by -session, project, configuration and reason; raw check results retain missingness. Counts in -the agent channel therefore differ intentionally from raw deferral counts. - -Cowork plugin receipts use a separate metadata-only schema and explicit exports. -Use **interlinked-cowork** and `interlinked cowork report --effects

` -for native conformance. An intended hook decision is not execution/prevention proof; -these receipts do not provide complete transcripts or authenticated writer attribution. +Interlinked captures normalized tool-call events that configured Claude Code, +Codex, Copilot CLI, Gemini CLI, Cursor, OpenCode, and Pi integrations deliver — +locally via hooks, offline-first, into append-only JSONL under `.interlinked/`. +The running daemon persists those delivered events. Detached lifecycle events and +asynchronous PostTool findings can arrive after the originating provider action, +and a cold fallback is not a complete capture path, so the log is evidence of +events already delivered and persisted—not a synchronous transcript of every +agent action. You can answer *what did I (or a parallel agent) just do? what ran, +on what files, with what tokens? what did the guard block? what mistakes keep +recurring?* — **all without a server** (the server is optional enrichment). + +## Load this when + +`recurrence propose ` reports a missing proposal with a nonzero exit. +Its JSON mode emits a structured error on stderr. `trajectory show --json` +validates retained JSON before printing it. Missing, unreadable or malformed +snapshots produce a structured JSON error and nonzero exit. Valid raw JSON keeps +its stored formatting. + +`collect --since` requires an explicit nonempty duration. Omitting it retains +whole-history collection. `telemetry --follow --json --limit N` emits JSONL for +both the initial tail and later events. When a watched spool shrinks, following +restarts at byte zero, which can replay retained rows after compaction. + +Git attribution preserves exact NUL-delimited paths and uses literal arguments +for filenames and revisions. Untracked-only work participates in its existing +patch-line estimate. Attribution remains a heuristic observation. + +- "What did I / another agent do this session?" — or you want to tail activity live. +- Reviewing what the guard blocked or warned. +- Finding recurring mistakes to harden against. +- Reporting recorded local changes without turning correlation into a savings or causal claim. +- Inspecting a specific session, event, or the repo dependency graph. +- Backfilling external (Codex) sessions, verifying the audit log, or syncing to the server. ## Search and organize all local evidence @@ -105,137 +69,18 @@ literal queries, FTS token queries, and raw `rg` searches have distinct semantic interlinked data scan "compiler import" --source check-results --max-mb 32 --limit 10 --full-text --raw --json ``` -Direct scans default to 32 MiB expanded input and 25,000 physical lines, taking complete-line -prefixes of the most recently modified files. They include retained gzip archives and numeric -rotations. A narrow time filter does not jump to a newer portion of a large file. Inspect -`coverage.complete` and `scope`; increase explicit budgets or choose an existing index when -necessary. `--raw` returns the observed source text with its hash. Scan/lab IDs are separate -from production `data show` IDs. File filters for `data scan` use project-relative paths. -Use `--full-text` when omission by the bounded index projection matters: it searches all -decoded string values inside each readable complete record, excluding JSON field names. -Byte/line budgets and oversized-record limits still apply. Without this flag, a complete scan -with `coverage.truncated > 0` does not establish that a term is absent from original payloads. - -Use `interlinked data catalog` to discover registered and unknown JSONL files recursively, -including numeric rotations and gzip archives. `data health` distinguishes observed writes, -unsupported/disabled/idle producers, failures, and unmeasured populated files. Its receipt -window is bounded; a quiet event-driven feed is not automatically broken. `doctor` reports -capture failures and unmeasured coverage. - -```bash -interlinked data index --max-mb 256 --max-records 250000 --json -interlinked data status --json -interlinked data search "compiler import" --since 7d --json -interlinked data search --source check-results --session SESSION --json -interlinked data show RECORD_ID -interlinked data investigate --session SESSION --json -interlinked data investigate --file src/app.ts --json -interlinked data checks --check typescript --json -interlinked data usage --session SESSION --json -interlinked data suggestions --json -interlinked data recurrence-inventory --json -``` - -Indexing is incremental and bounded: repeat until the retained backlog is covered. `--rebuild` -clears only derived tables. SQLite/FTS5 loads lazily; use a Node runtime with built-in SQLite -(Node 22.13+ avoids needing the earlier experimental flag). Search includes retained archives; -`--no-archives` restricts it to live files. `--fts` opts into FTS5 query grammar. Structured -filters include source/category/session/actor/provider/model/file/check/call/kind/decision/origin. -Catalog source names and categories stay consistent between direct scans and indexed search, -including sources stored under nested paths such as `logs/latency.jsonl`. -Unknown event timestamps are excluded by time bounds. The older `query` command scans a -bounded physical tail of one file and reports its scope; it does not promise archive coverage. - -Each indexed answer carries a record ID; `data show` retrieves the original JSON and verifies -its SHA-256. Projection text/field traversal is bounded, and oversized or malformed rows are -reported without deleting their raw bytes. Check `data status` for freshness and parse failures. -Invalid UTF-8 is malformed evidence: scans and new imports report it and continue to later -complete records; `data show` refuses to verify it. A valid replacement character (`�`) in -UTF-8 is ordinary text. For indexes created before strict UTF-8 validation, use an explicit -`data index --rebuild` to remove earlier lossy projections; historical raw bytes remain intact. -Exact duplicate raw records within one logical source share an indexed record but retain all -physical locations. Cross-stream observations are not automatically independent executions. - -`data sessions/files/checks/usage/schema/suggestions` expose evidence aggregates. `investigate` -correlates exact provider/session/actor/call identities and labels missing phases; a file filter -also strictly folds the obligations ledger. A block count is not a prevented-defect estimate. -Suggestion `shown` means selected for presentation, not acknowledged; later absence is an -observation, not proof of a fix. Usage has unknown values and no invented prices; never add -overlapping timeline and costs totals. Recurrence inventory is separate from incident counts. -Usage deduplication chooses a provider-message representative within the query's retained -scope, so superseded source generations and excluded archives do not hide a retained copy. -Aggregate limits bound returned groups, not necessarily database work; narrow supported -filters first. `schema` is a source-wide observed field census: only `--source` and `--limit` -affect its scope, even though its CLI accepts the shared filter flags. - -`data maintain` previews retention. `data maintain --execute --compact --no-index` losslessly -rotates eligible collection/timeline history without opening or creating SQLite. Add `--index` -to explicitly import a bounded batch and translate existing evidence pointers during rotation. -Without either index flag, indexing follows `auto_index`. It never deletes evidence or -automatically compacts activity/state ledgers/corpora. -Activity still requires the existing cursor-aware `compact` workflow. After an external -compactor, rerun `data index` to discover replacement files and archives. - -Preserve evidence indefinitely: do not delete, expire, truncate, sample away, or rewrite raw -records, archives, manifests, or integrity checkpoints to reclaim space or hide bad rows. -Lossless rotation changes physical placement while retaining every record. A smaller live -file is not less retained history. Search archives with `data search`; older live-file readers -cannot answer questions about the complete retained history. `--rebuild` replaces derived -index tables only and is not a routine retention operation. Index storage can exceed raw-log -storage substantially; the per-pass import budget is not a cap on total index size. - -Rotation prepares the bulk retained suffix before acquiring the append lock. Identity is -rechecked under the lock, and only a bounded catch-up plus the atomic rename exclude writers. -An excessive append burst or competing replacement aborts safely for retry. Maintenance -operation failures are recorded in capture health. - -`data configure --auto-index on` opts into bounded SessionEnd background indexing; -`--auto-compact on` independently enables collection/timeline rotation. Both default off; -enabling rotation alone does not enable or run the SQLite importer. -Defaults are 256 MiB/250,000 records per pass, a 256 MiB rotation threshold, and a 64 MiB live -tail. Configure via `--index-mb`, `--index-records`, `--compact-at-mb`, `--keep-live-mb`. -Settings live in `data.config.json` under the resolved data directory; capture itself continues -independently. Load new daemon capture code through the normal build/reload workflow. -SessionEnd is an actual provider lifecycle event, not each assistant Stop. This automation -does not continuously watch files or refresh a long-running active session on a timer. Run an -explicit index pass when recent evidence matters; a deferred background job is not freshness. - -`data audit diagnose` locates the first historical failure by physical source/offset and does -not infer tampering intent. Its source line and byte offset refer to the physical record even -when archived blank lines are omitted from the verifier's combined line count. -After investigation, `data audit checkpoint --reason TEXT` records -an explicit payload-verified live observation boundary. `data audit verify --checkpoint ID` -checks subsequent retained evidence, including after rotation. The historical verdict stays -unchanged; checkpoints never rewrite or reset the old chain. - The bundled [workflow reference](references/evidence-workflows.md) is available in installed skills. In the Interlinked CLI source repository, `docs/data-observability.md` and `docs/generated/data-catalog.md` provide the operator contract and generated source catalog; in another project, use `data catalog --json` to inspect its sources. -Interlinked captures normalized tool-call events that configured Claude Code, -Codex, Copilot CLI, Gemini CLI, Cursor, OpenCode, and Pi integrations deliver — -locally via hooks, offline-first, into append-only JSONL under `.interlinked/`. -The running daemon persists those delivered events. Detached lifecycle events and -asynchronous PostTool findings can arrive after the originating provider action, -and a cold fallback is not a complete capture path, so the log is evidence of -events already delivered and persisted—not a synchronous transcript of every -agent action. You can answer *what did I (or a parallel agent) just do? what ran, -on what files, with what tokens? what did the guard block? what mistakes keep -recurring?* — **all without a server** (the server is optional enrichment). - -## Load this when -- "What did I / another agent do this session?" — or you want to tail activity live. -- Reviewing what the guard blocked or warned. -- Finding recurring mistakes to harden against. -- Reporting recorded local changes without turning correlation into a savings or causal claim. -- Inspecting a specific session, event, or the repo dependency graph. -- Backfilling external (Codex) sessions, verifying the audit log, or syncing to the server. - ## Command surface Output-mode flags are **per-command** (not uniform); all support `--json`. `--since` grammar is strict: `\d+(s|m|h|d)` (e.g. `30m`, `2d`) — `15` or `1.5h` throw. +`status --watch --json` emits a sequence of complete JSON objects at each refresh. +Terminal clearing and refresh banners are limited to human output modes. + **Dashboard / feed** | Command | Purpose | Key flags | |---|---|---| @@ -274,9 +119,31 @@ over 250,000 records / 64 MiB instead of exhausting application memory. | `compact [--dry-run --keep-recent-mb --all]` | Lossless gzip + rotate `activity.jsonl` (safe prefix ≤ sync cursor, audit-chain-aware) PLUS `collection.jsonl` / `timeline.jsonl` (plain recent-tail rotation, per-log `manifest-.json`). Appenders and rotation share a cross-process lock, so appends made during compaction survive. A durable per-log claim precedes final segment publication; retry verifies its source identity, recorded prefix, gzip size, and SHA-256 before completing the SAME segment, even when the process died before the manifest write. Unknown or mismatched segment bytes stay untouched and stop that recovery. While either a durable claim or a legacy claim-less pending manifest row exists, `clean` and whole-file timeline rebuilds refuse to replace that log; ordinary appends remain allowed so recovery includes later rows. Activity recovery also refuses any recorded sync cursor beyond the retained suffix. Activity compaction refuses a sync cursor beyond the current EOF (unless `--all` explicitly bypasses sync bounds). All bytes remain recoverable via `gunzip` in manifest order. | | `sync [--dry-run --limit]` | Push buffered events to the server (`POST /api/hooks/activity/batch`, secret+PII scrubbed at egress). Network — use `--dry-run` for a safe pending count. | +Compaction can start a new archive when its directory is missing. If an existing archive directory cannot be listed, compaction stops before allocating a segment number. + `interlinked metrics` (whole-repo code-quality scan) lives in **interlinked-quality-gates**; `interlinked context` (effective config) in **interlinked-setup**. +`interlinked query checks --actions --json` projects selected retained hook evidence +into the same action schema as metrics and verification, without executing checks or +calling a model. Normal/full output includes next steps and validation. The ordinary +query time, row and byte bounds still apply and remain in the report; increase them +explicitly to inspect more history. This is historical evidence, not a current unresolved +worklist. Revalidate source and policy before acting. Captured observations with a +consistent nonempty primary source hash are snapshot-bound. Supplied `sourceEvidence` +also retains captured producer/consumer paths, lines and hashes. Grouped historical +versions with conflicting primary or supporting hashes have unknown freshness and +retain every version's evidence. This does not certify complete dependency capture +or current disk freshness; older record formats may retain only primary evidence. +Legacy records without detailed findings remain unknown, and simulated rows are +excluded. Suppressed raw observations retain their reason and structured suppression +metadata. Supplied evidence is appended without a function-argument count cutoff; +the query window limits still apply. Supplied, accepted and rejected finding-row +counts expose unsupported detail rows separately from unrecognized records. The flag requires +the `checks` source and cannot combine with `--by`, `--sum` or `--fields`. +Query row limits must be positive safe integers; byte budgets must represent at least +one byte. Malformed numeric suffixes are errors rather than partially parsed numbers. + For measured gate execution, `interlinked metrics gates --json` separates enabled policy from actual attempts, fresh source-bound reach, stale/deferred/unavailable work and recorded latency percentiles. `.interlinked/metrics/executions.jsonl` is the bounded local execution @@ -294,6 +161,13 @@ returns full pending identities and receipts. Neither starts recovery; route exp `harness coverage verify` and unresolved check prerequisites to **interlinked-verify**. Hook-check receipts with nonempty `unavailable` retain partial work; their pending version is not discharged. Do not count them as fully checked files or reusable passing evidence. +Receipts may separately retain `advisoryGaps` with a check, file and reason. These record +unmeasured advisory scope, such as incomplete Commander reverse-import evidence. They are +not defect findings and do not create required retry or blocking obligations. Completed +listed checks can settle their work while advisory coverage remains explicitly unknown. +Own-barrel pre-write unknowns also retain explicit unavailable advisory observations +in `check-executions`; see [capture notes](references/capture-notes.md). A zero finding +count on an unavailable observation is not a clean graph verdict. For runtime scan profiling, Node's `interlinked.coverage-runtime-scan` diagnostics channel emits root, completed flag, bytes read, entries visited and duration even on failed captures. Subscribers must be in the scanning process. The optional `evals/slopcodebench/scan-cost.mjs` @@ -419,53 +293,33 @@ Values: `session_start`, `session_end`, `tool_use_start`, `tool_use`, `tool_use_ `context_compact`, `task_completed`, `agent_stop`, and guard telemetry `guard_allow` / `guard_warn` / `guard_block`. +Claude Code reports a failed Bash call only as `PostToolUseFailure` (row type `tool_use_error`). +Installs before 2026-11-16 did not subscribe it, so failed calls from that time have no +completion row and `tests.jsonl` has no `fail` rows for them. That gap is missing capture, not +proof that the calls passed. Run `interlinked install-hooks --refresh --preserve-mode` to subscribe +it. A failed test command then gets `outcome: "fail"` and the `exit_code` from the error text. + +Read `outcome` in `tests.jsonl` together with `basis`. `exit_code` is always the shell's status, +and it is the check's verdict only when `exit_attributable` is `true`. After a pipe or a later +command (`vitest run … | tail`, `npm test; echo done`) the status belongs to that other command, +so the row gets `basis: "runner-summary"` when the output holds a vitest or jest summary line, and +`outcome: "unknown"` with `basis: "exit-status-not-attributable"` when it does not. `set -o +pipefail` before the check makes a piped status attributable again. Rows written before +2026-11-16 have no `exit_attributable` field: a `pass` with `basis: "provider"` on a piped +command there is the shell's status, not proof that the check passed. The same rule decides the +red/green state behind the Stop `unresolved-red` nudge: a typecheck, build or lint run with a +hidden status records nothing and returns an `[interlinked:check-evidence]` warning. + **Sync modes** (`sync_mode`, or `INTERLINKED_SYNC_MODE`): `realtime` (default — per-event POST + session-end batch), `local` (never posts), `manual` (per-event POST, no auto batch — you run `interlinked sync`). ## The Stop digest — what end-of-turn stderr actually shows -Every Stop event runs ~20 independent nudge families. They no longer print in -full: `src/harness/stop-digest.ts` ranks and caps the whole wall to **≤15 -stderr lines**, and everything it trims goes to the spool. - -| Position | Contents | -|---|---| -| TOP | up to 3 warnings printed in full (≤4 lines each), ordered **actionable → measurement-threatening → reflection** | -| SUMMARY | one line per remaining category: `[interlinked:digest] xN (see …)` | -| POINTER | `.interlinked/stop-digest.jsonl` — the full detail, per-session capped | - -Read the spool when a count line is not enough: - -```bash -interlinked query .interlinked/stop-digest.jsonl --where kind=subagent-attributed -tail -n 40 .interlinked/stop-digest.jsonl | jq -r '[.kind,.tag//.check,.file]|@tsv' -``` - -Row kinds: `stop-warning` (a trimmed nudge), `subagent-attributed` (a finding on -a file a SUBAGENT wrote — attributed via `timeline.jsonl` and kept out of the -main list), `pre-existing` (present in the session's git baseline), and -`sanctioned-scratch` (probe-pattern findings under root `scratch/`, which the -scratchpad policy sanctions — still reported by `interlinked verify ---all-checks`). The sanctioned classes are what a probe IS: print, no -companion test, import-time side effect, raw `JSON.parse`, plus the -entry-script family whose own rationale exempts bin/cli files — argv -boundary, env read, unjustified cast, wall clock, magic number. Product -code outside `scratch/` keeps every one of them. - -Two consequences worth knowing: -- **The rescan reports introduced-only.** A whole-file scan still runs, but a - finding your session did not introduce is spooled, not printed. -- **Suite failures are not multiplied into per-file regressions.** A cycle - reddened only by a whole-suite failure is excluded from the green→red Stop - list; the unresolved `test-suite` outcome remains one check-level signal - until a targeted test run supplies file-level evidence. -- **A repeat Stop prints only what is new**, plus one `R resolved, S unchanged - (suppressed)` line. Per-session state lives in - `.interlinked/.stop-digest-state.json` (daemon bookkeeping — do not hand-edit). - -Activating a change to any of this needs `npm run build && interlinked harness -restart`: the daemon serves the build it started with. +`src/harness/stop-digest.ts` caps the Stop stderr wall to 15 lines: up to 3 full warnings, one +`[interlinked:digest]` count line per other category, and a pointer to `.interlinked/stop-digest.jsonl` +(the full detail). A repeat Stop prints only what is new. The row kinds, the spool queries and the +introduced-only rules are in [references/calls-and-outcomes.md](references/calls-and-outcomes.md). ## `interlinked query stages` — where verification time goes @@ -565,50 +419,6 @@ interlinked viz snapshot [--json] [--full] # print the graph summary ( `.interlinked/viz.status` (`url=` + `pid=`), which the statusline reads to render a clickable `◈ viz` row; the row disappears when that pid dies, so the link is never stale. -Six lenses, each fed by its own SSE route: - -| Lens | Route | Source | Shows | -|---|---|---|---| -| FILES | `/api/graph` + `/api/stream` | project graph + `activity.jsonl` | one dot per source file, one line per import, dot size = how many files depend on it; a touched file pulses in the colour of the agent that touched it | -| GATES | `/api/checks` | `check-results.jsonl` | one frame per tool call: which checks ran, which fired, allowed or blocked, `[proven]`/`[heuristic]` | -| AGENTS | `/api/agents` | `activity.jsonl` (folded) | one lane per agent session working in this repo, indented lanes for subagents it spawned: runner, model, calls/edits/blocks/warns, current tool + file, live-vs-idle | -| TESTS | `/api/tests` | `test-events.jsonl` | every test case in the order the runner finished it; pass/fail/skip, slow cases outlined, failure messages | -| MUTANTS | `/api/mutants` | `mutation-manifest.json` | every mutant, survivors first; live kill-rate; a tile flashes when its status flips | -| DRIFT | — | — | not built yet (standby pane) | - -The AGENTS lens needs no producer: attributed activity rows carry `agent`, `session`, -`subagent_id`, `parent_agent`, and `model`, so presence is a fold over the stream the dashboard already tails -(`src/lib/viz/agent-roster.ts`, hosted at `/api/agents`). Each actor gets a stable hue from its -id, and that hue is reused for its ticker rows and its file pulses — with two sessions running, -colour alone answers "who did that". A subagent gets its OWN lane keyed under its parent, so a -session's own edits are never conflated with its subagents'. When a runner names the parent by -thread/session id, the roster resolves that id through the root lane's session before linking the -child. Lanes dim to idle after 2 minutes of silence rather than disappearing. - -The TESTS lens needs a producer. Any repo using vitest adds one line: - -```ts -// vitest.config.ts -reporters: ["default", "interlinked-cli/viz-reporter"] -``` - -Gating it behind an env var is the recommended setup, so a normal `vitest run` stays -byte-identical and only an explicit opt-in emits the feed — that is how interlinked-cli's own -`vitest.config.ts` wires it: `INTERLINKED_VIZ=1 npx vitest run`. Any equivalent conditional -works; nothing about the lens requires that variable name. The feed schema -(`.interlinked/test-events.jsonl`) is runner-agnostic — `{kind: run_start|file_start|test|run_end, -run_id, lane?, file?, name?, status?, ms?, error?}` — so a pytest/cargo adapter writes the same lines -and the lens renders unchanged. Every feed degrades to an honest empty state when its file is -absent; nothing about the dashboard is repo-specific. - -The Interlinked CLI e2e config always registers the reporter; `test:e2e` also -sets `INTERLINKED_VIZ=1`. The TESTS lens groups files by `unit`, `integration`, -`e2e`, `base` or `unknown` lane. A bare Vitest run is `base`; old rows without -a lane remain `unknown`. Repository test rows are run evidence. Fixture -ledgers are assertion subjects and do not establish which coding session ran -the tests. The Stop nudge attributes e2e invocations through that session's -observed Bash commands instead. - ## Common workflows ```bash interlinked status # sessions + last events + sync/server health @@ -648,51 +458,20 @@ interlinked sync --dry-run # safe: pending count, no send verify a supplied controlled experiment's artifact bindings, but it does not run or reproduce an experiment. No class is a generic savings claim. +## References + +Read a reference file only when the task needs it. + +- [references/evidence-workflows.md](references/evidence-workflows.md): task recipes, source selection, pagination and a handoff checklist. +- [references/data-commands.md](references/data-commands.md): direct-scan budgets, `data catalog`, indexing, `data show`, aggregates, `data maintain`, rotation, auto-index and `data audit diagnose`. +- [references/storage-evaluation.md](references/storage-evaluation.md): storage experiments and `data lab`. +- [references/capture-notes.md](references/capture-notes.md): capture-record notes, such as `hook-observation.v1`, `hook-reentry.jsonl`, receipt scopes, `source-scan-scope.v1` and Cowork receipts. +- [references/viz.md](references/viz.md): the `interlinked viz` lenses and the vitest TESTS reporter. +- [references/calls-and-outcomes.md](references/calls-and-outcomes.md): `harness calls`, the tool-output efficiency lab, finding outcomes and `harness explain`. + ## Related skills - **interlinked-quality-gates** — `interlinked metrics` (code-quality hotspots) and `recurrence scan`. - **interlinked-harness** — the guard whose block/warn telemetry you're inspecting. - **interlinked-coordination** — the server-backed side (tasks, messages) `watch`/`sync` reach. - **interlinked-simplification** — advisory opportunities whose estimated and validated impact must remain separate. - -## Comparing calls with daemon judgments - -Recurrence scans use the selected `--cwd` as their repository context. A throwing -detector or missing prerequisite emits NOT MEASURED while healthy detectors continue. -These notices are surfaced through stderr/callbacks; the retained finding receipt does -not yet contain a complete structured inventory of unavailable detector scope. An empty -finding list therefore does not establish that every detector ran successfully. - -`interlinked harness calls [--since 7d] [--session ] [--strict] [--json]` -joins live `timeline.jsonl` tool calls to live collection judgments by session AND -tool-use ID. It lists unjudged observed calls by tool, working folder and time span. -Run from the project root. Exit 0 means reported, 1 means `--strict` found unjudged -calls, and 2 means no calls/evidence or an error. This measures the observed live -window; rotated or missing capture is a gap, not a clean enforcement claim. - -## Tool-output efficiency lab (source checkout only) - -Use `evals/tool-output-efficiency/README.md` for frozen native-session measurement, -code/decision/embedding selection, and the explicit capture/expand wrapper. -No question means the declared baseline; `--full` bypasses selection. Keep the -receipt ID and expand missing evidence or exact edit text before acting. Offsets -are end-exclusive UTF-16 units. Selection is advisory and does not alter hooks. -Keep native logs local unless remote submission is explicitly authorized. -The lab's live model controls are synthetic; `.local/` artifacts remain ignored. -Report same-agent/same-compaction repetition separately from later compactions -and other agents. No observed later use is not proof of waste. Character budgets, -recorded token additions, repeated provider input, costs, and live context size -are different measurements. Replay does not establish live expansion behavior -or task success. See RESULTS.md before claiming savings or adopting filtering. - -## Finding outcomes and explanation - -`interlinked harness health --json` adds `finding_outcomes` and `corpus_precision`. `harness health --recheck --file src/a.ts` runs up to 20 confined files (2 MB each); omitted files come from retained finding records. Read failures remain unavailable. This explicit raw-detector recheck is independent of whether the agent edits again. - -The first raw file cohort is `async_promise_executor`, `nan_comparison`, and `unawaited_async_assertion`; this measurement cohort is separate from corpus qualification. Versioned `check-observations.v1` rows share the existing check-results stream. Full compatible successful rechecks with zero hits for that file/check can establish observed clearance. Partial scans, suppression, deletion, detector/config changes and missing execution cannot establish repair. The derived `finding-outcomes.v2` uses conservative file/check occurrence slots, independent of build identity. Changed text or multiplicity is ambiguous; it cannot credit a removed occurrence while that check still finds another. Counts are finding slots, not semantically unique defects. Delivery is intended/unknown, not inferred native receipt. - -The report shows distinct findings, emissions, follow-up coverage, recurrence, unavailable states, execution time and the observation window. Stop records individual intended emissions after filtering, capping and deduplication; a summary count is not individual delivery evidence. Inline deferrals retain acknowledgement reason/time/session and do not count as clearance. Native receipt remains unknown. Precision uses adjudicated live corpus hits only, with unsampled hits and scope visible; corpus freshness is not recomputed by health. Triage time remains unmeasured. Observed clearance is not causal fix rate. Legacy Boolean resolution scores are no longer produced or used by this report. The current reader covers the unrotated local log only; archives and legacy outcomes remain unknown. - -The outcome reader scans at most the newest 2 MiB and retains the newest 2,000 complete rows, with a 128 KiB per-line limit. JSON `read_window` reports omitted prefixes, records, oversized and incomplete lines. It does not claim all-time totals. Build-time identity is embedded in packaged code and combined with the Node runtime/platform; it needs neither a lockfile nor a directory hash at command startup. Source-mode identities remain process epochs and cannot establish cross-process clearance. - -`harness explain --client --json` separates implemented, enabled here, declared client support and latest retained execution (including clean execution). Observations carry timestamp, scope, configuration and detector identity; a seven-day recency field is separate from current-runtime matching. Missing observation is unknown, not disabled. diff --git a/skills/interlinked-observability/references/calls-and-outcomes.md b/skills/interlinked-observability/references/calls-and-outcomes.md new file mode 100644 index 000000000..acde1e09e --- /dev/null +++ b/skills/interlinked-observability/references/calls-and-outcomes.md @@ -0,0 +1,95 @@ +# interlinked-observability: calls, outcomes and explanation + +Reference for [SKILL.md](../SKILL.md). Read it for `harness calls`, `harness health` finding outcomes or `harness explain`. + +## Comparing calls with daemon judgments + +Recurrence scans use the selected `--cwd` as their repository context. A throwing +detector or missing prerequisite emits NOT MEASURED while healthy detectors continue. +These notices are surfaced through stderr/callbacks; the retained finding receipt does +not yet contain a complete structured inventory of unavailable detector scope. An empty +finding list therefore does not establish that every detector ran successfully. + +`interlinked harness calls [--since 7d] [--session ] [--strict] [--json]` +joins live `timeline.jsonl` tool calls to live collection judgments by session AND +tool-use ID. It lists unjudged observed calls by tool, working folder and time span. +Run from the project root. Exit 0 means reported, 1 means `--strict` found unjudged +calls, and 2 means no calls/evidence or an error. This measures the observed live +window; rotated or missing capture is a gap, not a clean enforcement claim. + +## Tool-output efficiency lab (source checkout only) + +Use `evals/tool-output-efficiency/README.md` for frozen native-session measurement, +code/decision/embedding selection, and the explicit capture/expand wrapper. +No question means the declared baseline; `--full` bypasses selection. Keep the +receipt ID and expand missing evidence or exact edit text before acting. Offsets +are end-exclusive UTF-16 units. Selection is advisory and does not alter hooks. +Keep native logs local unless remote submission is explicitly authorized. +The lab's live model controls are synthetic; `.local/` artifacts remain ignored. +Report same-agent/same-compaction repetition separately from later compactions +and other agents. No observed later use is not proof of waste. Character budgets, +recorded token additions, repeated provider input, costs, and live context size +are different measurements. Replay does not establish live expansion behavior +or task success. See RESULTS.md before claiming savings or adopting filtering. + +## Finding outcomes and explanation + +`interlinked harness health --json` adds `finding_outcomes` and `corpus_precision`. `harness health --recheck --file src/a.ts` runs up to 20 confined files (2 MB each); omitted files come from retained finding records. Read failures remain unavailable. This explicit raw-detector recheck is independent of whether the agent edits again. + +The first raw file cohort is `async_promise_executor`, `nan_comparison`, and `unawaited_async_assertion`; this measurement cohort is separate from corpus qualification. Versioned `check-observations.v1` rows share the existing check-results stream. Full compatible successful rechecks with zero hits for that file/check can establish observed clearance. Partial scans, suppression, deletion, detector/config changes and missing execution cannot establish repair. The derived `finding-outcomes.v2` uses conservative file/check occurrence slots, independent of build identity. Changed text or multiplicity is ambiguous; it cannot credit a removed occurrence while that check still finds another. Counts are finding slots, not semantically unique defects. Delivery is intended/unknown, not inferred native receipt. + +The report shows distinct findings, emissions, follow-up coverage, recurrence, unavailable states, execution time and the observation window. Stop records individual intended emissions after filtering, capping and deduplication; a summary count is not individual delivery evidence. Inline deferrals retain acknowledgement reason/time/session and do not count as clearance. Native receipt remains unknown. Precision uses adjudicated live corpus hits only, with unsampled hits and scope visible; corpus freshness is not recomputed by health. Triage time remains unmeasured. Observed clearance is not causal fix rate. Legacy Boolean resolution scores are no longer produced or used by this report. The current reader covers the unrotated local log only; archives and legacy outcomes remain unknown. + +The outcome reader scans at most the newest 2 MiB and retains the newest 2,000 complete rows, with a 128 KiB per-line limit. JSON `read_window` reports omitted prefixes, records, oversized and incomplete lines. It does not claim all-time totals. Build-time identity is embedded in packaged code and combined with the Node runtime/platform; it needs neither a lockfile nor a directory hash at command startup. Source-mode identities remain process epochs and cannot establish cross-process clearance. + +`harness explain --client --json` separates implemented, enabled here, declared client support and latest retained execution (including clean execution). Observations carry timestamp, scope, configuration and detector identity; a seven-day recency field is separate from current-runtime matching. Missing observation is unknown, not disabled. + +## The Stop digest — what end-of-turn stderr actually shows + +Every Stop event runs ~20 independent nudge families. They no longer print in +full: `src/harness/stop-digest.ts` ranks and caps the whole wall to **≤15 +stderr lines**, and everything it trims goes to the spool. + +| Position | Contents | +|---|---| +| TOP | up to 3 warnings printed in full (≤4 lines each), ordered **actionable → measurement-threatening → reflection** | +| SUMMARY | one line per remaining category: `[interlinked:digest] xN (see …)` | +| POINTER | `.interlinked/stop-digest.jsonl` — the full detail, per-session capped | + +Read the spool when a count line is not enough: + +```bash +interlinked query .interlinked/stop-digest.jsonl --where kind=subagent-attributed +interlinked query stop-digest --where kind=stop-rescan-finding --where file= +tail -n 40 .interlinked/stop-digest.jsonl | jq -r '[.kind,.tag//.check,.file]|@tsv' +``` + +Row kinds: `stop-warning` (a trimmed nudge), `stop-rescan-finding` (one row for +each finding the Stop rescan message counts, with check id, line and text: the +message prints at most four for each file, and its `...and N more` line names this +query), `unknown-writer` (a finding on a file that entered the rescan only because +Stop observed a workspace change that no tool call of the session declared), +`subagent-attributed` (a finding on +a file a SUBAGENT wrote — attributed via `timeline.jsonl` and kept out of the +main list), `pre-existing` (present in the session's git baseline), and +`sanctioned-scratch` (probe-pattern findings under root `scratch/`, which the +scratchpad policy sanctions — still reported by `interlinked verify +--all-checks`). The sanctioned classes are what a probe IS: print, no +companion test, import-time side effect, raw `JSON.parse`, plus the +entry-script family whose own rationale exempts bin/cli files — argv +boundary, env read, unjustified cast, wall clock, magic number. Product +code outside `scratch/` keeps every one of them. + +Two consequences worth knowing: +- **The rescan reports introduced-only.** A whole-file scan still runs, but a + finding your session did not introduce is spooled, not printed. +- **Suite failures are not multiplied into per-file regressions.** A cycle + reddened only by a whole-suite failure is excluded from the green→red Stop + list; the unresolved `test-suite` outcome remains one check-level signal + until a targeted test run supplies file-level evidence. +- **A repeat Stop prints only what is new**, plus one `R resolved, S unchanged + (suppressed)` line. Per-session state lives in + `.interlinked/.stop-digest-state.json` (daemon bookkeeping — do not hand-edit). + +Activating a change to any of this needs `npm run build && interlinked harness +restart`: the daemon serves the build it started with. diff --git a/skills/interlinked-observability/references/capture-notes.md b/skills/interlinked-observability/references/capture-notes.md new file mode 100644 index 000000000..a48aa7cf0 --- /dev/null +++ b/skills/interlinked-observability/references/capture-notes.md @@ -0,0 +1,81 @@ +# interlinked-observability: capture notes + +Reference for [SKILL.md](../SKILL.md). Read it when a capture record or receipt field needs explanation. + +For internal claim-verification research, `node --import tsx scripts/internal/jev.mjs claims + --receipt-shadow ` adds default-off, log-only +deterministic comparisons to `.interlinked/claim-receipt-shadow.jsonl`. It does not run from +public Stop hooks or change Jev's decision. Links explicitly bind a claim to receipt/source/ +selection identities; missing or duplicate links remain not assessable. Only four narrow +receipt predicates are supported; see `docs/internal/jev.md`. A missing Jev score is unmeasured, +including short claims omitted by the legacy splitter. Separate replay statistics from live +usage, and inspect `receiptShadowFailures()` before treating an absent row as no claim. + +Ordinary hook delivery omits deep-audit style/design messages after one review +notice, while raw check results remain intact. This applies to synchronous responses +and the late-warning spool; their deduplication state is separate so preparing a +fallback cannot consume the synchronous notice. Repeated guard-scope advice is +deduplicated per session. Compare native delivered feedback separately from raw +finding counts; fewer delivered warnings do not imply fewer findings or clean code. +Interactive ChangeSet batches defer project-wide Gitleaks to explicit verification +or background recovery, with an explicit non-verdict. Confirm actual tool timings +and completion before claiming latency or security-coverage improvements. + +For Claude compiler batching, distinguish tool calls, scheduled checks, compiler +executions and delivered diagnostics. `hook-observation.v1` rows record scheduled +TypeScript work; batch results and timing are in `check-results.jsonl`. Pending work +survives in `.interlinked/compiler-batches/`. Coverage observations are retained even +when repeated model warnings are suppressed. Silence does not mean coverage is complete. +Measure a repeated-edit problem by assistant-message/tool-use identity and timestamps: +an edit emitted before an earlier hook's feedback cannot be attributed to that feedback. + +`check-executions.jsonl` also carries `hook-observation.v1`: scheduled external overlays, +normal complexity/token measurements, and shadow trajectory observations. These are telemetry, +not check passes or confirmed model delivery. `check-results.jsonl` retains full findings, +including `novelty`, `findingCount` and server-computed `writeAttribution` where available. +Newly observed means report novelty, not proven causation. Repeated advisories may be hidden +from model feedback while remaining in each call's records; hidden findings prevent all-clean. + +Own-barrel pre-write analysis can retain advisory `hook-observation.v1` rows with +`measurementState: "unavailable"` and `findingCount: 0`. The zero records no defect +finding from that unavailable evidence; it is not a passing graph verdict. Reasons +include missing or unresolved modules and the runtime traversal budget. These rows +do not create a blocking gate, certify delivery or clear pending check obligations. +Dry-run evaluation does not persist them. + +Use `evals/compare-builds.mjs` for paired explicit-build agent pilots. It retains fixtures, +native streams, usage categories, settings, daemon status, final diffs and evaluator-owned +functional checks. Activity warning counts are ledger metrics. Missing native delivery/token +data remains unknown; do not infer billed savings from shorter commands or compressed rows. + +`repeated_implementation` check results retain each current AST-matched group with +a `group=` detail identity, even when unchanged agent-facing warnings are +suppressed. Compare these identities rather than line numbers across formatting edits. +Post-tool suppression is session-local and resets with the daemon; Stop uses its +existing digest state. NOT CHECKED means missing analysis, not zero clones. Findings +are review candidates, not proven defects or evidence that an extraction helped. + + +`hook-reentry.jsonl` records Stop/SubagentStop re-entry suppressed before daemon evaluation. +Translation receipts now include advisory context representation as well as denials and +rewrites. Operator-only Stop diagnostics are not model-context delivery. Audit native +completion messages by unique ID; streaming chunks and daemon Stop counts are insufficient +to count continuations. + +Shared hook-check receipts may include `scopes` with a batch ID, check name, configuration +hash and captured request-file identities. `kind: request-inputs` is historical execution +evidence, not a complete runtime/dependency closure or reusable cache key. Nonempty +`unavailable` preserves partial evidence and leaves the obligation pending. Keep those states +separate from clean results when comparing recovered check counts or latency. + +`source-scan-scope.v1` capture rows record dependency/runtime exclusions from authored-source +quality, with `excluded_not_checked` status. `source-scan-security.v1` retains the separate +security findings and request-input evidence. Neither row authenticates a writer or certifies +runtime-input closure. Repeated unavailable-check messages are deduplicated for delivery by +session, project, configuration and reason; raw check results retain missingness. Counts in +the agent channel therefore differ intentionally from raw deferral counts. + +Cowork plugin receipts use a separate metadata-only schema and explicit exports. +Use **interlinked-cowork** and `interlinked cowork report --effects ` +for native conformance. An intended hook decision is not execution/prevention proof; +these receipts do not provide complete transcripts or authenticated writer attribution. diff --git a/skills/interlinked-observability/references/data-commands.md b/skills/interlinked-observability/references/data-commands.md new file mode 100644 index 000000000..de0b167ad --- /dev/null +++ b/skills/interlinked-observability/references/data-commands.md @@ -0,0 +1,106 @@ +# interlinked-observability: data command detail + +Reference for [SKILL.md](../SKILL.md). Read it when a `data` command result needs its budgets, coverage or retention rules. + +Direct scans default to 32 MiB expanded input and 25,000 physical lines, taking complete-line +prefixes of the most recently modified files. They include retained gzip archives and numeric +rotations. A narrow time filter does not jump to a newer portion of a large file. Inspect +`coverage.complete` and `scope`; increase explicit budgets or choose an existing index when +necessary. `--raw` returns the observed source text with its hash. Scan/lab IDs are separate +from production `data show` IDs. File filters for `data scan` use project-relative paths. +Use `--full-text` when omission by the bounded index projection matters: it searches all +decoded string values inside each readable complete record, excluding JSON field names. +Byte/line budgets and oversized-record limits still apply. Without this flag, a complete scan +with `coverage.truncated > 0` does not establish that a term is absent from original payloads. + +Use `interlinked data catalog` to discover registered and unknown JSONL files recursively, +including numeric rotations and gzip archives. `data health` distinguishes observed writes, +unsupported/disabled/idle producers, failures, and unmeasured populated files. Its receipt +window is bounded; a quiet event-driven feed is not automatically broken. `doctor` reports +capture failures and unmeasured coverage. + +```bash +interlinked data index --max-mb 256 --max-records 250000 --json +interlinked data status --json +interlinked data search "compiler import" --since 7d --json +interlinked data search --source check-results --session SESSION --json +interlinked data show RECORD_ID +interlinked data investigate --session SESSION --json +interlinked data investigate --file src/app.ts --json +interlinked data checks --check typescript --json +interlinked data usage --session SESSION --json +interlinked data suggestions --json +interlinked data recurrence-inventory --json +``` + +Indexing is incremental and bounded: repeat until the retained backlog is covered. `--rebuild` +clears only derived tables. SQLite/FTS5 loads lazily; use a Node runtime with built-in SQLite +(Node 22.13+ avoids needing the earlier experimental flag). Search includes retained archives; +`--no-archives` restricts it to live files. `--fts` opts into FTS5 query grammar. Structured +filters include source/category/session/actor/provider/model/file/check/call/kind/decision/origin. +Catalog source names and categories stay consistent between direct scans and indexed search, +including sources stored under nested paths such as `logs/latency.jsonl`. +Unknown event timestamps are excluded by time bounds. The older `query` command scans a +bounded physical tail of one file and reports its scope; it does not promise archive coverage. + +Each indexed answer carries a record ID; `data show` retrieves the original JSON and verifies +its SHA-256. Projection text/field traversal is bounded, and oversized or malformed rows are +reported without deleting their raw bytes. Check `data status` for freshness and parse failures. +Invalid UTF-8 is malformed evidence: scans and new imports report it and continue to later +complete records; `data show` refuses to verify it. A valid replacement character (`�`) in +UTF-8 is ordinary text. For indexes created before strict UTF-8 validation, use an explicit +`data index --rebuild` to remove earlier lossy projections; historical raw bytes remain intact. +Exact duplicate raw records within one logical source share an indexed record but retain all +physical locations. Cross-stream observations are not automatically independent executions. + +`data sessions/files/checks/usage/schema/suggestions` expose evidence aggregates. `investigate` +correlates exact provider/session/actor/call identities and labels missing phases; a file filter +also strictly folds the obligations ledger. A block count is not a prevented-defect estimate. +Suggestion `shown` means selected for presentation, not acknowledged; later absence is an +observation, not proof of a fix. Usage has unknown values and no invented prices; never add +overlapping timeline and costs totals. Recurrence inventory is separate from incident counts. +Usage deduplication chooses a provider-message representative within the query's retained +scope, so superseded source generations and excluded archives do not hide a retained copy. +Aggregate limits bound returned groups, not necessarily database work; narrow supported +filters first. `schema` is a source-wide observed field census: only `--source` and `--limit` +affect its scope, even though its CLI accepts the shared filter flags. + +`data maintain` previews retention. `data maintain --execute --compact --no-index` losslessly +rotates eligible collection/timeline history without opening or creating SQLite. Add `--index` +to explicitly import a bounded batch and translate existing evidence pointers during rotation. +Without either index flag, indexing follows `auto_index`. It never deletes evidence or +automatically compacts activity/state ledgers/corpora. +Activity still requires the existing cursor-aware `compact` workflow. After an external +compactor, rerun `data index` to discover replacement files and archives. + +Preserve evidence indefinitely: do not delete, expire, truncate, sample away, or rewrite raw +records, archives, manifests, or integrity checkpoints to reclaim space or hide bad rows. +Lossless rotation changes physical placement while retaining every record. A smaller live +file is not less retained history. Search archives with `data search`; older live-file readers +cannot answer questions about the complete retained history. `--rebuild` replaces derived +index tables only and is not a routine retention operation. Index storage can exceed raw-log +storage substantially; the per-pass import budget is not a cap on total index size. + +Rotation prepares the bulk retained suffix before acquiring the append lock. Identity is +rechecked under the lock, and only a bounded catch-up plus the atomic rename exclude writers. +An excessive append burst or competing replacement aborts safely for retry. Maintenance +operation failures are recorded in capture health. + +`data configure --auto-index on` opts into bounded SessionEnd background indexing; +`--auto-compact on` independently enables collection/timeline rotation. Both default off; +enabling rotation alone does not enable or run the SQLite importer. +Defaults are 256 MiB/250,000 records per pass, a 256 MiB rotation threshold, and a 64 MiB live +tail. Configure via `--index-mb`, `--index-records`, `--compact-at-mb`, `--keep-live-mb`. +Settings live in `data.config.json` under the resolved data directory; capture itself continues +independently. Load new daemon capture code through the normal build/reload workflow. +SessionEnd is an actual provider lifecycle event, not each assistant Stop. This automation +does not continuously watch files or refresh a long-running active session on a timer. Run an +explicit index pass when recent evidence matters; a deferred background job is not freshness. + +`data audit diagnose` locates the first historical failure by physical source/offset and does +not infer tampering intent. Its source line and byte offset refer to the physical record even +when archived blank lines are omitted from the verifier's combined line count. +After investigation, `data audit checkpoint --reason TEXT` records +an explicit payload-verified live observation boundary. `data audit verify --checkpoint ID` +checks subsequent retained evidence, including after rotation. The historical verdict stays +unchanged; checkpoints never rewrite or reset the old chain. diff --git a/skills/interlinked-observability/references/viz.md b/skills/interlinked-observability/references/viz.md new file mode 100644 index 000000000..fabaff545 --- /dev/null +++ b/skills/interlinked-observability/references/viz.md @@ -0,0 +1,47 @@ +# interlinked-observability: viz lenses + +Reference for [SKILL.md](../SKILL.md). Read it to set up or read an `interlinked viz` lens. + +Six lenses, each fed by its own SSE route: + +| Lens | Route | Source | Shows | +|---|---|---|---| +| FILES | `/api/graph` + `/api/stream` | project graph + `activity.jsonl` | one dot per source file, one line per import, dot size = how many files depend on it; a touched file pulses in the colour of the agent that touched it | +| GATES | `/api/checks` | `check-results.jsonl` | one frame per tool call: which checks ran, which fired, allowed or blocked, `[proven]`/`[heuristic]` | +| AGENTS | `/api/agents` | `activity.jsonl` (folded) | one lane per agent session working in this repo, indented lanes for subagents it spawned: runner, model, calls/edits/blocks/warns, current tool + file, live-vs-idle | +| TESTS | `/api/tests` | `test-events.jsonl` | every test case in the order the runner finished it; pass/fail/skip, slow cases outlined, failure messages | +| MUTANTS | `/api/mutants` | `mutation-manifest.json` | every mutant, survivors first; live kill-rate; a tile flashes when its status flips | +| DRIFT | — | — | not built yet (standby pane) | + +The AGENTS lens needs no producer: attributed activity rows carry `agent`, `session`, +`subagent_id`, `parent_agent`, and `model`, so presence is a fold over the stream the dashboard already tails +(`src/lib/viz/agent-roster.ts`, hosted at `/api/agents`). Each actor gets a stable hue from its +id, and that hue is reused for its ticker rows and its file pulses — with two sessions running, +colour alone answers "who did that". A subagent gets its OWN lane keyed under its parent, so a +session's own edits are never conflated with its subagents'. When a runner names the parent by +thread/session id, the roster resolves that id through the root lane's session before linking the +child. Lanes dim to idle after 2 minutes of silence rather than disappearing. + +The TESTS lens needs a producer. Any repo using vitest adds one line: + +```ts +// vitest.config.ts +reporters: ["default", "interlinked-cli/viz-reporter"] +``` + +Gating it behind an env var is the recommended setup, so a normal `vitest run` stays +byte-identical and only an explicit opt-in emits the feed — that is how interlinked-cli's own +`vitest.config.ts` wires it: `INTERLINKED_VIZ=1 npx vitest run`. Any equivalent conditional +works; nothing about the lens requires that variable name. The feed schema +(`.interlinked/test-events.jsonl`) is runner-agnostic — `{kind: run_start|file_start|test|run_end, +run_id, lane?, file?, name?, status?, ms?, error?}` — so a pytest/cargo adapter writes the same lines +and the lens renders unchanged. Every feed degrades to an honest empty state when its file is +absent; nothing about the dashboard is repo-specific. + +The Interlinked CLI e2e config always registers the reporter; `test:e2e` also +sets `INTERLINKED_VIZ=1`. The TESTS lens groups files by `unit`, `integration`, +`e2e`, `base` or `unknown` lane. A bare Vitest run is `base`; old rows without +a lane remain `unknown`. Repository test rows are run evidence. Fixture +ledgers are assertion subjects and do not establish which coding session ran +the tests. The Stop nudge attributes e2e invocations through that session's +observed Bash commands instead. diff --git a/skills/interlinked-quality-gates/SKILL.md b/skills/interlinked-quality-gates/SKILL.md index 470dbeedb..40aef993d 100644 --- a/skills/interlinked-quality-gates/SKILL.md +++ b/skills/interlinked-quality-gates/SKILL.md @@ -1,160 +1,17 @@ --- name: interlinked-quality-gates -description: "Configure and respond to Interlinked's metric ratchets: line-count, per-function canonical-token count, cyclomatic complexity, coverage, CRAP, baseline integrity, the report-based mutation-score ratchet, the live per-edit mutation survivor gate, and experimental protocol-v3 durable mutation jobs. Load this for a quality-gate block; `caps`, `coverage`, `mutation`, `mutation cloud`, automatic debt obligations, manual `debt markers`, `metrics`, or `adopt`; a lowered-baseline refusal; choosing mutation cadence/scope/strictness; configuring `mutation_gate` or `per_edit_mutation`; connecting/sharding a mutation runner; operating the durable mutation journal; or interpreting `[interlinked:mutation]` and `[mutation:not-measured]`. Water-lines only tighten: meet the bar rather than lowering the baseline." +description: "Respond to and configure Interlinked metric ratchets: line count, function tokens, cyclomatic complexity, coverage, CRAP, baseline integrity, mutation-score ratchet, per-edit survivor gate and protocol-v3 durable mutation jobs. Load for a quality-gate block or lowered-baseline refusal; `caps`, `coverage`, `mutation`, `mutation cloud`, debt obligations, `debt markers`, `metrics`, `adopt`; mutation cadence, scope or strictness; `mutation_gate` or `per_edit_mutation`; mutation runner shards or journal; `[interlinked:mutation]` or `[mutation:not-measured]`. Water-lines only tighten: meet the bar." --- # interlinked-quality-gates — the metric ratchets -The source-only mutation research helpers support differential fuzzing, test-side -mutant enumeration and test-double candidates. They do not enable a new automatic -gate. Differential fuzzing calls original and mutated functions in-process; use it -only for suitable side-effect-free targets. A minimized divergence is a candidate -regression input, while no divergence is bounded search evidence, not equivalence. -Missing optional dependencies and unsupported targets remain explicitly unavailable. - -## Experimental decision-model measurements - -`metrics decisions relations` implements shared-invariant membership, nonexclusive -roles, pair/group compatibility, directional coupling and paired evidence comparison. -Use `prepare --revision REF --history-tip REF --since ISO --until ISO --engines FILE`, -then `freeze PLAN --output BUNDLE`, `assess BUNDLE`, and `export RUN`. The registry -lives in version-controlled `semantic-relations/invariants.json` and `scenarios.json`; -`--exploratory` explicitly permits an uncommitted registry. Runtime artifacts and -claim events share `.interlinked/semantic-graph/`, not the v1 decision-metrics store. -Groups have a dedicated v2 population and must not be joined to description claims. -For two revisions, `compare BEFORE --after AFTER --output-plan PLAN` creates a plan -consumed by `freeze` and `assess`; report with `compare --assessment-run PAIRED_RUN`. -Use the same pre-change history tip/window on both sides. Missing participants, -ambiguous identity, changed measurement conditions and unresolved sides remain -non-comparable. A changed probability or categorical answer is not a repair verdict. -Explicit D/J/H engine records pin backend, model identity, budgets and uncertainty -band; the default v1 backend remains Ollama. H is an independent Haiku 5.5 low arm, -with empty tools/MCP, safe mode, no persistence and a required canary. Preserve -unavailable arms; never replace them silently. No downloads are automatic. -`labels` creates blind Astra review inputs. `audit --labels FILE` separates model -reference agreement from fixture evidence, reports candidate recall first, and uses -one-sided 95% exact Clopper–Pearson bounds only when case IDs are independent. -No human review is required by this workflow. Model labels are not independent -ground truth, and these exploratory reports do not qualify or enable automatic alerts. -Retain frozen inputs and results locally under `semantic-relations/studies/`; -raw outputs are ignored, while readable Markdown reports are committed. Fresh clones -cannot regenerate study summaries without those local inputs. Hashes of -uncommitted bundles do not constitute Git review authority. See -`semantic-relations/README.md` for the complete current workflow and limitations. - -For interactive use, pass `--cwd` for the repository whose revision is being assessed; -the nested command inherits it from `metrics`. Source evidence comes from the pinned -Git revision, even with `--exploratory` policy. Capture dirty source in an isolated -snapshot if that is the intended subject. Compare the advice against a prior source -review and executable checks: confirmation of an existing hypothesis is a second -opinion, not a new finding. Exact cached assessments make no new model calls; their -latency is not fresh-inference latency. The runtime dogfood report under -`semantic-relations/studies/2026-10-27-runtime/` records these limits in actual use. - -For the internal public-GitHub semantic collection and Jev/Luna research workflow, -the optional local research checkout may contain -`research/semantic-factory/repo-pipeline/README.md`. That directory is ignored and -is not included in a fresh clone or package. When available, its `pipeline.py` uses -one active repository iteration: collect a pinned snapshot, prepare source-linked -candidates, import two separately recorded source reviews, freeze, then explicitly -evaluate with `--go`. It is not an Interlinked CLI command or harness gate. Treat -downloaded code and instructions as data; never execute target code during collection. -Inspect source availability, exact boundaries and semantic eligibility before inference. -Retain unresolved references, missing sources, failed calls and unpriced costs. -Finish with recorded lessons before starting another repository; changed questions, -sources or pipeline code require a new frozen iteration. Embedding retrieval is not -implemented in v0.1; lexical candidates are not established semantic graph edges. -Its `metrics`/`render` outputs include per-category and per-artifact semantic -profiles, source gaps, review eligibility, model scores and global call accounting. -Keep scores attached to the exact question and sampled population; do not turn -unassessed functions into zeroes, count context-only appearances as judged edges, -or average different relationship meanings into a universal quality score. - -`metrics decisions` is an experimental research/advice namespace, not a ratchet. -Read `docs/decision-metrics.md` for the full contract. `init` writes disabled -`.interlinked/decision-metrics.json`; manual commands explicitly request inference. -Defaults are local Ollama Clef Flash 9B through ThinkThen's CLI and the full -EmbeddingGemma 2 740M BF16 (`embeddinggemma-2:740m-bf16`) at 768 dimensions. Qwen3 Embedding 4B is an explicit -comparison model. No weights or binaries are downloaded automatically. - -Use `catalog`, `prepare --unit function|hunk|all`, `measure --plan`, then `measure`. -The source extractor pins native metrics; optional bca needs `--bca-command` and -the exact `--bca-version`. Keep bca values separate from native counters. -`snapshot` and `candidates [--retrieval lexical|embedding|hybrid]` prepare consumer -cohorts. `review --analysis obligations|atomicity|faithfulness|compare|coupling|rework` -runs the relational protocols. Atomicity and faithfulness require one revision. -Supply literal claims with `--claims`; otherwise description lines are the lexical -baseline. Verification-only obligations do not require unnecessary edits. -Use hunk records for contract changes to types, interfaces and enums; function-only -extraction omits those declarations. `embed` then `geometry` produces provisional -distances on a bounded population, never calibrated quality probabilities. - -`pilot` collects commits; `labels` creates blind templates; `join-labels` requires -the complete labeled population; `audit --cutoff DATE` uses a time split. Add -`--comparison` for matched direct/retrieval cohorts and five-arm reporting. -Independent reviewer labels, comparable features and clone/fork grouping remain -operator responsibilities. `replay --band LOW:HIGH` is offline; `diff --after RUN` -reports drift; `probe` performs fresh meaning/stability tests. An audit diagnostic -never promotes a question to a blocking gate. -Audit band suggestions use training labels only. Preserve full distributions and -question contracts when joining labels; mixed rubric versions are rejected. - -Preserve all five states: answered, insufficient evidence, abstained, failed and -unassessed. CLI exits are 0 completed/plan, 2 usage/configuration, 3 uncertain or -insufficient, 4 failed runtime/all failed, 6 partial failure and 7 unassessed. -Raw score distributions and exact wire exchanges stay in the private local run -store. `--fresh` preserves earlier observations. Model probabilities are marked -unvalidated on code; do not describe their sums as expected defect counts. - -Automatic advice requires both `enabled` and `hook.enabled`, permits only -function contracts, and uses exact observed source hashes for pre-edit baselines. -Missing baselines and short deadlines produce explicit missing assessments. -Keep existing deterministic coverage, mutation and e2e obligations in force. - -Edit-time function tokens, cyclomatic complexity and cognitive complexity now -advise by default. Shared `.interlinked/config.json` can explicitly select -`harness.edit_metrics.mode: "enforced"` for the existing hard cap behavior. -The following cap-block and grandfather-ledger instructions apply in that mode; -measurements, protected baselines, explicit verification and behavioral test gates -remain intact. Do not add concepts merely to lower a structural count. - -Physical per-file size is now advisory. The `lines` setting remains a review -preference and historical measurements remain available; it never blocks source -edits, native cold fallback, verification or commits solely for size. Do not remove -braces, join lines, invent temporary variables, or split modules merely to satisfy -that number. This is a decomposition prompt, not an LLM context-token budget. -Guard ownership belongs to predict–reveal–reconcile; see **interlinked-harness**. - -File-size and per-function checks share Write/Edit/MultiEdit and native patch projection. -Multi-file patches check every reconstructed target, and moves retain their source -before-state. Equivalent known effects face the same policy. Unknown reconstruction -is unmeasured, never a passing receipt. Arbitrary shell writes still require checking -their observed effects after execution. - -Behavioral execution and structural measurement have separate language coverage. Explicit -`tests suite` supports TS/JS, Python, Rust and Go; the new iterative diagnostic profiles -remain JS/TS and Python only. A passing runner is not evidence that new requirements have -tests. Exercise new public boundary/error/state-transition contracts as well as preserving -existing cases. Project-suite failures without a before result are not proven regressions. -No new verbosity or erosion hook gate is enabled by these diagnostics. - -Python test-first guidance recognizes `test_.py` and `_test.py`, including -root, package and separate test directories. Discovery refreshes when directories or -runner configuration change during a daemon session. These are naming hints, not proof -of coverage: inspect custom collection layouts before creating redundant tests. The -configured new-file policy applies to JS/TS and Python. Explicit -`test_first_mode: "enforce"` requires a companion even in an empty repository; -layout detection does not demote it. Create the first behavioral test before its -implementation. Pair debt can sequence later source/test edits once a test layout -exists; it cannot replace that first-test bootstrap. `"warn"` remains advisory. -A companion filename alone is not evidence of a failing or passing test. Python uses -`# interlinked-tdd: exempt` for the existing explicit exemption directive. This does not -establish equivalent pre-execution TDD enforcement for arbitrary Bash writes. - -The experimental Cowork portable plugin does not carry these repository baselines -or run coverage/mutation automatically. Load **interlinked-cowork** for explicit -host bridging and version checks. Its `cowork verify` external-tool subset is not -evidence that a coverage, mutation, CRAP or baseline ratchet passed. +For `metrics standards --profile dmmulroy-typescript`, see +[local standards measurements](references/standards.md). It retains all 35 pinned +guidance groups with separate syntax, detector, candidate and unknown coverage, +all-role denominators, source-driven units and explicit caller/context gaps. +Explicit metrics/standards surveys retain complete selected sources without implicit +body-size, path-count or Git-listing limits. See [metrics procedures](references/metrics.md) +for the separate foreground Python policy, runtime bounds, exclusions and unavailable inputs. Every quality metric is a **water-line** stored in a JSON file under `.interlinked/`. The gates enforce **"may only move in the tightening direction"**: coverage/mutation scores may only rise; @@ -177,94 +34,47 @@ test or lower complexity score does not prove complete correctness. Intentional changes need corresponding expectations; do not preserve a bug merely to keep a test green. Do not tailor implementations or test selection to hidden benchmark cases. +The experimental Cowork portable plugin does not carry these repository baselines +or run coverage/mutation automatically. Load **interlinked-cowork** for explicit +host bridging and version checks. Its `cowork verify` external-tool subset is not +evidence that a coverage, mutation, CRAP or baseline ratchet passed. + ## The gates you bump into at edit time -### Expression readability is advisory - -`interlinked metrics expressions [file-or-directory] --cwd --json` measures -JS/TS expressions with `interlinked-expression-v1`. It reports source hashes, UTF-16 -half-open spans, syntax tokens, callback counts/depth and literal-data classification. -Default preferences: tokens >60, callback depth >2, inline callbacks >=3, control-flow -depth >3; nested ternaries, multiline unbraced bodies and same-line sibling statements -also advise. Single-line guards are accepted by default. Generic brace advice defers -to a target's configured style tools; imported rules preserve their explicit policy. -Literal-only tables are excluded from the token warning. Test registration calls are -excluded as containers; computations inside their bodies are still inspected. - -Optional `.interlinked/readability.json` is `{ "version": 1, "limits": { -"expressionTokens": 60, "callbackDepth": 2, "callbackCount": 3, -"controlFlowDepth": 3 } }`. Omitted limits keep defaults; unknown fields and invalid -integers are unavailable evidence. The nearest ancestor policy applies, stopping at -the git root. These are calibrated preferences, not protected complexity baselines. -Keep useful domain abstractions and explicit loops even when their branch count rises. -Naming a predicate does not fix discarded provenance or a false success claim. - -The command exits 0 for measured inventories, including findings, and 2 for unavailable, -unsupported or empty scope. Directory completeness refers only to listed discovered -JS/TS files. Missing TypeScript or recovery syntax is NOT CHECKED. Hook advice compares -whole expressions against captured pre-edit content, so a change below an unchanged -initializer line is visible; moving or formatting existing debt does not reintroduce it. -Identity uses owner/label and metric-value allowances, not semantic equivalence. Without -a usable before-state the current inventory cannot prove a regression. - -Use **interlinked-verify** for `verify --all-checks` and explicit formatter/linter gates. -Do not turn these advisory checks into heuristic `pre_block` errors or lower protected -function/coverage baselines to accommodate formatting. - -### E2E coverage water-line - -In the Interlinked CLI repository, run `npm run build:e2e`, then -`npm run test:e2e:coverage`, then -`node dist/index.js coverage check --lane e2e --strict --require-measured`. -`interlinked coverage status` shows quality coverage lanes; it is distinct from -`interlinked harness coverage status`, which describes filesystem observations. - -The e2e lane reads only `coverage-e2e/coverage-summary.json` by default. Its -adjacent `run.json` must bind a passing child-process run to the current build, -test inputs, inventory and report. Missing, partial, stale or malformed evidence -fails. The full inventory includes zeroes for unexecuted code. Generated-hook -strings are checked behaviorally and excluded from line metrics. - -Create an absent `.interlinked/coverage-e2e-baseline.json` only with -`coverage check --lane e2e --init-baseline`. It refuses an existing file. -`--update-baseline` saves only after every check passes; failure preserves the -baseline bytes. All four percentages, touched-file share and weighted line -coverage have zero tolerance. `--changed-files` conflicts with `--lane e2e`. -`coverage baseline --lane e2e` displays the baseline, including line counts. - -Deleted code carries no obligation; surviving files retain their floors. -A deletion plus a new boundary path is UNRESOLVED until the author records -`coverage move --lane e2e ` or `coverage retire --lane e2e `. -Retire refuses surviving executable boundaries. Moves preserve entries; use -repeatable `--map A=B --map B=C` for atomic chains. A destination must meet its -transferred, pre-write and base floors. If a move cannot meet them, collect -coverage and use `coverage check --lane e2e --map A=B --map B=C --update-baseline` -to apply mapping and measured values in one locked transaction. - -Local comparisons use HEAD. CI supplies `--base `: the PR merge base or -the push's previous revision. Missing history, new-ref zero SHAs and force pushes -fail closed. `INTERLINKED_PRE_PUSH_SKIP_E2E=1` records an explicit skipped e2e -row; CI still runs. Intent and effect guards also check CLI writes; they judge -values and tree evidence without trusting a writer's identity. - -Behavioral contracts complement metric gates: `tests contracts inspect|run` separates -expectation provenance, configured acceptance, execution failures and unavailable evidence. -Exact example/expectation conflicts require reconciliation; a citation without an exact -observation binding remains a semantic review obligation. Passing agent-authored tests, -coverage or mutation scores cannot certify expected answers. `tests contracts run ---previous ` retains old expectations against current code; legitimate behavior -changes remain possible through explicit requirement/rationale review. This is not a new -heuristic edit block. Use **interlinked-verify** for schema, runner budgets and ownership. - -Execution evidence is available through `interlinked data checks` and `data investigate`. -`check-results.jsonl` retains per-call findings and reported execution coverage; -`check-executions.jsonl` records each configured quality-loop entry, including disabled, -skipped, deferred, error, and completed states. A completed check with no reported findings -is not necessarily a clean whole-file verdict because diff-aware filtering applies. Other -check pipelines have separate coverage. Capture does not change any gate decision. -These run before an edit lands. The local metric ratchets use **delta semantics**: holding or -reducing existing debt is allowed. Per-edit mutation is separately configurable as off, warn, -or block. +Edit-time function tokens, cyclomatic complexity and cognitive complexity now +advise by default. Shared `.interlinked/config.json` can explicitly select +`harness.edit_metrics.mode: "enforced"` for the existing hard cap behavior. +The following cap-block and grandfather-ledger instructions apply in that mode; +measurements, protected baselines, explicit verification and behavioral test gates +remain intact. Do not add concepts merely to lower a structural count. + +Per-metric settings in the check policy `metrics` map now control `cyclomatic`, +`cognitive`, and `function-tokens`: report, warn, block or off, with targets and +file/role scopes. Missing entries inherit the legacy posture. Blocking targets may +only tighten canonical caps, and adopted policy is protected against agent weakening. +See [metric policies](references/metric-policies.md) for edit configuration and +unsupported metric IDs. `metrics policies export|inspect|evaluate` shares versioned +data-only references to installed metrics and detectors. Its report/warn/off +assessment retains all 23 project readings and explicit evidence gaps. See +[policy profiles](references/policy-profiles.md) for the schema, aggregate-scope +limits and reviewable structural proposals. + +Physical per-file size is now advisory. The `lines` setting remains a review +preference and historical measurements remain available; it never blocks source +edits, native cold fallback, verification or commits solely for size. Do not remove +braces, join lines, invent temporary variables, or split modules merely to satisfy +that number. This is a decomposition prompt, not an LLM context-token budget. +Guard ownership belongs to predict–reveal–reconcile; see **interlinked-harness**. +The `file.lines` metric-policy entry controls advice targets, path/role scope and +report/warn/off disposition in the daemon and native cold pre-write path. Standalone +generated cold hooks emit NOT MEASURED for physical-line settings. The policy +reference records phase coverage and the project AST line-count convention. + +File-size and per-function checks share Write/Edit/MultiEdit and native patch projection. +Multi-file patches check every reconstructed target, and moves retain their source +before-state. Equivalent known effects face the same policy. Unknown reconstruction +is unmeasured, never a passing receipt. Arbitrary shell writes still require checking +their observed effects after execution. | Gate | Blocks when | Threshold | Correct response | |---|---|---|---| @@ -286,7 +96,7 @@ bricked and coverage only moves toward the goal. The separate `min_coverage` hard floor blocks outright and, once set, only rises (baseline-integrity gate). | **CRAP** | a touched function is both complex AND under-covered | shipped **30**; this repo overrides to **25**, default on | Decompose OR add coverage (both lower CRAP) | | **Per-edit mutation** | a measured edit adds a changed-region survivor/uncovered site, makes affected tests red, or exceeds the site limit | default **off**; site limit **50**; `mode: block\|warn\|off` | Strengthen the test, fix/remove the source behavior, or split an oversized behavioral change | -| **Baseline-integrity** | a Write/Edit *loosens* any `.interlinked/` water-line | per-file direction | Meet the bar; don't edit the baseline | +| **Baseline-integrity** | a Write/Edit *loosens* any `.interlinked/` water-line (the name matches in any letter case), or a `git commit` deletes one (`git rm`, `git mv`, `--pathspec-from-file` counts as the whole tree) | per-file direction | Meet the bar; don't edit, move or delete the baseline | **Modes ladder the philosophy-dependent gates (2026-08-17).** `interlinked mode` writes gate posture into `guard-rules.json` alongside its check-policy overrides: @@ -297,33 +107,6 @@ session-end nudges off. Findings still surface as warnings in lenient; security rails and every tighten-only ratchet ignore the mode. Hand edits to `guard-rules.json` win until the mode is re-applied. -**Refactor-readiness additions (plan 25, 2026-08-17).** -- `characterize_before_touch` (`structural_checks.characterize_mode`): editing - a file on the untested list asks for a characterization test FIRST — capture - today's behavior with exact assertions, then change it. Same - `// interlinked-tdd: exempt` escape as the new-file gate. -- Ratchet-family dimensions: `seam_ratchet` tracks added ambient clock/random/env - reads. `assertion_strength_ratchet` is heuristic PostToolUse advice for test files, - never a block: it flags introduced broad matchers without introduced exact checks. - JS/TS comparison uses complete assertion calls, ignoring comments, strings, - formatting, moves, and existing calls; Python retains a stripped-line heuristic. - Missing raw pre-edit content or unusable JS/TS syntax yields no assertion advice. - Exact undefined/null, call-count, and zero-call checks are legitimate contracts. - Broad membership/type checks can also be appropriate; assess the tested behavior - before changing them. A matcher classification does not prove mutation coverage - or require literal-only expected values. -- `new_import_cycle` (structural, default warn): fires the moment an edit - closes a module cycle that did not exist before. -- Advisory portability family: `dynamic_code_execution`, - `builtin_prototype_mutation`, `float_equality_comparison`, plus - `test_contract_annotation` (mutation-directed files only) and - `unvalidated_input_boundary`. -- `per_edit_mutation.max_test_scope` (default 150) is an engine budget. - `per_edit_coverage.drop_epsilon` is a tighten-only water-line: values above the - built-in 0.005 are ignored with a warning unless an operator intentionally resets - it in the daemon environment. Daemon timings are separate implementation budgets. - Cognitive and cyclomatic have no sub-cap slew rule. - **File size** — three advisory surfaces: PreToolUse growth advice, `large_files` under `verify --all-checks`, and a `[interlinked:file-size]` PostToolUse nudge. None refuses edits. Historical baselines and measurements remain intact. @@ -381,76 +164,15 @@ then decides: red-bar (default on) → uncovered-added-line → per-file coverag `coverage-edit-baseline.json` → `min_coverage` floor → CRAP (default on). With default `debt_mode:true`, the first uncovered or red result opens a pair-scoped debt and the edit lands; keep working in that source/test pair until it is covered and green. The commit gate remains the -ground-truth backstop. - -JS/TS can select affected tests from its supported dependency evidence. Python currently -uses the bounded full-suite route: a companion filename or an empty JS graph cannot prove -a complete Python test selection. Over-budget work retains the existing deferral policy. -Python suite and coverage paths share interpreter selection: explicit adapter configuration, -active `VIRTUAL_ENV`, project `.venv`/`venv`, then the platform Python. A selected but broken -environment is unavailable, with no silent fallback. Overlays execute in the staged tree -using the original project's interpreter; recognized environment layouts are linked rather -than copied, with proposed writes kept from mutating the original environment. -If observed imports resolve to original project source outside the staged tree, the run -is unmeasured for that edit, even when those cases pass or fail. This detects common editable -install mistakes; it does not remap editable installs or certify all subprocess/data inputs. - -Default pytest execution records fresh structured case outcomes. Missing, empty, skipped-only -or incomplete execution never earns a green verdict or a clean baseline. Observed assertion, -fixture or teardown failures remain red even if coverage is missing or collection is incomplete; -the configured failure/debt policy still applies. Custom Python command overrides retain their -argv but are unmeasured for red/green without structured evidence. Default Python coverage -runs own separate JSON report directories and `COVERAGE_FILE` databases, cleaned after parsing; -they preserve project cwd/configuration and do not clear a caller's existing report/database. -Custom command overrides keep their existing report-path contract and are not qualified for -concurrent report isolation. Reusable dependency-aware indexing and live mutation still lack -parity. Do not describe the language as fully qualified from a runner pass. - -Python edit/commit CRAP now uses coverage.py's native function-region executable lines, -matched to Radon by declaration line and function name. Nested bodies do not contribute to -their enclosing function's coverage; excluded lines and branch percentages do not inflate -function line coverage. Reports must include native regions with `start_line` (introduced in -coverage.py 7.13.1). Older/malformed reports, ambiguous or unmatched functions, and functions -with no measured executable lines produce explicit missingness, not inferred coverage or -invocation counts. A wholly excluded function is unmeasured for CRAP. Missing attribution -cannot earn a clean edit baseline or discharge commit obligations while CRAP is enabled; -known coverage violations still apply. Unavailable complexity analysis also keeps commit -obligations open. These changes qualify the edit/commit paths, not every metrics/report surface. -Active distributed pytest execution is explicitly unmeasured until worker collection and -runtime identity are qualified; installing xdist alone does not make a serial run unsupported. - -Vitest coverage include/exclude edits block only when a concrete path example is -provably included by HEAD and omitted by the proposed combined scope. These -examples describe configured path membership, not an on-disk file census. -Supported comparisons cover positive relative globs with literal directories, -complete globstars, filename suffix wildcards and bounded comma brace alternatives. -Widened includes, narrowed exclusions and equivalent redundant patterns pass. -Negation, extglobs, character classes, unsupported wildcard placement, unknown -defaults, computed object keys, object spreads or unresolved overlaps allow with an explicit abstention warning: -review manually; an abstention makes no measured or clean claim. The shared -baseline bypass policy is unchanged. -Any computed property name in the config source causes abstention, including -literal-looking computed names and nested objects accessed through aliases or -factories. The gate does not evaluate JavaScript bindings to prove a computed -value irrelevant. Ordinary identifiers and quoted property names retain the -literal-array/glob comparison. When a coverage literal exists, any object spread -in the source also requires abstention: an enclosing or aliased spread may -replace the entire `test` or `coverage` object. A blocking comparison requires -unique plain `test.coverage` properties in a directly default-exported object, -optionally wrapped by the named `defineConfig` import from `vitest/config` or -`vite` (including an import alias). Duplicate keys, accessors, detached literals, -exported bindings, factories, arbitrary calls and CommonJS assignments are not -resolved by this guard; they warn when a coverage literal cannot be established -as the effective configuration. Parentheses and TypeScript assertions are transparent. +ground-truth backstop. Commit coverage takes the real checkout’s heavy-process lease and the shared host test slot. Vitest runs one instrumented worker. A busy host or interrupted run leaves coverage obligations open. Retry the full coverage suite against the same staged contents or resulting commit. **CRAP** = `cyclomatic² · (1 − coverage/100)³ + cyclomatic`, where coverage is a percentage. Full coverage reduces the score to cyclomatic, but low coverage can exceed the default threshold even at modest complexity (complexity 5 at 0% coverage scores 30). Treat complexity and coverage as independent levers; neither cap alone guarantees a safe CRAP score. -The per-function Istanbul reader scopes its cache to the normalized report path and -repository root, with mtime invalidation. A shared monorepo report can therefore be -read from a package root or workspace root without reusing the other root's file keys. +The Coverage row reports whether the source coverage report was available. With +coverage present, an empty hotspot list means there are no CRAP rows to display. **A function with no coverage reading gets no CRAP score at all.** When the report contains no measurement for a function — the source moved since the last coverage run, or the instrumenter @@ -501,9 +223,21 @@ Set the score floor in `.interlinked/check-policy.json` (team) or **Current contract:** `min_score` affects the comparison. `enabled` and `schedule` record policy intent but do not invoke or schedule Stryker; wire the command into the chosen CI/hook/cron surface yourself. The public command currently exposes `--report`, `--baseline`, -`--update-baseline`, and `--json`; `--baseline` is accepted but the handler still reads the -standard `.interlinked/mutation-baseline.json`. Internal `minScore`/`changedFiles` support is not -registered as public CLI flags. +`--update-baseline`, and `--json`. Omitted `--report` searches +`reports/mutation/mutation.json`, `reports/mutation/mutation-report.json` and +`.stryker-tmp/reports/mutation.json` in order. An explicit report selects that +path and empty path arguments fail visibly. + +`--baseline ` selects an existing comparison baseline. The default is +`.interlinked/mutation-baseline.json`. Explicit inputs require readable, +shape-checked mutation data. With `--update-baseline`, the selected file receives +the preserved-or-tightened water-lines. JSON output retains requested and resolved +paths, selection source and update status. Ordinary aliases update their resolved +baseline target under the same cross-process claim. Other protected runtime +control paths, including resolved aliases, fail before comparison or updates. +The root mutation policy supplies `min_score`. Alternate updates target the +selected comparison file. Internal `minScore`/`changedFiles` support remains +available to existing callers. The score is `killed / (killed + survived)`. Timeout, no-coverage, compile-error, and runtime-error mutants are excluded from that denominator; inspect the engine report instead of @@ -514,403 +248,39 @@ engine: Stryker's `mutate` paths/ranges, test runner and selected tests, mutator concurrency, timeouts, coverage analysis, and incremental mode. There is no Interlinked `light|standard|full` preset. -### Current dogfood and cloud boundary (2026-08-31) - -The local synchronous runner can be exercised without enabling the edit gate -or changing a manifest: - -```bash -interlinked mutation measure src/path/to/file.ts \ - --runner-url http://127.0.0.1:8790 --budget-ms 180000 -``` - -Omit `--record` for a read-only smoke test. A successful command proves that -the selected local runner completed this one measurement; it does not prove -that background delivery, cloud tenancy, or the live hook path is ready. - -An HTTP 200 alone is not a recordable measurement. `measure` and sweep label a -syntactically readable but incomplete response `PARTIAL — NOT RECORDED`, show -any parsed mutants/survivors for diagnosis, and withhold the raw report from the -write path. `--record` moves the manifest only when the response names the exact -target and source, reports engine exit 0, proves a green test run with more than -zero executed tests, loses zero mutant rows during parsing, and has a non-zero, -conclusive whole-file census. On an existing baseline, every prior mutant in an -unchanged symbol must also remain in that census. The record function repeats -these checks itself, so callers cannot bypass them by invoking the writer -directly. Missing, malformed, red, stale, truncated, timeout, and indeterminate -evidence remains visible but cannot establish or replace a baseline. - -A request that outlives the per-request timeout (default 300 s) is not run -again blindly. The client asks the runner for the retained report by job id -(`GET /job/`) on every later round and takes it when it lands; -the outcome then carries `request.resumed: true` and the command prints a NOTE. -Only when the runner holds nothing for that id does the client POST again, and -an accepted repeat is counted: `request.attempts: 2` and a WARNING that the file -was measured twice. Treat `attempts: 2` as two separate runs when comparing -survivor counts. - -Protocol v3 now has a digest-pinned evidence contract, authenticated local -adapter, SQLite leases/journal-before-ack primitives, and strict cloud HTTP -submission/claim clients. The manual, explicit opt-in CLI composition is: - -```bash -interlinked mutation cloud submit \ - --request scratch/job-request.json --artifact scratch/source.bundle -interlinked mutation cloud submit-edit src/path/to/file.ts -interlinked mutation cloud onboard src/path/to/file.ts -interlinked mutation cloud process -``` - -All four commands require `.interlinked/mutation-cloud-v3.local.json` (or -`--config`) with `version:1`, `enabled:true`, one HTTPS endpoint, project / -claimant / owner identities, timeouts and lease duration, the pinned contract -digest and key registry, independently configured server authority, evaluator -policy version, and site limit. -The configured digest must equal the contract identity compiled into this CLI -build; agreement between a config file and a remote service is not sufficient, -and a mismatch is refused before source upload, admission, or evaluation. -These four durable-journal verbs require Node -22.5 or newer because they use the built-in `node:sqlite`; importing or using -other CLI commands does not open that runtime. The separate -`background_enabled` field defaults to `false` and is not required for any -manual command. `submit` authenticates cloud acceptance before -the job enters `.interlinked/mutation-journal.sqlite`, then makes ONE immediate -claim attempt. `submit-edit ` is the bounded convenience path for one -current proposed target: it rejects symlinks and unsafe paths, captures immutable -HEAD plus exactly those current target bytes, selects tests only from that synthetic -snapshot, and submits the parser-minted request plus its exact archive and target. -Its deterministic job key makes an exact retry idempotent, while a changed target, -HEAD, authority, artifact, scope, or test set produces a different job. It always -uses `require_established`; it cannot establish its own baseline, adopt current code, -or enable the live gate. `process` resumes at most one job through claim → authenticate → -the shared local evaluator → atomic SQLite decision/manifest/receipt/run/outbox -commit → remote ack. A failed ack leaves the committed row recoverable; none of -these verbs enables `per_edit_mutation` or changes its mode. - -`onboard ` is the separate, safe first-baseline path. It refuses any -staged, unstaged, or untracked change; binds the configured repository identity, -a stable immutable HEAD, and a tracked regular-file target; builds a bounded, -versioned `git archive` and selects tests only from its materialized HEAD snapshot. -The protocol binding names that byte format exactly as `git-archive-tar-v1`; -the request, acceptance receipt, and execution receipt all hash-bind the same -format/hash/length tuple, so a cloud executor must decode that format and must -never infer an archive type from content or a filename. -Before any network call it persists a fresh random job key plus the exact request, -archive, and target bytes as an unclaimable schema-v7 prepared intent. Only an -authenticated acceptance activates that intent atomically as a normal pending job -with `adopt_current`; reopen/replay reuses those exact bytes and rejects drift. -Ordinary `cloud submit` remains `require_established` and cannot carry adoption -intent. Onboarding does not deploy infrastructure or enable the live edit gate. - -Schema-v6 authenticated evidence retains the canonical envelope, receipt, and -terminal JSON plus exact report BLOB bytes for offline re-verification, with the -journal commit completed before remote acknowledgement. - -Schema v8 scopes the authoritative protocol-v3 manifest head by the exact -authenticated tenant, project, and repository. Switching any of those values is -a baseline miss, never reuse of another authority's state; reopening with the -same values reuses the same head. Upgrading a pre-v8 journal deliberately leaves -the old unscoped singleton head as historical data and creates no attributed -head from it. Ordinary v3 runtime startup does not scan or import -`.interlinked/mutation-manifest.json` or the legacy JSONL stores at all, so a -large, changing, corrupt, or unreadable legacy file cannot grow the SQLite -journal or block startup. The internal explicit audit-import seam is bounded to -256 KiB per file and 512 KiB total; larger files record only bounded metadata -and an `oversized` skip reason. Whether captured or skipped, legacy bytes never -mint or replace v3 authority state. After that migration, run authenticated -`mutation cloud onboard ` for each target whose v3 baseline should be -established; `submit` and `submit-edit` remain `require_established` and cannot -bootstrap from legacy state. - -Schema v9 applies that same authority boundary before a queue lease is minted. -Both keyed immediate processing and background `process` claims require exact -tenant, project, and repository columns written with the job; runtimes sharing -one local journal cannot claim one another's rows. Pre-v9 job rows are preserved -for audit but deliberately receive no inferred authority, remain unclaimable, -and are not automatically resumable; preserve/review them separately rather -than treating them as v3 work for the configured authority. Onboarding lookup -and uniqueness use the full tenant/project/repository/commit/target tuple, so -the same repository commit and target may establish independent baselines for -different authorities. Existing onboarding rows migrate using the tenant and -project values already persisted and request-bound in those rows; no authority -is reconstructed from a response. - -The protocol-v3 contract digest includes the normative source files. After updating those -files, regenerate the CLI digest and have the remote service vendor the matching contract -before expecting strict verification to accept its results. Updating a local pin alone does -not update the remote service; a mismatch remains a verification failure. - -Local mutation manifests validate each retained file, symbol, mutant and provenance record. -An invalid nested record makes the snapshot corrupt: it is not a missing baseline, cannot -start adoption, and remains on disk for recovery. Legacy `accepted_reason` and raw partial or -newer disposition data remain preserved; the disposition interpreter decides their meaning -without treating their mere presence as verification evidence. - -The separate shadow-v1 contract has its own schema and digest. In this CLI repository, -`npx tsx scripts/gen-shadow-schema.mts --check` and -`npx tsx scripts/gen-shadow-contract-digest.mts --check` verify the committed artifacts; -omit `--check` to regenerate them after an intentional contract change. Shared generator -implementations live under `src/harness/shadow/generation/`, outside the normative protocol -source inventory. Tuple schemas preserve required array entries and rest elements; the binding -mismatch outcome requires a nonempty array. Regenerate its schema and digest together, and -coordinate the matching contract with any remote verifier before using changed results. -After updating the shadow protocol package, re-vendor and re-pin its regenerated -contract digest in remote consumers. Literal ignored input paths retain their -filename bytes, including brackets and Git pathspec prefixes. - -The authority key intentionally excludes contract digest and evaluator policy -version. The head stores mechanical mutant identities and statuses, not an old -clean verdict or policy decision. Each result is authenticated under the -currently pinned contract and evaluated under the current policy; missing -prior mutants in unchanged symbols produce not-measured rather than clean. -Evaluation rows and receipts retain the evaluator policy version separately. - -The CLI resolves the request, source artifact, target source, and local config -through real paths under the repository root before opening the journal. Each -local input is opened once with no-follow semantics where the host supports -them, then regular-file identity, size, and repository confinement are checked -on that same descriptor before and after a bounded read. Final-component -symlinks are refused even when they point back inside the repository; a path, -inode, parent-link, or size change during the read also refuses the operation. -Protocol-v3 source artifacts are capped at 64 MiB, reports at 16 MiB, target -source at 2 MiB, request JSON at 1 MiB, and the ignored local config at 64 KiB; -remote JSON responses are capped at 8 MiB. These limits are enforced while -reading streams even when `Content-Length` is missing or dishonest, so an -oversized response is **not measured**, never a clean result. - -The SQLite queue persists a `next_attempt_at_ms` for every deferral so one old -job cannot monopolize `process`. A normal not-ready response waits one second -and clears the consecutive-failure counter. Operational, parse, evaluation, -commit, and acknowledgement failures retry after 1, 2, 4, 8, 16, 32, then 60 -seconds (the delay remains capped at 60 seconds). The eighth consecutive -failure dead-letters the row, preserves its last stage-qualified error, and -exits nonzero with “no clean verdict exists”; it is no longer auto-claimed. -Running `process` before a row is due returns idle rather than hot-looping. -Inspect and token-fence recovery through the public local operations: - -```bash -interlinked mutation cloud dead-letters --limit 20 -interlinked mutation cloud redrive --redrive-token -``` - -The list limit defaults to 20 and must be from 1 through 100. It reports each -row's poll-vs-ack phase, failure count, last error, and current redrive token. -Redrive only clears the dead-letter state and makes the row due; it does not -claim, process, evaluate, acknowledge, or return a verdict. A poll row resumes -polling and an evaluated row resumes acknowledgement-only when a later -`mutation cloud process` invocation claims it. A stale token is refused. - -The explicit commands remain available for inspection and recovery with -`enabled:true`. Autonomous daemon work has a second, default-off boundary: -only a local config that also sets `background_enabled:true` starts the -daemon-owned scheduler. This second opt-in is experimental while each terminal -job still copies the full manifest into an append-only journal snapshot. Leave -it false until bounded/delta manifest storage and retention land. When it is -explicitly enabled, every 15 seconds while the harness daemon is running the -scheduler processes at most one due job and delivers at most one committed -finding. Delivery fsyncs a versioned record to -`.interlinked/mutation-findings.jsonl` before acknowledging the exact SQLite -outbox lease. The stable `outbox_id` makes retries safely deduplicable; every -session active at delivery time queues the bounded finding for its next hook -event (subject to the in-memory queue's 10-minute TTL). With no active session -the durable JSONL row still exists, but the daemon does not currently replay -that file into a later-created session. - -This local scheduler is **not** the protocol-v3 live edit gate or proof of a -deployed cloud product. The cloud deployment still needs provisioned -D1/R2/Workflow/private-Sandbox bindings and an isolated executor, followed by -the deployed crash/retry/adverse acceptance matrix. Until that cutover is -atomic, the live gate remains the legacy synchronous v2 path and the old late -harvest remains survivor-only evidence. - -Protocol-v3 signing authority is split across that deployment boundary. The -control plane may sign admission plus pre-execution terminalization and its -matching failure result; it must not possess the runner private key. The -isolated executor signs every execution receipt and matching execution result -before returning its service artifact. Verification requires the result signer -to be the same key that signed the receipt for that arm, so a control key cannot -mint measured execution and a runner key cannot approve admission or -terminalization. Only the runner public key is configured in the control -Workflow; provisioning the private runner key in the separate executor remains -a release prerequisite, not something `mutation cloud` commands do locally. - -A protocol-v3 durable first sighting defaults to **not measured** when no -baseline exists. It may adopt only when the caller explicitly marks a -background onboarding measurement of current code; a proposed per-edit job -must never establish its own floor. - ### Live per-edit survivor gate -The shipped default is off. Opt in under `.interlinked/guard-rules.json` for team policy or -`.interlinked/guard-rules.local.json` for machine-local runner topology/credentials: - -```json -{ - "per_edit_mutation": { - "enabled": true, - "mode": "warn", - "unavailable_behavior": "allow_unmeasured", - "site_count_threshold": 25, - "budget_ms": 10000, - "harvest_budget_ms": 15000, - "runner_url": "https://mutation-runner.example" - } -} -``` - -| Knob | Effect | -|---|---| -| `enabled` | Master opt-in. `false` does no live mutation work. | -| `mode` | `block` rejects measured findings; `warn` runs the same measurement but allows with warnings; `off` is a no-op. | -| `unavailable_behavior` | `allow_unmeasured` preserves continuity with `[mutation:not-measured]`; `block` fails closed when no verdict is available. | -| `site_count_threshold` | Maximum distinct changed-symbol mutation sites in one established file before "split this patch"; default 50. | -| `budget_ms` | Initial runner round-trip ceiling; default 25,000 ms. Expiry is not a pass. Harvest of an expired run works only when the configured runner implements the durable job protocol; the current experimental Cloud Worker does not, so its expired runs are simply not-measured. | -| `harvest_budget_ms` | PostToolUse wait for an over-budget pending run; default 25,000 ms. A harvest that comes back with nothing is reported as **survivor-only evidence, NOT clean** (2026-08-27): the late path carries back survivors and nothing else — no test-run, engine-exit or mutant-census evidence, and it does not go through the evaluator the synchronous path uses — so "no survivors" is equally consistent with a run that executed no tests. Read that message as "nothing adverse was reported", never as a pass. | -| `runner_url` | THE mutation-runner endpoint (exactly one). No endpoint means unavailable, not clean. | -| `runner_urls` | OBSOLETE (2026-08-27): line-range sharding is retired from v1 — a mutant spanning a range split vanished from both sides. Extra entries are NOT used (no partition, no failover) and the daemon logs a deprecation warning. Remove them. | -| `token` | Optional bearer credential. Keep it in the gitignored local rules file, never committed policy. | - -Every v1 run measures the WHOLE FILE (the runner receives no line range; the -incremental cache is explicitly off on the wire); the evaluator still judges -only changed symbols. Scope is deliberately narrow: JS/TS product source -(`.ts/.tsx/.js/.jsx/.mjs/.cjs`) only; test and root `scratch/` paths are -excluded. A change set with MORE THAN ONE eligible source file returns -not-measured (MUT-AC-26) — today's tool adapters are single-file, so -multi-file shapes (apply_patch, CLI batch) are simply NOT measured yet; -adapters are open work. A **NEW file** (no on-disk baseline) is likewise -reported as not-measured naming the file, rather than passing silently -(2026-08-27): with no prior manifest entry every mutant is first-sighting, -which is baseline ADOPTION, not evidence this edit is safe — and the silent -version made brand-new untested code the one edit that skipped the gate with -no trace. It ships the full proposed change set, companion -test, and local dependencies as -overlays; the runner measures that primary file, while the ratchet judges mutants in changed -symbols. There is no sharding in v1: the range-split prototype was retired because a mutant -whose span crossed a shard boundary vanished from both sides. A future partial-scope design -lives dormant in plan 27 Appendix B and would need sharded-vs-whole-file census equality -proven before it can return. - -The first measured sighting of a file is a distinct **`baseline_adopted`** outcome (2026-08-28): -it records the accepted floor so brownfield survivors do not make adoption impossible, persists -the manifest, and appends a receipt whose `outcome` field says "baseline_adopted" — it is an -allow with a visible "baseline adopted … NOT certified clean" warning, never a clean verdict -(nothing was compared, because that run created the baseline; "adopted" is declared only after -the persistence callback completes — but the current file-based state (manifest → receipt → -index → ledger, no transaction) can still be PARTIAL after a crash, and a failed persist -downgrades to "measured but NOT fully adopted"; true atomicity waits on the SQLite journal). A -red affected suite still blocks in `block` mode even on first sighting. Later runs flag new -changed-region survivors and uncovered sites, plus killed→survived regressions in unchanged -symbols (the accepted floor never grows from a routine run). Beyond adoption, only a FULL-scope, -fully-conclusive clean run refreshes the manifest and appends a receipt (its receipt says -"measured_clean"). A partial (line-range) run can block on -positive evidence but never certifies clean, never creates a first-sighting baseline, and never -touches the manifest; changed-region timeout/indeterminate results are likewise not-measured. -A report with zero mutants for the target — or no entry for it at all — is not-measured, never -clean: an empty report is not proof of a mutant-free scope. -Certifying clean also requires an explicit **engine exit 0** from the runner (strict since -2026-08-28): a response whose `engine.exitCode` is absent, `null`, or non-zero is not-measured — -a crashed engine's partial report is indistinguishable from a complete one, and its unreached -survivors are exactly what a forged clean pass would hide. A red suite still blocks WITHOUT -engine evidence (the engine legitimately never ran; adverse evidence outranks missing evidence). -It also requires a positive **executed-test count**. A green boolean with an absent, malformed, -or zero count is not-measured: it does not prove that any test oracle actually ran. The live -protocol-v2 gate and `mutation measure [--record]` share this evidence floor; neither may persist -or certify from a zero-test run. The sole v3 exception is an authenticated `not_mutatable` -result with an exact zero-mutant report and a `no_test_policy` approved by the signed acceptance -receipt. That exception reaches the evaluator through an opaque verifier-minted capability, not -a caller-controlled flag, and cannot be used by v2 runners. Proven adverse evidence still wins -first, so a survivor or red suite is reported even when the executed-test count is missing. -Note: Stryker exits non-zero when its score is under `thresholds.break`, so a runner that does -not disable that threshold will produce not-measured runs on valid reports — fail-safe, but -configure the runner's Stryker with `thresholds.break: null`. -Every "could not measure" exit — no runner, runner failure, missing shards, inconclusive -evidence — obeys `unavailable_behavior`. Warn-mode findings never launder the manifest clean. - -When the live gate reports: - -- **New survivor:** strengthen the assertion, fix the source behavior, or remove dead/over-specific code. -- **Uncovered site:** add a test that executes the changed behavior. -- **Affected suite red:** restore green before interpreting mutation results. -- **Over site limit:** split the patch into smaller behavioral changes with their tests. -- **Not measured:** check runner configuration/reachability, test selection, budget, and the target repo's Stryker setup. Do not describe it as a pass. - -### Full-manifest census and survivor rounds - -Use `mutation measure --record` for one source file. Use `mutation sweep` for a ranked -survivor batch. For a genuinely current whole-repo manifest, take one cutoff after proving the -exact working tree green, then reuse it across every restart: - -```bash -cutoff="$(date -u +%Y-%m-%dT%H:%M:%SZ)" -interlinked mutation sweep --all-eligible --measured-before "$cutoff" --dry-run -interlinked mutation sweep --all-eligible --measured-before "$cutoff" --limit 20 \ - --runner-url http://runner-a:8790 --runner-url http://runner-b:8790 \ - --budget-ms 1200000 --skip-preflight -``` - -Repeat the second command with the **same cutoff**. Each successful record gets newer provenance -and drops out of the next batch. `--all-eligible` inventories JS/TS product source under `src/`, -including absent and previously measured-clean files; it excludes test/spec paths and `.d.ts`. -Repeated runner URLs create worker lanes pulling from one queue, so one CLI process owns manifest -writes. Use `--skip-preflight` only after this exact overlay/tree passed its suite; otherwise a red -suite can falsely report mutants killed. Keep `not_measurable` and errors as explicit census residue. - -After the census, rank work with `interlinked mutation survivors`. Add or strengthen tests in -small file/symbol batches, remeasure each target with `mutation measure --record`, and run an -independent final census from a new cutoff. A baseline is fully current only when every eligible -file has qualifying provenance from that final round; a high score alone does not prove that. +The shipped default is off. Opt in with a `per_edit_mutation` block in `.interlinked/guard-rules.json` +(team policy) or `.interlinked/guard-rules.local.json` (machine-local runner and credentials). +The knob table (`enabled`, `mode`, `unavailable_behavior`, `site_count_threshold`, `budget_ms`, +`harvest_budget_ms`, `runner_url`, `token`) and the per-finding fixes (new survivor, uncovered site, +affected suite red, over site limit, not measured) are in +[references/mutation-live-gate.md](references/mutation-live-gate.md). +A "not measured" result is never a pass. -For a file-scoped survivor report, the CLI also prints the mutation-test grounding form. Put one -receipt immediately before every new case in a mutation-directed JS/TS test: - -```ts -// test-contract: — -``` +## Command surface -Mutation-directed filenames are dotted policy segments. Canonical forms are -`foo.mutation-kill.test.ts`, `foo.mutation-hardening.test.ts`, and `foo.survivors.test.ts`. -Model/wave qualifiers are allowed directly on the semantic token — for example -`foo.mutation-kill-luna.test.ts` — and remain inside the same strict class. A repo opts into the -blocking profile with `{"mutation_directed_strict_profile":{"enabled":true}}` in -`.interlinked/guard-rules.json` (team policy) or the local rules file. Under that profile, -introduced missing receipts, broad truthiness, missing SUT grounding, and assertion removal are -pre-execution blocks; pre-existing findings remain warnings. Do not rename a file to evade this -classification. - -The write hook now surfaces `test_legitimacy` before a mutation-directed test edit lands; then run -`interlinked verify --all-checks --details` for the full audit. The advisory check reviews -missing/generic receipts, broad truthiness, incidental call order, and explicitly private/internal -imports (including multiline named imports); a companion warning catches cast-based private-member -access. Exact CLI/help/policy strings can be the public contract. “Kills mutant X” cannot: a -mutation kill proves sensitivity to an injected fault, not that the asserted distinction is a -supported behavior. The wider branch/partition, property/model, hermetic-repeat, -refactor-resistance, and blinded-review protocol is currently a design workflow, not a shipped -single command; see `docs/design/session-2026-08-11-synthesis.md` Part 6. Do not claim those -evidence layers ran merely because `mutation measure` succeeded. - -For survivor repair, first reproduce against current source, tests, fixtures and runner -configuration. A live worker or HTTP health response is not proof of measurement. Retain -the initial green test execution, full report and input identities; match the same mutant -before/after, and keep timeouts, uncovered sites and changed-scope results separate from -kills. A fixture missing from a runner checkout is a delivery failure: preserve and ship -the fixture rather than excluding its test. Dispatch agents from the freshly reproduced -survivor set; historical logs can contain mutants already killed by existing tests. Keep -realistic failing application examples intact while investigating a source defect; do not -remove surrounding context merely to get green tests. Document equivalent mutations with -their supported-input reasoning instead of inventing impossible private-helper inputs. -A collected-test inventory is not an executed -test count. Do not add malformed inputs or private-state assertions solely to kill an -equivalent mutant; derive the observable obligation first. Where a behavior crosses a CLI -or hook boundary, share concrete input/expected-outcome examples between unit and e2e -tests, with independent assertions at each boundary. Local personal runner automation -does not establish a supported local-mutation product feature or autonomous repair service. - -**Baseline-integrity** — a PreToolUse block on any edit that loosens a water-line file (below). -Pure disk-vs-proposed numeric diff, near-zero FP. Reset an intentional baseline change with -`INTERLINKED_DISABLE_BASELINE_GUARD=1` (logged). A commit-gate backstop closes the -`apply_patch`/subagent hole for the git-tracked baselines. +`caps --json ` and `caps --json` both preserve JSON output. +`metrics --cwd ` propagates the selected repository to nested commands, +including every `metrics decisions` action. A leaf's explicitly parsed options +take precedence when merging inherited options. + +Finding review uses `metrics decisions findings plan BUNDLE --select IDS --output PLAN` +to freeze complete semantic inputs, provider identity and labeled cost estimates. +`assess PLAN --approve-plan ID --output RUN` admits that frozen identity, while +`--estimate-allowance-usd` explicitly accepts estimate-based admission. Inspect saved +plans and v1/v2 runs with `show`; viewing and validated v2 `--reuse` are inference-free. +TypeSafe exposes its exact public JSON body. Other installed decision adapters expose +semantic inputs and retain actual wire receipts after dispatch. Unknown costs stop +later paid requests, and byte-derived estimates can exceed monetary allowances. + +`findings questions DRAFT --output PROFILE` freezes alternative disposition and +priority instructions and criteria. `plan --question-profile PROFILE` creates +plan/2 with a full map and checksum. Outcome keys stay fixed. Metadata-only renaming +retains semantic request identity, while wording or criteria changes miss the cache. +Default plan/1 and saved v1/v2 runs remain readable. Orchestrator retries are zero, +with external adapter retry guarantees recorded as capability-dependent. -## Command surface | Command | Purpose | |---|---| | `interlinked caps` | Show effective caps (lines/function-tokens/cyclomatic/crap/coverage) + provenance. | @@ -919,11 +289,11 @@ Pure disk-vs-proposed numeric diff, near-zero FP. Reset an intentional baseline | `interlinked caps ratchet --to [--dry-run]` | Tighten a per-function cap AND regenerate the grandfather ledger (`function-complexity-baseline.json`) for everything over it. Only writer of the ledger; `caps set` delegates here when a section exists. | | `interlinked caps status` | Ledger burn-down per metric: cap, entries remaining, top offenders, delta vs the previous snapshot. | | `interlinked caps propose` | Data-driven cap proposals from a live census: percentile ladder and the count each candidate cap would grandfather. | -| `interlinked metrics complexity [--metric ] [--top ] [--churn-days ]` | Complexity census: within-repo ranks, histograms, per-file mass, churn hotspots (90 days by default), directory line-count Gini, over-cap counts. | -| `interlinked metrics jit [ref] [--staged] [--message ] [--calibrate ] [--cwd ] [--json\|--short]` | Ordinal commit-risk score and rank against recent first-parent commits (default 200); defaults to HEAD. `--message` classifies the staged commit's purpose. | -| `interlinked metrics diagnostics [--profile js-ts\|python] [--cwd ] [--json\|--short]` | Explicit verbosity/erosion census, line overlap and absolute contributors; separate language profiles, diagnostic only. | -| `interlinked metrics diagnostics compare [--json]` | Validate snapshot identity, scope and totals; incompatible overall deltas are withheld with nonzero exit, dilution remains visible. | -| `interlinked metrics score [--profile structure-v1] [--cwd ] [--json\|--short]` | Explained composite and individual burdens, explicit evidence bounds and ranking eligibility; legacy structure profile remains selectable. | +| `interlinked metrics complexity [--metric ] [--top ] [--churn-days ]` | Complexity census: within-repo ranks, histograms, per-file mass, churn hotspots (90 days by default), directory line-count Gini, over-cap counts. Generated, vendored and minified files are set aside (source roles v5, as in `metrics score`) and counted in `population`. | +| `interlinked metrics jit [ref] [--staged] [--message ] [--calibrate ] [--cwd ] [--json\|--short]` | Scores HEAD or the selected commit against recent first-parent commits (default 200). Use `--calibrate 0` for the score with an empty comparison population. `--message` classifies the staged commit's purpose. | +| `interlinked metrics diagnostics [--profile auto\|js-ts\|python] [--cwd ] [--json\|--short]` | Explicit verbosity/erosion census, line overlap and absolute contributors; separate language profiles, diagnostic only. Without `--profile` the profile follows the product files: only JS/TS runs `js-ts`, only Python runs `python`, both return `{mixed, profileSelection, profiles: [js-ts, python]}` with one report per language and no shared denominator; `profileSelection {rule, languages, shares}` is printed. An explicit `--profile` is unchanged. A mixed envelope is not a snapshot: save one profile to run `compare`. Uses source roles v5 (`population` in the JSON). | +| `interlinked metrics diagnostics compare [--cwd ] [--json]` | Resolve relative snapshots against the selected root and validate identity, scope and totals. Incompatible overall deltas remain explicit with nonzero exit. | +| `interlinked metrics score [--profile structure-v1] [--cwd ] [--json\|--short\|--full]` | Explained composite and individual burdens, explicit evidence bounds and ranking eligibility; full/JSON adds every retained action and evidence gap. Legacy structure profile remains selectable. | | `interlinked metrics arch [--cwd ] [--json]` | Import graph statistics including isolated modules; graphVersion 2 retains N² propagation cost and adds normalizedReach with N(N−1). | | `interlinked metrics split-plan ` | Where to cut one over-cap file: 2–4 cohesive modules from the intra-file reference graph. | | `interlinked coverage check [--strict] [--changed-files a,b] [--report

] [--update-baseline] [--json]` | Full-suite per-file coverage ratchet vs `coverage-baseline.json`. ADVISORY by default (exit 0 with findings); `--strict` exits 1 on any per-file drop; `--changed-files` scopes to a comma-separated list (what the pre-push hook passes). | @@ -931,6 +301,7 @@ Pure disk-vs-proposed numeric diff, near-zero FP. Reset an intentional baseline | `interlinked mutation check [--report

] [--update-baseline]` | Per-file mutation-score ratchet vs `mutation-baseline.json` (needs a Stryker report). | | `interlinked mutation measure [--record]` | Measure one source file; `--record` persists a complete, conclusive measured report as an explicit manifest baseline update. Recording is not a clean verdict. | | `interlinked mutation survivors [--file ]` | Rank open manifest survivors by file, symbol, and mutator. | +| `interlinked mutation saturation [--file ] [--ratchet]` | Per-file saturation from the manifest: `saturated` (every mutant killed or proved equivalent on current symbol hashes), `open`, `unknown` (stale or unmeasured symbols), `unmeasured`, `gone`. `--ratchet` only adds files to `.interlinked/saturation-baseline.json` (a water-line: a removal is blocked). A listed file that is no longer saturated exits 1. Stability, not correctness. | | `interlinked mutation sweep [--all-eligible] [--measured-before ]` | Re-measure ranked debt or run a restartable full-source census; repeat `--runner-url` for worker lanes. | | `interlinked mutation cloud submit --request --artifact ` | Explicitly submit one protocol-v3 job, authenticate acceptance, journal it, and poll once. Requires the ignored local v3 config; does not enable the edit gate. | | `interlinked mutation cloud submit-edit ` | Capture immutable HEAD plus the current regular target as one proposed edit, submit it with deterministic replay identity and `require_established`, journal its authenticated acceptance, and poll once. Never adopts a baseline or enables the edit gate. | @@ -938,7 +309,7 @@ Pure disk-vs-proposed numeric diff, near-zero FP. Reset an intentional baseline | `interlinked mutation cloud process` | Manually resume at most one due journaled v3 job through the same verified evaluator and journal-before-ack path. A separately opted-in (`background_enabled:true`) harness daemon also runs this single-row processor on a 15-second cadence; autonomous processing is default-off while manifest snapshots are copy-amplifying. Pending/failure retries are durably delayed; eight consecutive failures dead-letter and exit nonzero. | | `interlinked mutation cloud dead-letters [--limit <1..100>]` | List bounded local job dead letters without claiming or processing them, including the poll/ack phase and token needed for fenced recovery. | | `interlinked mutation cloud redrive --redrive-token ` | Make one matching dead letter due again without processing it or returning a verdict; preserves poll-vs-ack phase. | -| `interlinked metrics [--top ] [--full] [--include-tests] [--json]` | Read-only whole-repo scan: exhaustive function-token inventory and file aggregates, companion-test, coverage, cyclomatic, CRAP + gate verdicts. | +| `interlinked metrics [--top ] [--full] [--include-tests] [--json]` | Measures function tokens, companion tests, coverage, cyclomatic complexity and CRAP. The hotspot limit accepts decimal integers from 1 through 200 and defaults to 25. Full and JSON output retain every projected action and next step. | | `interlinked debt list \| show \| resolve ` | The obligation ledger — coverage / red-suite debts AND `transient` debts (the deferred tsc/registry findings a coordinated edit opens). All three verbs see every kind; `resolve` is the human override for a debt no future edit will clear. | | `interlinked debt markers [--root ] [--exclude ] [--record [--reason ]] [--json\|--short\|--full]` | Scan explicit design-debt receipts in source comments. The default is read-only; `--record` appends a local snapshot and lifecycle transitions. Neither mode consults or mutates the obligation ledger. | | `interlinked adopt [--dry-run] [--suite-baseline]` | Seed the supported adoption artifacts from the repo's current state (see below; mutation state is excluded). | @@ -952,395 +323,6 @@ entries may omit a metric; a present metric must have the expected numeric field entries are excluded rather than trusted through a type assertion. Missing or rejected data does not establish coverage, and must not be described as a clean measurement. -### Within-repository ranks and commit-risk nudges - -Complexity rows and file mass now include `pct`; coupling pairs and rework rows include -`percentile`. Ranks are the rounded percentage of the measured population strictly below -the value, so ties share a rank. They are computed before the displayed top-N slice; coupling -uses pairs surviving its filters, and rework ranks all files with measured old-side lines. -These are within-repository comparisons, not cross-project quality grades. - -`metrics complexity` additionally reports hotspots as file cyclomatic mass times changed -lines in the `--churn-days` window. First-parent history is bounded to 2,000 commits and -commits touching more than 30 files are excluded from churn. Directory spread measures -line-count Gini among direct children, with at least three files. These reports are advisory; -an empty hotspot section can mean no usable history rather than no risk. - -`metrics jit` reports size, diffusion, history, experience and purpose contributions to a -static versioned score. It is ordinal, never a defect probability. Calibration uses the -repository's recent first-parent history (up to 365 days / 2,000 commits); no population -means an unranked result. A missing commit, empty staged diff or unavailable Git causes -the command to exit nonzero. The commit-time `[interlinked:jit][heuristic]` nudge inspects -the current staged diff and warns at p90 or above. It never blocks and remains silent when -measurement is unavailable. For `git commit -a` or commands that construct the index later, -the staged snapshot is advisory context, not a measurement of the eventual commit. - -The commit-time session checks read the files this SESSION edited, not the commit. Since -2026-10-05 three of them — `prod_delta_no_test_delta`, `tpp_leapfrog`, -`reintroduces_removed_code`, whose `file` is the file they judged — are narrowed to the files the -commit captures (`evaluator/commit-file-set.ts`). The scope is used only when git alone makes it -certain: the WHOLE command is one `git commit` (the index) or `git commit -a` (plus tracked edits) -with only message/author/quiet/no-verify-style flags, in the session directory. Any other command -in the same line (`git add`, `git apply --cached`, `cd`), an environment or `git -c` override, a -pathspec, `--amend`, `-p` or a heredoc leaves the scope unknown, and every finding is reported -session-wide. The capped -`reintroduces_removed_code` detector gets the committed files as its INPUT, so unstaged files -cannot use up its result limit. Every other commit-time check is reported session-wide as before, -because its `file` can be an example or a cycle's source rather than the evidence. Errors are -never narrowed. - -A second warn-only commit-time backstop, `[interlinked:commit-shippability]`, checks that the -commit would work in a clean checkout. It warns when a staged `.ts/.tsx/.js/.mjs/.cjs/.mts` -file imports a relative file that exists on disk but is untracked or gitignored, and when a -`.github/workflows/*.yml|yaml` `run:` line names a `scripts|src|bin|tools` path that is -ignored, untracked or missing. The workflow scan uses a documented regex, not a YAML parser, -and runs only when the commit stages a workflow or a file under those directories. It inspects -at most 200 staged files and reports any git failure as one `NOT CHECKED` line. It never blocks. - -A third warn-only backstop, `[interlinked:commit-coverage]`, echoes the pre-push per-file -coverage ratchet at commit time. A passed coverage run writes `coverage/sources.json` in its run -directory: the sha256 of each file it measured, with its percentages. At `git commit` the gate -hashes each staged product code file (the line-cap scope, at most 50). If a recent run measured -exactly those bytes below `.interlinked/coverage-baseline.json`, the gate names the file and the -metrics. Staged bytes that no run measured get one `NOT MEASURED` line with the command that -measures them (`interlinked tests run --all --coverage`). A match binds the source bytes only, -not the staged tests, so the pre-push ratchet stays the gate. It never blocks. - -### Function-token inventory - -`interlinked metrics --top 10` shows the stable function bands, percentile summaries, the ten -largest functions, and the ten files with the largest summed function-token counts. `--json` -always includes every measured function and file under `functionTokenMetrics`; `--full` prints -that exhaustive inventory for humans. The default scope is exactly the hard cap's hand-written -product-source scope. `--include-tests` adds test/spec functions as advisory measurements — it -does not make the hard cap apply to tests. Unsupported adapters and unreadable tracked sources -appear under `notMeasured`; they are never reported as zero. Normal output previews up to five -of those gaps with their reasons, while `--full` and `--json` show the complete list. Hand-written -product files with an unrecognized code extension are reported as unsupported instead of silently -disappearing; generated, vendored, declaration, documentation/configuration, markup/data, -dependency/build/binary, scratch, and tool-state paths remain outside the product scope. The -function-token census uses its own broad tracked/unignored discovery pass, so hidden product -source and large source files omitted by the ordinary verify walk are still classified. - -Per-file `summedFunctionTokens` is the sum of function measurements, not a unique lexical count -for the whole file. Nested implementations intentionally count once in their own row and again -inside the enclosing function's span, and imports/types/top-level statements outside functions -are absent. Use `maxFunctionTokens` to judge the cap and the summed value to understand the -nested-inclusive function payload carried by a file. - -### Model-free scoring and evidence workflows - -`interlinked metrics diagnostics` is a separate read-only `interlinked-iterative-js-ts-v1` -profile: union of existing trivial-helper pattern lines and all exact-clone body lines over -token-bearing product SLOC, plus CC × sqrt(innermost-owned function SLOC) mass above CC 10. -JSON retains overlap, redundant clone lines, per-function contributions, source/parser identity, -exclusions and gaps. No target tests, models or new per-edit scans run. Interpret absolute -burdens alongside ratios: unrelated simple code can dilute the denominator. `--profile python` -selects a separate AST/tokenize profile using isolated stdlib Python >=3.10, bounded batches -(eight files, ten seconds each, thirty-second analysis budget). It excludes docstrings and -Python test names, preserves nesting/indentation in clone evidence, and measures an advisory -opposite-boolean-return pattern. The body CC counter is versioned independently of radon; -existing Python edit gates are unchanged. Missing tools, exhausted budgets, unsupported source -and parse failures remain gaps. This limited pattern set is -not benchmark-equivalent, a composite score, a safe-deletion verdict or a new hard gate. -Interactive trivial-helper warnings remain capped; the explicit census is uncapped. -`metrics diagnostics compare` accepts saved reports and refuses incompatible/missing scope; -the older `metrics compare` remains for scores. Save snapshots outside the measured tree so -their files do not change recorded exclusions. `simplify review --diagnostics js-ts|python` -joins candidates to existing scoped review/overlap/recording, with validation still not run. See -`docs/metrics-iterative-diagnostics.md` for the counting contract and pending qualification. - -`interlinked metrics score` defaults to the schema-2 `interlinked-slop-v1` composite: -individual structure, file-size, coverage, mutation, test-integrity, redundancy, -type-operation, architecture, correctness and declared-contract measurements. -The profile has a fixed 100-point budget and hashes its measurement revision. -Higher burden is worse. This is an experimental quality policy, not authorship detection. - -Use **syntax tokens** (lexical tokens) in user-facing explanations. AST nodes are -different units. JS/TS uses parser-resolved lexical leaves under `interlinked-code-v2` / -`interlinked-ts-ast-v1`; regexes, templates and JSX follow that contract. Complete -function size includes types and nested functions, while composite exposure excludes -double ownership. The stable `canonicalTokens` field retains counter provenance. -The inclusive 500 syntax-token cap and existing over-limit hold-or-shrink policy are -independent of scoring curves. There is no additional LLM-token cap or model download. -The optional semantic index's `llama-tokenize` path has a separate purpose. - -Every reading supplies state, numerator/denominator, eligible/measured entities, -evidence IDs and limitations. States are `measured`, `not-applicable`, `missing`, -`stale`, `unsupported` and `inconclusive`. `observedScore` covers measured weight; -`evidenceCompleteness` is not line coverage. Missing evidence widens `range` and -withholds `slopScore` / `rankingEligible`. Unmeasured source broadens whole-repo -bounds to 0–100. Do not rank provisional reports as complete repository scores. -CRAP and uncovered mutation sites remain diagnostics to avoid overlap. - -`--profile structure-v1` retains the schema-1 structural report and its earlier -field names. Select it explicitly for existing consumers. Do not silently compare -different profile hashes, parser revisions, source roles or behavioral policies. -Export-surface correction revision `2026-09-08.2` changes the profile hash; -historical `2026-09-08.1` corpus measurements retain their original identity. - -Declared `export` contracts name the module's exported binding, including aliases -and re-exports; use `name: "default"` for a default export. A default function's -local declaration name does not establish a named export. The compiler reads -inventoried project source and its standard library; unresolved export bindings, -re-export dependencies outside that inventory, conflicting exports and malformed -modules remain inconclusive. Unrelated type errors or unresolved ordinary imports -do not erase a provable local export name. This checks the declared export surface, -including TypeScript type exports, without executing the module or proving its behavior. - -```bash -interlinked metrics catalog --checks --json -interlinked metrics explain tokens --json -interlinked metrics compare before.json after.json --json -interlinked metrics corpus manifest.json --out scratch/corpus --json -interlinked metrics evidence status --json -interlinked metrics evidence identity --json -interlinked metrics evidence import receipt.json artifact.json --json -interlinked metrics gates --json -interlinked metrics coverage status --json -``` - -Catalog assigns each registered check/guard a scored, supporting, advisory or -enforcement disposition. A changed registry requires scoring review. Scoring -supports JS/TS; recognized unsupported source remains a gap, even when another -CLI capability supports that language. Generated/vendor/fixture/test roles cannot -pad product denominators. Bare `@generated` comments do not exempt product code. -Only recognized dependency lockfile names and suffixes receive the configuration -role; product filenames containing `lock`, such as `clock.ts` or -`file-mutation-lock.ts`, remain product. Source roles use -`interlinked-source-roles-v2`; composite profile revision `2026-09-08.3` invalidates -older scope and score comparisons. - -`types.unsafe` scores unsafe access/call/assertion/assignment/return sites and -reports explicit `any`/`unknown` counts separately. Safe unknown narrowing and -sound widening do not incur penalties. Missing compiler bindings and saturated -detector limits produce inconclusive results. Graph/deletion candidates still -need review for dynamic and external consumers. A surviving mutant is not dead-code proof. - -The corpus manifest contains `repositories: [{name,path,commit,stars?,cohort?}]`, -with full Git SHAs, manifest-relative paths and optional `calibration`/`held-out` -cohorts. The command requires clean pinned clones, writes individual reports plus -`corpus.json`, and does not clone, install dependencies, execute target code or -call a model. The source script `scripts/metrics-corpus.ts` delegates to this engine. - -Behavioral work is explicit: `metrics evidence run --kind coverage|mutation ---command '' --artifact --runner-version ---policy [--timeout ] [--resume]`. It runs without a shell in a disposable -copy, binds source/tests/configuration/manifests/locks/support inputs, runner, -outcome and artifact hashes, and supports cancellation. Dependencies must already -exist. Resume requires matching inputs; failed/cancelled attempts cannot be hidden -by older passes. These runs consume CPU time but make no model calls by Interlinked. -An explicitly selected third-party command remains responsible for its own behavior. - -Local evidence runs capture the complete inherited environment before asynchronous -work and pass that snapshot to the child process. The receipt stores a digest of -its string entries and Node runtime identity, never raw environment values. Any -environment change, including a feature flag, invalidates `--resume`; absent and -empty values remain distinct. Unchanged environments can reuse matching receipts. -Imported CI receipts continue to assert their own runner environment provenance. - -Local `--resume` also requires a digest of the actual disposable workspace inputs, -including Git-ignored runtime files such as `.env`, installed dependency bytes, -relative symlinks and file/directory permissions. The configured output artifact -and control directories omitted by the copy policy are excluded. Raw runtime -configuration is never added to receipts. A cache lookup still copies and hashes -the workspace; this can be substantial for installed dependencies. Copying and -hashing share the execution deadline and the 200,000-entry / 4-GiB workspace -bounds. Unavailable, escaping or unstable inputs cannot produce measured evidence. -The original inputs must match the copy before execution and remain unchanged -afterward; new runner outputs are allowed. Older receipts without the workspace -digest remain readable but cannot satisfy local `--resume`. The normalized -`--artifact` selector is persisted and is part of cache identity: selecting -`a.json` and then `b.json` requires separate evidence even for the same runner; -equivalent relative spellings share one selector. - -Local evidence status and scoring revalidate the runtime digest and current -inherited environment before treating a receipt as measured. Changed bytes or -environment make it stale; missing provenance, unreadable inputs or exhausted -validation budgets make it inconclusive. Synchronous reads share a ten-second -validation deadline and hash each artifact selector at most once per store load; -an execution's earlier deadline takes precedence. No raw environment/configuration -values are persisted. Copied ignored directories such as `scratch` and `coverage` -remain inputs, so changing them can invalidate evidence and increase hash cost. -Imported CI receipts retain explicitly asserted provenance rather than claiming -that the local process independently reproduced the CI runtime. - -Coverage accepts strict Istanbul maps; mutation accepts source-bound Stryker-style -reports. Missing files remain inconclusive. Timeout/error/ignored outcomes are not -kills, and no-coverage mutants cannot establish assertion discrimination. Imported -CI receipts have asserted provenance and hash integrity, not signed CI attestation -or independent verification of all installed dependency bytes. Artifact and receipt -JSON must be valid UTF-8; malformed bytes make the evidence unavailable. - -In this repository, the pre-push gate groups protected ref updates by their exact -pushed revision and unions changed source paths within each revision. New refs or -unknown comparison bases require that revision's full tracked source tree. Each -revision runs in a disposable export; source-changing pushes run the tests once -with coverage there, using a 120-second per-test timeout and JSON summary output. -Working-tree coverage reports and report timestamps never establish freshness. -Distinct revisions get distinct runs, and export failures block the push. - -The full pre-push suite remains mandatory. `INTERLINKED_PRE_PUSH_WORKERS=1|2|3|4` -selects a bounded local worker count (default 1); it changes neither test scope nor the -strict coverage ratchet. Use `node scripts/benchmark-tests.mjs` in this repository to -compare 1/2/4 workers on explicit unit and subprocess samples with retries disabled, -elapsed time, failures and sampled process-tree RSS. Add `--full --coverage` for the -actual full coverage workload and `--iterations=3` for repeated measurements. Sample -speedups alone do not establish a safe CI or pre-push default. - -The repository's E2E-capable build and deterministic E2E preflight run before that -suite. Malformed baselines, unresolved inventory moves, invalid source maps or unsafe -report destinations therefore fail before unit execution. Preflight is explicitly unmeasured: -the E2E run, merge and strict measured ratchet remain required. Build fingerprints -exclude untracked runtime-state files only when current build-input analysis proves -they are not inputs; tracked files, declaration inputs, copied assets and uncertain -cases remain bound. This does not authorize ignoring runtime files in test receipts. - -The gate copies the local coverage baseline into the export and checks that every -changed, previously baselined runtime source is measured in that export's report, -including when other changed files are present. A reporter captures the native -coverage provider's effective inclusion decisions during that same test run; -explicitly excluded files do not become required merely because a retained -baseline still names them. Dynamic configuration is evaluated by Vitest, and -missing scope evidence fails closed. A scope with no remaining runtime targets is -reported explicitly without certifying a coverage pass. Deleted files, test-only paths -and modules containing only explicit type/declaration syntax do not require an -entry. Ordinary imports retain a measurement requirement because compiler options -can preserve their runtime side effects. It then runs -`coverage check --strict --json` on that report and checks the JSON measurement -verdict as well as the exit code. Partial, missing or malformed evidence cannot -certify coverage. The CLI's existing advisory/partial-report exit behavior is -unchanged. Coverage instrumentation increases source-push verification time; -there is no second uninstrumented test run. Working-tree files and reports are -left untouched. - -`coverage check --from-index [--index-store ] [--timeout ]` (Unit 7, -2026-09-29) is the ratchet over that index instead of a report: only the test -shards whose transitive inputs changed re-run, every other shard's recorded -contribution and the zeroed `@denominators` shard stay, so the summary is -full-shaped and the ratchet can judge it (a report assembled from selected tests -alone reads as partial and certifies nothing). `--index-store` names the checkout -whose `.interlinked/coverage-index/` holds the index, so a disposable pre-push -export measures against the source checkout's index the way `--receipt-store` -reuses its receipts. When the index cannot certify (a failed or unstable shard, -a changed runtime, quarantine, or a missing index whose full warm then failed) -the command exits 75 — no verdict, never a pass — and the `coverage:index` -stage row carries the reason as `reuse_denied_reason`; `reused: true` means no -shard re-ran. The route is ADMITTED like a scheduled test run -(`coverage-index/admission.ts`: the project's heavy-process lease, the -foreground host slot, then a memory budget the capture's child tree is -supervised against — a refused admission is exit 75 with its reason), and a run -that captured shards ACCEPTS its proposal before returning (a proposal the -current bytes no longer match is no verdict). The test child's environment -identity excludes the supervisor's own variables and the shell's working -directory (`PWD`, `OLDPWD`, `INIT_CWD`), so two exports of one revision share -one identity. The pre-push hook runs this route only when explicitly enabled with -`INTERLINKED_PRE_PUSH_COVERAGE_COMPARE=1`, in COMPARISON MODE — after a measured -regression immediately (nothing follows), after a passing verdict LAST, once -e2e and packaging have judged the export (the comparison runs tests in that -export; no authoritative gate reads bytes it could have modified); only a -partial or unmeasured result compares nothing — and appends `{push_sha, full, index, agree}` to -`.interlinked/coverage-index-comparison.jsonl` (`interlinked query -coverage-compare`); it never decides the push, and promotion waits on that -ledger agreeing over recorded pushes (`INTERLINKED_PRE_PUSH_SKIP_COVERAGE_COMPARE=1` -takes precedence and skips it for one push). When enabled, the comparison runs in a DETACHED -background job that owns the export: the push returns as soon as the -authoritative gates finish, the job appends the same row, writes its notes to -`.interlinked/coverage-index-compare.log` and removes the export when done -(`INTERLINKED_PRE_PUSH_COMPARE_FOREGROUND=1` keeps it inline; the hook tests use -that). Indexed checks and warm runs propagate SIGINT/SIGTERM through discovery and -capture; cancellation prevents accepted summary/proposal promotion and exits without -a verification verdict. Measured on this repository (2507 test shards, an -export, 2026-09-30, supervised, one worker — `--workers`, default 1: three -instrumented workers exceeded the 4 GiB tree budget): the first full index -run 1679 s (961 s unsupervised with three workers on 2026-09-29), a re-run of -the same revision from a DIFFERENT export directory 28 s with `reused: true` -(6 s runtime census plus 22 s folding the shard blobs), one edited source line -1035 s with 2506/2506 test files re-run — nearly every test here is OPAQUE and an opaque shard binds -the whole inventory, so on this repository the index buys exact-revision reuse, -not selection, until the opacity backlog is worked down — peak RSS 3.8 GB; -materialization STREAMS -(each shard is persisted and folded as it is read; holding every contribution -at once needed 11 GB), an opaque shard binds the whole inventory through ONE -`@inventory` digest entry, and the indexed capture is worker-capped by the -host governor. The index is 156 MB on disk. Limits: the runtime census that -validates the index walks every file in the checkout except `.git`, -`.interlinked`, generated and tool directories (`coverage-e2e/`, the e2e -lane's own outputs; `node_modules/.vite`, Vite's cache; the index's own -`.interlinked-coverage-capture-*` scratch), so a working tree carrying -gigabytes of probe or eval bulk (`scratch/`, `evals/`) exceeds the 4 GiB bound -and the index cannot be built there — build and measure in an export. A test -file the runner discovers under a fixture directory is inventoried as a test -(roles v3), because the index needs every executed test in the inventory. A -test that writes into the checkout (a fixture-rooted harness run, a learned -permission persisted to the daemon's cwd) makes the runtime "change" during -the run and the index unavailable; the census error names the files. A wholly -skipped test file is a passed, empty shard; a negative implicit-else branch -count from the V8→istanbul converter is 0 hits. - -`metrics coverage warm --timeout ` runs full Vitest coverage in an overlay and -initializes an exact per-test-file contribution index. Its scoring receipt remains -explicitly inconclusive: index validation uses its own overlay input policy, not -the workspace identity required by local composite scoring receipts. -Use `metrics evidence run` to obtain that scoring evidence. Warming and index -operations remain available; warming alone does not certify a composite score. -Affected tests replace their previous contribution; untouched shards and zero-hit -denominators remain. Input/configuration/dependency/discovery/runner/environment -changes invalidate reuse. Dependency uncertainty is per importing module and -per shard: a pure shard can remain valid alongside an unrelated opaque I/O shard. -Opaque consumers retain repository-wide source dependencies; opaque shared setup or -configuration widens every shard. Configuration/runtime/discovery identity still -invalidates globally when needed. The same static dependency graph powers -`tests plan/run`; ordinary test-run receipts do not replace coverage contributions. - -Coverage-index runtime validation captures a shared original/workspace root once -per validation boundary, comparing that capture with both expected identities. -Distinct overlays still get separate captures, and later validations read fresh -bytes; this is not a time-based cache or a lockfile-only dependency identity. -Proposal promotion checks whether candidate entries exist before scanning source -or runtime inputs. No candidate means no promotion, not a fresh coverage verdict. - -A bounded child process uses Vitest's native discovery -to identify executable test files. Both warm and status load the project's Vitest -configuration in that child; status does not execute tests. Helpers, resolved setup -and global-setup files, and configuration dependencies remain invalidating inputs -without being counted as executable shards. Their static import closure is global -support even when filenames otherwise look like product code. Streamed snapshots bind the -actual overlay inputs, including Git-ignored files and linked dependency bytes, -before and after execution. They require a project-root `node_modules` directory -(a verified dependency mount may be linked), allow at most 200,000 entries and -4 GiB per snapshot, and share the command deadline. Vite's bundle directory is -initialized before capture; existing cache contents remain hashed. Unreadable, -unstable or over-budget inputs prevent an authoritative index verdict. Dynamic dependencies widen selection. Unsupported, -multi-project, incomplete-location or ambiguous capture degrades visibly. -A staged generation promotes only after its exact source is on disk. Corruption -prevents reuse; identical-input coverage churn quarantines it until three full -warm runs agree. Do not enable a local gate solely from the small synthetic benchmark. - -`metrics gates` reports policy separately from actual execution reach, freshness, -deferred/unavailable attempts and measured latency. Historical ratchet reach is -not test coverage; a disabled gate measures nothing. Use warm/status to establish -local evidence before changing a disabled gate's policy. - -`metrics deletions` joins advisory candidates with source-bound behavioral evidence. -`metrics deletions validate plan.json` runs explicit removal trials in isolation, -requiring both baseline and candidate tests plus type checking. A checks-passed -result still requires public-API/runtime review; it does not apply the deletion. -Baseline and candidate phases use separate matching copies prepared before any -check runs. Each phase executes the same ordered checks, so a compiler/build can -produce artifacts consumed by later tests within that phase. Baseline side effects -do not become candidate inputs. Copying and validation share the trial deadline; -changed original runtime inputs make the result inconclusive. This uses two -bounded disposable trees and can increase copy/storage costs. -See `docs/metrics-scoring.md` and `docs/metrics-corpus-2026-09-08.md` for the complete -contract, policies, bounds and pinned empirical artifacts. - -`metrics arch` now retains isolated modules in directory and propagation populations. Its existing -`propagation.cost` still uses N² with self excluded from reach. `normalizedReach` uses N(N−1), or -zero for a fully inventoried singleton/empty graph. The JSON identifies `graphVersion: 2`; old and -new node populations are not interchangeable. These are import-reach diagnostics, not proven change -impact or an architecture quality score. Type-only/runtime edge qualification remains separate work. - ## Automatic obligations vs manual debt markers The `debt` namespace has two deliberately separate records: @@ -1409,126 +391,8 @@ The integrity gate matches these eight files; direction is **per-file**: | `mutation-manifest.json` | the accepted-survivor set may only **shrink**. | | `function-complexity-baseline.json` | per-function grandfather ledger (cyclomatic / cognitive): a recorded value may only **fall**, an entry may only be **dropped**; new entries enter only through `caps ratchet` on a tightening; Write-tool creation is refused. A listed function may hold or shrink at its value; an unlisted over-cap function blocks even when held. When the cap in `metric-caps.json` is tighter than the ledger's, the block says so and names `caps ratchet --to `. | -### Decomposition campaigns (added 2026-09-02) -The gates carry campaign-aware relaxations so a refactor is never blocked by the -metric it improves: the cyclomatic block lists a `↳ plan:` (fewest arm -extractions to get under the cap); per-edit coverage treats a RELOCATED uncovered -line as moved, not added; per-edit mutation reconciles survivors that moved into -an extracted helper; `mutation_directed_assertion_removal` recognizes an assertion -moved to a new test file (`INTERLINKED_ASSERTION_MOVE_WAIVER=1` is the logged -escape). `structural_checks.characterize_mode: block` requires a test run covering -the file before a ledger-listed function is edited. Two advisory nudges catch the -decomposition footguns: `new_export_without_importer` and -`extracted_helper_duplicate`. - -### SessionEnd baseline auto-fold (added 2026-08-16) - -Three of those water-lines used to go stale, because refreshing them needed a human to -remember a manual full run — measured 2026-08-16, the coverage and untested-files -baselines were 49 and 66 days old, and one `interlinked adopt` dropped 38 exemptions -that had been earned weeks earlier. The daemon now folds the session's own evidence -back in at **SessionEnd**, so the bar tracks the tree instead of lagging it: - -| Fold | What it does | Refusal direction | -|---|---|---| -| coverage | raises per-file high-waters from a **fresh** `coverage/coverage-summary.json` | a pct that FELL is held at its high-water, never lowered | -| untested-files | drops the exemption for a file you wrote that now has a companion test | never ADDS an exemption | -| large-files | drops (or lowers) the grandfather count for a file you brought back under the cap | never adds a new entry, never raises a count | - -Each fold is independent and skippable; the whole pass is time-bounded (~2s) and never -throws into SessionEnd. When something folds, the session shows one line — -`[interlinked:baseline-fold] coverage +N raised, untested -M dropped, large-files -K dropped` -— and one JSONL row per fold lands in `.interlinked/baseline-folds.jsonl`. A dry run -(`interlinked harness test`) writes nothing. - -The fold writes through plain `fs` from inside the daemon, so it does not pass the -PreToolUse baseline-integrity gate — the same sanctioned carve-out `coverage-ratchet.ts` -and `interlinked adopt` use. That is safe only because the loosening direction is refused -in the planners themselves, not merely avoided. - -**Opt out** with `{"baseline_autofold": {"enabled": false}}` in -`.interlinked/guard-rules.local.json` (default ON). This does not replace -`interlinked adopt` — adopt still seeds a repo from scratch and folds metrics the -auto-fold leaves alone. - -The unjustified-cast ratchet counts distinct assertion-token lines, even when a line contains -multiple assertions. AST detection broadens syntax coverage without changing that unit. -Both pre-edit and proposed content use the same file path and parser selection. If the -optional TypeScript parser is unavailable, the legacy lexical counter is used; malformed -syntax retains lexical findings alongside recovered AST findings. This remains an advisory -cast review signal, not proof that an assertion is unsound or a safety comment is correct. - -### `max_predicate_drift` — ratchet the unchecked-assertion count to zero (added 2026-08-09) - -A repo-wide COUNT water-line, not a per-function cap. It bounds how many -`type_predicate_drift` findings the tree may carry: a hand-rolled -`function isFoo(v): v is Foo` that validates some of `Foo`'s required properties -and silently ignores the rest. - -Why it needs a ratchet rather than a block: `v is T` is an **unchecked assertion**. -TypeScript never compares the predicate body to `T`, so adding a required field to -`T` leaves every stale guard returning `true` — no compile error, no test failure. -The count only ever grows by accident, so the water-line only ever falls. - -To clear a finding, do not enlarge the guard — replace it with a parser: - -```ts -export function parseFoo(v: unknown): Foo | null { - if (!isJsonObject(v)) return null; - // …validate each field… - return { a, b, c }; // CONSTRUCTED literal — the compiler checks it against Foo -} -``` - -The constructed return is the point: add a required field to `Foo` and this fails -to compile at the boundary instead of under-validating at runtime. - -Measure the current count with `interlinked verify --all-checks` (section -"type predicate drift"), then lower `max_predicate_drift` to match. Raising it is -blocked by `baseline_integrity_gate`. - -> **Two different "min coverage" numbers:** `metric-caps.json → min_coverage` = the per-file -> **floor for the edit-time gate** (default 0 = off). `untested-files-baseline.json → -> min_coverage_pct` = the threshold deciding whether a companion-less file counts as "tested" -> for the `untested_files` verify check (default 60). And **two coverage baselines**: -> `coverage-baseline.json` (full-suite CLI) vs `coverage-edit-baseline.json` (per-edit gate). -> Editing the wrong one has no effect on the gate you're trying to satisfy. - ## Adopting on a legacy repo — `interlinked adopt` -Existing lint debt has its own adoption flow: `interlinked lint import` previews -recognized configs; `lint import --write --baseline` enables the imported check -and seeds `.interlinked/lint-baseline.json` from a complete analyzer batch. -`lint check --update-baseline` may seed previously unadopted scopes; existing -allowances only shrink. Complete ordinary checks and PostToolUse batches retire -resolved allowances automatically. Missing tools, malformed output, timeouts, -or changed config never count as fixes and never update the baseline. - -Native analyzers and declared SARIF adapters participate in the same ratchet. -Named ESLint profiles are discovered automatically as audit candidates. -Use repeatable `lint import --eslint-config ` for named configs; optional -`--eslint-scope ` chooses their working scope. Re-import retains those -selections and refreshes digests without requiring the flags again. A selected -config that disappeared must be restored; it is never silently unenforced. - -The baseline is a multiset of fingerprints keyed by tool/scope/config/targets/flags, file, rule, -message and trimmed source line. It tolerates line movement and counts duplicate -occurrences; identical-line relocation/replacement is ambiguous, so do not treat -matching as an AST identity proof. Added/increased allowances within adopted scopes -and deleting scope history are covered by the shared baseline integrity guard. -First adoption of another scope retains all existing scope history. The reader -uses recorded trusted bytes while a detected loosening awaits restoration. Keep original -lint configs/dependencies; conversion preserves their analyzer semantics. -Default entries keep their original `tool:scope` keys. Explicit/invocation profiles -use separate identities, so multiple configs in one scope cannot share allowances. -Use **interlinked-verify** for the command contract and review-list limitations. - -PostToolUse and ordinary verify measure hook profiles; `lint check` and -`verify --all-checks` also measure audit profiles. Skipping an audit profile in a -hook never retires its debt. `lint import --cadence hook|audit` changes scheduling -without changing baseline identity. Re-import retains saved cadence. SARIF analysis -failures, error notifications and stale/out-of-project locations cannot retire debt. - Seeds the supported non-mutation water-lines from the repo's **current** state so day-1 gates become ratchets ("everything can only improve from here"). Human-invoked `fs` writes, so it bypasses the integrity gate (the sanctioned carve-out). Idempotent and **never loosens** — a re-run refuses @@ -1592,87 +456,6 @@ public `interlinked mutation adopt` command. from a line scanner, and every JS/TS edit then carries a `[interlinked:self_import] NOT MEASURED` warning (the daemon startup warning names both degrades). A clean edit in that state was not scanned for self-imports — keep `typescript` installed. Python needs `radon` on PATH. - Module resolution respects each usage's mode: dynamic imports in CommonJS use import - resolution, while import-equals declarations in ESM use require resolution. Parser - availability at startup does not establish that any particular file was measured. - `self_import` resolves each specifier with the PROJECT's own compiler options (the nearest - tsconfig, following `references` to the project whose `files`/`include` claim the file; nothing - cached, so an edited `extends` target or a new nearer tsconfig applies on the next edit). Five - more states are NOT MEASURED rather than guessed, each with its own `[interlinked:self_import] - NOT MEASURED` warning: a tsconfig on that walk that cannot be parsed, two referenced projects - that both claim the file, a reference walk that hits its 32-project bound with projects - unvisited, a file that no config in reach claims by a `files`/`include` pattern (the nearest - config, its `references`, and its sibling `tsconfig*.json` files are all consulted; an - unclaimed file may be a transitive member — a `/// ` target — which root patterns - cannot decide, so it is never guessed into the nearest config), and an importer whose - directory is not on disk yet. Inside a batch (`write --batch`, `multi-edit`, `verify-changeset` - — all three run the one shared gate) every check sees the WHOLE proposed batch: a sibling the - batch creates is visible to `self_import` AND to the type checker's overlay, and the - introduced-only baseline is judged against the DISK, so an exporter-first batch that adds - `widget.native.ts` and points `widget.ts` at it passes end to end, while a batch that rewrites - `tsconfig.json` so an existing re-export becomes a self-import is refused as INTRODUCED. A - batch that rewrites any file of the project's configuration graph — the selected tsconfig, - any file its `extends` chain reaches whatever its name (`base.json` counts), or a - tsconfig/jsconfig/package.json anywhere in the batch — gets a `type checker cannot see the - proposed configuration` row for its TypeScript entries (the checker reads the disk's config): - land the configuration change first, then the sources. A member whose bytes equal the disk - is still type-checked against the members that differ (a changed exporter can break an - untouched consumer); `multi-edit` validates every manifest member and writes only the - changed ones. Only a batch whose members are ALL unchanged skips the type check, and a - config member whose bytes equal the disk is not a rewrite. The type checker judges each - file under the SAME project `self_import` selects (one program per governing config); a - file no single project claims is `type checker unavailable (project_orphan: …)` rather than - checked under the project root's config. Its disk baseline is recomputed on every check, so - a dependency repaired on disk cannot mask a reintroduced error; a warm compiler service is - rebuilt when the content of its tsconfig or any `extends` target changes on disk and - re-reads the project's root files on every reuse (a declaration file added or removed on - disk joins or leaves the program), sees a dependency rewritten on disk whatever its - timestamp says, and forgets a proposal the moment its check ends (a refused proposal never - colours a later check); and a configured project with no source on disk yet still measures - the first source written into it. - -The type checker's snapshot and its identity share one captured compiler text per file -per check. The identity preserves every UTF-16 code unit, including lone surrogates; -UTF-8 replacement encoding would incorrectly merge distinct compiler texts. -An unreadable disk baseline is unavailable, not an empty baseline. Diagnostic comparison -counts repeated equivalent findings, so moving existing debt is allowed while another -occurrence remains new debt. - -## Dead code: two controls, four evidence layers, buckets before deletion - -Per-edit detection and repo scanning are SEPARATE controls (operator decision -2026-08-17). The config keys `structural_checks.dead_imports` / -`dead_exports` run on every edit (with `dead_code_action: "flag" | "delete"` -deciding whether the warning reports candidates or instructs the agent to -remove them in the same edit — the harness never deletes code itself). The -verb `interlinked deadcode` sweeps the whole repo on demand, in its own -process, and works with or without any of the per-edit checks enabled. - -Four evidence layers, weakest claim first: unreachable files (nothing imports -them — the scan resolves `export … from` barrels and dynamic `import()` edges, -but runtime path-loading stays invisible, so every row is a CANDIDATE), unused -import bindings (same-file evidence, near-zero FP), unused exports (cross-file -inference, type-surface FPs are common), and behaviorally inert branches — -which only the MUTATION lane can prove (`interlinked mutation disposition ---list dead_code`; reachable code whose mutants change nothing observable). - -**Never hand a raw candidate list to a deletion agent.** Run -`interlinked deadcode --categorize` first: every candidate buckets by -mechanical signals (git first-import probe, docs/plans references, seam-shaped -names, package.json published surface, test-only importers, re-export shape, -type-only shape). `future-scaffolding` (never imported + doc-referenced — -planned design) and `deliberate-seam` (test seams, published API) are KEEP -buckets; `reexport-residue` and `orphaned-type` are compiler-guarded -deletions; `superseded` carries git evidence of a successor; `ambiguous` -means review, not delete. The buckets exist because the costly error is -deleting planned or deliberate code — a candidate is a lead, a bucket is a -policy. - -`interlinked simplify scan/review/audit` composes a bounded subset of these dead-code signals -with other advisory simplification evidence. Its local dead-code adapter deliberately skips -per-candidate Git archaeology for latency, so it does not replace `deadcode --categorize` before -deletion or mutation evidence for behaviorally inert branches. Load -**interlinked-simplification** for its evidence, coverage, recording, and deep-handoff contract. ## Quick reference ```bash @@ -1689,16 +472,24 @@ interlinked debt markers --full # explicit source-comment debt + coverage interlinked debt markers --record --reason "reviewed" # append source snapshot + transitions ``` +## References + +Read a reference file only when the task needs it. + +- [references/gates-detail.md](references/gates-detail.md): language coverage and Python test-first naming, refactor readiness, Python and Vitest coverage-gate internals, the `self_import` and batch type-check detail, and evidence qualification additions. +- [references/expression-readability.md](references/expression-readability.md): `interlinked metrics expressions` and `.interlinked/readability.json`. +- [references/e2e-coverage-water-line.md](references/e2e-coverage-water-line.md): the e2e coverage lane and its baseline in the Interlinked CLI checkout, and behavioral contracts beside metric gates. +- [references/mutation-live-gate.md](references/mutation-live-gate.md): how the live per-edit survivor gate measures a file, and `baseline_adopted`. +- [references/mutation-cloud-v3.md](references/mutation-cloud-v3.md): `mutation cloud`, runner connection and sharding, protocol-v3 durable jobs and the mutation journal. +- [references/mutation-campaigns.md](references/mutation-campaigns.md): source-only mutation research helpers, the full-manifest census and survivor rounds. +- [references/metrics.md](references/metrics.md): ranks and commit-risk nudges, the function-token inventory, model-free scoring, evidence runs, this repository's pre-push gate and the coverage index. +- [references/decision-metrics.md](references/decision-metrics.md) covers changed-function evidence, declaration-level complexity, frozen finding assessments and directional Astra reference reviews in the experimental `metrics decisions` namespace. +- [references/baselines-detail.md](references/baselines-detail.md): decomposition campaigns, the SessionEnd baseline auto-fold and `max_predicate_drift`. +- [references/lint-debt-adoption.md](references/lint-debt-adoption.md): `interlinked lint import` and the lint-debt baseline. +- [references/dead-code.md](references/dead-code.md): dead-code controls, evidence layers and deletion buckets. + ## Related skills - **interlinked-verify** — the content gate (pre_block/biome/tsc) and how to land edits. - **interlinked-harness** — the general guard, suppression grammar, cold fallback. - **interlinked-observability** — `interlinked metrics` and recurrence for finding hotspots. - **interlinked-simplification** — advisory delete/stdlib/native/YAGNI/shrink review and audit. - -## Evidence qualification additions - -The baseline-integrity gate treats removing entries from `check-evidence-baseline.json#corpus_cohort` as weakening. Qualification requires fresh complete v2 corpus evidence and the named controls; stale or legacy zero-hit records cannot qualify. This remains local, bypassable enforcement. The broader policy-change contract is a design proposal, not an implemented external authority. - -Stryker adapter paths retain optional statusReason, killedBy, testsCompleted, test IDs, unknown fields and report/run hashes in `.interlinked/mutation-evidence/`. Reports exceeding the 16 MiB retention budget or failed writes emit NOT RETAINED. These are locally hashed JSON-value sidecars, not authenticated protocol-v3 extensions or original HTTP-byte attestations. Mutation score semantics are unchanged. A historical kill and applicability to current tests/helpers/fixtures/config/runtime/environment are separate; incomplete dependency closure remains unknown, and killedBy alone is not closure or causal attribution. Signed v3 payloads retain their existing strict schema; the sidecar capability design is documented separately. - -The cloud runner requires an explicit evidence root and never uses the process working directory as an implicit persistence target. Sidecar retention is bounded to 64 MiB, 128 reports and 30 days, retaining the current report. Run metadata keeps two generations of at most 1 MiB each. Pruning counts are recorded; unrelated files are untouched. This diagnostic store is not an indefinite audit archive, and old run metadata may reference a pruned report. diff --git a/skills/interlinked-quality-gates/references/baselines-detail.md b/skills/interlinked-quality-gates/references/baselines-detail.md new file mode 100644 index 000000000..c3a1b10a6 --- /dev/null +++ b/skills/interlinked-quality-gates/references/baselines-detail.md @@ -0,0 +1,88 @@ +# interlinked-quality-gates: baseline detail + +Reference for [SKILL.md](../SKILL.md). Read it for decomposition campaigns, the SessionEnd auto-fold or `max_predicate_drift`. + +### Decomposition campaigns (added 2026-09-02) +The gates carry campaign-aware relaxations so a refactor is never blocked by the +metric it improves: the cyclomatic block lists a `↳ plan:` (fewest arm +extractions to get under the cap); per-edit coverage treats a RELOCATED uncovered +line as moved, not added; per-edit mutation reconciles survivors that moved into +an extracted helper; `mutation_directed_assertion_removal` recognizes an assertion +moved to a new test file (`INTERLINKED_ASSERTION_MOVE_WAIVER=1` is the logged +escape). `structural_checks.characterize_mode: block` requires a test run covering +the file before a ledger-listed function is edited. Two advisory nudges catch the +decomposition footguns: `new_export_without_importer` and +`extracted_helper_duplicate`. + +### SessionEnd baseline auto-fold (added 2026-08-16) + +Three of those water-lines used to go stale, because refreshing them needed a human to +remember a manual full run — measured 2026-08-16, the coverage and untested-files +baselines were 49 and 66 days old, and one `interlinked adopt` dropped 38 exemptions +that had been earned weeks earlier. The daemon now folds the session's own evidence +back in at **SessionEnd**, so the bar tracks the tree instead of lagging it: + +| Fold | What it does | Refusal direction | +|---|---|---| +| coverage | raises per-file high-waters from a **fresh** `coverage/coverage-summary.json` | a pct that FELL is held at its high-water, never lowered | +| untested-files | drops the exemption for a file you wrote that now has a companion test | never ADDS an exemption | +| large-files | drops (or lowers) the grandfather count for a file you brought back under the cap | never adds a new entry, never raises a count | + +Each fold is independent and skippable; the whole pass is time-bounded (~2s) and never +throws into SessionEnd. When something folds, the session shows one line — +`[interlinked:baseline-fold] coverage +N raised, untested -M dropped, large-files -K dropped` +— and one JSONL row per fold lands in `.interlinked/baseline-folds.jsonl`. A dry run +(`interlinked harness test`) writes nothing. + +The fold writes through plain `fs` from inside the daemon, so it does not pass the +PreToolUse baseline-integrity gate — the same sanctioned carve-out `coverage-ratchet.ts` +and `interlinked adopt` use. That is safe only because the loosening direction is refused +in the planners themselves, not merely avoided. + +**Opt out** with `{"baseline_autofold": {"enabled": false}}` in +`.interlinked/guard-rules.local.json` (default ON). This does not replace +`interlinked adopt` — adopt still seeds a repo from scratch and folds metrics the +auto-fold leaves alone. + +The unjustified-cast ratchet counts distinct assertion-token lines, even when a line contains +multiple assertions. AST detection broadens syntax coverage without changing that unit. +Both pre-edit and proposed content use the same file path and parser selection. If the +optional TypeScript parser is unavailable, the legacy lexical counter is used; malformed +syntax retains lexical findings alongside recovered AST findings. This remains an advisory +cast review signal, not proof that an assertion is unsound or a safety comment is correct. + +### `max_predicate_drift` — ratchet the unchecked-assertion count to zero (added 2026-08-09) + +A repo-wide COUNT water-line, not a per-function cap. It bounds how many +`type_predicate_drift` findings the tree may carry: a hand-rolled +`function isFoo(v): v is Foo` that validates some of `Foo`'s required properties +and silently ignores the rest. + +Why it needs a ratchet rather than a block: `v is T` is an **unchecked assertion**. +TypeScript never compares the predicate body to `T`, so adding a required field to +`T` leaves every stale guard returning `true` — no compile error, no test failure. +The count only ever grows by accident, so the water-line only ever falls. + +To clear a finding, do not enlarge the guard — replace it with a parser: + +```ts +export function parseFoo(v: unknown): Foo | null { + if (!isJsonObject(v)) return null; + // …validate each field… + return { a, b, c }; // CONSTRUCTED literal — the compiler checks it against Foo +} +``` + +The constructed return is the point: add a required field to `Foo` and this fails +to compile at the boundary instead of under-validating at runtime. + +Measure the current count with `interlinked verify --all-checks` (section +"type predicate drift"), then lower `max_predicate_drift` to match. Raising it is +blocked by `baseline_integrity_gate`. + +> **Two different "min coverage" numbers:** `metric-caps.json → min_coverage` = the per-file +> **floor for the edit-time gate** (default 0 = off). `untested-files-baseline.json → +> min_coverage_pct` = the threshold deciding whether a companion-less file counts as "tested" +> for the `untested_files` verify check (default 60). And **two coverage baselines**: +> `coverage-baseline.json` (full-suite CLI) vs `coverage-edit-baseline.json` (per-edit gate). +> Editing the wrong one has no effect on the gate you're trying to satisfy. diff --git a/skills/interlinked-quality-gates/references/dead-code.md b/skills/interlinked-quality-gates/references/dead-code.md new file mode 100644 index 000000000..2eed03b19 --- /dev/null +++ b/skills/interlinked-quality-gates/references/dead-code.md @@ -0,0 +1,83 @@ +# interlinked-quality-gates: dead code + +Reference for [SKILL.md](../SKILL.md). Read it before a dead-code scan or a deletion. + +## Dead code: two controls, four evidence layers, buckets before deletion + +Per-edit detection and repo scanning are SEPARATE controls (operator decision +2026-08-17). The config keys `structural_checks.dead_imports` / +`dead_exports` run on every edit (with `dead_code_action: "flag" | "delete"` +deciding whether the warning reports candidates or instructs the agent to +remove them in the same edit — the harness never deletes code itself). The +verb `interlinked deadcode` sweeps the whole repo on demand, in its own +process, and works with or without any of the per-edit checks enabled. + +Four evidence layers, weakest claim first: unreachable files (nothing imports +them — the scan resolves `export … from` barrels and dynamic `import()` edges, +but runtime path-loading stays invisible, so every row is a CANDIDATE), unused +import bindings (same-file evidence, near-zero FP), unused exports (cross-file +inference, type-surface FPs are common), and behaviorally inert branches — +which only the MUTATION lane can prove (`interlinked mutation disposition +--list dead_code`; reachable code whose mutants change nothing observable). + +**Never hand a raw candidate list to a deletion agent.** Run +`interlinked deadcode --categorize` first: every candidate buckets by +mechanical signals (git first-import probe, docs/plans references, seam-shaped +names, package.json published surface, test-only importers, re-export shape, +type-only shape). `future-scaffolding` (never imported + doc-referenced — +planned design) and `deliberate-seam` (test seams, published API) are KEEP +buckets; `reexport-residue` and `orphaned-type` are compiler-guarded +deletions; `superseded` carries git evidence of a successor; `ambiguous` +means review, not delete. The buckets exist because the costly error is +deleting planned or deliberate code — a candidate is a lead, a bucket is a +policy. + +`interlinked simplify scan/review/audit` composes a bounded subset of these dead-code signals +with other advisory simplification evidence. Its local dead-code adapter deliberately skips +per-candidate Git archaeology for latency, so it does not replace `deadcode --categorize` before +deletion or mutation evidence for behaviorally inert branches. Load +**interlinked-simplification** for its evidence, coverage, recording, and deep-handoff contract. + +## Python trees + +`interlinked deadcode` also reads Python. One `python3 -I` process parses every `.py` file with `ast` (nothing is +imported or run), and the same resolver as `check --only broken-imports` builds one node per module and one edge per +static import (absolute, relative, `from pkg import submodule`, package `__init__.py`). Third-party and standard-library +imports are external; an import of a first-party module that does not exist is counted and listed under +`python.unresolvedImports`. The JSON keeps the TypeScript keys (`unreachableFiles`, `deadImportBindings`, `deadExports`, +`testOnlyImporterFiles`, `scannedFiles`, `scannedPaths`) with the Python rows added, plus `language` +(`typescript`, `python` or `mixed`) and a `python` object. `deadTypeExports` and `--categorize` stay TypeScript only, +and `interlinked simplify` still reads only the TypeScript half. + +- **Reachability** runs from entry roots, each listed in `python.entryRoots` with its kind and the rule that named it: + `console-script` and `entry-point-group` (pyproject, `setup.cfg`, `setup.py`), `main-module` (`__main__.py`), + `main-guard` (`if __name__ == "__main__":`), `shebang`, `test` / `conftest`, `command` (a literal path or + `-m module` or `module:app` in a Makefile, workflow, Dockerfile, shell script, tox/noxfile, or a Python import written + inside a shell script), `documented-command` (`python file.py` in a README), `framework-file` (`manage.py`, + `wsgi.py`, `asgi.py`, `setup.py`, `noxfile.py`, Sphinx `conf.py`), `django-settings` / `django-app` (Django settings + strings; an installed app's `models.py`, `admin.py`, `apps.py`, `migrations/`, `management/commands/`), + `pytest-plugin`, `alembic`, and `loader-glob` (a module that imports by a computed name and holds a glob such as + `provider_*.py`: the files that match are loaded by it). Importing a module runs the `__init__.py` of each parent + package, so those are reached too. A dotted module path in a string literal (`include("app.urls")`, + `"pkg.mod.Class"`) is an edge of kind `string`. A file that only a test root reaches is in `testOnlyImporterFiles`. +- **Unused exports** are public module-level names (no leading underscore, or listed in `__all__`) that no other module + imports, reads by attribute (`mod.name`, `getattr(mod, "name")`, `setattr`, `patch.object`), or reads through a + star import, an enumeration (`dir(mod)`) or a string path. Entry-root modules and decorated definitions are not + judged. Each row carries `weaker`, the evidence that makes it less certain: `dynamic_import_in_tree`, + `getattr_on_module`, `star_import_of_module`, `module_used_as_value`, `listed_in_all`, `used_in_own_file`, + `defined_in_package_init`. A row with an empty `weaker` list is the strongest claim. +- **Dynamic imports.** `importlib.import_module("literal")` is an edge. A computed argument, `pkgutil.iter_modules` + and `entry_points()` mark the tree (`python.dynamicImports.treeHasDynamicImports`); every unreachable file then + carries `dynamic_import_in_tree` and stays a candidate, never a proof. A directory loader whose path comes from + configuration (a tools directory read with `os.scandir`) is still invisible. + +## Alias imports, components and framework roots + +The scan resolves `$lib/x`, tsconfig `paths`, workspace packages (`@scope/pkg/sub`) and framework +aliases the same way as `metrics score` (see `metrics.md`, revision `2026-11-16.2`). It reads the +`\n

{usedBySvelte()}{viaAlias}

\n", + "src/routes/+page.server.ts": "export const load = () => ({});\n", + "src/routes/api/+server.ts": "export function GET() { return new Response(); }\n", +}; + +describe("deadcode: aliases, single-file components, framework roots", () => { + const report = scan(KIT); + it("P1: a module that only a component imports through $lib is reachable", () => { + expect(report.unreachableFiles).not.toContain("src/lib/helpers.ts"); + expect(report.unreachableFiles).not.toContain("src/lib/viaAlias.ts"); + }); + it("P2: a module that nothing imports still fires", () => { + expect(report.unreachableFiles).toEqual(["src/lib/orphan.ts"]); + }); + it("P3: an export that a component imports is used; an export nobody imports still fires", () => { + const details = report.deadExports.filter(item => item.file === "src/lib/helpers.ts").map(item => item.detail).join("\n"); + expect(details).toContain("reallyDead"); + expect(details).not.toContain("usedBySvelte"); + }); + it("N1: SvelteKit route modules are roots, never unreachable", () => { + expect(report.unreachableFiles).not.toContain("src/routes/+page.server.ts"); + expect(report.unreachableFiles).not.toContain("src/routes/api/+server.ts"); + }); + it("N2: the load and GET exports of route modules are not dead exports", () => { + expect(report.deadExports.filter(item => item.file.startsWith("src/routes/"))).toEqual([]); + }); + it("N4: a script that an HTML page loads by path is referenced; one no page names still fires", () => { + const html = scan({ ...KIT, "src/lib/loaded.js": "export const loaded = 1;\n", "src/lib/unloaded.js": "export const unloaded = 1;\n", "static/index.html": '\n' }); + expect(html.unreachableFiles).not.toContain("src/lib/loaded.js"); + expect(html.unreachableFiles).toContain("src/lib/unloaded.js"); + }); + it("N3: an import that sits outside the script block does not make a module used", () => { + const text = scan({ ...KIT, "src/routes/+page.svelte": "

import { viaAlias } from '$lib/viaAlias'

\n" }); + expect(text.unreachableFiles).toContain("src/lib/viaAlias.ts"); + }); +}); diff --git a/src/commands/deadcode-command-entries.test.ts b/src/commands/deadcode-command-entries.test.ts new file mode 100644 index 000000000..fe777e5af --- /dev/null +++ b/src/commands/deadcode-command-entries.test.ts @@ -0,0 +1,57 @@ +import { expect, it } from "vitest"; +import { scriptCommandEntries } from "./deadcode-command-entries.js"; + +it("finds documented invocation targets in shell blocks and inline code", () => { + const files = new Map([ + ["docs/migration.md", [ + "```bash", "node --expose-gc --import tsx scripts/bench.ts src/input.ts", "```", + "Run `npx tsx scripts/scan.ts` to repeat it.", "Merely mentioning scripts/stale.ts is insufficient.", + "```js", "node scripts/stale.ts", "```", + "`echo node scripts/stale.ts`", "`node -e 'scripts/stale.ts'`", + ].join("\n")], + ["docs/fixtures/example.md", "`node scripts/stale.ts`"], + ]); + const known = new Set(["scripts/bench.ts", "scripts/scan.ts", "scripts/stale.ts", "src/input.ts"]); + expect([...scriptCommandEntries([...files.keys()], path => files.get(path) ?? null, known)].sort()).toEqual(["scripts/bench.ts", "scripts/scan.ts"]); +}); + +it("credits a subproject's repository-qualified commands in its own README and study reports", () => { + const docs = new Map([ + ["lab/README.md", "From the repository root, run `node --import tsx lab/run.ts`."], + ["lab/studies/set/REPORT.md", "```sh\nnode lab/summary.ts\n```"], + ["lab/old/report.md", "`node scripts/ambiguous.ts` or `node lab/shadowed.ts`"], + ["lab/fixtures/REPORT.md", "`node lab/fixture.ts`"], + ["other/README.md", "`node lab/unrelated.ts`"], + ]); + const known = new Set(["lab/run.ts", "lab/summary.ts", "scripts/ambiguous.ts", "lab/fixture.ts", "lab/unrelated.ts", "lab/shadowed.ts", "lab/old/lab/shadowed.ts"]); + expect([...scriptCommandEntries([...docs.keys()], path => docs.get(path) ?? null, known)].sort()).toEqual(["lab/run.ts", "lab/summary.ts"]); +}); + +it("credits workflow run targets and preserves unknowns when the directory changes", () => { + const workflow = `jobs: + lint: + runs-on: ubuntu-latest + steps: + - name: node scripts/unused.ts + run: node --import tsx scripts/job.ts scripts/unused.ts + - run: | + cd nested + node scripts/unused.ts +`; + const known = new Set(["scripts/job.ts", "scripts/nested.ts", "nested/scripts/nested.ts", "scripts/unused.ts"]); + const result = scriptCommandEntries([".github/workflows/job.yml", ".github/workflows/nested.yml"], + path => path.endsWith("/job.yml") ? workflow : "defaults:\n run:\n working-directory: nested\njobs:\n test:\n steps:\n - run: node scripts/nested.ts", known); + expect([...result]).toEqual(["scripts/job.ts"]); +}); + +it("resolves worker and lint-plugin entries from their config directory without treating arbitrary JSON paths as entries", () => { + const inputs = new Map([ + ["deploy/workers/wrangler.jsonc", '{ /* entry */ "main": "../../src/worker.ts", "other": "../../src/stale.ts", }'], + ["oxlint.custom.json", '{"jsPlugins":[{"name":"rules","specifier":"./tools/rules.ts"},"npm-plugin",{"specifier":"../outside.ts"}]}'], + ["fixtures/wrangler.json", '{"main":"../src/stale.ts"}'], + ["other.json", '{"main":"src/stale.ts"}'], + ["oxlint.invalid.json", "{ broken"], + ]); + const known = new Set(["src/worker.ts", "tools/rules.ts", "src/stale.ts", "../outside.ts"]); + expect([...scriptCommandEntries([...inputs.keys()], path => inputs.get(path) ?? null, known)].sort()).toEqual(["src/worker.ts", "tools/rules.ts"]); +}); diff --git a/src/commands/deadcode-command-entries.ts b/src/commands/deadcode-command-entries.ts new file mode 100644 index 000000000..d05e7d087 --- /dev/null +++ b/src/commands/deadcode-command-entries.ts @@ -0,0 +1,99 @@ +import { posix } from "node:path"; +import { extractWorkflowCommands } from "../harness/ci-command-extractor.js"; +import { extractFencedBlocks, fencedLineSet } from "../harness/spec/extract-misc.js"; +import { parseJsonc } from "../lib/import-resolution/jsonc.js"; +import { isJsonObject } from "../lib/json-types.js"; + +// Only the launcher's script operand is a root. Paths after it can be data or +// ordinary CLI arguments. Keep unsupported shell syntax out of this evidence. +const SCRIPT_INVOCATION = /^(?:node\s+(?:(?:--expose-gc|--enable-source-maps|--(?:import|loader|require)(?:=|\s+)[\w@./-]+)\s+)*|(?:npx\s+)?tsx\s+)(?:\.\/)?([\w][\w./-]*\.[cm]?[jt]sx?)(?=\s|$)/; +const SHELL_FENCE = /^(?:bash|sh|shell|console)$/i; +const FIXTURE = /(?:^|\/)(?:__fixtures__|fixtures?|tests?|__tests__|node_modules|vendor)(?:\/|$)/; +const DOC = /^(?:readme(?:\.[\w-]+)?\.md|(?:docs|skills)\/.+\.md)$/i; +const PROJECT_DOC = /\/(?:readme|report)(?:\.[\w-]+)?\.md$/i; +const WORKFLOW = /^\.github\/workflows\/[^/]+\.ya?ml$/; +const WORKER_CONFIG = /(?:^|\/)wrangler\.jsonc?$/; +const OXLINT_CONFIG = /(?:^|\/)(?:\.oxlintrc|oxlint(?:\.[\w.-]+)?)\.json$/; + +/** Local configured entry modules are loaded by their tool even without a JS import. */ +function configEntries(file: string, text: string): string[] { + const config = parseJsonc(text); + if (!isJsonObject(config)) return []; + const plugins = Array.isArray(config.jsPlugins) ? config.jsPlugins : []; + const paths = WORKER_CONFIG.test(file) ? [config.main] : plugins.map(plugin => isJsonObject(plugin) ? plugin.specifier : plugin); + return paths.flatMap(path => { + if (typeof path !== "string" || posix.isAbsolute(path)) return []; + if (OXLINT_CONFIG.test(file) && !/^\.{1,2}\//.test(path)) return []; + const target = posix.join(posix.dirname(file), path); + return target.startsWith("../") ? [] : [target]; + }); +} + +function addInvocations(block: string, known: ReadonlySet, found: Set): void { + const lines = block.split(/\r?\n/).map(line => line.trim().replace(/^\$\s+/, "")).filter(line => line && !line.startsWith("#")); + const invocations = lines.map(line => SCRIPT_INVOCATION.exec(line)?.[1]); + // Another command in a shell block can change the cwd or open a heredoc. + if (invocations.some(path => path === undefined) || /[;&|<>`]|\$\(|\\\s*$/m.test(lines.join("\n"))) return; + for (const path of invocations) if (path && known.has(path)) found.add(path); +} + +/** Shell-labelled fences and explicit inline command examples carry invocation + * evidence. Source-language examples and bare prose can name arbitrary paths. */ +function markdownInvocations(text: string, known: ReadonlySet, found: Set): void { + const lines = text.split(/\r?\n/); + const blocks = extractFencedBlocks(lines); + for (const block of blocks) { + if (SHELL_FENCE.test(block.lang)) addInvocations(lines.slice(block.startLine, block.endLine - 1).join("\n"), known, found); + } + const fenced = fencedLineSet(blocks); + for (const [index, line] of lines.entries()) { + if (fenced.has(index + 1)) continue; + for (const code of line.matchAll(/`([^`\n]+)`/g)) addInvocations(code[1] ?? "", known, found); + } +} + +function entrySource(file: string) { + if (FIXTURE.test(file)) return null; + if (WORKER_CONFIG.test(file) || OXLINT_CONFIG.test(file)) return "config"; + if (DOC.test(file)) return "document"; + if (PROJECT_DOC.test(file)) return "project-document"; + if (WORKFLOW.test(file)) return "workflow"; + return null; +} + +function projectDocumentInvocations(file: string, text: string, known: ReadonlySet, found: Set): void { + const paths = new Set(); + markdownInvocations(text, known, paths); + const root = file.slice(0, file.indexOf("/") + 1); + for (const path of paths) { + if (path.startsWith(root) && !known.has(posix.join(posix.dirname(file), path))) found.add(path); + } +} + +/** Positive, root-relative invocation evidence from repository operating docs + * and GitHub Actions run steps. Dynamic paths and cwd overrides stay unknown. */ +export function scriptCommandEntries(files: readonly string[], read: (path: string) => string | null, known: ReadonlySet): Set { + const entries = new Set(); + for (const file of files) { + const source = entrySource(file); + if (!source) continue; + const text = read(file); + if (!text) continue; + switch (source) { + case "config": + for (const target of configEntries(file, text)) if (known.has(target)) entries.add(target); + break; + case "document": + markdownInvocations(text, known, entries); + break; + case "project-document": + projectDocumentInvocations(file, text, known, entries); + break; + case "workflow": + if (/\bworking-directory["']?\s*:/.test(text)) break; + for (const step of extractWorkflowCommands(text)) addInvocations(step.command, known, entries); + break; + } + } + return entries; +} diff --git a/src/commands/deadcode-entries.test.ts b/src/commands/deadcode-entries.test.ts new file mode 100644 index 000000000..1047d4094 --- /dev/null +++ b/src/commands/deadcode-entries.test.ts @@ -0,0 +1,41 @@ +import { describe, expect, it } from "vitest"; +import { mapRepoView } from "../lib/import-resolution/repo-view.js"; +import { nestedPackageEntries, reachabilityRoots } from "./deadcode-entries.js"; + +const FILES = new Map([ + ["package.json", '{"scripts":{"build":"tsup src/index.ts"}}'], + ["packages/db/package.json", '{"dependencies":{},"scripts":{"seed":"tsx src/scripts/seed.ts","reset":"node ./scripts/reset.js --force"},"bin":{"db":"./dist/cli.js"}}'], + ["apps/web/package.json", '{"dependencies":{"@sveltejs/kit":"2"}}'], + ["apps/broken/package.json", "{ nope"], +]); +const view = mapRepoView(FILES); +const known = new Set([ + "packages/db/src/scripts/seed.ts", "packages/db/scripts/reset.js", "packages/db/src/cli.ts", "packages/db/src/other.ts", + "apps/web/vite.config.ts", "apps/web/src/routes/+page.server.ts", "apps/web/src/lib/a.ts", "packages/ui/.storybook/main.ts", "apps/web/postcss.config.js", +]); + +describe("nestedPackageEntries", () => { + it("P1: a script and a bin target of a nested package are entries, resolved from that package", () => { + expect([...nestedPackageEntries(view, known)].sort()).toEqual(["packages/db/scripts/reset.js", "packages/db/src/cli.ts", "packages/db/src/scripts/seed.ts"]); + }); + it("N1: a path that is not a known file is not an entry, and a broken package.json adds none", () => { + expect(nestedPackageEntries(view, new Set(["packages/db/src/other.ts"]))).toEqual(new Set()); + }); +}); + +describe("reachabilityRoots", () => { + const roots = reachabilityRoots(view, [...known], ["apps/web/src/routes/+page.svelte"], new Set(["src/index.ts"])); + it("P1: adds framework route files, nested scripts and tool configs to the given entries", () => { + for (const path of ["src/index.ts", "apps/web/src/routes/+page.server.ts", "packages/db/src/scripts/seed.ts", "apps/web/vite.config.ts", "apps/web/postcss.config.js", "packages/ui/.storybook/main.ts"]) { + expect(roots.entries.has(path)).toBe(true); + } + }); + it("P2: only framework entries lose their export scan", () => { + expect(roots.frameworkEntries.has("apps/web/src/routes/+page.server.ts")).toBe(true); + expect(roots.frameworkEntries.has("apps/web/vite.config.ts")).toBe(false); + }); + it("N1: an ordinary module is not an entry", () => { + expect(roots.entries.has("apps/web/src/lib/a.ts")).toBe(false); + expect(roots.entries.has("packages/db/src/other.ts")).toBe(false); + }); +}); diff --git a/src/commands/deadcode-entries.ts b/src/commands/deadcode-entries.ts new file mode 100644 index 000000000..3bed7d6e1 --- /dev/null +++ b/src/commands/deadcode-entries.ts @@ -0,0 +1,63 @@ +// Entry roots for the `deadcode` reachability scan that come from more than the root package.json: +// framework route files, scripts and bins of nested packages, and tool config files. + +import { frameworkEntryFiles } from "../lib/import-resolution/framework-entries.js"; +import type { RepoView } from "../lib/import-resolution/repo-view.js"; +import { isJsonObject, type JsonObject } from "../lib/json-types.js"; + +/** Tool configuration that a tool loads by name from its package directory, at any depth (vite, svelte-kit, postcss, tailwind, playwright, storybook). */ +const TOOL_CONFIG_RE = /(?:^|\/)[\w-]+\.config\.[cm]?[jt]s$|(?:^|\/)\.storybook\/[\w-]+\.[cm]?[jt]sx?$/; +const SOURCE_NAME_RE = /[\w./-]+\.(?:tsx?|[cm]?js)\b/g; + +function parseObject(text: string | null): JsonObject | null { + try { + const json: unknown = JSON.parse(text ?? ""); + return isJsonObject(json) ? json : null; + } catch { + return null; + } +} + +/** Every string value of `scripts` and `bin`. */ +function commandTexts(json: JsonObject): string[] { + const values = [...Object.values(isJsonObject(json.scripts) ? json.scripts : {}), ...Object.values(isJsonObject(json.bin) ? json.bin : {})]; + return values.filter((value): value is string => typeof value === "string"); +} + +/** Paths a command text names, as written and with a build-output path mapped to its source. */ +function candidatePaths(dir: string, text: string): string[] { + return [...text.matchAll(SOURCE_NAME_RE)].flatMap(match => { + const rel = `${dir}/${match[0].replace(/^\.\//, "")}`; + return [rel, rel.replace(`${dir}/dist/`, `${dir}/src/`).replace(/\.js$/, ".ts")]; + }); +} + +/** + * Files that a nested package's own package.json runs: `bin` targets and any + * source file named in a script value, resolved from that package's directory. + * The root package.json is read elsewhere. Only paths in `known` count. + */ +export function nestedPackageEntries(view: RepoView, known: ReadonlySet): Set { + const found = new Set(); + for (const file of view.configFiles().filter(path => path.endsWith("/package.json"))) { + const json = parseObject(view.read(file)); + const dir = file.slice(0, -"/package.json".length); + for (const text of json ? commandTexts(json) : []) { + for (const path of candidatePaths(dir, text)) if (known.has(path)) found.add(path); + } + } + return found; +} + +/** `base` plus every root that the scan can name: `entries` for reachability, `frameworkEntries` for the export scan skip. */ +export function reachabilityRoots( + view: RepoView, + codeFiles: readonly string[], + componentFiles: readonly string[], + base: Set, +): { entries: Set; frameworkEntries: ReadonlySet } { + const frameworkEntries = frameworkEntryFiles(view, [...codeFiles, ...componentFiles]); + const entries = new Set([...base, ...frameworkEntries, ...nestedPackageEntries(view, new Set(codeFiles))]); + for (const path of codeFiles) if (TOOL_CONFIG_RE.test(path)) entries.add(path); + return { entries, frameworkEntries }; +} diff --git a/src/commands/deadcode-html.test.ts b/src/commands/deadcode-html.test.ts new file mode 100644 index 000000000..a049bf102 --- /dev/null +++ b/src/commands/deadcode-html.test.ts @@ -0,0 +1,28 @@ +import { describe, expect, it } from "vitest"; +import { htmlReferencedPaths } from "./deadcode-html.js"; + +const KNOWN = new Set(["proto/learn.js", "proto/site/academy.js", "proto/components/Button.jsx", "root.js", "other/x.js"]); + +describe("htmlReferencedPaths", () => { + it("P1: a script src is a reference, relative to the HTML file", () => { + const html = '\n'; + expect(htmlReferencedPaths(html, "proto/index.html", KNOWN)).toEqual(["proto/learn.js", "proto/site/academy.js"]); + }); + it("P2: a quoted path in an inline script or a path list is a reference", () => { + const html = ""; + expect(htmlReferencedPaths(html, "proto/preview.html", KNOWN)).toEqual(["proto/components/Button.jsx", "root.js"]); + }); + it("P3: a root-absolute src reads from the repo root", () => { + expect(htmlReferencedPaths('', "proto/a.html", KNOWN)).toEqual(["other/x.js"]); + }); + it("N1: a path to a file that does not exist is not a reference", () => { + expect(htmlReferencedPaths('', "proto/a.html", KNOWN)).toEqual([]); + }); + it("N2: a URL and a non-code file are not references", () => { + const html = ''; + expect(htmlReferencedPaths(html, "proto/a.html", KNOWN)).toEqual([]); + }); + it("N3: a path that is only named in prose is not a reference", () => { + expect(htmlReferencedPaths("

see learn.js for details

", "proto/a.html", KNOWN)).toEqual([]); + }); +}); diff --git a/src/commands/deadcode-html.ts b/src/commands/deadcode-html.ts new file mode 100644 index 000000000..5623431c5 --- /dev/null +++ b/src/commands/deadcode-html.ts @@ -0,0 +1,54 @@ +// A static HTML page loads scripts by path (`", + "", + "
import nothing from 'markup-text'
", + "", + "", + ].join("\n"); + const masked = maskComponentScripts(source, "svelte"); + + it("P1: keeps both script bodies at their original line numbers", () => { + expect(lineOf(masked, "$lib/a")).toBe(lineOf(source, "$lib/a")); + expect(lineOf(masked, "../c")).toBe(lineOf(source, "../c")); + }); + it("P2: keeps the length and the line count", () => { + expect(masked.length).toBe(source.length); + expect(masked.split("\n").length).toBe(source.split("\n").length); + }); + it("N1: drops markup and style text", () => { + expect(masked).not.toContain("markup-text"); + expect(masked).not.toContain("css"); + }); + it("N2: ignores a script tag inside an HTML comment", () => { + const text = "\n"; + const out = maskComponentScripts(text, "svelte"); + expect(out).not.toContain("dead"); + expect(out).toContain("live"); + }); + it("N3: handles a generics attribute that holds a closing angle bracket", () => { + const text = ""; + expect(maskComponentScripts(text, "svelte")).toContain("./q"); + }); + it("N4: skips a script in a language the parser cannot read", () => { + const text = ""; + expect(maskComponentScripts(text, "svelte")).not.toContain("./x"); + }); + it("N5: ignores a self-closing script tag", () => { + expect(maskComponentScripts("\n"; + const out = maskComponentScripts(text, "vue"); + expect(lineOf(out, "@/a")).toBe(3); + expect(lineOf(out, "./b")).toBe(6); + }); +}); + +describe("maskComponentScripts: astro", () => { + const text = "---\nimport Layout from '../layouts/Layout.astro';\nconst x = 1;\n---\n\n"; + const out = maskComponentScripts(text, "astro"); + it("P1: reads the frontmatter between the two dash lines", () => { + expect(lineOf(out, "../layouts/Layout.astro")).toBe(2); + }); + it("P2: reads a body script too", () => { + expect(lineOf(out, "./client")).toBe(7); + }); + it("N1: reads nothing from a body when the file has no frontmatter and no script", () => { + expect(maskComponentScripts("

import a from 'x'

", "astro")).not.toContain("import"); + }); + it("N2: treats an unclosed frontmatter fence as no frontmatter", () => { + expect(maskComponentScripts("---\nimport a from 'x'\n", "astro")).not.toContain("import"); + }); +}); diff --git a/src/lib/import-resolution/component-scripts.ts b/src/lib/import-resolution/component-scripts.ts new file mode 100644 index 000000000..241fd0d53 --- /dev/null +++ b/src/lib/import-resolution/component-scripts.ts @@ -0,0 +1,130 @@ +// =========================================== +// Single-file components: script text with the line numbers kept +// =========================================== +// A `.svelte`, `.vue` or `.astro` file imports modules from its `