weatherreporter/docs/roadmap/implementation.md

# Stateless Execution Implementation Plan

Status: Complete.

## Purpose

This plan implements the accepted [Stateless Execution
Roadmap](ephemeral-state.md). The roadmap is authoritative for product intent,
policy choices, and the desired end state. This document records the completed
migration and records the remediation work completed during post-implementation
review.

Stages 1-18 are complete and are summarized below.

## Implementation Rules

1. Keep the repository buildable and `go test ./...` passing after every stage.
2. Follow all policies under `docs/policy/`, especially the architecture,
   documentation, and risk-based testing requirements.
3. Preserve the accepted stateless contracts: no application-owned durable
   workspace, no local Recent Changes comparison, one operator-owned output per
   successful report, atomic publication, and explicit-only prompt debug
   capture.
4. Preserve prompt and profile inspection before weather collection, exact
   prompt versions, structured-output validation, repository-owned rendering,
   deterministic report periods, batch membership, and Distributor upload of
   published Markdown files.
5. Keep default tests deterministic and offline. Do not contact live Weather
   API, Promptkit provider, or Distributor services.
6. Use behavior-focused regression tests at the narrowest stable boundary.
   Avoid tests that merely encode private helper structure or call order.
7. Update canonical documentation in the same stage as any user-visible or
   architectural behavior change. Do not create release notes until a release
   version is selected.
8. Do not modify or reinterpret the Accepted stateless-execution ADR. A changed
   architectural decision would require a new ADR; the remaining work does not
   require one.

## Fixed Remediation Decisions

The following decisions are complete and require no further product input:

- A canceled generation must not publish or replace its selected output if
  cancellation is observable before atomic publication begins.
- A batch must validate every planned report destination before starting any
  report's Promptkit execution or output publication. Dynamic Daily
  destinations may be validated after weather collection and batch planning,
  because those dates are not known earlier.
- `BatchResult.Total`, `Succeeded`, and `Failed` count reports only. A batch
  notification failure changes overall batch status and exit behavior through
  the top-level notification result; it does not increment `Failed`.
- Batch report items do not expose per-report notification fields because batch
  reports deliberately suppress per-report notification.
- Completed roadmap prose must distinguish the former persistent architecture
  from current stateless behavior, and repository hygiene must no longer hide
  an accidentally recreated root-level `workspace` directory.

## Completed Stages

### Stage 1: Record The Stateless Architecture Decision — Complete

Added the Accepted ADR recording the stateless transformation pipeline,
operator-owned output boundary, removal of local comparison and historical
inspection, atomic publication, and explicit debug-capture exception.

### Stage 2: Remove Recent Changes From The Prompt Contract — Complete

Removed Recent Changes from prompt input, advanced the data package to
`weatherreporter.data_package.v4`, and advanced all four embedded prompts to
exact version `2.0.0`.

### Stage 3: Delete Dormant Local Comparison Policy — Complete

Removed the local comparison implementation and `recent_change` configuration;
strict configuration loading now rejects the obsolete field.

### Stage 4: Establish The Operator-Owned Output Contract — Complete

Made every successful report publish one atomic Markdown output, added
current-working-directory defaults and explicit destination overrides, and
centralized report output naming.

### Stage 5: Separate Explicit Debug Capture From State — Complete

Moved secure opt-in Promptkit diagnostics into `internal/promptdebug` without
introducing implicit diagnostics or ordinary artifact persistence.

### Stage 6: Remove Notification Persistence — Complete

Removed notification receipts and changed Distributor delivery to consume the
published operator-owned output from the active workflow.

### Stage 7: Replace The Persisted Generation Workflow — Complete

Converted single and batch generation to in-memory orchestration and removed
ordinary persistence of snapshots, prompt packages, generated text, render
contexts, metadata, and managed reports.

### Stage 8: Remove Historical Inspection And Prior Compatibility — Complete

Removed the `inspect` command family, historical lookup, prior-run selection,
and metadata compatibility surfaces.

### Stage 9: Delete The Workspace And State Subsystem — Complete

Removed `internal/state`, workspace configuration, state-only helpers, and
legacy artifact models. Strict loading rejects the obsolete `workspace` stanza.

### Stage 10: Consolidate Stateless Behavioral Coverage — Complete

Replaced state-oriented fixtures with focused offline coverage of generation,
batching, atomic output, partial success, notification ordering, prompt
inspection, summaries, and explicit debug capture.

