On the beliefs that
do not move.
This document sets down the slow-moving convictions that govern how the work is built, what is written, and how data is made to reach the least-equipped hand.
These are the top-level beliefs that cut across the technical and professional shape of the work. They are slow by design: nothing that changes more than once a quarter shall be set down here.
Constraints shall be encoded in the types.
The System shall make wrong states unrepresentable, and shall not trust where it can prove.
Types catch the errors that conventions cannot. Where a precondition would guard a value, a failable init shall guard it sooner, and the wrong state shall be made impossible to construct.
Internal code shall be trusted. Validation belongs at the boundaries of the System, where user input and external APIs enter; no fallback shall be added for a scenario that cannot occur.
A guard's output shall not be read without a positive control.
Silence from a guard has two readings that look identical: nothing to report, and unable to report.
A denial carries the same ambiguity, for a correct catch and a false positive arrive in the same shape. Neither can be told apart from outside the guard, and so the System may accumulate guards for months while learning nothing from any of them.
Two properties shall make a guard readable, and they are separate. Its arming state shall be observable: whether the guard is live shall be checkable from outside it, and never inferred from the absence of complaints. Its denial shall have been seen: the defect it exists to catch shall be planted, the guard watched as it denies, the plant removed, and the guard watched as it passes. Until both halves have been observed, a report of no findings carries no information at all.
Particular care is owed where the arming condition is a side effect of something else, so that nobody owns turning it on; where a fixture arms what the System itself never arms, so that the test proves the guard works in a world that does not exist; where a long quiet period is read as adherence; and where an instrument's own expected state is recorded nowhere, so that unarmed and armed with nothing to say are the same observation.
Recovery shall come before prevention, and never bundled.
When the root cause of a fault is structural, the remedy shall be split across two changes, and recovery shall ship first.
Recovery shall come first: the System shall detect the bad state at runtime and recover, by wiping and retrying, by falling back to known-good defaults, or by surfacing a specific error. It shall be tightly scoped, low in risk, shall close the pain felt by the user, and shall ship the same day.
Prevention shall come second, as a separate follow-up, restructuring the orchestration, the data flow, or the lifecycle so the fault can no longer be reached. A single change that mixes the two joins concerns of mismatched urgency; bundle them and one side shall suffer. The recovery machinery shall be kept for defence in depth and for users upgrading from earlier builds, and its documentation shall be updated to reflect its changed role.
Only what tests cannot hold shall be documented.
Tests are a record that does not lie; prose drifts because nothing fails loudly when it lies.
When the tests pass, the behaviour holds. Standalone prose carries no such guarantee. Documentation shall therefore be reserved for seam-level invariants: those behaviours that span two features and have no single owner, such as a count staying in sync with a persistence layer after an ingestion event.
Everything else shall be documented by the code that implements it.
External material is inspiration, not doctrine.
Articles, videos, transcripts, and research papers brought into planning are starting points, not received wisdom.
Framings shall be challenged before they are adopted, and stress-tested before they are committed to tickets or to architecture. Particular care is owed where the author sells tooling, consulting, or courses around the framing; where the source is recent and unproven; where it collapses distinct concerns into one concept; or where existing artefacts in the knowledge store already address the problem differently.
Where a source's framing conflicts with what is already in place, the conflict shall be flagged. Where the source carries commercial motivation that may colour its advice, that motivation shall be flagged. The existing mental model often covers the same ground more precisely than the source does.
The cadence keys off tickets and elapsed time, not sprints.
This is solo work without sprints, and the hobbyist time budget shall shape its scope.
Recurring process shall key off ticket count or elapsed time, never sprint count. The time available shapes what may reasonably be undertaken.
Pre-launch is not post-launch. Before real users exist, schema changes go directly into the initial DDL, and runtime migrations come only after launch. Security and compliance ship to App Store and ICO minimums; the rest defers.
Tests ship with the logic, and formats are chosen for reach.
Tests shall travel with the logic they cover, and data shall be readable by the least-equipped hand.
Tests shall ship with the logic they cover: not as separate tickets, not as follow-ups. Manual test plans shall cover only what unit tests cannot.
Formats shall be chosen for reach, not for the ergonomics of the tool that produced the data. CSV shall be preferred over JSON for the spreadsheet human; Markdown over proprietary formats; SQLite over custom binaries. The tool that produces the data is rarely the only tool that needs to read it.
These Articles may be amended in the open, as a charter shows its revisions.
The cursor waits for the next hand.