@phuc1403/musketeer 0.11.0 → 0.12.0

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

@@ -7,9 +7,12 @@ namespace LogicalComponents;
 /// <summary>
 /// <c>render --components &lt;components.json&gt; --resp &lt;dir|file&gt;... --repo &lt;repoPath&gt; --out &lt;md&gt;</c>.
 /// Merges the agents' batch files (a directory means every <c>batch-*.json</c> in it, read in name order), validates them
-/// against the extraction and the repo's files, and writes the markdown only when everything is valid.
-/// Exit codes: 0 written; 1 usage; 2 inputs unusable (unreadable components.json, a missing path, a repo that does not
-/// match components.json, an unwritable --out); 3 responsibilities rejected, every problem on stderr and no --out left.
+/// against the extraction and the repo's files, and writes the markdown only when everything is valid. The markdown is
+/// written to a temp file beside --out and renamed over it, so a failed or rejected run never deletes or corrupts
+/// whatever --out already held.
+/// Exit codes: 0 written; 1 usage; 2 inputs unusable (unreadable components.json, a missing path, components.json has
+/// no file-hash map from an old extract, a file the extraction cites changed or went missing since extract, an
+/// unwritable --out); 3 responsibilities rejected, every problem on stderr, --out left exactly as it was.
 /// </summary>
 public static class RenderCommand
 {
@@ -51,10 +54,28 @@ public static class RenderCommand
             return 2;
         }
 
-        // Checked before any citation: a repo that does not match components.json is not the agents' fault.
+        // Checked before any citation: a repo that no longer matches components.json is not the agents' fault.
+        if (extraction.FileHashes is null)
+        {
+            await errors.WriteLineAsync($"{arguments.Components} has no file hashes (from an old extract); re-run extract");
+            return 2;
+        }
+
+        var changed = ChangedFiles(extraction.FileHashes, arguments.Repo);
+        if (changed.Count > 0)
+        {
+            foreach (var file in changed)
+            {
+                await errors.WriteLineAsync($"{file}: changed since extract");
+            }
+
+            return 2;
+        }
+
         var sourceLines = ReadSourceLines(extraction, arguments.Repo, out var missingSources);
         if (missingSources.Count > 0)
         {
+            // Defensive only: every span/reaches file is already covered by the file-hash check above.
             await errors.WriteLineAsync(
                 $"The repo does not match components.json (re-run extract); missing: {string.Join(", ", missingSources)}");
             return 2;
@@ -71,27 +92,67 @@ public static class RenderCommand
                 await errors.WriteLineAsync(problem);
             }
 
-            // Never leave a document from an earlier run looking like this run's result.
-            if (File.Exists(arguments.Out))
-            {
-                File.Delete(arguments.Out);
-            }
-
+            // A rejected run is the agents' problem, not the user's: an --out from an earlier successful run is left
+            // exactly as it was, so a failed retry can never look like data loss.
             return 3;
         }
 