### Stage 11: Publish User, Operator, And Policy Documentation — Complete

Updated the CLI, operations, architecture, configuration, and documentation
policy owners for stateless operation and manual legacy-workspace cleanup.

### Stage 12: Reconcile Internal And Integration Documentation — Complete

Updated focused internal and integration documents to describe in-memory
orchestration, published-output notification sources, and the absence of
historical inspection.

### Stage 13: Run The Repository Exit Gate — Complete

Ran the complete offline test, race, vet, build, help, formatting, stale-string,
and documentation review gates and marked the initial migration implemented.

## Stage 14: Prevent Publication After Cancellation — Complete

### Goal

Close the cancellation window between successful Promptkit execution and
atomic output publication.

### Work

1. In the report workflow, check the active context after validation and
   rendering have completed and immediately before calling the atomic file
   writer.
2. If `ctx.Err()` is `context.Canceled`, wrap it in a
   `promptexec.Canceled` error; if it is `context.DeadlineExceeded`, wrap it in
   a `promptexec.DeadlineExceeded` error. Return that classified error through
   the existing report-error surface. Preserve `errors.Is` behavior for the
   underlying context error; do not collapse either case into a generic
   rendering or output error.
3. Do not remove an output that was published before a later cancellation.
   Cancellation observed after publication remains subject to the existing
   notification and result behavior.
4. Add a focused app regression test whose fake executor returns valid output
   but cancels the context before returning. Prove that generation fails and a
   pre-existing destination remains byte-for-byte unchanged. This test must not
   depend on the fake executor voluntarily returning a cancellation error.
5. Ensure the same workflow check protects every single-report and batch item;
   do not add duplicate cancellation logic in CLI or batch orchestration.

### Tests

Run:

```sh
go test ./internal/app
go test ./...
go test -race ./internal/app
git diff --check
```

### Exit Gate

Cancellation observable before publication prevents the atomic write, the
selected destination remains unchanged, and cancellation identity is retained.

## Stage 15: Preflight Every Planned Batch Output — Complete

### Goal

Ensure a structural destination error cannot appear midway through a batch
after earlier reports have already been published.

### Work

1. After weather collection and `planBatchRun` have produced the complete
   dynamic report set, resolve and validate the output path for every planned
   report before executing the first report prompt.
2. Store each validated absolute output path with its planned report for use by
   the generation loop. Do not recompute or revalidate destinations inside the
   loop.
3. Treat any invalid path, including an existing directory at a report's final
   filename, as a batch preflight error. Return before Promptkit execution and
   before publication of any batch item. Weather collection may already have
   occurred because eligible Daily dates depend on collected coverage.
4. Keep missing parent-directory creation in the atomic publication helper;
   preflight must not create report files or introduce a new managed directory
   lifecycle.
5. Add a focused app test using a real temporary output directory where a later
   planned filename, such as `tomorrow.md`, already exists as a directory.
   Assert that prompt inspection still occurs before collection, the executor's
   prompt-execution method is never called, and no earlier report output is
   created or replaced.
6. Retain the existing independent report-failure behavior after successful
   preflight: a provider, validation, rendering, or publication failure for one
   report remains an item failure, later items continue, and successful outputs
   remain available.

### Tests

Run:

```sh
go test ./internal/app
go test ./internal/fileutil
go test ./...
git diff --check
```

### Exit Gate

Every selected batch destination is validated before any batch report executes,
and a destination collision cannot yield an unreported partial batch.

## Stage 16: Separate Report Counts From Batch Notification Status — Complete

### Goal

Restore coherent batch counters while preserving failed status and non-zero
exit behavior when the batch notification fails.

### Work

1. Define and enforce the invariant
   `Total == Succeeded + Failed == len(Reports)` after report execution.
   `Succeeded` and `Failed` count only report-item statuses.
2. Remove the increment of `BatchResult.Failed` when `notifyBatch` returns an
   error. Preserve the failed top-level `BatchNotificationResult`, including
   its safe error and identity fields.
3. Update the `RunBatch` wrapper to return `BatchError` when either a report
   failed or the top-level batch notification failed. Keep
   `RunBatchDetailed` returning the populated result according to its existing
   detailed-result contract.
4. Retain CLI behavior in which the batch summary status is failed and the
   command exits unsuccessfully for a batch notification failure, even though
   all report counters show success.
5. Make `BatchError` use report counts only for report-failure wording and its
   existing notification-specific wording when the reports succeeded but the
   notification failed.
