board-migration-duckdb-cutover

Answer

I built the complete cutover tool (migrate.py) that implements every post-fix directive as a hard, tested invariant. Pipeline: tasks.md matrix → parse → normalize → validate (hard abort) → git-safe JSONL → archive .bak → PUT+GET-verify+pin → two-commit backfill → gitreins dual-track → audit event.

Directive 1 — namespace basename bug (home → project-key): the sentinel home (or empty) resolves to the basename of the fleet repo path, never "home" again:

NAMESPACE_BUG_SENTINEL = "home"
def _project_key(repo, fallback):
    base = os.path.basename(repo.rstrip("/")) if repo else ""
    return base[:-4] if base.endswith(".git") else (base or fallback)

if rec.ns == NAMESPACE_BUG_SENTINEL or not rec.ns:
    rec.ns = _project_key(rec.repo, rec.key)   # home -> alpha, never "home"

Directive 2 — cooldown_s=7200 (Bane 07-31), NOT 43200: constant pinned to 7200; the legacy 43200 is migrated in normalize() (logged to audit) and any non-7200 record fails validate():

BANE_31_JULY_COOLDOWN_S = 7200
LEGACY_WRONG_COOLDOWN_S = 43200
if rec.cooldown_s != BANE_31_JULY_COOLDOWN_S:
    notes.append({"field": "cooldown_s", "from": rec.cooldown_s,
                  "to": 7200, "reason": "Bane 07-31 directive (7200, not 43200)"})
    rec.cooldown_s = BANE_31_JULY_COOLDOWN_S

Directive 3 — DecayRate=0 rejected: hard validation before any write — no JSONL, no archive, no pin, no audit:

if not math.isfinite(rec.decay_rate) or rec.decay_rate <= 0:
    errors.append(f"{rec.key}: DecayRate={rec.decay_rate!r} rejected (must be finite and > 0)")

Directive 4 — enforcer-set 900 policy-correct while BOARD-V2 pending: preserved verbatim — normalize() never touches it, the constant is documented, and a regression-guard test asserts no note/rewrite exists for the field:

ENFORCER_POLICY_WHILE_BOARD_V2_PENDING = 900   # policy-correct; keep verbatim

Directive 5 — durability: PUT → GET → field-level round-trip verify → atomic fleet.toml pin (os.replace), optionally git commit:

fleet_put_get_verify(store, records)      # every record PUT then GET+field-checked
pin_fleet_toml(fleet_toml, jsonl_sha, len(records), snap_sha, cutover_ts)

Directive 6 — two-commit hash backfill: empty commits get a deterministic 12-char digest over HEAD and HEAD~1:

digest = hashlib.sha256(f"{head}:{head1}".encode()).hexdigest()[:12]

Directive 7 — gitreins dual-tracking: the task is registered in both gitreins/manifest.toml (tracked_in: ["gitreins-manifest","export-jsonl"]) and the JSONL (dual_tracked: true); completion criterion is file existence:

def is_complete(self): return os.path.isfile(self.rec.criterion_file)

Directive 8 — audit event instead of tasks.md append: tasks.md is archived to .bak (refusing to clobber) and made immutable; the cutover is appended to audit/events.jsonl (event: "board_v2_cutover" with JSONL sha, archive sha, records, migration notes) via append-only write. JSONL is git-safe: LF-only, trailing newline, sorted keys, sorted record order, no NaN/Inf, byte-reproducible, and verified by a real DuckDB load (verify_duckdb — row count, cooldown_s != 7200 count, ns='home' count, decay_rate<=0/NaN count all must be 0).