@phuc1403/musketeer 0.11.0 → 0.12.0

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

@@ -6,9 +6,11 @@ namespace LogicalComponents;
 /// <summary>
 /// <c>classify-batches --candidates &lt;candidates.json&gt; --agents &lt;n&gt; --repo &lt;repoPath&gt; --out &lt;dir&gt;</c>: splits
 /// the candidates the config does not classify yet into at most n equal batches, in candidates.json order, one
-/// <c>batch-NN.json</c> per classifier agent. Already classified candidates are never sent again. It also records the
-/// repo config's hash, so classify-merge can refuse to merge if anything edited the config in between.
-/// Exit codes: 0 written, 1 usage, 2 unreadable candidates.json.
+/// <c>batch-NN.json</c> per classifier agent. Already classified candidates are never sent again: the repo config is
+/// read fresh here (not trusted from candidates.json's own status), so a stale candidates.json - written before an
+/// earlier classify-merge - cannot resend a type that is already reviewed. It also records the repo config's hash, so
+/// classify-merge can refuse to merge if anything edited the config in between.
+/// Exit codes: 0 written, 1 usage, 2 unreadable candidates.json or repo config.
 /// </summary>
 public static class ClassifyBatchesCommand
 {
@@ -42,8 +44,27 @@ public static class ClassifyBatchesCommand
             return 2;
         }
 
+        if (file.Candidates is null)
+        {
+            await output.WriteLineAsync($"{candidatesPath} is not a candidates.json written by the candidates command");
+            return 2;
+        }
+
+        ExtractConfig config;
+        try
+        {
+            config = ExtractConfig.Load(repo);
+        }
+        catch (ExtractConfigException e)
+        {
+            await output.WriteLineAsync(e.Message);
+            return 2;
+        }
+
+        // c.Status reflects the config at candidates time; re-check against the config now in case it changed since
+        // (classify-merge could have classified some of these candidates in an earlier round).
         var unclassified = file.Candidates
-            .Where(c => c.Status == CandidatesCommand.Unclassified)
+            .Where(c => c.Status == CandidatesCommand.Unclassified && !config.IsClassified(c.Type))
             .Select(c => new ClassifyCandidate(c.Type, c.Layer, c.Module, c.Spans))
             .ToList();
         var size = Math.Max(1, (unclassified.Count + agents - 1) / agents);

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

@@ -7,11 +7,12 @@ namespace LogicalComponents;
 /// (<c>verdicts/batch-NN.json</c>: <c>[{ type, verdict: component|helper, reason, cite }]</c>) to the repo's
 /// <c>logical-components.json</c>. The agents' output is checked against the batches they were given before anything is
 /// written: one verdict file per batch and none left over, exactly one verdict per candidate of the batch and no other
-/// type, a known verdict, a one-line reason under 200 characters, and a citation inside the candidate's declaration.
+/// type, a known verdict, a one-line reason under 200 characters, a citation inside the candidate's declaration, and a
+/// type the config does not already classify (a stale candidates.json could otherwise resend an already-reviewed type).
 /// The config must be unchanged since classify-batches, so nothing can slip an entry past the review.
 /// Prints each added entry (helpers first, for review) and a summary on <c>output</c>.
