narratio/docs/roadmap/cleanup.md

Roadmap: Pre-1.0 Code Cleanup

Status: Planned

This roadmap turns the remaining findings in docs/roadmap/audit.md into decision-complete implementation stages. It follows the policy documents under docs/policy/ and preserves current public CLI, config, storage layout, manifest, and stage behavior unless a stage explicitly says otherwise.

Goals

• Reduce repeated path, file, source-policy, and read-only inspection logic before 1.0.
• Keep Narratio explicit, stage-driven, and easy to review.
• Keep storage adapters free of campaign/session/run/root-prefix semantics.
• Keep command output text-only and command-specific.
• Keep implementation changes small enough for focused prompts and focused tests.

Non-Goals

• Do not introduce a generic workflow engine or DAG abstraction.
• Do not introduce a generic CLI framework.
• Do not introduce a broad manifest abstraction.
• Do not move secret loading into storage adapters.
• Do not make storage adapters infer Narratio path or key semantics.
• Do not add compatibility aliases for retired archive/promote, campaign, transcript, or previous-session source names.
• Do not move restore's remote-key include/exclude policy out of restore unless another caller is added.

Stage 1: Path and File Mechanics

Add shared mechanics for root-scoped path safety and atomic file operations.

Implementation decisions:

• Add root-scoped helpers in internal/pathsafe:
  • join a slash-style relative path safely under a root;
  • derive a safe slash-style relative path from a path under a root;
  • reject empty paths, absolute paths, traversal, and paths outside the root.
• Add a small dependency-light internal/fileops package for shared file installation mechanics:
  • atomic byte write;
  • atomic file copy;
  • atomic file copy with SHA-256 checksum;
  • install an already-downloaded temp file with permissions.
• Prefer internal/fileops over extending artifacts.LocalStore, because the same mechanics are used by app, stage, audio, artifacts, and manifest code.
• Keep higher-level semantics local:
  • restore decides which remote keys are in scope;
  • audio decides cache hit/miss behavior;
  • manifest decides JSON marshaling and validation;
  • stages decide canonical output materialization.

Implementation targets:

• Replace duplicate root-escape checks in restore planning, run-local output handling, previous-cache path conversion, and artifact local path helpers where doing so keeps behavior identical.
• Replace duplicate temp-write/copy/rename mechanics in artifact local store, audio cache materialization, restore execution, and prepare helpers where the call site can keep its current error context.
• Leave manifest save behavior unchanged if sharing it would obscure manifest-specific validation or error text.

Tests:

• go test ./internal/pathsafe -v
• go test ./internal/audio -v
• go test ./internal/app -run Restore -v
• go test ./internal/stage -run Prepare -v
• go test ./...

Acceptance criteria:

• Root escape, absolute path, empty path, Windows separator, and valid relative path cases are covered by path-safe tests.
• Atomic helper tests prove temp files are cleaned up on failure and checksums match final file contents.
• Restore, prepare, and audio cache behavior remain unchanged.

Stage 2: Artifact Source Policy

Finish centralizing artifact source vocabulary and validation in internal/artifactpolicy.

Implementation decisions:

• Extend internal/artifactpolicy with Scriptorium-input policy helpers:
  • classify and validate built-in, configured, and previous-session source IDs;
  • validate referenced configured artifact keys against the configured artifact set;
  • expose a previous-session source descriptor for callers that need the configured artifact key.
• Keep runtime artifact lookup in internal/artifacts.
• Keep missing, required, optional, and operator-guidance behavior at call sites:
  • config validation still produces field-specific errors;
  • analyze still decides whether missing inputs fail or skip;
  • previous-cache planning still decides required vs optional behavior.
• Do not make artifactpolicy inspect manifests, files, object storage, or runtime catalogs.

Implementation targets:

• Replace source parsing and static built-in checks in config validation with artifactpolicy helpers.
• Update analyze input resolution to consume the shared classification/descriptors while preserving current error messages and required/optional behavior.
• Update previous-cache planning to use shared previous-session source descriptors where source vocabulary is involved.
• Keep publish output destination derivation through artifactpolicy.ResolvePublishedDestination.

Tests:

• go test ./internal/artifactpolicy -v
• go test ./internal/config -v
• go test ./internal/stage -run Analyze -v
• go test ./internal/previouscache -v
• go test ./...

