State Management
State derivation from filesystem — no tracking files, idempotent operations, scan-based status
Tags
Overview
Purpose
State derivation from filesystem — no tracking files, idempotent operations, scan-based status
Rules
STM-001: NO state/status tracking files. State is derived by scanning filesystem structure.
Tracking files drift from reality. Filesystem IS reality — derived state is always consistent with actual artifacts.
Verification: Grep for state/status files in entity directories. None should exist — state comes from scanning.
STM-002: All operations must be idempotent — running twice produces same result.
Idempotent operations are safe to retry and compose. Non-idempotent operations create ordering dependencies and partial-failure risks.
Verification: Test: run operation twice in sequence. Second run produces identical output and no side effects.
STM-003: Use order (number) + suborder (string, optional) for parallel execution.
Numeric ordering enables deterministic sequencing. String suborders enable parallel items at the same order level.
Verification: Schema review: ordered entities have order (int) and optional suborder (string) fields.
STM-004: Step completion = output artifacts exist. Pipeline scans filesystem for status.
Completion is an observable property, not a declared one. If the output exists, the step is complete. If not, it isn't.
Verification: Pipeline logic: completion checks test for artifact existence, not status flags.