Merge pull request #60 from jakehildreth:docs/document-new-features

docs(phase-7): document ConvertTo-StepperScript, retry behavior, and fix dialog option casing

Author: jakehildreth

Docs/adr/0001-ast-parsing-over-regex.md

@@ -14,7 +14,7 @@ Three categories of fragility were identified:
 
 1. **Structural detection:** `New-Step` regex requires `{` on the same line as the call, breaking if the scriptblock is on the next line. Manual brace-counting to find block end does not account for `{`/`}` inside strings or heredocs.
 2. **Comment span detection:** `<#` / `#>` are matched line-by-line, which breaks if either token appears after executable code on the same line.
-3. **Executable-line classification:** A 5-pattern regex whitelist (`[CmdletBinding(`, `param(`, `using`, etc.) is used to skip "non-executable" lines. Incomplete by construction — any pattern not in the list is a false positive.
+3. **Executable-line classification:** A 5-pattern regex whitelist (`[CmdletBinding(`, `param(`, `using`, etc.) is used to skip "non-executable" lines. Incomplete by construction; any pattern not in the list is a false positive.
 
 Additionally, the step-counting + name-listing logic is copy-pasted verbatim 3 times in `New-Step.ps1` (lines 349–371, 501–529, 713–740), and the script file is read from disk 2–3 times per `New-Step` execution.
 
@@ -27,7 +27,7 @@ Replace all structural regex with `[System.Management.Automation.Language.Parser
 Introduce a new private function `Get-ScriptAst` that:
 - Calls `[Parser]::ParseFile()`, returning `[PSCustomObject]@{ Ast; Tokens; Errors }`
 - Emits `Write-Warning` per parse error and returns the partial AST (callers decide whether to abort)
-- Maintains a module-scoped `$script:astCache` hashtable keyed on `"$ScriptPath:$hash"` (using the existing `Get-ScriptHash` function) — auto-invalidates when the script changes, eliminates redundant disk reads
+- Maintains a module-scoped `$script:astCache` hashtable keyed on `"$ScriptPath:$hash"` (using the existing `Get-ScriptHash` function); auto-invalidates when the script changes, eliminates redundant disk reads
 
 ---
 
@@ -39,14 +39,14 @@ The PowerShell AST is syntax-aware. It correctly handles:
 - `New-Step` and `Stop-Stepper` appearing inside comments (they simply won't produce `CommandAst` nodes)
 - All PS quoting rules by construction
 
-The alternative — keeping regex but fixing edge cases — is a local patch on a structural problem. Every edge case fixed reveals the next one.
+The alternative (keeping regex but fixing edge cases) is a local patch on a structural problem. Every edge case fixed reveals the next one.
 
 ---
 
 ## Consequences
 
 - `Get-ScriptAst.ps1` added to `Private/`
-- `Get-StepInventory.ps1` added to `Private/` — encapsulates the deduplicated step-counting logic
+- `Get-StepInventory.ps1` added to `Private/`: encapsulates the deduplicated step-counting logic
 - `Find-NewStepBlocks.ps1` signature changes from `[object[]]$ScriptLines` to `[string]$ScriptPath`; brace-counting loop replaced with `$ast.FindAll(...)` + `Extent` properties
 - `Find-UnmanagedCodeBlocks.ps1` comment detection replaced with token stream inspection; executable-line classification replaced with AST extent check
 - `Test-StepperScriptRequirements.ps1` uses `$ast.ParamBlock.Attributes` and `$ast.ScriptRequirements.RequiredModules` instead of regex
@@ -58,6 +58,6 @@ The alternative — keeping regex but fixing edge cases — is a local patch on
 
 ## Rejected alternative
 
-**Direct `[Parser]::ParseFile()` calls per function** — each function would handle its own `[ref]` vars and error handling. Rejected because:
+**Direct `[Parser]::ParseFile()` calls per function**: each function would handle its own `[ref]` vars and error handling. Rejected because:
 - Error handling (`Write-Warning` per parse error) would be copy-pasted into 4–5 functions and drift over time
-- The re-parsing problem (2–3 disk reads per execution) stays unfixed — caching can only be centralized in a wrapper
+- The re-parsing problem (2–3 disk reads per execution) stays unfixed; caching can only be centralized in a wrapper

Docs/adr/0002-logging-and-step-transcripts.md

@@ -8,7 +8,7 @@
 
 ## Context
 
-Stepper had no persistent log output. All status information was emitted via `Write-Verbose`, which is ephemeral — lost if the caller omits `-Verbose` or does not capture output. There was no record of step runtimes, step failures, or what happened during a previous run.
+Stepper had no persistent log output. All status information was emitted via `Write-Verbose`, which is ephemeral; lost if the caller omits `-Verbose` or does not capture output. There was no record of step runtimes, step failures, or what happened during a previous run.
 
 Three design questions required explicit decisions before implementation:
 
@@ -24,13 +24,13 @@ Three design questions required explicit decisions before implementation:
 
 Logging is enabled for every step unless the user explicitly passes `-NoLog` to a `New-Step` call. When `-NoLog` is present on any step, Stepper prompts the user at init time to choose scope:
 
-- **A** — log all steps (ignore `-NoLog` flags)
-- **S** — skip logging for the flagged steps only
-- **D** — disable logging entirely
+- **A**, log all steps (ignore `-NoLog` flags)
+- **S**, skip logging for the flagged steps only
+- **D**, disable logging entirely
 
 This decision is persisted in the `.stepper` state file so resumed runs do not re-prompt.
 
-Rationale: unattended scripts need logs most — requiring an explicit opt-in means logs are missing exactly when they're most needed.
+Rationale: unattended scripts need logs most; requiring an explicit opt-in means logs are missing exactly when they're most needed.
 
 ### Native `Start-Transcript` per step, folded into the log file
 
@@ -42,7 +42,7 @@ Rationale: `Start-Transcript` captures the full host output including `Write-Hos
 
 Before starting a per-step transcript, Stepper checks `$Host.UI.IsTranscribing`. If `$true`, it emits a clear user-facing message and throws a terminating error (`TranscriptAlreadyActive`, category `ResourceBusy`). It does not silently skip transcript capture and continue.
 
