dot-iu-cutter v0.4 — Cutter-Agent Code-Authoring Report

document_path: knowledge/dev/laws/dieu44-trien-khai/v0.4-code/dot-iu-cutter-v0.4-cutter-agent-code-authoring-report-2026-05-16.md
revision: r1
date: 2026-05-16
author: Agent (Claude Code CLI, Opus 4.7 1M)
sovereign: User / anh Huyền
verifier: GPT (code review pending — this report routes the package in)
phase: v0.4 — Tier 2 CODE-AUTHORING cycle REPORT
authorization: GPT v0.4 design review = PASS (10 ODs resolved) + explicit
  User code-authoring prompt. CODE AUTHORING ONLY.
status: code_authored_pending_gpt_code_review

⛔ CODE AUTHORING ONLY. No production DB connection. No credential/role created. No GRANT/REVOKE. No .env edit. No Directus/RLS change. No Qdrant/vector. No deploy/restart. No cutter_governance row written to any real database. No CUT/VERIFY against production. No self-advance to dry-run or production.

---

§1 — Repo Inspected (VPS = SSOT)

host: contabo / 38.242.240.89 (root)
dot_repo: /opt/incomex/dot  (independent git repo, branch main)
  layout: bin/ (286 bash dot-* scripts), lib/ (mixed py/sh), config/,
    migrations/, specs/, reports/
  pre-existing UNRELATED WIP (NOT touched by this cycle):
    M bin/dot-birth-trigger-setup, M bin/dot-context-pack-build.sh,
    M bin/dot-vector-audit, ?? bin/dot-search-canary, ?? specs/ ...
python_on_vps: 3.12.3 ; pytest NOT installed → stdlib unittest only
no_pre_existing_iu_cutter_code: confirmed (greenfield runtime; schema was
  built in prior cycles via SQL artefacts, not app code)

§2 — Target Path Chosen (User-confirmed Option 1)

root: /opt/incomex/dot/iu-cutter/
rationale: self-contained Python package inside the DOT governance repo
  (git-tracked + committed there per the after-VPS-edit rule), aligned
  with DOT-991/992, isolated from the 286 bash bin/ scripts, PG-direct
  (not via Directus/Agent Data — matches the design control-plane).

§3 — Files Created (16; commit 689e53e, scoped to iu-cutter/)

iu-cutter/.gitignore                         __pycache__/ , *.pyc
iu-cutter/README.md                          impl note + later-authorization chain
iu-cutter/cli.py                             dry-run/local entrypoint (demo|run|selftest); --production refused rc2
iu-cutter/cutter_agent/__init__.py           version, DOT-991/992 lanes, principal names
iu-cutter/cutter_agent/db_adapter.py         txn boundaries; InMemoryDryRun + refusing ProductionDBAdapter; principal guard; append-only
iu-cutter/cutter_agent/state_machine.py      states, allowed/forbidden, S5/S7 non-persistable, compare-and-set
iu-cutter/cutter_agent/idempotency.py        payload.idempotency_key (OD-1; scenario_ref excluded)
iu-cutter/cutter_agent/ledger.py             append-only writer ifaces; transition_status = validate+CAS+history
iu-cutter/cutter_agent/phases.py             CutterRuntime: mark/sweep/review/cut/verify
iu-cutter/cutter_agent/canonicalization.py   interface + Deferred + alias-free Stub (OD-2)
iu-cutter/cutter_agent/signing.py            interface + Deferred + non-crypto Stub (DOT-991/992, no secret)
iu-cutter/cutter_agent/signal.py             local/test signal contract only (OD-4)
iu-cutter/tests/test_state_machine.py        valid/forbidden/terminal/S5-S7/CAS
iu-cutter/tests/test_idempotency.py          determinism, scenario_ref excluded, dedup
iu-cutter/tests/test_phase_contracts.py      append-only retry, OD-6 sig ownership, 1-txn/phase, rollback/escalation, guards
iu-cutter/tests/test_security_boundaries.py  prod-refusal, cutter_ro never writes, no DSN, no secret printed, --production refused
files_modified: none (greenfield); unrelated repo WIP left uncommitted
git: commit 689e53e on main; `git add iu-cutter/` ONLY (no git add -A)

