dot-iu-cutter v0.1 — Manifest and Operator Contract (D2)

Date: 2026-05-15 Status: DESIGN DRAFT Baseline: rev5d Scope: DESIGN ONLY.

---

1. Purpose

Define the manifest that MARK produces, REVIEW inspects, and CUT consumes. Define the operator contract governing who may emit, review, approve, and rollback. Manifest is the single artifact bridging segmentation decision to execution; it is manifest-as-code (Đ38).

2. Scope

• Manifest field definition (logical contract, not DDL)
• REVIEW checklist
• Operator/reviewer roles per Đ37
• Risk gating per Đ32
• Persistence pattern (PG-first; markdown mirror)

Out of scope: split/merge manifests (D3), thread membership manifests (D9), capability intake records (D4).

3. Dependencies

• D1 (operational design)
• rev5d §7.B, §7.C, §13.3
• C1A segmentation law (3-question test, SR, OD-PILOT)
• Đ24 (vocabulary), Đ32 (risk), Đ37 (roles), Đ38 (manifest as code), Đ0-G (birth gate)
• Existing TAC schema (tac_logical_unit, tac_unit_version, tac_publication)

4. Key Decisions

4.1 Manifest Is Code (P3, Đ38)

A manifest is a versioned PG row + JSONB envelope. Every manifest:

• Has a deterministic manifest_id.
• Has manifest_version (semver-style).
• Is diffable against prior versions of the same source.
• Carries provenance (who, when, by which tool revision).
• Is reviewable as a code artifact: review = diff over fields.

4.2 Manifest Field Set (Q4)

The manifest is a structured envelope with header + per-unit blocks.

Header fields (manifest-level):

Field	Purpose
manifest_id	Deterministic ID
manifest_version	Semver-style
source_path	KB path or TAC source identifier
source_revision	Exact revision marker
source_kind	law, design, requirements, code, report, runbook, etc.
tool_revision	dot-iu-cutter revision that emitted this manifest
emitted_by	actor (system / user / agent)
emitted_at	timestamp
C1A_rule_refs	which SR/OD-PILOT/NL rules applied at manifest level
body_source_policy	how body content is sourced per unit
collision_status	none / prior_cut_present / supersedes (with refs)
risk_class	Đ32 risk class
review_required	bool (false only for low-risk single-command path)

Per-unit block fields (Q4):

Field	Purpose
unit_local_id	Within-manifest unit ID
source_span_start / source_span_end	Byte/line span in source
title	Unit title (C1A "clear title" requirement)
section_type	From Đ24 vocabulary; if missing → vocabulary gap
unit_kind	From Đ24 vocabulary
parent_unit_id	Canonical parent (one canonical parent rule)
hierarchy_depth	Integer
body_source_policy	inline / referenced / generated
C1A_rule_refs	Which SR/OD-PILOT applied
three_question_test_result	clear_title / independently_editable / not_too_hard_to_edit, each bool + note
cut_reason	Free text, structured tag set
confidence	numeric or banded
length_flag	within_band / over / under
edge_readiness_notes	Hooks for D6 axis-2 metadata
review_flags	List of explicit reviewer-attention items
semantic_role	If determinable (links to D6/D9)
candidate_edges	Pre-marked edges to existing units, for KG hooks
render_order	For axis-1 reconstruction
canonical_address	Stable address (e.g. "Đ44 §5.3.1")

4.3 Boundary Rules (Q5)

Boundaries are determined by C1A, not by mechanical splitting:

1. C1A 3-question test (clear title? independently editable? not too hard to edit?).
2. SR-1 through SR-7 (semantic rules).
3. OD-PILOT-01 → 06.
4. NL1–NL4 length rules.
5. CI-1 → CI-12.
6. No mechanical A/B/C splitting.
7. One unit = one canonical parent.
8. Birth gate readiness (Đ0-G) per unit.

If a boundary cannot be justified by an explicit rule citation, REVIEW must reject.

4.4 Vocabulary Discipline (Q6, Đ24)

• section_type and unit_kind come only from the Đ24-controlled vocabulary.
• If MARK encounters an artifact whose section type is not covered, it MUST emit vocabulary_gap and route the manifest to NEEDS_HUMAN; it must NOT invent terminology.
• Vocabulary gaps go to Decision Backlog Registry (D5).

4.5 Heading / Container / Body Policy (Q7)

body_source_policy per unit declares:

• inline — the body text lives in this unit.
• container — this unit owns title + structure; body in child units.
• referenced — body is external (TAC reference, publication snapshot).
• generated — body produced by a deterministic rule (rare; must justify).

A container unit MUST have children; a body-bearing unit MUST have non-empty body span. REVIEW enforces.

4.6 REVIEW Contract (Q9, Q10)

REVIEW checklist (a manifest passes only when ALL hold):

1. No-loss: union of source spans equals source coverage (modulo declared excluded regions).
2. No-overlap: pairwise span intersection is empty (except for declared containment).
3. C1A 3-question test passes per unit.
4. C1A SR / OD-PILOT / NL / CI rule citations are valid.
5. Vocabulary is Đ24-conformant (or vocabulary_gap is raised).
6. Canonical parent uniqueness holds.
7. Birth gate readiness per Đ0-G.
8. Length flags within policy or escalated with reason.
9. Edge readiness notes are present for non-trivial units (axis-2 hook).
10. Body source policy is consistent with children/parents.

