review-ps

name	review-ps
description	Self-review PowerShell code against the project's PS7 conventions before reporting work as done.

PowerShell Code Review Checklist

Run this checklist against all changed .ps1 / .psm1 files before reporting work as done.

1. Strict Mode Safety

• Set-StrictMode -Version Latest is set (or inherited from caller)
• All JSON property access uses $obj.PSObject.Properties['prop'] guards
• All Where-Object pipelines wrapped in @() before .Count
• No .Count on raw ConvertFrom-Json arrays — wrap in @()
• No complex .NET constructors inside inline if/else assignments

2. Module Export Registration

• New public functions added to BOTH AITriad.psm1 Export-ModuleMember AND AITriad.psd1 FunctionsToExport
• Run Test-ModuleManifest -Path scripts/AITriad/AITriad.psd1 passes

3. Error Handling

• All unrecoverable errors use New-ActionableError with Goal, Problem, Location, NextSteps
• No bare throw "message" — always throw (New-ActionableError ...)
• Prefer recovery (retry, fallback, partial results) over failure
• $ErrorActionPreference = 'Stop' in cmdlets that need it

4. Naming & Structure

• Approved verb used (Get-Verb to check)
• Public functions in Public/, helpers in Private/
• [CmdletBinding()] on all public functions
• SupportsShouldProcess for any function that modifies data

5. AI Integration

• Prompt text in Prompts/*.prompt, loaded via Get-Prompt — not inline
• Model validation uses [ValidateScript({ Test-AIModelId $_ })]
• Resolve-AIApiKey uses -ExplicitKey and -Backend (not -ApiKey/-Model)
• Default model is gemini-3.1-flash-lite

6. Data Paths

• Uses Get-TaxonomyDir, Get-SourcesDir, etc. — no hardcoded Join-Path
• Source doc IDs generated by New-Slug

7. Typed Output

• Prefer typed class output over [PSCustomObject] for reusable return types
• Classes defined in AITriad.psm1 when used by multiple commands

8. Pipeline Hygiene

• No pipeline pollution — unwanted output captured in $null = or [void]
• Write-Host for user-facing output, not Write-Output (which pollutes pipeline)
• Progress bars use Write-Progress with -Id to avoid conflicts

9. Concurrency (if applicable)

• ForEach-Object -Parallel blocks explicitly Import-Module needed modules
• Thread-safe collections (ConcurrentBag, ConcurrentDictionary) for shared state
• [System.Threading.Interlocked]::Increment for counters
• Pester mocks don't apply in parallel runspaces — tests adapted accordingly

10. Testing

• Pester tests exist for new cmdlets
• Invoke-Pester ./tests/ passes (373+ tests, 0 failures)
• Tests cover: parameter validation, skip/error paths, happy path, WhatIf if applicable

Final Gate

Invoke-Pester ./tests/ -Output Minimal
Test-ModuleManifest -Path ./scripts/AITriad/AITriad.psd1

Both must pass before reporting complete.