feat: add downstream README alignment workflow

.codex/skills/change-delivery-workflow/SKILL.md

@@ -0,0 +1,125 @@
+---
+name: change-delivery-workflow
+description: Use when asked to perform ordinary repository changes through a consistent workflow that handles sandbox escalation, non-main branches, changelog updates, release decisions, conventional commits, ready pull requests, and post-merge cleanup without inventing repo-specific process.
+---
+
+# Change Delivery Workflow
+
+## Overview
+
+Use this skill for day-to-day repository maintenance and feature work that does not already belong to a more specialized workflow such as downstream cleanup, downstream guidance sync, runtime policy updates, or template release finalization.
+
+This skill standardizes how agents should deliver ordinary changes: inspect guidance first, work from a non-main branch, capture the change in `CHANGELOG.md`, decide whether the work is release-worthy, validate with the repository's existing checks, and finish with a normal ready PR to `main`.
+
+This workflow is intentionally guidance-oriented rather than script-driven. The controls are repository guidance, Git state, repo-specific validators, diff review, and human review.
+
+## Why This Exists
+
+Routine ordinary repository work was already following a repeated pattern, but that pattern was not captured in one reusable place. The result was avoidable drift in how branches, changelog entries, release decisions, PRs, and post-merge cleanup were handled.
+
+The recurring Windows sandbox failure also needs to be treated explicitly. Errors such as `helper_sid_resolve_failed` and `LookupAccountNameW ... CodexSandboxOffline` are environment/runtime failures, not repository defects. They should trigger a scoped escalation retry for the blocked command, not a process shortcut or a speculative repository change.
+
+## Required Context
+
+Before acting, identify:
+
+- the repository guidance entrypoint, normally `AGENTS.md` and `.github/copilot-instructions.md`
+- the current branch and working tree state
+- whether the repository already has a release/version contract such as `VERSION`, a changelog version validator, release docs, or tag conventions
+- whether the requested change is ordinary maintenance, a release-worthy capability change, or post-merge cleanup
+
+If the repo does not provide a clear versioning contract, default to a `CHANGELOG.md` update under `## Unreleased` unless the user explicitly asks to introduce release metadata.
+
+## Preflight Workflow
+
+Use this sequence before editing:
+
+1. Read the repository guidance and inspect the working tree.
+2. If the current branch is `main` or `master`, create and switch to a working branch before making changes.
+3. Review the relevant implementation, tests, docs, and existing validators before choosing the smallest safe change.
+4. Decide whether the repo already defines a release workflow that should be respected for this change.
+
+If the task clearly matches a more specialized repo-local skill, use that skill instead of this one.
+
+## Sandbox Recovery
+
+When a needed command fails because of the Windows sandbox runtime, retry the blocked command with:
+
+- `sandbox_permissions: require_escalated`
+- a narrow, user-facing `justification`
+- the smallest reasonable `prefix_rule`
+
+Use this recovery path only for commands that are important to the requested work. Keep the retry scoped to the blocked command rather than broadening the task. After escalation succeeds, continue normal diff review and validation.
+
+Do not describe sandbox failures as repository bugs unless repository code or configuration is actually responsible.
+
+## Change Workflow
+
+When the user wants the repository changed, use this sequence:
+
+1. Confirm the working branch is not `main` or `master`.
+2. Make the smallest change that satisfies the request.
+3. Update `CHANGELOG.md` for every meaningful change.
+4. Run the repository's normal validation entrypoints when they exist.
+5. Inspect the diff and stage only intended files.
+6. Create a Conventional Commit message that matches the actual change.
+7. Push the branch and open a ready PR to `main` unless the user explicitly asks for a draft PR.
+
+Use `## Unreleased` for ordinary maintenance notes by default.
+
+## Release Decision
+
+Use the repository's existing release posture instead of inventing one:
+
+- if the repo already has `VERSION`, release validators, tag conventions, or release docs, follow them
+- if the change adds a meaningful new repo capability, prepare the next release entry using the repo's established SemVer policy
+- if the change is not release-worthy, keep the note under `## Unreleased`
+
+When preparing a release-worthy change:
+
+1. Move relevant `Unreleased` notes into the new version section.
+2. Update the repo's existing version metadata together.
+3. Validate the release metadata with the repo's existing checks before opening the PR.
+4. After the PR is merged, follow the repo's existing post-merge tag and release process.
+
+If the repo does not already define release metadata, stop short of inventing a new versioning system unless the user explicitly asks for that broader change.
+
+## Post-Merge Cleanup
+
+After a PR is merged:
+
+1. Switch to `main`.
+2. Fast-forward from `origin/main`.
+3. Prune deleted remote refs.
+4. Confirm the working tree is clean.
+5. Delete the merged local branch only after the remote branch deletion or merge is confirmed.
+
+If the repository has an established post-merge release step such as tag creation or GitHub Release publishing, perform it only when the repo's workflow calls for it.
+
+## Success Criteria
+
+The workflow is complete when:
+
+- repository guidance was reviewed before changes were made
+- edits were performed from a non-main branch
+- `CHANGELOG.md` was updated appropriately
+- release metadata was updated only when the repo already supported that workflow and the change justified it
+- validation was run, or a clear reason was reported when it was unavailable or intentionally skipped
+- the branch was pushed and a ready PR to `main` was opened when requested
+- post-merge cleanup or release follow-up was handled according to the repo's existing workflow
+
+## Stop Conditions
+
+Stop and report instead of improvising when:
+
+- repository guidance is missing
+- the working tree is dirty in a way that conflicts with the requested change
+- the repo's release/version contract is inconsistent across files or validators
+- validation fails and the failure is not clearly unrelated to the requested change
+- the user asks for a versioning or release process the repository does not currently define
+
+Do not bypass branch discipline, changelog updates, or diff review just because a task appears small.
+
+## Agent Role
+
+Treat repository guidance, Git state, changelog history, and repo-specific validators as the source of truth. The agent role is to coordinate a repeatable delivery workflow: inspect context, recover safely from sandbox failures when needed, keep changes off `main`, capture the work in the changelog, respect repo-specific release posture, validate, prepare commits, open ready PRs, and clean up local state after merge.

