01 — Operational flow: MARK → REVIEW → CUT → VERIFY

This document defines the four stages, their inputs, outputs, and gates. Every later doc in this package refers back to a stage defined here.

0. Visual

┌────────────────────┐   user request    ┌───────────┐   proposal    ┌──────────┐
│  Stage 0 — REQUEST │ ────────────────▶ │ Stage 1 — │ ────────────▶ │ Stage 2 —│
│  (User → Agent)    │                   │   MARK    │  (cut_manifest)│  REVIEW │
│  link + article #  │                   │  (Agent)  │  status=pending│ (Operator)│
└────────────────────┘                   └───────────┘                └────┬─────┘
                                                                          │ approve
                                                                          ▼
                          ┌──────────────────────────┐         ┌────────────────────┐
                          │ Stage 4 — VERIFY         │ ◀────── │ Stage 3 — CUT      │
                          │  reconstruct + axis      │         │   (DOT / system)   │
                          │  + rollback report       │         │   approved manifest│
                          └──────────────────────────┘         └────────────────────┘

1. Stage 0 — User request

The user provides minimal input:

Đánh dấu cắt Điều 37, 38, 39 từ các link sau:
- Điều 37: https://example.gov.vn/luat/.../dieu-37
- Điều 38: https://example.gov.vn/luat/.../dieu-38
- Điều 39: https://example.gov.vn/luat/.../dieu-39

The user may provide any of:

• an exact URL;
• a local source file path;
• inline source text;
• a path to an already-pinned source manifest in KB.

The user does NOT provide (unless correcting an Agent draft):

• SQL;
• tags;
• source_position numbers;
• piece IDs;
• boundary quotes.

If the user input is ambiguous (no link, no source, no article numbers), the Agent stops at Stage 1.0 (precheck) and asks one clarification question only.

2. Stage 1 — MARK (Agent)

2.1 Goal

Produce a cut_manifest that proposes how the requested article(s) will be cut into pieces, with all three axes drafted, plus a reconstruction preview.

2.2 Inputs

• The Stage 0 user request.
• The source content (fetched read-only from the URL/file provided).
• The current substrate vocabularies (loaded from KB or DB read-only):
  • unit_kind ∈ {design_doc_section, law_unit};
  • section_type ∈ vocabulary defined by iu_core_section_type_vocab (e.g., article, paragraph, clause, definition, …);
  • piece_role ∈ {title, intro, body, step, clause, appendix, reference};
  • Axis-B kinds = {legal_document, section_type, unit_kind};
  • link_role (for SQL bridges) ∈ 11-role vocab; default represents.

2.3 Outputs

• One cut_manifest.json (schema in 03-cut-manifest-schema.md).
• One Markdown report mark_report.md summarizing decisions, ambiguities, and the reconstruction preview.
• One coverage_proof.json (if multi-article): asserts every article in the request appears in manifest.articles[].

2.4 Forbidden side effects

• No INSERT / UPDATE / DELETE against any DB.
• No call to fn_iu_create, fn_iu_compose, fn_iu_collection_add_piece, etc.
• No file uploaded to KB until Stage 1.5 (artifact upload after MARK completes).
• No assertion that "CUT is done" or "IU created".

2.5 Steps (high level — see 02-agent-mark-instructions.md for full procedure)

1. Precheck request shape.
2. Fetch source.
3. Confirm the article label(s) exist in the source.
4. Extract article body byte-for-byte (normalized whitespace OK; original hash kept).
5. Propose piece segmentation (one piece per leaf clause/paragraph).
6. Assign source_position, parent_local_piece_id, depth, unit_kind, section_type, axis_a/b/c draft.
7. Build reconstruction preview from the proposed pieces (concatenate by source_position ascending) and assert it equals the normalized source.
8. Compute manifest_digest = sha256(canonical_json(manifest)).
9. Emit outputs to --out-dir (ephemeral scratch).
10. Upload the manifest + report to KB; mark approval.status = pending.

2.6 Stop conditions

• Source URL unreachable → STOP, report source_unreachable.
• Article label not found in source → STOP, report article_not_found.
• Reconstruction preview not byte-equal to normalized source → STOP, report reconstruction_mismatch.
• Any ambiguous piece boundary the Agent cannot resolve → STOP with uncertainty_flags[] populated; let the operator decide in Stage 2.

3. Stage 2 — REVIEW / APPROVE (Operator)

3.1 Goal

A human (or a DOT review function with its own approval policy) decides whether the proposed manifest may proceed to CUT.

3.2 Inputs

• The manifest emitted in Stage 1.
• The mark_report.md.
• The 04-review-approval-checklist.md from this package.

3.3 Outputs

• Either:
  • APPROVED: approval.status = approved, approved_by and approved_at filled, manifest re-uploaded to KB at a stable path; the approval doc id is recorded.
  • REJECTED: rejection reason recorded, Agent re-runs MARK with the feedback.