REVIEW emits PASS / FAIL / NEEDS_HUMAN with structured findings.

4.7 Independent Review (Q8, P2)

• Default reviewer is an independent AI in a separate execution context.
• Human review escalation per Đ37: ambiguity, new vocabulary, suspected data loss, legal/governance change, high-risk per Đ32.
• The reviewer identity (AI revision + context fingerprint or human ID) is recorded on the manifest envelope.

4.8 Risk Gating (Đ32)

risk_class is computed from:

• Source kind (law > design > requirement > report > runbook).
• Source authority (enacted > draft > runtime).
• Collision status (supersession > prior_cut > none).
• Vocabulary novelty.
• Length and overlap patterns.

High-risk manifests REQUIRE human review (cannot be PASSed by AI alone). Manifest-level review_required = true is sticky once set.

4.9 Persistence (Q21, P14)

• Manifest envelope: PG row in TAC schema (target DB: directus; layer: Kho).
• Per-unit blocks: child rows or JSONB array (final shape pending Đ33/Đ43 placement in D7/D10).
• Review decision: separate PG row referencing manifest_id + manifest_version.
• KB markdown export is a mirror for human reading and diff; not authority.

4.10 Operator Contract

Role	Permissions	Reference
User	Issue command, override AI rejection with rationale, request human review	Đ37
Independent AI Reviewer	PASS/FAIL/NEEDS_HUMAN	Đ37
Council / Human Reviewer	Final PASS on high-risk or escalated manifests	Đ37, Đ32
Executor (dot-iu-cutter)	Emit MARK; consume PASSed manifest; emit CUT	D1
Verifier (dot-iu-cutter-verify)	Independent VERIFY; co-sign REPORT	D1 §4.14
Decision Backlog Registry	Receive gaps and escalations	D5

4.11 Diffability

Manifests are diffable across versions:

• Field-level diffs against prior manifest_version of the same source_path × source_revision.
• Cut-time diffs against the actual tac_logical_unit rows produced.

Diffs are governance artifacts: REVIEW uses prior-version diff to limit re-review surface.

4.12 No Auto-Merge from Manifest

Manifest cannot itself trigger merges of existing units. Merges are F2 (D3) — they require usage evidence and a separate lifecycle. This preserves P5 and acceptance criterion 8.

---

5. PG Storage per Object (Design Intent — No DDL)

Object	Target DB	Layer	Notes
Manifest envelope	directus (TAC schema)	Kho	SSOT, versioned
Manifest per-unit block	directus (TAC schema)	Kho	child rows or JSONB
Review decision	directus (TAC schema)	Não	PASS/FAIL/NEEDS_HUMAN + findings
Reviewer identity	directus	Não	AI rev or human ID
Risk class	directus	Não	computed at MARK time
Manifest diff	directus	Não	derived view

6. Schema Gaps

1. manifest_envelope table — distinct from tac_logical_unit; needs placement decision per Đ33/Đ43 (D10).
2. manifest_unit_block — per-unit child rows or JSONB array; shape unconfirmed.
3. review_decision — reviewer identity, findings, status.
4. vocabulary_gap_register — Đ24 gaps from MARK; routes to Decision Backlog.
5. risk_class field — Đ32 risk classification on manifest header.
6. reviewer_identity field — independence provenance.
7. manifest_diff materialized view — version-to-version diff.
8. canonical_address formatting — current TAC schema may lack canonical_address as a first-class column.
9. body_source_policy enum — vocabulary placement per Đ24.

7. Law References

Surface	Law
Segmentation rules	C1A
Vocabulary	Đ24
Risk gating	Đ32
Roles, escalation	Đ37
Manifest as code	Đ38
Birth gate	Đ0-G
PG placement	Đ33 / Đ43

8. Open Questions

1. Should per-unit blocks be child rows or JSONB? Trade-off: queryability vs flexibility. Final answer in D7 / D10.
2. How is vocabulary additionally surfaced when Đ24 itself needs extension (vocabulary-of-vocabulary)? Defer to Đ24 governance.
3. How does manifest_diff handle reorderings vs renames? Recommend deferring to a diff specification subdoc.

9. Coverage

Questions covered (primary): Q4, Q5, Q6, Q7, Q8, Q9, Q10, Q21. Questions covered (secondary): Q11, Q31, Q32.

Acceptance criteria covered:

• 3 (manifest as code)
• 4 (independent review pre-cut)
• 5 (round-trip — supporting D1)
• 6 (rollback — supporting D1)
• 18 (dogfood TAC)
• 27 (PG-driven manifest persistence)
• 29 (separates schema gaps from impl)

Schema gaps: 9 named (see §6).

Law dependencies: C1A, Đ24, Đ32, Đ33/Đ43, Đ37, Đ38, Đ0-G.

Open questions: 3 (see §8).

Law conflicts encountered: none.