.codex/skills/change-delivery-workflow/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Change Delivery Workflow"
+  short_description: "Deliver ordinary repo changes with branch, changelog, PR, and release discipline"
+  default_prompt: "Use $change-delivery-workflow to perform routine repository changes through the standard branch, changelog, validation, commit, PR, and post-merge cleanup workflow."

.codex/skills/downstream-guidance-sync/SKILL.md

@@ -1,28 +1,31 @@
 ---
 name: downstream-guidance-sync
-description: Use when asked to sync, audit, update, or align AI guidance from powershell-dev-template into a downstream repository created from the template. Guides agents to operate scripts/Invoke-TemplateGuidanceSync.ps1 safely with audit-first behavior, non-main branches, diff review, validation, commits, and pull requests.
+description: Use when asked to sync, audit, update, or align AI guidance and downstream cleanup workflow assets from powershell-dev-template into a downstream repository created from the template. Guides agents to operate scripts/Invoke-TemplateGuidanceSync.ps1 safely with audit-first behavior, non-main branches, diff review, validation, commits, and pull requests.
 ---
 
 # Downstream Guidance Sync
 
 ## Overview
 
-Use this skill to synchronize template-owned AI guidance and ADR scaffolding from `powershell-dev-template` into a downstream repository. The deterministic tool is `scripts/Invoke-TemplateGuidanceSync.ps1`; this skill defines how an agent should operate that tool safely.
+Use this skill to synchronize template-owned downstream guidance, workflow documentation, and cleanup workflow assets from `powershell-dev-template` into an existing downstream repository. The deterministic tool is `scripts/Invoke-TemplateGuidanceSync.ps1`; this skill defines how an agent should operate that tool safely.
 
