@cratis/pi 7.101.0 → 7.103.0

package/package/corpus/skills/cratis-engineering-local-cross-repo-verification/scripts/npm-restore-check.cjs

@@ -0,0 +1,109 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+'use strict';
+
+// Read-only guard: all validation completes before the shell restores either file.
+const fs = require('fs');
+const path = require('path');
+const {isDeepStrictEqual: equal} = require('util');
+const [repo, backup] = process.argv.slice(2);
+const read = (base, name) => fs.readFileSync(path.join(base, name), 'utf8');
+const json = (base, name) => JSON.parse(read(base, name));
+const refuse = message => { throw new Error(message); };
+
+function overlayResolutions(original, expected) {
+    const before = original.resolutions || {};
+    const after = expected.resolutions || {};
+    return new Map(Object.entries(after).filter(([name, value]) => !equal(value, before[name])));
+}
+
+function checkManifest(original, current, overlay) {
+    for (const [name, value] of overlay) {
+        const actual = (current.resolutions || {})[name];
+        if (actual !== value && !equal(actual, (original.resolutions || {})[name]))
+            refuse('Changed overlay resolution: ' + name);
+    }
+    const withoutOverlay = manifest => {
+        const copy = JSON.parse(JSON.stringify(manifest));
+        if (copy.resolutions) {
+            for (const name of overlay.keys()) delete copy.resolutions[name];
+            if (!Object.keys(copy.resolutions).length) delete copy.resolutions;
+        }
+        return copy;
+    };
+    if (!equal(withoutOverlay(current), withoutOverlay(original)))
+        refuse('Unrelated package.json changes');
+}
+
+// Yarn 4 lockfiles have quoted top-level descriptor keys and indented bodies.
+// Preserve bytes for every unaffected block, including metadata and comments;
+// unsupported syntax or install churn is a conflict, not permission to overwrite.
+function lockBlocks(text) {
+    const starts = [...text.matchAll(/^[^\s#].*$/gm)];
+    const header = text.slice(0, starts.length ? starts[0].index : text.length);
+    const blocks = new Map();
+    for (let index = 0; index < starts.length; index++) {
+        const line = starts[index][0];
+        const key = line === '__metadata:' ? '__metadata' : JSON.parse(line.slice(0, -1));
+        if (!line.endsWith(':') || typeof key !== 'string' || blocks.has(key))
+            refuse('Unsupported or duplicate lockfile key');
+        blocks.set(key, text.slice(starts[index].index, starts[index + 1]?.index ?? text.length));
+    }
+    return {header, blocks};
+}
+
+function descriptorNames(key) {
+    return key.split(', ').map(descriptor => {
+        const match = descriptor.match(/^(@[^/]+\/[^@]+|[^@]+)@/);
+        if (!match) refuse('Unsupported lockfile descriptor: ' + descriptor);
+        return match[1];
+    });
+}
+
+function localBlock(key, body, overlay) {
+    if (key === '__metadata') return false;
+    const names = descriptorNames(key);
+    const name = names[0];
+    if (!overlay.has(name) || names.some(other => other !== name)) return false;
+    const match = body.match(/^  resolution: (.+)$/m);
+    if (!match) return false;
+    const resolution = JSON.parse(match[1]);
+    const prefix = name + '@' + overlay.get(name);
+    // Yarn may append archive/locator parameters, but not a different filename.
+    return [prefix, encodeURI(prefix)].some(value => resolution === value ||
+        resolution.startsWith(value + '::') || resolution.startsWith(value + '#'));
+}
+
+function checkLock(original, current, overlay) {
+    if (original === current) return;
+    const before = lockBlocks(original), after = lockBlocks(current);
+    if (before.header !== after.header) refuse('Changed lockfile header');
+    const localNames = new Set();
+    for (const [key, body] of after.blocks) {
+        if (before.blocks.get(key) === body) continue;
+        if (!localBlock(key, body, overlay)) refuse('Unrelated lockfile change: ' + key);
+        for (const name of descriptorNames(key)) localNames.add(name);
+    }
+    for (const [key, body] of before.blocks) {
+        if (after.blocks.get(key) === body) continue;
+        // Only entries for locally replaced package names may change or vanish.
+        // Changed entries were already checked against the exact tarball above.
+        if (key === '__metadata' ||
+            descriptorNames(key).some(name => !localNames.has(name)))
+            refuse('Changed or removed unrelated lockfile entry: ' + key);
+    }
+}
+
+try {
+    const original = json(backup, 'package.json');
+    const expected = json(backup, 'expected-package.json');
+    const overlay = overlayResolutions(original, expected);
+    checkManifest(original, json(repo, 'package.json'), overlay);
+    const beforeExists = fs.existsSync(path.join(backup, 'yarn.lock'));
+    const afterExists = fs.existsSync(path.join(repo, 'yarn.lock'));
+    if (beforeExists !== afterExists) refuse('Lockfile created or removed; manual review required');
+    if (beforeExists) checkLock(read(backup, 'yarn.lock'), read(repo, 'yarn.lock'), overlay);
+} catch (error) {
+    console.error('ERROR: ' + error.message);
+    process.exitCode = 2;
+}

package/package/corpus/skills/csharp-refactoring/LICENSE

@@ -0,0 +1,23 @@
+The MIT License (MIT)
+
+Copyright (c) .NET Foundation and Contributors
+
+All rights reserved.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/package/corpus/skills/csharp-refactoring/NOTICE

@@ -0,0 +1,22 @@
+C# Refactoring (behavior-preserving)
+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/csharp-refactoring/SKILL.md
+
+Changes made by Cratis:
+
+LICENSE:
+- Copy upstream MIT license and copyright verbatim.
+
+SKILL.md:
+- Normalize frontmatter serialization, add MIT license where absent; preserve name and description.
+- Add marked modification/source comment and applicability/Cratis precedence line.
+- Add the requested Cratis persisted-event, proxy, Orleans identity and framework-public-API contract section.
+- 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.
+- Remove references to the dotnet-upgrade skill; point to the repository's own upgrade workflow.
+
+references/operation-catalog.md:
+- Replace the upstream issue reference with a plain statement of the behavior.
+
+NOTICE: Add this attribution, change list, and any download/execution disclosure.

package/package/corpus/skills/csharp-refactoring/SKILL.md

@@ -0,0 +1,175 @@
+---
+name: csharp-refactoring
+description: 'Safely refactors C#/.NET code without changing behavior: rename, move, extract, inline, merge, consolidate, deduplicate, split, or modernize, including partial or generated declarations, public APIs, serialization and reflection names, friend assemblies, conditional compilation, and multi-targeted projects. Use when a request asks for a refactor, or calls a feature, bug fix, upgrade, or public nullability change a refactor and the behavior-changing part must be separated or declined. Not for ordinary feature or bug fixes, standalone framework or package upgrades, adding tests, or formatting-only work.'
+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/csharp-refactoring/SKILL.md; see NOTICE) -->
+
+# C# Refactoring (behavior-preserving)
+
+Cratis rules in `.cratis/ai/rules/` (including `csharp.md`, `specs.csharp.md`, and `orleans.md`) and the `cratis-*` skills win where they differ.
+
+A refactor changes **structure**, never observable **behavior**. Do the edit with binding-aware tools,
+then confirm behavior held with a build + the relevant tests. Keep the effort proportional to the change:
+a one-line local rename does not need the ceremony a public multi-targeted change does.
+
+## Mandatory gate: classify before validation or editing
+
+Read only enough repository context to classify **each requested operation**. Do this before restoring,
+building, or making an edit. Classification precedence is:
+
+- If the request explicitly asks for at least one separable behavior-preserving operation, complete
+  that structural work and defer only the behavior-changing or contract-changing operations. Do not
+  invent or infer structural work to avoid the stop response.
+- If the structural and behavior-changing parts cannot be separated, use the whole-request stop
+  response and state why they are inseparable.
+- Otherwise, use the whole-request stop response only when **every** requested operation is outside
+  behavior-preserving refactoring.
+
+For a whole request that is outside behavior-preserving refactoring:
+
+1. State: `Not a behavior-preserving refactor: <specific reason>.`
+2. State: `No files changed.`
+3. State: `Next workflow: <workflow>.` Then stop. Do not add manual implementation steps, alternatives,
+   an offer to proceed without the workflow, or a follow-up question — even when that workflow is unavailable.
+
+| Requested as a "refactor" | Classification and action |
+|---|---|
+| Framework or NuGet version change | **Upgrade.** Do not edit or validate the upgrade here; hand off to the repository's upgrade workflow. |
+| New capability, flag, endpoint, tier, or behavior | **Feature.** Do not implement it here; hand off to the repository's feature workflow. |
+| Threshold, rate, output, or bug-result change | **Behavior change.** Defer it and hand off to the repository's bug-fix or behavior-change workflow; still complete any clearly separable structural operation. |
+| Tighten or loosen a shipped/public nullable annotation | **Source-contract change.** Leave the declaration and API record unchanged; hand off to the repository's API-contract workflow. |
+
+For a mixed request, never stop after classification. Perform the separable structural operation,
+explicitly defer the behavior/contract change, and never state `No files changed.` after completing
+structural work. Never modify tests to make an unauthorized behavior change appear preserved.
+
+## Work only in the current workspace
+
+Use the current agent workspace as the boundary. If it is a Git checkout, resolve its repository root
+(`git rev-parse --show-toplevel`) and stay inside it. If Git metadata is absent, treat the current working
+directory and its subdirectories as the boundary, and use a solution or project named in the request
+inside it; Git is not a prerequisite for a refactor. Resolve prompt-provided relative paths inside that
+boundary.
+
+Search and edit only that workspace. Never use filesystem-wide search or select a similarly named clone,
+another worktree, build output, or unrelated temporary directory because a file also exists there. If a
+named path is absent, stop and report the mismatch instead of guessing another workspace. If a tool rejects
+an in-workspace path for a mechanical reason such as path form or unsupported tool root, retry through
+another in-workspace mechanism. If the rejection is a permission or policy denial, report it instead of
+working around it. Never search outside the boundary.
+
+## Rename / move by bindings, not text
+
+The #1 way a "rename" silently corrupts code is editing textual matches (comments, strings, unrelated
+overloads) instead of real **bindings**. Find every binding reference first, then edit semantically. Use
+the strongest tool available: an IDE/Roslyn workspace refactoring, then the C# LSP the
+[`dotnet` plugin declares](https://github.com/dotnet/skills/blob/main/plugins/dotnet/lsp.json)
+(`findReferences`, `goToDefinition`, `incomingCalls`, `rename` code action), then analyzer code-fixes /
+Roslynator, then compiler-validated edits (edit the true bindings, rebuild, let the compiler flag misses).
+Plain find/replace only when scope is provably tiny and every hit is verified. Include **every** `partial`
+declaration, and edit the generator input, never generated (`*.g.cs`) output.
+
+For the operation → Roslyn-provider mapping and representative PRs, see
+[references/operation-catalog.md](references/operation-catalog.md).
+
+## Consolidate toward the existing source of truth
+
+When de-duplicating, preserve the ownership direction stated by the code or request. If `B` duplicates
+an implementation already owned by `A`, keep `A` canonical and make `B` delegate to it; do not invert
+the dependency merely because either direction compiles. Preserve public compatibility wrappers when
+the duplicate surface is shipped, and migrate only in-repo callers that are safe to move.
+
+## Decisions that change the edit
+
+Use the first matching row instead of applying the requested operation mechanically:
+
+| Situation | Do | Never |
+|---|---|---|
+| Inline an internal, unshipped pass-through wrapper | Migrate every binding reference to the target, remove the wrapper, then compile to catch misses. | Keep dead indirection "for compatibility" when no compatibility boundary exists. |
+| Inline or remove a shipped/public wrapper | Migrate ordinary in-repo callers, but retain an `[Obsolete]` forwarding entry point unless the request explicitly authorizes a breaking change. | Delete a shipped API merely because all current source callers were migrated. |
+| Rename a member reached by a string, reflection, DI, or configuration | Rename binding-based callers; preserve the observed external name with a forwarding shim or metadata, and exercise the old-name path. | Rewrite an external/configured name just to make the new source name consistent. |
+| Extract duplicated logic whose callers pass different values | Extract the algorithm and pass each caller's existing inputs through unchanged. | Collapse distinct inputs, evaluation order, rounding, or side effects into one caller's version. |
+| Rename code compiled under `#if` or multiple TFMs | Update every source branch and validate each target framework explicitly. | Treat a green default-target build as evidence for unbuilt branches. |
+| Merge near-identical types | Parameterize only the values that differ, migrate every construction site, and preserve each old value exactly. If the old types are internal/unshipped and the request says to merge into one type, delete their declarations. | Retain unnecessary aliases, static holders, factories, or wrapper types that leave the requested merge incomplete; introduce a new hierarchy or behavior. |
+
+## Preserve contracts beyond C# call sites
+
+Compilation proves binding compatibility, not every external contract. Before renaming or moving a
+type/member, check whether its name or metadata is observed by serialization, reflection, dependency
+injection, configuration binding, source generators, P/Invoke, or `dynamic`.
+
+| Boundary | Required decision |
+|---|---|
+| Serialized/configuration name | Preserve the external name with the repository's existing mechanism (for example, `JsonPropertyName`) while migrating C# callers; run a focused round-trip or payload test. |
+| Public nullable annotation | The mandatory classification gate applies: leave it unchanged and hand off as a source-contract change. |
+| Uncovered reflection or runtime lookup | Do not guess that a compile-clean rename is safe. Preserve the observed name or stop and report the unverified runtime boundary. |
+
+## Verify proportionally
+
+Confirm behavior is preserved after the edit — scaled to blast radius, not a fixed ceremony:
+
+- **Local / private** (method-local or `private` member, one file, single target framework, no public
+  surface, no `partial`/generated/`#if`): skip a separate baseline unless the tree is already suspect.
+  Make the edit, then run the narrowest build and relevant tests once. Let the compiler catch missed
+  references.
+- **Cross-boundary** (public/shipped symbol, multi-targeted project, `#if`/platform branches, or
+  `partial`/generated code): establish a baseline, then run an explicit build and the relevant tests for
+  **each** target framework after the edit (a test command's implicit build is not separate build evidence;
+  a green default build can hide a break on another TFM), and run the hazards check below.
+
+Use the repo's own build/test workflow when it documents one (`README`/`CONTRIBUTING`, `build.*`, `eng/`,
+`global.json`, `.github/workflows`); its instructions win over any generic command.
+
+### Typical workflow (one operation)
+1. Choose one named refactoring operation and keep the step focused on that operation only.
+2. Find true binding references (`findReferences`/`goToDefinition`/rename) and include all `partial` declarations.
+3. Establish a baseline first only for a cross-boundary change or a tree not already known green.
+4. Apply the change via the most semantics-aware tool available; avoid blind find/replace when possible.
+5. Rebuild and run the relevant tests. If the gate goes red, report the failure and repair or reassess only
+  your edit; never discard unrelated worktree changes.
+
+Otherwise:
+```bash
+dotnet build   # 0 errors
+dotnet test    # stays green; same pass count as before
+```
+
+One operation per step; never mix a refactor and a behavior change in the same step. On red, stop and report the failure; repair only your edit without discarding unrelated worktree changes.
+
+## Final response contract
+
+Keep the handoff concise and evidence-based:
+
+- **Refactor:** name the structural operation and the symbols/files changed.
+- **Preserved:** name the behavior or compatibility boundary and the mechanism that preserved it.
+- **Validation:** report the exact commands and observed result; never claim success after a failed restore,
+  build, target framework, or test run.
+- **Deferred:** for a mixed request, name the behavior/contract change intentionally left undone and its
+  correct next workflow. Omit this line when nothing was deferred.
+
+## Cross-boundary hazards (only when it touches a boundary)
+
+If — and only if — the change touches a **public** symbol, a **multi-targeted** project, or
+`partial`/generated code, some breaks won't show up as a failing test. Search the repo for the surface
+that governs the symbol (don't assume): the public-API gate (`PublicAPI.Shipped/Unshipped.txt` for
+PublicApiAnalyzers, and/or `ApiCompat`/`<EnablePackageValidation>` — not interchangeable),
+`<TargetFrameworks>`/`#if` branches, and `InternalsVisibleTo`. Moving a public type to another assembly
+needs `[TypeForwardedTo]` in the original assembly; a move within one assembly does not. A public
+*rename* needs an `[Obsolete]` shim, not a forwarder. For a provably local/private change, skip these
+checks.
+
+## Stop an in-scope refactor when
+
+- The baseline is already red (you can't prove you preserved behavior).
+- The requested structural change would alter a public/shipped API and no compatibility shim or forwarder
+  can preserve it. Report the boundary. Use the gate's handoff format when no structural work was completed;
+  after separable work, put the incompatible operation on the `Deferred:` line instead. Do not ask to make
+  the breaking change.
+- Equivalence depends on runtime behavior tests don't cover (reflection, DI, serialization, `dynamic`,
+  P/Invoke) — report the unverified boundary instead of claiming behavior was preserved.
+
+## Contracts the compiler cannot see in Cratis code
+
+Preserve `[EventType]` identifiers and type names of persisted events, generated TypeScript proxies of Arc commands/queries, `[Alias]`/serializer ids in Orleans, and public API of framework packages (semver).

package/package/corpus/skills/csharp-refactoring/references/operation-catalog.md

@@ -0,0 +1,37 @@
+# C# refactoring operation catalog (detail)
+
+Load this when you need the full operation taxonomy or the Roslyn provider each maps to.
+The core SKILL.md keeps only the short operation list; this file is the depth.
+
+## Contents
+
+- Operation catalog (provider, recurrence, representative PR)
+- "Modernize" is defined by the repo's analyzer config
+
+## Operation catalog
+
+Canonical operations, aligned with Roslyn's own IDE refactoring providers
+(`src/Features/CSharp/Portable/CodeRefactorings`). The provider column is informational — a
+headless CLI agent usually cannot invoke these IDE code actions directly, so apply them via the fallback
+ladder in SKILL.md.
+
+| Operation | Roslyn provider / tool | Recurrence | Representative real PR |
+|-----------|------------------------|-----------:|------------------------|
+| **Rename** symbol / type / file | rename engine (`Renamer`) | high | _runtime_ "Rename `DISABLE_CROSSGEN`"; _sdk_ "Rename `dnup` to `dotnetup`" |
+| **Move** type / member / file | `MoveType`, `MoveStaticMembers` | high | _runtime_ "Move DSA tests into System.Security.Cryptography"; _sdk_ "Move SDK task unit test projects from src/ to test/" |
+| **Consolidate / de-duplicate** | analyzer-assisted | high | _runtime_ "Consolidate ComWrappers implementation across platforms" |
+| **Modernize / simplify** idioms | `UseExplicitOrImplicitType`, `UseRecursivePatterns`, `ConvertLocalFunctionToMethod`, `AddAwait` | high | _roslyn_ "Simplify lots of redundant code in code fix providers" |
+| **Split** large class / file / assembly | extract + move | medium | _roslyn_ "Split `FeatureSwitchManager`"; _runtime_ "Move RPC contracts to a separate assembly" |
+| **Extract** method / class / interface | `ExtractClass`, extract-method, extract-interface | medium | _runtime_ "Extract `ManifestBuilder` and `EventListener`" |
+| **Inline** method / local / constant | `InlineMethod`, `InlineTemporary` | lower | _runtime_ "Refactor `UInt128` division" |
+| **Pull up / push down** member | `PullMemberUp` | tail | move members between a type and its base/interface |
+| **Sync namespace** to folder | `SyncNamespace` | tail | align `namespace` with folder layout after a move |
+
+## "Modernize" is defined by the repo's analyzer config, not personal taste
+
+These repos drive idiom rules through `.editorconfig` + `EnforceOnBuild` (which enforces
+code-style analyzers during build). Apply the fixes the repo's own analyzers request
+(IDE00xx / CAxxxx) via `dotnet format` / code-fixes; don't impose a style it hasn't opted into, and don't
+blanket-suppress diagnostics to make an edit "pass." For _adopting_ nullable annotations specifically, see
+the repository's nullable migration workflow; enabling nullable across a project or changing public API
+annotations is a migration or contract change, not a canonical behavior-preserving refactoring operation.

package/package/corpus/skills/directory-build-organization/LICENSE

@@ -0,0 +1,23 @@
+The MIT License (MIT)
+
+Copyright (c) .NET Foundation and Contributors
+
+All rights reserved.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/package/corpus/skills/directory-build-organization/NOTICE

@@ -0,0 +1,21 @@
+Organizing Build Infrastructure with Directory.Build Files
+Copyright (c) .NET Foundation and Contributors
+Licensed under the MIT License. See LICENSE.
+
+Upstream source: https://github.com/dotnet/skills/blob/a6bf43ab61967c30919334986515163ab24d7635/plugins/dotnet-msbuild/skills/directory-build-organization/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.
+- 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/multi-level-examples.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/directory-build-organization/SKILL.md

@@ -0,0 +1,205 @@
+---
+name: directory-build-organization
+description: 'Organizes shared MSBuild policy across Directory.Build.props, Directory.Build.targets, Directory.Build.rsp, and Directory.Packages.props: centralizing repeated properties, targets, and package versions, hierarchy and import structure, props-versus-targets placement, and folder or project exceptions. Use when two or more projects repeat MSBuild policy, or an existing Directory.Build hierarchy has an import, placement, or layering defect, even if only one project is affected. Not for a one-project repo without a Directory.Build file, property value or condition semantics, legacy-to-SDK migration, or non-MSBuild systems.'
+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-msbuild/skills/directory-build-organization/SKILL.md; see NOTICE) -->
+
+# Organizing Build Infrastructure with Directory.Build Files
+
+Cratis rules in `.cratis/ai/rules/` (including `csharp.md`, `specs.csharp.md`, and `orleans.md`) and the `cratis-*` skills win where they differ.
+
+## Intent control
+
+- For "should we", "how should we organize", "recommend", "advise", or review
+  requests, inspect the actual project files and return a proposed layout only.
+  Do not create or edit files unless the user explicitly asks to apply, move,
+  centralize, or clean up the configuration.
+- Before summarizing, verify which project retains each project-specific
+  property, item, or target. Name the actual file; do not infer it from sibling
+  names.
+- Recommend a verification command only after discovering a real `.sln`,
+  `.slnx`, `.proj`, or project file at that path. If no repo-root entry point
+  exists, give commands for the discovered projects or state that the entry
+  point was not found.
+- Every advice response must explain that `Microsoft.Common.props` searches
+  upward from each project and automatically imports the nearest
+  `Directory.Build.props` early; project values can then override shared
+  defaults. Explain the equivalent late `Microsoft.Common.targets` import when
+  recommending `Directory.Build.targets`.
+
+## Directory.Build.props vs Directory.Build.targets
+
+Understanding which file to use is critical. They differ in **when** they are imported during evaluation:
+
+**Evaluation order:**
+
+```
+Microsoft.Common.props imports Directory.Build.props early
+→ project body and package/project imports evaluate
+→ Microsoft.Common.targets imports Directory.Build.targets late
+```
+
+| Use `.props` for | Use `.targets` for |
+|---|---|
+| Setting property defaults | Custom build targets |
+| Common item definitions | Late-bound property overrides |
+| Properties projects can override | Post-build steps |
+| Assembly/package metadata | Conditional logic on final values |
+| Analyzer PackageReferences | Targets that depend on SDK-defined properties |
+
+**Rule of thumb:** Properties and items go in `.props`. Custom targets and late-bound logic go in `.targets`.
+
+Because `.props` is imported before the project file, the project can override any value set there. Because `.targets` is imported after everything, it gets the final say—but projects cannot override `.targets` values.
+
+### ⚠️ Critical: TargetFramework Availability in .props vs .targets
+
+**Property conditions on `$(TargetFramework)` in `.props` files silently fail for single-targeting projects** — the property is empty during `.props` evaluation. Move TFM-conditional properties to `.targets` instead. ItemGroup and Target conditions are not affected.
+
+See [targetframework-props-pitfall.md](references/targetframework-props-pitfall.md) for the full explanation.
+
+## Directory.Build.props
+
+Good candidates: language settings, assembly/package metadata, build warnings, code analysis, common analyzers.
+
+```xml
+<Project>
+  <PropertyGroup>
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
+    <EnforceCodeStyleInBuild>true</EnforceCodeStyleInBuild>
+    <Company>Contoso</Company>
+    <Authors>Contoso Engineering</Authors>
+  </PropertyGroup>
+</Project>
+```
+
+**Do NOT put here:** project-specific TFMs, project-specific PackageReferences, targets/build logic, or properties depending on SDK-defined values (not available during `.props` evaluation).
+
+## Directory.Build.targets
+
+Good candidates: custom build targets, late-bound property overrides (values depending on SDK properties), post-build validation.
+
+```xml
+<Project>
+  <Target Name="ValidateProjectSettings" BeforeTargets="Build">
+    <Error Text="All libraries must target netstandard2.0 or higher"
+           Condition="'$(OutputType)' == 'Library' AND '$(TargetFramework)' == 'net472'" />
+  </Target>
+
+  <PropertyGroup>
+    <!-- DocumentationFile depends on OutputPath, which is set by the SDK -->
+    <DocumentationFile Condition="'$(IsPackable)' == 'true'">$(OutputPath)$(AssemblyName).xml</DocumentationFile>
+  </PropertyGroup>
+</Project>
+```
+
+## Directory.Packages.props (Central Package Management)
+
+Central Package Management (CPM) provides a single source of truth for all NuGet package versions. See [https://learn.microsoft.com/en-us/nuget/consume-packages/central-package-management](https://learn.microsoft.com/en-us/nuget/consume-packages/central-package-management) for details.
+
+**Enable CPM in `Directory.Packages.props` at the repo root:**
+
+```xml
+<Project>
+  <PropertyGroup>
+    <ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageVersion Include="Microsoft.Extensions.Logging" Version="8.0.0" />
+    <PackageVersion Include="Newtonsoft.Json" Version="13.0.3" />
+    <PackageVersion Include="xunit" Version="2.9.0" />
+    <PackageVersion Include="xunit.runner.visualstudio" Version="2.8.2" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <!-- GlobalPackageReference applies to ALL projects — great for analyzers -->
+    <GlobalPackageReference Include="StyleCop.Analyzers" Version="1.2.0-beta.556" />
+    <GlobalPackageReference Include="Microsoft.CodeAnalysis.NetAnalyzers" Version="8.0.0" />
+  </ItemGroup>
+</Project>
+```
+
+## Directory.Build.rsp
+
+Contains default MSBuild CLI arguments applied to all builds under the directory tree.
+
+**Example `Directory.Build.rsp`:**
+
+```
+/maxcpucount
+/nodeReuse:false
+/consoleLoggerParameters:Summary;ForceNoAlign
+/warnAsMessage:MSB3277
+```
+
+- Works with both `msbuild` and `dotnet` CLI in modern .NET versions
+- Great for enforcing consistent CI and local build flags
+- Each argument goes on its own line
+
+## Multi-level Directory.Build Files
+
+MSBuild only auto-imports the **first** `Directory.Build.props` (or `.targets`) it finds walking up from the project directory. To chain multiple levels, explicitly import the parent at the **top** of the inner file. See [multi-level-examples](references/multi-level-examples.md) for full file examples.
+
+```xml
+<Project>
+  <Import Project="$([MSBuild]::GetPathOfFileAbove('Directory.Build.props', '$(MSBuildThisFileDirectory)../'))"
+         Condition="Exists('$([MSBuild]::GetPathOfFileAbove('Directory.Build.props', '$(MSBuildThisFileDirectory)../'))')" />
+
+  <!-- Inner-level overrides go here -->
+</Project>
+```
+
+**Example layout:**
+
+```
+repo/
+  Directory.Build.props          ← repo-wide (lang version, company info, analyzers)
+  Directory.Build.targets        ← repo-wide targets
+  Directory.Packages.props       ← central package versions
+  src/
+    Directory.Build.props        ← src-specific (imports repo-level, sets IsPackable=true)
+  test/
+    Directory.Build.props        ← test-specific (imports repo-level, sets IsPackable=false, adds test packages)
+```
+
+## Artifact Output Layout (.NET 8+)
+
+Set `<ArtifactsPath>$(MSBuildThisFileDirectory)artifacts</ArtifactsPath>` in `Directory.Build.props` to automatically produce project-name-separated `bin/`, `obj/`, and `publish/` directories under a single `artifacts/` folder, avoiding bin/obj clashes by default. See [common-patterns](references/common-patterns.md) for the directory layout and additional patterns (conditional settings by project type, post-pack validation).
+
+## Workflow: Organizing Build Infrastructure
+
+1. **Audit all `.csproj` files** — Catalog every `<PropertyGroup>`, `<ItemGroup>`, and custom `<Target>` across the solution. Note which settings repeat and which are project-specific.
+2. **Create root `Directory.Build.props`** — Move shared property defaults (LangVersion, Nullable, TreatWarningsAsErrors, metadata) here. These are imported before the project file so projects can override them.
+3. **Create root `Directory.Build.targets`** — Move custom build targets, post-build validation, and any properties that depend on SDK-defined values (e.g., `OutputPath`, `TargetFramework` for single-targeting projects) here. These are imported after the SDK so all properties are available.
+4. **Create `Directory.Packages.props`** — Enable Central Package Management (`ManagePackageVersionsCentrally`), list all `PackageVersion` entries, and remove `Version=` from `PackageReference` items in `.csproj` files.
+5. **Set up multi-level hierarchy** — Create inner `Directory.Build.props` files for `src/` and `test/` folders with distinct settings. Use `GetPathOfFileAbove` to chain to the parent.
+6. **Simplify `.csproj` files** — Remove all centralized properties, version attributes, and duplicated targets. Each project should only contain what is unique to it.
+7. **Validate** — Run restore/build against the discovered `.sln`, `.slnx`,
+   `.proj`, or project path, for example
+   `dotnet restore <entrypoint> && dotnet build <entrypoint>`. If no root
+   entrypoint exists, validate each discovered project explicitly instead of
+   claiming a repo-root build. Use
+   `dotnet msbuild <project> -pp:output.xml` to inspect the final merged view.
+
+## Troubleshooting
+
+| Problem | Cause | Fix |
+|---|---|---|
+| `Directory.Build.props` isn't picked up | File name casing wrong (exact match required on Linux/macOS) | Verify exact casing: `Directory.Build.props` (capital D, B) |
+| Properties from `.props` are ignored by projects | Project sets the same property after the import | Move the property to `Directory.Build.targets` to set it after the project |
+| Multi-level import doesn't work | Missing `GetPathOfFileAbove` import in inner file | Add the `<Import>` element at the top of the inner file (see Multi-level section) |
+| Properties using SDK values are empty in `.props` | SDK properties aren't defined yet during `.props` evaluation | Move to `.targets` which is imported after the SDK |
+| `Directory.Packages.props` not found | File not at repo root or not named exactly | Must be named `Directory.Packages.props` and at or above the project directory |
+| Property condition on `$(TargetFramework)` doesn't match in `.props` | `TargetFramework` isn't set yet for single-targeting projects during `.props` evaluation | Move property to `.targets`, or use ItemGroup/Target conditions instead (which evaluate late) |
+
+**Diagnosis:** Use the preprocessed project output to see all imports and final property values:
+
+```bash
+dotnet msbuild -pp:output.xml MyProject.csproj
+```
+
+This expands all imports inline so you can see exactly where each property is set and what the final evaluated value is.