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.
146 lines
5.2 KiB
Markdown
146 lines
5.2 KiB
Markdown
# 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.*
|