[Tracking] PowerShellBuild v1.0.0 roadmap

[tablackburn]

[Tracking] PowerShellBuild v1.0.0 roadmap

Goal: ship PowerShellBuild 1.0.0 — the first version with a stable public-API contract per SemVer. Treats the 0.x line as initial development per SemVer §4; 1.0.0 defines the public API per SemVer §5.

Status: planning → execution
Current version: 0.8.2
Target version: 1.0.0
Prerelease cadence: 1.0.0-previewN to PSGallery once there is meaningful breaking/behavioral change to soak. Preview numbers increment from the first preview cut — they are not tied to phase numbers (Phase 1 was conventions/guardrails and shipped almost nothing consumer-facing, so the first preview is cut after Phase 2).
Branching: PRs land directly on main (allowed under 0.x); 1.0.0 cuts when scope is complete

Why 1.0.0 and not 2.0.0: there has never been a stable 1.x. Jumping to 2.0.0 would imply a prior stable 1.x existed. SemVer says go to 1.0.0.

Destination

PowerShellBuild 1.0.0 published to PSGallery. This issue is the wayfinder map for
that route: it indexes every decision already made and points at the tickets holding the
detail. The map is complete when 1.0.0 ships — not when planning ends.

Working this map

Route steps are sub-issues of this issue (and of #105 for the PlatyPS chain), wired
with GitHub's native dependency edges, so the tracker itself shows what is takeable.

• Frontier — open route tickets with zero open blockers and no assignee. These are
  takeable right now, in any order, by anyone.
• Claim before working — assign the ticket to yourself first, so parallel sessions
  skip it. An open, unassigned route ticket is unclaimed.
• Resolve — post the answer or outcome as a comment, close the issue, and add a line
  to this map's decision index if it settled something.
• Umbrellas are not takeable. Update PlatyPS dependency from platyPS v0.14.x to Microsoft.PowerShell.PlatyPS v1.x #105 is a container for the PlatyPS chain. Neither are
  folded issues — Tests: Build-PSBuildMarkdown #99, Tests: Build-PSBuildMAMLHelp #100, Tests: Build-PSBuildUpdatableHelp #101 close as part of their parent PR, and Test-PSBuildScriptAnalysis does not fail on the PSScriptAnalyzer rule crash from #136 #147 rides along
  with Settle the FailBuildOnSeverityLevel contract: 'Any' is documented but rejected, and ParseError escapes every threshold #144. Only children of this issue and of Update PlatyPS dependency from platyPS v0.14.x to Microsoft.PowerShell.PlatyPS v1.x #105 are route tickets.

Read the frontier without a script by opening this issue: blocked children render with a
blocked marker, and the rest are the frontier.

---

Locked-in decisions

Decision	Choice
Version	1.0.0 (not 2.0.0)
Tracking	This issue + v1.0.0 milestone + GitHub Project board
AIM deployment	Phase 0 (first PR)
Branching	PRs to main + 1.0.0-previewN prereleases
Breaking changes	Hard cut + migration guide
Migration guide	docs/migration-v0.8-to-v1.0.md; per-PR entries; AI-assisted prompt at top
Auto-migration tool	None
Deprecation cycle	None (skip 0.9.0)
psake 5.x	In scope for 1.0.0
Minimum PS version	Windows PowerShell 5.1; PowerShell 7.4+ for PS 7 (decided 2026-07-21; PlatyPS 1.x validated on 5.1, Pester 6 floor drives the 7.4+)
Consumer Pester minimum	Keep ≥ 5.x (decided 2026-07-22; RequiredModules stays at 5.6.1 — Test-PSBuildPester supports Pester 5 and 6, verified by the #137 integration matrix)
Preview numbering	Decoupled from phase numbers (decided 2026-07-22). No preview is cut after Phase 1 — it shipped only two small changes (Test-PSBuildPester fixes #102 + the manifest floor #141), nothing risky to soak. The first preview is preview1, cut after Phase 2, and it carries the Phase 1 shipped changes along with it.
Migration guide scope	Breaking changes plus behavioral changes that can require action on upgrade (decided 2026-07-25). The guide previously said "breaking changes only", which excluded fixes like #143 that can turn a passing consumer build red. Preamble widened to match.
Destination	1.0.0 published to PSGallery (decided 2026-08-19). The route is done when the release ships, not when the planning does.
Route tracking	This issue is the map (decided 2026-08-19). Route steps are sub-issues wired with native dependency edges rather than checkboxes, so the frontier is visible in the tracker and claimable by parallel sessions.
psake 5.x	In scope, clean re-spike (decided 2026-08-19) — #155. The extras that sank #117 (task caching, LLM Pester output, external PesterConfiguration file, Format-PSBuildResult) are 1.1.0 features, not part of a dependency bump.
psake 5.x outcome	MIGRATE (#155, resolved 2026-08-19). Consumer-facing psakeFile.ps1 needs zero changes under 5.0.4 — no task renames, no $PSBPreference change — so the abort criterion did not fire. All four breaking changes in psake's own v4→v5 guide were checked and none apply. Full suite 428/0 under 5.0.4, matching the 4.9.1 baseline. psake 5.x does differ behaviorally — Invoke-psake returns a PsakeBuildResult where v4 returned nothing, and Set-BuildEnvironment in a Pester BeforeAll fails the container — but neither is triggered by upgrading PowerShellBuild, so neither is documented here. Migration filed as #161.
BuildHelpers break escape	Found by the #155 spike, undocumented upstream (2026-08-19). Set-BuildEnvironment in a Pester BeforeAll leaks an escaping break from Get-BuildVariable's switch blocks; psake 4.9.x absorbs it, psake 5.x does not, and Pester fails the whole container. Guarding the call on $env:BHProjectName fixes it. Affects any consumer whose Pester tests call Set-BuildEnvironment.
psake abort criterion	Fixed in advance, before the spike runs (decided 2026-08-19). Migrate if the consumer-facing PowerShellBuild/psakeFile.ps1 needs only mechanical changes; cut psake 5.x to 1.1.0 and ship 1.0.0 on 4.9.0 if task names or the $PSBPreference contract must change. Set ahead of the findings so the call is made on evidence rather than sunk cost.
Phase 2 ordering	PlatyPS and psake chains run in parallel (decided 2026-08-19), gated by a single preview1 cut. They touch disjoint files, so serializing them buys nothing and halves the frontier.
FailBuildOnSeverityLevel	#144 option 3, extended to cover #147 (decided 2026-08-19): fold ParseError into the Error threshold and add 'Any' wired to the catch-all branch. The ParseError half is a behavior change and needs a migration-guide entry. Corrected 2026-08-20: this row originally also said the gate should fail on analyzer-level errors "so a crashed rule no longer reads as 'no findings'". That premise was wrong — #147 measured that a crashed rule does not cost findings (100 cold runs, never fewer than the known-good count). #163 therefore implements #147's preferred fix, a retry on RULE_ERROR that leaves failure semantics untouched, rather than a hard failure that would have cost some consumers a red build to help others. Implemented in #163.
#83 design	Grilling ticket first (#156, decided 2026-08-19). Precedence between a supplied PesterConfiguration and $PSBPreference.Test.* is public API and must settle before implementation. The former pointer to "joshooaj's design in #80" was stale — #80 is a different, closed request.
Phase 4 milestone discrepancy	Resolved 2026-08-19 — milestone stripped. #94, #95, #98, and #103 no longer carry v1.0.0, matching this issue's prose and the 2026-05-19 comment. The milestone now shows only genuinely blocking work.
Changelog and guide scope	Internal changes get neither (decided 2026-08-20, applied to #162). CHANGELOG.md records user-facing changes only, and the migration guide covers changes triggered by upgrading PowerShellBuild. A build-toolchain pin in requirements.psd1 is neither, even when the upgraded dependency behaves differently — that belongs in the dependency's own migration guide. Sharpens the existing "Migration guide scope" row: the test is who is affected by this upgrade, not how interesting the change is.
Scope additions	#124 and #138 pulled in (decided 2026-08-19). Both touch the public surface freezing at 1.0.0: #124 adds a PlatyPS setting to functions Phase 2 already rewrites, #138 is a correctness bug in a public function's output.

---

Migration guide

Lives at docs/migration-v0.8-to-v1.0.md. Every breaking-change PR must add an entry
using the standard structure (What changed / Why / Detection / Migration / Notes). Enforced
through instructions/git-workflow.instructions.md (AIM) plus reviewer catch — not a PR
template checkbox, which Phase 1 explicitly skipped. The top-of-file section includes a
canonical AI prompt users can paste into their agent to migrate their build.ps1
automatically; #159 tests that prompt before release.

---

Phase 0 — Foundation

• Deploy AIM to the repo (feat: deploy AIM (AI Agent Instruction Modules) #122, merged 2026-05-18)
  • Add AGENTS.md, aim.config.json, instructions/
  • Migrate CLAUDE.md content → instructions/repository-specific.instructions.md
  • Modules to include: agent-workflow, shorthand, git-workflow, testing, powershell, markdown, releases, github-cli, readme, contributing, update, repository-specific
  • Fix stale version reference (CLAUDE.md says 0.7.3; actual is 0.8.0)

Phase 1 — Conventions & guardrails ✅ complete (2026-07-22)

• Add PR template — skipped: PowerShellBuild inherits a PR template from the org-level psake/.github repo, which is sufficient for general PR structure. The migration-guide entry rule for breaking-change PRs is enforced through instructions/git-workflow.instructions.md (AIM) + reviewer catch, not a checkbox. Repo-level override would only add value if drive-by external contributors became likely during the cycle.
• Initialize docs/migration-v0.8-to-v1.0.md skeleton (docs: initialize v0.8 to v1.0 migration guide skeleton #123, merged 2026-07-03)
• Create v1.0.0 milestone, link this issue
• Create GitHub Project board (Status: Todo / In Progress / Done — kept GitHub defaults; tests don't trigger version bumps so milestone state is the only prioritization axis needed)
• Investigate minimum PowerShell version for v1.0.0 — decided 2026-07-21: Windows PowerShell 5.1, or PowerShell 7.4+. Microsoft.PowerShell.PlatyPS 1.x validated end-to-end on Windows PowerShell 5.1 (net472 assembly, no manifest floor, functional test of the markdown→MAML pipeline); Pester 6 supports 5.1 and 7.4+ only, which sets the pwsh floor. Details: [Tracking] PowerShellBuild v1.0.0 roadmap #120 (comment)
• Audit PowerShellVersion in PowerShellBuild.psd1 and CI matrix — done via chore: Raise minimum PowerShell version to 5.1 in module manifest #141 (merged 2026-07-22): PowerShellVersion = '5.1' (was '3.0'); no CI change needed — the org ModuleCI.yml already runs Windows PowerShell 5.1 plus current pwsh on Linux/Windows/macOS. Migration-guide entry and changelog entry included in chore: Raise minimum PowerShell version to 5.1 in module manifest #141.
• Refresh non-breaking dependency versions (psake and platyPS deferred to Phase 2, breaking):
  • PSScriptAnalyzer 1.24.0 → 1.25.0 in requirements.psd1 (chore: Pin Pester 5.8.0 and update PSScriptAnalyzer to 1.25.0 #129, merged 2026-07-03)
  • Pin Pester build dependency to 5.8.0 in requirements.psd1 — was floating via MinimumVersion = '5.6.1', so CI installed whatever was newest at bootstrap (chore: Pin Pester 5.8.0 and update PSScriptAnalyzer to 1.25.0 #129) — superseded: repo suite now pins Pester 6.0.0 (chore: Pin Pester 6.0.0 for the repository test suite #132), with 5.9.0 installed side-by-side via requirements.pester-matrix.psd1 for the Test-PSBuildPester compatibility matrix (test: Add Test-PSBuildPester integration tests and fix latent bugs #137)
  • Pester consumer-facing minimum in PowerShellBuild.psd1 RequiredModules — decided 2026-07-22: keep ≥ 5.x; stays at 5.6.1, no manifest change. Test-PSBuildPester supports Pester 5 and 6, and the test: Add Test-PSBuildPester integration tests and fix latent bugs #137 integration matrix verifies both majors; requiring 6.0 would force an upgrade on consumers for no functional gain.
  • InvokeBuild 5.8.1 → 5.14.23 (chore: Update InvokeBuild to 5.14.23 and actions/checkout to v4 #142, merged 2026-07-22)
  • actions/checkout in publish.yaml v2 → v4 (chore: Update InvokeBuild to 5.14.23 and actions/checkout to v4 #142, merged 2026-07-22)
  • Add CompatiblePSEditions = @('Desktop','Core') to PowerShellBuild.psd1 (chore: Raise minimum PowerShell version to 5.1 in module manifest #141, merged 2026-07-22)
• Confirm branch protection on main — done 2026-07-22 via the repo-level "Default" ruleset: require a pull request before merging (1 approval; merge/squash/rebase allowed); require status checks — CI / Run Pwsh Tests (ubuntu-latest / windows-latest / macOS-latest), CI / Run Tests (Windows PowerShell 5.1), CI / Run Linters — with branches up to date before merging; require linear history; require signed commits; restrict deletions; block force pushes. Bypass: Organization admin = always allow; Repository admin = pull requests only (admins cannot push directly to main; they may merge a PR without waiting for an approval — maintainers and outside contributors need 1 approval + green CI).

No preview cut after Phase 1. Phase 1 was conventions/guardrails: the only consumer-facing changes since v0.8.2 are the Test-PSBuildPester bug fixes (#102) and the manifest version floor (#141) — nothing risky enough to warrant a prerelease soak. These ride along in preview1 (cut after Phase 2). See the Preview numbering decision above.

Phase 2 — Breaking dependency upgrades

Both chains below are open in parallel — they touch disjoint files — and both gate the
same preview cut.

PlatyPS migration (#105)

One reviewable PR per link. Each link is blocked by the one before it, except the docs
conversion, which only needs the module installed and runs alongside the function work.

1. PlatyPS 2a: add Microsoft.PowerShell.PlatyPS 1.x alongside platyPS #149 — 2a add Microsoft.PowerShell.PlatyPS 1.x alongside platyPS, update CI
2. PlatyPS 2b: migrate Build-PSBuildMarkdown to New-MarkdownCommandHelp #150 — 2b migrate Build-PSBuildMarkdown (closes Tests: Build-PSBuildMarkdown #99)
3. PlatyPS 2c: migrate Build-PSBuildMAMLHelp to Export-MamlCommandHelp #151 — 2c migrate Build-PSBuildMAMLHelp (closes Tests: Build-PSBuildMAMLHelp #100)
4. PlatyPS 2d: migrate Build-PSBuildUpdatableHelp to the 1.x cab pipeline #152 — 2d migrate Build-PSBuildUpdatableHelp (closes Tests: Build-PSBuildUpdatableHelp #101) — highest risk in the
   chain: Windows-only, makecab.exe-dependent, and untested today
5. PlatyPS 2e: convert committed docs/ markdown to the 1.x schema #154 — 2e convert committed docs/ markdown to the 1.x schema (needs only 2a)
6. PlatyPS 2f: remove the old platyPS 0.14.2 dependency #153 — 2f remove the old platyPS 0.14.2 dependency (needs every link above)

psake 5.x bump

• psake 5.x spike: assess breakage under psake 5.0.4 (clean bump, no extras) #155 — spike: assess breakage under psake 5.0.4. Resolved 2026-08-19: MIGRATE.
  The consumer-facing PowerShellBuild/psakeFile.ps1 needs zero changes, so the abort
  criterion did not fire.
• psake 5.x migration: bump the pin to 5.0.4 and record the behavior change #161 — migration: bump the pin to 5.0.4 and carry the Set-BuildEnvironment test
  guard. A single small PR, not a chain — and an internal one: no changelog or migration-guide
  entry, since the manifest floor stays at psake 4.9.0. Open as chore: Move the build toolchain to psake 5.0.4 #162, all CI legs green —
  including Windows PowerShell 5.1, which settles the last open question about psake 5.x on
  the v1.0.0 support floor. Awaiting review.

Gate

• Release gate: cut 1.0.0-preview1 after Phase 2 #157 — cut 1.0.0-preview1, the first prerelease. Blocked on both chains so the soak
  covers the whole Phase 2 break surface at once. Carries the Phase 1 changes (Tests: Test-PSBuildPester #102, chore: Raise minimum PowerShell version to 5.1 in module manifest #141)
  along with it.

Phase 3 — API improvements

• Design: precedence contract for a consumer-supplied PesterConfiguration (#83) #156 — design: precedence contract for a consumer-supplied PesterConfiguration
  (blocks Add support for passing a PesterConfiguration object to PowerShellBuild #83)
• Add support for passing a PesterConfiguration object to PowerShellBuild #83 — PesterConfiguration object support, built to that contract
• Settle the FailBuildOnSeverityLevel contract: 'Any' is documented but rejected, and ParseError escapes every threshold #144 — settle the FailBuildOnSeverityLevel contract, with Test-PSBuildScriptAnalysis does not fail on the PSScriptAnalyzer rule crash from #136 #147 (analyzer rule crashes
  escaping the gate) folded in
• Scope PlatyPS to Specific Paths #124 — scope PlatyPS to specific paths; waits on the function migrations so it is written
  against the 1.x API
• Test-PSBuildPester coverage threshold math truncates every percentage to zero #138 — fix the coverage-percentage truncation in Test-PSBuildPester
• Close Add support for configuring Pester's SkipRemainingOnFailure and Verbosity options #80 as superseded by Add support for passing a PesterConfiguration object to PowerShellBuild #83 — already closed
• Release gate: cut 1.0.0-preview2 after Phase 3 #158 — cut 1.0.0-preview2 after the above land

Phase 4 — Test infrastructure

In v1.0.0:

• Tests: Create shared fixture module #97 — shared fixture module at tests/fixtures/PSBuildTestFixture/ (closed via test: Add PSBuildTestFixture shared fixture module #135, 2026-07-09)
• Tests: Test-PSBuildPester #102 — Test-PSBuildPester integration tests (closed via test: Add Test-PSBuildPester integration tests and fix latent bugs #137, 2026-07-09)
• Tests: Build-PSBuildMarkdown #99, Tests: Build-PSBuildMAMLHelp #100, Tests: Build-PSBuildUpdatableHelp #101 — folded into PR 2b, 2c, and 2d respectively, and reparented
  under them. They are written against the new PlatyPS API so the tests are not written
  twice, and they close with their parent PR rather than independently.

Related test-infra work that landed during the cycle: #128/#133 (fail the build on Pester
block/container failures, not just failed tests), #140 (code-coverage tracking in the
Pester task), #143 (severity gate actually fails the build; also closed #125).

Tracked but not blocking 1.0.0 — see "Out of scope" below.

Phase 5 — Release

• Release: finalize the migration guide, test the AI prompt, write the 1.0.0 changelog #159 — finalize docs/migration-v0.8-to-v1.0.md, test the AI migration prompt against a
  real sample consumer build.ps1 (it has never been exercised), write the CHANGELOG.md
  1.0.0 entry
• Release: bump to 1.0.0, cut rc1, soak, and publish 1.0.0 #160 — bump ModuleVersion to 1.0.0, cut 1.0.0-rc1, soak ≥ 7 days, publish 1.0.0

---

Not yet specified

In scope, but not yet sharp enough to ticket. Graduates as the frontier advances.

• Whether updatable help survives PlatyPS 1.x. If the 1.x cab story is materially
  different from 0.14.x, or absent, PlatyPS 2d: migrate Build-PSBuildUpdatableHelp to the 1.x cab pipeline #152 surfaces a scope decision about Build-PSBuildUpdatableHelp
  that belongs on this map rather than inside that PR.
• The shape of Scope PlatyPS to Specific Paths #124's path scoping — whether it needs a new $PSBPreference.Docs.*
  setting or the 1.x API makes it inferable is unknown until 2b–2d reveal the new surface.
• Consumer guidance for the docs/ schema conversion. 2e converts this repo's docs;
  what consumers with committed docs/ must do is learned by doing it.
• Whether psake 4.x compatibility stays continuously tested. chore: Move the build toolchain to psake 5.0.4 #162 bumps the toolchain to
  psake 5.0.4 while the manifest still claims psake >= 4.9.0. Both majors were verified
  locally (428/0 each), but CI now exercises only 5.0.4, so the claim is asserted rather than
  tested. Options are a side-by-side matrix like requirements.pester-matrix.psd1, raising the
  manifest floor to 5.x, or accepting the gap. Not sharp enough to ticket until chore: Move the build toolchain to psake 5.0.4 #162 lands.
• rc1 blocker triage. If the soak surfaces blockers, the response is a route decision.

Out of scope

Ruled beyond this destination. These do not graduate; they return only if the destination
is redrawn.

• CI: Intermittent PSScriptAnalyzer crash in the Analyze task #136 — intermittent PSScriptAnalyzer crash in CI's Analyze task. Upstream defect
  (PSScriptAnalyzer#1538/#1351, both deferred to 2.0), transient, and re-running succeeds.
  CI hygiene, not consumer-facing.
• CI: Publish the repository's code coverage results #139 — publish the repository's coverage results. CI reporting; needs a change to the
  psake org's shared workflow. No SemVer impact.
• Consider pinning GitHub Actions to commit SHAs instead of moving tags #145 — pin GitHub Actions to commit SHAs. Supply-chain hardening, orthogonal to the
  release.
• Additional Pester tests needed #17 — "additional Pester tests needed" umbrella. Open-ended; would never close.
• Tests: Clear-PSBuildOutputFolder #94, Tests: Initialize-PSBuild #95, Tests: Build-PSBuildModule #98, Tests: Publish-PSBuildModule #103 — test backfill for Clear-PSBuildOutputFolder,
  Initialize-PSBuild, Build-PSBuildModule, Publish-PSBuildModule. Unmilestoned
  2026-08-19. Tests are not user-facing and do not influence SemVer, so they ride with
  whichever release is next cut for API reasons. Contributions welcome during the cycle.
• The [1.0.0-alpha1] Upgrade to psake 5.0.0 with task caching and LLM output #117 extras — task caching via Inputs/Outputs, LLM-mode Pester output,
  external PesterConfiguration file support, and a public Format-PSBuildResult. These
  are 1.1.0 features that were bundled into a dependency bump; keeping them out is why the
  psake spike is being re-run clean.

---

Definition of done

• Every route ticket under this map is closed, or explicitly ruled out of scope above
• The Phase 4 milestone discrepancy is resolved — done 2026-08-19, milestone
  stripped from Tests: Clear-PSBuildOutputFolder #94/Tests: Initialize-PSBuild #95/Tests: Build-PSBuildModule #98/Tests: Publish-PSBuildModule #103
• The migration guide is complete and its AI prompt has been tested against a sample
  consumer build.ps1
• 1.0.0-rc1 has soaked ≥ 7 days with no blocker reports
• 1.0.0 is published to PSGallery

---

AI-assisted-development notes

• Keep PRs small (≤ ~400 lines diff where feasible) so they fit in agent context
• Each PR description should reference this tracking issue and the relevant phase
• The AIM instructions/ files are the canonical guide for any agent working in this repo — agents must read agent-workflow.instructions.md first
• Conventional commit prefixes (feat:, fix:, docs:, chore:, BREAKING CHANGE:) to keep history machine-parseable

[tablackburn]

Phase 0 PR opened (draft): #122

Status of Phase 0 checklist (boxes to tick in the issue body once #122 merges):

• Add AGENTS.md, aim.config.json, instructions/
• Migrate CLAUDE.md content → instructions/repository-specific.instructions.md
• Modules included: agent-workflow, shorthand, git-workflow, testing, powershell, markdown, releases, github-cli (plus readme, contributing, update, repository-specific — flagged in the PR description; happy to drop any if the 8-module list here was intentional)
• Fix stale version reference (CLAUDE.md said 0.7.3; actual is 0.8.0; public function count corrected 9 → 12)

After this lands, Phase 1 (Conventions & guardrails) begins.

[tablackburn]

Phase 0 — complete ✅

#122 merged 2026-05-18 (squash commit 08b191a). All Phase 0 checkboxes above ticked.

What shipped:

• AGENTS.md, aim.config.json, and 12 instruction modules under instructions/ (per the original Phase 0 list, plus readme, contributing, update, and repository-specific)
• CLAUDE.md migration → instructions/repository-specific.instructions.md (repo-specific content only; generic content dropped to avoid duplication with standard AIM modules)
• CLAUDE.md retained as a one-line @AGENTS.md import so Claude Code auto-loads AIM context on every session
• AIM template synced to 0.8.14 (the deployment caught two bugs in the upstream templates which were fixed upstream as tablackburn/ai-agent-instruction-modules#24 and re-synced into feat: deploy AIM (AI Agent Instruction Modules) #122 before merge)
• Stale references in the migrated content corrected (version 0.7.3 → 0.8.0; public function count 9 → 12 after the signing functions)

No module code, dependency, or CI workflow changes — docs/config only.

---

Phase 1 — kickoff plan

Working order I'm proposing:

GitHub admin (UI-only, needs maintainer):

• Create v1.0.0 milestone; link this issue
• Create the GitHub Project board (Now / Next / Later / Done)
• Confirm branch protection on main (PR + 1 review + CI green) before cutting 1.0.0-preview.1

PRs, smallest first:

1. .github/PULL_REQUEST_TEMPLATE.md with a "breaking change → migration-guide entry" checkbox (unblocks every future PR carrying that contract)
2. docs/migration/v0.8-to-v1.0.md skeleton (header, AI-prompt placeholder, per-PR entries section, format guide) — needs to exist before any Phase 2 breaking-change PR
3. Minimum-PowerShell-version investigation — outputs both a written decision recorded in the Locked-in decisions table above and a follow-up PR fixing PowerShellVersion = '3.0' in PowerShellBuild.psd1 and aligning the CI matrix. Gated by Microsoft.PowerShell.PlatyPS 1.x and psake 5.x requirements, so timing it ahead of Phase 2 is deliberate

1.0.0-preview.1 to PSGallery after all Phase 1 items are done.

[tablackburn]

Project board + v1.1.0 milestone changes

Project board created: https://github.com/orgs/psake/projects/2 ("PowerShellBuild v1.0.0"). Status: Todo / In Progress / Done (GitHub defaults — no custom fields). Seeded with the 7 v1.0.0 milestone issues plus #122 (set to Done).

⚠️ Visibility note: the project was created private (default for org projects via API). Making it public requires org admin and has to be flipped in the UI: https://github.com/orgs/psake/projects/2/settings.

v1.1.0 milestone dissolved. Its 4 issues (#17 / #98 / #102 / #103) moved to no-milestone and joined the existing "not blocking 1.0.0" pile alongside #94/#95/#96.

Reasoning (per discussion above): tests aren't user-facing and don't influence SemVer. Milestoning test backfill under v1.1.0 implied "v1.1.0 ships when these are done," which is misleading — none of these would trigger a release on their own. They'll ship with whichever release is next cut for API reasons. The v1.1.0 milestone will be re-created when an actual feature motivates that release; any tests merged in the meantime will ride along automatically.

Phase 1 status:

• Create v1.0.0 milestone, link this issue
• Create GitHub Project board
• Add PR template
• Initialize docs/migration/v0.8-to-v1.0.md skeleton
• Investigate minimum PowerShell version
• Audit PowerShellVersion in PowerShellBuild.psd1
• Confirm branch protection on main (admin-only — UI work)
• Cut 1.0.0-preview.1