@cratis/pi 7.102.0 → 7.103.1

package/package/corpus/skills/msbuild/NOTICE

@@ -0,0 +1,55 @@
+MSBuild troubleshooting
+Copyright (c) .NET Foundation and Contributors
+Licensed under the MIT License. See LICENSE.
+
+Upstream source: https://github.com/dotnet/skills/blob/a6bf43ab61967c30919334986515163ab24d7635/plugins/dotnet/skills/msbuild/SKILL.md
+
+Changes made by Cratis:
+
+LICENSE:
+- Copy upstream MIT license and copyright verbatim.
+
+SKILL.md:
+- Lead the description trigger with an explicit "Use when" clause.
+- Normalize frontmatter serialization, add MIT license where absent; preserve name and description.
+- Add marked modification/source comment and applicability/Cratis precedence line.
+- Require analyzer/warnings-as-errors restoration after labelled timing experiments.
+- Add direct conditional pointers for all otherwise-indirect reference/script/asset files: references/antipatterns/additional-antipatterns.md, references/antipatterns/incremental-build-inputs-outputs.md, references/antipatterns/private-assets.md.
+- Rewrite the description to the Cratis shape (what it does, Use when, Not for) and drop references to skills that are not part of this corpus.
+
+references/binlog-failure-analysis.md:
+- Render unimported binlog-failure-analysis routing reference as plain topic text.
+
+references/build-perf-baseline.md:
+- Render unimported build-perf-baseline routing reference as plain topic text.
+- Qualify analyzer/warning suppression as timing-only; require the real gate restored.
+- Add or normalize the top Contents list from existing headings; preserve section content.
+
+references/build-perf-diagnostics.md:
+- Render unimported build-perf-diagnostics routing reference as plain topic text.
+- Qualify analyzer/warning suppression as timing-only; require the real gate restored.
+- Add or normalize the top Contents list from existing headings; preserve section content.
+
+references/copy-to-output-directory.md:
+- Render unimported copy-to-output-directory routing reference as plain topic text.
+- Add or normalize the top Contents list from existing headings; preserve section content.
+
+references/eval-performance.md:
+- Render unimported eval-performance routing reference as plain topic text.
+- Add or normalize the top Contents list from existing headings; preserve section content.
+
+references/incremental-build.md:
+- Render unimported incremental-build routing reference as plain topic text.
+- Add or normalize the top Contents list from existing headings; preserve section content.
+
+references/msbuild-antipatterns.md:
+- Render unimported msbuild-antipatterns routing reference as plain topic text.
+- Add or normalize the top Contents list from existing headings; preserve section content.
+
+references/antipatterns/additional-antipatterns.md:
+- Add or normalize the top Contents list from existing headings; preserve section content.
+
+references/extension-points.md:
+- Add or normalize the top Contents list from existing headings; preserve section content.
+
+NOTICE: Add this attribution, change list, and any download/execution disclosure.