+        return await WriteAsync(arguments.Out, extraction, batches.Responsibilities, errors);
+    }
+
+    /// <summary>
+    /// Writes the markdown to a temp file beside <paramref name="outPath"/> and renames it over the target only once
+    /// the write succeeds, so a failure (disk full, an unwritable path) never leaves a partial or truncated --out, and
+    /// never touches whatever was already there.
+    /// </summary>
+    private static async Task<int> WriteAsync(
+        string outPath, ExtractResult extraction, IReadOnlyDictionary<string, IReadOnlyList<Responsibility>> responsibilities,
+        TextWriter errors)
+    {
+        var fullPath = Path.GetFullPath(outPath);
+        var directory = Path.GetDirectoryName(fullPath)!;
+        var temp = Path.Combine(directory, $".{Path.GetFileName(fullPath)}.{Guid.NewGuid():N}.tmp");
         try
         {
-            Directory.CreateDirectory(Path.GetDirectoryName(Path.GetFullPath(arguments.Out))!);
-            var markdown = MarkdownRenderer.Render(extraction, batches.Responsibilities);
-            await File.WriteAllBytesAsync(arguments.Out, new UTF8Encoding(encoderShouldEmitUTF8Identifier: false).GetBytes(markdown));
+            Directory.CreateDirectory(directory);
+            var markdown = MarkdownRenderer.Render(extraction, responsibilities);
+            await File.WriteAllBytesAsync(temp, new UTF8Encoding(encoderShouldEmitUTF8Identifier: false).GetBytes(markdown));
+            File.Move(temp, outPath, overwrite: true);
             return 0;
         }
         catch (Exception e) when (e is IOException or UnauthorizedAccessException)
         {
-            await errors.WriteLineAsync($"Cannot write {arguments.Out}: {e.Message}");
+            await errors.WriteLineAsync($"Cannot write {outPath}: {e.Message}");
             return 2;
         }
+        finally
+        {
+            if (File.Exists(temp))
+            {
+                File.Delete(temp);
+            }
+        }
+    }
+
+    /// <summary>Every file in <paramref name="hashes"/> whose current content hash differs, in file order, or that is missing.</summary>
+    private static List<string> ChangedFiles(IReadOnlyDictionary<string, string> hashes, string repo) =>
+        hashes.OrderBy(h => h.Key, StringComparer.Ordinal)
+            .Where(h => IsChanged(Path.Combine(repo, h.Key), h.Value))
+            .Select(h => h.Key)
+            .ToList();
+
+    private static bool IsChanged(string path, string expectedHash)
+    {
+        try
+        {
+            return !File.Exists(path) || ComponentsFile.HashFile(path) != expectedHash;
+        }
+        catch (Exception e) when (e is IOException or UnauthorizedAccessException)
+        {
+            // Became unreadable between the existence check and the hash read: treat it the same as changed, since
+            // render cannot trust an uncheckable citation either.
+            return true;
+        }
     }
 
     private static async Task<ExtractResult?> ReadExtractionAsync(string path, TextWriter errors)

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

@@ -23,6 +23,9 @@ public static partial class ResponsibilityValidation
     {
         var errors = new List<(string Id, int Item, string Message)>();
         var components = extraction.Components.ToDictionary(c => c.Id, StringComparer.Ordinal);
+        // Computed once per file and reused across every citation into it, since CiteProblem may be called many
+        // times for the same file (several components, or several responsibilities of one component).
+        var codeLines = new Dictionary<string, IReadOnlyList<bool>>(StringComparer.Ordinal);
 
         foreach (var id in responsibilities.Keys.Where(id => !components.ContainsKey(id)))
         {
@@ -51,7 +54,7 @@ public static partial class ResponsibilityValidation
                     errors.Add((component.Id, item, $"{prefix}repeats item {seen[Normalize(items[index].Text)]}"));
                 }
 
-                if (CiteProblem(items[index].Cite, component, sourceLines) is { } citeProblem)
+                if (CiteProblem(items[index].Cite, component, sourceLines, codeLines) is { } citeProblem)
                 {
                     errors.Add((component.Id, item, prefix + citeProblem));
                 }
@@ -77,7 +80,13 @@ public static partial class ResponsibilityValidation
         return match is null ? message : $"{message}; did you mean '{match}'?";
     }
 
-    /// <summary>One plain markdown line: no HTML or links (they would render as something else), balanced code spans.</summary>
+    /// <summary>
+    /// One plain markdown line: no hidden or control unicode (<see cref="PlainText"/>), balanced code spans
+    /// (<see cref="MarkdownCodeSpans"/> - CommonMark backtick-run matching, so an escaped backtick cannot smuggle real
+    /// HTML past the check by being mistaken for a delimiter), and outside those code spans no backslash, angle
+    /// bracket, square bracket or bare URL - anything that could render as something other than plain text, or point
+    /// the reader somewhere the tool never checked.
+    /// </summary>
     private static string? TextProblem(string text)
     {
         if (string.IsNullOrWhiteSpace(text))
@@ -90,27 +99,48 @@ public static partial class ResponsibilityValidation
             return "text must be a single line";
         }
 
+        if (PlainText.HasDisallowedUnicode(text))
+        {
+            return "text contains a control or invisible unicode character";
+        }
+
         if (text.Trim().Length > MaxTextLength)
         {
             return $"text is {text.Trim().Length} characters; keep it under {MaxTextLength}";
         }
 
-        if (text.Count(c => c == '`') % 2 != 0)
+        var (outsideCode, unclosed) = MarkdownCodeSpans.Strip(text);
+        if (unclosed)
         {
             return "text has an unclosed ` code span";
         }
 
