Newer
Older
openstack-caracal-ipv4 / docs / as-executed-log-convention.md
@JANeumatrix JANeumatrix 14 hours ago 1 KB Patches

As-executed log convention (DOCFIX-076)

The verbatim-retrieval rule -- "for irreversible / one-shot / secret steps, retrieve the exact prior working command verbatim, never improvise" (the DOCFIX-006 vault-init loss is the cautionary tale) -- is only as strong as the artifact it retrieves from. Until now "the as-executed log" was a habit with no defined location, format, or retention. This defines it.

WHERE: jumphost, ~/as-executed/<UTC date>-<label>.log (dir 0700, files 0600). NEVER in the repo: sessions are secret-adjacent (tokens print, paths leak, hidden-prompt secrets do NOT echo but everything around them does).

HOW: start every consequential session (any RUN/CAUTION work) with bash scripts/run-logged.sh <label> -- it opens a logged subshell via script(1); exit to close. Labels: phase-NN-<topic> for deploy work, ops-<topic> for operations, incident-<date>-<topic> for incidents.

INDEX (this IS committed): logs/as-executed-index.md -- one line per session: date, label, operator, one-phrase scope. No content, no hostnames beyond the jumphost, no secrets. The index is what makes a two-year-old one-shot command findable by a Roosevelt operator who knows only "vault was initialized around June 2026".

RETENTION: keep indefinitely on the jumphost; include ~/as-executed in the jumphost backup set. A log that would age out is exactly the one the verbatim rule will someday need.

WHAT STILL GOES IN RUNBOOKS: the PROCEDURE. Logs capture what actually ran (with its warts); runbooks capture what SHOULD run. When they diverge, that divergence is a DOCFIX.