Document stateless output operations

docs/policy/architecture.md

@@ -10,9 +10,10 @@ package inventory; focused documents in `docs/internal/` own implementation deta
 
 Weatherreporter is a deterministic weather-report CLI. It collects normalized
 weather data, derives facts and modules, builds a curated YAML data package,
-compares prior snapshots, executes exact-version Promptkit prompts, validates
-structured generated prose, and renders repository-owned Markdown. Completed
-managed Markdown may be uploaded through Distributor.
+executes exact-version Promptkit prompts, validates structured generated prose,
+and renders repository-owned Markdown in memory. Completed Markdown is
+atomically published to an operator-owned output destination and may then be
+uploaded through Distributor.
 
 The supported report products are Daily, Today, Tomorrow, and Hourly. A batch
 collects once, validates its complete candidate prompt/profile set before
@@ -25,14 +26,12 @@ after every planned report succeeds.
 - `internal/cli` owns command parsing, help, summaries, and one executor
   construction per action.
 - `internal/config` owns defaults, loading, validation, and secret loading.
-- `internal/app` owns workflow order, partial results, and notification
-  coordination through project-owned contracts.
+- `internal/app` owns in-memory workflow order, partial results, atomic output
+  publication, and notification coordination through project-owned contracts.
 - Deterministic domain packages own weather derivation, report periods, modules,
   generated-text validation, and template contexts.
 - `internal/adapters/weatherapi`, `internal/adapters/promptkit`, and
   `internal/adapters/distributor` own their external dependency mechanics.
-- `internal/state` owns workspace paths, V2 metadata, atomic persistence, and
-  read-only inspection.
 
 Dependency-specific Promptkit types remain inside its adapter. The application
 does not parse flags, construct provider clients, or render provider output
@@ -41,28 +40,29 @@ directly.
 ## Prompt Execution Invariants
 
 - Prompts receive curated module packages, never unbounded raw weather payloads.
-- Every execution inspects the exact prompt version and output contract before
+- Every execution validates the exact prompt version and output contract before
   collection. The selected profile is configured explicitly or declared by the
   prompt; unsupported direct-key profiles and missing reported credentials fail
   before collection.
-- Prepared execution persists safe preparation provenance before provider work.
-  Completed execution persists safe execution provenance; raw output is
-  validated before template rendering.
+- Prompt and profile validation completes before weather collection. Raw output
+  is validated before template rendering.
 - Generated text fills defined prose slots only. Deterministic facts remain
   authoritative and repository-owned templates produce all managed Markdown.
 - Sensitive rendered prompts, schemas, input bodies, provider endpoints, and
-  credentials never enter normal metadata, summaries, logs, or workspace
-  artifacts. They are written only to an explicit secure debug root when
-  requested.
+  credentials never enter normal summaries or logs. They are written only to
+  an explicit secure debug root when requested.
 
-## State, Notification, And Testing Invariants
+## Output, Notification, And Testing Invariants
 
-- Managed writes are atomic where practical and stay beneath the configured
-  workspace root. Reached artifacts remain inspectable after later failures.
-- New records use `weatherreporter.metadata.v2`; V1 records remain readable for
-  inspection compatibility.
-- Distributor uploads use only the managed Markdown report, never output copies
-  or workspace scans. Notification follows report and final metadata success.
+- Normal execution is stateless: it keeps weather data, prompt input, generated
+  text, and render context in memory and creates no application-owned durable
+  state.
+- Markdown writes are atomic at an operator-selected destination. A
+  pre-publication failure does not replace an existing destination; a
+  notification failure does not remove a newly published output.
+- Distributor uploads use only the published Markdown output, never a scan of
+  local files. Single notification follows publication; batch notification
+  follows publication of every selected report.
 - Default tests are deterministic, offline, and use Promptkit/provider fakes
   rather than live provider calls. See the [testing policy](testing.md).
 

docs/policy/documentation.md

@@ -85,8 +85,8 @@ mechanisms, not secret values.
 | Release procedure | `docs/release.md` | Version policy, release preparation, validation, tagging, automated publication, verification, failure handling, and release ordering. | General contributor workflow, product contracts, release-specific change summaries, and implementation history. |
 | Release notes | `docs/releases/` | One versioned, changelog-style summary for each release, including compatibility and operator action. The file at the tagged commit supplies the corresponding Gitea release body. | Current CLI, configuration, operations, integration, architecture, and internal contracts; release procedure; implementation plans. |
 | CLI contract | `docs/cli.md` | Commands, arguments, flags, invocation semantics, stdout and stderr behavior, summaries, and exit behavior. | Configuration field definitions, complete operating procedures, runtime filesystem layout, and command implementation. |