-/// Exit codes: 0 written, 1 usage, 2 the existing config is unreadable, 3 the verdicts break the contract or the config
-/// changed (every problem listed, nothing written).
+/// Exit codes: 0 written, 1 usage, 2 the existing config or a batch file is unreadable, 3 the verdicts break the
+/// contract or the config changed (every problem listed, nothing written).
 /// </summary>
 public static class ClassifyMergeCommand
 {
@@ -22,6 +23,9 @@ public static class ClassifyMergeCommand
 
     private sealed record VerdictJson(string? Type, string? Verdict, string? Reason, string? Cite);
 
+    /// <summary>A batch file from classify-batches could not be read: an environment/tooling problem, not the agents' fault.</summary>
+    private sealed class MalformedBatchException(string message) : Exception(message);
+
     public static async Task<int> RunAsync(string[] args, TextWriter output)
     {
         if (args is not ["--batches", var batchDir, "--verdicts", var verdictDir, "--repo", var repo]
@@ -49,7 +53,17 @@ public static class ClassifyMergeCommand
             problems.Add($"{ExtractConfig.FileName} changed since classify-batches; review that change, then batch again");
         }
 
-        var verdicts = Check(batchDir, verdictDir, problems);
+        List<VerdictJson> verdicts;
+        try
+        {
+            verdicts = Check(batchDir, verdictDir, existing, problems);
+        }
+        catch (MalformedBatchException e)
+        {
+            await output.WriteLineAsync(e.Message);
+            return 2;
+        }
+
         if (problems.Count > 0)
         {
             foreach (var problem in problems)
@@ -94,7 +108,8 @@ public static class ClassifyMergeCommand
     }
 
     /// <summary>Every verdict of every batch, or problems (in batch file order) when the agents' output breaks the contract.</summary>
-    private static List<VerdictJson> Check(string batchDir, string verdictDir, List<string> problems)
+    /// <exception cref="MalformedBatchException">A batch file itself (written by classify-batches, not an agent) is not valid JSON.</exception>
+    private static List<VerdictJson> Check(string batchDir, string verdictDir, ExtractConfig existing, List<string> problems)
     {
         var batchFiles = Directory.EnumerateFiles(batchDir, "batch-*.json").Select(Path.GetFileName).OfType<string>()
             .Order(StringComparer.Ordinal).ToList();
@@ -106,7 +121,16 @@ public static class ClassifyMergeCommand
         var all = new List<VerdictJson>();
         foreach (var name in batchFiles)
         {
-            var batch = ComponentsFile.FromJson<ClassifyBatchesCommand.ClassifyBatch>(File.ReadAllBytes(Path.Combine(batchDir, name)));
+            ClassifyBatchesCommand.ClassifyBatch batch;
+            try
+            {
+                batch = ComponentsFile.FromJson<ClassifyBatchesCommand.ClassifyBatch>(File.ReadAllBytes(Path.Combine(batchDir, name)));
+            }
+            catch (Exception e) when (e is IOException or UnauthorizedAccessException or JsonException)
+            {
+                throw new MalformedBatchException($"{name}: not a valid batch file ({e.Message})");
+            }
+
             var verdictPath = Path.Combine(verdictDir, name);
             if (!File.Exists(verdictPath))
             {
@@ -137,7 +161,7 @@ public static class ClassifyMergeCommand
                 {
                     problems.Add($"{name}: {group.Key}: more than one verdict");
                 }
-                else if (Problem(group.Single(), candidate) is { } problem)
+                else if (Problem(group.Single(), candidate, existing) is { } problem)
                 {
                     problems.Add($"{name}: {group.Key}: {problem}");
                 }
@@ -151,8 +175,15 @@ public static class ClassifyMergeCommand
         return all;
     }
 
-    private static string? Problem(VerdictJson verdict, ClassifyBatchesCommand.ClassifyCandidate candidate)
+    private static string? Problem(VerdictJson verdict, ClassifyBatchesCommand.ClassifyCandidate candidate, ExtractConfig existing)
     {
+        // Never overwrite a reviewed entry: a stale candidates.json could otherwise resend an already-classified type
+        // and have its verdict silently replace the reviewed reason, or put the type in both lists.
+        if (existing.IsClassified(candidate.Type))
+        {
+            return $"already classified in {ExtractConfig.FileName}; re-run candidates";
+        }
+
         if (verdict.Verdict is not (CandidatesCommand.Component or CandidatesCommand.Helper))
         {
             return "verdict must be component or helper";
@@ -163,8 +194,9 @@ public static class ClassifyMergeCommand
             return "reason is empty";
         }
 
-        // The reason is printed at the review gate and stored in the config: one plain line, so it cannot fake other lines.
-        if (verdict.Reason.Any(char.IsControl))
+        // The reason is printed at the review gate and stored in the config: one plain line, so it cannot fake other
+        // lines or hide a bidi/zero-width character in what looks like a normal sentence.
+        if (PlainText.HasDisallowedUnicode(verdict.Reason))
         {
             return "reason has control characters";
         }
@@ -183,5 +215,5 @@ public static class ClassifyMergeCommand
     }
 
     // An unknown type is agent text: print it without anything that could start a new line at the review gate.
-    private static string Printable(string text) => new(text.Select(c => char.IsControl(c) ? '?' : c).ToArray());
+    private static string Printable(string text) => new(text.Select(c => PlainText.IsDisallowed(c) ? '?' : c).ToArray());
 }

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

@@ -18,7 +18,15 @@ public static class ComponentDiscovery
     public static async Task<CandidateList> CandidatesAsync(LoadedWorkspace loaded, CancellationToken cancellationToken = default)
     {
         var warnings = new List<string>();
-        var candidates = (await SourceTypesAsync(loaded.Solution, cancellationToken))
+        var types = await SourceTypesAsync(loaded.Solution, cancellationToken);
+        if (types.All(t => t.Layer is not (ApplicationLayer or InfrastructureLayer)))
+        {
+            // Nothing to classify is easy to miss: an empty document with no explanation looks like success.
+            warnings.Add(
+                $"no {ApplicationLayer} or {InfrastructureLayer} project found among: {string.Join(", ", loaded.ProjectNames)}");
+        }
+
+        var candidates = types
             .Where(t => t.Layer is (ApplicationLayer or InfrastructureLayer) && ComponentRule.IsCandidate(t.Symbol))
             .Select(t => ToComponent(t, loaded, warnings))
             .OfType<Component>()
@@ -64,13 +72,19 @@ public static class ComponentDiscovery
 
     /// <summary>
     /// <c>WorkerDwg.Export.Application</c> → (Application, Export); <c>Sample.Infrastructure</c> → (Infrastructure, Sample);
-    /// any other project → (Other, its last name segment).
+    /// a bare <c>Application</c>/<c>Infrastructure</c> project → that layer, itself as its module; matched
+    /// case-insensitively, so <c>Foo.application</c> counts too. Any other project → (Other, its last name segment).
     /// </summary>
     public static (string Layer, string Module) LayerAndModule(string projectName)
     {
         foreach (var layer in new[] { ApplicationLayer, InfrastructureLayer })
         {
-            if (projectName.EndsWith("." + layer, StringComparison.Ordinal))
+            if (string.Equals(projectName, layer, StringComparison.OrdinalIgnoreCase))
+            {
+                return (layer, projectName);
+            }
+
+            if (projectName.EndsWith("." + layer, StringComparison.OrdinalIgnoreCase))
             {
                 var rest = projectName[..^(layer.Length + 1)];
                 return (layer, rest[(rest.LastIndexOf('.') + 1)..]);
@@ -119,9 +133,9 @@ public static class ComponentDiscovery
     }
 
     /// <summary>
-    /// The component for a type, with spans from real source files inside the repo only. Generator output (under obj/)
-    /// is skipped silently; a declaration outside the repo cannot be cited, so it is skipped with a warning. No span
-    /// left means no component.
+    /// The component for a type, with spans from real source files inside the repo only. Generator output — a source
+    /// generator's virtual document, or a real file under bin/ or obj/ — is skipped silently; a declaration outside the
+    /// repo cannot be cited, so it is skipped with a warning. No span left means no component.
     /// </summary>
     public static Component? ToComponent(SourceType type, LoadedWorkspace loaded, List<string> warnings)
     {

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

@@ -9,7 +9,18 @@ namespace LogicalComponents;
 /// </summary>
 public static class ComponentRule
 {
-    private const string ServiceCollection = "Microsoft.Extensions.DependencyInjection.IServiceCollection";
+    // Host/DI builder types a composition root wires up. Matched by qualified name, not by referencing the host
+    // packages, since a target repo may use only some of them (a library-only Infrastructure project has no
+    // WebApplicationBuilder, for instance).
+    private static readonly string[] HostBuilderTypes =
+    [
+        "Microsoft.Extensions.DependencyInjection.IServiceCollection",
+        "Microsoft.Extensions.Hosting.IHostApplicationBuilder",
+        "Microsoft.AspNetCore.Builder.WebApplicationBuilder",
+        "Microsoft.Extensions.Hosting.IHostBuilder",
+    ];
+
+    private const string AutofacModule = "Autofac.Module";
 
     /// <summary>
     /// A candidate is a top-level, source-declared class (static classes included) or record (abstract records and
@@ -30,16 +41,17 @@ public static class ComponentRule
         && DeclaresBehaviour(type);
 
     /// <summary>
-    /// A static class that extends <c>IServiceCollection</c> (classic <c>this</c> parameter or a C# 14
-    /// <c>extension(IServiceCollection)</c> block) wires the app together and <c>new</c>s nearly every class; counting it
-    /// would make it look coupled to everything.
+    /// A static class that extends <c>IServiceCollection</c> or a host builder (classic <c>this</c> parameter or a
+    /// C# 14 <c>extension(...)</c> block), or an Autofac <c>Module</c> overriding <c>Load</c>, wires the app together
+    /// and <c>new</c>s or reaches nearly every class; counting it would make it look coupled to everything.
     /// </summary>
     public static bool IsCompositionRoot(INamedTypeSymbol type) =>
-        type.IsStatic
-        && (type.GetMembers().OfType<IMethodSymbol>().Any(m =>
-                m.IsExtensionMethod && m.Parameters.Length > 0 && IsServiceCollection(m.Parameters[0].Type))
-            || ExtensionBlocks(type).Any(block =>
-                block.ExtensionParameter is { } parameter && IsServiceCollection(parameter.Type)));
+        (type.IsStatic
+            && (type.GetMembers().OfType<IMethodSymbol>().Any(m =>
+                    m.IsExtensionMethod && m.Parameters.Length > 0 && IsHostBuilderType(m.Parameters[0].Type))
+                || ExtensionBlocks(type).Any(block =>
+                    block.ExtensionParameter is { } parameter && IsHostBuilderType(parameter.Type))))
+        || IsAutofacModule(type);
 
     // An exception carries a failure; even with factory methods of its own it is data, not a unit of behaviour.
     private static bool IsException(INamedTypeSymbol type)
@@ -56,9 +68,11 @@ public static class ComponentRule
     }
 
     /// <summary>
-    /// An ordinary method, explicit interface implementation, or C# 14 extension member written in the type, with a body.
-    /// Not behaviour: constructors, accessors, operators, abstract methods, compiler-synthesized record members, and
-    /// overrides of <c>object.ToString/Equals/GetHashCode</c> (formatting or comparing what the type holds).
+    /// An ordinary method, explicit interface implementation, or C# 14 extension member written in the type, with a body
+    /// of its own. Not behaviour: constructors, accessors, operators, abstract methods, compiler-synthesized record
+    /// members, overrides of <c>object.ToString/Equals/GetHashCode</c> (formatting or comparing what the type holds),
+    /// and <c>extern</c>/<c>[DllImport]</c>/<c>[LibraryImport]</c> methods (no body of their own; the behaviour, if any,
+    /// is native code).
     /// </summary>
     private static bool DeclaresBehaviour(INamedTypeSymbol type) =>
         type.GetMembers().Concat(ExtensionBlocks(type).SelectMany(block => block.GetMembers()))
@@ -67,7 +81,8 @@ public static class ComponentRule
                 && !m.IsAbstract
                 && !(m.IsPartialDefinition && m.PartialImplementationPart is null)
                 && m.MethodKind is MethodKind.Ordinary or MethodKind.ExplicitInterfaceImplementation
-                && !OverridesObjectMember(m));
+                && !OverridesObjectMember(m)
+                && !IsNativeInterop(m));
 
     private static bool OverridesObjectMember(IMethodSymbol method)
     {
@@ -80,8 +95,36 @@ public static class ComponentRule
         return overridden?.ContainingType.SpecialType == SpecialType.System_Object;
     }
 
+    /// <summary>
+    /// A classic <c>extern</c> P/Invoke method, or a <c>[LibraryImport]</c> partial method: the attribute lives on the
+    /// partial definition part, not the source-generator-written implementation part, so both parts are checked.
+    /// </summary>
+    private static bool IsNativeInterop(IMethodSymbol method)
+    {
+        var definition = method.PartialDefinitionPart ?? method;
+        return definition.IsExtern
+            || definition.GetAttributes().Any(a => a.AttributeClass is { } attribute
+                && SymbolNames.QualifiedName(attribute) is
+                    "System.Runtime.InteropServices.DllImportAttribute" or "System.Runtime.InteropServices.LibraryImportAttribute");
+    }
+
     private static IEnumerable<INamedTypeSymbol> ExtensionBlocks(INamedTypeSymbol type) =>
         type.GetTypeMembers().Where(t => t.IsExtension);
 
-    private static bool IsServiceCollection(ITypeSymbol type) => SymbolNames.QualifiedName(type) == ServiceCollection;
+    private static bool IsHostBuilderType(ITypeSymbol type) => HostBuilderTypes.Contains(SymbolNames.QualifiedName(type));
+
+    // Autofac.Module declares Load as virtual (empty by default); matching by name keeps this working without
+    // referencing Autofac.
+    private static bool IsAutofacModule(INamedTypeSymbol type)
+    {
+        for (var current = type.BaseType; current is not null; current = current.BaseType)
+        {
+            if (SymbolNames.QualifiedName(current) == AutofacModule)
+            {
+                return type.GetMembers("Load").OfType<IMethodSymbol>().Any(m => m.IsOverride);
+            }
+        }
+
+        return false;
+    }
 }

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

@@ -1,3 +1,4 @@
+using System.Security.Cryptography;
 using System.Text;
 using System.Text.Encodings.Web;
 using System.Text.Json;
@@ -38,12 +39,18 @@ public sealed record ExternalNode(string Id, string Type, string Name, string La
 /// </summary>
 public sealed record Edge(string From, string To, IReadOnlyList<string> Kinds, IReadOnlyList<string> Via, string At);
 
-/// <summary>Everything <c>extract</c> writes: the components, the ports they reach, the edges, and the warnings.</summary>
+/// <summary>
+/// Everything <c>extract</c> writes: the components, the ports they reach, the edges, and the warnings.
+/// <see cref="FileHashes"/> is a repo-relative-file → content-hash map covering every file any component span, reach or
+/// edge citation points into, so <c>render</c> can tell whether the repo changed since extraction. Null when read from
+/// a components.json written before this map existed.
+/// </summary>
 public sealed record ExtractResult(
     IReadOnlyList<Component> Components,
     IReadOnlyList<ExternalNode> ExternalNodes,
     IReadOnlyList<Edge> Edges,
-    IReadOnlyList<string> Warnings);
+    IReadOnlyList<string> Warnings,
+    IReadOnlyDictionary<string, string>? FileHashes = null);
 
 /// <summary>
 /// Writes <c>components.json</c>. Byte-identical for identical input: fixed property order, LF line endings,
@@ -68,6 +75,7 @@ public static class ComponentsFile
             externalNodes = result.ExternalNodes,
             edges = result.Edges,
             warnings = result.Warnings,
+            fileHashes = result.FileHashes,
         });
 
     /// <summary>Any file the tool writes: indented camelCase JSON, LF line endings, no BOM, trailing newline.</summary>
@@ -80,4 +88,14 @@ public static class ComponentsFile
     /// <summary>Reads any file written by <see cref="ToJson{T}"/>.</summary>
     public static T FromJson<T>(byte[] json) =>
         JsonSerializer.Deserialize<T>(json, Options) ?? throw new JsonException("the file is empty");
+
+    /// <summary>
+    /// SHA-256 of a repo file's text, lowercase hex, with CRLF normalized to LF first so a checkout's line-ending
+    /// setting never changes the hash.
+    /// </summary>
+    public static string HashFile(string path) => HashText(File.ReadAllText(path));
+
+    /// <summary>SHA-256 of text with CRLF normalized to LF, as lowercase hex.</summary>
+    public static string HashText(string text) =>
+        Convert.ToHexStringLower(SHA256.HashData(Encoding.UTF8.GetBytes(text.Replace("\r\n", "\n"))));
 }

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

@@ -37,22 +37,28 @@ public static class CouplingResolver
             var self = new HashSet<string>(StringComparer.Ordinal) { component.Type };
             var declarations = symbol.DeclaringSyntaxReferences.Select(r => r.GetSyntax()).ToList();
             var roots = new List<SyntaxNode>(declarations);
+            var baseBindings = new List<(ITypeParameterSymbol Parameter, ITypeSymbol Argument)>();
 
             // Up the base chain: the first component ancestor is an 'inherits' edge; the code of non-component source
-            // bases in between (typically abstract) is this component's own behaviour, so it is walked as such.
-            for (var baseType = symbol.BaseType?.OriginalDefinition;
-                 baseType is not null && CitableSource.IsRepoSource(baseType, loaded);
-                 baseType = baseType.BaseType?.OriginalDefinition)
+            // bases in between (typically abstract) is this component's own behaviour, so it is walked as such. Roslyn
+            // resolves BaseType through the whole construction chain, so a generic base's own type parameters bind to
+            // what this component (or an intermediate base) actually supplies, however many levels deep.
+            for (var constructedBase = symbol.BaseType;
+                 constructedBase is not null && CitableSource.IsRepoSource(constructedBase.OriginalDefinition, loaded);
+                 constructedBase = constructedBase.BaseType)
             {
+                var baseType = constructedBase.OriginalDefinition;
                 var baseName = SymbolNames.FullName(baseType);
                 if (components.Contains(baseName))
                 {
-                    var (file, line) = BaseListLocation(declarations, loaded) ?? (component.Spans[0].File, component.Spans[0].Start);
+                    var (file, line) = await BaseListLocationAsync(declarations, baseType, loaded, cancellationToken)
+                        ?? (component.Spans[0].File, component.Spans[0].Start);
                     raw.Add(new(component.Type, baseName, EdgeExtraction.Inherits, [], file, line));
                     break;
                 }
 
                 self.Add(baseName);
+                baseBindings.AddRange(TypeMap.Zip(baseType.TypeParameters, constructedBase.TypeArguments));
                 roots.AddRange(baseType.DeclaringSyntaxReferences.Select(r => r.GetSyntax()));
             }
 
@@ -64,9 +70,10 @@ public static class CouplingResolver
             // In (file, position) order, so the first path the walk records is the same on every checkout.
             var ordered = roots.OrderBy(r => r.SyntaxTree.FilePath, StringComparer.Ordinal).ThenBy(r => r.SpanStart);
             var uses = await MemberUses.ReadAsync(ordered, loaded, cancellationToken);
-            var resolved = await resolution.ResolveAsync(component.Type, self, uses, cancellationToken);
+            var resolved = await resolution.ResolveAsync(component.Type, self, uses, TypeMap.FromBindings(baseBindings), cancellationToken);
             raw.AddRange(resolved.Edges);
             reaches[component.Type] = resolved.Reaches;
+            warnings.AddRange(resolved.Warnings);
         }
 
         var ids = discovery.Components.ToDictionary(c => c.Type, c => c.Id, StringComparer.Ordinal);
