@renzrollon/interlock 1.4.2 → 1.5.0

package/.claude-plugin/plugin.json

@@ -1,8 +1,8 @@
 {
   "name": "interlock",
   "displayName": "Interlock",
-  "version": "1.4.2",
-  "description": "Autonomous spec-driven development orchestration for Claude Code, layered on OpenSpec. Onboard a repo, produce a reviewed spec, then ship it start-to-commit with parallel agents and a deterministic gate spine.",
+  "version": "1.5.0",
+  "description": "Spec-driven development for Claude Code, layered on OpenSpec. You read one spec; parallel agents ship it to a tested commit.",
   "author": {
     "name": "Carl Rollon",
     "url": "https://github.com/renzrollon"

package/CHANGELOG.md

@@ -5,6 +5,47 @@ All notable changes to this project are documented here.
 The format follows Keep a Changelog 1.1.0, and
 this project adheres to Semantic Versioning 2.0.0.
 
+## [Unreleased]
+
+## 1.5.0 — 2026-10-11
+
+### Added
+
+- **The graph indexes C# and Bicep (#8).** `.cs`, `.csproj` and `.bicep` files were skipped, so a .NET repository got docs and OpenSpec links and nothing structural.
+  - **Project references** (`<ProjectReference>`, either slash style) are `EXTRACTED` project-to-project edges. A reference that holds a `$(...)` property or names no file stays unresolved rather than guessed.
+  - **Types** (`class`, `record`, `struct`, `interface`, `enum`) are symbols with their line. A namespace is one `namespace:` node, with a `declares` edge from each file that declares it; a `using` resolves to it, or to an external name when the repository declares none.
+  - **References and tests are `INFERRED`.** A file that names a type from a namespace it can see gets a `references` edge. A method under `Fact`, `Theory`, `Test`, `TestCase`, `TestMethod` or `DataTestMethod` is a test node, and `consumers` prints a `consumer_test:` line for it.
+  - **Bicep** modules are import edges, `param`, `var`, `resource` and `output` are symbols, and a `<module>.outputs.<x>` use is an `INFERRED` reference.
+  - **Build output is not indexed.** A `bin/` or `obj/` beside a `.csproj` is skipped; one without a project file beside it, such as `bin/cli.js`, is still indexed.
+  - **Known limits**, stated in `skills/graph/SKILL.md`: a fully-qualified name with no `using` is not seen, `global using` applies to its own file, a nested type has no record of its nesting, and a declaration-shaped line inside a verbatim or raw string is a false positive.
+  - **The empty-graph notice** lists the new extensions.
+
+### Changed
+
+- **`interlock-graph` finishes when it meets a path it cannot read (#7).** One unreadable `.mcp.json` made `build` exit 1 with a stack trace and no graph, and `update` and `docs-index` skipped unreadable files without a word.
+  - **Each skipped path is named** on stderr as `GRAPH SKIPPED UNREADABLE: <path> (<code>)`, once. An unreadable `.gitignore` or `.interlockignore` says its patterns were not applied.
+  - **The command exits 0.** The `build` and `update` summaries end in `skipped=<n>` only when something was skipped, `manifest.json` records `skipped`, and `GRAPH_REPORT.md` lists the paths under "Not indexed". `update` rebuilds when the set of unreadable paths changes, and a manifest from an older build reads as having none.
+  - **A query says when its graph is partial.** `query`, `consumers`, `path`, `explain` and `context` print one `GRAPH PARTIAL` line on stderr when the graph they read was built past skipped paths. Their stdout and exit code do not change, and a graph built with nothing skipped prints nothing new.
+  - **A script that read the exit code as "the graph is complete" must read `skipped=<n>` as well.** `/interlock:bootstrap` now does: it prints `GRAPH PARTIAL` for a graph built past unreadable paths, and tells an unreadable tree apart from an unsupported language.
+  - **A file the graph holds a node for is a file it read.** The hash and the node now come from one read.
+- **The inter-wave verify budget is derived from the test profile (#10).** It was one published constant, so a suite slower than the constant was never planned at the second checkpoint and a ship run silently stopped verifying between waves.
+  - **At `run start` the budget is derived from `unit.timeout_ms`** and floored at the published budget, then fixed for the run; editing the profile mid-run changes nothing for that run. The `interlock limits` row is relabelled `inter-wave verify budget (floor)`; its value and its `--json` key are unchanged.
+  - **`VERIFY BUDGET AT THE PUBLISHED FLOOR`** is raised once, when a checkpoint is cut short — to nothing, or to typecheck alone when the profile names a typecheck command — and the profile carried no `unit.timeout_ms`. It names `/interlock:fix-tests --reconfigure`.
+  - **`interlock verify plan --context inter-wave --json`** applies the same budget and prints `budgetSource` (`profile`, `published` or `flag`).
+  - **`/interlock:fix-tests`** records `unit.timeout_ms` as a green full run's wall time in whole milliseconds, rounded up, and never writes a value below one it measured.
+  - **The run's receipt and close summary carry `verifyBudget`.**
+
+### Fixed
+
+- **A handoff packet that fails the schema no longer fails a task that reported success, or halts the run (#9).** Three finished tasks whose packets were over the character cap, had an evidence range, or an empty `next` counted as three failures and stopped a run on work that was done and ticked by hand afterwards.
+  - **Breaking, for the recorded outcome.** Such a task is now recorded `ok` with a `reportRejected` reason, its box is ticked, and it no longer counts toward the task-failure halt. A reader or script that took a rejected packet to be a failed task now sees an `ok` outcome. Look for `HANDOFF REJECTED` in the batch's banners, a `handoff reports rejected` row in the run's summary, `reportRejected` on the receipt's wave, and `report(s) rejected` in `interlock run-log show`. Outcome rows and the resume card carry the ids too.
+  - **`CLAIM OVERRIDDEN` no longer fires from a real run.** A rejected packet was the only way `record-batch` recorded a claimed success as a failure. The claim and the record now agree for that input, so nothing is overridden; the adjudication stays and is pinned by its unit cases.
+  - **The packet is still never kept or trimmed.** The next wave's briefing gets a `NO VALIDATED REPORT` block naming the task, the reason and the paths it reported, and not its summary. The reason is a short single line that quotes at most a clipped piece of the offending value, and the paths are listed only up to the handoff character cap with the rest counted, so a rejected report cannot hand on more than a valid packet may.
+  - **The last wave says so.** With no later wave to brief, `HANDOFF REJECTED` no longer ends in "the next wave is told": it names what does check that work — the review under `--strict` or `--review`, final verification otherwise — or says that nothing does under `--apply-only`. The review briefing carries an `UNVALIDATED REPORTS` block naming every rejected report of the run. A rejected report on the last wave still does not block the commit.
+  - **The implementer briefing no longer says an over-cap packet "fails the task".** It says the packet is rejected whole and the task is recorded as having filed no usable report. Every implementer prompt changes by that sentence, so a Workflow run resumed across this upgrade re-runs lanes it had already finished.
+  - **A task that reports `ok: false`, or never reports, fails and counts exactly as before**, and keeps its own error.
+  - **This change did not touch** checkpoint scoping, the re-ask, or checkpoint placement. Where the inter-wave checkpoints fall and what each re-checks are as they were.
+
 ## 1.4.2 — 2026-10-10
 
 ### Fixed

package/README.md

@@ -6,10 +6,16 @@
 [![CI](https://github.com/renzrollon/interlock/actions/workflows/ci.yml/badge.svg)](https://github.com/renzrollon/interlock/actions/workflows/ci.yml)
 [![Claude Code ≥ 2.1.154](https://img.shields.io/badge/Claude%20Code-%E2%89%A5%202.1.154-blue)](docs/01-first-hour.md#before-you-start)
 [![MIT](https://img.shields.io/badge/license-MIT-green)](./LICENSE)
+[![Site](https://img.shields.io/badge/site-renzrollon.github.io%2Finterlock-ff563c)](https://renzrollon.github.io/interlock/)
 
 <p align="center">
-  <img src="docs/assets/interlock-flow-wide.png" alt="Interlock flow: bootstrap once, then spec, you read the spec, ship, and optionally mr. Two commands, one human checkpoint." width="900">
+  <img src="docs/assets/spec-and-ship.gif" alt="One real run, 34 seconds: /interlock:spec asks one question, writes the change and stops at the checkpoint; /interlock:ship runs two waves of parallel agents, the suite passes 180 of 180, one commit." width="838">
 </p>
+<p align="center"><sub>One real run, cut to 34 s. <code>spec</code> asks one question, writes 11 specs and 12 tasks, then stops. <code>ship</code> runs three agents in parallel across two waves and ends in a commit with the suite green, 180 of 180.</sub></p>
+<p align="center"><code>12 tasks · 2 waves · 19 agents · 13m 54s · 57 files · 2,881 lines · 180 of 180 pass · 1 commit</code></p>
+<!-- The uncut, captioned 2:34 of the same run is not in git. Once it is a release asset, uncomment:
+<p align="center"><sub>The whole run, uncut and captioned: <a href="https://github.com/renzrollon/interlock/releases/download/v1.4.2/interlock-spec-and-ship-full.mp4">2:34, mp4, 9 MB</a>.</sub></p>
+-->
 
 ```bash
 /interlock:spec "<idea>"   # explores your repo, writes a reviewed spec, then stops
@@ -54,11 +60,22 @@ interlock doctor          # preflight: prints the exact allowlist an unattended
 | `/interlock:ship` | Reviewed change → waves (parallel batches of file-disjoint tasks) → your test suite → commit. No review by default; `--strict` adds adversarial review and handoff artifacts. `--solo` / `--waves` force the shape | **workflow** |
 | `/interlock:mr` | Change → merge request | skill |
 
+<p align="center">
+  <img src="docs/assets/interlock-flow-wide.png" alt="Interlock flow: bootstrap once, then spec, you read the spec, ship, and optionally mr. Two commands, one human checkpoint." width="900">
+</p>
+
 `ship` is the odd one out on purpose. A skill is instructions Claude follows; a workflow is a script a runtime executes, and this runtime has no channel for a question. That is why every decision that could need a human is settled *before* ship starts, and why `spec` is conversational where it has to be. The plan preview names the shape and the agent count before anything is spawned.
 
+<p align="center">
+  <img src="docs/assets/ship-meter.png" alt="The ship meter pane during the recorded run: wave 1 with three lanes marked ok and the model that served each, the verify checkpoint between the waves, wave 2 with two lanes running and one pending, then verify-final, commit and close." width="760">
+</p>
+<p align="center"><sub>The same run, drawn inside Claude Code while it ran: every wave, batch and lane as the CLI reported them.</sub></p>
+
+**You can watch it.** On Claude Code 2.1.287 and later the plugin's hooks module draws the run as it goes: a status line that names the stage and stops at the checkpoint, a pane with every wave, lane and agent, and each degradation banner as a toast the moment the step that raised it prints. The pane observes; the CLI decides. On an older host the run is the same, without the pane. [The ship meter →](docs/07-cli-and-configuration.md#the-ship-meter-interlock-meter)
+
 ## Why this and not a folder of prompts
 
-Decisions that have a correct answer are moved out of prose and into code, one at a time. The script holds the loop, the CLI holds the rules, the agents do the work.
+Decisions that have a correct answer are moved out of prose and into code, one at a time. The script holds the loop, the CLI holds the rules, the agents do the work. Interlock is built with Interlock: the features and fixes here start as OpenSpec changes and go through the same spec, checkpoint and ship, and [openspec/changes/archive](openspec/changes/archive) is the record, one folder per change.
 
 - **Thresholds are code.** Wave order, the parallel-agent cap, the remediation round budget, the review quality band: each is an `interlock` subcommand with an exit code, not markdown a model can talk itself past. [Every subcommand →](docs/07-cli-and-configuration.md)
 - **Parallel agents cannot overwrite each other.** The planner separates tasks that would touch the same file; with `--isolate-waves`, every parallel task runs in its own git worktree and a collision is a named halt, never a lost write.
@@ -71,6 +88,14 @@ Decisions that have a correct answer are moved out of prose and into code, one a
 
 Most of the category competes on how much structure you write before coding — Spec Kit adds phases, BMAD adds roles, Kiro adds an IDE. Interlock competes on a different axis: **how many decisions the model is not allowed to make.**
 
+| | Competes on | Where the rules live |
+|---|---|---|
+| Spec Kit | phases you write before code | prompt templates, portable across thirty agents |
+| BMAD | roles you assign | prompt templates |
+| Kiro | an IDE with specs built in | the IDE |
+| OpenSpec | the artifact loop and its CLI | the CLI validates artifacts; skills run the loop |
+| **Interlock** | how many decisions the model may not make | a CLI with exit codes, and a runtime with no channel for a question |
+
 It composes OpenSpec rather than replacing it. `openspec init` installs its own skills, and `/interlock:spec` drives the `openspec` CLI directly, so both stay available. Use `/interlock:spec` when you want the gates, and the stock skills when you want the plain artifact loop. What Interlock adds, and when plain OpenSpec is the right call: [03](docs/03-openspec-vs-interlock.md). Where it sits against OpenClaw, Hermes Agent and DeepSeek Harness: [08](docs/08-harness-landscape.md).
 
 The trade is portability. Claude Code is the **default and supported host**; Cursor and Copilot are not supported. Everything the loop decides lives in a CLI any host can shell out to, so portability means a second host adapter, not thirty prompt templates.
@@ -79,7 +104,7 @@ The trade is portability. Claude Code is the **default and supported host**; Cur
 
 `interlock-run` drives the same loop over the Claude Code CLI, any [Agent Client Protocol (ACP)](https://agentclientprotocol.com) agent, OpenAI Codex or Qwen Code. You start it yourself. No slash command does, and `/interlock:ship` never falls back to it.
 
-Two things to know before you do. `claude -p`, the Agent SDK and ACP are the usage Anthropic flagged for separate metered credit; the interactive Workflow runtime that `/interlock:ship` uses is the exempted path, and the runner prints which path it is on. And Codex and Qwen do not understand the planner's model tiers, so map them per host with `INTERLOCK_MODEL_MAP`; an unmapped tier is bannered, never silently run on your default.
+Two caveats, both bannered by the runner. `claude -p`, the Agent SDK and ACP are the usage Anthropic flagged for separate metered credit, while the Workflow runtime behind `/interlock:ship` is the exempted path. And Codex and Qwen need the planner's model tiers mapped with `INTERLOCK_MODEL_MAP`; an unmapped tier is bannered, never silently run on your default.
 
 Host table, banners and configuration: [07](docs/07-cli-and-configuration.md#interlock-run--the-experimental-runner). The older `interlock-ship-acp` still works, prints a deprecation line, and is removed in the next minor. Code Mode is out of scope.
 

package/bin/interlock

@@ -104,6 +104,7 @@ import {
 import { writeReviewMetrics } from '../lib/metrics.mjs'
 import {
   planVerification,
+  interWaveVerifyBudget,
   judgeVerification,
   judgeUnitResult,
   clusterFailures,
@@ -652,7 +653,8 @@ verify plan:
   --no-lint              Skip lint
   --pre-existing         The suite was already red before this change
   --elapsed-ms <n>       Verification time already spent this run
-  --budget-ms <n>        Soft budget (default ${LIMITS.interWaveVerifyBudgetMs}ms); past it, typecheck only
+  --budget-ms <n>        Soft budget; past it, typecheck only. The inter-wave default is derived
+                         from the profile and floored at the published budget
   --context <ctx>        ${Object.keys(VERIFY_CONTEXTS).join('|')}. inter-wave omits e2e and
                          coverage by default (typecheck, unit, lint only).
   --changed <files...>   Repo-relative paths the last wave touched. When every
@@ -764,9 +766,12 @@ wave-state:
                                            handoff: { schema: "interlock.wave-handoff/1", taskId,
                                            status: ok|blocked|partial, summary, evidence[], next,
                                            blocker }. A task claiming ok:true without a valid,
-                                           in-budget packet is recorded as failed ("invalid
-                                           handoff: ..."); see "interlock limits" for the cap.
-                                           The next wave's step carries these as previousHandoffs.
+                                           in-budget packet stays recorded as done; the packet
+                                           is rejected, never stored or trimmed, and the outcome
+                                           carries reportRejected with the reason. See
+                                           "interlock limits" for the cap. The next wave's step
+                                           carries valid packets as previousHandoffs and rejected
+                                           ones as previousRejectedReports.
   record-verify --state <f> --result <f>   result: { ok, errors?, blocksNextWave? } or
                                            { skipped: true, reason }
   replan --state <f> --groups <f>          groups: [{ group, tasks: [...] }]
@@ -2575,6 +2580,7 @@ async function main() {
         if (elapsedMs !== undefined) opts.elapsedMs = elapsedMs
         const budgetMs = num(flags, 'budget-ms')
         if (budgetMs !== undefined) opts.budgetMs = budgetMs
+        let budgetSource = budgetMs !== undefined ? 'flag' : 'published'
         const context = flags.context === undefined ? undefined : String(flags.context)
         if (context !== undefined) {
           if (!Object.prototype.hasOwnProperty.call(VERIFY_CONTEXTS, context)) {
@@ -2584,12 +2590,17 @@ async function main() {
           }
           opts.context = context
           if (context === 'inter-wave') opts.coverage = false
+          if (context === 'inter-wave' && profile && budgetMs === undefined) {
+            const derived = interWaveVerifyBudget(profile)
+            opts.budgetMs = derived.ms
+            budgetSource = derived.source
+          }
         }
         if (flags.changed !== undefined) {
           opts.changed = Array.isArray(flags.changed) ? flags.changed : splitPaths(flags.changed)
         }
 
-        const plan = planVerification(profile, opts)
+        const plan = { ...planVerification(profile, opts), budgetSource }
         emit(json, plan, formatVerification(plan))
       } else if (sub === 'judge') {
         const plan = readInput(flags.plan, '--plan <file|->')

package/lib/graph/cli.mjs

@@ -13,7 +13,16 @@ import {
   writeDocsIndex,
 } from './retrieve/docs-index.mjs';
 import { formatDocsResult, retrieveMarkdownSections } from './retrieve/markdown.mjs';
-import { graphPath, reportPath, resolveRoot } from './paths.mjs';
+import {
+  createSkips,
+  formatSkip,
+  graphPath,
+  loadJson,
+  manifestPath,
+  PARTIAL_MARKER,
+  reportPath,
+  resolveRoot,
+} from './paths.mjs';
 import { resolveStateHome } from '../state-home.mjs';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
@@ -78,6 +87,51 @@ function graphRootFor(root) {
   return root;
 }
 
+/**
+ * The root a query command reads its graph from, having said — once, on stderr —
+ * when that graph was built past paths it could not read (graph/unreadable-paths).
+ *
+ * The build named each skipped path when it skipped it. A query runs later, often
+ * in another session, and "no consumers" from a graph that never read the file is
+ * not evidence the file is unused. The count comes from the manifest beside the
+ * graph that is actually loaded, so a query served from the main checkout reports
+ * that graph's skips. A graph built with none, by a version that recorded none, or
+ * beside a manifest that cannot be read prints nothing: the query answers as it
+ * always did, and stdout and the exit code never move.
+ */
+function queryGraphRoot(root) {
+  const from = graphRootFor(root);
+  let recorded;
+  try {
+    recorded = loadJson(manifestPath(from), null)?.skipped;
+  } catch {
+    recorded = null;
+  }
+  if (Array.isArray(recorded) && recorded.length > 0) {
+    process.stderr.write(
+      `${PARTIAL_MARKER}: ${recorded.length} path(s) were unreadable when this graph was built and ` +
+        `are not in it (GRAPH_REPORT.md lists them under "Not indexed") — no result for one of ` +
+        `them is not evidence it is unused; interlock-graph update re-reads them\n`,
+    );
+  }
+  return from;
+}
+
+/**
+ * Name every path the command could not read, one line each on stderr, after
+ * the command's stdout (graph/unreadable-paths). A reader never prints; the
+ * command does, here, so a skip is said once and the exit code does not move.
+ */
+function speakSkips(skips) {
+  for (const entry of skips.list()) process.stderr.write(`${formatSkip(entry)}\n`);
+}
+
+/** ` skipped=<n>` for a summary line, and nothing at all on a clean tree. */
+function skippedField(skips) {
+  const n = skips.list().length;
+  return n > 0 ? ` skipped=${n}` : '';
+}
+
 function parseArgs(argv) {
   const args = {
     _: [],
@@ -142,19 +196,27 @@ function main() {
         break;
       }
       case 'build': {
-        const result = buildGraph(root);
+        const skips = createSkips(root);
+        const result = buildGraph(root, { skips });
         const written = writeGraphArtifacts(root, result);
         process.stdout.write(
           `Built graph → ${written.graphPath}\nReport → ${written.reportPath}\n` +
-            `files=${result.stats.files} nodes=${result.stats.nodes} edges=${result.stats.edges} extractor=${result.stats.extractor}\n`,
+            `files=${result.stats.files} nodes=${result.stats.nodes} edges=${result.stats.edges} extractor=${result.stats.extractor}${skippedField(skips)}\n`,
         );
         // An empty graph is a legitimate outcome — this repo is written in a
         // language the walker does not structurally index. Saying so is the
-        // difference between "unsupported" and "broken".
-        if (result.stats.files === 0) {
+        // difference between "unsupported" and "broken". An empty graph beside
+        // skipped paths is a third thing: blaming the language there would
+        // misname a permissions problem.
+        if (result.stats.files === 0 && skips.list().length > 0) {
+          process.stdout.write(
+            '\nNo source files were indexed: nothing indexable under the root could be read ' +
+              '(each skipped path is named on stderr).\n',
+          );
+        } else if (result.stats.files === 0) {
           process.stdout.write(
             '\nNo source files were indexed. Structural indexing covers ' +
-              '.ts .tsx .js .jsx .mjs .cjs .py .pyi .sh .bash\n' +
+              '.ts .tsx .js .jsx .mjs .cjs .py .pyi .sh .bash .cs .csproj .bicep\n' +
               'plus curated config JSON. Other languages (Go, Rust, Java, Ruby) ' +
               'are not structurally indexed yet:\n' +
               'docs, OpenSpec specs and spec→file links still work, but there ' +
@@ -163,18 +225,22 @@ function main() {
               'prose retrieval on this repo.\n',
           );
         }
+        speakSkips(skips);
         break;
       }
       case 'update': {
-        const result = updateGraph(root);
+        const skips = createSkips(root);
+        const result = updateGraph(root, { skips });
         if (!result.updated) {
-          process.stdout.write(`Graph up to date (${result.reason})\n`);
+          process.stdout.write(`Graph up to date (${result.reason})${skippedField(skips)}\n`);
         } else {
           process.stdout.write(
             `Updated graph (${result.reason})\n` +
-              `files=${result.stats.files} nodes=${result.stats.nodes} edges=${result.stats.edges}\n`,
+              `files=${result.stats.files} nodes=${result.stats.nodes} edges=${result.stats.edges}${skippedField(skips)}\n`,
           );
         }
+        // Said whether or not it rebuilt: a path still unreadable is still not indexed.
+        speakSkips(skips);
         break;
       }
       case 'report': {
@@ -187,7 +253,10 @@ function main() {
           modules: graph.nodes.filter((n) => n.type === 'module').length,
           extractor: graph.graph?.extractor,
         };
-        const report = writeReport(root, graph, stats);
+        // Regenerated from the graph, which holds no skips: the manifest is
+        // their record, so the section survives a re-render.
+        const recorded = loadJson(manifestPath(root), null)?.skipped;
+        const report = writeReport(root, graph, stats, Array.isArray(recorded) ? recorded : []);
         fs.writeFileSync(reportPath(root), report);
         process.stdout.write(report);
         break;
@@ -195,7 +264,7 @@ function main() {
       case 'query': {
         const q = args._.slice(1).join(' ');
         if (!q) throw new Error('query requires a search string');
-        const from = graphRootFor(root);
+        const from = queryGraphRoot(root);
         const graph = loadGraph(from);
         const seeds = findSeedNodes(graph, q);
         if (!seeds.length) {
@@ -214,32 +283,35 @@ function main() {
       case 'consumers': {
         const target = args._.slice(1).join(' ');
         if (!target) throw new Error('consumers requires a symbol or file');
-        process.stdout.write(consumers(loadGraph(graphRootFor(root)), target));
+        process.stdout.write(consumers(loadGraph(queryGraphRoot(root)), target));
         break;
       }
       case 'path': {
         const a = args._[1];
         const b = args._[2];
         if (!a || !b) throw new Error('path requires two endpoints');
-        process.stdout.write(shortestPath(loadGraph(graphRootFor(root)), a, b));
+        process.stdout.write(shortestPath(loadGraph(queryGraphRoot(root)), a, b));
         break;
       }
       case 'explain': {
         const q = args._.slice(1).join(' ');
         if (!q) throw new Error('explain requires a node query');
-        process.stdout.write(explain(loadGraph(graphRootFor(root)), q));
+        process.stdout.write(explain(loadGraph(queryGraphRoot(root)), q));
         break;
       }
       case 'docs': {
         const q = args._.slice(1).join(' ');
         if (!q && args.changed.length === 0) throw new Error('docs requires a query or --changed paths');
+        const skips = createSkips(root);
         const result = retrieveMarkdownSections(root, {
           query: q,
           changedFiles: args.changed,
           dirs: args.dirs ?? undefined,
           budget: defaultBudget('docs', args),
+          skips,
         });
         process.stdout.write(formatDocsResult(result));
+        speakSkips(skips);
         if (result.empty) process.exit(1);
         break;
       }
@@ -248,8 +320,10 @@ function main() {
         if (!q && args.changed.length === 0 && !args.commitSubject) {
           throw new Error('context requires a query, --changed paths, or --commit-subject');
         }
+        const skips = createSkips(root);
         const result = retrieveContext(root, {
-          graphRoot: graphRootFor(root),
+          skips,
+          graphRoot: queryGraphRoot(root),
           query: q,
           changedFiles: args.changed,
           commitSubject: args.commitSubject,
@@ -259,13 +333,16 @@ function main() {
           docsDirs: args.dirs ?? undefined,
         });
         process.stdout.write(formatContextResult(result));
+        speakSkips(skips);
         if (result.empty) process.exit(1);
         break;
       }
       case 'docs-index': {
         const write = args.write !== false;
+        const skips = createSkips(root);
         const { index, path: outPath, written } = writeDocsIndex(root, {
           write,
+          skips,
           // Omit rather than defaulting, so buildDocsIndex can probe for the
           // docs root this repo actually uses (doc/, site/, root README, …).
           dirs: args.dirs ?? undefined,
@@ -274,6 +351,7 @@ function main() {
         if (!written) {
           process.stdout.write(`${JSON.stringify(index, null, 2)}\n`);
         }
+        speakSkips(skips);
         break;
       }
       default:

package/lib/graph/extract/bicep.mjs

@@ -0,0 +1,67 @@
+/**
+ * Regex-based Bicep extractor: module imports, param/var/resource/output
+ * declarations, and `<module>.outputs.<x>` references.
+ */
+
+const MODULE_RE = /^[ \t]*module[ \t]+([A-Za-z_]\w*)[ \t]+'([^'\n]+)'[ \t]*=/;
+const DECL_RE = /^[ \t]*(param|var|resource|output)[ \t]+([A-Za-z_]\w*)\b/;
+const COMMENT_LINE_RE = /^[ \t]*(?:\/\/|\/\*|\*)/;
+
+/**
+ * @param {string} filePath relative posix path
+ * @param {string} source
+ */
+export function extractBicep(filePath, source) {
+  const imports = [];
+  const exports = [];
+  const lines = source.split(/\r?\n/);
+  const modules = new Map(); // module symbolic name -> target as written
+
+  for (let i = 0; i < lines.length; i += 1) {
+    const text = lines[i];
+    if (COMMENT_LINE_RE.test(text)) continue;
+    const line = i + 1;
+    let m = MODULE_RE.exec(text);
+    if (m) {
+      modules.set(m[1], m[2]);
+      imports.push({
+        from: m[2],
+        imported: null,
+        local: m[1],
+        line,
+        confidence: 'EXTRACTED',
+      });
+      continue;
+    }
+    m = DECL_RE.exec(text);
+    if (m) {
+      exports.push({ name: m[2], kind: m[1], line, confidence: 'EXTRACTED' });
+    }
+  }
+
+  if (modules.size > 0) {
+    const seen = new Set();
+    for (let i = 0; i < lines.length; i += 1) {
+      const text = lines[i];
+      if (COMMENT_LINE_RE.test(text)) continue;
+      for (const [name, target] of modules) {
+        const re = new RegExp(`(?<![\\w.])${name}(?:\\[[^\\]]*\\])?\\??\\.outputs\\.([A-Za-z_]\\w*)`, 'g');
+        let m;
+        while ((m = re.exec(text))) {
+          const key = `${name}\0${m[1]}`;
+          if (seen.has(key)) continue;
+          seen.add(key);
+          imports.push({
+            from: target,
+            imported: m[1],
+            local: null,
+            line: i + 1,
+            confidence: 'INFERRED',
+          });
+        }
+      }
+    }
+  }
+
+  return { filePath, imports, exports, references: [] };
+}

package/lib/graph/extract/create-extractor.mjs

@@ -3,6 +3,9 @@ import { createJsExtractor } from './typescript.mjs';
 import { extractPython } from './python.mjs';
 import { extractShell } from './shell.mjs';
 import { extractConfigJson } from './config-json.mjs';
+import { extractCsproj } from './csproj.mjs';
+import { extractCsharp } from './csharp.mjs';
+import { extractBicep } from './bicep.mjs';
 
 /**
  * Language-dispatching extractor. JS/TS uses typescript AST when available.
@@ -29,6 +32,18 @@ export function createExtractor(root) {
         modes.add('json');
         return extractConfigJson(filePath, source);
       }
+      if (ext === '.csproj') {
+        modes.add('csproj');
+        return extractCsproj(filePath, source);
+      }
+      if (ext === '.cs') {
+        modes.add('csharp');
+        return extractCsharp(filePath, source);
+      }
+      if (ext === '.bicep') {
+        modes.add('bicep');
+        return extractBicep(filePath, source);
+      }
       return js.extract(filePath, source);
     },
   };