Skip to content

Refactor Pull-SDLC.ai.ps1 output to intent-appropriate streams (#194)#195

Merged
MarkMichaelis merged 2 commits into
mainfrom
refactor/194-output-streams
Jun 7, 2026
Merged

Refactor Pull-SDLC.ai.ps1 output to intent-appropriate streams (#194)#195
MarkMichaelis merged 2 commits into
mainfrom
refactor/194-output-streams

Conversation

@MarkMichaelis

Copy link
Copy Markdown
Contributor

Summary

Refactors Pull-SDLC.ai.ps1 so every message lands on the intent-appropriate stream, complying with the "Output & Streams" guidance added in 65b12a0 to .github/instructions/powershell.instructions.md. Previously all output (data, status, advisories, errors) funnelled through Write-Host -ForegroundColor, so nothing could be captured, redirected, or detected by callers/CI.

Closes #194

What changed (by intent)

Stream Cmdlet Examples
Errors (stream 2) Write-Error -ErrorAction Continue POLICY VIOLATION (rc 2), ABORT commit-context (rc 3), commit-did-not-advance (rc 4), no-git/init-failed (rc 5), worktree-sync-failed (rc 6)
Advisories (stream 3) Write-Warning -Force overwrite, push failed, manual-PR hints, bootstrap declined, bootstrap-overwrite preamble
Status (stream 6) Write-Information fetch/add-remote, worktree lifecycle, applied/created-commit, PR opened/updated, self-update, scaffolding
Decorative (host) Write-Host (narrowly suppressed) dry-run op preview (extracted to Write-PlannedOpsPreview), Next-steps banner, SSH-setup transcript

Key risk control: exit codes are byte-for-byte unchanged

$ErrorActionPreference = 'Stop' is script-scoped, so a bare Write-Error would terminate before the return <rc>. Every fatal site uses Write-Error -ErrorAction Continue, so the record lands on stream 2 and the original return code is preserved. New behavior-first tests assert both the rc and the stream for each category. $InformationPreference = 'Continue' is set at script scope to keep status visible by default.

PSAvoidUsingWriteHost findings: 108 -> 0 (remaining decorative Write-Host carry justified SuppressMessageAttribute scoped to the three sanctioned helpers). No new analyzer findings introduced.

Tests

Invoke-Pester -Path .\Pull-SDLC.ai.Tests.ps1 -Output Detailed
Invoke-ScriptAnalyzer -Path .\Pull-SDLC.ai.ps1 -Severity Warning,Error

199 passed, 0 failed (193 existing + 6 new stream-assignment tests). Analyzer clean aside from pre-existing, unrelated findings.

Evidence (inline)

Fatal path now capturable on the error stream, rc preserved, stdout clean:

EVIDENCE 1: forced FATAL path (no git repo + -NoAutoInit) -> rc=5
rc (return code)      : 5
stdout (data stream)  : '5'  <- clean, no diagnostics leaked
error stream captured : ERROR: not inside a git repository and -NoAutoInit specified. Run `git init` first or omit -NoAutoInit.

-WhatIf visible output preserved:

EVIDENCE 2: normal -WhatIf run -- visible output PRESERVED

Files to update: 2 (syncing 92c5064 -> 8646d9d)
  A: 1
  M: 1
    add     .github/agents/new.md
    update  CLAUDE.md
-WhatIf specified; no changes written.
rc = 0   (working tree untouched: CLAUDE.md still 'v1')

Copilot added 2 commits June 7, 2026 12:03
Behavior-first tests: fatal messages land on the error stream (rc 2/3/5 preserved), advisories on the warning stream, and status flows through Write-Information (non-PSHOST records) rather than Write-Host.
Map Write-Host calls to Write-Error/Write-Warning/Write-Information per the Output & Streams guidance, preserving every exit/return code (Write-Error -ErrorAction Continue keeps non-terminating under \Continue='Stop'). Set \SilentlyContinue='Continue' to keep status visible by default. Keep the decorative dry-run preview, Next-steps banner, and SSH-setup transcript on Write-Host, extracted/annotated with narrow PSAvoidUsingWriteHost suppressions.
@MarkMichaelis

Copy link
Copy Markdown
Contributor Author

Dry-run smoke test (this project's dry run is the script's own -WhatIf): a normal sync run with -WhatIf returns rc=0, prints the preserved op-preview, and leaves the working tree untouched (Evidence 2 in the PR body). CI: Validate Instructions/validate and Pester tests (.github/) both green. Note: an automated Copilot code review could not be requested in this environment -- the repo exposes only the copilot-swe-agent actor (not a review-capable reviewer) and --add-reviewer Copilot fails on the projects-classic deprecation error.

@MarkMichaelis MarkMichaelis merged commit ee0f63c into main Jun 7, 2026
2 checks passed
@MarkMichaelis MarkMichaelis deleted the refactor/194-output-streams branch June 7, 2026 19:08
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Refactor Pull-SDLC.ai.ps1 output to intent-appropriate streams (Output & Streams guidance)

1 participant