-        var outsideCode = CodeSpan().Replace(text, "");
-        if (HtmlTag().IsMatch(outsideCode))
+        if (outsideCode.Contains('\\'))
+        {
+            return "text contains a backslash; put code in `backticks`";
+        }
+
+        if (outsideCode.IndexOfAny(['<', '>']) >= 0)
         {
             return "text contains HTML; put code in `backticks`";
         }
 
-        return outsideCode.Contains("](") ? "text contains a link" : null;
+        if (outsideCode.IndexOfAny(['[', ']']) >= 0)
+        {
+            return "text contains a link; put code in `backticks`";
+        }
+
+        return outsideCode.Contains("://", StringComparison.Ordinal)
+               || outsideCode.Contains("www.", StringComparison.OrdinalIgnoreCase)
+            ? "text contains a URL; put code in `backticks`"
+            : null;
     }
 
     private static string? CiteProblem(
-        string cite, Component component, IReadOnlyDictionary<string, IReadOnlyList<string>> sourceLines)
+        string cite,
+        Component component,
+        IReadOnlyDictionary<string, IReadOnlyList<string>> sourceLines,
+        Dictionary<string, IReadOnlyList<bool>> codeLines)
     {
         if (Citation.Parse(cite) is not { } citation)
         {
@@ -131,11 +161,17 @@ public static partial class ResponsibilityValidation
             return $"cite '{cite}' is past the end of the file ({lines.Count} lines)";
         }
 
+        if (!codeLines.TryGetValue(citation.File, out var code))
+        {
+            code = SourceCodeLines.Compute(lines);
+            codeLines[citation.File] = code;
+        }
+
         // Every code line must be citable, and the first and last lines must lie inside a citable span. Lines between
         // two citable members (blank, comment, brace) are not code, so a citation may run across neighbouring helper
         // members without claiming anything uncited, but it cannot start or end outside them.
         bool Citable(int line) => spans.Any(s => s.Start <= line && line <= s.End);
-        if (Enumerable.Range(citation.Start, citation.LineCount).Any(n => !Citable(n) && (IsCode(lines[n - 1]) || n == citation.Start || n == citation.End)))
+        if (Enumerable.Range(citation.Start, citation.LineCount).Any(n => !Citable(n) && (code[n - 1] || n == citation.Start || n == citation.End)))
         {
             var where = component.Reaches is { Count: > 0 }
                 ? "the component's declaration and the helper code it runs"
@@ -148,31 +184,14 @@ public static partial class ResponsibilityValidation
             return $"cite '{cite}' spans {citation.LineCount} lines; cite at most {MaxCitedLines}";
         }
 
-        return Enumerable.Range(citation.Start, citation.LineCount).Any(n => IsCode(lines[n - 1]))
+        return Enumerable.Range(citation.Start, citation.LineCount).Any(n => code[n - 1])
             ? null
             : $"cite '{cite}' covers no code (only blank, comment or brace lines)";
     }
 
-    /// <summary>Not blank, not only a comment, not only braces, parentheses and semicolons.</summary>
-    private static bool IsCode(string line)
-    {
-        var trimmed = line.Trim();
-        return trimmed.Length > 0
-            && !trimmed.StartsWith("//", StringComparison.Ordinal)
-            && !trimmed.StartsWith("/*", StringComparison.Ordinal)
-            && !trimmed.StartsWith('*')
-            && trimmed.Trim('{', '}', '(', ')', ';', ' ', '\t').Length > 0;
-    }
-
     // "  Stores EACH   order. " and "stores each order." are the same responsibility.
     private static string Normalize(string text) => Whitespace().Replace(text.Trim(), " ").ToLowerInvariant();
 
-    [GeneratedRegex("`[^`]*`")]
-    private static partial Regex CodeSpan();
-
-    [GeneratedRegex("<[A-Za-z/!]")]
-    private static partial Regex HtmlTag();
-
     [GeneratedRegex(@"\s+")]
     private static partial Regex Whitespace();
 }

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

@@ -54,6 +54,62 @@ public static class SeamDispatch
         _ => null,
     };
 
