dot-iu-cutter v0.5 — First Snapshot CUT-plan Dry-run · Command Shape, Artifacts, Write Statement

doc 2 of 5 · review_design_only__no_execution__no_code · 2026-05-19 · sub-phase S1

1. Exact proposed non-production command shape (required item 2)

The entrypoint cutter_agent/cutplan.py does not exist yet (it is authored in S2, gated). This is the ratified target command shape the S2 entrypoint must implement — DO NOT RUN.

# CONTRACT — requires the S2-built import-isolated stdlib-only entrypoint. NOT runnable today.
cd /Users/nmhuyen/iu-cutter-build/repo/iu-cutter            # branch feature/constitution-snapshot-mark-dryrun
WD="$(mktemp -d /tmp/icx-const-cutplan-dryrun.XXXXXX)"; chmod 700 "$WD"   # OUTSIDE the repo

python3 -m cutter_agent.cutplan \
  --mode                    cut-plan-only \
  --no-db-write --no-cut --no-verify --fail-closed \
  --manifest                "$WD/manifest.json" \
  --expect-manifest-digest  9d908a62fcf01bb88e05a1af4335b960710006ddcfd21c811ca63efb33dd324f \
  --expect-manifest-file-sha 7d56f3ce066950ccef3de4156c5afeea81b2450b8e38393205b52c1fca012179 \
  --expect-candidate-count  60 \
  --source-version-id       icxconst-008a06ace23a96ea6cd456146e805c97 \
  --docprefix               ICX-CONST \
  --scope                   enacted_only \
  --exclude-dieu-44 \
  --out-dir                 "$WD/cutplan" \
  --emit                    cut_plan.json,write_set_preview.jsonl,iu_mapping_preview.json,idempotency_keys_preview.json,dryrun_report.md

guard_semantics (must mirror dryrun.py's hardening):
  mode != cut-plan-only                      ⇒ exit 2 REFUSED
  missing any of --no-db-write/--no-cut/--no-verify ⇒ exit 2 REFUSED
  scope != enacted_only                      ⇒ exit 2 REFUSED
  any DB env var set (PG_DSN/DATABASE_URL/DIRECTUS_URL/PGPASSWORD/PGHOST/PGUSER) ⇒ exit 2 REFUSED
  manifest digest / file-sha / candidate-count mismatch, or Điều 44 in candidates ⇒ exit 3 BLOCKED
  --emit accepted but the 5 fixed-name files are always written (value documents intent)
manifest_input: operator regenerates manifest.json via the pinned deterministic MARK command
  into $WD, then runs cut-plan-only against it; the entrypoint re-digests and gates on identity.

2. Expected artifact outputs (required item 4)

All written ONLY to the local ephemeral $WD/cutplan (outside the git repo). Fixed names:

cut_plan.json:
  header: {manifest_digest, manifest_file_sha256, candidate_count:60, excluded_count:4,
           source_document_version_id, docprefix, scope_policy, cut_plan_digest_sha256,
           re_run_equal:true}
  planned_write_set_summary: counts per would-be table (manifest_envelope:1,
           manifest_unit_block:60, cut_change_set:1, decision_backlog_history:n,
           dot991_executor_signature:n) — PREVIEW counts only, zero inserted
write_set_preview.jsonl:
  one JSON object per line = one row a production CUT WOULD INSERT, in apply order, with a
  "table" tag; append-only shape per ledger.py (manifest_envelope/manifest_unit_block/
  cut_change_set...). Marked "preview": true, "persisted": false on every line.
iu_mapping_preview.json:
  60 entries: {canonical_address: ICX-CONST/<path>, level, source_span{line_start,line_end,
  span_sha256}, content_hash, provenance.source_document_version_id} — derived from the
  manifest candidates[]; addresses REUSED from MARK (no stub-resolver invocation).
idempotency_keys_preview.json:
  60 deterministic keys, OD-1 style: sha256 over canonical JSON (sorted keys, no whitespace)
  of the idempotency-relevant tuple (source_document_version_id, canonical_address,
  content_hash). All 60 distinct; key independent of any human/scenario label.
dryrun_report.md:
  status PASS|BLOCKED + mode cut-plan-only + db_write NONE + production_touched false +
  candidate_count 60 + excluded_count 4 + dieu_44_excluded true + cut_plan_digest +
  re_run_equal true.

3. Explicit write statement (required item 6)

artifact_only:        TRUE — writes ONLY the 5 files above to local ephemeral $WD/cutplan
db_write:             NONE
iu_write:             NONE (IU rows are PREVIEWED in artifacts, never inserted)
directus_write:       NONE
vector_write:         NONE
source_mutation:      NONE (snapshot/source is read-only & pinned)
production_touched:   false
net_zero_guarantee:   by construction — the S2 entrypoint MUST be import-isolated stdlib-only
  (argparse/hashlib/json/os/re/sys/pathlib), MUST NOT import db_adapter/phases/ledger/signal,
  MUST make no network call (same discipline & TestNoDbImportIsolation as dryrun.py).

doc 2 of 5. Nothing executed. Self-advance PROHIBITED.