v0.1.63 to v0.1.64

1 added, 1 removed. Audit A to A.

What this update changes in the checks

No check changed: every fixed check gives the same answer before and after this update.

A tripped check is a label, not a verdict: read the matched text and the lines below. This week's updates that newly trip a check.

---
name: dotnet-repo-workflow
description: >-
Build, gate and ship a change in a .NET (C#/F#) repo: shell prerequisites, the repo's own gate
harness instead of a hand-rolled `dotnet test`, package/lock-file mechanics, Roslyn in-memory
compilation traps, and the PR merge-ready checklist. Use when a .NET build/test fails, when adding a
NuGet package, or when a .NET change is ready to commit and open as a PR. Do not use for the repo's
code style (its own AGENTS.md) or for orchestrator install maintenance.
metadata:
- version: "0.1.63"
+ version: "0.1.64"
areas: "software-development"
targets: "runtime-agnostic"
summary: "run the repo's own .NET gate harness instead of a hand-rolled `dotnet test`; lock files, Roslyn harness traps, merge-ready checklist"
summary_zh: "走仓库自带 .NET gate 而非手搓 `dotnet test`;lock 文件、Roslyn 编译陷阱、merge-ready 清单"
kind: "entry"
---
# .NET repo workflow
Building, gating and shipping changes in .NET (C#/F#) repositories: shell prerequisites, the repo's own
gate harness, package/lock mechanics, and the in-memory compilation harness trap.
## When to Use
| You hear / see | Do |
|---|---|
| "build/test this .NET repo", `dotnet test` / `dotnet build` failing | shell prerequisites → the repo's own gate harness |
| adding a NuGet package, `packages.lock.json` diff appears | packages and lock files |
| analyzer / code-fix / example-cleanliness tests fail with CS1061 | in-memory compilation harnesses |
| "commit and open a PR" for a .NET change | shipping |
**Not for**: writing style → the repo's own `AGENTS.md`; orchestrator maintenance → its operations
skill.
## Shell prerequisites
Non-login shells do not read `~/.bashrc`, so `dotnet` can be "command not found" while the SDK is
installed:
```bash
export DOTNET_ROOT="$HOME/.dotnet"; export PATH="$DOTNET_ROOT:$PATH"; dotnet --version
```
Export once per session. Read `command not found` as a PATH gap and check `~/.dotnet/dotnet` (or
`dotnet --list-sdks`) before concluding the SDK is missing.
## Gates: run the repo's own harness
- Read the repo `AGENTS.md` / `README` first. Mature .NET repos route every gate through a build
script, e.g. `dotnet fsi build.fsx -- -p test|format|verify-docs-snippets|release`; use those, not a
hand-rolled subset of `dotnet test`, and note that PR CI often runs only some of them — green CI is
not a green tree.
- Capture real exit codes: `cmd >/tmp/log 2>&1; echo rc=$?`. Piping a gate through a truncating filter
such as `| tail -5` hands back the filter's status, and a failed run can still end with a
clean-looking tail. Read the log file itself rather than re-piping it.
- Full suites take minutes: run backgrounded with completion notify, then report counts
(`2579 passed / 0 failed / 0 skipped`) plus each gate's rc, not adjectives.
- Repo invariants commonly include: every warning is a build error, zero skipped tests, committed
`packages.lock.json`, and a formatter gate over C# only.
## Repo-specific knowledge
Everything repo-specific — the gate list and how to read it, API-baseline rules, docs-snippet counts,
goal-file/archive conventions, evidence-record rules — belongs in that repo's **project profile**
(skill `gdd` ships the template). This skill supplies only the .NET mechanics.
## Packages and lock files
- With `RestorePackagesWithLockFile`, adding a `PackageReference` needs
`dotnet restore <proj> --force-evaluate` and the lock diff committed.
- A restore may also rewrite *unrelated* lock files with a trailing-newline-only change; check
`git diff --stat` afterwards and revert those (`git checkout -- <path>`) so the commit stays scoped.
## In-memory compilation harnesses
Roslyn-based tests that compile repo sources (analyzer / code-fix / example-cleanliness harnesses) use
an explicit metadata reference set. An API shipped in a NuGet package rather than the shared framework
is invisible to them even though the example project itself builds, and the harness fails with CS1061
"missing assembly reference" (e.g. `AddOpenApi`/`MapOpenApi` from `Microsoft.AspNetCore.OpenApi`).
Fix it by adding the package to the *test* project and appending its assemblies to the harness
reference set (scan `AppContext.BaseDirectory` for that assembly prefix) — not by deleting the
example's use of the API to make the test pass.
## Shipping
Commit with explicit paths (never `git add -A`), one logical change per commit, then push and open the
PR. Merging is the operator's call unless they delegated it in writing for that repo.
### Babysit the PR to merge-ready
Act only from a fresh snapshot of PR state, never from chat history. Mark a review bot's "review
running" status comment as `dispatched` instead of spending a resolver pass on it. How to drive a PR
snapshot helper directly, and what each tick checks: [`references/pr-babysit.md`](references/pr-babysit.md).
"Merge-ready" is not a judgement call — in a goal-driven repo the verdict is a script
(`gdd`, Phase 6), not a feeling.
### Pre-existing red work
When the repo's own gate is red for a reason the change did not cause (a stale harness, a broken
example project), fix it in the same branch as its own commit and disclose it as a separate section in
the PR body. Shipping a branch that leaves the full suite red, or folding the repair into the feature
commit, both make the diff lie about what the feature cost.
### Clean up after the merge
A squash merge leaves the branch tip outside `main`'s history, so `git branch -d` refuses (unmerged).
Prove equivalence first — `git diff --stat <squash-merge-commit> origin/<branch>` empty — then
`git branch -D <branch>` and `git push origin --delete <branch>`. Delete remote branches only when the
operator asks, and treat any branch with an open PR in another repo as still in use.