3.4 What the reviewer checks

See 04-review-approval-checklist.md. In one line: source link correctness · article boundary · piece count plausibility · source_position density · parent/child structure · Axis B tags · reconstruction preview byte-equal · all uncertainty flags resolved.

3.5 Gate

The CUT command in Stage 3 refuses to run unless all of these are satisfied:

• manifest.approval.status == 'approved';
• approved_by references a known operator/DOT identity;
• approved_at is within the freshness window (≤ 24 h by default; configurable);
• manifest_digest recomputed by CUT matches the digest at the time of approval (byte-stable).

4. Stage 3 — CUT (DOT / system)

4.1 Goal

Atomically create durable IU rows from the approved manifest. Only stage that mutates production.

4.2 Inputs

• An approved cut_manifest.
• Approval KB doc id passed via --approval-doc-id (G1 gate).
• Pinned digests passed via --expect-manifest-digest (G2 gate).
• The current DB connection as a permitted principal (workflow_admin for IU core writes, per 70000x channel discovery; or directus for non-IU writes).
• Backup gate: a fresh pg_dump within ≤ 60 min (G7 gate).

4.3 Code path

• dot_iu_cut_from_manifest (DOT command, registered in dot_iu_command_catalog).
• Implementation: a guarded wrapper around fn_iu_compose (for collection-as-IU instances) and fn_iu_create (for new pieces), called in one atomic transaction.

4.4 Outputs

• Durable rows in information_unit, iu_piece_membership, iu_piece_collection, iu_metadata_tag, optionally iu_sql_link.
• One row in dot_iu_command_run (audit row, column command_name).
• A cut_execution_log.md (operator-visible) plus a rollback_plan.json keyed on manifest_id.

4.5 Forbidden inside CUT

• Any write to production_documents.
• Any DDL (no CREATE TABLE, no ALTER, no trigger install).
• Any GRANT.
• Any production write outside the manifest's declared pieces.
• Any retry without a fresh operator sign-off.

4.6 Atomicity

BEGIN;
  -- one fn_iu_compose call per article
  -- each call mints pieces and attaches them
  -- audit row INSERT
COMMIT;

If any guard or any internal SQL raises, the entire transaction rolls back; no partial state remains. This is the [[feedback-in-tx-gate-toggle-reversibility]] pattern proven 12000x–70000x.

5. Stage 4 — VERIFY (automatic, post-CUT)

5.1 Goal

Prove that the CUT produced exactly what the manifest specified, and that no governed invariant is violated.

5.2 Inputs

• The manifest used by CUT (with approval + cut_at + cut_iu_ids filled in).
• A read-only connection.

5.3 Checks (read-only SQL)

#	Check	Source
V1	Axis A: fn_iu_reconstruct_source(article_label) returns N pieces with monotonic source_position, no holes; normalized concat equals manifest.articles[].original_text_hash.	T01 of six-flow runner
V2	Axis B: every piece has at least one tag in axis-B kinds (legal_document, section_type, unit_kind).	T02
V3	Axis C: fn_iu_subtree(root) returns depth ∈ {0,1,2}, child count matches manifest's parent_local_piece_id graph.	T03
V4	No cross-IU vector writes (Qdrant iu_core_iu_chunks count unchanged).	regression matrix
V5	production_documents row count unchanged.	regression matrix
V6	All 11 IU-core write gates remain inert after VERIFY ends.	regression matrix
V7	A dot_iu_command_run row exists for this CUT with command_name='dot_iu_cut_from_manifest'.	DOT-991/DOT-992 invariants
V8	If any SQL bridge was declared, iu_sql_link validator returns resolved=true for each.	T06

5.4 Outputs

• verify_report.md (PASS/FAIL per check + per-piece evidence).
• KB upload of the verify report alongside the cut artifacts.

5.5 If V1–V8 PASS

The CUT is considered durable. The manifest's approval.status transitions to verified (record-only; no further DB mutation).

5.6 If any V check FAILs

Run rollback_plan.json to retire/supersede the newly-created pieces (using fn_iu_piece_retire / fn_iu_piece_supersede). Re-VERIFY; emit the rollback report. Investigate root cause before re-attempting CUT.

6. Authority matrix

Stage	Who can authorize
0 (request)	Any user
1 (MARK)	Agent runs autonomously; no production authority needed
2 (REVIEW)	Operator with KB write access; or DOT dot_iu_manifest_review
3 (CUT)	Approved manifest + operator sign-off + backup gate; principal workflow_admin for IU writes
4 (VERIFY)	Auto, on CUT completion; read-only

7. Self-advance prohibition

An Agent performing MARK must not advance itself to CUT, even if it believes the manifest is obviously correct. The review gate exists to catch source mis-attribution, boundary errors, and Axis B/C drift that the same Agent cannot detect by re-reading its own output. This rule is non-negotiable.

See 02-agent-mark-instructions.md for the Agent's per-step procedure.