♻️ refactor(app): move follow-import example maintenance into tests

Author: cocosip

docs/go/maintainer/development-tracker.md

@@ -151,6 +151,34 @@ Immediate next tasks:
 
 ### 2026-03-17 Session Update
 
+- Completed: Removed the maintainer-only `--list-examples` / `--refresh-examples` execution path from the production `cleanup-follow-imports` and `audit-follow-imports` commands. Hygiene example catalogs now live only in `internal/app/follow_examples_test.go`, checked-in fixture rewrites happen through env-gated test helpers, and the operator/maintainer docs now describe that test-driven maintenance flow instead of advertising unsupported runtime flags.
+- In progress: none.
+- Blockers: none.
+- Next step: decide whether the remaining cleanup/audit flag parsing should also move behind a smaller shared helper, or whether the next slice should return to a new operator-facing capability.
+
+### 2026-03-17 Session Update
+
+- Completed: Extended the shared follow/import example helper to cover example-mode flag parsing and validation as well as fixture IO. `cleanup-follow-imports` and `audit-follow-imports` now reuse the same `--list-examples` / `--refresh-examples[=<name[,name...]>]` parsing, duplicate-name normalization, incompatibility checks, and named-fixture validation, leaving only command-specific operational-target validation in `internal/app/import_follow.go`.
+- In progress: none.
+- Blockers: none.
+- Next step: decide whether the remaining cleanup/audit option-parsing duplication is worth another shared helper, or whether follow/import work should pivot back to new operator-facing functionality.
+
+### 2026-03-17 Session Update
+
+- Completed: Refactored the follow/import example-fixture workflow behind a shared helper in `internal/app/follow_examples.go`. `cleanup-follow-imports` and `audit-follow-imports` now reuse the same base-dir resolution, example-name parsing, named fixture selection, list output, and refresh-writing logic instead of carrying two near-identical helper stacks, while keeping their command-specific example catalogs and renderers unchanged.
+- In progress: none.
+- Blockers: none.
+- Next step: decide whether the current shared helper plus hard-coded example catalogs is the right steady state, or whether a later slice should move those example catalogs into a small manifest once the operator sample set grows further.
+
+### 2026-03-17 Session Update
+
+- Completed: Added checked-in `audit-follow-imports` sample outputs under `internal/app/testdata` together with `--list-examples` and `--refresh-examples[=<name[,name...]>]` maintenance helpers. The audit command now matches the cleanup command's fixture workflow, app and parser coverage verify example-mode parsing plus refresh/list wiring, and `TestAuditFollowImportsExampleOutputsStayInSync` fails if future audit renderer changes are not reflected in the checked-in fixtures and docs.
+- In progress: none.
+- Blockers: none.
+- Next step: decide whether the audit example catalog is complete enough now, or whether future follow/import operator samples should move into a small manifest once the hard-coded fixture set grows further.
+
+### 2026-03-17 Session Update
+
 - Completed: Added `--policy-profile` presets to `scripts/readiness-check` with initial `ci` and `release` profiles. Profiles expand to the existing threshold and warning-policy flags instead of introducing a second policy engine: `ci` sets the current slow-run thresholds, while `release` adds the stale follow-health failure policy on top. Explicit flags still override profile thresholds and append extra warning codes, and the final text/JSON outputs now expose `policy_profile` alongside the already-expanded thresholds and warning-policy fields. Tests now cover profile parsing, override behavior, lint is clean again, and `go test ./...` remains green.
 - In progress: none.
 - Blockers: none.

docs/go/maintainer/mcp-integration.md

@@ -235,20 +235,35 @@ That combined check now covers:
 2. stdio MCP smoke test
 3. HTTP MCP smoke test
 
