feat(#1512): remove abandoned generated documentation files

[fullsend-ai-coder]

Add cleanup logic to the documentation generation process that removes stale generated .adoc files when their corresponding CLI commands, Rego builtins, or Tekton tasks are removed.

Each documentation template now includes a generated-file marker comment at the top of each output file. The GenerateAsciidoc function collects all file paths written by the CLI, Rego, and Tekton generators, then scans the pages directory for .adoc files with the marker that were not produced in the current run. These stale files are removed automatically. Handwritten documentation files (which lack the marker) are never touched.

The generator functions (GenerateCommandLineDocumentation, GenerateRegoReference, GenerateTektonDocumentation) now return the list of page file paths they wrote, enabling the cleanup logic in the parent GenerateAsciidoc function.

---

Closes #1512

Post-script verification

• Branch is not main/master (agent/1512-abandoned-doc-removal)
• Secret scan passed (gitleaks — d134e495b18cf8493cfea8791e310b58f0320797..HEAD)
• Pre-commit hooks passed (authoritative run on runner)
• Tests ran inside sandbox

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 9:55 AM UTC · Completed 10:06 AM UTC
Commit: 47d3320 · View workflow run →

[codecov]

Codecov Report

❌ Patch coverage is 32.53012% with 56 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
internal/documentation/asciidoc/rego/rego.go	0.00%	19 Missing ⚠️
internal/documentation/asciidoc/asciidoc.go	62.79%	16 Missing ⚠️
internal/documentation/asciidoc/tekton/tekton.go	0.00%	12 Missing ⚠️
internal/documentation/asciidoc/cli/cli.go	0.00%	9 Missing ⚠️

Flag	Coverage Δ
acceptance	53.44% <ø> (+<0.01%)	⬆️
generative	16.72% <0.00%> (-0.07%)	⬇️
integration	27.55% <0.00%> (-0.11%)	⬇️
unit	69.07% <32.53%> (-0.06%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
internal/documentation/asciidoc/cli/cli.go	0.00% <0.00%> (ø)
internal/documentation/asciidoc/tekton/tekton.go	0.00% <0.00%> (ø)
internal/documentation/asciidoc/asciidoc.go	56.25% <62.79%> (+56.25%)	⬆️
internal/documentation/asciidoc/rego/rego.go	0.00% <0.00%> (ø)

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[fullsend-ai-review]

Review — approve

Clean implementation of stale generated-doc cleanup for #1512. The marker-based approach is sound: each template now embeds a // Generated by conforma CLI documentation tooling. DO NOT EDIT. comment as the first line of output, the three generator functions (GenerateCommandLineDocumentation, GenerateRegoReference, GenerateTektonDocumentation) return the list of page paths they wrote, and removeAbandonedPages scans the pages/ directory and removes only .adoc files whose first line matches the marker but which were not part of the current generation run. Handwritten files are never touched.

Correctness

• Path consistency ✅ — All generators construct paths as filepath.Join(module, "pages", <filename>) and the cleanup function reconstructs paths identically from os.ReadDir entries. Confirmed matching.
• Recursive CLI path tracking ✅ — generateCommandReference uses a *[]string accumulator passed through recursive calls, so subcommand page paths are correctly collected at all levels.
• rego.tmpl marker placement ✅ — The marker is placed after {{define}} blocks, which produce no rendered output. The trailing -}} trim markers on the last define block consume the intervening whitespace, so the marker is the first character of rendered output.
• Nav files excluded ✅ — Nav files are written to partials/, not pages/, so they are correctly excluded from the generated-paths list and from the cleanup scan.
• GenerateAsciidoc signature unchanged ✅ — The public function signature remains error, so the caller in documentation.go is unaffected.
• Tests ✅ — Good coverage of the main scenarios: stale removal, handwritten preservation, non-adoc file skipping, mixed scenario, empty directory, and marker detection (with marker, without marker, empty file).

Security

No security findings. The code operates on a known local directory using safe Go standard library APIs (os.ReadDir, os.Open, os.Remove). DirEntry.Name() cannot contain path separators, so path traversal via filepath.Join is not possible. os.Remove on symlinks removes the link, not the target. All changes are in internal/ packages with no external API surface.

Scope & coherence

The PR precisely addresses issue #1512's request: "The document generation code should keep track of any abandoned components and remove the corresponding Asciidoc files." No scope creep — all changes serve the cleanup feature. The marker-based approach is a pragmatic choice that is safe by default (only deletes files it can positively identify as generated).

Notes

• Pre-existing defer f.Close() in loops — Both generateRegoReference (rego.go) and generateTektonReference (tekton.go) use defer f.Close() inside for loops. Since defer executes at function return (not loop iteration end), all file handles opened during the loop remain open simultaneously. With the small number of builtins and tasks this is unlikely to cause issues, but it is a well-known Go anti-pattern worth fixing as follow-up.
• Pre-existing orphan — verify-conforma-vsa-release-ta.adoc exists in the pages directory but has no corresponding task YAML in tasks/. Since it was generated before the marker system, it lacks the marker and will not be auto-cleaned. This is the correct safe behavior — the cleanup mechanism works going forward for newly-generated files. A one-time manual deletion could address this specific file.

---

Labels: PR modifies documentation generation tooling and generated docs

[fullsend-ai-review]

[low] resource-leak

Pre-existing: defer f.Close() inside for loop in generateRegoReference keeps all file handles open until function return. Same pattern exists in tekton.go:95. Not introduced by this PR, but these functions are modified here.

Suggested fix: Extract the loop body into a helper function so defer scopes correctly per iteration, or replace defer f.Close() with explicit f.Close() after template execution.