§4 — Ratified Open Decisions → Where Implemented

OD-1  idempotency.compute_idempotency_key (scenario_ref NOT an input)
OD-2  canonicalization.py — no alias row ever written; Stub is alias-free
OD-3  __init__.PRINCIPAL_EXEC/VERIFY; phases uses 2 principal-scoped adapters
OD-4  signal.LocalSignal (local/test only; no prod source)
OD-5  ledger prior_*/write-once superseded_by_*; phases re-review/re-verify chain
OD-6  ledger.write_cut_change_set leaves verifier_signature_id=None;
      verify_result owns verifier_signature_id (asserted in tests)
OD-SM-1 state_machine.compare_and_set + db_adapter.cas_status (no advisory lock)
OD-SM-2 state_machine.NON_PERSISTABLE_STATES {S5,S7}; assert_persistable raises
OD-SM-3 phases.sweep — same agent, writes sweep_log + history each pass
OD-CR-1 not implemented by design (no secret minted; README documents the
        future VPS .env credential cycle)

§5 — Tests Run + Results

command: cd /opt/incomex/dot && python3 -m unittest discover -s iu-cutter/tests
environment: VPS, Python 3.12.3, stdlib only, NO prod creds, NO DSN
result: Ran 45 tests — OK (0 fail, 0 error)
also_local: Python 3.11.6 — 45/45 OK (parity)
cli_demo: pipeline → final_status=verified_complete, production_touched=false,
  committed_txns=5, in-memory ledger only (no real DB)
cli --production: REFUSED, rc=2
coverage_highlights:
  - valid + forbidden state transitions; S5/S7 never persisted
  - idempotency determinism + scenario_ref-independent dedup
  - append-only retry (prior chain + write-once superseded stamp)
  - CUT leaves cut_change_set.verifier_signature_id NULL (OD-6)
  - VERIFY owns verifier signature; change set not back-filled
  - cutter_ro / workflow_admin / directus / postgres write → WriteForbidden
  - ProductionDBAdapter refuses to construct (no DSN/env/secret)
  - pipeline runs with PG/DB/SECRET env vars stripped
  - no secret/DSN pattern in CLI output or package source
  - DELETE/TRUNCATE forbidden; write outside txn forbidden

§6 — Code Limitations (intentional, by scope)

- storage is in-memory only; no real DB adapter implemented (deferred)
- canonicalization + signing are placeholders/stubs (HIGH-risk deferred):
  Stub signing is NON-cryptographic and clearly flagged is_production=False
- dry-run lineage uses a helper key (review_decision._source_entry) to
  associate decisions to entries — a real schema-backed adapter must map
  this via the manifest/source columns, not an ad-hoc field
- composite manifest_unit_block PK + full FK graph are modelled loosely
  (dicts), not enforced as in PG — enforcement returns with the real adapter
- no concurrency: CAS is modelled single-process; real multi-writer race
  behaviour is a dry-run-cycle concern (OD-SM-1 says revisit only if
  dry-run proves CAS insufficient)
- signal source is local/test only (OD-4); no queue/bus

§7 — No-Production-Touch Confirmation

production_db_connection: NONE (ProductionDBAdapter raises on construct)
credentials_created: NONE   roles_created: NONE   GRANT/REVOKE: NONE
env_file_touched: NONE      secret_read_or_printed: NONE
directus_change: NONE       RLS_change: NONE       qdrant_vector: NONE
deploy_or_restart: NONE     cutter_governance_rows_written: NONE (in-memory only)
production_CUT_or_VERIFY: NONE
git: scoped commit to iu-cutter/ only; unrelated dot WIP left untouched
sysid / prod DB: not contacted at all this cycle

§8 — Status / Readiness

v0_4_code_authoring: COMPLETE (skeleton + 45 passing stdlib tests)
ready_for_gpt_code_review: TRUE
ready_for_credential_cycle: FALSE (separate gated cycle)
ready_for_dry_run: FALSE (needs code-review PASS + real adapter design)
ready_for_production_CUT_VERIFY: FALSE
the_only_next_thing: GPT code review of this skeleton
agent_self_advance: PROHIBITED

End of v0.4 cutter-agent code-authoring report (code only; no production touch; ready for GPT code review; self-advance PROHIBITED).