-The checked-in `cleanup-follow-imports` example outputs under [../../../internal/app/testdata](../../../internal/app/testdata/) now support the same maintainer loop. When the cleanup text or JSON renderer changes on purpose, refresh every cleanup fixture from the repository root with:
+The checked-in `cleanup-follow-imports` and `audit-follow-imports` example outputs under [../../../internal/app/testdata](../../../internal/app/testdata/) still support a maintainer refresh loop, but that loop now lives only in test code so the packaged commands stay production-focused. When a hygiene-report renderer changes on purpose, refresh every cleanup fixture from the repository root with:
 
 ```powershell
-go run ./cmd/codex-mem cleanup-follow-imports --refresh-examples
+$env:CODEX_MEM_REFRESH_CLEANUP_EXAMPLES = "all"
+go test ./internal/app -run TestRefreshCleanupFollowImportsExampleFixtures
+Remove-Item Env:CODEX_MEM_REFRESH_CLEANUP_EXAMPLES
 ```
 
-If you only need a subset while iterating, list the current names first and then refresh the exact fixtures you touched:
+Refresh every audit fixture the same way:
 
 ```powershell
-go run ./cmd/codex-mem cleanup-follow-imports --list-examples
-go run ./cmd/codex-mem cleanup-follow-imports --refresh-examples=filtered-cleanup-json
+$env:CODEX_MEM_REFRESH_AUDIT_EXAMPLES = "all"
+go test ./internal/app -run TestRefreshAuditFollowImportsExampleFixtures
+Remove-Item Env:CODEX_MEM_REFRESH_AUDIT_EXAMPLES
 ```
 
-Then rerun `go test ./internal/app -run TestCleanupFollowImportsExampleOutputsStayInSync` plus the normal repo checks so the updated cleanup fixtures are verified in read-only mode again.
+If you only need a subset while iterating, pass the exact fixture names through the matching environment variable. The canonical names live in [../../../internal/app/follow_examples_test.go](../../../internal/app/follow_examples_test.go):
+
+```powershell
+$env:CODEX_MEM_REFRESH_CLEANUP_EXAMPLES = "filtered-cleanup-json"
+go test ./internal/app -run TestRefreshCleanupFollowImportsExampleFixtures
+Remove-Item Env:CODEX_MEM_REFRESH_CLEANUP_EXAMPLES
+
+$env:CODEX_MEM_REFRESH_AUDIT_EXAMPLES = "filtered-audit-json"
+go test ./internal/app -run TestRefreshAuditFollowImportsExampleFixtures
+Remove-Item Env:CODEX_MEM_REFRESH_AUDIT_EXAMPLES
+```
+
+Then rerun `go test ./internal/app -run "Test(Audit|Cleanup)FollowImportsExampleOutputsStayInSync"` plus the normal repo checks so the updated hygiene fixtures are verified in read-only mode again.
 
 The default text summary from `scripts/readiness-check` echoes the `doctor.follow_imports` fields as flat `doctor_follow_imports_*` lines so CI or local automation can inspect last-known runtime watch health from the existing sidecar without having to parse the full doctor JSON again. The helper also emits explicit overall `started_at`, `completed_at`, and `duration_ms` fields plus per-phase `phase_*_status`, `phase_*_summary`, and timing lines for the `doctor`, stdio smoke, and HTTP smoke phases, so a failed run still tells automation which phase stopped progress and how long both the whole run and each attempted phase took before the command exits non-zero. `--json` returns one structured summary object that embeds the parsed doctor report, compact stdio/HTTP smoke-test summaries, and the same overall plus per-phase timing results. `--keep-going` keeps attempting later phases after an earlier failure, which is useful when you want one failing run to still capture as much phase state as possible. `--slow-run-ms` and `--slow-phase-ms` add explicit readiness warnings to both text and JSON output when thresholds are exceeded, `--fail-on-warning-code` lets automation promote selected warning codes, including nested doctor follow-health warning codes, into a failed readiness result, and `--policy-profile` expands a small set of documented presets into those same underlying options while still exposing the final thresholds and warning-policy state in the output. In all modes the follow-health fields are informational by default unless your own automation explicitly chooses to gate on them.
 

docs/go/operator/import-ingestion.md

