From 4b7b50981bd90102721c7c1f6b3eb6f98224b613 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Sat, 16 May 2026 23:21:45 -0500 Subject: [PATCH] Add .gocache to .gitignore and minor documentation cleanup --- .gitignore | 3 +++ report-gemma4.md | 31 --------------------------- report.md | 54 ------------------------------------------------ 3 files changed, 3 insertions(+), 85 deletions(-) delete mode 100644 report-gemma4.md delete mode 100644 report.md diff --git a/.gitignore b/.gitignore index bd5973e..072e8ab 100644 --- a/.gitignore +++ b/.gitignore @@ -22,6 +22,9 @@ AGENTS.md # Dependency directories (remove the comment below to include it) # vendor/ +# Go cache +.gocache + # Go workspace file go.work go.work.sum diff --git a/report-gemma4.md b/report-gemma4.md deleted file mode 100644 index 841b80c..0000000 --- a/report-gemma4.md +++ /dev/null @@ -1,31 +0,0 @@ -# Narratio UX Evaluation Report - -## 1. Executive Summary -Narratio has a functional core pipeline with robust S3 integration for input and output, but it currently falls short of the intended "minimalist" operator UX. The primary gaps are the lack of session configuration discovery, the absence of session template support (and the `--session-id` flag), and the missing local cleanup logic. While the pipeline runs successfully, the operator must currently provide explicit session file paths for every run. - -## 2. Feature Matrix - -| Feature | Status | Evidence | Tests | Documentation | Notes | -| :--- | :--- | :--- | :--- | :--- | :--- | -| **Pipeline Config Discovery** | Implemented | `internal/app/pipeline_config_path_test.go` | Yes | Accurate | Checks `/usr/local/etc` and `/etc`. | -| **Session Config Discovery** | Missing | `internal/app/run.go:30` | N/A | Stale | `--session` is mandatory. | -| **Session Templates** | Missing | `internal/config/load.go` | N/A | Missing | No variable interpolation in `session.yml`. | -| **`--session-id` CLI Flag** | Missing | `cmd/narratio` | N/A | Missing | Not implemented in CLI. | -| **Minimal Seriatim Config** | Implemented | `internal/config/load.go` | Yes | Accurate | Defaults for timeout/schema provided. | -| **Minimal Audita Config** | Implemented | `internal/config/load.go` | Yes | Accurate | Defaults for base_url/model provided. | -| **S3 Audio Input** | Implemented | `internal/stage/prepare.go` | Yes | Accurate | Supports `.flac` downloads from S3. | -| **S3 Archive & Promotion** | Implemented | `internal/stage/archive.go` | Yes | Accurate | Correct paths and commit markers. | -| **Local Cleanup** | Missing | `architecture.md:136` | No | Stale | Config exists, logic is not implemented. | - -## 3. Current Happy Path -The shortest command that works today is: -`narratio run --session ` -*(Assuming `pipeline.yml` is present in `/etc/narratio/` or `/usr/local/etc/narratio/`)*. - -## 4. Gaps to Intended UX -1. **Session Discovery & Templates (High):** The requirement to pass `--session` and the inability to use `--session-id` with a template is the largest friction point for operators. -2. **Local Cleanup (Medium):** Spool and work directories are not cleaned up after successful archival, leading to local disk growth. -3. **Local Pipeline Config (Low):** Narratio does not check `./pipeline.yml`, requiring users to use `--config` or move files to system directories. - -## 5. Recommended Next Implementation Prompt -"Implement session configuration discovery and template support. Specifically: 1) Add a search order for `session.yml` (e.g., `./session.yml`, `/etc/narratio/session.yml`) if `--session` is omitted. 2) Implement the `--session-id` CLI flag. 3) Add variable interpolation to `session.yml` so that `{{session_id}}` can be replaced by the value from the flag or the discovered session config before YAML decoding." diff --git a/report.md b/report.md deleted file mode 100644 index df901bb..0000000 --- a/report.md +++ /dev/null @@ -1,54 +0,0 @@ -## 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 ` 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.