# PROMPT FOR CODE -- Project grounding audit and record-system restructure

## 0. Mission and framing

The operator's assessment, which the evidence supports: the project's record-keeping
system has become the primary work generator. Sessions open by reconciling records,
find discrepancies, file findings about the discrepancies, and thereby create more
reconciliation surface. The last working day was spent in circles at the end of the
Office1 stage without reaching a stable point on either goal (trustworthy records, or
a repeatable stable environment). Details are getting lost. This audit exists to stop
that structurally, not to fix the current crop of defects faster.

Measured evidence (verified 2026-07-18 against the pushed repo at `43b29d7`):

- `docs/` holds 135 files; **95 are changelogs** (31 filed on 2026-07-09 alone;
  sustained 6-14/day since).
- **Nine D-numbers ruled in four days** (D-121..D-129). Several are operational
  choices, not architecture: D-126 (an SSH-forward option), D-127 (an autostart
  setting), D-128 (an operating model note), D-129 (a plugin list). The decision
  register is being used as a diary, which dilutes its authority and multiplies
  reconciliation surface.
- `docs/dc0-deploy-readiness.md` carries **5/2/6 at line 37 and 5/0/6 at line 59** --
  two contradictory plan counts, both live, in the deploy gate document.
- The D-127 changelog asserts plan outcomes that are false as written (per the
  2026-07-18 session's own findings). README pins tofu 1.12.3; the binary is 1.12.4.
- `docs/session-ledger.md` is 1,125 lines and growing without a rotation rule.
- Root cause pattern: **status lives as hand-written copies in many surfaces**
  (workflow-doc stage rows, ledger, changelogs, readiness doc, README, runbook gates),
  each rotting at its own rate. Every fix to one copy creates drift in another.

What is NOT broken, and must be preserved: fence discipline (validated OK), the
adversarial-review process (ran 2026-07-16, R3-F01..F13, repairs landed), gated
mutation discipline, honest retractions, refusal to fabricate. This session's
epistemics are good. The audit repairs the SYSTEM, not the operator relationship or
the discipline culture.

## 1. Ground rules (binding for the whole audit)

- **FULL FREEZE.** No fixes -- not one typo, not one doc correction -- until Phase 5.
  No new D-numbers (audit findings use `GA-NNN`). No new changelogs. No module edits.
  No state writes. No cloud mutation. The 2026-07-18 issue list (D-130 candidates,
  platform-traps, doc-integrity items, env reconcile) is EVIDENCE for this audit,
  not a work queue. It gets re-verified and folded into the findings register.
  - **Sole exemption:** the two read-only verifications already identified (v0.9.8
    volume-replace-under-running-domain on a throwaway domain; ignore_changes
    suppression check). They are audit evidence-gathering and are read-only /
    throwaway-scoped by construction.
- **Fresh session.** This prompt is the entire charter of a NEW session. Do not
  resume the circling session; its context carries every half-fix as live state.
- **Model tiering: token budget is explicitly NOT a constraint.** The operator has
  authorized maximum effort. Ground-truth author, adjudicator, and all fresh-context
  probe agents run on the HIGHEST tier available (Fable / Opus-class). Do not
  economize by shortening reads: every document a phase touches is read in FULL, not
  grepped for keywords. The deterministic layer stays deterministic regardless of
  budget -- scripts, not agents, for anything provable.
- Verify-before-assert. Every claim in every audit output carries its evidence
  (path:line, command output, or commit). A claim without evidence is not written.
- ASCII-only, LF, all standing hard rules apply.

## 1a. Operator-endorsed leans (recorded 2026-07-18; binding as PRIORS, not rulings)

The operator has reviewed the audit design and endorses the following. Record them
accurately; do not strengthen or weaken them.

- **Primary success metric = the fresh-agent grounding test (Phase 3).** The operator
  confirms: the audit succeeds when a cold session can stand up from the repo alone
  and know where it is. Findings volume is not the metric.
- **GA-R3 (D-number admission) and GA-R5 (one ruling per operator exchange, exact
  utterance quoted) are the operator's highest-priority structural rulings.** Draft
  them first and draft them tight. Endorsement of DIRECTION is not ratification of
  TEXT: every GA-R still goes to the operator individually for gating.
- **D-130 mechanism -- the operator's provisional lean is (a) `lifecycle
  { ignore_changes }` on the seed volume, EXPLICITLY CONTINGENT on verification 8
  confirming it actually suppresses the force-replacement diff.** Rationale to
  record with the ruling: (a) is in-repo and environment-independent -- the
  Roosevelt-shaped property -- while (b) `$TMPDIR` depends on every future
  operator's shell being correctly configured, which is fragile in exactly the way
  that bites a bare-metal redeploy under pressure. **If verification 8 refutes the
  suppression, the lean is DEAD -- do not rescue it. Fall back to (b) plus a
  runbook-enforced env guard, and say plainly that the fragility concern stands and
  is being accepted.** This is a lean pending evidence, NOT a pre-ruling; the D-130
  decision text must quote the verification output it rests on.
- **Sequencing stands as written:** D-130 is ruled inside Phase 5, after
  CURRENT-STATE.md exists. The deploy is already stopped by its own gate; ruling
  against a contradictory record base is how the last batch went wrong.

## 2. Phase 1 -- deterministic inventory (scripts, not judgment)

Build and run (dry, read-only) a `scripts/record-audit.py` that produces
`docs/audit/record-inventory.md`:

1. **Doc census.** Every file in `docs/`: size, last-commit date, class (changelog /
   decision / ledger / runbook / readiness / finding / reference / patch), and
   whether anything else in the repo references it (grep). Unreferenced changelogs
   are consolidation candidates by default.
2. **Status-claim extractor.** Grep every doc for the claim classes that have already
   been caught lying: plan counts (`N add / N change / N destroy` and `N/N/N` forms),
   stage statuses (READY / BLOCKED / CLOSED / COMPLETE / HELD), version pins
   (tofu/MAAS/Juju/OPNsense/NetBox version strings), and gate assertions
   ("blocking", "unblocked", "imported", "verified"). Emit a table:
   claim | file:line | value. **Every place two rows disagree is a Phase-1 finding,
   mechanically, with zero judgment spent.**
3. **D-number ledger check.** Full `ledger-scan.sh` including `--fences`; reconcile
   the D-115-class false-positive fix (R3-F09) if still pending.
4. **Reference-integrity pass.** Every doc that cites another doc, a commit, a line
   number, or a D-number: verify the target exists and says what the citer claims.
   Broken or stale references are findings.
5. **Repo-vs-live divergence snapshot** (read-only): `tofu plan` captured to a file
   (this is the 7/2/7 vs 5/0/6 question made durable), `virsh list --all` +
   autostart table, git status. The plan OUTPUT FILE becomes the only citable source
   for plan counts from here forward.

## 3. Phase 2 -- ground-truth rebuild (highest-tier, fresh context)

One agent, highest tier, whose ONLY inputs are: Phase-1 outputs, the live environment
(read-only), git history, and as-executed logs. Explicitly NOT inputs: changelogs'
prose claims, the ledger's narrative, memory of prior sessions.

Deliverable: `docs/CURRENT-STATE.md` -- the single source of truth. Contents:

- Where the project IS: stage, what is APPLIED (from tofu state + live env, not from
  docs), what is AUTHORED-BUT-NOT-APPLIED, what is RULED-BUT-NOT-BUILT.
- Every open gate, each with: what closes it, who owns it, evidence of current state.
- The definitive current plan count, cited to the Phase-1 captured plan file.
- Version pin table, cited to `--version` command output captured in Phase 1.
- Open decision queue (D-130 mechanism ruling; netem D-100 sub-item; anything else
  found), each stated as the exact question the operator must answer, with the
  verified evidence needed to answer it attached.

Rule going forward (proposed for ratification in Phase 4): **no status claim may be
hand-written anywhere else.** Other docs POINT at CURRENT-STATE.md. CURRENT-STATE.md
cites captured command output. Two sources for the same fact is the defect class this
whole audit exists to kill.

## 4. Phase 3 -- the fresh-agent grounding test (this is the metric)

Deploy THREE clean-context agents, highest tier, no session history, no memory, no
this-audit context. Each receives ONLY the repo (post-Phase-2, with CURRENT-STATE.md
present) and this question set:

1. What stage is this project in, and what is the very next action?
2. What is applied to the live environment vs authored-only? Name three of each.
3. What gates are currently open, and what closes each?
4. What would you run before any `tofu apply`, and what must its output read?
5. What are the three most dangerous known traps in this environment?
6. Where do you look to find whether a decision D-NNN is ADOPTED, and can you trust
   a changelog's claim about it?
7. You have just been asked to redeploy DC0 from scratch. Which document do you open,
   and does it get you there without leaving the repo?

Score each answer against ground truth. **Every wrong or unanswerable item is a
grounding hole, mapped to the artifact that should have answered it.** This converts
"Code lost grounding" from a feeling into a measured defect list -- and it is the
direct test of the real requirement: that a future session can stand up cold and
work. The holes map IS the Phase-5 work queue for documentation.

Run the probes INDEPENDENTLY (no shared scratchpad). If all three agree and are
wrong the same way, that is a repo defect, not agent error -- weight it double.

## 5. Phase 4 -- structural rulings (proposed to the operator, individually gated)

Draft each of the following as a decision for the operator to gate. These are the
recurrence-stoppers; without them the audit buys two weeks.

- **GA-R1: Single source of truth.** CURRENT-STATE.md owns all status. Every other
  surface demotes to pointer or history. The workflow doc's stage table keeps only
  stage IDENTITY and links; the readiness doc becomes a checklist that cites the
  plan capture; README drops every pin that CURRENT-STATE.md owns.
- **GA-R2: Changelog consolidation.** Per-stage consolidation on stage close (the
  proven v1 do-doc pattern): the 95 changelogs collapse into per-stage consolidated
  records; individual files preserved in git history via the consolidation commit;
  working set target: under 25 files in docs/. Standing rule: changelogs are
  session-scoped scratch, consolidated at stage close, and are NEVER citable as
  status authority (Phase 1 proved they lie).
- **GA-R3: D-number admission criteria.** A D-number requires: architectural
  consequence beyond one stage, OR a Roosevelt-delta implication, OR supersession of
  an existing D. Operational choices (tool options, service settings, plugin lists,
  process notes) get a changelog line or a runbook edit, not a D-number. Include a
  one-time review: which of D-121..D-129 would not meet the bar (candidates:
  D-126, D-127, D-128, D-129) -- they KEEP their numbers (append-only), but the
  register gains a class tag so architectural Ds are findable among operational ones.
- **GA-R4: Ledger rotation.** Sessions close with a bounded summary (hard cap,
  suggest 15 lines) written to the ledger; the body of a closed session moves to
  docs/archive/. The ledger's live section stays under a size a session can actually
  read in full (suggest 300 lines). Fence discipline unchanged.
- **GA-R5: Ruling gate discipline.** Extend the existing individually-gated rule
  from mutations to RULINGS: one decision ruled per operator exchange, quoting the
  exact operator utterance in the status line. No batch adoptions. (This is R3-F01's
  lesson made standing policy.)
- **GA-R6: Executable definition of done.** A stage is CLOSED only when a named
  script/gauntlet target passes, and the closing commit records its output. For the
  current gate specifically: DC0 readiness == the captured outer plan reads exactly
  5 add / 0 change / 6 destroy AND the fresh-agent test question 7 passes. Prose
  cannot close a stage.

## 6. Phase 5 -- repair sweep (only now do fixes happen)

- Consolidated findings register `docs/audit/grounding-audit-YYYYMMDD.md`:
  GA-F01..GA-Fnn, each with severity, evidence, proposed fix, and which GA-R ruling
  or grounding hole it traces to. Fold in and re-verify the 2026-07-18 issue list
  (D-130 staging trap, platform-traps items a/b, doc-integrity items, autostart
  state reconcile, seed-volume diff) and the adversarial review's unapplied
  residuals (R3-F12 Octavia headroom; netem sub-item; any other open R3-F).
- The operator gates the sweep. Fixes are applied in traceable batches; **every fix
  commit message names its GA-F number. A fix without a finding number does not
  ship.** This is the churn-killer: it makes "found another thing, fixed it inline"
  impossible by construction.
- **Skill sweep (mandatory Phase-5 item):** implement the RATIFIED GA-R rulings in
  the `openstack-cloud-ops` operating skill, per the standing stage-close
  skill-sweep discipline (commit `80502e9`). The skill is what every future session
  loads first -- if the rulings do not land there, they decay. Proposed additions
  are in the operator's companion note (`skill-additions-proposed.md`); reconcile
  against the ratified GA-R text, not the proposal, where they differ. Keep the
  skill TIGHT: it is also record surface, and a bloated skill is this disease in
  its most expensive location.
- The D-130 mechanism ruling happens HERE, informed by the two exempted
  verifications, as a single operator-gated decision -- after CURRENT-STATE.md
  exists, so the ruling lands on a trustworthy base.

## 7. Phase 6 -- exit criteria (executable, not prose)

The audit is DONE when, in order:

1. Phase-1 extractor re-run reports ZERO contradictory status-claim pairs.
2. `docs/` working set is at the GA-R2 target with history preserved.
3. The fresh-agent test re-runs with a NEW trio of clean agents and scores 7/7 on
   at least two of three agents, with no question failed by all three.
4. The captured outer plan reads exactly 5 add / 0 change / 6 destroy (the standing
   gate; if the audit legitimately changes the expected counts, CURRENT-STATE.md
   records the new expected triple and WHY before the re-plan).
5. The operator reads CURRENT-STATE.md top to bottom and signs it as matching their
   own understanding -- and where it does not match, the discrepancy is resolved in
   the document, not in chat.

Then, and only then, the DC0 apply path resumes from its gate.

## 8. Conduct notes

- Do not perform contrition. The operator needs the system fixed, not apologized to.
  Findings about your own prior work are stated exactly like findings about anything
  else: evidence, severity, fix.
- Where an audit finding implicates a prior operator ruling, say so plainly and
  propose the amendment -- the operator has explicitly asked for pushback and
  best-practice debate with sourced rationale.
- If at any point the audit itself starts generating more record surface than it
  retires, STOP and report -- that is the disease presenting inside the cure, and
  the operator should see it immediately.
