…ants (psake#91)

Documents the module structure, $PSBPreference config system, public
API,
build workflows, task dependency system, CI/CD setup, code conventions,
and guidance specific to AI-assisted development in this repository.

https://claude.ai/code/session_018vQunv4wiTuk8WCkXCPfHn

Co-authored-by: Claude <noreply@anthropic.com>

## Summary
This PR adds comprehensive Authenticode code-signing capabilities to
PowerShellBuild, enabling modules to be signed with digital certificates
from multiple sources. It includes three new public functions and
corresponding build tasks for signing module files and creating/signing
Windows catalog files.

## Key Changes

- **New Function: `Get-PSBuildCertificate`** - Resolves code-signing
X509Certificate2 objects from five different sources:
  - Auto (environment variable or certificate store, configurable)
  - Windows certificate store (with optional thumbprint filtering)
  - Base64-encoded PFX from environment variables (CI/CD pipelines)
  - PFX files on disk with optional password protection
- Pre-resolved certificate objects (for custom providers like Azure Key
Vault)

- **New Function: `Invoke-PSBuildModuleSigning`** - Signs PowerShell
module files (*.psd1, *.psm1, *.ps1) with Authenticode signatures,
supporting configurable timestamp servers and hash algorithms (SHA256,
SHA384, SHA512, SHA1)

- **New Function: `New-PSBuildFileCatalog`** - Creates Windows catalog
(.cat) files that record cryptographic hashes of module contents for
tamper detection

- **New Build Tasks** - Added to both psakeFile.ps1 and IB.tasks.ps1:
  - `SignModule` - Signs module files with Authenticode
  - `BuildCatalog` - Creates a Windows catalog file
  - `SignCatalog` - Signs the catalog file
  - `Sign` - Meta-task that orchestrates the full signing pipeline

- **Configuration** - Extended `build.properties.ps1` with comprehensive
`Sign` configuration section supporting:
  - Certificate source selection and parameters
  - Timestamp server configuration
  - Hash algorithm selection
  - File inclusion patterns
  - Catalog generation settings (version, filename)

- **Localization** - Added localized messages for certificate
resolution, file signing, and catalog creation

## Implementation Details

- All signing operations include platform checks (Windows-only) with
appropriate warnings
- Pre-condition checks ensure signing is only attempted when enabled and
dependencies are available
- Certificate resolution supports both explicit configuration and
environment-based auto-detection
- Task dependencies ensure proper execution order: Build → SignModule →
BuildCatalog → SignCatalog
- Verbose logging throughout for troubleshooting certificate resolution
and signing operations

https://claude.ai/code/session_01Bt5Xb9HLoSppQ22PQUTyGP

---------

Co-authored-by: Claude <noreply@anthropic.com>

### Added

- [**psake#92**](psake#92) Add
Authenticode
code-signing support for PowerShell modules with three new public
functions:
- `Get-PSBuildCertificate` - Resolves code-signing X509Certificate2
objects
from certificate store, PFX files, Base64-encoded environment variables,
    or pre-resolved certificate objects
- `Invoke-PSBuildModuleSigning` - Signs PowerShell module files (*.psd1,
    *.psm1, *.ps1) with Authenticode signatures supporting configurable
    timestamp servers and hash algorithms
  - `New-PSBuildFileCatalog` - Creates Windows catalog (.cat) files for
    tamper detection
- New build tasks for module signing pipeline: `SignModule`,
`BuildCatalog`,
  `SignCatalog`, `Sign` (meta-task)
- Extended `$PSBPreference.Sign` configuration section with certificate
source selection, timestamp server configuration, hash algorithm
options,
  and catalog generation settings

### Fixed

- Remove extra backticks during localization text migration.

…n permissions (psake#118)

Potential fix for
[https://github.com/psake/PowerShellBuild/security/code-scanning/3](https://github.com/psake/PowerShellBuild/security/code-scanning/3)

In general, this should be fixed by explicitly defining GITHUB_TOKEN
permissions in the workflow, either at the root level (applying to all
jobs) or per job, and restricting them to the least privilege required
(for a simple test workflow usually `contents: read` is enough). This
documents the workflow’s needs and prevents it from gaining broader
access if repository or organization defaults change.

For this specific workflow in `.github/workflows/test.yml`, the safest,
least intrusive fix that preserves existing behavior is to add a
root-level `permissions:` block granting only `contents: read`. The
existing steps perform a checkout and run a PowerShell script; there is
no explicit indication they need to write to the repo, issues, or pull
requests. Adding the block directly under the workflow `name:` (before
`on:`) is conventional and applies to all jobs unless overridden. No
imports or additional methods are required; this is purely a YAML
configuration change within the workflow file.


_Suggested fixes powered by Copilot Autofix. Review carefully before
merging._

Signed-off-by: Gilbert Sanchez <me@gilbertsanchez.com>
Co-authored-by: Copilot Autofix powered by AI <62310815+github-advanced-security[bot]@users.noreply.github.com>

…n permissions (psake#119)

Potential fix for
[https://github.com/psake/PowerShellBuild/security/code-scanning/1](https://github.com/psake/PowerShellBuild/security/code-scanning/1)

In general, the fix is to explicitly define a `permissions:` block for
the workflow or individual jobs, granting only the scopes actually
needed. For most build/publish workflows that only need to read the
repository contents, `contents: read` is an appropriate minimal default.
If later steps need more permissions (e.g., to create releases or write
issues), those can be added explicitly.

For this specific file, the simplest and safest fix without altering
functionality is to add a workflow-level `permissions:` block with
`contents: read`. This will apply to the `publish` job because it
currently has no `permissions` of its own. Concretely, in
`.github/workflows/publish.yaml`, insert:

```yaml
permissions:
  contents: read
```

between the `on:` block and the `jobs:` block. No additional imports or
dependencies are needed, and no other lines in the workflow need to
change.


_Suggested fixes powered by Copilot Autofix. Review carefully before
merging._

Signed-off-by: Gilbert Sanchez <me@gilbertsanchez.com>
Co-authored-by: Copilot Autofix powered by AI <62310815+github-advanced-security[bot]@users.noreply.github.com>

Phase 0 of psake#120 — deploy [AIM (AI Agent Instruction
Modules)](https://github.com/tablackburn/ai-agent-instruction-modules)
as the first PR of the v1.0.0 cycle.

## What's included

- `AGENTS.md` (root) — agent-facing entry point with instruction matrix;
Last sync: 2026-05-17 (AIM 0.8.14)
- `aim.config.json` — module configuration; external sources enabled
(awesome-copilot fallback)
- `instructions/` — 12 instruction modules:
- Core: `agent-workflow`, `shorthand`, `git-workflow`, `testing`,
`update`
  - Language/tools: `powershell`, `markdown`, `readme`, `github-cli`
  - Repository management: `releases`, `contributing`
- Repo-specific: `repository-specific.instructions.md` (migrated from
CLAUDE.md)
- `CLAUDE.md` — one-line `@AGENTS.md` import so Claude Code auto-loads
AIM context (see "CLAUDE.md handling" below)

## CLAUDE.md migration

CLAUDE.md content was migrated to
`instructions/repository-specific.instructions.md`, keeping only
repo-specific content (project layout, `$PSBPreference` internals, task
dependency variables, naming conventions, build workflows, BuildHelpers
env vars). Generic content covered by standard AIM modules (PowerShell
style, git workflow, generic testing patterns) was dropped to avoid
duplication.

Stale references corrected during migration:
- Version: 0.7.3 → 0.8.0
- Public function count: 9 → 12 (signing functions added in 0.8.0)

## CLAUDE.md handling

The original CLAUDE.md was deleted, then re-added as a one-line file
containing only `@AGENTS.md`. Reason: Claude Code auto-loads `CLAUDE.md`
from the project root but does not auto-load `AGENTS.md` ([memory
docs](https://code.claude.com/docs/en/memory.md)). Using the official
`@`-import syntax means fresh Claude Code sessions in this repo
automatically pick up AIM context (AGENTS.md → instruction matrix →
applicable modules) without needing a manual pointer in every prompt.

This matches the AIM source repo, which ships both `AGENTS.md` and
`CLAUDE.md`.

## AIM 0.8.14 sync

Bumped from 0.8.13 → 0.8.14 (released 2026-05-16). Pulls three
instruction-file fixes from
[tablackburn/ai-agent-instruction-modules#24](tablackburn/ai-agent-instruction-modules#24):

- **`contributing.instructions.md`** — "Make Changes" pointed
contributors at `instructions/` instead of `instruction-templates/`.
Surfaced during Copilot review of this PR and filed upstream as
[tablackburn/ai-agent-instruction-modules#23](tablackburn/ai-agent-instruction-modules#23).
- **`github-cli.instructions.md`** — "Creating Releases" example used
`gh release create --notes`, contradicting `releases.instructions.md`
which mandates `--notes-file` to avoid escaping issues. Replaced with a
temp-file pattern and added a precedence note. Also surfaced during this
PR's review; same upstream issue.
- **`shorthand.instructions.md`** — backfilled the missing `Dir →
Directory` row (pre-existing sync drift in the upstream template; fixed
in the same upstream PR).

`AGENTS.md` Template Version 0.8.13 → 0.8.14 and Last sync 2026-05-15 →
2026-05-17.

## Scope

Docs/config-only — no module code changes. Verified locally:
- `git diff --stat origin/main`: 16 files changed, 0 under
`PowerShellBuild/`, `requirements.psd1`, `CHANGELOG.md`, or `.github/`
- `./build.ps1 -Task Test -Bootstrap` passes (314 passed, 0 failed, 2
skipped — the skips are git-tagging tests that expectedly skip on
feature branches)
- Module version, dependencies, and CI workflows untouched

## Note on module count vs psake#120 checklist

psake#120's Phase 0 checklist lists 8 modules. This PR deploys 12 — the
additional `readme`, `contributing`, `update`, and `repository-specific`
modules were included per the Phase 0 deployment scope I worked from.
Happy to drop any of them if the tracking issue's narrower list was
intentional.

## Phase 0 checklist (psake#120)

- [x] Add `AGENTS.md`, `aim.config.json`, `instructions/`
- [x] Migrate `CLAUDE.md` content →
`instructions/repository-specific.instructions.md`
- [x] Modules included: `agent-workflow`, `shorthand`, `git-workflow`,
`testing`, `powershell`, `markdown`, `releases`, `github-cli` (plus
`readme`, `contributing`, `update`, `repository-specific` — see note
above)
- [x] Fix stale version reference (CLAUDE.md said 0.7.3; actual is
0.8.0)

## Commits

1. `feat: deploy AIM (AI Agent Instruction Modules)` — main deployment +
CLAUDE.md content migration + CLAUDE.md deletion
2. `docs: add CLAUDE.md as @AGENTS.md import for Claude Code
auto-loading` — restore CLAUDE.md as a 1-line pointer
3. `docs: address Copilot review feedback on repository-specific
instructions` — Sign/Catalog rows, IB alias examples, `-FromModule`
psake pattern, signing task dependency + task rows
4. `docs: sync AIM 0.8.14 fixes (contributing folder, gh release notes,
Dir row)` — pull the three instruction-file fixes from AIM 0.8.14 and
bump template version + sync date

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

## Summary

PowerShellBuild 0.8.0 fails to **import** under Windows PowerShell 5.1
(Desktop). `Get-PSBuildCertificate` (added in psake#92) used the PowerShell
7+-only ternary operator; since the module loader dot-sources every
`Public/*.ps1` at import, the parse failure broke import of the whole
module on 5.1 — even though the manifest still declares
`PowerShellVersion = '3.0'`.

## Fix

- **Ternary → `if/else` expression** in `Get-PSBuildCertificate`
(5.1-safe; identical PS7 behavior).
- **`$IsWindows` guard made 5.1-safe** using the repo's existing idiom
(`$null -ne $IsWindows -and -not $IsWindows`, as in
`Build-PSBuildUpdatableHelp`). On Desktop edition the automatic variable
is absent and the platform is always Windows.

## Audit

Swept all `.ps1/.psm1/.psd1` under `PowerShellBuild/`, `build/`, and
`tests/` (and re-parsed every module file on a real 5.1 engine) for
PS7-only constructs (ternary, `??`/`??=`, `?.`/`?[ ]`, `&&`/`||`,
`clean{}`, `-Parallel`, Core-only `$Is*` vars, Core-only cmdlets/types).
The two issues in `Get-PSBuildCertificate.ps1` were the only real
incompatibilities.

## Guardrails

- **PSScriptAnalyzer compatibility rules**
(`PSUseCompatibleSyntax`/`Commands`/`Types`) enabled in
`ScriptAnalyzerSettings.psd1`, targeting Windows PowerShell 5.1
(Desktop) and PowerShell 7. `PSUseCompatibleSyntax` checks the target
language version regardless of the engine it runs on, so it catches a
ternary even from `pwsh`. Two documented false positives are suppressed
with justifications (`Get-ChildItem -CodeSigningCert` provider dynamic
parameter; `Invoke-Pester -Configuration` from the required Pester 5+).
- **`Analyze` build task fails on any compatibility violation** (these
rules are Warning-severity, which the existing Error-only gate would not
catch).
- **New `import-smoke` CI job** parses and imports the module on the
real Windows PowerShell 5.1 engine (`shell: powershell`).

## Verification

- Parse + dot-source + `Import-Module` on **real Windows PowerShell
5.1**: clean (original failed with the documented parse errors).
- PSScriptAnalyzer with the new settings: 0 compatibility findings;
confirmed it flags a reintroduced ternary.
- psake `Test` (Analyze + Pester) on pwsh 7: Analyze clean of
compatibility issues; **304 Pester tests pass**, including all of
`Get-PSBuildCertificate.tests.ps1`.

## Support contract

Per maintainer direction, the manifest
(`PowerShellVersion`/`CompatiblePSEditions`) is **left unchanged** in
this PR; the code is fixed to comply with the existing 5.1/Desktop
contract. Formalizing the declared floor is tracked for the v1.0.0
roadmap (psake#120).

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

## Summary

Removes the `### Added` entry from the 0.8.1 CHANGELOG section. It
documented an internal **CI job**, which isn't a user-facing change to
the module (public functions, build tasks, `$PSBPreference`, or
build/publish behavior).

## Why

- **Convention:** no prior release in this changelog (0.1.0 → 0.8.0)
documents CI, test, or internal-tooling changes — only the module's
user-facing surface. This entry was the sole exception.
- **It was also stale:** the bespoke `Import smoke (Windows PowerShell
5.1)` job it described was replaced in psake#126 by the shared
`psake/.github` ModuleCI workflow's full 5.1 **test** run, so the text
no longer matched what shipped.

The user-facing `### Fixed` entry (the 5.1 import regression) is
unchanged — that one genuinely affects consumers and stays.

Prep for cutting the `v0.8.1` release so the release notes reflect only
what users care about.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>