-Rationale: silently skipping produces a log with missing transcript sections — worse than a clear failure because the user may not notice. A hard stop with an actionable message (`Stop-Transcript and re-run`) is unambiguous.
+Rationale: silently skipping produces a log with missing transcript sections; worse than a clear failure because the user may not notice. A hard stop with an actionable message (`Stop-Transcript and re-run`) is unambiguous.
 
 ### Default log path: `scriptname.ps1.stepper.log` alongside the script
 
@@ -54,19 +54,19 @@ If one or more `New-Step` calls specify `-LogPath` with a static string, that pa
 
 `LogPath`, `LoggingEnabled`, and `NoLogStepIds` are added to the existing `Export-Clixml` state object. On a resumed run, these values are read from state and applied without re-prompting.
 
-Rationale: consistency — the path and scope decisions made on the first run should apply to the resumed run, which may be unattended.
+Rationale: consistency; the path and scope decisions made on the first run should apply to the resumed run, which may be unattended.
 
 ---
 
 ## Consequences
 
 - **New private functions:** `Write-StepperLog` (structured log helper), `Get-StepLogConfig` (AST scan for `-LogPath` and `-NoLog` across all steps)
-- **State schema change:** three new fields (`LogPath`, `LoggingEnabled`, `NoLogStepIds`) added to the `Export-Clixml` object in `Write-StepperState.ps1`. Backwards compatible — old state files simply lack these fields (treated as `$null`/`$false`).
+- **State schema change:** three new fields (`LogPath`, `LoggingEnabled`, `NoLogStepIds`) added to the `Export-Clixml` object in `Write-StepperState.ps1`. Backwards compatible; old state files simply lack these fields (treated as `$null`/`$false`).
 - **`New-Step` new params:** `-LogPath [string]`, `-NoLog [switch]`
 - **`Stop-Stepper` no new params:** reads `LogPath` from `__StepperExecutionState` in the calling scope; no user-facing change.