Acceptance criteria:

• Valid Scriptorium input source cases pass through one shared policy path.
• Invalid source format and unknown configured artifact references keep clear config-field errors.
• Analyze behavior for required/optional built-in, configured, and previous-session sources is unchanged.
• Previous-cache candidate ordering and required/optional behavior are unchanged.

Stage 3: Read-Only Inspection Layer

Extract shared read-only session inspection checks for session validate and session status.

Implementation decisions:

• Keep the new inspection helpers in internal/app; they are command orchestration helpers, not stage or storage adapter behavior.
• Create small result types for checks, but do not create a generic reporting framework.
• Keep command-specific rendering local:
  • session validate renders findings and fails on ERROR;
  • session status renders state and does not fail for missing local/remote state unless config loading fails.
• Do not download artifact bodies for inspection unless current behavior already does so.

Implementation targets:

• Extract stable input checks from operator_findings.go into a reusable inspection helper.
• Extract local and remote audio presence checks that mirror prepare's selection rules without materializing audio.
• Extract previous-session readiness checks using existing current-state and previous-cache planning mechanics where possible.
• Extract effective lock and remote current-state inspection into reusable command helpers.
• Keep artifact catalog rendering separate from these checks.

Tests:

• go test ./internal/app -run 'SessionValidate|Status' -v
• go test ./internal/previouscache -v
• go test ./internal/stage -run Prepare -v
• go test ./...

Acceptance criteria:

• session validate and session status agree on local/remote audio and previous-session readiness facts.
• Missing current run pointer/manifest behavior remains command-appropriate: validation reports an error; status reports unavailable state.
• Existing lock and remote current-state behavior is unchanged.

Stage 4: Optional CLI Edge Cleanup

Only implement this stage if Stage 1-3 leave meaningful repeated parser code.

Implementation decisions:

• Add at most one small parser helper for commands with session_id plus one additional positional argument.
• Use it for session locks add and session locks remove if it reduces duplication without obscuring syntax.
• Keep command handlers explicit.
• Do not change public syntax, flag names, help text meaning, or error semantics.

Tests:

• go test ./internal/app -run 'Session|Locks|RunStage' -v
• go test ./...

Acceptance criteria:

• Positional session_id and --session-id mismatch errors remain unchanged.
• Missing source arguments for lock add/remove remain clear.
• No new command aliases are introduced.

Stage 5: Final Sweep

Run final validation after the implementation stages.

Required searches:

• rg -n "archive|promote|promoted|promotion" internal docs examples cmd
• rg -n "narratio.transcript.merged|narratio.transcript.full|narratio.transcript.trimmed" internal docs examples
• rg -n "previous_session_artifact|promote_artifacts|pipeline.archive" internal docs examples
• rg -n "CreateTemp|Rename|copyFileAtomic|WriteFileAtomic|DownloadObjectToTemp" internal

Expected search results:

• Retired terminology should remain only where intentionally historical or where fixture names make it unrelated to current behavior.
• Old transcript and old config/source names should not appear in runtime code, tests, examples, or current-behavior docs.
• File-operation searches should show centralized helpers plus acceptable direct uses where package-specific behavior remains intentional.

Required tests:

• go test ./internal/artifactpolicy -v
• go test ./internal/artifacts -v
• go test ./internal/config -v
• go test ./internal/stage -run 'Analyze|Prepare|Publish' -v
• go test ./internal/app -run 'SessionValidate|Status|Restore|Locks|RunStage' -v
• go test ./internal/previouscache -v
• go test ./internal/audio -v
• go test ./internal/pathsafe -v
• go test ./internal/adapters/storage -v
• go test ./internal/manifest -v
• go test ./...

Roadmap cleanup:

• Mark each completed stage as implemented only after its code, tests, and any internal docs are updated.
• Keep this file as planned work until the implementation stages land.
• Do not update canonical user/operator docs unless implementation changes visible behavior, which this roadmap does not intend.

Assumptions

• Public CLI and config behavior remains unchanged throughout this cleanup.
• internal/fileops is the preferred home for shared atomic file mechanics.
• internal/artifactpolicy remains the source-policy home.
• internal/artifacts remains the path/key/current-state home.
• internal/app remains the command-loading, inspection, and rendering home.
• Stage packages keep stage execution policy and adapter interaction.