@@ -183,10 +183,6 @@ Useful flags:
   `cleanup-follow-imports` and `audit-follow-imports` only. Optional. Repeats or accepts comma-separated glob patterns that remove checkpoint and retry-artifact candidates from the matched set after includes are considered. Excludes win over includes.
 - `--retention-profile stale|daily|reset`
   `cleanup-follow-imports` and `audit-follow-imports` only. Optional. Expands to a documented default age threshold instead of making you spell out `--older-than` every time. `stale` means `1h`, `daily` means `24h`, and `reset` means `0s`. An explicit `--older-than` still overrides the profile.
-- `--list-examples`
-  `cleanup-follow-imports` only. Maintainer-oriented. Lists the checked-in cleanup sample fixture names and relative paths.
-- `--refresh-examples[=<name[,name...]>]`
-  `cleanup-follow-imports` only. Maintainer-oriented. Rewrites the checked-in cleanup sample outputs under `internal/app/testdata`. Run it from the repository root, or pass `--cwd <repo-root>` first; omit the value to refresh every fixture or pass one or more names to refresh only a subset.
 
 ## Event Schema
 
@@ -270,18 +266,41 @@ Checked-in sample outputs for common cleanup flows live under [../../../internal
 
 - [cleanup-follow-imports-daily-dry-run.txt](../../../internal/app/testdata/cleanup-follow-imports-daily-dry-run.txt)
 - [cleanup-follow-imports-filtered-cleanup.json](../../../internal/app/testdata/cleanup-follow-imports-filtered-cleanup.json)
+- [audit-follow-imports-daily-audit.txt](../../../internal/app/testdata/audit-follow-imports-daily-audit.txt)
+- [audit-follow-imports-filtered-audit.json](../../../internal/app/testdata/audit-follow-imports-filtered-audit.json)
 
-If a deliberate cleanup-output change makes those fixtures drift, refresh them from the repository root with:
+If a deliberate output change makes those fixtures drift, refresh the cleanup fixtures from the repository root through the test-only maintainer helper:
 
 ```powershell
-codex-mem.exe cleanup-follow-imports --refresh-examples
+$env:CODEX_MEM_REFRESH_CLEANUP_EXAMPLES = "all"
+go test ./internal/app -run TestRefreshCleanupFollowImportsExampleFixtures
+Remove-Item Env:CODEX_MEM_REFRESH_CLEANUP_EXAMPLES
 ```
 
-If you only need one fixture while iterating on a specific report shape, first list the available names and then refresh just that subset:
+Refresh the audit fixtures the same way:
 
 ```powershell
-codex-mem.exe cleanup-follow-imports --list-examples
-codex-mem.exe cleanup-follow-imports --refresh-examples=filtered-cleanup-json
+$env:CODEX_MEM_REFRESH_AUDIT_EXAMPLES = "all"
+go test ./internal/app -run TestRefreshAuditFollowImportsExampleFixtures
+Remove-Item Env:CODEX_MEM_REFRESH_AUDIT_EXAMPLES
+```
+
+If you only need one fixture while iterating on a specific report shape, pass a comma-separated fixture-name subset instead of `all`:
+
+```powershell
+$env:CODEX_MEM_REFRESH_CLEANUP_EXAMPLES = "filtered-cleanup-json"
+go test ./internal/app -run TestRefreshCleanupFollowImportsExampleFixtures
+Remove-Item Env:CODEX_MEM_REFRESH_CLEANUP_EXAMPLES
+
+$env:CODEX_MEM_REFRESH_AUDIT_EXAMPLES = "filtered-audit-json"
+go test ./internal/app -run TestRefreshAuditFollowImportsExampleFixtures
+Remove-Item Env:CODEX_MEM_REFRESH_AUDIT_EXAMPLES
+```
+
+The fixture names live in [follow_examples_test.go](../../../internal/app/follow_examples_test.go), and the ordinary read-only guard remains:
+
+```powershell
+go test ./internal/app -run "Test(Audit|Cleanup)FollowImportsExampleOutputsStayInSync"
 ```
 
 ## Operational Notes