@phuc1403/musketeer 0.11.0 → 0.12.0

package/README.md

@@ -37,8 +37,8 @@ musketeers are in this project; promote = upgrade the binary._
 | **core** | always on (locked, hidden) | research, handoff, skill-creator, git (+ git-manager agent) · statusline, usage-quota, format-json hooks |
 | **architecture** | off | adr-writer, architecture-characteristic-writer, context-map · CML validation hook |
 | **hallmark** | off | hallmark, hallmark-explore, hallmark-loop · auditor/explorer agents |
-| **code-review** | off | code-review skill + code-reviewer agent |
-| **dotnet** | off | tdd, knowledge-crunching, logical-components · EF migration guard hook · always merges 4 quality-gate props into root `Directory.Build.props` (`MUSKETEER_SKIP_DOTNET_PROPS=1` to skip) · scaffolds a generic `src`/`tests` Clean Architecture skeleton when the project is blank |
+| **code-review** | off | code-review skill + code-reviewer agent · a parallel naming pass on `.cs` diffs when the C# naming rule is installed |
+| **dotnet** | off | tdd, knowledge-crunching, logical-components · C# identifier naming rule (`.claude/rules/`, injected into every subagent by a SubagentStart hook; deleting the file turns it off until the next muster, deselecting dotnet removes it) · EF migration guard hook · always merges 4 quality-gate props into root `Directory.Build.props` (`MUSKETEER_SKIP_DOTNET_PROPS=1` to skip) · scaffolds a generic `src`/`tests` Clean Architecture skeleton when the project is blank |
 | **design-docs** | off | inject-design-docs SessionStart hook |
 
 The muster starts every musketeer **unselected**, except ones you already installed (pre-checked from

package/manifest.json

@@ -171,7 +171,7 @@
     },
     "dotnet": {
       "label": "dotnet",
-      "description": ".NET extras: tdd, knowledge-crunching, logical-components + EF migration-guard & ubiquitous-language auto-load hooks. Muster also always merges 4 quality-gate MSBuild properties into root Directory.Build.props (any dotnet-selected project, set MUSKETEER_SKIP_DOTNET_PROPS=1 to skip) and scaffolds a generic src/tests Clean Architecture skeleton when the project is genuinely blank.",
+      "description": ".NET extras: tdd, knowledge-crunching, logical-components + EF migration-guard & ubiquitous-language auto-load hooks + the C# identifier naming rule (.claude/rules, also injected into every subagent). Muster also always merges 4 quality-gate MSBuild properties into root Directory.Build.props (any dotnet-selected project, set MUSKETEER_SKIP_DOTNET_PROPS=1 to skip) and scaffolds a generic src/tests Clean Architecture skeleton when the project is genuinely blank.",
       "locked": false,
       "deps": [],
       "files": [
@@ -179,7 +179,9 @@
         "skills/knowledge-crunching/**",
         "skills/logical-components/**",
         "hooks/block-migration-edits.cjs",
-        "hooks/inject-ubiquitous-language.cjs"
+        "hooks/inject-ubiquitous-language.cjs",
+        "hooks/inject-naming-rule-into-subagents.cjs",
+        "rules/csharp-identifier-naming.md"
       ],
       "settings": [
         {
@@ -195,6 +197,12 @@
           "command": "node \"${CLAUDE_PROJECT_DIR}/.claude/hooks/inject-ubiquitous-language.cjs\"",
           "order": 1,
           "statusMessage": "Loading ubiquitous language"
+        },
+        {
+          "event": "SubagentStart",
+          "matcher": null,
+          "command": "node \"${CLAUDE_PROJECT_DIR}/.claude/hooks/inject-naming-rule-into-subagents.cjs\"",
+          "order": 1
         }
       ],
       "prereqs": [
@@ -293,7 +301,8 @@
       }
     },
     "dotnet": {
-      "detect": "dotnet --version",
+      "detect": "dotnet --list-sdks",
+      "versionPick": "highest",
       "minVersion": "10",
       "kind": "package",
       "install": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phuc1403/musketeer",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "Distributable custom Claude Code harness — one declarative command scaffolds a curated company of musketeers (skills/agents/hooks) into any project's .claude/.",
   "type": "commonjs",
   "bin": {

package/src/provisioner/detect.js

@@ -29,6 +29,20 @@ function parseVersion(text) {
   return [Number(m[1] || 0), Number(m[2] || 0), Number(m[3] || 0)];
 }
 
+/**
+ * Highest version among the lines that start with one. For list-style detect output such as `dotnet --list-sdks`
+ * ("8.0.100 [path]" per line), where the first match is only the oldest install.
+ */
+function parseHighestVersion(text) {
+  let best = null;
+  for (const line of String(text).split(/\r?\n/)) {
+    if (!/^\s*v?\d/.test(line)) continue;
+    const ver = parseVersion(line);
+    if (ver && (!best || !versionGte(best, ver.join('.')))) best = ver;
+  }
+  return best;
+}
+
 /** found >= min ? (min may be "18" or "3.8") */
 function versionGte(found, min) {
   if (!found) return false;
@@ -75,7 +89,8 @@ function detectPrereq(name, prereq, ctx) {
       let r = run(prereq.detect);
       if (r.code !== 0 && name === 'python') r = run('python3 --version'); // unix fallback
       const out = r.stdout + r.stderr;
-      const ver = parseVersion(out);
+      // `versionPick: "highest"` reads every installed version the detect command lists and keeps the newest.
+      const ver = prereq.versionPick === 'highest' ? parseHighestVersion(out) : parseVersion(out);
       if (r.code !== 0) return { name, present: false, version: null, reason: 'not found' };
       if (prereq.minVersion && !versionGte(ver, prereq.minVersion)) {
         return {
@@ -90,4 +105,4 @@ function detectPrereq(name, prereq, ctx) {
   }
 }
 
-module.exports = { detectPrereq, parseVersion, versionGte, defaultRun, SECRET_ENV };
+module.exports = { detectPrereq, parseVersion, parseHighestVersion, versionGte, defaultRun, SECRET_ENV };

package/src/resolver.js

@@ -5,9 +5,13 @@ const path = require('path');
 
 const CORE_ID = 'core';
 
+// Build output of tools shipped inside skills (a skill's .NET tool builds into bin/ and obj/). A git checkout of the
+// template can hold it; it must never be copied into a project. Mirrors the `!template/**/bin|obj` package excludes.
+const BUILD_OUTPUT_DIRS = new Set(['bin', 'obj']);
+
 /**
  * Recursively list every file under `root`, returned as POSIX-style paths
- * relative to `root` (forward slashes, stable sorted).
+ * relative to `root` (forward slashes, stable sorted), skipping build output dirs.
  * @param {string} root
  * @returns {string[]}
  */
@@ -22,8 +26,9 @@ function listFiles(root) {
     }
     for (const e of entries) {
       const abs = path.join(dir, e.name);
-      if (e.isDirectory()) walk(abs);
-      else if (e.isFile()) out.push(path.relative(root, abs).split(path.sep).join('/'));
+      if (e.isDirectory()) {
+        if (!BUILD_OUTPUT_DIRS.has(e.name)) walk(abs);
+      } else if (e.isFile()) out.push(path.relative(root, abs).split(path.sep).join('/'));
     }
   }
   walk(root);

package/src/schema.js

@@ -39,6 +39,7 @@ const VALID_EVENTS = new Set([
   'SessionStart',
   'SessionEnd',
   'Stop',
+  'SubagentStart',
   'SubagentStop',
   'Notification',
   'PreCompact',

package/template/.claude/hooks/inject-naming-rule-into-subagents.cjs

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+// SubagentStart hook (dotnet company): inject `.claude/rules/csharp-identifier-naming.md`
+// into every subagent. The main session loads the rule itself (an unscoped rule file), but
+// subagents do not: checked on Claude Code 2.1.284, an Explore subagent saw no rule without
+// this hook. The failure the rule exists for came from an agent rewriting many files.
+//
+// A missing rule file injects nothing, silently (muster copies it back on its next run).
+// Any other error fails open (emits nothing, exit 0) so it can never block a subagent.
+const fs = require("fs");
+const path = require("path");
+
+const root = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+const REL = ".claude/rules/csharp-identifier-naming.md";
+const file = path.join(root, ".claude", "rules", "csharp-identifier-naming.md");
+
+try {
+  let content;
+  try {
+    content = fs.readFileSync(file, "utf-8");
+  } catch {
+    process.exit(0); // no rule file: the project opted out
+  }
+
+  // A rule file may carry YAML frontmatter for Claude Code's loader; the subagent needs only the body.
+  const body = content.replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n/, "").trim();
+  if (!body) process.exit(0);
+
+  const additionalContext =
+    `Project naming rule (${REL}) — injected into every subagent. Apply it to any C# you ` +
+    "write or review in this task.\n\n" +
+    body;
+
+  process.stdout.write(
+    JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: "SubagentStart",
+        additionalContext,
+      },
+    })
+  );
+  process.exit(0);
+} catch {
+  process.exit(0); // fail open
+}

package/template/.claude/rules/csharp-identifier-naming.md

@@ -0,0 +1,77 @@
+# C# identifier naming: name it after its type
+
+## The rule
+
+**An identifier is named after its type.** Parameters and locals alike: take the type name, drop a leading `I` on
+an interface, drop generic arguments, camelCase the rest. It reaches result and data types too, not only the
+collaborators you call.
+
+```csharp
+// right
+public sealed class CheckoutPipeline(
+    OrderFetcher orderFetcher,
+    IPaymentGateway paymentGateway,
+    IReceiptPublisher receiptPublisher,
+    TimeSpan deadline,
+    ILogger<CheckoutPipeline> logger)
+
+PricedBasket pricedBasket = basketPricer.Price(basket);   // BasketPricer basketPricer, Basket basket
+var shipmentLabel = new ShipmentLabel(...);
+
+// wrong: each of these names a role, not the thing
+OrderFetcher fetcher, IPaymentGateway gateway, IReceiptPublisher publisher,
+PricedBasket priced, var label
+```
+
+## Why
+
+A component's class is named after the component **so that grepping the name finds every use of it**. A
+role-named identifier defeats that inside every body that holds one: `gateway.Charge(...)` does not match a search
+for `PaymentGateway`. The failure is invisible in review, because each file reads fine on its own. It only shows
+when someone greps for a component, gets an incomplete answer, and believes it.
+
+## Where it stops: three exceptions, and only three
+
+| Exception | Example | Why |
+|---|---|---|
+| Framework and primitive types keep a meaningful name | `TimeSpan deadline`, `TimeSpan budget`, `CancellationToken ct`, `Uri statusUrl`, `int`, `string`, `Stream`, collections | The rule exists to make a name findable. A framework type name carries no domain meaning to find, and `timeSpan` would give a deadline and a per-call budget the same name. |
+| Several instances of one type in one scope | `Coordinate from, Coordinate to`, `Placement inner, Placement outer` | The role *is* the distinguishing information. Never `coordinate1, coordinate2`. |
+| Third-party types | `BlockRecord mark` | Not ours to name; the role says more than `blockRecord`. |
+
+**The test is arity, not taste: one instance of the type in scope → name it after the type; several → let the
+roles distinguish them.** It is decided per site, not per type: a type used as `from`/`to` in one method is still
+`coordinate` in a method that holds only one.
+
+## Boundaries that were tried and are wrong
+
+Both read well and will be re-derived unless stated:
+
+- **Behaviour vs data** ("rename the collaborators you call, leave data types alone"). Wrong: `PricedBasket priced`
+  is exactly as ungreppable as `OrderFetcher fetcher`. Pure data types take the rename too.
+- **Ours vs not quite ours** (by module or ownership). Wrong: every type the repo defines is ours to find.
+
+Arity in scope is the only axis.
+
+## What it costs to skip
+
+- A port was renamed twice; the types followed, the identifiers did not. A constructor read
+  `IOrderRecording legacyOrderStore`, a port named after the component and a parameter named after the mechanism
+  it replaced. A call site still said `legacyOrderStore.Open(...)`, so grepping `OrderRecording` missed it, which
+  was the whole failure the renames were meant to fix.
+- A feature was deleted and rebuilt by an agent from its design document, dozens of new files at once. Every
+  injected collaborator in the rebuilt pipeline came back role-named. The build did not object and review did not
+  catch it; a human noticed while reading one constructor. The convention was only a few commits old at the time.
+
+A rule that lives only in a commit message is a rule the next rewrite will not see. That is why it is written here.
+
+## Renaming safely
+
+Renaming a parameter that a pattern match then rebinds produces `if (labelSpec is { } labelSpec)`: the pattern
+variable shadows the parameter and the build fails (CS0136 for a method parameter; CS9113 and CS0841 for a
+primary-constructor parameter). Rename the pattern variable (or use the parameter directly) in the same edit.
+
+## Enforcement
+
+Deliberately none beyond this rule and the code-review naming pass: no fitness test, no edit hook. A regex over C#
+parameter lists misfires on generics, tuples, defaults and multi-line signatures, and a hook that cries wolf gets
+switched off.

package/template/.claude/skills/code-review/SKILL.md

@@ -64,6 +64,7 @@ Verify before implementing. Ask before assuming. Evidence before claims.
 | Edge case scouting | After implementation, before review | `references/edge-case-scouting.md` |
 | **Checklist review** | Pre-landing, pre-merge, security audit | `references/checklist-workflow.md` |
 | **Task-managed reviews** | Multi-file features (3+ files), parallel reviewers, fix cycles | `references/task-management-reviews.md` |
+| **Naming pass** | Diff touches `.cs` files and `.claude/rules/csharp-identifier-naming.md` exists | `references/naming-rule-review.md` |
 
 ## Quick Decision Tree
 
@@ -83,7 +84,8 @@ SITUATION?
 │   ├─ Stage 1: Spec compliance review (references/spec-compliance-review.md)
 │   │   └─ PASS? → Stage 2 │ FAIL? → Fix → Re-review Stage 1
 │   ├─ Stage 2: Code quality review (code-reviewer subagent)
-│   │   └─ Scout edge cases → Review standards, performance
+│   │   ├─ Scout edge cases → Review standards, performance
+│   │   └─ .cs in diff + naming rule present? → parallel naming pass
 │   └─ Verification gate → Run required tests/builds before claims
 ├─ Completed work (no plan) → Scout → Code quality → Verification
 ├─ Pre-landing / ship → Load checklists → Two-pass review → Verification
@@ -101,6 +103,7 @@ SITUATION?
 **Stage 2 — Code Quality** (code-reviewer subagent)
 - Only runs AFTER spec compliance passes
 - Standards, security, performance, edge cases
+- **Naming pass:** when the diff touches `.cs` files and `.claude/rules/csharp-identifier-naming.md` exists, dispatch a second `code-reviewer` **in the same message** with the prompt in `references/naming-rule-review.md`. A general review samples names; this pass enumerates every declared identifier, which is what catches role-named parameters. Merge its violations into the report under **Naming**.
 
 **Final Verification**
 - Runs AFTER Stage 2 passes

package/template/.claude/skills/code-review/references/naming-rule-review.md

@@ -0,0 +1,41 @@
+# Naming pass — agent prompt
+
+Run as a second `code-reviewer`, in parallel with the main review, when the diff touches `.cs` files and
+`.claude/rules/csharp-identifier-naming.md` exists. Fill `{{...}}` and send the part between the `---` lines.
+
+- `{{DIFF_SCOPE}}`: how to get the diff, exactly as the main review resolved it (`git diff <base>..<head> -- '*.cs'`,
+  `gh pr diff <n>`, `git diff HEAD -- '*.cs'`).
+- `{{RULE_FILE}}`: absolute path of `.claude/rules/csharp-identifier-naming.md`.
+
+---
+
+You review one thing only: whether the C# identifiers **declared in this change** follow the project's naming rule.
+Ignore every other concern; the main review covers them. Never edit files.
+
+1. Read `{{RULE_FILE}}` in full. It defines the rule (an identifier is named after its type), its three exceptions
+   and the arity test. It is the authority; do not apply a stricter or looser version.
+2. Get the change: `{{DIFF_SCOPE}}`. Only identifiers **declared on added or changed lines** are in scope:
+   constructor parameters (including primary constructors), method and lambda parameters, locals (`var` included:
+   use the inferred type), pattern and `foreach` variables, `out var` declarations. Open the file around a
+   declaration when you need the type or the other identifiers in the same scope.
+3. For every in-scope identifier, decide:
+   - **ok**: named after its type (leading `I` dropped, generic arguments dropped, camelCase);
+   - **exempt**: say which exception applies:
+     - framework or primitive type (`TimeSpan deadline`, `CancellationToken ct`, collections);
+     - several instances of the same type in the same scope (`Coordinate from, Coordinate to`). Count per scope,
+       not per type: a single instance is not exempt;
+     - third-party type;
+   - **violation**: give the type-named replacement (`OrderFetcher fetcher` → `orderFetcher`).
+4. For each violation, check whether renaming would collide with another identifier in scope, or with a pattern
+   variable that rebinds it (`x is { } x`: CS0136, or CS9113/CS0841 for a primary-constructor parameter). If so,
+   say so and suggest the rename for that one too.
+
+## Output
+
+Reply with violations only, in file and line order. Nothing else, no summary of the ok/exempt ones:
+
+```
+file:line | identifier | type | suggested name | note (collision, pattern rebind, or empty)
+```
+
+Then one line: `Naming: <n> violations in <m> declarations checked`. If there are none, reply only that line.

package/template/.claude/skills/logical-components/SKILL.md

@@ -13,40 +13,44 @@ Produces `# Logical Components` (name, type, responsibilities with `file:lines`
 **What is deterministic and what is not.** Which classes are components comes from `logical-components.json` in the repo root, written once by classifier agents and reviewed by the user. Every edge comes from Roslyn. Same code plus same config gives the same bytes. Agents write only the responsibility sentences. Each sentence must cite code inside its own component, is checked by a separate verifier agent, and is rejected by `render` if its citation is not real code in that component. Never edit components, edges or the diagram by hand, and never render a document with a component missing.
 
 **Rules the tool applies** (details in `scripts/LogicalComponents/*.cs`):
-- **Candidate:** a top-level class or record (abstract records and record structs included) in an `*.Application` or `*.Infrastructure` project that declares at least one method with a body of its own. It doesn't count: constructors, accessors, operators, partial methods without an implementation, and `ToString`/`Equals`/`GetHashCode` overrides. Excluded: interfaces and abstract classes (seams), DI setup classes, `*Options`, exceptions, `file` classes, nested types.
+- **Candidate:** a top-level class or record (abstract records and record structs included) in an `*.Application` or `*.Infrastructure` project (or one named exactly `Application`/`Infrastructure`; matched case-insensitively) that declares at least one method with a body of its own. It doesn't count: constructors, accessors, operators, partial methods without an implementation, `extern`/`[DllImport]`/`[LibraryImport]` methods, and `ToString`/`Equals`/`GetHashCode` overrides. Excluded: interfaces and abstract classes (seams), DI setup classes (static classes extending `IServiceCollection`, `IHostApplicationBuilder`, `WebApplicationBuilder` or `IHostBuilder`, and Autofac modules overriding `Load`), `*Options`, exceptions, `file` classes, nested types, and files under `obj/` or `bin/` (build output). When no project matches either layer, `candidates` warns.
 - **Component or helper:** judged once per candidate by classifier agents with `references/component-classifier-prompt.md`, then frozen in `logical-components.json` as `{ "components": [full type names], "helpers": { full type name: reason } }`. A component decides or enforces a rule, coordinates, does I/O, or owns state. A helper converts formats, looks things up, holds data, delegates, or is a value object (even a self-validating one). A candidate in neither list stops `extract` (exit 4).
 - **Edge A → B** (A depends on B):
   - `di`: a constructor parameter, looked through `IEnumerable`/lists/`Lazy`/`Func`/arrays;
-  - `new` (an object creation, or a `: this(...)`/`: base(...)` constructor call), `static` (a static member, an extension, a user-defined operator or conversion; const reads excluded), `call` (an instance member used on any receiver: parameter, local, field, returned value, an indexer, the enumerator a `foreach` runs);
+  - `new` (an object creation, or a `: this(...)`/`: base(...)` constructor call), `static` (a static member, an extension, a user-defined operator or conversion; const reads excluded), `call` (an instance member used on any receiver: parameter, local, field, returned value, an indexer including `x?[i]`, and what the compiler calls for you: the enumerator's `GetEnumerator`/`MoveNext`/`Current` a `foreach` runs, the `Deconstruct` a deconstruction runs, the `Add` a collection initializer runs, and `GetAwaiter`/`IsCompleted`/`GetResult` for an `await`). A seen-through type's static constructor is walked with its first static use or construction, like its static field initializers;
   - `inherits`.
-  - Interfaces and abstract classes resolve to the member that runs in each implementation of the construction used. A class implementing `IHandler<Ping>` and `IHandler<Pong>` runs its Pong member for a Pong call.
+  - Interfaces and abstract classes resolve to the member that runs in each implementation of the construction used. A class implementing `IHandler<Ping>` and `IHandler<Pong>` runs its Pong member for a Pong call. Type arguments carry through the seam: a generic `IDispatch.Send<T>` called with `Ping` reaches only the Ping handlers of the implementation that runs.
+  - A non-virtual member of an abstract class runs as written, so it is walked directly. An abstract or virtual member with no implementation in the repo gives an `extract` warning.
   - Helpers, records and other non-component types are **seen through**, following only the code that runs for the use. That means the member A calls, only the getter for a read or the setter for a write, and the constructor, initializers and base constructor for a `new`. Whatever that code reaches is A's. So:
     - reading one property of a record never couples A to what another property or a setter calls;
     - compiler-written record members (`ToString`, `Equals`) run nothing;
-    - a generic helper is walked with its type parameters bound to A's type arguments, so a dispatcher called with `Ping` reaches only the Ping handlers.
-  - `via` in `components.json` lists the seams and seen-through types on the first path found to each target.
+    - a generic helper is walked with its type parameters bound to A's type arguments, so a dispatcher called with `Ping` reaches only the Ping handlers. A component's generic base class is walked with its type parameters bound too (`PingRunner : HandlerBase<Ping>`).
+    - a generic helper that instantiates itself one level deeper at every call is cut off at a fixed depth, with a warning.
+  - `via` in `components.json` lists the seams and seen-through types on the first path found to each target, in path order, by simple name (full name when two types on the path share one).
   - **Not followed:**
     - overrides of virtual members of concrete classes;
     - static abstract interface members;
     - `Dispose` run by `using`;
-    - implicit user-defined conversions.
+    - implicit user-defined conversions;
+    - attributes (an attribute's constructor runs only when something reads it through reflection).
 - **Reaches:** the helper members a component's code runs are recorded as its `reaches` spans. A rule held in a helper, such as `SrcPath` rejecting paths outside the imports root, is described in the responsibilities of the component that runs it, citing the helper's lines. `render` accepts citations inside a component's own `spans` or its `reaches`. A helper only the DI setup touches is reached by no component, so it appears nowhere. `render` rejects a citation over 60 lines; the prompts ask for at most 30, leaving room for a writer's off-by-a-few ranges.
 
 ## Arguments
 
 - `<repoPath>`: the repo root (holds the `.sln`/`.slnx`, or `src/`). Required.
 - `--out <md>`: default `<repoPath>/docs/logical-components.generated.md`. Never write over a hand-written `docs/logical-components.md` unless the user names it.
-- `--agents <n>`: agents per wave, default 9.
+- `--agents <n>`: agents per wave, default 9. Pass it as `$AGENTS` wherever the steps say `--agents`.
+- `--solution <file>`: the solution to load (relative to `<repoPath>`, or absolute). Required when the repo root holds more than one solution; pass it to both `candidates` and `extract`.
 
 ## Run
 
-Set `SKILL` to this skill's directory, `REPO` to the repo root, and `WORK` to a fresh per-run directory outside the repo (`WORK="$(mktemp -d)"`). All work files live in `WORK`. Nothing is written into the repo except `logical-components.json` (by the classify step, after the user's review) and `--out`.
+Set `SKILL` to this skill's directory, `REPO` to the repo root, `OUT` to `--out` (default `$REPO/docs/logical-components.generated.md`), `AGENTS` to `--agents` (default 9), `SOL` to `--solution <file>` when given (else empty), and `WORK` to a fresh per-run directory outside the repo (`WORK="$(mktemp -d)"`). All work files live in `WORK`. Nothing is written into the repo except `logical-components.json` (by the classify step, after the user's review) and `--out`.
 
 1. **Build the tool once** (skip if the dll is newer than the sources):
-   `(cd "$SKILL/scripts" && dotnet build LogicalComponents -c Release -nologo -v q)`. Build from inside `scripts/`: its `global.json`, `Directory.Build.props` and `Directory.Packages.props` keep the repo's own SDK pin, build settings and central package versions away from the tool. Then use `LC="dotnet $SKILL/scripts/LogicalComponents/bin/Release/net10.0/LogicalComponents.dll"`.
-2. **Candidates:** `$LC candidates "$REPO" --out "$WORK/candidates.json"`. Its last line counts the components, helpers and unclassified candidates. With 0 unclassified, skip to step 4.
+   `(cd "$SKILL/scripts" && dotnet build LogicalComponents -c Release -nologo -v q)`. Build from inside `scripts/`: its `global.json`, `Directory.Build.props`/`.targets`/`.rsp`, `Directory.Packages.props` and `NuGet.config` keep the repo's own SDK pin, build settings, central package versions and package feeds away from the tool. Then use `LC="dotnet $SKILL/scripts/LogicalComponents/bin/Release/net10.0/LogicalComponents.dll"`.
+2. **Candidates:** `$LC candidates "$REPO" --out "$WORK/candidates.json" $SOL`. Its last line counts the components, helpers and unclassified candidates. With 0 unclassified, skip to step 4.
 3. **Classify** (only the unclassified candidates):
-   1. `$LC classify-batches --candidates "$WORK/candidates.json" --agents 9 --repo "$REPO" --out "$WORK/classify"`. It also records the config's hash.
+   1. `$LC classify-batches --candidates "$WORK/candidates.json" --agents $AGENTS --repo "$REPO" --out "$WORK/classify"`. It also records the config's hash and skips any candidate the current config already classifies (so a stale `candidates.json` can't resend one).
    2. Empty `$WORK/verdicts` (create it if needed), then spawn one `Agent` per `classify/batch-NN.json`, **all in one message**. Prompt: `references/component-classifier-prompt.md` (the part between the `---` lines), with `{{REPO}}`, `{{BATCH_FILE}}` and `{{OUT_FILE}}` = `$WORK/verdicts/batch-NN.json`.
    3. `$LC classify-merge --batches "$WORK/classify" --verdicts "$WORK/verdicts" --repo "$REPO"`. It checks the agents' output against the batches before writing anything:
       - one verdict file per batch;
@@ -57,27 +61,28 @@ Set `SKILL` to this skill's directory, `REPO` to the repo root, and `WORK` to a
 
       It also checks that the config is unchanged since step 3.1.
       - Exit 3 lists every problem. For a batch's own problems, re-run that batch's agent once, then merge again. If the config changed, stop and tell the user: something edited it outside the review.
-      - Exit 2: the existing config can't be read. Exit 1: usage, or a directory is missing.
-      - It never changes an entry that is already in the file. Rewriting the file drops any `//` comments in it.
+      - Exit 2: the existing config or a batch file can't be read. Exit 1: usage, or a directory is missing.
+      - It never changes an entry that is already in the file: a verdict for a type the config already classifies is an exit-3 problem (re-run step 2). Rewriting the file drops any `//` comments in it.
    4. **Review gate:** show the user every line merge printed (helpers with reasons first, then components; the tool checked each is one plain line) and ask with `AskUserQuestion`:
       - accept;
       - "I'll edit `logical-components.json` first", then wait for them.
 
       Do not continue without an answer. This file decides what the document contains.
-4. **Extract:** `$LC extract "$REPO" --out "$WORK/components.json"`.
+4. **Extract:** `$LC extract "$REPO" --out "$WORK/components.json" $SOL`. It also records a hash of every file a component cites or runs, so `render` can tell when the repo changed since.
    - Exit 4: `unclassified <type>` lines mean candidates are still missing from the config. Run step 2 again, then step 3 for those candidates only.
    - Any other non-zero exit: stop and show stderr.
    - Keep the `warning:` lines for the final report. `config entry ... names no candidate` means a class was renamed or deleted: tell the user.
-5. **Batch:** `$LC batches --components "$WORK/components.json" --agents 9 --out "$WORK/batches"`.
+5. **Batch:** `$LC batches --components "$WORK/components.json" --agents $AGENTS --out "$WORK/batches"`.
 6. **Writers:** one `Agent` per `batches/batch-NN.json`, **all in one message**, with no `model` override (a cheaper writer model produced false claims). Prompt: `references/responsibility-agent-prompt.md` (the part between the `---` lines, without `## Repair`), with `{{REPO}}`, `{{BATCH_FILE}}` = `$WORK/batches/batch-NN.json`, `{{OUT_FILE}}` = `$WORK/resp/batch-NN.json`. Create `$WORK/resp` first.
-7. **Verifiers:** one `Agent` per `resp/batch-NN.json`, all in one message. Prompt: `references/responsibility-verifier-prompt.md` with `{{RESP_FILE}}`, `{{OUT_FILE}}` = `$WORK/verify/batch-NN.json`.
+7. **Verifiers:** one `Agent` per `resp/batch-NN.json`, all in one message. Prompt: `references/responsibility-verifier-prompt.md` with `{{REPO}}`, `{{RESP_FILE}}` = `$WORK/resp/batch-NN.json`, `{{OUT_FILE}}` = `$WORK/verify/batch-NN.json`.
 8. **Prune:** `$LC prune --resp "$WORK/resp" --verify "$WORK/verify" --out "$WORK/pruned"`.
-   - Exit 3 (a verdict missing or malformed): re-run the verifier of the named batches once, then prune again.
+   - Exit 3 (a verdict missing or malformed, including an entry without `supported`): re-run the verifier of the named batches once, then prune again.
    - Every `removed <id>[<n>]: <reason>` line goes to the repair round, including `empty <id>` lines (components that lost every claim). This covers components that lost only some of their claims.
 9. **Render:** `$LC render --components "$WORK/components.json" --resp "$WORK/pruned" --repo "$REPO" --out "$OUT"`.
    - Exit 0: done, unless step 8 produced `removed` lines. Then run the repair round before calling it done.
    - Exit 3: every line starts with a component id. Those components go to the repair round.
-   - Exit 2: inputs do not match (the repo changed since extract, or a path is missing). Stop and report; this is not the agents' fault.
+   - Exit 2: inputs do not match: a cited file changed or went missing since extract (one line each), `components.json` predates the file hashes, or a path is missing. Re-run from step 4 if the repo changed on purpose; otherwise stop and report. This is not the agents' fault.
+   - `render` writes `--out` only on success; a failed render never touches an existing file.
 
 **Repair round (at most once per run).**
 1. Collect the problem lines per batch: the `removed`/`empty` lines from prune and the render exit-3 lines. `$WORK/batches` shows which batch each component is in.

package/template/.claude/skills/logical-components/references/component-classifier-prompt.md

@@ -37,7 +37,7 @@ When in doubt: if removing the class and inlining its code into its callers woul
 
 ## Reason and citation
 
-- `reason`: one sentence, at most 200 characters, saying what in the code decides it: "Rejects a callback URL outside the allowed hosts." or "Maps `LayerColor` values to names; no decision."
+- `reason`: one plain sentence, at most 200 characters, no control or invisible characters (it is shown to the reviewer verbatim), saying what in the code decides it: "Rejects a callback URL outside the allowed hosts." or "Maps `LayerColor` values to names; no decision."
 - `cite`: `<file>:<start>-<end>` (or `<file>:<line>`), `file` copied exactly from the candidate's `spans`, at most 30 lines, showing the reason.
 
 ## Output

package/template/.claude/skills/logical-components/references/responsibility-agent-prompt.md

@@ -25,7 +25,7 @@ You write the responsibilities of a few logical components of a .NET codebase, s
 - Not a restatement of fields, properties or parameters. Not what a collaborator does: `uses` is context; you may say the component hands work to X only when the cited lines make that call.
 - A rule inside `reaches` (a check, a limit, a decision the helper makes when this component calls it) is part of what this component does. Describe it as this component's behaviour and name the helper: "Rejects a source path that leaves the imports root (through `SrcPath`)." Skip helper code that only formats or holds data.
 - Cover the component's main behaviour first. Prefer fewer precise sentences over many vague ones; do not repeat yourself.
-- Plain text, at most 300 characters, one line. Put code names in backticks (`LayerTitle`, `List<Feature>`). No HTML, no links, no markdown other than backticks.
+- Plain text, at most 300 characters, one line, no control or invisible characters (bidi overrides, zero-width, line separators). Put code names in backticks (`LayerTitle`, `List<Feature>`). No HTML, no links, no markdown other than backticks. Outside backticks, never write a backslash, `<`, `>`, `[`, `]` or a URL (`://`, `www.`); `render` rejects them.
 - Name a technology or library only when the code is about it.
 - Never quote literals that look like credentials, keys, tokens, passwords or connection strings; describe what the code does with them instead.
 

package/template/.claude/skills/logical-components/scripts/Directory.Build.rsp

@@ -0,0 +1 @@
+# Stops MSBuild picking up a host repo's Directory.Build.rsp (extra command-line switches) for the tool.

package/template/.claude/skills/logical-components/scripts/Directory.Build.targets

@@ -0,0 +1,6 @@
+<Project>
+  <!--
+    MSBuild searches upward for Directory.Build.targets separately from Directory.Build.props. This file stops that
+    search here too, so a host repo's targets (extra checks, custom errors) never reach the tool.
+  -->
+</Project>

package/template/.claude/skills/logical-components/scripts/LogicalComponents/BatchPlanning.cs

@@ -31,7 +31,8 @@ public static class BatchPlanning
         var names = extraction.Components.Select(c => (c.Id, c.Name))
             .Concat(extraction.ExternalNodes.Select(n => (n.Id, n.Name)))
             .ToDictionary(n => n.Id, n => n.Name, StringComparer.Ordinal);
-        var size = (extraction.Components.Count + maxAgents - 1) / maxAgents;
+        // Clamp to at least 1: with an enormous --agents, Count + maxAgents - 1 can overflow int and wrap negative.
+        var size = Math.Max(1, (extraction.Components.Count + maxAgents - 1) / maxAgents);
 
         return extraction.Components
             .Select(c => new BatchComponent(

package/template/.claude/skills/logical-components/scripts/LogicalComponents/BatchesCommand.cs

@@ -4,7 +4,8 @@ namespace LogicalComponents;
 
 /// <summary>
 /// <c>batches --components &lt;components.json&gt; --agents &lt;n&gt; --out &lt;dir&gt;</c>: writes one <c>batch-NN.json</c> agent
-/// input per batch (see <see cref="BatchPlanning"/>). Exit codes: 0 written, 1 usage, 2 unreadable components.json.
+/// input per batch (see <see cref="BatchPlanning"/>). Exit codes: 0 written, 1 usage, 2 components.json is unreadable
+/// or not one extract wrote.
 /// </summary>
 public static class BatchesCommand
 {
@@ -30,6 +31,13 @@ public static class BatchesCommand
             return 2;
         }
 
+        // Deserialization leaves absent lists null despite the non-nullable types: `{}` is not a components.json.
+        if (extraction.Components is null || extraction.ExternalNodes is null || extraction.Edges is null)
+        {
+            await output.WriteLineAsync($"{componentsPath} is not a components.json written by extract");
+            return 2;
+        }
+
         var batches = BatchPlanning.Plan(extraction, agents);
         BatchPlanning.Write(batches, outDir);
         await output.WriteLineAsync(

package/template/.claude/skills/logical-components/scripts/LogicalComponents/CandidatesCommand.cs

@@ -1,13 +1,16 @@
 namespace LogicalComponents;
 
 /// <summary>
-/// <c>candidates &lt;repoPath&gt; [--out &lt;candidates.json&gt;]</c>: lists every candidate with where it is declared and how
-/// the repo config classifies it (<c>component</c>, <c>helper</c> or <c>unclassified</c>), for the classify step.
+/// <c>candidates &lt;repoPath&gt; [--out &lt;candidates.json&gt;] [--solution &lt;file&gt;]</c>: lists every candidate with where
+/// it is declared and how the repo config classifies it (<c>component</c>, <c>helper</c> or <c>unclassified</c>), for
+/// the classify step. <c>--solution</c> picks the solution file to load (relative to repoPath, or absolute) instead of
+/// searching the repo root; it is required when the repo root has more than one top-level solution.
 /// Progress goes to <c>errors</c> (stderr). Exit codes: 0 written, 1 usage, 2 the repo or its config could not be loaded.
 /// </summary>
 public static class CandidatesCommand
 {
-    public const string Usage = "usage: LogicalComponents candidates <repoPath> [--out <candidates.json>]";
+    public const string Usage =
+        "usage: LogicalComponents candidates <repoPath> [--out <candidates.json>] [--solution <file>]";
 
     public const string Component = "component";
     public const string Helper = "helper";
@@ -19,21 +22,15 @@ public static class CandidatesCommand
 
     public static async Task<int> RunAsync(string[] args, TextWriter errors)
     {
-        var outPath = "candidates.json";
-        if (args is not [var repoPath, ..] || args[1..] is not ([] or ["--out", _]))
+        if (args is not [var repoPath, ..] || !TryParseOptions(args[1..], "candidates.json", out var outPath, out var solution))
         {
             await errors.WriteLineAsync(Usage);
             return 1;
         }
 
-        if (args is [_, "--out", var given])
-        {
-            outPath = given;
-        }
-
         try
         {
-            using var loaded = await WorkspaceLoader.LoadAsync(repoPath, log: errors);
+            using var loaded = await WorkspaceLoader.LoadAsync(repoPath, solution: solution, log: errors);
             var file = await ListAsync(loaded, ExtractConfig.Load(loaded.RepoRoot));
             Directory.CreateDirectory(Path.GetDirectoryName(Path.GetFullPath(outPath))!);
             await File.WriteAllBytesAsync(outPath, ComponentsFile.ToJson(file));
@@ -67,4 +64,35 @@ public static class CandidatesCommand
 
     private static string Status(ExtractConfig config, string type) =>
         config.Helpers.ContainsKey(type) ? Helper : config.Components.Contains(type) ? Component : Unclassified;
+
+    /// <summary>
+    /// <c>--out</c> and <c>--solution</c>, in either order; each takes exactly one value. Shared with <c>extract</c>,
+    /// which loads the repo the same way.
+    /// </summary>
+    internal static bool TryParseOptions(string[] options, string defaultOut, out string outPath, out string? solution)
+    {
+        outPath = defaultOut;
+        solution = null;
+        for (var i = 0; i < options.Length; i += 2)
+        {
+            if (i + 1 >= options.Length)
+            {
+                return false;
+            }
+
+            switch (options[i])
+            {
+                case "--out":
+                    outPath = options[i + 1];
+                    break;
+                case "--solution":
+                    solution = options[i + 1];
+                    break;
+                default:
+                    return false;
+            }
+        }
+
+        return true;
+    }
 }

package/template/.claude/skills/logical-components/scripts/LogicalComponents/CitableSource.cs

@@ -10,7 +10,10 @@ public static class CitableSource
 {
     public enum Kind
     {
-        /// <summary>Not a project document, or generator output under obj/: never cited, silently skipped.</summary>
+        /// <summary>
+        /// Not a project document, a source generator's virtual output, or a real file under a bin/ or obj/ folder
+        /// (gRPC/NSwag output, a stray build copy): never cited, silently skipped.
+        /// </summary>
         NotSource,
 
         /// <summary>A real file outside the repo root (linked file, other drive): cannot be cited portably.</summary>
@@ -28,11 +31,23 @@ public static class CitableSource
         }
 
         var relative = Path.GetRelativePath(loaded.RepoRoot, tree.FilePath);
-        return Path.IsPathRooted(relative) || relative.StartsWith("..")
-            ? (Kind.OutsideRepo, "")
-            : (Kind.InRepo, relative.Replace('\\', '/'));
+        if (Path.IsPathRooted(relative) || relative.StartsWith(".."))
+        {
+            return (Kind.OutsideRepo, "");
+        }
+
+        return IsBuildOutputPath(relative) ? (Kind.NotSource, "") : (Kind.InRepo, relative.Replace('\\', '/'));
     }
 
+    /// <summary>
+    /// True when any path segment is <c>bin</c> or <c>obj</c>, case-insensitively: build output is never real source,
+    /// whether it is design-time generator output (gRPC, NSwag) or a build step's stray copy of a project file.
+    /// Shared with <see cref="WorkspaceLoader"/>'s project-file discovery so the two never disagree.
+    /// </summary>
+    public static bool IsBuildOutputPath(string relativePath) =>
+        relativePath.Split('/', '\\').Any(segment =>
+            segment.Equals("bin", StringComparison.OrdinalIgnoreCase) || segment.Equals("obj", StringComparison.OrdinalIgnoreCase));
+
     /// <summary>Declared in a real document of the loaded solution (not metadata, not generator output).</summary>
     public static bool IsRepoSource(Microsoft.CodeAnalysis.INamedTypeSymbol type, LoadedWorkspace loaded) =>
         type.Locations.Any(l => l.IsInSource && Classify(loaded, l.SourceTree).Kind != Kind.NotSource);