+    /// <summary>
+    /// The bindings for walking <paramref name="runs"/> (the member <see cref="ImplementationOf"/> found) as it executes
+    /// for <paramref name="member"/> of <paramref name="seam"/> (as constructed at the use) in
+    /// <paramref name="implementation"/>: <paramref name="implementation"/>'s own type parameters, unified from its
+    /// construction of the seam (an open-generic decorator's own type argument, e.g. <c>Decorator&lt;T&gt; : IHandler&lt;T&gt;</c>
+    /// against <c>IHandler&lt;Ping&gt;</c>), plus a generic method declared on the seam (e.g. <c>Send&lt;T&gt;</c>) bound to
+    /// the type argument the use supplied. <paramref name="outer"/> resolves a use's type argument that is itself still
+    /// an unbound type parameter of an enclosing walk. Without this, <see cref="MemberUseResolution"/> would walk
+    /// <paramref name="runs"/> with its own type parameters unbound, and a seam it calls in turn would look like it
+    /// matches every construction (<see cref="PortResolution"/>).
+    /// </summary>
+    public static TypeMap BindingFor(
+        INamedTypeSymbol implementation, INamedTypeSymbol seam, ISymbol member, ISymbol runs, TypeMap outer)
+    {
+        var bindings = new List<(ITypeParameterSymbol Parameter, ITypeSymbol Argument)>();
+
+        if (seam.IsGenericType)
+        {
+            var definition = SymbolNames.FullName(seam.OriginalDefinition);
+            var construction = Supertypes(implementation, seam.TypeKind)
+                .FirstOrDefault(s => SymbolNames.FullName(s.OriginalDefinition) == definition);
+            for (var i = 0; construction is not null && i < construction.TypeArguments.Length && i < seam.TypeArguments.Length; i++)
+            {
+                if (construction.TypeArguments[i] is ITypeParameterSymbol parameter
+                    && SymbolEqualityComparer.Default.Equals(parameter.ContainingSymbol, implementation))
+                {
+                    bindings.Add((parameter, seam.TypeArguments[i]));
+                }
+            }
+        }
+
+        if (member is IMethodSymbol { TypeArguments.Length: > 0 } used && runs is IMethodSymbol { TypeArguments.Length: > 0 } implemented)
+        {
+            bindings.AddRange(TypeMap.Zip(implemented.OriginalDefinition.TypeParameters, used.TypeArguments)
+                .Select(b => (b.Parameter, outer.Substitute(b.Argument))));
+        }
+
+        return TypeMap.FromBindings(bindings);
+    }
+
+    private static IEnumerable<INamedTypeSymbol> Supertypes(INamedTypeSymbol type, TypeKind seamKind)
+    {
+        if (seamKind == TypeKind.Interface)
+        {
+            return type.AllInterfaces;
+        }
+
+        var bases = new List<INamedTypeSymbol>();
+        for (var current = type.BaseType; current is not null; current = current.BaseType)
+        {
+            bases.Add(current);
+        }
+
+        return bases;
+    }
+
     // Compared as text: symbols of the same type seen from two projects' compilations are not the same instance.
     private static string Display(ITypeSymbol type) => type.ToDisplayString(SymbolDisplayFormat.FullyQualifiedFormat);
 }

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

