TheRON
34316d2429
- README.md: project identity, TESSERA relationship, directory layout - CIVICVS-CBPs.md: CBP-001 through CBP-006 adapted for CIVICVS - docs/corpus/mesolithic-corpus-standard-v1.md: 10-table schema, 6-sprint plan, 25 seed concepts Per CBP-001: committed same session as produced.
5.2 KiB
CIVICVS — Critical Baseline Protocols
Status: Normative
Date: 2026-04-18
Adapted from: TESSERA v3.0 CBPs (ssot/docs/v3/README.md)
These are not guidelines. They are not best practices. They are the conditions under which this project operates. Deviation is not permitted. If a CBP cannot be followed, work stops until it can be.
CIVICVS inherits the same process failure mode that cost TESSERA v2.0 months of work: documents produced in chat sessions, never committed, permanently lost. These CBPs exist to prevent that failure from recurring in CIVICVS.
CBP-001 — Every document is committed before the session ends
Any document produced in a session — schema, governance doc, architecture decision, corpus entry, session log — is committed to this repository before the session ends. Not summarised. Not noted for later. Committed.
A session that produces a document and does not commit it has produced nothing. The chat log is not a repository. It is not durable. It is not citable. It does not exist.
Enforcement: The last action of every session is to verify that every document produced in that session exists in the repository. If it does not, the session is not over.
CBP-002 — Every session produces a session log
A session log is a raw, detailed record of what happened. It includes:
- Every decision made, with the reasoning
- Every failure encountered, with the exact error
- Every workaround discovered, with the exact command
- Every assumption that proved wrong
- Every benchmark measured, with the actual number
Session logs are not polished. They are not summaries. They are the unfiltered record. Future contributors — human or AI — must be able to reconstruct exactly what was tried, what worked, and what did not, without repeating the same experiments.
Enforcement: A session log is committed before any other end-of- session work. It is the first commit, not the last.
CBP-003 — Infrastructure is tested before it is designed around
No component — Saltcorn, ChromaDB, Ollama, any API — is designed around an assumption about what it can do. The assumption is tested first with a minimal real operation. Only then is the design built.
If a data source, service, or tool is investigated and found unsuitable, that finding is documented. Failures are permanent knowledge. Do not let the next session repeat the same investigation.
Enforcement: Before any new service is incorporated into CIVICVS design, its actual behaviour, actual data format, and actual limitations are documented with the date of investigation.
CBP-004 — The file transfer protocol is followed without exception
Every file that reaches a server node travels this exact path:
Claude produces tarball → user downloads → user uploads to /tmp/ on target node → commands run there
There is no other path. There is no heredoc injection. There is no "write it directly." There is no assuming a file is present because it was produced in a previous step.
If a command references a file that is not confirmed present in /tmp/ on the target node, the command is not run.
Enforcement: Every deploy sequence begins with confirming the tarball is present at /tmp/ on the target node before any git or extract command runs.
CBP-005 — The Mesolithic Corpus Standard is the source of truth for corpus work
When the corpus schema says one thing and a corpus entry does another, the entry is wrong until proven otherwise. If the schema is wrong, it is corrected immediately and the correction is committed with an inline note explaining what was wrong and when it was fixed.
The corpus standard is at docs/corpus/mesolithic-corpus-standard-v1.md.
It is normative. All corpus entries, Saltcorn tables, and views must
conform to it. Deviations are not tolerated silently — they are
either corrected or the standard is updated with explicit reasoning.
Enforcement: Before any corpus sprint begins, the corpus standard and the current Saltcorn table schema are read together and confirmed consistent.
CBP-006 — The handover is written for the next assistant, not for posterity
A handover document is not a summary of what was accomplished. It is an operational briefing for an assistant who has no prior context and must be able to continue the work without asking clarifying questions about project state.
A handover must state:
- What is currently running and its status
- What is pending and why
- What is broken and what the exact error is
- The first task for the next session, unambiguously
A handover that requires the recipient to make assumptions is incomplete.
Enforcement: The handover is tested by asking: "What is the first thing to do?" If the answer is uncertain, the handover is rewritten.
What CIVICVS CBPs do not cover
These CBPs govern session continuity and commit discipline. They do not cover:
- The corpus schema (see
docs/corpus/mesolithic-corpus-standard-v1.md) - Infrastructure decisions (see TESSERA
ssot/docs/v3/infrastructure.md) - The simulation RFC stack (to be created)
- The TESSERA data model (see TESSERA RFC stack)
CIVICVS-CBPs.md — 2026-04-18 Status: Normative The process is the project.