feat(#194): enhance Nova scaffolding with .gitignore management

- create or update default .gitignore in generated project root when Git is enabled
- append missing Nova-managed artifact entries without overwriting existing rules
- update documentation to reflect .gitignore functionality in scaffold flows

Author: stiwicourage

CHANGELOG.md

@@ -17,6 +17,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
     - The generated guidance now expresses PowerShell source/helper-script maintainability rules through `code-quality-matrix.instructions.md` and keeps test-specific design guidance in the testing instruction/skill files.
       - The generated guidance now requires `docs/<ProjectName>/en-US/*.md` to stay valid PlatyPS help with YAML metadata and build-compatible structure, tells agents to use the documented `New-MarkdownCommandHelp` / `Update-MarkdownCommandHelp` / `Test-MarkdownCommandHelp` workflow instead of replacing command help with plain Markdown that breaks `nova build`, and requires a matching help file for every new public entry point in the same change.
       - The generated PowerShell guidance now requires agents to review every changed or generated text file before handoff and normalize the file ending to exactly one trailing newline with no extra blank lines at the bottom.
+    - When Git is enabled during either scaffold flow, Nova now creates or updates a default `.gitignore` in the generated project root and appends only the missing Nova-managed artifact entries instead of overwriting existing ignore rules.
 
 
 ### Changed

RELEASE_NOTE.md

@@ -15,6 +15,7 @@ This file summarizes public cmdlet, CLI, configuration, and migration changes fo
     - Generated guidance now expresses PowerShell source/helper-script maintainability rules through `code-quality-matrix.instructions.md` and keeps test-specific design guidance in the testing instruction/skill files.
     - Generated guidance now requires `docs/<ProjectName>/en-US/*.md` to stay valid PlatyPS help with YAML metadata and build-compatible structure, points agents to the `New-MarkdownCommandHelp` / `Update-MarkdownCommandHelp` / `Test-MarkdownCommandHelp` workflow, and requires a matching help file for every new public entry point in the same change so command help stays build-compatible from the start.
     - Generated PowerShell guidance now requires agents to review every changed or generated text file before handoff and normalize the file ending to exactly one trailing newline with no extra blank lines at the bottom.
+    - When Git is enabled during either scaffold flow, Nova now creates or updates a default `.gitignore` in the generated project root and appends only the missing Nova-managed artifact entries instead of overwriting existing ignore rules.
 
 
 ### Changed

docs/NovaModuleTools/en-US/Initialize-NovaModule.md

@@ -27,7 +27,8 @@ PS> Initialize-NovaModule [-Path <string>] [-Example] [-WhatIf] [-Confirm] [<Com
 
 `Initialize-NovaModule` creates a new project folder, the standard `src/` layout, and a starter `project.json` file.
 
-The command collects project details interactively, including the module name, description, version, author, minimum PowerShell version, Git initialization, and an optional Agentic Copilot starter package. When you enable the Agentic package, Nova also asks for a project short name used in generated guidance placeholders such as `Invoke-<ShortName>*`; for NovaModuleTools the short name is `Nova`, but it could also have been `NMT`. The Agentic package follows Nova's maintained agentic guidance through a filtered starter mirror, including Nova build/test/package expectations, `project.json` `Manifest.PowerShellHostVersion` compatibility guidance, strict ScriptAnalyzer guidance without excluded rules, generated `dist` module files, command-help ownership, source-mirrored test guidance, guidance that ScriptAnalyzer findings reported by
+The command collects project details interactively, including the module name, description, version, author, minimum PowerShell version, Git initialization, and an optional Agentic Copilot starter package. When Git initialization is enabled, Nova also creates or updates a default `.gitignore` in the generated project root so common local and CI artifact paths such as `artifacts/`, `dist/`, `run.ps1`, and `reload.ps1` are ignored from the start. Existing `.gitignore` files are preserved and only receive the missing Nova-managed entries. When you enable the Agentic package, Nova also asks for a project short name used in generated guidance placeholders such as `Invoke-<ShortName>*`; for NovaModuleTools the short name is `Nova`, but it could also have been `NMT`. The Agentic package follows Nova's maintained agentic guidance through a filtered starter mirror, including Nova build/test/package expectations, `project.json`
+`Manifest.PowerShellHostVersion` compatibility guidance, strict ScriptAnalyzer guidance without excluded rules, generated `dist` module files, command-help ownership, source-mirrored test guidance, guidance that ScriptAnalyzer findings reported by
 `run.ps1` must be fixed before handoff, explicit PSScriptAnalyzer workflow guidance for `./scripts/build/Invoke-ScriptAnalyzerCI.ps1`, `./run.ps1`, and focused `Invoke-ScriptAnalyzer` usage, explicit public/private PowerShell file ownership rules, best-effort source/helper-script maintainability guidance plus separate test-design guidance delivered through Agentic Copilot files, explicit valid-PlatyPS help guidance for `docs/<ProjectName>/en-US/*.md` that uses `New-MarkdownCommandHelp`, `Update-MarkdownCommandHelp`, and `Test-MarkdownCommandHelp`, and a strict file-ending rule for changed or generated text files. For the standard scaffold, the interactive flow also includes optional basic Pester support.
 
 If you enter an invalid answer during the interactive flow, `Initialize-NovaModule` reports the validation problem immediately and retries that prompt before it continues to the next question.
@@ -36,7 +37,7 @@ Use this command when you want to start a new module in the NovaModuleTools stru
 
 Use `-Path` when you want to create the project under a specific base directory. Positional path syntax is no longer supported.
 
-Use `-Example` when you want the scaffold to start from the packaged example project instead of the minimal default layout. The example flow keeps the example source, resource, and test files, skips the Pester enable/disable question, and applies the interactive metadata values to the copied `project.json`. The standard and example flows share the same inline validation and retry behavior for interactive answers, including the optional Agentic Copilot setup prompt after the Git question. When you answer `Yes`, Nova asks for the short project name, adds the same starter package to either scaffold style, and merges the example README instead of replacing it with the generic starter README outright.
+Use `-Example` when you want the scaffold to start from the packaged example project instead of the minimal default layout. The example flow keeps the example source, resource, and test files, skips the Pester enable/disable question, and applies the interactive metadata values to the copied `project.json`. The standard and example flows share the same inline validation and retry behavior for interactive answers, including the optional Agentic Copilot setup prompt after the Git question. When Git is enabled in either flow, Nova also ensures the generated project root has the default `.gitignore` entries for local and CI artifacts without overwriting any existing `.gitignore` content. When you answer `Yes`, Nova asks for the short project name, adds the same starter package to either scaffold style, and merges the example README instead of replacing it with the generic starter README outright.
 
 This command supports `-WhatIf` and `-Confirm` through PowerShell `SupportsShouldProcess`. Use `-WhatIf` to preview the scaffold target after the interactive answers have been collected, without creating folders, writing `project.json`, or initializing Git.
 
@@ -137,7 +138,7 @@ This cmdlet does not emit an output object.
 
 ## NOTES
 
-Generated projects start with NovaModuleTools defaults for recursive discovery, source markers, and duplicate-function validation. The packaged example scaffold keeps its bundled example source and tests, while still updating prompt-driven metadata such as project name, description, version, author, and PowerShell host version. The optional Agentic Copilot starter package adds repository-local Copilot workflow files under the project root and `.github/` that tell agents to keep build/test/package workflows on Nova, treat `project.json` `Manifest.PowerShellHostVersion` as the PowerShell compatibility target, run ScriptAnalyzer before build/test through the repo-standard `Invoke-ScriptAnalyzerCI.ps1` / `run.ps1` workflow, fix any ScriptAnalyzer findings before handoff, run project tests through `Test-NovaBuild` instead of direct `Invoke-Pester`, leave `.psm1` / `.psd1` files to generated
+Generated projects start with NovaModuleTools defaults for recursive discovery, source markers, duplicate-function validation, and—when Git is enabled—a default `.gitignore` for common local and CI artifact paths. The packaged example scaffold keeps its bundled example source and tests, while still updating prompt-driven metadata such as project name, description, version, author, and PowerShell host version. The optional Agentic Copilot starter package adds repository-local Copilot workflow files under the project root and `.github/` that tell agents to keep build/test/package workflows on Nova, treat `project.json` `Manifest.PowerShellHostVersion` as the PowerShell compatibility target, run ScriptAnalyzer before build/test through the repo-standard `Invoke-ScriptAnalyzerCI.ps1` / `run.ps1` workflow, fix any ScriptAnalyzer findings before handoff, run project tests through `Test-NovaBuild` instead of direct `Invoke-Pester`, leave `.psm1` / `.psd1` files to generated
 `dist` output, generate and validate command help with the Microsoft.PowerShell.PlatyPS cmdlets instead of hand-written Markdown structure, require a matching help file for every new public entry point in the same change, and mirror new tests to source files.
 
 `Initialize-NovaModule` uses `SupportsShouldProcess`, so `Get-Help Initialize-NovaModule -Full` surfaces native

docs/commands.html

@@ -162,7 +162,7 @@ <h3>Install the <code>nova</code> launcher</h3>
                         </ul>
                         <pre><code>PS&gt; Install-NovaCli
 PS&gt; Install-NovaCli -DestinationDirectory ~/bin -Force</code></pre>
-                        <p><a class="text-link" href="./getting-started.html#install-and-update">See setup details</a>
+                        <p><a class="text-link" href="./getting-started.html#install-module">See setup details</a>
                         </p>
                     </article>
 
@@ -174,9 +174,11 @@ <h3>Start a new project</h3>
                         <div class="surface-note" data-command-visibility="powershell">
                             <p><strong>Cmdlet:</strong> <code>Initialize-NovaModule</code></p>
                         </div>
-                        <p>Create the minimal scaffold or the example scaffold for a new module project. Both interactive
-                            flows can also add the optional Agentic Copilot starter package, which follows Nova's
-                            maintained agentic guidance through a filtered starter mirror, including Nova build/test
+                        <p>Create the minimal scaffold or the example scaffold for a new module project. When Git is
+                            enabled, Nova also creates or updates a default <code>.gitignore</code> in the generated
+                            project root so common local and CI artifact paths are ignored without overwriting existing
+                            rules. Both interactive flows can also add the optional Agentic Copilot starter package,
+                            which follows Nova's maintained agentic guidance through a filtered starter mirror, including Nova build/test
                             expectations, <code>project.json</code> <code>Manifest.PowerShellHostVersion</code>
                             compatibility guidance, strict ScriptAnalyzer guidance without excluded rules, generated
                             <code>dist</code> module files, command-help ownership, source-mirrored test guidance,

docs/core-workflows.html

@@ -124,8 +124,11 @@ <h2>Create the project</h2>
                         path syntax such as <code>% nova init ~/Work</code>.</p>
                 </div>
                 <p>Both scaffold styles ask the same core project questions, and both now offer an optional Agentic
-                    Copilot starter package after the Git prompt. The Agentic prompt defaults to <code>No</code>, and
-                    the package follows Nova's maintained agentic guidance through a filtered starter mirror, including
+                    Copilot starter package after the Git prompt. When you enable Git in either scaffold style, Nova
+                    also creates or updates a default <code>.gitignore</code> in the generated project root so common
+                    local and CI artifact paths are ignored without overwriting existing rules. The Agentic prompt
+                    defaults to <code>No</code>, and the package follows Nova's maintained agentic guidance through a
+                    filtered starter mirror, including
                     Nova build/test/package expectations, <code>project.json</code>
                     <code>Manifest.PowerShellHostVersion</code> compatibility guidance, strict ScriptAnalyzer guidance
                     without excluded rules, generated <code>dist</code> module files, command-help ownership,

docs/getting-started.html

@@ -195,6 +195,9 @@ <h2>4. Scaffold the packaged example</h2>
                 </div>
                 <p>Nova asks for the project name, description, version, author, minimum PowerShell version, whether
                     Git should be initialized, and whether Nova should add the optional Agentic Copilot starter package.
+                    When you enable Git, Nova also creates or updates a default <code>.gitignore</code> in the new
+                    project root so common local and CI artifact paths start ignored without overwriting existing ignore
+                    rules.
                     The Agentic package follows Nova's maintained agentic guidance through a filtered starter mirror,
                     including Nova build/test/package expectations, <code>project.json</code>
                     <code>Manifest.PowerShellHostVersion</code> compatibility guidance, strict ScriptAnalyzer guidance

scripts/build/Sync-AgenticCopilotScaffold.ps1

@@ -64,32 +64,55 @@ function Test-AgenticPathExcluded {
     return $false
 }
 
-function Get-AgenticMirrorSourceFile {
+function Get-AgenticSourceFileListForPath {
     param(
         [Parameter(Mandatory)][string]$RootPath,
-        [Parameter(Mandatory)][string[]]$SourcePathList,
+        [Parameter(Mandatory)][string]$SourcePath
+    )
+
+    $resolvedSourcePath = Resolve-AgenticRepositoryPath -RootPath $RootPath -RelativePath $SourcePath
+    if (-not (Test-Path -LiteralPath $resolvedSourcePath)) {
+        throw "Agentic scaffold source path does not exist: $SourcePath"
+    }
+
+    if (Test-Path -LiteralPath $resolvedSourcePath -PathType Leaf) {
+        return @(Get-Item -LiteralPath $resolvedSourcePath)
+    }
+
+    return @(Get-ChildItem -LiteralPath $resolvedSourcePath -File -Recurse -Force)
+}
+
+function ConvertTo-AgenticMirrorSourceFile {
+    param(
+        [Parameter(Mandatory)][string]$RootPath,
+        [Parameter(Mandatory)][System.IO.FileInfo]$SourceFile,
         [Parameter(Mandatory)][string[]]$ExcludedPathList
     )
 
-    $sourceFileList = foreach ($sourcePath in $SourcePathList) {
-        $resolvedSourcePath = Resolve-AgenticRepositoryPath -RootPath $RootPath -RelativePath $sourcePath
-        if (-not (Test-Path -LiteralPath $resolvedSourcePath)) {
-            throw "Agentic scaffold source path does not exist: $sourcePath"
-        }
+    $relativePath = Get-AgenticRelativePath -RootPath $RootPath -Path $SourceFile.FullName
+    if (Test-AgenticPathExcluded -RelativePath $relativePath -ExcludedPathList $ExcludedPathList) {
+        return $null
+    }
 
-        if (Test-Path -LiteralPath $resolvedSourcePath -PathType Leaf) {
-            Get-Item -LiteralPath $resolvedSourcePath
-        } else {
-            Get-ChildItem -LiteralPath $resolvedSourcePath -File -Recurse -Force
-        }
+    return [pscustomobject]@{
+        SourcePath = $SourceFile.FullName
+        RelativePath = $relativePath
     }
+}
+
+function Get-AgenticMirrorSourceFile {
+    param(
+        [Parameter(Mandatory)][string]$RootPath,
+        [Parameter(Mandatory)][string[]]$SourcePathList,
+        [Parameter(Mandatory)][string[]]$ExcludedPathList
+    )
 
-    foreach ($sourceFile in $sourceFileList) {
-        $relativePath = Get-AgenticRelativePath -RootPath $RootPath -Path $sourceFile.FullName
-        if (-not (Test-AgenticPathExcluded -RelativePath $relativePath -ExcludedPathList $ExcludedPathList)) {
-            [pscustomobject]@{
-                SourcePath = $sourceFile.FullName
-                RelativePath = $relativePath
+    foreach ($sourcePath in $SourcePathList) {
+        $sourceFileList = @(Get-AgenticSourceFileListForPath -RootPath $RootPath -SourcePath $sourcePath)
+        foreach ($sourceFile in $sourceFileList) {
+            $mirrorSourceFile = ConvertTo-AgenticMirrorSourceFile -RootPath $RootPath -SourceFile $sourceFile -ExcludedPathList $ExcludedPathList
+            if ($null -ne $mirrorSourceFile) {
+                $mirrorSourceFile
             }
         }
     }

src/private/scaffold/InitializeNovaModuleScaffold.ps1

@@ -20,6 +20,7 @@ function Initialize-NovaModuleScaffold {
     }
 
     if ($Answer.EnableGit -eq 'Yes') {
+        Update-NovaGitIgnore -ProjectRoot $Paths.Project -Confirm:$false
         Write-Message 'Initialize Git Repo'
         New-InitiateGitRepo -DirectoryPath $Paths.Project
     }