-- **Temp files:** one temp file per step execution, deleted in a `finally` block. If the process is killed mid-step, the temp file may be orphaned in `$env:TEMP` — acceptable.
+- **Temp files:** one temp file per step execution, deleted in a `finally` block. If the process is killed mid-step, the temp file may be orphaned in `$env:TEMP`; acceptable.
 - **PS 5.1 + active transcript:** hard stop with `TranscriptAlreadyActive`. Users running enterprise runbooks that pre-start transcripts must stop them before using Stepper logging. `-NoLog` on all steps or `-N` at the scope prompt is the workaround.
-- **`Read-Host` not captured in transcripts on Unix/macOS:** `Start-Transcript` on PS Core (Unix/macOS) does not capture `Read-Host` prompts or their responses. Pipeline output, `Write-Host`, and `Write-Output` are captured normally. This is a `Start-Transcript` platform limitation — not a Stepper defect. On Windows (PS 5.1 or PS 7), `Read-Host` prompts are captured.
+- **`Read-Host` not captured in transcripts on Unix/macOS:** `Start-Transcript` on PS Core (Unix/macOS) does not capture `Read-Host` prompts or their responses. Pipeline output, `Write-Host`, and `Write-Output` are captured normally. This is a `Start-Transcript` platform limitation; not a Stepper defect. On Windows (PS 5.1 or PS 7), `Read-Host` prompts are captured.
 
 ---
 

Docs/adr/0003-silent-auto-add-requirements.md

@@ -12,10 +12,10 @@
 
 This behavior is problematic:
 
-1. **Blocks automation** — any CI/CD pipeline or unattended run hangs indefinitely waiting for interactive input.
-2. **Surprises users** — an unexpected halt mid-execution on first run violates the principle of least surprise.
-3. **Violates module design principles** — `Read-Host` is explicitly against Stepper's non-interactive design pattern.
-4. **"Skip" is a footgun** — silently continuing without the required declarations causes unpredictable failures downstream, making it the worst option despite being the easiest to reach.
+1. **Blocks automation**: any CI/CD pipeline or unattended run hangs indefinitely waiting for interactive input.
+2. **Surprises users**: an unexpected halt mid-execution on first run violates the principle of least surprise.
+3. **Violates module design principles**: `Read-Host` is explicitly against Stepper's non-interactive design pattern.
+4. **"Skip" is a footgun**: silently continuing without the required declarations causes unpredictable failures downstream, making it the worst option despite being the easiest to reach.
 
 The only safe response in the old dialog was always "Add". The "Skip" and "Quit" paths offer false choice.
 
@@ -27,14 +27,14 @@ Replace the interactive prompt with silent auto-add behavior:
 
 - If declarations are missing, add them and return `$true` without any user prompt.
 - Emit one `Write-Verbose` call per declaration added.
-- Delete any existing state file (same as before — the script has structurally changed).
+- Delete any existing state file (same as before; the script has structurally changed).
 - Add a `-SkipRequirementsCheck` `[switch]` parameter to `New-Step` for callers who want to bypass the check entirely.
 
 ---
 
 ## Rationale
 
-Silent auto-add preserves the original intent (ensure the script is properly structured) while eliminating interactive friction. Since "Add" was the only safe option in the old prompt, auto-add is semantically equivalent to the old default. `Write-Verbose` satisfies observability without blocking execution — users running with `-Verbose` see exactly what changed.
+Silent auto-add preserves the original intent (ensure the script is properly structured) while eliminating interactive friction. Since "Add" was the only safe option in the old prompt, auto-add is semantically equivalent to the old default. `Write-Verbose` satisfies observability without blocking execution; users running with `-Verbose` see exactly what changed.
 
 The `-SkipRequirementsCheck` escape hatch gives advanced users who consciously manage their own declarations a clean opt-out, without requiring workarounds or file hacks.
 

