Rewrite operations and state documentation

docs/internal/state.md

@@ -2,7 +2,8 @@
 
 This document describes the implementation collaborators behind output, cache,
 and debug state. User-visible fields belong in [Configuration](../config.md),
-and layouts and lifecycle belong in [Operations](../operations.md).
+and physical layout, retention, recovery, reason codes, and cleanup belong in
+[Operations](../operations.md).
 
 ## Composition
 
@@ -12,6 +13,12 @@ constructs cache collaborators, writes logical output files, and reports paths.
 Pipeline modules receive interfaces and request data, never output, cache, or
 debug roots.
 
+The CLI creates no chunk-plan store in bypass mode. It creates a checkpoint
+recorder only when recording is enabled and a checkpoint loader only for a
+resume invocation. It allocates debug state only after a safe run identity has
+been generated and only when debug capture was requested. These choices keep
+the three state families independently composable.
+
 ## Output And Cache
 
 The pipeline runner returns logical output files. After validating every
@@ -68,12 +75,19 @@ names only the step, lane, and stable reason code. Decision detail is selected
 from code-owned descriptions by reason code and then UTF-8 normalized and
 bounded; callers cannot supply arbitrary diagnostic prose. Typed categories and
 codes remain intact through pipeline events and become strings only in manifest
-and debug-summary JSON. [Operations](../operations.md#resume-and-selective-recompute)
-is the canonical operator-facing reason-code reference.
+and debug-summary JSON.
+[Operations](../operations.md#checkpoint-recording-resume-and-recompute) is the
+canonical operator-facing reason-code reference.
 
 `internal/core/fileio` provides confined atomic file writes used by state
 collaborators. The chunk-plan store retains its stronger entry validation.
 
+The CLI constructs selective-recomputation policy from resolved generated
+artifact dependencies. It forces the selected step and transitive consumers,
+while marking unforced producers as required reusable inputs. The runner owns
+the actual hydration and rejection decisions; the [Operations guide](../operations.md#checkpoint-recording-resume-and-recompute)
+owns the operator workflow and stable reason-code meanings.
+
 ## Debug Bundles
 
 `internal/core/debugbundle` allocates an explicitly requested per-run bundle
@@ -98,12 +112,27 @@ operation writes the success report, or makes one attempt each to write the
 failure report and error log. Terminal persistence failures are reported
 separately and never replace the command's primary error.
 
+## Invariants To Preserve
+
+- Modules receive state collaborators and request data, never physical roots.
+- Output logical paths are validated before a run directory is allocated, and
+  files are atomically written within that directory.
+- Chunk-plan publication occurs only for accepted plans; bypass does not
+  construct or touch a plan store.
+- Checkpoint recording and checkpoint loading remain separate collaborators.
+- Debug state is opt-in, is not cache input, and terminal reporting does not
+  obscure the command's primary failure.
+
 ## Tests To Inspect
 
 - `internal/cli/run_contract_test.go`: command-owned state allocation,
   terminalization, and output/report boundaries.
+- `internal/cli/cache_contract_test.go`: cache-mode precedence, root selection,
+  and resume collaborator construction.
 - `internal/cli/state_hardening_test.go`: independent roots, reuse, failures,
   permissions, cleanup, and redaction.
+- `internal/cli/recompute_policy_test.go`: forced dependents and required
+  reusable predecessors for selective recomputation.
 - `internal/cli/recompute_execution_contract_test.go`: selective recomputation,
   filesystem recovery, deterministic decisions, and failed predecessor state.
 - `internal/cli/production_contract_test.go`: production composition and