powerforge-library-builder

name	powerforge-library-builder
description	Build, version, pack, sign, and publish multi-project .NET libraries using Invoke-ProjectBuild and project.build.json. Use for ExpectedVersionMap/X-pattern resolution, NuGet publishing, GitHub release mode/tag strategy, and release troubleshooting.

PowerForge Library Builder

Use this skill for repository/package pipelines (Invoke-ProjectBuild), including NuGet + GitHub release workflows. Prefer one entrypoint script: Build/Build-Project.ps1.

Golden Path (Do This In Order)

1. Confirm repository scope and branch hygiene.
   • Prefer feature branch/worktree.
2. Validate project.build.json.
   • Discovery filters (IncludeProjects, ExcludeProjects, expected map include mode).
   • Version expectations and version sources.
3. Generate plan before publishing.
   • Use PlanOnly or cmdlet -Plan first.
4. Execute build/pack/sign path.
   • Ensure staging/output paths are deterministic.
   • Treat CleanStaging as artifact cleanup only; release compilation freshness is enforced by PowerForge.
   • Require primary managed package assemblies to match the fresh release build before signing or publishing; do not treat native runtime assets or metadata-only packages as managed assembly payloads.
   • Keep Build-Project.ps1 minimal (param pass-through + Invoke-ProjectBuild call).
   • Do not keep legacy wrapper scripts (Build-AllPackages.ps1, Publish-*.ps1, Update-Version.ps1) unless explicitly required.
5. Publish NuGet with explicit fail-fast and duplicate policy.
6. Publish GitHub release with explicit tag policy.
   • Choose Single or PerProject intentionally.
   • Set GitHubPrimaryProject for single-mode version source.
7. Handle tag conflicts intentionally.
   • Prefer configurable conflict policy instead of ad-hoc retries.
8. Verify final release state.
   • Confirm release/tag and attached asset set match plan.
   • Inspect the published package content when the release adds or changes public APIs; version visibility and a valid signature alone do not prove the payload is current.
   • If an immutable feed already contains a stale package, publish a corrected higher version and keep consumers off the bad version.
9. Update docs/schema/help for any new config fields.
10. Keep engine boundaries explicit.

• Use Invoke-ProjectBuild for package/release pipelines.
• Use DotNet publish engine (Invoke-DotNetPublish, New-ConfigurationDotNet*) for service/app publish packaging.

High-Value Commands

# Plan-only
Invoke-ProjectBuild -ConfigFilePath .\Build\project.build.json -Plan

# Full run
Invoke-ProjectBuild -ConfigFilePath .\Build\project.build.json

# Validate core tests after engine changes
dotnet test .\PowerForge.Tests\PowerForge.Tests.csproj -c Release

Decision Rules

• Standard script surface for repos:

  • Keep Build/Build-Project.ps1 and Build/project.build.json.
  • Remove obsolete wrapper scripts once migration is complete.

• Keep Build-Project.ps1 simple:

  • avoid custom coercion/helper blocks when normal nullable bool parameters and splatting are enough.

• If projects have mixed versions in Single release mode:

  • set GitHubPrimaryProject or use date/timestamp tags by template.

• Prefer template-based tags over hardcoded tags:

  • tokens include {Project}, {Version}, {PrimaryProject}, {PrimaryVersion}, {Repo}, {Date}, {UtcDate}, {DateTime}, {UtcDateTime}, {Timestamp}, {UtcTimestamp}.

• Use explicit conflict policy for existing tags:

  • Reuse, Fail, or AppendUtcTimestamp.

• In plan/what-if mode, avoid hard failures that require produced artefacts on disk.

• Never use CleanStaging as evidence that project bin/obj outputs were rebuilt.

• Do not publish when PowerForge reports a package payload provenance mismatch.

Reference Files (Read As Needed)

• references/checklist.md for quick release-mode and tag-policy decisions.
• Docs/PSPublishModule.ProjectBuild.md for JSON behavior.
• Docs/PSPublishModule.DotNetPublish.Quickstart.md when release work also needs app/service publish flows.
• schemas/project.build.schema.json for allowed fields and enums.
• Module/Docs/Invoke-ProjectBuild.md for cmdlet behavior.