@@ -119,29 +126,54 @@ public static class CouplingResolver
             return [new(from, portName, EdgeExtraction.Di, [], reference.File, reference.Line)];
         }
 
+        var via = SymbolNames.FullName(target.OriginalDefinition);
         return implementations
             .Select(SymbolNames.FullName)
             .Where(components.Contains)
-            .Select(to => new MemberUseResolution.RawEdge(from, to, EdgeExtraction.Di, [target.Name], reference.File, reference.Line))
+            .Select(to => new MemberUseResolution.RawEdge(from, to, EdgeExtraction.Di, [via], reference.File, reference.Line))
             .ToList();
     }
 
-    /// <summary>Where a partial class names its base class: the base list of the declaration that has one.</summary>
-    private static (string File, int Line)? BaseListLocation(IEnumerable<SyntaxNode> declarations, LoadedWorkspace loaded)
+    /// <summary>
+    /// Where a partial class names <paramref name="baseType"/> as its base: the base list of the declaration whose base
+    /// list actually contains it, not merely the first declaration that has any base list (a partial fragment can list
+    /// only interfaces). Ties (there should be at most one match; a duplicate base is a compile error) break by file
+    /// path ordinal, then position.
+    /// </summary>
+    private static async Task<(string File, int Line)?> BaseListLocationAsync(
+        IEnumerable<SyntaxNode> declarations, INamedTypeSymbol baseType, LoadedWorkspace loaded, CancellationToken cancellationToken)
     {
+        var matches = new List<(string File, int Line)>();
         foreach (var baseList in declarations.OfType<Microsoft.CodeAnalysis.CSharp.Syntax.TypeDeclarationSyntax>()
                      .Select(d => d.BaseList).OfType<Microsoft.CodeAnalysis.CSharp.Syntax.BaseListSyntax>())
         {
             var (kind, file) = CitableSource.Classify(loaded, baseList.SyntaxTree);
-            if (kind == CitableSource.Kind.InRepo)
+            if (kind != CitableSource.Kind.InRepo || loaded.Solution.GetDocument(baseList.SyntaxTree) is not { } document)
+            {
+                continue;
+            }
+
+            var model = await document.GetSemanticModelAsync(cancellationToken)
+                ?? throw new InvalidOperationException($"No semantic model for {file}");
+            var namesBaseType = baseList.Types.Any(t =>
+                model.GetSymbolInfo(t.Type, cancellationToken).Symbol is INamedTypeSymbol candidate
+                && SymbolEqualityComparer.Default.Equals(candidate.OriginalDefinition, baseType));
+            if (namesBaseType)
             {
-                return (file, baseList.GetLocation().GetLineSpan().StartLinePosition.Line + 1);
+                matches.Add((file, baseList.GetLocation().GetLineSpan().StartLinePosition.Line + 1));
             }
         }
 
-        return null;
+        return matches.Count == 0 ? null : matches.OrderBy(m => m.File, StringComparer.Ordinal).ThenBy(m => m.Line).First();
     }
 