Docs/adr/0004-convert-steppersscript-output-target.md

@@ -11,8 +11,8 @@
 `Convert-StepperScript` rewrites variable references inside `New-Step` blocks from `$var` to `$Stepper.Var`. A rewrite tool that modifies files needs a clear answer to "where does the output go?"
 
 Two options were considered:
-1. **In-place only** — always overwrites the source file
-2. **In-place with backup + optional -OutputPath** — default is in-place with a `.bak` copy; `-OutputPath` writes to a new file instead, leaving the original untouched
+1. **In-place only**: always overwrites the source file
+2. **In-place with backup + optional -OutputPath**: default is in-place with a `.bak` copy; `-OutputPath` writes to a new file instead, leaving the original untouched
 
 Option 1 is simpler but gives users no recovery path if the rewrite produces unexpected results. A `.bak` is trivial to create and provides a safety net without any extra cognitive overhead.
 
@@ -29,7 +29,7 @@ Option 2 gives maximum flexibility: users who want a diff-friendly workflow can
 ## Rationale
 
 - In-place is the expected UX for a "migration" tool (lower friction)
-- `.bak` is zero-cost insurance — most users will never need it, but they'll be grateful when they do
+- `.bak` is zero-cost insurance; most users will never need it, but they'll be grateful when they do
 - `-OutputPath` enables review workflows and CI dry-run scenarios without a separate `-WhatIf` level of complexity
 - Consistent with how other script-rewriting tools in the ecosystem behave (e.g. `2to3`, `ps-upgrade`)
 
@@ -40,4 +40,4 @@ Option 2 gives maximum flexibility: users who want a diff-friendly workflow can
 - `Convert-StepperScript` has a common `-OutputPath [string]` optional parameter
 - When `-OutputPath` is absent: reads source, writes `.bak`, writes rewritten content back to source
 - When `-OutputPath` is present: reads source, writes rewritten content to `-OutputPath`, source untouched, no `.bak`
-- `-WhatIf` support via `SupportsShouldProcess` — prints what would change without writing anything
+- `-WhatIf` support via `SupportsShouldProcess`; prints what would change without writing anything

Docs/adr/0005-cbh-injection-is-silent.md

@@ -11,8 +11,8 @@
 `Repair-StepperScript` (and the first-run hook in `New-Step`) detects whether a user's script has comment-based help (CBH). If CBH is absent, Stepper can inject a skeleton block automatically.
 
 Two injection styles were considered:
-1. **Silent** — inject without prompting; emit one `Write-Verbose` call; continue execution
-2. **Interactive** — print a notice, call `exit`, require user to re-run (same pattern as `MissingCmdletBinding` in the old `Test-StepperScriptRequirements`)
+1. **Silent**: inject without prompting; emit one `Write-Verbose` call; continue execution
+2. **Interactive**: print a notice, call `exit`, require user to re-run (same pattern as `MissingCmdletBinding` in the old `Test-StepperScriptRequirements`)
 
 The `[CmdletBinding()]` and install-guard injections are already silent as of ADR 0003. CBH injection modifies the script in the same category of "structural improvement" as those two, and carries no functional risk (CBH is inert at runtime).
 
@@ -30,7 +30,7 @@ CBH injection is silent. No `Write-Host`, no `exit`, no user prompt. Consistent
 
 - CBH is documentation-only; its absence or presence does not affect script execution
 - Interrupting execution for a non-functional change violates the principle of least surprise
-- Consistency with existing silent injections (ADR 0003) — users learn one mental model
+- Consistency with existing silent injections (ADR 0003); users learn one mental model
 - Verbose output is still emitted, so `-Verbose` users see what happened
 
 ---

