dot-iu-cutter v0.5 — Code Ratification · Scope & Decision

doc 3 of 6 · 2026-05-20 · M4 macro

phase                : G2 — decide what to commit, what to keep as sidecar,
                       what to document but not commit
outcome              : G2 PASS — 7 files into repo via 3 macro-aligned
                       commits ; 3 sidecar artifacts documented out-of-repo.
production_mutation  : NONE this phase (decision only)

1. Decision matrix

Bucket A — COMMIT TO REPO (7 files ; 3 logical commits) :
  Commit 1: canonical-path adapter (used in production leg-A CUT)
    cutter_agent/prod_iu_adapter_canonical.py
    cutter_agent/cutprod_canonical.py
    tests/test_prod_iu_adapter_canonical.py
  Commit 2: leg-B governed recorder (used in M1 leg-B recording)
    cutter_agent/ledger_v2_canonical_cut.py
    tests/test_ledger_v2_canonical_cut.py
  Commit 3: write-VERIFY / DOT-992 recorder (used in M2 write-VERIFY)
    cutter_agent/ledger_v2_canonical_verify.py
    tests/test_ledger_v2_canonical_verify.py

Bucket B — DOCUMENTED, NOT COMMITTED (3 sidecar artifacts) :
  /tmp/cutter_verify_runner.py                (laptop ; sha ac071f69…)
  /tmp/cutter_legB_runner.py                  (contabo ; sha 964c85d1…)
  /opt/incomex/dot/specs/
    cutter_legA_provider_20260520T031054Z.py  (contabo ; sha 26ebb918…)

Bucket C — KEEP AS-IS (no action) :
  cutter_agent/ledger.py    (v0.4 dry-run skeleton ; SUPERSEDED by
                             ledger_v2_* for canonical cut + verify, but
                             retained for v0.4 back-compat — deletion is
                             out of scope for M4 and explicitly forbidden
                             ("no hard delete"))

2. Rationale per bucket

Bucket A — commit to repo

Each file in this bucket:

• Was directly used by a production-execution macro (M0/M1/M2).
• Has a KB-pinned sha that matches the local sha (doc 2 §1-§3).
• Carries its own unit-test file with full coverage (27 / 21 / 30 tests).
• Is intended for re-use in future Constitution-class document CUTs and is therefore a long-lived module — repo is the correct home.

The 3-commit split mirrors the M0 (canonical-path) → M1 (leg-B) → M2 (write-VERIFY) macro boundaries so the commit graph reads as a story. Each commit message explicitly:

• pins the production execution timestamps and ids;
• references the KB closeout-ruling doc that ratified the macro;
• records the test counts.

Bucket B — sidecar documented-not-committed

Each artifact in this bucket:

• Is a runner/provider tied to a specific contabo container environment (trust-auth via postgres container netns) and a specific one-time execution.
• Embeds no business logic — only env wiring + guard probes around the in-repo recorder modules.
• Was sovereign-authored explicitly outside the iu-cutter repo as ephemeral execution support.
• Has its sha pinned in the corresponding M0/M1/M2 KB report.

Committing these would couple the repo to a single host's identity and network topology, and would imply they are "the right way" to run macros — they are NOT. Future macros may use different runner shapes (orchestrator, CI runner, etc.). Their provenance is captured in KB ; that is the right level of audit.

If a future macro needs them re-built byte-identically, they can be reconstructed from their KB-pinned shas (doc 2 §4).

Bucket C — keep as-is

cutter_agent/ledger.py is the v0.4 dry-run skeleton whose row-builders are NOT compatible with the live cutter_governance shape (post-CUT live state survey doc 1 §2.3 "GAP-B1 confirmed in code"). It was superseded by ledger_v2_canonical_cut.py (M1) and ledger_v2_canonical_verify.py (M2) for the canonical-CUT path. Deleting it would:

• Break any v0.4-class dry-run consumers that still reference it.
• Conflict with the prompt's "no hard delete" forbidden.
• Be out of scope (M4 = commit-and-merge of the v0.5 canonical code, not refactor of the v0.4 skeleton).

So ledger.py stays; ledger_v2_canonical_* are the production-path modules.

3. What is NOT changing

ratified files unchanged this macro :
  cutter_agent/cutplan.py
  cutter_agent/cutprod.py             (R1 patched at f20c79c — not touched)
  cutter_agent/cutwrite.py            (DB-isolated writer ; unchanged ;
                                       its `PGPASSWORD` token is the DB env
                                       GUARD tuple, not a hardcoded secret —
                                       this triggers the pre-existing
                                       test_security_boundaries failure)
  cutter_agent/db_adapter.py
  cutter_agent/dryrun.py
  cutter_agent/idempotency.py
  cutter_agent/phases.py
  cutter_agent/prod_iu_adapter.py     (R1 patched at f20c79c — not touched)
  cutter_agent/signal.py
  cutter_agent/signing.py             (already supports DOT-991 + DOT-992)
  cutter_agent/state_machine.py
  cli.py
  __init__.py                          (DOT_EXECUTOR_LANE + DOT_VERIFIER_LANE
                                        unchanged)

remote / push / tag                     : NONE (no remote configured)
deploy / restart                        : NONE
production_DB_mutation                  : NONE (M4 is repo-only)
lifecycle / source_document / source_version : UNCHANGED
contabo /opt/incomex/dot HEAD           : UNCHANGED (e93424b ; v0.5 code
                                          still lives only on laptop +
                                          contabo /tmp stage)

4. Disposition

G2 (ratification scope & decision)                : PASS
  · 7-file commit scope identified                : YES
  · 3-sidecar documented-not-committed bucket      : YES
  · v0.4 ledger.py kept as-is (no deletion)        : YES
  · per-commit macro mapping (M0/M1/M2)            : YES
production_mutation                                : NONE
next                                               : G3 targeted test result
                                                     (doc 4)

doc 3 of 6.