+    /// <summary>
+    /// CS1705: a referenced assembly was built against a newer framework. The loader keeps one target framework per
+    /// multi-targeted project, so a project on an older framework that references it always gets this error, yet every
+    /// symbol still binds. It says nothing about missing edges.
+    /// </summary>
+    private const string NewerFrameworkReference = "CS1705";
+
     /// <summary>Code that does not compile binds partially, so edges can be missing: say so instead of staying silent.</summary>
     private static async Task<List<string>> CompileErrorWarningsAsync(Solution solution, CancellationToken cancellationToken)
     {
@@ -149,7 +181,8 @@ public static class CouplingResolver
         foreach (var project in solution.Projects.OrderBy(p => p.Name, StringComparer.Ordinal))
         {
             var compilation = await project.GetCompilationAsync(cancellationToken);
-            var errors = compilation?.GetDiagnostics(cancellationToken).Count(d => d.Severity == DiagnosticSeverity.Error) ?? 0;
+            var errors = compilation?.GetDiagnostics(cancellationToken)
+                .Count(d => d.Severity == DiagnosticSeverity.Error && d.Id != NewerFrameworkReference) ?? 0;
             if (errors > 0)
             {
                 warnings.Add($"project {project.Name} has {errors} compile error(s); coupling may be incomplete");
@@ -176,7 +209,11 @@ public static class CouplingResolver
             .ToList();
     }
 
-    /// <summary>One edge per (from, to): kinds and via as sorted sets, cited at the earliest (file, line) recorded use.</summary>
+    /// <summary>
+    /// One edge per (from, to): kinds as a sorted set, cited at the earliest (file, line) recorded use, with <c>via</c>
+    /// naming the seams and seen-through types on that earliest use's own path (the first path found), in the order the
+    /// walk actually followed it rather than merged and alphabetised across every raw edge to the same target.
+    /// </summary>
     private static List<Edge> MergeEdges(List<MemberUseResolution.RawEdge> raw, IReadOnlyDictionary<string, string> ids) =>
         raw.Where(e => e.From != e.To)
             .GroupBy(e => (From: ids[e.From], To: ids[e.To]))
@@ -187,10 +224,28 @@ public static class CouplingResolver
                     g.Key.From,
                     g.Key.To,
                     g.Select(e => e.Kind).Distinct().Order(StringComparer.Ordinal).ToList(),
-                    g.SelectMany(e => e.Via).Distinct().Order(StringComparer.Ordinal).ToList(),
+                    DisambiguatedVia(first.Via),
                     $"{first.File}:{first.Line}");
             })
             .OrderBy(e => e.From, StringComparer.Ordinal)
             .ThenBy(e => e.To, StringComparer.Ordinal)
             .ToList();
