init: CIVICVS repository — CBPs, corpus standard, directory structure
- 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.
This commit is contained in:
145
CIVICVS-CBPs.md
Normal file
145
CIVICVS-CBPs.md
Normal file
@@ -0,0 +1,145 @@
|
||||
# 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.*
|
||||
Reference in New Issue
Block a user