6. Add focused app and CLI tests for a batch whose reports all publish
   successfully but whose batch notifier fails. Assert:
   - `Total == Succeeded == len(Reports)` and `Failed == 0`;
   - every output remains present;
   - the top-level notification status is `failed`;
   - the summary status is `failed`;
   - the returned error describes notification failure rather than claiming a
     report failed; and
   - the action exits unsuccessfully.

### Tests

Run:

```sh
go test ./internal/app ./internal/cli
go test ./...
git diff --check
```

### Exit Gate

Batch report counters are internally consistent, while notification failure
still produces a failed summary, safe diagnostic, retained outputs, and
non-zero command result.

## Stage 17: Remove Impossible Per-Report Notification State — Complete

### Goal

Align batch result types and stderr output with the architecture in which
per-report notification is suppressed and delivery is represented once at the
batch level.

### Work

1. Remove `NotificationStatus`, `NotificationRunID`,
   `NotificationPipelineID`, and `NotificationError` from
   `BatchReportResult`.
2. Remove the unreachable copying of `ReportResult.Notification` into a batch
   item. Rename `copyBatchReportPaths` to reflect that it copies the current
   safe report result fields rather than only paths, or replace it with an
   equally clear narrow helper.
3. Remove per-report notification formatting from `writeBatchStatus`. Keep the
   top-level `batchNotification` status line and the batch summary
   `notification` object unchanged.
4. Search tests and documentation for the removed per-report fields. Delete
   stale assertions or descriptions rather than adding compatibility fields;
   no backward compatibility is required for this pre-release result cleanup.
5. Retain single-report notification fields and behavior. This stage changes
   only batch report items.

### Tests

Run:

```sh
go test ./internal/app ./internal/cli
go test ./...
git diff --check
```

### Exit Gate

Batch items expose only report-generation facts, and all batch delivery state
is represented by the single top-level notification result.

## Stage 18: Reconcile Documentation And Run The Remediation Exit Gate — Complete

### Goal

Remove the remaining documentation and repository-hygiene traces of the former
workspace architecture and verify the remediated implementation as a whole.

### Work

1. In `docs/roadmap/ephemeral-state.md`, rename `Current State` to
   `Former State`, convert its description of persistence and Recent Changes to
   past tense, and reconcile other implementation-future phrasing with the
   roadmap's Implemented status. Preserve the roadmap's product intent and
   desired end state; do not turn it back into a staged plan.
2. Remove the root-level `/workspace` ignore rule from `.gitignore` and update
   its adjacent comment. Legacy workspace cleanup remains an explicit operator
   procedure in `docs/operations.md`; removing the ignore rule must not delete
   any operator data or add automated cleanup.
3. Review the canonical CLI, operations, architecture, app-orchestration, and
   testing documentation for the Stage 14-17 behavior. Update only documents
   whose owned contract changed, avoiding duplicate definitions.
4. Search production code, tests, examples, and current-state documentation
   for:
   - stale per-report batch notification fields;
   - report counters that include notification failures;
   - output validation performed inside the batch execution loop;
   - claims that cancellation can publish an output;
   - present-tense descriptions of the removed workspace; and
   - active ignore rules or defaults that conceal a workspace tree.
5. Confirm ordinary generation and batch tests use isolated temporary
   directories and leave only the selected Markdown outputs unless explicit
   prompt debug capture is requested.
6. Run formatting and all repository validation gates. Review the complete
   remediation diff for unrelated changes, content leakage, compatibility
   shims, and unnecessary abstractions.
7. When every exit gate passes, mark Stages 14-18 and this plan Complete. Keep
   the feature roadmap marked Implemented. Do not create, tag, or publish a
   release in this plan.

### Tests

Run:

```sh
git diff --name-only --diff-filter=ACM -- '*.go' | xargs -r gofmt -w
go test ./...
go test -race ./...
go vet ./...
go build ./...
go run ./cmd/weatherreporter --help
git diff --check
```

Verify all changed repository-relative documentation links resolve and inspect
`git status --short` for an accidentally created root-level `workspace` tree.

### Exit Gate

The remediated stateless workflow honors cancellation before publication,
preflights complete batch destinations, reports coherent batch counts, exposes
only reachable notification state, and has documentation and repository
hygiene consistent with the implemented architecture.

## Open Questions

None. The roadmap, accepted ADR, and remediation decisions above provide all
product and architectural choices required to implement Stages 14-18.