@@ -0,0 +1,79 @@
+using System.Text;
+
+namespace LogicalComponents;
+
+/// <summary>
+/// Which lines of a whole file contain real code, for <see cref="ResponsibilityValidation"/>'s citation checks. Tracks
+/// `/* */` block-comment state across the file (so a continuation line without a leading `*` is still recognised as a
+/// comment, and a comment that closes mid-line is not mistaken for a comment-only line), and treats punctuation-only
+/// lines, preprocessor directives, and a lone `else`/`try`/`finally`/`do` with no condition of its own as not code.
+/// </summary>
+public static class SourceCodeLines
+{
+    public static IReadOnlyList<bool> Compute(IReadOnlyList<string> lines)
+    {
+        var result = new bool[lines.Count];
+        var inBlockComment = false;
+        for (var i = 0; i < lines.Count; i++)
+        {
+            result[i] = LineHasCode(lines[i], ref inBlockComment);
+        }
+
+        return result;
+    }
+
+    /// <summary>
+    /// Strips `//` line comments and `/* */` block comments from one line (updating <paramref name="inBlockComment"/>
+    /// for the next line), then true if what remains is more than punctuation <c>{}()[];,</c>, a preprocessor
+    /// directive, or a lone <c>else</c>/<c>try</c>/<c>finally</c>/<c>do</c>.
+    /// </summary>
+    private static bool LineHasCode(string line, ref bool inBlockComment)
+    {
+        var code = new StringBuilder();
+        var i = 0;
+        while (i < line.Length)
+        {
+            if (inBlockComment)
+            {
+                var close = line.IndexOf("*/", i, StringComparison.Ordinal);
+                if (close < 0)
+                {
+                    break; // the rest of the line is still inside the comment
+                }
+
+                inBlockComment = false;
+                i = close + 2;
+                continue;
+            }
+
+            if (line[i] == '/' && i + 1 < line.Length && line[i + 1] == '/')
+            {
+                break; // the rest of the line is a line comment
+            }
+
+            if (line[i] == '/' && i + 1 < line.Length && line[i + 1] == '*')
+            {
+                var close = line.IndexOf("*/", i + 2, StringComparison.Ordinal);
+                if (close < 0)
+                {
+                    inBlockComment = true;
+                    break;
+                }
+
+                i = close + 2;
+                continue;
+            }
+
+            code.Append(line[i]);
+            i++;
+        }
+
+        if (code.ToString().TrimStart(' ', '\t').StartsWith('#'))
+        {
+            return false;
+        }
+
+        var stripped = code.ToString().Trim('{', '}', '(', ')', '[', ']', ';', ',', ' ', '\t');
+        return stripped.Length > 0 && stripped is not ("else" or "try" or "finally" or "do");
+    }
+}

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

@@ -25,6 +25,37 @@ public sealed class TypeMap
     /// <summary>Stable text of the bindings: the same member walked for two different bindings is two walks.</summary>
     public string Key { get; }
 
