narratio/report.md

1. Executive Summary

Narratio is close on S3 input/archive mechanics but not yet close on the intended minimal operator UX. Core S3 workflow is implemented (prepare S3 audio download, archive run upload, promotions, current pointers), but key UX items are missing: no --session-id flag, no session auto-discovery, and no session template variable injection. Cleanup/retention for spool/workdirs after archive is also still future work.

2. Feature Matrix

Feature	Status	Evidence	Tests	Documentation status	Notes
Pipeline config auto-discovery when --config omitted	Implemented	internal/app/pipeline_config_path.go, internal/config/defaults.go	internal/app/pipeline_config_path_test.go, internal/app/commands_test.go	Accurate in README.md, architecture.md	Order: /usr/local/etc/narratio/pipeline.yml, then /etc/narratio/pipeline.yml; no ./pipeline.yml default
Session config auto-discovery when --session omitted	Missing	--session required in internal/app/run.go, plan.go, resume.go, run_stage.go	Covered by missing-flag tests in internal/app/commands_test.go	Accurate (docs do not claim auto-discovery)	No precedence order exists for session file search
Session template variables in session.yml	Missing	Strict decode path in internal/config/load.go + strict YAML behavior	No template tests found	Not documented as implemented	No render-before-decode templating mechanism found
--session-id CLI injection	Missing	No --session-id flag in command parsers (run/plan/resume/run-stage)	No tests for --session-id	Not documented as implemented	Intended minimal UX command not currently supported
Campaign/run-aware work+spool paths	Implemented	internal/artifacts/paths.go, usage in prepare/archive	Path/helper tests in internal/artifacts + stage tests	Documented in README/architecture/roadmap	Layout includes {campaign}/{session_id}/{run_id}
Run ID generation format	Implemented	internal/artifacts/run_id.go	Run ID tests in internal/artifacts	Documented	UTC timestamp + random suffix format present
Storage backend abstraction	Implemented	internal/adapters/storage/object_store.go	Storage backend tests in internal/adapters/storage	Documented in README/architecture	Narrow interface (List/Download/Upload/Exists)
S3 backend + fake backend	Implemented	internal/adapters/storage/s3_backend.go, fake.go	Adapter tests pass without live S3	Documented	No AWS creds in config schema/examples
Prepare S3 audio input (inputs.audio_s3)	Implemented	internal/stage/prepare.go	internal/stage/prepare_test.go	Documented in docs/s3-audio-input.md, README, architecture	Lists prefix, filters .flac, downloads/materializes, fails on none
Local audio workflow	Implemented	Prepare logic still supports audio_dir/audio_files	Prepare tests cover local behavior and conflict with audio_s3	Documented	Local+S3 conflict is enforced
Manifest provenance for S3 audio	Implemented	S3 source metadata assignment in prepare stage	Covered by S3 prepare tests	Documented	ETag recorded as metadata, not checksum
Archive run upload under runs/{run_id}	Implemented	internal/stage/archive.go	internal/stage/archive_test.go	Documented in docs/archive-storage.md, README, architecture	Successful/completed runs only
Archive promotion rules	Implemented	Archive stage promotion handling	Archive tests cover required/optional/mapping behavior	Documented	Default promoted outputs: transcripts/trimmed.json, artifacts/session_recap.md
current/manifest.json + current/run_id.txt last	Implemented	Archive stage upload order logic	Archive tests verify ordering and pointer content	Documented	current/run_id.txt is commit marker; written last
Avoid upload of failed/incomplete runs	Implemented	Archive prerequisite checks	Archive tests cover prerequisite failure path	Documented	Failed runs stay local
Spool/workdir cleanup after successful archive	Missing	spool.delete_audio_after_archive exists but no cleanup behavior in stages/app	No cleanup behavior tests found	Docs accurately call cleanup future work	Gap vs intended UX item 12
Minimal Seriatim config	Partial	Validation requires seriatim.binary; defaults fill timeout/schema/gap	Config load/validate tests	Docs mostly accurate	“Binary-only” works after defaults, but still validated post-defaults
Minimal Audita config	Partial	Validation requires audita.binary and audita.model; defaults for timeout/base_url/etc in loader	Config tests in internal/config	Docs currently list timeout/base_url as required in README section	UX expectation “binary + llm_api_key_env only” does not hold because model is required

3. Current Happy Path

Shortest realistic command today is:

narratio run --session /path/to/session.yml

That works only if pipeline config is discoverable at /usr/local/etc/narratio/pipeline.yml or /etc/narratio/pipeline.yml. Otherwise minimum is:

narratio run --config /path/to/pipeline.yml --session /path/to/session.yml

narratio run --session-id 2026-04-04 does not work today (flag not implemented).

4. Gaps to Intended UX

1. Missing --session-id flow with session template injection (largest UX gap).
2. No session config auto-discovery order when --session is omitted.
3. No session template rendering engine / unresolved-variable handling.
4. Cleanup policy not implemented (spool.delete_audio_after_archive is modeled only).
5. Audita minimal config UX still stricter than intended (model required).
6. Optional doc refinement: explicitly call out that ./pipeline.yml is not in current default search order.

5. Recommended Next Implementation Prompt

Implement session template and --session-id UX only:

Add session discovery and template rendering support so narratio run --session-id <id> works with no --session in normal setups. Requirements: define deterministic session discovery order; support rendering template variables in session.yml before strict YAML decode; inject CLI --session-id into template variables; fail clearly on unresolved variables; preserve strict field validation after render; keep existing --session explicit path behavior; add tests for discovery precedence, render success/failure, and CLI integration; update README/architecture/examples accordingly; do not change archive/prepare storage behavior.

Validation note: go test ./... passes for the inspected state.