dot-iu-cutter v0.5 — Constitution Snapshot-source MARK Entrypoint: Code Authoring Plan

Phase: v0_5_constitution_snapshot_source_MARK_dryrun_entrypoint_code_authoring · Nature: code_authoring_package_only__no_execution__no_first_dryrun · Date: 2026-05-18 · doc 1 of 6

first_dryrun: not_executed ; cut: none ; verify: none ; db_write: none
git_commit: false ; deploy: false ; real_repo_working_tree: UNMODIFIED
input_basis: pinned snapshot artifact 17660443e0f23e99 (KB SSOT)
decision_authority: GPT / User ONLY ; self_advance: PROHIBITED

Implements GPT ruling reviews/dot-iu-cutter-v0.5-constitution-snapshot-source-mark-entrypoint-design-gpt-ruling-and-code-authoring-approval-2026-05-18.md (next_phase: code_authoring_package_only__no_execution; OD-G3 = APPROVE_EMIT_ALL_3_RATIFIED_LEVELS_WITH_DIEU_AS_FLOOR). The frozen input spec is the GPT-PASSed design package v0.5-constitution-snapshot-source-mark-dryrun-entrypoint-design/.

---

1. Read-only repository inspection (allowed)

repo_found (read-only):
  path: /Users/nmhuyen/iu-cutter-build/repo/iu-cutter   (mirror; NOT a git repo — no .git)
  also: /Users/nmhuyen/.iu-cutter-stage/iu-cutter        (older stage copy)
layout_observed:
  cli.py                      v0.4 dry-run-only CLI: subcommands run|demo|selftest;
                              --production is hard-refused
  cutter_agent/__init__.py    v0.4 skeleton; principals/lanes names only
  cutter_agent/phases.py      CutterRuntime: MARK→SWEEP→REVIEW→CUT→VERIFY over an
                              IN-MEMORY ledger adapter (still goes through CUT/VERIFY)
  cutter_agent/db_adapter.py  InMemoryDryRunAdapter + real-pg adapter (refuses)
  cutter_agent/canonicalization.py  OD-2 alias DEFERRED; Stub/Deferred only
  cutter_agent/signal.py      LocalSignal (hand/test signal contract)
  cutter_agent/ledger.py/state_machine.py/idempotency.py/signing.py
  tests/                      unittest suite (phase contracts, security, pg adapter)
git_state: `git rev-parse` => "not a git repository"; no .git anywhere up-tree

1.1 Gap confirmed (matches KB SSOT R9)

finding: NO existing entrypoint ingests a normalized SNAPSHOT ARTIFACT and emits a
  cut MANIFEST without writing IU rows. cli.py `run`/`demo` build a LocalSignal and
  call CutterRuntime which always proceeds MARK→…→CUT→VERIFY against the in-memory
  ledger (writes ledger rows, signs DOT-991/992, runs cut/verify). There is NO
  `cutter_agent.dryrun` module and NO `mark-manifest-only` mode.
closest_module: cli.py (CLI host) + the MARK concept in phases.py — but extending
  CutterRuntime is the WRONG seam: it is ledger/CUT/VERIFY-coupled. The snapshot→
  manifest mark step is upstream of, and independent from, the ledger runtime.

2. Chosen design — additive, import-isolated new module

decision: ADD a NEW standalone module `cutter_agent/dryrun.py` (+ a new test
  `tests/test_dryrun_snapshot_mark.py`). DO NOT modify any existing file.
rationale:
  - the entrypoint must be provably no-DB: a separate module that imports ONLY the
    Python stdlib (never db_adapter/phases/ledger/signal) makes "cannot write a DB
    row / cannot CUT / cannot VERIFY" a structural, test-verifiable property, not a
    runtime flag
  - additive-only => zero regression risk to the ratified v0.4 skeleton; the patch
    is a pure new-file addition (doc 2)
  - `python -m cutter_agent.dryrun` is exactly the GPT/■task-specified invocation
delivery:
  - real repo working tree is NOT modified (it is not even a git repo; an in-place
    edit could not be cleanly diffed/reverted). The patch is delivered as a
    new-file patch in KB (doc 2) per GPT preference "do not commit; provide
    patch/diff". A later, separately-authorized code phase may apply + commit it.

3. Module responsibilities (frozen spec → code mapping)

snapshot_gate:        extract_region() + snapshot_gate() — sentinel-bounded region,
                      sha256==17660443…cae80c, len==17522, markers=={✅19,📋1,📝1,⛔1};
                      mismatch => FailClosed BEFORE any parse
matchers (design doc 2 §2):
  mc.icx.zone_router            -> zone_router()
  mc.icx.nguyen_tac             -> parse_nguyen_tac()   (15 principles, contiguous)
  mc.icx.kien_truc_section      -> parse_kien_truc()    (sections A/B/C)
  mc.icx.dieu                   -> parse_dieu()          (catalog rows, group-aware)
  status_marker_detector        -> MARKERS map + group/row marker detection in parse_dieu
  changelog_boundary_detector   -> zone_router Z6 + structural classification
status_cascade (design doc 2 §3):
  tier_0 document promulgation  -> NGUYEN_TAC/KIEN_TRUC_SECTION = enacted
  tier_1 group-header inherit   -> DIEU inherits its catalog group's marker
  tier_2 explicit row override  -> Ghi-chú leading marker overrides group
                                   (Điều 44 📋 -> controlled_draft EXCLUDED)
manifest (design doc 3):    build_manifest() — candidates(enacted) + excluded(+reason)
                            + noncontent; ICX-CONST/<path>; status NOT in address;
                            provenance binds source_version_id + snapshot sha
proofs:                     independent coverage (no gap/overlap), reconstruction_ok(),
                            deterministic manifest_digest_sha256 (re-run equality)
outputs:                    manifest.json, review_evaluation.json,
                            coverage_proof.json, determinism_digest.md,
                            dryrun_report.md  (artifact files only; --out-dir)
fail_closed:                FailClosed -> BLOCKED dryrun_report.md + non-zero exit;
                            mode/flag/scope/DB-env guards refuse (exit 2)

4. Allowed/forbidden for THIS phase

done_this_phase:
  - read-only repo inspection (above)
  - authored new module + test (doc 2) in an ISOLATED /tmp scratch
  - ran local unit tests in scratch (doc 3) — gate + matchers + cascade + coverage
    + determinism + fail-closed negatives + import isolation
  - validated logic in-memory against the pinned snapshot region (gate reproduces
    canonical identity; counts/exclusions/coverage correct)
  - shredded scratch; produced this KB command-review package
NOT done (forbidden / gated):
  - the official first Constitution dry-run (NO manifest artifacts emitted to the KB
    dry-run folder; the PASS pipeline was only exercised in-memory in scratch)
  - any DB / production / Directus / vector contact
  - git commit, branch, deploy, restart
  - modifying the real iu-cutter working tree
  - self-advance to execution

5. Statement

• QG1/QG2/QG5 honored by design: pinned-snapshot identity gate; 3 ratified levels with DIEU floor (OD-G3); artifact-only/no-DB module.
• Repo inspected read-only; gap confirmed = KB SSOT R9; additive no-DB module chosen.
• Real working tree UNMODIFIED; nothing committed/deployed; first dry-run NOT run.
• doc 1 of 6; STOP after 6 docs → route GPT/User. Self-advance PROHIBITED.

Companion docs: code-diff-or-patch (2), test-plan-and-results (3), command-review-package (4), risk-and-rollback-note (5), code-authoring-report (6).