Fork: 0
OpenStack / openstack-caracal-dc-dc
Transfer to URL with SHA Find file
Newer
Older
openstack-caracal-dc-dc / docs / changelog-20260805-skill-close-convention-docfix.md
@JANeumatrix JANeumatrix 16 hours ago 5 KB DOCFIX-209: correct SKILL.md session-CLOSE bookend + re-seed ledger machine-block
Raw Blame History

Changelog 2026-08-05 (skill close-convention DOCFIX) -- SKILL.md close bookend corrected

Session changelog (GA-R2/D1: ONE per session; distinct session from the 2026-08-05 vault-init close, whose body is docs/changelog-20260805-vault-init-ovn-resolved.md). Branch dc-dc-stage5-preconditions. Session open reconciled at HEAD e252b31: repo-lint 0 fail / 1 legacy warn, ledger-scan 4 open decisions / 29 open SEC / next-free D-143, DOCFIX-209, BUNDLEFIX-053. Status claims live in docs/CURRENT-STATE.md ONLY; nothing here is a status claim.

Scope: a single skill/repo divergence in the session-CLOSE bookend text, surfaced 2026-08-05. No live-cloud mutation; no state-bearing surface touched (a skill routing line is not a status claim, so no GA-R1 L10 coupling). Stage 5 dc0 remains OPEN and untouched by this session.

Item 1 -- DOCFIX-209: SKILL.md close-bookend text conflated GA-R4 ledger rotation with the GA-R2 changelog body

WHAT WAS WRONG. .claude/skills/openstack-cloud-ops/SKILL.md (the always-loaded routing layer -- F12: a wrong line here misleads every fresh session before any runbook loads) described session CLOSE as: "a bounded ledger summary (15-line hard cap, GA-R4 rule 1); the full session body goes to docs/archive/ in the same close commit." That last clause is a paraphrase of ratified GA-R4 rule 2's literal words -- but it CONFLATES two distinct ratified mechanisms and describes neither correctly:

  • GA-R4 rule 2 + amendment F1 (docs/audit/ga-rulings.md:328-338) is the LEDGER ROTATION mechanism: bounded summaries rotate out to a dated docs/archive/session-ledger-rotated-*.md file when the 300-line live-ledger cap binds at a close -- NOT a "full body" and NOT "in the same close commit" of every session. Practice follows this: docs/archive/ holds 11 such rotated ledgers (latest session-ledger-rotated-20260804.md).
  • GA-R2 amendment D1 (docs/audit/ga-rulings.md:228-234) makes the CHANGELOG the session body-of-record ("one changelog per session"). The session's full body is docs/changelog-<date>-<label>.md, cited by a Body: line in the ## SESSION CLOSE <date> block appended to docs/session-ledger.md. That changelog is consolidated per-stage into docs/archive/changelogs/ at STAGE close (GA-R2 rule 2), not moved at session close.

So the skill line was wrong on both counts: the per-session body is the changelog (it stays in docs/changelog-* until stage-close consolidation), and what reaches docs/archive/ at a session close is a ledger rotation, and only at cap.

EVIDENCE (measured, not asserted).

  • Ratified text: docs/audit/ga-rulings.md:328-332 (GA-R4 rules 1-2), :333-338 (F1 cap-at-close), :209-234 (GA-R2 rules 2/5 + D1).
  • ls docs/archive/ -> session-ledger-rotated-*.md (x11) PLUS changelogs/ (consolidated per-stage bodies) PLUS stage-records/ PLUS one-off historical docs. Archive is NOT "rotated ledgers only".
  • Close blocks in docs/session-ledger.md carry Body: changelog citations: 08-05 -> docs/changelog-20260805-vault-init-ovn-resolved.md; 08-04 -> docs/changelog-20260804-ovn-central-cert-fix.md; 08-02 -> docs/changelog-20260802-queued-items.md.
  • references/operating-discipline.md "Session continuity" (:100-112) is already correct (ledger = what is open; changelog = what changed) and needs NO edit.

DISPOSITION. Operator-ruled 2026-08-05: "Proceed as DOCFIX-209". Because both same-day rulings, read correctly, BACK the practice and CONTRADICT the skill line's conflation, no ratified text changes -- this is a skill-text correction, not a GA-R5 amendment. (The alternative -- amend GA-R4 rule 2 first -- was offered and declined.)

THE FIX. In .claude/skills/openstack-cloud-ops/SKILL.md, the CLOSE sentence now reads: bounded <=15-line summary (GA-R4 rule 1) appended to docs/session-ledger.md as a ## SESSION CLOSE <date> block; the session's full body is its changelog (docs/changelog-<date>-<label>.md, GA-R2 one-per-session) cited by that block's Body: line; and docs/archive/ is explicitly NOT the per-session body store -- it holds periodically-rotated full ledgers (session-ledger-rotated-*.md, GA-R4 rule 3) and per-stage consolidated records (archive/changelogs/, archive/stage-records/, GA-R2 rule 2 at STAGE close). ASCII-only (<= not the glyph; -- dashes).

SECOND COPY FIXED. The derived Chat-upload snapshot .claude/skills/openstack-cloud-ops-consolidated-20260727.md:54-57 carried the byte-identical sentence and was patched identically, so the Chat mount does not stay stale in the interim (a stale mount is the known failure mode that caused a bad clone 2026-07-25, docs/audit/skill-divergence-20260725.md). The snapshot is a DERIVED artifact; it is properly regenerated from SKILL.md + references at stage close -- this hand-patch is an interim-consistency measure, not a substitute for that regeneration. (A third copy exists in the git-ignored worktree .claude/worktrees/skill-repackage-20260727/; left untouched -- it is a separate working tree, not part of the tracked surface.)

REVERT. git revert this commit (skill edits ship uncommitted for operator diff review, so pre-commit this is git checkout -- <the two skill files>). Restores a routing line that conflates GA-R4 ledger rotation with the GA-R2 changelog body and mis-describes docs/archive/. Do not revert without re-opening the finding -- the line misleads every fresh session's close bookend.