-The sync scope is intentionally narrow. Do not manually copy, edit, or invent files outside the script allowlist.
+This workflow does not perform cleanup itself. For newly created downstream repositories, cleanup still runs locally from the downstream repo through `scripts/Initialize-DownstreamRepo.ps1`.
+
+The sync scope is intentionally narrow and migration-oriented. Do not manually copy, edit, or invent files outside the script allowlist.
 
 ## Why This Exists
 
 Repositories created from this template become independent projects after creation. Their source, tests, CI, analyzer settings, runtime policy, and scaffolds are project-owned and should not be clobbered by template updates.
 
-AI guidance is the default sync target because it governs how AI-assisted work is produced, reviewed, and validated. The ADR scaffold README is also safe to sync because it provides a documentation convention without overwriting project-specific decisions. Keeping these files aligned helps downstream repositories inherit the current operating model without overwriting implementation choices.
+AI guidance is the default sync target because it governs how AI-assisted work is produced, reviewed, and validated. The ADR scaffold README is also safe to sync because it provides a documentation convention without overwriting project-specific decisions. For downstream repositories that predate the cleanup workflow, the sync process can also deliver the cleanup script, cleanup skill, shared downstream README skeleton, README alignment workflow assets, and the runtime-policy README-generation assets that keep that README workflow functional.
 
 ## Required Context
 
 Before acting, identify:
 
 - the template repo path, normally the current `powershell-dev-template` checkout
 - the downstream repo path supplied by the user
+- whether the downstream repo already contains the cleanup workflow assets
 - whether the user wants audit-only output or a branch/PR workflow
 
 If the downstream repo path is missing, ask for it. Do not guess from nearby folders.
@@ -32,17 +35,19 @@ If the downstream repo path is missing, ask for it. Do not guess from nearby fol
 Run audit mode first from the template repo:
 
 ```powershell
-powershell.exe -NoProfile -File ./scripts/Invoke-TemplateGuidanceSync.ps1 -Path ../downstream-repo
+powershell.exe -NoProfile -File .\scripts\Invoke-TemplateGuidanceSync.ps1 -Path ..\downstream-repo
 ```
 
 Use audit output to determine whether drift exists. Report `Current`, `Outdated`, `Missing`, or `Malformed` statuses in plain language. Do not apply changes during audit mode.
 
 For automation-friendly inspection, use:
 
 ```powershell
-powershell.exe -NoProfile -File ./scripts/Invoke-TemplateGuidanceSync.ps1 -Path ../downstream-repo -OutputFormat Json
+powershell.exe -NoProfile -File .\scripts\Invoke-TemplateGuidanceSync.ps1 -Path ..\downstream-repo -OutputFormat Json
 ```
 
+If the downstream repo is missing `scripts/Initialize-DownstreamRepo.ps1` or `.codex/skills/downstream-repo-cleanup/`, treat that as a signal that the repo predates the cleanup workflow and should receive those assets through sync before cleanup is run locally.
+
 ## Apply Workflow
 
 When the user requests sync changes, use this sequence:
@@ -51,24 +56,25 @@ When the user requests sync changes, use this sequence:
 2. Create or switch to a non-main branch in the downstream repo, for example:
 
    ```powershell
-   git -C ../downstream-repo switch -c chore/sync-template-guidance-0.7.0
+   git -C ../downstream-repo switch -c chore/sync-template-guidance
    ```
 
 3. Run the sync script from the template repo:
 
    ```powershell
-   powershell.exe -NoProfile -File ./scripts/Invoke-TemplateGuidanceSync.ps1 -Path ../downstream-repo -Apply
+   powershell.exe -NoProfile -File .\scripts\Invoke-TemplateGuidanceSync.ps1 -Path ..\downstream-repo -Apply
    ```
 