+
+    /// <summary>
+    /// <paramref name="via"/> holds each step's full metadata name (stable identity). Displayed as its plain simple
+    /// name, except when a simple name on the path is shared by two genuinely different full names (two unrelated
+    /// <c>Builder</c>s): every step with that simple name then falls back to its readable full name instead of
+    /// collapsing into one indistinguishable entry. A single type revisited twice on the same path (it is not its own
+    /// collision) still displays by its plain simple name both times.
+    /// </summary>
+    private static List<string> DisambiguatedVia(IReadOnlyList<string> via)
+    {
+        var colliding = via.GroupBy(SymbolNames.SimpleName)
+            .Where(g => g.Distinct(StringComparer.Ordinal).Count() > 1)
+            .Select(g => g.Key)
+            .ToHashSet(StringComparer.Ordinal);
+        return via
+            .Select(name => colliding.Contains(SymbolNames.SimpleName(name)) ? SymbolNames.ReadableFullName(name) : SymbolNames.SimpleName(name))
+            .ToList();
+    }
 }

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

@@ -1,18 +1,22 @@
 namespace LogicalComponents;
 
 /// <summary>
-/// <c>extract &lt;repoPath&gt; [--out &lt;components.json&gt;]</c>: loads the repo and writes the deterministic extraction.
-/// Progress and warnings go to <c>errors</c> (stderr); the artifact goes to the --out file.
+/// <c>extract &lt;repoPath&gt; [--out &lt;components.json&gt;] [--solution &lt;file&gt;]</c>: loads the repo and writes the
+/// deterministic extraction, including a hash of every cited file's content (see <see cref="FileHashes"/>) so
+/// <c>render</c> can tell whether the repo changed since. <c>--solution</c> picks the solution file as in
+/// <c>candidates</c>. Progress and warnings go to <c>errors</c> (stderr); the artifact goes to the --out file.
 /// Exit codes: 0 written, 1 usage, 2 the target repo or its config could not be loaded, 4 candidates not classified
 /// in the repo config yet (one <c>unclassified &lt;type&gt;</c> line each; nothing is written).
 /// </summary>
 public static class ExtractCommand
 {
-    public const string Usage = "usage: LogicalComponents extract <repoPath> [--out <components.json>]";
+    public const string Usage =
+        "usage: LogicalComponents extract <repoPath> [--out <components.json>] [--solution <file>]";
 
     public static async Task<int> RunAsync(string[] args, TextWriter errors)
     {
-        if (args is not [var repoPath, ..] || !TryParseOut(args[1..], out var outPath))
+        if (args is not [var repoPath, ..]
+            || !CandidatesCommand.TryParseOptions(args[1..], "components.json", out var outPath, out var solution))
         {
             await errors.WriteLineAsync(Usage);
             return 1;
@@ -20,10 +24,11 @@ public static class ExtractCommand
 
         try
         {
-            using var loaded = await WorkspaceLoader.LoadAsync(repoPath, log: errors);
+            using var loaded = await WorkspaceLoader.LoadAsync(repoPath, solution: solution, log: errors);
             await errors.WriteLineAsync($"Loaded {loaded.ProjectNames.Count} projects from {loaded.Source}.");
 
-            var result = await CouplingResolver.ExtractAsync(loaded, ExtractConfig.Load(loaded.RepoRoot));
+            var extracted = await CouplingResolver.ExtractAsync(loaded, ExtractConfig.Load(loaded.RepoRoot));
+            var result = extracted with { FileHashes = FileHashes(loaded.RepoRoot, extracted) };
             foreach (var warning in result.Warnings)
             {
                 await errors.WriteLineAsync($"warning: {warning}");
@@ -59,14 +64,24 @@ public static class ExtractCommand
         }
     }
 
-    private static bool TryParseOut(string[] options, out string outPath)
+    /// <summary>
+    /// A repo-relative-file → content-hash map (see <see cref="ComponentsFile.HashFile"/>) for every file any component's
+    /// spans, reaches or outgoing edge citations point into, so <c>render</c> can later tell whether the repo changed.
+    /// </summary>
+    private static IReadOnlyDictionary<string, string> FileHashes(string repoRoot, ExtractResult result)
     {
-        outPath = "components.json";
-        return options switch
+        var files = result.Components
+            .SelectMany(c => c.Spans.Concat(c.Reaches ?? []).Select(s => s.File))
+            .Concat(result.Edges.Select(e => Citation.Parse(e.At)?.File).OfType<string>())
+            .Distinct(StringComparer.Ordinal)
+            .Order(StringComparer.Ordinal);
+
+        var hashes = new SortedDictionary<string, string>(StringComparer.Ordinal);
+        foreach (var file in files)
         {
-            [] => true,
-            ["--out", var path] => (outPath = path) is not null,
-            _ => false,
-        };
+            hashes[file] = ComponentsFile.HashFile(Path.Combine(repoRoot, file));
+        }
+
+        return hashes;
     }
 }