-| Configuration contract | `docs/config.md` | Discovery and precedence, fields, defaults, secrets, validation rules, and user-selectable values. | Complete example files, CLI syntax, runtime state lifecycle, and loading implementation. |
-| Operations | `docs/operations.md` | Normal workflows, physical workspace layout, artifacts and metadata, inspection, notification behavior, diagnosis, recovery, cleanup, permissions, and operational caveats. | Complete CLI syntax, configuration field definitions, logical external contracts, and implementation mechanics. |
+| Configuration contract | `docs/config.md` | Discovery and precedence, fields, defaults, secrets, validation rules, and user-selectable values. | Complete example files, CLI syntax, output lifecycle, and loading implementation. |
+| Operations | `docs/operations.md` | Normal output handling, atomic replacement, notification behavior, diagnosis, explicit debug capture, manual legacy-workspace cleanup, permissions, and operational caveats. | Complete CLI syntax, configuration field definitions, logical external contracts, and implementation mechanics. |
 | Report template surface | `docs/templates.md` | Implemented template files and partials, render-context fields, editing rules, and maintainer-facing template examples. | Weather derivation, module implementation, generated-text validation internals, and operator procedures. |
 | External and durable integration contracts | `docs/integrations/` | Weather API, Promptkit, Distributor, external formats and protocols, durable logical paths and schemas, compatibility behavior, and upstream or downstream responsibilities. | Physical runtime placement and lifecycle, internal transformations, CLI syntax, and configuration defaults. |
 | Internal subsystem behavior | `docs/internal/` | Implementation flow, internal collaborators and state transitions, package-local guarantees and failures, and relevant tests. | Global architecture invariants, user-facing contracts, external schemas, operator procedures, and future package plans. |
@@ -113,8 +113,8 @@ parallel package or behavior references.
 
 CLI documentation answers how to invoke Weatherreporter and what its command
 interface does. Configuration documentation answers what settings mean.
-Operations answers what happens to runtime state and how to operate or recover
-the application, including diagnosis and safe responses to runtime failures.
+Operations answers how to handle operator-owned outputs and runtime failures,
+including diagnosis, explicit debug capture, and safe legacy cleanup.
 
 When a workflow crosses these topics, place the complete procedure with the
 document that owns the task and link to the other contracts. Do not duplicate

docs/policy/testing.md

@@ -96,8 +96,8 @@ Use each test type where it protects a distinct risk:
 - Integration tests use real deterministic collaborators when correctness
   depends on their interaction, while replacing live or nondeterministic
   external boundaries.
-- App and CLI tests protect representative assembled generation, batch,
-  inspection, persistence, and notification workflows.
+- App and CLI tests protect representative assembled generation, batch, atomic
+  output, and notification workflows.
 - Fixtures must be minimal, synthetic, versioned with the behavior they
   exercise, and free of credentials or private data.
 - Golden files are appropriate only when the complete output is intentionally
@@ -199,9 +199,9 @@ Each behavior should have a clear test owner:
 - Config tests own loading, precedence, defaults, secrets, and validation.
 - Domain tests own weather transformations and invariants.
 - Adapter tests own HTTP, Promptkit/provider, and upload boundaries.
-- Orchestrator tests own workflow ordering, persistence, partial success, and
-  failure propagation.
-- State tests own path derivation, atomic artifacts, lookup, and round trips.
+- Orchestrator tests own workflow ordering, output publication, partial success,
+  and failure propagation.
+- Filesystem tests own atomic writes and destination-preservation behavior.
 - Template and generated-text tests own schemas, render contexts, and rendered
   output contracts.
 
@@ -219,8 +219,8 @@ observation:
 3. Use stubs when a dependency only needs controlled responses.
 4. Use mocks when the interaction itself is contractual.
 
-Mocks are appropriate for requirements such as uploading exactly once, saving
-metadata before notification, propagating cancellation to Promptkit, or
+Mocks are appropriate for requirements such as uploading exactly once,
+notifying only after output publication, propagating cancellation to Promptkit, or
 avoiding an external call after an earlier workflow failure. Do not use mocks
 merely to isolate every object or reproduce the implementation's call graph.