+    /// <summary>
+    /// A map built from known (parameter, argument) pairs: a generic base class's own parameters bound to what the
+    /// derived class supplies (<see cref="CouplingResolver"/>), or an implementation's own parameters unified from its
+    /// construction of a seam, plus a generic seam method's parameters bound to the use's type arguments
+    /// (<see cref="SeamDispatch"/>). Pairs where the argument is the parameter itself carry no information and are
+    /// dropped, same as <see cref="For"/>.
+    /// </summary>
+    public static TypeMap FromBindings(IEnumerable<(ITypeParameterSymbol Parameter, ITypeSymbol Argument)> bindings)
+    {
+        var map = new Dictionary<ITypeParameterSymbol, ITypeSymbol>(SymbolEqualityComparer.Default);
+        foreach (var (parameter, argument) in bindings)
+        {
+            if (!SymbolEqualityComparer.Default.Equals(parameter, argument))
+            {
+                map[parameter] = argument;
+            }
+        }
+
+        return map.Count == 0 ? Empty : new TypeMap(map);
+    }
+
+    /// <summary>Pairs a generic definition's own type parameters with a construction's type arguments, positionally.</summary>
+    public static IEnumerable<(ITypeParameterSymbol Parameter, ITypeSymbol Argument)> Zip(
+        ImmutableArray<ITypeParameterSymbol> parameters, ImmutableArray<ITypeSymbol> arguments)
+    {
+        for (var i = 0; i < parameters.Length && i < arguments.Length; i++)
+        {
+            yield return (parameters[i], arguments[i]);
+        }
+    }
+
     /// <summary>The type with every mapped type parameter replaced, inside generic arguments too.</summary>
     public ITypeSymbol Substitute(ITypeSymbol type) => type switch
     {

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

@@ -37,7 +37,12 @@ public static class WorkspaceLoader
 {
     private static readonly TimeSpan RestoreTimeout = TimeSpan.FromMinutes(10);
 
-    public static async Task<LoadedWorkspace> LoadAsync(string repoPath, bool restore = true, TextWriter? log = null)
+    /// <param name="solution">
+    /// An explicit solution file, relative to <paramref name="repoPath"/> or absolute, used instead of searching the
+    /// repo root. Use it to resolve the "more than one solution" error, or to pick a non-top-level solution on purpose.
+    /// </param>
+    public static async Task<LoadedWorkspace> LoadAsync(
+        string repoPath, bool restore = true, string? solution = null, TextWriter? log = null)
     {
         var repoRoot = Path.GetFullPath(repoPath);
         if (!Directory.Exists(repoRoot))
@@ -47,7 +52,7 @@ public static class WorkspaceLoader
 
         log ??= TextWriter.Null;
 
-        var solutionFile = FindSolutionFile(repoRoot);
+        var solutionFile = solution is null ? FindSolutionFile(repoRoot) : ResolveGivenSolution(repoRoot, solution);
         if (solutionFile is not null)
         {
             var name = Path.GetFileName(solutionFile);
@@ -62,7 +67,7 @@ public static class WorkspaceLoader
             log.WriteLine($"{name} contains no C# source projects; falling back to project files.");
         }
 
-        var (projectFiles, glob) = FindProjectFiles(repoRoot);
+        var (projectFiles, glob) = FindProjectFiles(repoRoot, log);
         if (projectFiles.Count == 0)
         {
             throw new WorkspaceLoadException($"No solution and no C# source project found under {repoRoot}");
@@ -115,7 +120,7 @@ public static class WorkspaceLoader
                     $"Loading {source} failed:{Environment.NewLine}  " + string.Join(Environment.NewLine + "  ", failures));
             }
 
-            return new LoadedWorkspace(workspace, KeepSourceProjects(workspace.CurrentSolution, repoRoot), repoRoot, source);
+            return new LoadedWorkspace(workspace, KeepSourceProjects(workspace.CurrentSolution, repoRoot, log), repoRoot, source);
         }
         catch (Exception e)
         {
@@ -126,23 +131,37 @@ public static class WorkspaceLoader
 
     /// <summary>
     /// Drops non-C# and test projects, and keeps one project per multi-targeted project file: the highest target
-    /// framework, renamed without its <c>(tfm)</c> suffix, so every type is seen exactly once.
+    /// framework, renamed without its <c>(tfm)</c> suffix, so every type is seen exactly once. A project referencing a
+    /// dropped copy (another TFM of the same file resolved by a referencing project that targets a lower framework)
+    /// is redirected to the kept copy first, so it never silently loses that reference.
     /// </summary>
-    private static Solution KeepSourceProjects(Solution solution, string repoRoot)
+    private static Solution KeepSourceProjects(Solution solution, string repoRoot, TextWriter log)
     {
         foreach (var byFile in solution.Projects.GroupBy(p => p.FilePath ?? "", StringComparer.OrdinalIgnoreCase))
         {
             var projects = byFile.ToList();
-            var isSource = byFile.Key != ""
+            var isTest = byFile.Key != ""
                 && projects[0].Language == LanguageNames.CSharp
-                && !ProjectFilters.IsTestProject(Path.GetRelativePath(repoRoot, byFile.Key), File.ReadAllText(byFile.Key));
+                && ProjectFilters.IsTestProject(Path.GetRelativePath(repoRoot, byFile.Key), File.ReadAllText(byFile.Key));
+            if (isTest)
+            {
+                log.WriteLine($"dropped test project: {Path.GetRelativePath(repoRoot, byFile.Key)}");
+            }
+
+            var isSource = byFile.Key != "" && projects[0].Language == LanguageNames.CSharp && !isTest;
             var kept = isSource
                 ? projects.MaxBy(p => ProjectFilters.TargetFrameworkRank(p.Name))
                 : null;
 
-            foreach (var project in projects.Where(p => p != kept))
+            var dropped = projects.Where(p => p != kept).Select(p => p.Id).ToList();
+            if (dropped.Count > 0)
+            {
+                solution = RedirectProjectReferences(solution, dropped, kept?.Id);
+            }
+
+            foreach (var id in dropped)
             {
-                solution = solution.RemoveProject(project.Id);
+                solution = solution.RemoveProject(id);
             }
 
             if (kept is not null)
@@ -154,6 +173,33 @@ public static class WorkspaceLoader
         return solution;
     }
 
+    /// <summary>
+    /// Points every reference to one of <paramref name="droppedIds"/> at <paramref name="keptId"/> instead (deduped
+    /// against a reference the project already has), or drops it if there is no kept copy to redirect to (the whole
+    /// group is being dropped, e.g. a test or non-C# project).
+    /// </summary>
+    private static Solution RedirectProjectReferences(
+        Solution solution, IReadOnlyCollection<ProjectId> droppedIds, ProjectId? keptId)
+    {
+        foreach (var project in solution.Projects.ToList())
+        {
+            if (droppedIds.Contains(project.Id) || project.ProjectReferences.All(r => !droppedIds.Contains(r.ProjectId)))
+            {
+                continue;
+            }
+
+            var references = project.ProjectReferences.Where(r => !droppedIds.Contains(r.ProjectId)).ToList();
+            if (keptId is not null && project.Id != keptId && references.All(r => r.ProjectId != keptId))
+            {
+                references.Add(new ProjectReference(keptId));
+            }
+
+            solution = solution.WithProjectReferences(project.Id, references);
+        }
+
+        return solution;
+    }
+
     private static string? FindSolutionFile(string repoRoot)
     {
         // Top-level only: a nested solution usually belongs to a sample or a vendored dependency.
@@ -167,21 +213,45 @@ public static class WorkspaceLoader
             0 => null,
             1 => candidates[0],
             _ => throw new WorkspaceLoadException(
-                $"More than one solution in {repoRoot}: {string.Join(", ", candidates.Select(Path.GetFileName))}"),
+                $"More than one solution in {repoRoot}: {string.Join(", ", candidates.Select(Path.GetFileName))}"
+                + "; pass --solution <file> to pick one."),
         };
     }
 
+    /// <summary>Resolves an explicit <c>--solution</c> file (relative to the repo root, or absolute); errors if missing.</summary>
+    private static string ResolveGivenSolution(string repoRoot, string solution)
+    {
+        var path = Path.IsPathRooted(solution) ? solution : Path.Combine(repoRoot, solution);
+        if (!File.Exists(path))
+        {
+            throw new WorkspaceLoadException($"Solution not found: {Path.GetFullPath(path)}");
+        }
+
+        return Path.GetFullPath(path);
+    }
+
     /// <summary>C# project files under <c>src/</c>, or under the repo root minus build output and dot folders.</summary>
-    private static (List<string> Files, string Glob) FindProjectFiles(string repoRoot)
+    private static (List<string> Files, string Glob) FindProjectFiles(string repoRoot, TextWriter log)
     {
         var src = Path.Combine(repoRoot, "src");
         var (searchRoot, glob) = Directory.Exists(src) ? (src, "src/**/*.csproj") : (repoRoot, "**/*.csproj");
         var files = Directory
             .EnumerateFiles(searchRoot, "*.csproj", SearchOption.AllDirectories)
-            .Where(file => !Path.GetRelativePath(repoRoot, file)
-                .Split(Path.DirectorySeparatorChar, Path.AltDirectorySeparatorChar)
-                .Any(segment => segment is "bin" or "obj" || segment.StartsWith('.')))
-            .Where(file => !ProjectFilters.IsTestProject(Path.GetRelativePath(repoRoot, file), File.ReadAllText(file)))
+            .Where(file => !CitableSource.IsBuildOutputPath(Path.GetRelativePath(repoRoot, file))
+                && !Path.GetRelativePath(repoRoot, file)
+                    .Split(Path.DirectorySeparatorChar, Path.AltDirectorySeparatorChar)
+                    .Any(segment => segment.StartsWith('.')))
+            .Where(file =>
+            {
+                var relative = Path.GetRelativePath(repoRoot, file);
+                if (!ProjectFilters.IsTestProject(relative, File.ReadAllText(file)))
+                {
+                    return true;
+                }
+
+                log.WriteLine($"dropped test project: {relative}");
+                return false;
+            })
             .Order(StringComparer.Ordinal)
             .ToList();
         return (files, glob);

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

@@ -57,6 +57,14 @@ public class BatchPlanningTests
         Assert.Equal(reaches, batch.Reaches);
     }
 
+    [Fact]
+    public void An_enormous_agent_count_does_not_overflow_the_batch_size()
+    {
+        var batches = BatchPlanning.Plan(WithComponents(3), int.MaxValue);
+
+        Assert.Equal([1, 1, 1], batches.Select(b => b.Components.Count));
+    }
+
     [Fact]
     public void Batch_files_are_written_identically_every_time()
     {