Docs/adr/0006-new-steppersscript-showcase-switch.md

@@ -11,10 +11,10 @@
 `New-StepperScript` generates a new `.ps1` file pre-wired for Stepper. The question was how much content to include by default.
 
 Two extremes:
-1. **Minimal skeleton** — just the structural requirements: CBH, `[CmdletBinding()] param()`, install guard, two placeholder `New-Step` blocks, `Stop-Stepper`. Minimal noise, immediately editable.
-2. **Feature-showcase template** — everything in minimal, plus commented examples demonstrating named steps, `$Stepper.<var>` persistence, `-NoLog`, `-Retry`/`-RetryInterval`/`-MaxRetries`, and `#region Stepper ignore` blocks.
+1. **Minimal skeleton**: just the structural requirements: CBH, `[CmdletBinding()] param()`, install guard, two placeholder `New-Step` blocks, `Stop-Stepper`. Minimal noise, immediately editable.
+2. **Feature-showcase template**: everything in minimal, plus commented examples demonstrating named steps, `$Stepper.<var>` persistence, `-NoLog`, `-Retry`/`-RetryInterval`/`-MaxRetries`, and `#region Stepper ignore` blocks.
 
-Both templates can be useful in either situation — the right choice depends on intent, not experience level. A single fixed template forces a tradeoff: a minimal-only tool requires users to look up API details elsewhere; a showcase-only tool clutters files that just need a starting point.
+Both templates can be useful in either situation; the right choice depends on intent, not experience level. A single fixed template forces a tradeoff: a minimal-only tool requires users to look up API details elsewhere; a showcase-only tool clutters files that just need a starting point.
 
 The solution is a default of minimal with an opt-in flag for the full showcase.
 
@@ -28,9 +28,9 @@ The solution is a default of minimal with an opt-in flag for the full showcase.
 
 ## Rationale
 
-- Minimal is the right default because the common case is starting a new script, not exploring the API — less to delete, immediately writable
+- Minimal is the right default because the common case is starting a new script, not exploring the API; less to delete, immediately writable
 - Showcase is the right opt-in for any time you want in-file examples as a reference, regardless of experience level
-- Aliases make the flag discoverable — users who think `-Full` or `-WithExamples` are likely to get tab-completion
+- Aliases make the flag discoverable; users who think `-Full` or `-WithExamples` are likely to get tab-completion
 - Single implementation path per template variant (no runtime branching inside each `New-Step` block)
 
 ---

Docs/adr/0007-new-steppersscript-parameter-sets.md

@@ -10,8 +10,8 @@
 
 `New-StepperScript` needs a way to specify where to write the new script. Two calling styles exist in the wild:
 
-- `New-StepperScript -Path './scripts/Deploy.ps1'` — caller specifies a full path
-- `New-StepperScript -Name 'Deploy' -Directory './scripts'` — caller specifies name and location separately; the function constructs the path
+- `New-StepperScript -Path './scripts/Deploy.ps1'`: caller specifies a full path
+- `New-StepperScript -Name 'Deploy' -Directory './scripts'`: caller specifies name and location separately; the function constructs the path
 
 Both are idiomatic for PowerShell creation functions. `New-Item` uses `-Path`. `New-ADUser` and similar functions use `-Name` + a location parameter. Some users will have a full path from a variable; others want to type less by specifying just a name.
 
@@ -23,7 +23,7 @@ Supporting only one style forces awkward usage for the other half of callers.
 
 `New-StepperScript` uses two parameter sets:
 
-- **`ByPath`**: `-Path [string]` (mandatory) — full file path
+- **`ByPath`**: `-Path [string]` (mandatory): full file path
 - **`ByName`**: `-Name [string]` (mandatory) + `-Directory [string]` (optional, defaults to `$PWD`)
 
 Both produce identical output; `ByName` constructs the full path as `Join-Path $Directory "$Name.ps1"`.