ops: add doctrine anchor script and runbook
This commit is contained in:
78
50-runbooks/10-provision/anchor-doctrine-to-ledger.md
Normal file
78
50-runbooks/10-provision/anchor-doctrine-to-ledger.md
Normal file
@@ -0,0 +1,78 @@
|
||||
# Runbook: Anchor Doctrine to Civilization Ledger
|
||||
|
||||
## Purpose
|
||||
|
||||
Produce tamper-evident, witness-backed receipts for doctrine files so audits can verify: **git state ↔ signed entry ↔ inclusion proof ↔ witness attestation**.
|
||||
|
||||
## Preconditions
|
||||
|
||||
- Access/role required: operator key + (optional) witness key.
|
||||
- Systems required:
|
||||
- `ops/` working tree
|
||||
- Civilization Ledger CLI (`ledger`)
|
||||
- Expected safe state:
|
||||
- No plaintext secrets in `ops/` or `civilization-ledger/`
|
||||
- Doctrine files have been reviewed and are ready to anchor
|
||||
- Time estimate: 2–5 minutes
|
||||
|
||||
## Steps
|
||||
|
||||
1. Build the `ledger` CLI if needed:
|
||||
|
||||
```bash
|
||||
cd ../civilization-ledger
|
||||
cargo build -p ledger-cli
|
||||
```
|
||||
|
||||
2. Choose a ledger directory (persistent, not inside Git), e.g.:
|
||||
|
||||
```bash
|
||||
export LEDGER_DIR="$HOME/.local/share/civ-ledger/ops-law"
|
||||
```
|
||||
|
||||
3. Ensure keys exist (store outside Git):
|
||||
|
||||
```bash
|
||||
mkdir -p ~/.config/civ-ledger/keys
|
||||
ledger keygen --out ~/.config/civ-ledger/keys/operator.json
|
||||
ledger keygen --out ~/.config/civ-ledger/keys/witness.json
|
||||
```
|
||||
|
||||
4. Anchor doctrine and emit receipts into `ops/70-audits/reports/ledger/`:
|
||||
|
||||
```bash
|
||||
cd ops
|
||||
./80-automation/scripts/anchor-doctrine-to-ledger.sh \
|
||||
--ledger-dir "$LEDGER_DIR" \
|
||||
--operator-key ~/.config/civ-ledger/keys/operator.json \
|
||||
--witness-key ~/.config/civ-ledger/keys/witness.json
|
||||
```
|
||||
|
||||
5. (Optional) Commit the receipts as audit evidence:
|
||||
|
||||
```bash
|
||||
git add 70-audits/reports/ledger
|
||||
git commit -m "audit: anchor doctrine receipts"
|
||||
```
|
||||
|
||||
## Validation
|
||||
|
||||
- Receipts exist under `70-audits/reports/ledger/`.
|
||||
- Each receipt passes verification:
|
||||
|
||||
```bash
|
||||
ledger verify-receipt --receipt 70-audits/reports/ledger/<receipt>.json --require-attestation
|
||||
```
|
||||
|
||||
## Rollback / Abort
|
||||
|
||||
- Ledger writes are append-only. If you anchored something you didn’t intend:
|
||||
- correct the doctrine in Git,
|
||||
- anchor again (new entry),
|
||||
- record the supersession in audit notes.
|
||||
|
||||
## Evidence
|
||||
|
||||
- Receipt files: `70-audits/reports/ledger/*.receipt.json`
|
||||
- (Optional) `ledger verify-attestations --dir "$LEDGER_DIR" --format json` output
|
||||
|
||||
Reference in New Issue
Block a user