package/package/corpus/skills/msbuild/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: msbuild
+description: 'Investigates MSBuild build failures, diagnoses build performance, and reviews build XML and extension contracts using binary logs. Use for failing dotnet build, restore, pack, or publish; .binlog capture and replay; project, props, and targets conditions; custom-target inputs/outputs; Import/Exists hooks and packed NuGet imports; slow evaluation, compilation, copying, or no-change builds; and controlled timing comparisons. Not for legacy or non-SDK project migration, framework or package upgrades, SDK installation, C# refactoring, runtime profiling, assertions after a successful build, or non-MSBuild builds.'
+license: MIT
+---
+
+<!-- Modified by Cratis from dotnet's original (MIT): frontmatter, applicability, navigation and the changes listed in NOTICE. Upstream: https://github.com/dotnet/skills (plugins/dotnet/skills/msbuild/SKILL.md; see NOTICE) -->
+
+# MSBuild troubleshooting
+
+Cratis rules in `.cratis/ai/rules/` (including `csharp.md`, `specs.csharp.md`, and `orleans.md`) and the `cratis-*` skills win where they differ.
+
+This is the entry skill. Choose **troubleshooting**, **performance**, or **authoring review**, then
+read only the relevant local references. The references retain the content and identities of
+the original MSBuild skills, with correctness fixes; they are not separate skills to activate.
+
+## Start with the task and evidence
+
+For tasks that need a checkout, discover the relevant project/solution, shared build files, SDK
+selection, and repository build instructions in the current workspace. Preserve the original command, working directory,
+configuration, target framework, runtime identifier, global properties, and target.
+Ask only for consequential information that cannot be discovered.
+
+An existing `.binlog` can be the only available artifact. Analyze it before requesting a new
+build; paths inside it do not prove a checkout exists locally. For a self-contained static review
+or advisory question, use the supplied XML and relevant references; do not require a checkout,
+restore, build, or binlog.
+
+For a mixed request, fix correctness before measuring successful builds, and keep authoring review
+separate from a performance experiment. A failing test assertion after a successful build is not
+an MSBuild failure.
+
+## 1. Troubleshoot build issues
+
+**Goal:** identify the independent root causes and make the smallest repair, not a broad cleanup.
+
+| Situation | Read | Action |
+| --- | --- | --- |
+| A build failed and a binary log exists | [binlog-failure-analysis](references/binlog-failure-analysis.md) | Replay the log with MSBuild; connect errors to the responsible project instance, target, and task. Separate root causes from cascading failures. |
+| The failure needs evidence and no matching log exists | [binlog-generation](references/binlog-generation.md), then [failure analysis](references/binlog-failure-analysis.md) | Capture the original invocation once, verify the artifact, and analyze it. |
+| A project/build file has incorrect conditions, items, properties, or output paths | [msbuild-antipatterns](references/msbuild-antipatterns.md) | Select the relevant catalog entries and check their exceptions before changing anything. |
+| Imports or build hooks are missing, overwritten, or run in the wrong order | [extension-points](references/extension-points.md) | Inspect the import contract, discovery order, and packed NuGet layout rather than hiding a required failure. |
+| Outputs are stale or required work is skipped | [incremental-build](references/incremental-build.md) | Prove which input, output, timestamp, item, or condition makes the decision wrong. Correctness takes priority over speed. |
+
+After a repair, rerun the original failing scenario and check affected dependents. If only a log
+is available, provide an evidence-backed proposed fix and say it was not applied or rebuilt.
+Do not turn a targeted failure investigation into solution-wide authoring cleanup.
+
+## 2. Diagnose and improve build performance
+
+**Goal:** measure the reported scenario, identify its bottleneck, change one cause, and compare
+equivalent builds without losing required behavior.
+
+1. Reuse matching measurements. If they are missing, establish the relevant baseline before
+   editing configuration; do not time a failed build as a successful baseline.
+2. Classify evaluation versus target/task execution. Inclusive target totals and dependency waits
+   are not additive wall time or proof of CPU utilization.
+3. Follow the measured branch below. Do not apply every optimization in every reference.
+4. Repeat the same scenario, command, input change, and instrumentation. Report spread/noise and
+   correctness checks; an isolated faster run is not proof of improvement.
+
+| Situation | Read | Keep distinct |
+| --- | --- | --- |
+| No trustworthy before/after measurements, or a baseline/controlled optimization is requested | [build-perf-baseline](references/build-perf-baseline.md) | Cold-output, warm changed-input, and no-change builds; restore/cache state; ordinary Build versus forced Rebuild. |
+| The expensive work is not yet identified, or compiler/analyzer/reference/restore time dominates | [build-perf-diagnostics](references/build-perf-diagnostics.md) | Actual task cost versus orchestration waits, overlapping durations, and missing instrumentation. |
+| Time is spent before target execution, in globs, imports, or property evaluation | [eval-performance](references/eval-performance.md) | Evaluation versus execution; legitimate versus accidental project instances. |
+| Content copies or output I/O dominate | [copy-to-output-directory](references/copy-to-output-directory.md) | Copy mode/version support, unchanged copies, and the intended handling of a modified destination. |
+| A second unchanged build recompiles/regenerates, or incremental behavior is broken | [incremental-build](references/incremental-build.md) | Expected invalidation versus missing tracking; changed/added/removed inputs and missing outputs. |
+
+Stop when the suspected bottleneck is not supported by evidence, results fall within noise, or
+correctness regresses. Report missing measurements rather than manufacturing a complete baseline.
+
+## 3. Review build authoring
+
+**Goal:** improve project/build-file structure and extension contracts while preserving behavior.
+This route means MSBuild authoring cleanup, not an implicit framework, package, language,
+or legacy project-system migration.
+
+| Requested change | Read | Preserve |
+| --- | --- | --- |
+| Review/clean up project files, shared properties, item declarations, or custom targets | [msbuild-antipatterns](references/msbuild-antipatterns.md) | Intentional overrides, F# source order, required imports, package assets, and actual input/output contracts. |
+| Review/improve hooks, imports, shared-file discovery, or NuGet build extensions | [extension-points](references/extension-points.md) | Prior hooks, evaluation order, direct/transitive consumer behavior, and the packed layout. |
+| Restructure generation or copying as part of cleanup | [incremental-build](references/incremental-build.md) and [copy-to-output-directory](references/copy-to-output-directory.md), as applicable | First-build and no-change behavior, invalidation, generated-item registration, and output completeness. |
+
+Record the existing contract before editing. Review only relevant catalog entries; a matching text
+pattern is not proof of a defect. Leave already-correct patterns unchanged. Validate the original
+configurations, relevant consumers, and affected incremental/pack/publish behavior.
+
+## Shared evidence and safety
+
+- For capture-only requests, use [binlog-generation](references/binlog-generation.md), report the
+  new artifact and original exit code, and stop. For analysis, use
+  [MSBuild replay](references/binlog-failure-analysis.md#replay-a-binary-log), never binary-file
+  text parsing. Replay success and replay duration are not the recorded build's result or duration.
+- Resolve these files relative to this skill. Do not load the original plugin's skills or search
+  other installations/checkouts. If a bundled reference is missing, allow one listing of
+  `references`, report the gap, and do not pretend its guidance was followed.
+- Do not clean outputs/caches, stop shared build servers, disable diagnostics, change SDKs, or
+  serialize builds as generic fixes. Scope any necessary destructive experiment to approved,
+  owned outputs. Keep binary and replayed logs local unless sharing is authorized.
+- Distinguish recorded facts from hypotheses. Missing source, log detail, tools, or platform
+  support must be reported explicitly, not replaced with assumed values or invented verification.
+
+## Completion
+
+Return the selected task, the cause/bottleneck or authoring decision, supporting evidence,
+and the minimal change made or proposed. State when no change is needed. Give the exact
+verification and result, distinguishing successful, failed, and not-run checks; performance work
+also needs comparable measurements and uncertainty. Keep the response proportional to the task.
+
+> **Cratis:** Only as a labelled timing experiment; restore analyzers and warnings-as-errors and run the real gate before finishing.
+
+## Reference navigation
+
+- Read references/antipatterns/additional-antipatterns.md when working on additional antipatterns.
+- Read references/antipatterns/incremental-build-inputs-outputs.md when working on incremental build inputs outputs.
+- Read references/antipatterns/private-assets.md when working on private assets.

package/package/corpus/skills/msbuild/references/antipatterns/additional-antipatterns.md

@@ -0,0 +1,291 @@
+# Additional MSBuild anti-patterns
+
+## Contents
+
+- AP-16: Exec for string or path operations
+- AP-17: Updating an item before it exists
+- AP-18: Apparently redundant transitive project references
+- AP-19: Side effects during evaluation
+- AP-20: Platform-specific Exec without a platform contract
+- AP-21: An early property condition reads TargetFramework too soon
+- AP-22: Project instances with path-neutral global properties
+- AP-23: Re-injecting a single-targeted project's own framework
+- Quick-reference checklist
+
+This continues the original catalog with AP-16 through AP-23. The same rule applies:
+verify the behavior and exceptions before changing a pattern.
+
+## AP-16: Exec for string or path operations
+
+**Smell:** invoking a shell or another runtime for simple transformations.
+
+**Impact:** platform dependence, process overhead, and awkward property capture.
+
+```xml
+<!-- BAD: a shell pipeline for a simple transformation. -->
+<Target Name="GetCleanVersion">
+  <Exec Command="echo $(Version) | sed 's/-preview//'" ConsoleToMSBuild="true">
+    <Output TaskParameter="ConsoleOutput" PropertyName="CleanVersion" />
+  </Exec>
+</Target>
+
+<!-- GOOD: property functions, where the transformation is the intended contract. -->
+<PropertyGroup>
+  <CleanVersion>$(Version.Replace('-preview', ''))</CleanVersion>
+  <HasPrerelease>$(Version.Contains('-'))</HasPrerelease>
+  <LowerName>$(AssemblyName.ToLowerInvariant())</LowerName>
+  <NormalizedOutput>$([MSBuild]::NormalizeDirectory('$(OutputPath)'))</NormalizedOutput>
+  <ToolPath>$([MSBuild]::NormalizePath('$(MSBuildThisFileDirectory)', 'tools', 'mytool.exe'))</ToolPath>
+</PropertyGroup>
+```
+
+Preserve transformation semantics and evaluation timing. This does not mean arbitrary external
+tools or stateful operations should become property functions.
+
+## AP-17: Updating an item before it exists
+
+**Smell:** `Update` is evaluated before the intended item is included.
+
+**Impact:** the metadata change matches no existing item.
+
+```xml
+<!-- BAD: no matching item exists at the update. -->
+<ItemGroup>
+  <Extra Update="external.dat" Visible="false" />
+  <Extra Include="external.dat" />
+</ItemGroup>
+
+<!-- GOOD: Include then Update in the SAME group is valid. -->
+<ItemGroup>
+  <Extra Include="external.dat" />
+  <Extra Update="external.dat" Visible="false" />
+</ItemGroup>
+```
+
+The original catalog incorrectly treated mixing Include and Update in one ItemGroup as a
+defect. Order and existence are what matter; splitting groups is neither necessary nor a fix
+for an update that still precedes its include.
+
+## AP-18: Apparently redundant transitive project references
+
+**Smell:** `App` references both `Core` and `Utils`, and `Core` also references `Utils`.
+
+**Impact:** a truly unnecessary edge can add coupling or resolution work, but transitive
+reachability alone does not prove redundancy or an ordering bug.
+
+```xml
+<!-- Candidate for review, not automatically incorrect. -->
+<ItemGroup>
+  <ProjectReference Include="..\Core\Core.csproj" />
+  <ProjectReference Include="..\Utils\Utils.csproj" />
+</ItemGroup>
+```
+
+Keep `App -> Utils` if App uses its API directly, needs its metadata/build-order contract, or
+repository policy requires explicit dependencies. Remove an edge only after verifying equivalent
+compile/runtime/pack behavior and supported SDK/framework configurations. Removing this edge does
+not itself shorten the required `App -> Core -> Utils` reference chain.
+Use [build-perf-baseline](../build-perf-baseline.md) for a measured graph experiment.
+
+## AP-19: Side effects during evaluation
+
+**Smell:** property evaluation writes files, mutates state, or performs network operations.
+
+**Impact:** evaluation can repeat during IDE/design-time and graph discovery, making side effects
+unpredictable. Some such functions are not permitted by default; do not loosen restrictions to
+make a side-effecting property expression work.
+
+```xml
+<!-- BAD, and not a generally permitted property function. -->
+<PropertyGroup>
+  <Timestamp>$([System.IO.File]::WriteAllText('stamp.txt', 'built'))</Timestamp>
+</PropertyGroup>
+
+<!-- Execution-time work belongs in a properly scheduled target. -->
+<Target Name="WriteTimestamp" BeforeTargets="Build">
+  <WriteLinesToFile File="stamp.txt" Lines="built" Overwrite="true" />
+</Target>
+```
+
+Moving work to a target still requires deciding its inputs, outputs, and whether it must run
+every time. For evaluation-time read/CPU cost, use [eval-performance](../eval-performance.md).
+
+## AP-20: Platform-specific Exec without a platform contract
+
+**Smell:** `chmod`, `cmd /c`, or a platform-specific executable is invoked on every OS.
+
+**Impact:** the wrong shell/tool or path syntax fails on another platform.
+
+```xml
+<Target Name="MakeExecutable" AfterTargets="Build"
+        Condition="!$([MSBuild]::IsOSPlatform('Windows'))">
+  <Exec Command="chmod +x &quot;$([MSBuild]::NormalizePath('$(OutputPath)', 'mytool'))&quot;" />
+</Target>
+```
+
+Prefer a portable built-in task when equivalent. Otherwise gate supported platforms, quote
+paths, and confirm that skipping the operation on other systems preserves their required behavior.
+An OS condition is not a substitute for implementing a capability the other platform also needs.
+
+## AP-21: An early property condition reads TargetFramework too soon
+
+**Smell:** a PropertyGroup or property in an early `.props` file conditions on a framework that
+the project body has not set yet.
+
+**Impact:** a single-targeted project can silently miss the assignment. A multi-targeted inner
+build may instead receive TargetFramework globally; distinguish those cases.
+
+```xml
+<!-- BAD in an early Directory.Build.props when the project sets TargetFramework later. -->
+<PropertyGroup Condition="'$(TargetFramework)' == 'net8.0'">
+  <DefineConstants>$(DefineConstants);MY_FEATURE</DefineConstants>
+</PropertyGroup>
+
+<!-- The same assignment can be placed after the project defines the framework,
+     for example in Directory.Build.targets for a single-targeted/inner build. -->
+<PropertyGroup Condition="'$(TargetFramework)' == 'net8.0'">
+  <DefineConstants>$(DefineConstants);MY_FEATURE</DefineConstants>
+</PropertyGroup>
+```
+
+An outer cross-targeting build may still have no single TargetFramework. Check the intended
+instance, and preserve existing constants rather than replacing them.
+
+**Item conditions are different:** items are evaluated after properties. These early-file
+patterns can be correct and must not be flagged merely for using TargetFramework:
+
+```xml
+<!-- Valid in Directory.Build.props when the project later sets this framework. -->
+<ItemGroup Condition="'$(TargetFramework)' == 'net472'">
+  <PackageReference Include="System.Memory" />
+</ItemGroup>
+
+<!-- Valid per-framework package version selection. -->
+<ItemGroup Condition="'$(TargetFramework)' == 'net8.0'">
+  <PackageVersion Include="Microsoft.AspNetCore.Mvc.Testing" Version="8.0.11" />
+</ItemGroup>
+```
+
+Target conditions are evaluated at execution time. Do not move all item/target conditions just
+because an early **property** condition is wrong.
+
+## AP-22: Project instances with path-neutral global properties
+
+**Smell:** an MSBuild task builds/publishes the same project, or a referenced project, with an
+extra global property that does not isolate its output paths.
+
+```xml
+<!-- Both shapes can create a distinct instance sharing existing bin/obj paths. -->
+<MSBuild Projects="$(MSBuildProjectFullPath)" Targets="Publish" Properties="_IsPublishing=true" />
+<MSBuild Projects="..\tool\tool.csproj" Targets="Publish" Properties="_IsPublishing=true" />
+```
+
+**Impact:** instance identity includes the project path and global properties. Distinct instances
+can write the same assemblies, PDBs, assets files, or generated files, producing duplicated work
+and intermittent parallel-build locks.
+
+Confirm the actual global-property differences and evaluated output/intermediate paths using
+[replayed build evidence](../binlog-failure-analysis.md). A property difference alone is not a
+collision if every relevant output is isolated.
+
+**Repair choices depend on the build contract:**
+
+1. Remove an unnecessary second invocation/property discriminator.
+2. For work that belongs to one instance, schedule a suitable target in that instance, after
+   checking its dependency graph for cycles.
+3. Make a producer own its artifacts, and have consumers sequence and consume them rather than
+   re-publishing the same project under a different property set.
+4. If different instances are intentional, isolate all relevant outputs/intermediate paths
+   early enough for SDK and NuGet consumers, and use matching restore/build settings.
+
+**Publish-on-build needs special care.** The original example used a private `_IsPublishing`
+guard and `AfterTargets="Build" DependsOnTargets="Publish"`. That can work through `dotnet build`
+and `dotnet publish` yet produce `MSB4006` through `dotnet msbuild -t:Publish`, because Publish
+already depends on Build. It is not a universal repair.
+
+Prefer an explicit publish operation when publish is the requested outcome, choosing an unused
+log name first:
+
+```powershell
+dotnet publish .\Tool\Tool.csproj -c Release "-bl:publish-01.binlog"
+```
+
+If a repository genuinely needs publish-on-build orchestration, validate its target graph and
+all supported entry commands; do not blindly substitute private SDK flags or add a cycle.
+A build-order-only reference can sequence a producer:
+
+```xml
+<ProjectReference Include="..\Tool\Tool.csproj" ReferenceOutputAssembly="false" />
+```
+
+That reference schedules the producer's **build**, not automatically its Publish target.
+The producer's actual artifact workflow must still exist. Retest the original parallel/graph
+scenario; serialization or repeated cleaning is not a permanent collision fix.
+
+## AP-23: Re-injecting a single-targeted project's own framework
+
+**Smell:** a reference injects the TFM that a single-targeted project already declares.
+
+```xml
+<!-- Tool already declares TargetFramework=net8.0. -->
+<ProjectReference Include="..\Tool\Tool.csproj" SetTargetFramework="TargetFramework=net8.0" />
+```
+
+**Impact:** a globally supplied TargetFramework can create an instance different from the ordinary
+build, even though both resolve to the same framework output paths. Confirm that duplicate
+instances actually share paths before attributing file-lock failures to this metadata.
+
+```xml
+<!-- Remove the redundant injection when the tool should build as declared. -->
+<ProjectReference Include="..\Tool\Tool.csproj" />
+```
+
+Do not remove legitimate framework selection:
+
+- Selecting one TFM of a multi-targeted reference can be intentional.
+- Overriding a single-targeted reference to a **different** framework can be intentional if the
+  project, dependencies, restore, and output paths support that contract.
+- Different frameworks/configurations do not guarantee isolation when custom paths omit their
+  discriminators; inspect actual paths.
+
+### Build-only references across incompatible frameworks
+
+An incompatible assembly cannot become a compiler reference. A build-order-only tool reference
+may need both `ReferenceOutputAssembly="false"` and `SkipGetTargetFrameworkProperties="true"`.
+Bypassing negotiation can also let the caller's global TargetFramework leak into the tool.
+
+To build a single-targeted tool as declared:
+
+```xml
+<ProjectReference Include="..\Tool\Tool.csproj"
+                  SkipGetTargetFrameworkProperties="true"
+                  UndefineProperties="TargetFramework"
+                  ReferenceOutputAssembly="false" />
+```
+
+When an explicit TFM must be selected instead, use `SetTargetFramework` with the intended value.
+Do not simultaneously set and remove the same property. Do not apply this bypass to ordinary
+compatible assembly references, and verify the tool's actual framework/output in the log.
+
+## Quick-reference checklist
+
+| Source | Check first | Typical concern |
+| --- | --- | --- |
+| AP-02 | Unsafe string conditions | Parsing/correctness |
+| AP-19 | Evaluation side effects | Repeated or unsafe work |
+| AP-21 | Early framework-dependent properties | Silent missing settings |
+| AP-22, AP-23 | Distinct instances sharing outputs | Duplicate builds/races |
+| AP-03 | Machine-specific paths | Portability |
+| AP-06 | Legacy package HintPaths | Dependency migration |
+| AP-07 | Unwanted consumer dependencies/assets | Package contract |
+| AP-11 | Incomplete generation inputs/outputs | Stale or repeated work |
+| AP-13 | Optional versus required imports | Missing dependency behavior |
+| AP-05 | Duplicate source items versus language/order exceptions | Item correctness |
+| AP-04 | Proven redundant defaults versus intentional pins | Maintainability |
+| AP-08, AP-09 | Shared settings or unintended version drift | Consistency |
+| AP-01, AP-16 | Shell operations replaceable by built-ins | Portability/overhead |
+| AP-14, AP-20 | Actual path consumer and platform support | Cross-platform behavior |
+| AP-10 | Mixed target responsibilities | Scheduling/incrementality |
+| AP-12, AP-15 | Assignment timing and intended overrides | Property contracts |
+| AP-17 | Update before Include, not merely a shared ItemGroup | Missing metadata |
+| AP-18 | Real direct dependencies versus redundant edges | Graph/asset contracts |

package/package/corpus/skills/msbuild/references/antipatterns/incremental-build-inputs-outputs.md

@@ -0,0 +1,57 @@
+# Incremental inputs and outputs on custom targets
+
+Expensive artifact-producing targets need complete inputs and real outputs. This is not a rule
+that every validation/orchestration target must have a stamp file.
+
+The original catalog's project-file-only example was incomplete when generation depended on
+`$(Version)`: a command-line property can change without touching the project file. A stable
+value-input file can represent that dependency while a separate target registers outputs even
+when generation is skipped:
+
+```xml
+<Target Name="WriteBuildInfoInputs">
+  <ItemGroup>
+    <FileWrites Include="$(IntermediateOutputPath)BuildInfo.inputs" />
+  </ItemGroup>
+  <MakeDir Directories="$(IntermediateOutputPath)" />
+  <WriteLinesToFile File="$(IntermediateOutputPath)BuildInfo.inputs"
+                    Lines="$(Version)" Overwrite="true" WriteOnlyWhenDifferent="true" />
+</Target>
+
+<Target Name="GenerateBuildInfo"
+        DependsOnTargets="WriteBuildInfoInputs"
+        Inputs="$(MSBuildProjectFullPath);$(MSBuildAllProjects);$(IntermediateOutputPath)BuildInfo.inputs"
+        Outputs="$(IntermediateOutputPath)BuildInfo.g.cs">
+  <WriteLinesToFile File="$(IntermediateOutputPath)BuildInfo.g.cs"
+                    Lines="// Generated for $(Version)" Overwrite="true" />
+</Target>
+
+<Target Name="RegisterBuildInfo"
+        BeforeTargets="CoreCompile"
+        DependsOnTargets="GenerateBuildInfo">
+  <ItemGroup>
+    <Compile Include="$(IntermediateOutputPath)BuildInfo.g.cs" />
+    <FileWrites Include="$(IntermediateOutputPath)BuildInfo.g.cs" />
+  </ItemGroup>
+</Target>
+```
+
+This illustrates a simple version-dependent producer. Adapt it to the actual generator:
+
+- Add its templates, tools, configuration, and source files to the inputs.
+- Serialize every relevant non-file value into a stable fingerprint without losing distinctions.
+  Git/clock/network state is not tracked merely by listing the project file.
+- Keep outputs in stable, configuration/framework/runtime-isolated intermediate paths.
+- Ensure generated compile items are registered exactly once on both first and skipped builds.
+  Intermediate files are normally excluded from SDK default source globs.
+- Register the state file in its producer before generation can fail, so failed-build cleanup
+  records its ownership too. Register generated outputs on successful and skipped generation.
+  FileWrites is not a substitute for incremental inputs/outputs or compiler item inclusion.
+- Timestamp checks do not remember a removed wildcard input. Track input-set membership and
+  remove obsolete owned outputs when the generator's contract requires it.
+
+Verify first build, identical second build, a relevant file/property change, removed inputs,
+deleted output, successful-build Clean, and failed-generation Clean. Do not assume a timestamp-only
+model can distinguish arbitrary same-timestamp mutations. Keep mutation/cleanup experiments confined
+to approved disposable outputs. See [incremental-build](../incremental-build.md) for the full workflow
+and IDE checks.

package/package/corpus/skills/msbuild/references/antipatterns/private-assets.md

@@ -0,0 +1,29 @@
+# PrivateAssets for analyzers and build tools
+
+Use `PrivateAssets="all"` when a package is an implementation-only build dependency and must not
+become a dependency of consumers of the produced package.
+
+```xml
+<!-- These packages are intended to remain local to this project's build. -->
+<PackageReference Include="StyleCop.Analyzers" Version="1.2.0-beta.556" PrivateAssets="all" />
+<PackageReference Include="Microsoft.SourceLink.GitHub" Version="8.0.0" PrivateAssets="all" />
+<PackageReference Include="MinVer" Version="5.0.0" PrivateAssets="all" />
+```
+
+Typical candidates from the original catalog include:
+
+- Analyzer and code-fix packages.
+- Source generators intended to run only in the producer.
+- SourceLink providers.
+- Versioning tools such as MinVer or Nerdbank.GitVersioning.
+- Build-only compatibility/checking tools.
+
+Do not infer a leak merely from a missing literal attribute. Inspect evaluated metadata,
+`IncludeAssets`/`ExcludeAssets`, package contents, generated restore assets, and the packed
+dependency contract. PackageReference's default private-asset categories already restrict some
+asset flow, while `buildTransitive` and other dependencies can have different effects.
+
+An analyzer or build extension deliberately distributed to consumers is not a private
+implementation detail. Do not suppress intentional transitive behavior, hide required runtime
+dependencies, or treat `PrivateAssets` as a way to skip building a project.
+Verify the produced package and a representative consumer before declaring the change safe.

package/package/corpus/skills/msbuild/references/binlog-failure-analysis.md

@@ -0,0 +1,85 @@
+# Analyzing MSBuild failures with binary logs
+
+Based on the original binlog failure analysis skill. Use MSBuild's built-in replay to diagnose
+an existing `.binlog`, including when the original checkout is unavailable.
+
+## Before analysis
+
+- Reuse a log that records the relevant invocation. If none exists and the build can be reproduced,
+  follow [binlog-generation](binlog-generation.md) with the original arguments.
+- A `.binlog` is binary. Do not use a text reader, `strings`, or text search directly on it.
+- Recorded paths identify the original build; they are not permission to search unrelated
+  checkouts or proof that source/project files exist locally.
+- Synthesize findings as evidence emerges. Stop once actionable causes and remaining uncertainty
+  are clear rather than spending the whole investigation collecting unrelated events.
+
+## Replay a binary log
+
+Choose unused text-log filenames, substitute the supplied binary-log path, and replay it:
+
+```powershell
+dotnet msbuild ".\build.binlog" -noconlog -fl "-flp:logfile=full-01.log;verbosity=diagnostic;PerformanceSummary" -fl1 "-flp1:logfile=errors-01.log;errorsonly" -fl2 "-flp2:logfile=warnings-01.log;warningsonly"
+```
+
+Quote each complete semicolon-delimited logger argument, especially in PowerShell. The command
+reads the recorded build; it does not restore or rebuild its projects. A compatible `MSBuild.exe`
+can replace `dotnet msbuild`; no analysis server or extra package is required.
+
+Confirm the command completed and the diagnostic log is nonempty. Errors-only or warnings-only
+logs can legitimately be empty. If the installed MSBuild cannot read the binary-log format,
+report that blocker and the need for compatible tooling instead of pretending analysis succeeded.
+
+Replay success is **not** proof that the recorded build succeeded. Replay duration is **not**
+the recorded build's elapsed time. The same replay mechanics serve
+[performance diagnostics](build-perf-diagnostics.md): use recorded events and the Project,
+Target, and Task Performance Summaries, not the time spent converting the log.
+
+## Inspect the replayed text
+
+Start with errors, then search the diagnostic text around the actual codes, targets, and projects:
+
+```powershell
+Get-Content -LiteralPath .\errors-01.log
+Select-String -LiteralPath .\full-01.log -Pattern 'CS0246', 'CoreCompile', 'Build FAILED' -Context 2
+```
+
+The patterns above are examples, not a filter that should discard other error codes. Inspect the
+recorded evidence needed to explain the failure:
+
+- Build errors and warnings, including custom task errors.
+- Project-instance identity, configuration, target framework, and global properties.
+- Property assignments and item/reference metadata visible in the log.
+- Evaluation, import, target, and task execution or skip messages.
+
+Text replay cannot manufacture data that was not recorded and does not guarantee extraction of
+embedded project/import source. Read source only when it is available in the current checkout.
+If the responsible definition is absent from both local source and replayed text, state that
+limitation and request the specific missing evidence; do not invent an exact edit location.
+
+## Find independent causes
+
+1. Associate each error with its project **instance**, target, and task. The same project path
+   under different global properties can represent distinct builds.
+2. Follow producer/consumer dependencies. Parallel log order is not causal order: a missing
+   referenced assembly may be downstream of a failed producer, while another project has an
+   independent failure.
+3. Inspect the actual values seen by the failing task rather than assuming the project body's
+   value won. Check conditions, imports, item metadata, and command-line global properties.
+4. Connect each root cause to a minimal repair. A namespace error alone does not prove which
+   package should be added; confirm the relevant references and target framework.
+
+Use [msbuild-antipatterns](msbuild-antipatterns.md) for a demonstrated authoring defect,
+[extension-points](extension-points.md) for imports/hooks or packed-layout issues, and
+[incremental-build](incremental-build.md) for stale outputs or incorrect skip decisions.
+Do not turn failure diagnosis into an unrequested modernization pass.
+
+## Verify and report
+
+If source can be changed, rerun the original failing scenario with a new binary log, preserving
+its configuration/framework/properties. Confirm the independent root errors and their cascades
+are resolved, and exercise affected dependents. Check a no-change build when targets/items/outputs
+were changed.
+
+For artifact-only analysis, provide proposed changes and explicitly say they were not applied
+or rebuilt. Report the evidence, root causes versus downstream failures, minimal repair, and
+actual verification status. Treat replayed text as sensitive diagnostic data just like its binlog.