-4. Inspect the downstream diff and verify changes are limited to AI guidance files, `docs/decisions/README.md`, and the README template badge.
-5. Run downstream validation if the repo provides a clear validation entrypoint, such as `scripts/Invoke-RepoChecks.ps1`.
-6. Commit with a conventional docs message, for example:
+4. Inspect the downstream diff and verify changes are limited to synced guidance files, the ADR scaffold README, the README template badge, and the cleanup or README workflow assets shipped from the template.
+5. If the sync delivered `scripts/Initialize-DownstreamRepo.ps1`, the cleanup skill, or the shared README workflow assets into an older downstream repo, switch into the downstream repo and run cleanup or README alignment there before adding more project-specific changes.
+6. Run downstream validation if the repo provides a clear validation entrypoint, such as `scripts/Invoke-RepoChecks.ps1`.
+7. Commit with a conventional docs or chore message that reflects the actual change, for example:
 
    ```text
-   docs(ai): sync template guidance to 0.7.0
+   chore(repo): sync template guidance and cleanup assets
    ```
 
-7. Open or draft a PR when requested, summarizing changed guidance and validation results.
+8. Open or draft a PR when requested, summarizing changed guidance, delivered cleanup assets, and validation results.
 
 ## Success Criteria
 
@@ -78,7 +84,7 @@ The workflow is complete when:
 - apply mode, when used, ran only from a non-main downstream branch
 - the downstream diff is limited to the sync allowlist, including only the ADR scaffold README under `docs/decisions/`
 - downstream validation was run, or a clear reason was reported when validation was unavailable or skipped
-- the commit or PR summary states the synced template guidance version and validation result
+- the commit or PR summary states whether the change was a guidance refresh, a cleanup-asset delivery, a README-workflow delivery, or a combination of those, along with the validation result
 
 ## Stop Conditions
 
@@ -99,12 +105,20 @@ The script may update only:
 
 - `AGENTS.md`
 - `.github/copilot-instructions.md`
+- `.codex/skills/downstream-repo-cleanup/`
+- `.codex/skills/readme-alignment/`
 - selected AI governance and operating-model docs under `docs`
+- `docs/agent-workflows.md`
 - `docs/decisions/README.md`
+- `scripts/Initialize-DownstreamRepo.ps1`
+- `scripts/Invoke-ReadmeAlignment.ps1`
+- `scripts/Update-GeneratedMarkdown.ps1`
+- `eng/runtime-policy.json`
+- `templates/downstream/README.md`
 - the README template-version badge
 
-It must not update downstream source, tests, Pester configuration, PSScriptAnalyzer settings, CI workflows, development-environment configuration, runtime policy, module manifests, scaffolds, or numbered project-specific ADRs.
+It must not update downstream source, tests, Pester configuration, PSScriptAnalyzer settings, CI workflows, development-environment configuration, module manifests, scaffolds other than the cleanup and README workflow assets, or numbered project-specific ADRs. The one runtime-policy exception is the narrow set of README-generation assets required by the shared downstream README workflow. It also does not perform cleanup or README alignment itself; it only delivers the assets needed for those workflows to run locally in downstream repositories.
 
 ## Agent Role
 
-Treat the script as the source of truth for deterministic behavior. The agent role is to orchestrate: run the script, interpret output, inspect diffs, run validation, prepare commits, and draft PR text.
+Treat the script as the source of truth for deterministic behavior. The agent role is to orchestrate: run the script, interpret output, inspect diffs, identify whether cleanup assets were delivered, run validation, prepare commits, and draft PR text.

.codex/skills/downstream-guidance-sync/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "Downstream Guidance Sync"
-  short_description: "Sync template AI guidance into downstream repos"
-  default_prompt: "Use $downstream-guidance-sync to sync a downstream repository with the current powershell-dev-template AI guidance."
+  short_description: "Sync template guidance and cleanup assets into downstream repos"
+  default_prompt: "Use $downstream-guidance-sync to sync a downstream repository with the current powershell-dev-template guidance and cleanup workflow assets."