Master Design Rev2 — 08 Addendum: Bidirectional Flow + Kaizen + MOT/JFT + Governance-at-Scale (MP-D11..MP-D15)
Master Design Rev2 — Bidirectional Data Flow + Kaizen Intake + MOT/JFT + Governance-at-Scale (Addendum)
Path:
knowledge/dev/design/v0.6-iu-4mothers-event-foundation-rev2/08-bidirectional-input-kaizen-governance-addendum.mdStatus: DRAFT Rev3 patch addendum (DOCUMENT ONLY). Companion to00-master-design-rev2.md. Materializes patch pack MP-D11..MP-D15. Hardened by09-…(rev4 MP-D16..MP-D22) — see §14 cross-link: MP-D17 gives the governance cockpit (§7) its problem-queue lifecycle; MP-D18 gives Kaizen (§5) its anti-noise/duplicate lifecycle; MP-D19 gives the input gateway (§3) its direct-canonicalization guardrails; MP-D20 gives a Minimum Observability Profile; MP-D16 maps the MOW T6→T1 hierarchy (§4) onto the Điều 5 five-tier architecture; MP-D22 adds the Governance Ops Survey. Cross-law-bound by10-…(rev5 MP-D23..MP-D30) — see §15: the staging-review (§3), Kaizen widget (§5), MOW canvas (§4) and cockpit (§7) surfaces are Điều 28 templates; the artifacts they generate follow Điều 36/0-G/29 birth. Date: 2026-05-28 (rev3) · cross-linked 2026-05-28 (rev409-…) · cross-linked 2026-05-28 (rev510-…) Authority: MacroIU_4MOTHERS_MASTER_DESIGN_MP_D11_D15_INPUT_KAIZEN_GOVERNANCE_DOCUMENT_ONLY_6000X. Built strictly on Rev2 brief authority + Master Design Rev2 invariants. No new law surface introduced. Future framework law referent = future Điều XX (4 Mothers application layer); Điều 34 cited only as decision-path (per MP-D10). Boundary: Hiến pháp v4.6.3 (PG-first / DOT 100% / no hardcode / no hidden SoT), Điều 7 (Assembly First), Điều 28 (Nuxt render/input shell), Điều 30 (reversibility), Điều 31 (integrity/audit), Điều 32 (approval/governance), Điều 33 v2.1 (3-layer / Nuxt never reads PG), Điều 35 (DOT governance), Điều 37 (governance org), Điều 38/39 (IU/KG ownership), Điều 45 (event/queue/state-machine boundary). Master Design Rev2 invariants 1..20 (00-…§3) are preserved verbatim. Forbidden in this macro (binding): No PG mutation. No Directus mutation. No Qdrant/vector write or reindex. No migration. No DOT command run. No law enactment / drafting. No implementation macro. No UI deployment. No final OSS tool selection. No raw SQL apply. Nodot_configgate change. No schema creation. No code generation. The schemas listed below are paper-only.
§1. Why this addendum exists
Master Design Rev2 (revision 2 / MP-D1..MP-D10) is correct on read-side architecture (PG → Directus → Nuxt), state machines, event 5-layer, and IU body singleton. The reviewer-followup target (IU_4MOTHERS_MASTER_DESIGN_MP_D11_D15_…) widens the design so the same infrastructure also supports:
- A unified MOW hierarchy UI from T6 down to T1 that staff can navigate (10–20 tasks/day) and super-admin can drill through without the MOW canvas becoming a 20 000-task cockpit.
- Kaizen proposal intake simple enough that any staff member (no BPMN, no schema, no form-builder vocabulary) can click "Đề xuất cải tiến → Thêm/Sửa/Xoá → vị trí → comment/audio → gửi".
- Bidirectional data flow with an explicit input/staging architecture — read path stays
PG → Directus → Nuxt; write path isNuxt → Staging → Processing (direct | workflow) → PG canonical; Nuxt never writes PG. - MOT as a JFT (Just-For-This-Task) envelope — fixed task frame assembled from a matrix/config so the system can generate thousands of right-task / right-person / right-time tasks without bespoke code per task family.
- Governance at scale for both staff (10–20 items) and super-admin / AI-agent ops (20 000+) without reusing the MOW canvas as the super-admin UI.
Each item is captured as a patch (MP-D11..MP-D15) anchored to the existing law/invariant matrix and the existing PG substrate. No new ownership boundary is introduced; only the future Điều XX referent already documented in Master Design Rev2 §11 + §13 carries the application-layer concern.
This addendum is mandatory reading alongside 00, 02, 03, 04, and 06. The patch text in those files cross-links here.
§2. Top-line invariants added (extending 00-… §3)
These are additive — they do not relax or replace any of the existing 20 invariants in 00-… §3. They are numbered I21..I30 to preserve numbering continuity.
- I21. Bidirectional flow with single SoT. Read path =
PG → Directus → Nuxt; write path =Nuxt → Staging → Processing → PG canonical. PG is the only SoT for canonical artifacts. Directus and any staging collection are NOT SoT; they are mediation surfaces. (MP-D11.) - I22. Nuxt never writes PG and never holds business logic. Nuxt is render shell and input shell only (Điều 28). All input goes through a backend gateway / API into staging or directly into a typed RPC; Nuxt does not embed schema validation beyond a thin client-side echo of backend rules. (Điều 28 + Điều 33 v2.1.)
- I23. Staging is mediation, not SoT. A staging row is a proposal-shaped envelope (paper schema
input_submission/proposal) carrying raw text/audio/attachments + captured context + processing branch. Canonicalization (direct ingest OR workflow approval) is what writes to canonical PG; staging row is closed by reference (canonical_target_ref) or rejected with reason. (MP-D11.) - I24. Refs-only event payloads still hold. Events emitted at submission, validation, canonicalization, rejection carry refs only (staging_id, proposal_id, target_artifact_ref, trace_id, correlation_id). Raw text/audio/attachment bytes never travel in event_outbox — they live in staging columns / file_ref tables; workers fetch by ref. (Extends
00-…§3 inv 6 +03-…§3.3 MP-D8 deny-list to staging-originated events.) - I25. Unified MOW hierarchy T6→T1, one canvas pattern per tier. Tabs T6..T1; same card primitive at every tier; selected tier determines card meaning; child rows = next lower tier. T0 (field) is the atomic schema layer underneath T1 (task), not an official tier. (MP-D12.)
- I26. Kaizen intake stays simple. Five clicks max:
Đề xuất cải tiến → Thêm|Sửa|Xoá → chọn vị trí → comment/audio → gửi. Auto-capture every backend-relevant context (tier, breadcrumb, node id, parent id, insert position, edge id, IU/bundle refs, workflow/step/task def + run refs, actor, role, department, permission scope, timestamp, trace_id, correlation_id, screen context, filters, intent). The user does not need to understand BPMN, registry shape, queue, event, or schema. (MP-D13.) - I27. MOT/JFT envelope from matrix. Every task instance is materialized from a
task_template×(IU/bundle, MOIT contract, MOUT contract, trigger, assignee policy, deadline policy, executor class, state machine, dashboard target, permission scope, escalation policy)matrix row. The MOT envelope has fixed regions (header / input / reference / instruction / action / state-deadline-escalation). Tasks appear only when actionable for the assignee and disappear when done (JFT). (MP-D14.) - I28. Four separated UI surfaces. (1) Personal JFT Dashboard, (2) MOW Hierarchy Canvas T6→T1, (3) Governance Cockpit (problem-first, severity-based, SLO/SLA), (4) AI/Agent Ops Console. MOW Canvas is not a super-admin 20 000-task cockpit. Governance Cockpit is the high-volume super-admin / AI-agent surface. (MP-D15.)
- I29. Governance Cockpit is aggregate-first / problem-first / drill-down only. No raw event noise. AI/worker summaries carry the MP-D9 evidence rule (source_event_count ≥1, time_window, generated_by, confidence, source_event_refs). Drill-down via
vw_audit_event_timeline(trace_id). Same component, backend permission filter (Điều 37 v3.3). (MP-D15 + extends00-…§3 inv 16.) - I30. Proposal/input lifecycle never bypasses approval boundary. Direct-branch input writes only artifacts whose contract permits direct ingest (e.g.
task_comment,audit_note,input_submissionof staff-scope data). Workflow-branch input always routes throughworkflow_change_requests(workflow proposals) orproposal(non-workflow proposals); both gated by Điều 32 governance for impactful changes. KG / Kaizen never mutates canonical registries directly (extends00-…§3 inv 14). (MP-D11 + MP-D13.)
These ten invariants are binding on every WS file in the package and on every future macro that touches input, Kaizen, MOT, or governance UI.
§3. MP-D11 — Bidirectional data flow + staging input architecture
§3.1 Two halves of the data plane (binding diagram)
READ PATH (existing, unchanged)
┌────────────────────────────────────────────────────────────────────────┐
│ PG (SoT) → backend gateway → Directus collections / views │
│ ↘ │
│ → realtime gateway (event_outbox tail, governed) │
│ │
│ ↓ HTTP / SSE │
│ Nuxt (render shell) │
└────────────────────────────────────────────────────────────────────────┘
WRITE / INPUT PATH (new explicit shape, MP-D11)
┌────────────────────────────────────────────────────────────────────────┐
│ Nuxt (input shell, zero business logic) │
│ ↓ HTTP submit (refs + raw text / audio_ref / attachments_ref) │
│ Backend input gateway (Node service; Điều 28 / Điều 33 v2.1) │
│ ↓ validates envelope shape + permission + size cap │
│ Staging collection = input_submission OR proposal (paper schema) │
│ │ (text + audio_ref + attachments_ref; captured_context_jsonb) │
│ │ │
│ ├──── processing_branch = 'direct' ─────────────┐ │
│ │ (config-permitted artifact kinds only) │ │
│ │ canonicalizer worker ▼ │
│ │ ↓ PG canonical │
│ │ (writes canonical row) (task_comment / │
│ │ audit_note / │
│ │ input_submission_ack) │
│ │ │
│ └──── processing_branch = 'workflow' ───────────┐ │
│ (Kaizen / proposal / multi-step intake) │ │
│ route to workflow_change_requests or │ │
│ generic `proposal` (per OD2 / `06-…` §S2)│ │
│ ▼ │
│ Điều 32 approval │
│ ▼ │
│ canonicalizer worker │
│ ↓ │
│ PG canonical (mutation │
│ via DOT pair per Điều 35)│
└────────────────────────────────────────────────────────────────────────┘
The two halves share no path: read traffic never carries write authority, and write traffic never bypasses staging or governance. Directus never writes canonical PG; Directus may host staging collections as admin UI but those collections are not SoT.
§3.2 Generic staging shape (paper-only)
input_submission
staging_id uuid PK
input_kind text -- 'kaizen_add' | 'kaizen_edit' | 'kaizen_delete' |
-- 'task_comment' | 'task_attachment' |
-- 'workflow_proposal' | 'iu_split_request' |
-- 'iu_merge_request' | 'moit_field_request' |
-- 'mout_view_request' | 'audit_note' |
-- 'generic_question' | ...
source_actor_id uuid -- principal who submitted
source_role text -- role at submission time (Điều 37 v3.3 ref)
source_surface text -- 'mow_canvas' | 'jft_dashboard' |
-- 'governance_cockpit' | 'mot_envelope' |
-- 'mout_view' | 'kaizen_inline'
hierarchy_context jsonb -- {tier ∈ T6..T1, breadcrumb[], department_id, lane_ids[]}
target_artifact_ref jsonb -- {kind, id, parent_id, edge_id?, insert_position?}
-- kind ∈ {'workflow_def_step','workflow_def_edge',
-- 'iu','iu_bundle','task_def','moit_field',
-- 'mout_block','mow_node','mot_region',
-- 'governance_metric','none'}
intent text -- 'add' | 'edit' | 'delete' | 'comment' | 'question' | 'flag'
raw_text text nullable
audio_ref text nullable -- pointer to file blob (audio_file_registry, paper)
attachments_ref text[] nullable -- pointers to file blobs (attachment_registry, paper)
captured_context_jsonb jsonb -- ALL auto-captured backend context (see MP-D13 §5.3)
validation_status text -- 'pending' | 'valid' | 'invalid' | 'needs_clarification'
validation_reason_code text nullable
processing_state text -- 'received' | 'queued' | 'in_progress' |
-- 'canonicalized' | 'rejected' | 'expired'
processing_branch text -- 'direct' | 'workflow' | 'undecided'
canonical_target_ref jsonb nullable -- {kind, id} once canonicalized (direct branch)
proposal_ref uuid nullable -- FK -> proposal | workflow_change_requests
-- (workflow branch)
rejection_reason text nullable
trace_id text -- W3C 32-hex (MP-D1)
parent_span_id text
trace_flags text
correlation_id uuid
created_at timestamptz
closed_at timestamptz nullable
Notes:
- Two-stage envelope. Raw artifact bytes (text / audio / attachments) live on the staging row; the downstream events carry only refs (
staging_id,target_artifact_ref,proposal_ref,canonical_target_ref, trace IDs). MP-D8 deny-list applies to every emitted event around input lifecycle. - No second SoT.
input_submissionis mediation. Canonical row writes (task_comment, proposal row, workflow_change_requests row, audit_note, etc.) are the only SoT-eligible writes; canonicalizer worker performs them through DOT or RPC routes per Điều 35. - Reversibility (Điều 30). Staging row can be reversed (
processing_state='rejected'+rejection_reason) without leaving canonical residue, because no canonical write happens until canonicalization. If canonicalization already happened, the canonical write itself carries reversibility per its own contract (e.g. proposal row can be withdrawn pre-approval).
§3.3 Direct vs workflow processing branch
The branch is decided at the gateway by configuration; Nuxt does not choose. Config table (paper):
input_routing_policy
input_kind text PK
default_branch text -- 'direct' | 'workflow'
permitted_actor_roles text[]
permitted_target_kinds text[]
size_caps_jsonb jsonb -- max_raw_text_bytes, audio_max_seconds, attachments_max_count
canonicalizer_executor_class_ref text -- FK -> executor_class_registry
approval_policy_ref text nullable -- FK -> Điều 32 policy
active bool
Default routing:
| input_kind | default_branch | Reason |
|---|---|---|
task_comment |
direct | Comment on a task the user already has access to; ingest as task_comments row. |
task_attachment |
direct | Bind to existing task; permission already established. |
audit_note |
direct | Append-only audit; per-actor scope. |
kaizen_add / kaizen_edit / kaizen_delete (on workflow graph) |
workflow | Targets workflow_change_requests; needs Điều 32. |
kaizen_add / kaizen_edit / kaizen_delete (on IU / MOT / MOIT / MOUT) |
workflow | Targets generic proposal (per OD2 / 06-… §S2). |
iu_split_request / iu_merge_request |
workflow | KG proposal; Điều 32-gated. |
moit_field_request / mout_view_request |
workflow | Schema-impactful; Điều 32 + MP-D7 sentinel (CRS gate). |
generic_question |
direct | Routes to support / governance queue without mutating canonical structure. |
Sentinel: any direct-branch ingest whose target row is not in input_routing_policy.permitted_target_kinds MUST be refused at gateway with reason direct_branch_not_permitted_for_kind.
§3.4 Event family for input lifecycle (paper, register-before-emit per 03-… §3.1)
| event_type | Trigger | Payload (refs only) |
|---|---|---|
input.submitted |
gateway accepts input_submission row | staging_id, input_kind, source_actor_id, source_role, source_surface, target_artifact_ref, processing_branch, trace_id |
input.validated |
validator passes | staging_id, validation_status='valid', trace_id |
input.rejected |
validator/canonicalizer refuses | staging_id, validation_reason_code/rejection_reason, trace_id |
input.queued_for_canonicalization |
direct branch enters worker queue | staging_id, canonicalizer_executor_class_ref, trace_id |
input.canonicalized |
direct branch worker writes canonical row | staging_id, canonical_target_ref, trace_id |
input.routed_to_workflow |
workflow branch creates proposal row | staging_id, proposal_ref, trace_id |
input.audio_transcribed |
transcription worker outputs text | staging_id, audio_ref, transcription_ref, confidence, trace_id |
input.attachment_indexed |
attachment indexing complete | staging_id, attachment_ref, trace_id |
All payloads obey MP-D8 deny-list (no body_text, payload_blob, raw audio, raw attachment bytes). Audio / text / attachments are fetched by worker via the staging row, never carried in event payload.
§3.5 IU/PG/queue relationship across input flow
- IU body remains singleton. No input writes IU body text into an event or a staging-row downstream payload. Kaizen proposals reference IU by
iu_unit_id(+ optional version pin); Edit proposals carry the user's suggestion as araw_textblob in staging only — canonicalization (post-approval) creates a newiu_versionrow through Điều 38/39 surface using the regular author lifecycle. - Queue carries refs only. Worker queue rows for canonicalization carry
staging_id+executor_class_ref+idempotency_key+ W3C trace. Body / audio / attachment fetched from PG/file registry by worker. - Event 5-layer reuses producer taxonomy.
input.*events sit under producer classinput_gateway(new entry under03-…§3.2). Subscriber classes: canonicalizer worker (job_dispatch), governance cockpit (realtime_topic), audit (fanout).
§3.6 Permission and audit
- Gateway records
source_actor_id,source_role,permission_scope_hashat submit time. Identical torender_iu_bodyMP-D6 cache key shape so downstream notifications and drill-down obey recipient-scope. - Every staging row is auditable via
vw_audit_event_timeline(trace_id)joiningevent_outbox+input_submissionlifecycle.
§3.7 Reversibility (Điều 30)
- Staging row prior to canonicalization → reversible by gateway rejection.
- Workflow branch prior to approval → reversible by withdraw on
workflow_change_requestsorproposal. - Direct-branch canonical row (e.g. task_comment) → reversible per its own table semantics (soft delete + audit).
- IU-altering canonicalization always reroutes through Điều 38/39 author lifecycle (carries its own versioning + KG impact analysis).
§4. MP-D12 — Unified MOW hierarchy canvas T6→T1
§4.1 Tier vocabulary
| Tier | Name | Card meaning when selected | Children shown | Cap-binding hint |
|---|---|---|---|---|
| T6 | Lĩnh vực (Domain) | A business domain (e.g. Tài chính, Vận hành, Pháp lý) | T5 companies in domain | rare; only super-admin or holding-scope users |
| T5 | Công ty (Company) | A legal/operational company | T4 departments | tenant-scope users |
| T4 | Phòng ban (Department) | A department / unit | T3 specialties | department-scope users |
| T3 | Chuyên môn (Specialty) | A specialty / function (kế toán phải thu, IT, etc.) | T2 missions / workflows in this specialty | specialty-scope users |
| T2 | Nhiệm vụ / Workflow (Mission / Workflow definition) | A workflow definition or composite mission | T1 tasks (within the workflow) | workflow author / runner |
| T1 | Task (Task instance or task template) | A task instance (when runtime) or template (when authoring) | T0 fields (when drilling into form/output) | task PIC / executor |
| T0 | Field (atomic schema layer; NOT a tier) | A single MOIT field / MOUT field; atomic schema slot | leaves; not a navigation tier | binds to field_registry (CRS-gated, MP-D7) |
T0 is the atomic schema layer underneath T1 — never used as a canvas tab. Any future tier additions (e.g. tổng công ty above T5) require Birth Registry (Điều 0-G) and a new row here.
§4.2 Canvas pattern (one component, six tier modes)
The Nuxt component <MowHierarchyCanvas tier currentNodeId /> is the only canvas component. Tier selection drives:
Top: [T6 Lĩnh vực] [T5 Công ty] [T4 Phòng ban] [T3 Chuyên môn] [T2 Workflow] [T1 Task]
(current tier highlighted)
Sub: Breadcrumb of selected node path (e.g. "Tài chính > Inc Co. > Kế toán > Phải thu > Workflow X")
Body: Card grid of nodes at the current tier
Each card shows tier-specific identity fields + traffic-light rollup of children
Click a card → drill down one tier (or open T1 task envelope at T1).
Side: Inline filters (status, owner, deadline window, severity, search)
Backend permission filter on top of every query.
Properties (binding):
- Same card primitive at every tier. Card has
title,breadcrumb_segment,metrics(children completed / children blocked / children overdue / SLA aggregate),traffic_light(red>yellow>green roll-up per02-…§5),action_chip(Đề xuất cải tiến / Mở chi tiết). No tier-specific layout fork in the component. - Card binding. Each card MAY bind one IU (instruction at this tier level — e.g. SOP for a department, mission brief for a workflow) or an IU bundle. Body renders via
render_iu_bodyper04-…§2.3 + MP-D6. - Permission scope. Backend filters which T6/T5/T4/T3/T2/T1 rows are visible per principal (Điều 37 v3.3). Super-admin sees full hierarchy but is expected to use the Governance Cockpit (MP-D15) for high-volume operational triage rather than the canvas.
- Long-list virtualization. At every tier the card grid virtualizes (same
<VirtualGrid>primitive). 5 cards or 500 cards → same component. Tier-specific labels come fromtier_registry(paper) not from component code.
§4.3 PG / Directus substrate (reuse-first)
| Tier | Source rows | Reuse / extend |
|---|---|---|
| T6 | domain_registry (paper; sits above company registry; new IF not already in workflow_categories taxonomy) |
extend workflow_categories (category_kind='domain' rows) OR new table; survey before Phase 1 |
| T5 | company_registry (paper; consult existing tenant/company table if any) |
survey before Phase 1 |
| T4 | department_registry (paper or existing) |
survey |
| T3 | specialty_registry (paper) |
survey |
| T2 | workflows + workflow_categories [VL row 16, 18] |
reuse |
| T1 | task_def + task_run (paper extensions to tasks) [VL row 19] |
reuse + extension |
| T0 | field_registry [CRS row 28] |
survey-gated; MP-D7 sentinel applies |
Reuse decision: every tier above T2 is a classification taxonomy layered on top of workflow_categories and existing department/company tables (where they exist). The MOW canvas does not introduce a new orthogonal hierarchy; it reads the existing classification graph + tenant tables. A pre-Phase-1 survey will confirm what already exists and what needs paper extension. No tier creates duplicate ownership of workflow / task / IU rows.
§4.4 What this canvas is not
- Not the super-admin 20 000-task cockpit. A super-admin who needs to triage 20 000 active tasks uses Governance Cockpit (MP-D15). MOW canvas optimizes for understanding hierarchy + navigating to a card, not for high-volume problem triage.
- Not a workflow modeler. Workflow editing happens via Proposal mode (
02-…§6.5 + §8) backed byworkflow_change_requests. Canvas hosts the Proposal mode toggle for T2 cards but does not host BPMN-style editing UX. - Not a personal task list. Personal pending tasks live in JFT Dashboard (MP-D14 + MP-D15 surface 1). Canvas may filter to "my tasks" but the optimized surface is Dashboard.
§4.5 Sentinel
- Same
<MowHierarchyCanvas>component renders all 6 tiers (T6..T1). Tier-specific rendering branches are forbidden in component code; tier-specific labels/metrics come fromtier_registryrows. - Backend permission filter on every tier query; Nuxt holds no role decisions.
- Card metrics are computed by backend rollup function (extends
fn_workflow_rollup_computesemantics to hierarchy nodes — paper).
§5. MP-D13 — Inline Kaizen proposal intake
§5.1 User flow (binding minimal)
- User clicks "Đề xuất cải tiến" on any card (any tier) or on any node/edge in a workflow graph or on any MOT region or MOUT block.
- UI asks Thêm | Sửa | Xoá.
- UI lets user click vị trí (position) — node, edge, before/after insertion slot, or "thay thế" (replace). For Sửa, the position is the existing element; for Thêm, the position is an insertion slot; for Xoá, the position is the element to delete.
- UI shows a comment box + audio record button + attachment paperclip. User types or records or attaches (any combination).
- User clicks Gửi.
That is the whole user-facing flow. No BPMN. No registry vocabulary. No schema editor. No multi-step wizard. No form-builder. No task-design dialog. The complexity is behind the gateway.
§5.2 Sentinel — UX simplicity (MP-D13 binding)
- Maximum 5 user-decisions per Kaizen submission: (a) intent (Thêm/Sửa/Xoá), (b) target/position click, (c) text or audio body, (d) optional attachments, (e) Gửi.
- The user MUST NOT be asked to select event_type, registry name, BPMN element kind, MOIT field type, MOUT block kind, workflow_def_id, step_def_id, executor_class_ref, or any internal vocabulary. All of those are derived from the click context and auto-filled.
- If the click context is ambiguous (e.g. user clicked an empty area), UI offers a short clarification ("Bạn muốn đề xuất ở đâu?") with at most 3 visible options. No deep nested menus.
§5.3 System auto-capture (binding context fields)
On submit the backend gateway populates captured_context_jsonb with every field below that resolves from the click context:
| Field | Source |
|---|---|
tier ∈ {T6..T1} |
current canvas tier or originating surface |
breadcrumb |
array of (tier, node_id, label) from current navigation state |
target_node_id |
node clicked (workflow step, IU id, MOT region id, MOUT block id, card id, etc.) |
target_parent_id |
parent in the tier/graph hierarchy |
insert_position ∈ {before, after, inside, replace, none} |
derived from click position |
edge_id (workflow graph only) |
edge id if Kaizen targets an edge condition |
iu_unit_id / iu_version_id (if applicable) |
IU bound to the target |
iu_bundle_id / iu_bundle_version (if applicable) |
bundle bound to the target |
workflow_def_id / workflow_run_id (if applicable) |
workflow context |
step_def_id / step_run_id (if applicable) |
step context |
task_def_id / task_run_id (if applicable) |
task context |
actor_id / actor_role / actor_department_id |
session + Điều 37 v3.3 |
permission_scope_hash |
hash of permission-affecting context (matches MP-D6 cache key shape) |
timestamp |
server-side now() |
trace_id, parent_span_id, trace_flags, correlation_id |
W3C (MP-D1) |
screen_context |
route path, viewport, theme |
active_filters |
filter state at click time (status, owner, deadline window, severity, search) |
intent ∈ {add, edit, delete, comment, flag, question} |
from step 2 |
raw_text, audio_ref, attachments_ref |
from step 4 |
The user contributes only intent + position click + body (text/audio/attachments). All else is auto-captured.
§5.4 Routing (Kaizen → staging → workflow_change_requests or proposal)
Kaizen submit → gateway validates envelope + permission + size caps
→ write input_submission row (input_kind='kaizen_*')
→ emit input.submitted
→ routing decision:
IF target kind ∈ workflow-graph artifacts (step, edge, condition, sub-workflow):
route_to = 'workflow_change_requests'
processing_branch = 'workflow'
ELSE IF target kind ∈ {iu, iu_bundle, mot_region, moit_field, mout_block, governance_metric}:
route_to = 'proposal' (generic, OD2 / `06-…` §S2)
processing_branch = 'workflow'
ELSE IF target kind = 'task_comment_target' (Kaizen-as-comment):
route_to = 'task_comments'
processing_branch = 'direct'
ELSE:
route_to = 'support_queue' (governance)
processing_branch = 'direct'
→ emit input.routed_to_workflow OR input.queued_for_canonicalization
- Audio inputs are not transcribed inline. A separate
worker.transcription(paper executor class) leases transcription jobs, writes back toinput_submission.raw_textviainput.audio_transcribedevent, and re-runs validation. The Kaizen submission UX never blocks on transcription. - Attachments are not indexed inline;
worker.attachment_index(paper) processes asynchronously.
§5.5 What backend does NOT do (boundary)
- The system does not auto-apply a Kaizen. Workflow-branch Kaizens land as proposals; Điều 32 approval is required to merge.
- The system does not infer schema changes from free text. Even if the user writes "thêm field 'Mã hóa đơn' kiểu string vào form ABC", the proposal still lands as a
moit_field_requestrow that an admin / reviewer must shape into a realfield_registryrow (post MP-D7 sentinel close). The user is not asked to provide schema; backend captures intent and defers shaping. - The system does not mutate the canonical graph from Kaizen for any visible target. Even comment-Kaizens that resolve to direct ingest go to
task_comments/audit_note— never toworkflow_step_def/iu_version/task_def/moit_field/mout_block.
§5.6 Sentinel checklist (MP-D13)
- A single Kaizen submission produces exactly one
input_submissionrow + at most one downstreamworkflow_change_requestsrow ORproposalrow ORtask_commentsrow (never multiple canonical mutations from one submission). - Audio bytes / attachment bytes appear in event payload zero times (MP-D8 deny-list extended to staging-originated events).
- User-facing UI strings contain zero references to internal vocabulary (BPMN, schema, registry, executor, queue, event).
- Auto-context capture is complete; missing fields are recorded as
nullwith reason incaptured_context_jsonb._missingto keep the lifecycle auditable.
§6. MP-D14 — MOT / JFT task envelope from matrix
§6.1 MOT envelope regions (extends 04-… §4.2 with action + state regions)
| Region | Purpose | Source |
|---|---|---|
| 1. Header | metadata: task identity, state, traffic-light, deadline, assignee, trace_id, permission badge | task_run row + state_machine_registry |
| 2. Input | MOIT field group(s) for whatever the actor must produce | MOIT contract via <MOITForm formId contextRef /> |
| 3. Reference / Output context | MOUT blocks: reference data, prior outputs, related IUs | MOUT contract via <MOUTBlock blockId contextRef /> |
| 4. Instruction | IU / IU-bundle render (text / video / audio / sơ đồ) via render_iu_body (MP-D6) |
IU registry + render layer |
| 5. Action | submit / save draft / cannot_complete / comment / attach / "Đề xuất cải tiến" inline | RPC routes, all governed by Điều 32 where mutating |
| 6. State / Deadline / Escalation | 9-state floor + waiting facet + countdown + escalation chain + Kaizen entry point | step_run / task_run state + state_facet_def + escalation policy |
Regions 1..4 already documented in 04-… §4.2 + Rev2 §5.2; this addendum adds region 5 (action) and region 6 (state/deadline/escalation) as explicit, named parts of the envelope so they cannot be forgotten during MOT generation.
§6.2 The matrix — what a task_template row binds
A task_template row (paper) is the matrix anchor. One row defines a class of tasks; many task_run instances materialize from one template + a runtime context (workflow_run, step_run, actor, time).
task_template
task_template_id uuid PK
task_kind text -- 'review' | 'data_entry' | 'approval' | 'reconciliation' |
-- 'configuration' | 'investigation' | 'agent_supervised' | ...
instruction_iu_or_bundle_ref jsonb -- {kind ∈ {iu, bundle, assembly_view}, ref_id, pin_policy}
moit_input_contract_ref text -- FK -> input_form_registry (CRS, MP-D7 gated)
mout_reference_contract_ref text -- FK -> output_table_registry (CRS, MP-D7 gated)
trigger_subscription_ref uuid -- FK -> event_subscription (decides when task materializes)
assignee_policy_ref text -- FK -> assignee_policy (paper)
-- e.g. 'pic_from_role.<role>' | 'pic_from_workflow_run.previous_actor' |
-- 'pic_from_agent_pool.<pool>' | 'round_robin.<queue>'
deadline_policy_ref text -- FK -> deadline_policy (paper)
-- e.g. 'fixed_24h' | 'business_calendar.+2d' |
-- 'sla_class.<class>'
executor_class_ref text -- FK -> executor_class_registry (`03-…` §5.1)
state_machine_id text -- FK -> state_machine_def (`02-…` §2.1) — typically the 9-state floor
dashboard_target text -- 'personal_jft' | 'shared_team' | 'governance_problem_queue' |
-- 'agent_ops_console'
permission_scope_ref text -- FK -> permission_scope (Điều 37 v3.3)
escalation_policy_ref text -- FK -> escalation_policy (paper)
-- e.g. 'overdue_4h_pic_manager' | 'cannot_complete_escalate_to_workflow_owner'
kaizen_enabled bool default true
active bool
created_at timestamptz
The matrix is just the cross-product of task_template × runtime context. When an event matching trigger_subscription_ref lands and assignee_policy_ref resolves to a principal, a task_run row is materialized using everything else as defaults; the resulting MOT envelope renders the six regions from refs.
§6.3 JFT semantics (binding)
- Right task. The matrix row's
task_kind+ bound IU describe exactly what is to be done. - Right person / agent.
assignee_policy_refresolves the principal. Pure-human / pure-agent / mixed (e.g. agent suggests → human approves) are all expressible by different policies + matchedexecutor_class_ref. - Right time.
trigger_subscription_refensures the task materializes only when actionable (postcondition events satisfied; precondition resolved). Tasks do NOT appear in user dashboards before the trigger fires. - Pushed only when actionable. No "preview" tasks. No "draft" tasks visible to assignee until ready.
- Disappears when done. On T8
step.completed/ task completion, MOT row leaves the personal JFT Dashboard. Audit + history preserved instep_run_state_history(MP-D3) +task_runhistory; visible via Governance Cockpit drill-down only. - Auto deadline + escalation.
deadline_policy_refpopulatestask_run.deadline;escalation_policy_reffires on overdue / cannot_complete / blocked-threshold (per MP-D4); escalation events emit through standard event 5-layer.
§6.4 Required input parameters BEFORE matrix can safely generate thousands of tasks
This is the exact gap list so a future macro can close it without surprise. For mass MOT generation to be safe, the following must exist:
task_templatetable — paper now; needs Phase 2 DDL.assignee_policyregistry — paper; needs Phase 2 DDL. Policies must be enumerable (no free-form code per template).deadline_policyregistry — paper; needs Phase 2 DDL. Same enumerability requirement.escalation_policyregistry — paper; needs Phase 2 DDL.permission_scoperegistry (Điều 37 v3.3 ref) — survey existing; extend if needed.executor_class_registry— Phase 1 per06-…§S18.state_machine_registry— Phase 1.event_subscriptionwithdelivery_kind='job_dispatch'already exists in design (03-…§4.2).- CRS gate close for
input_form_registry(MOIT) +output_table_registry(MOUT) — Phase 1 survey (G7,06-…§S16). Until VL or shape-adapter, templates may not be materialized referring to these by literal name (MP-D7 strict form). - Idempotency key per materialization —
(task_template_id, trigger_event_id)UNIQUE ontask_runto prevent duplicate JFT tasks for the same event. - Audit row per materialization —
task_runcarriesmaterialized_from_template_id+trigger_event_id+correlation_id.
Exact remaining gaps for MOT/JFT mass generation: items 1, 2, 3, 4 are paper-only; items 6, 7, 9 are dependencies tracked elsewhere; the new task_template/assignee_policy/deadline_policy/escalation_policy registries are listed in 06-… §S18 patched table.
§6.5 Boundary
- MOT is not an executor (Rev2 §11.5; preserved). MOT envelope calls
executor_class_reffromexecutor_class_registry. - MOT does not own approval (preserved). Approval calls Điều 32 surface from the action region.
- MOT does not own state machine (preserved). State transitions go through
fn_state_transition_validate(02-…§2.3). - MOT does not own queue/event (preserved). Trigger arrives via subscription; postcondition events emit via standard producers.
- MOT does not own IU body (preserved). Instruction region renders via
render_iu_body(MP-D6).
§6.6 Sentinel
- Every
task_runrow references atask_template_idAND atrigger_event_id; orphantask_runrows (no template / no trigger) are forbidden. - Every MOT envelope render fetches all six regions through backend gateway; Nuxt holds no template logic.
- The matrix is the only way thousands of tasks get generated; no ad-hoc task creation path bypasses
task_template.
§7. MP-D15 — Governance at scale (super-admin + AI/agent ops)
§7.1 Why a separate cockpit
A super-admin or AI-agent ops operator looking at 20 000+ active tasks / events / proposals / Kaizens cannot use the MOW canvas (designed for hierarchy navigation, not high-volume triage) nor the Personal JFT Dashboard (designed for 10–20 actionable items). They need a problem-first, aggregate-first, severity-based surface — the Governance Cockpit.
§7.2 Four UI surfaces (separated, not nested)
| # | Surface | Audience | Volume profile | Source design |
|---|---|---|---|---|
| 1 | Personal JFT Dashboard | every staff member | 10–20 actionable tasks / day | 04-… §4.2 + MP-D14 |
| 2 | MOW Hierarchy Canvas T6→T1 | author / runner / department lead / occasional super-admin navigation | tier-bounded; per-card volume manageable | MP-D12 |
| 3 | Governance Cockpit | super-admin / governance reviewer / SRE | 20 000+ aggregated entries; problem-first | 02-… §7 + MP-D15 |
| 4 | AI / Agent Ops Console | super-admin / agent supervisor | dozens to thousands of agent tasks | new in MP-D15 |
The four surfaces share the backend (same PG SoT, same event 5-layer, same realtime gateway) but their UIs are tuned to their respective volume and intent.
§7.3 Governance Cockpit content (extends 02-… §7)
Default route: /governance with the following panels, all driven by aggregate views:
- Severity-prioritized problem queue. Top of page; sorted by severity tier + SLA breach proximity. Rows aggregated by problem class (DLQ / silent worker / event lag breach / overdue / blocked-escalated / failed cuts / schema violation / integrity warning / orphan workflow). Source views per
02-…§7.2. - Owner / domain / department / severity facets. Filter sidebar with multi-select facets backed by the same backend permission filter (Điều 37 v3.3).
- SLO / SLA panel. Per workflow category / executor class / event subscription: SLO definition + current SLI + breach minutes in window. Source:
dot_config slo.*(paper) +vw_governance_event_lag+step_runoverdue ledger. - Heatmaps T6→T1. Heatmap matrix per tier showing problem density per node at that tier; click drills into the canvas in problem-first mode (a different filter on the same canvas component).
- Trend lines. Event lag p50/p95/p99 per (producer, consumer) over rolling windows; DLQ count over time; overdue ratio over time; Kaizen submission rate (volume + quality — see §7.5 below).
- Cluster panels. Failure clusters (group
step.failedevents by error class, root cause inference summary — see MP-D9 evidence rule), overdue clusters (group overdue by deadline_policy_ref / executor_class_ref / department), blocked-escalated clusters (per02-…§3.1 + MP-D4 escalation rules). - Silent worker / heartbeat panel. False-heal protected per
03-…§5.5; lists workers + last_tick_at + status + drill-down. - DLQ replay panel. Lists
dlq_replay_requestrows insubmitted/approved/in_progressstates; replay requires Điều 32 (03-…§6.2). - Cannot_complete cluster panel. Lists steps / tasks in
cannot_completegrouped by reason; triage entry point for governance reviewers. - Kaizen volume + quality panel. Submission rate, approval rate, merge rate, average time-to-decision, top targets receiving Kaizen, AI-agent vs human ratio of proposals.
- AI / Agent ops summary. Cross-link to surface 4 (next section).
- No raw event tail. Inherited from
00-…§3 inv 16 +02-…§7.7. Drill-down viavw_audit_event_timeline(trace_id)only.
§7.4 AI / Agent Ops Console (surface 4)
Content:
- Agent task queue: pending agent_run rows + assigned agent + prompt payload summary + work type + status + retries + heartbeat + last output + failure cluster + evidence links + escalation chain.
- Agent class index: every executor_class_registry row with
executor_kind='ai'; shows config, recent throughput, recent failure rate, last heartbeat, recent prompt cost (if recorded). - Confidence distribution: aggregate of AI summary
confidencevalues (MP-D9 evidence) per category; low-confidence flagged for human review. - Drill-down:
(task_run_id, trace_id) → vw_audit_event_timelineshowing prompt → output → downstream events. - Approval / kill switch: operator can pause an agent class (config flip) or freeze a specific agent_run pending review (writes to
agent_run.frozen_until); both gated by Điều 32 for high-impact agent classes (per policy table paper).
This console is bound by the same MP-D9 evidence rule: every concise AI status carries source_event_count ≥ 1, time_window, generated_by, confidence, source_event_refs + drill-down link.
§7.5 Kaizen quality metrics (binding)
To prevent Kaizen from becoming noise:
kaizen.submission_rateper department / role / surface.kaizen.approval_rate= approved / submitted.kaizen.duplicate_rate= % flagged as duplicate of an open / recently-decided proposal (clustering by target_artifact_ref + intent).kaizen.time_to_decisionp50 / p95.kaizen.merge_rate= merged / approved.kaizen.audio_share= audio_ref-bearing submissions / total (proxies accessibility).kaizen.ai_share= AI-proposer / total (when AI agents start submitting Kaizen-like proposals).
These metrics are computed by paper STABLE functions over input_submission + proposal + workflow_change_requests lifecycle events. Surface them on the Governance Cockpit Kaizen panel (§7.3 item 10).
§7.6 OSS adapter slots only (no final pick)
Adapter slots that can plug into Governance Cockpit / AI Ops Console as candidates (no Phase-1 pick; Gate A + Gate B per 05-… apply):
- Observability metrics: Prometheus / VictoriaMetrics / OpenTelemetry Collector → metrics endpoint adapter; SoT-pointback to PG (
dot_config slo.*+ lag views). - Tracing UI: Jaeger / Tempo → consumes W3C trace_id stream from OTel exporter; SoT remains
vw_audit_event_timeline(trace_id). - Log viewer: Grafana Loki / OpenSearch → indexes log lines emitted from worker classes; SoT remains
event_outbox+dot_iu_command_run. - Dashboarding: Grafana → reads from
event_outboxprojections + governance views; never replaces governance UI. - AI Ops surfaces: Langfuse / Helicone / Phoenix Arize (as candidates ONLY) → ingest AI prompt/response evidence; SoT remains in PG agent_run tables.
Every adapter requires the standard SoT-pointback row + Gate A + B (state-vocab fit, config-first fit) + Council review (per 05-… §5). No final pick in this macro.
§7.7 Boundary
- Governance Cockpit is not a CRUD admin table. It is operational. Admin CRUD remains in Directus admin surface bounded by Điều 33 v2.1.
- Governance Cockpit is not the canvas. It uses different layouts, different aggregations, different filter primitives. Same backend, different UI.
- Permission filter is backend (Điều 37 v3.3). Same
<GovernanceProblemView>component is reused per02-…§7.8; role variance is via backend response filtering. - No raw outbox surface. No raw DOT command log surface. Drill-down only through governance summary functions +
vw_audit_event_timeline(trace_id).
§7.8 Sentinel
- Governance Cockpit default page renders 11 panels listed in §7.3; absent panels are governance bugs not by-design omissions.
- Every AI / worker summary row carries MP-D9 evidence fields; rows missing those fields are refused at write-time (
event_validation_audit). - Auto-resolve of any governance problem requires a
*.resolved/*.recovered/*.healedevent inevent_outbox(MP-D9 binding); summarizer flips without such an event are integrity violations.
§8. Existing infrastructure reuse table (decision per concept)
For every new concept introduced by MP-D11..MP-D15, the decision is reuse | extend | paper-only-new + reason. No new ownership.
| Concept | Decision | PG / Directus / event substrate touched | Reason |
|---|---|---|---|
| Input gateway / staging row | extend (paper-only input_submission) |
new staging table; producer class input_gateway registered in event_type_registry |
No existing staging shape generic enough; staging is mediation not SoT (Điều 33 v2.1). |
| Direct branch → task_comments | reuse | task_comments [VL row 19] |
Existing canonical artifact for task scope. |
| Direct branch → audit_note | extend | small audit ledger (paper) or reuse iu_lifecycle_log for IU-scope audits |
Append-only; per-actor scope. |
| Workflow branch → workflow proposal | reuse | workflow_change_requests [VL row 17] |
Already designated by OD2 / 02-… §8. |
| Workflow branch → non-workflow proposal | use generic staging/proposal | generic proposal table (06-… §S2) |
Per OD2 refined decision. |
| Audio capture | extend (paper file_registry) | audio_file_registry (paper) referenced via audio_ref |
No body bytes in events (MP-D8). Transcription via async worker. |
| Attachment capture | extend (paper file_registry) | attachment_registry (paper) referenced via attachments_ref |
Same. |
| Kaizen routing policy | extend (paper config) | input_routing_policy (paper) |
Decides direct vs workflow per input_kind. |
| MOW canvas T6..T1 | reuse + extend | workflows, workflow_categories, plus paper tier_registry / company / department / specialty rows if absent (survey) |
T2/T1 already exist; tiers above T2 use existing classification taxonomy when present. |
| MOT/JFT envelope | reuse + extend | tasks + task_checkpoints + task_comments [VL row 19] + paper task_def / task_run / task_template |
MOT envelope already in 04-… §4.2; template + matrix are the new explicit layer. |
| Assignee / deadline / escalation policies | paper-only-new | assignee_policy, deadline_policy, escalation_policy registries |
No enumerable registry exists today; needed for safe matrix generation. |
| Governance Cockpit panels | reuse + extend | vw_governance_* (per 02-… §7.2) + new vw_governance_kaizen_*, vw_governance_cannot_complete_* views |
Existing problem-first design covers most categories; Kaizen quality + cannot_complete cluster are gaps. |
| AI / Agent Ops Console | extend | new agent_run paper schema cross-linking executor_class_registry + dot_iu_command_run |
Surfaces operational view of existing agent activity. |
| OSS observability adapters | candidate slots only | external_tool_registry (06-… §S18) |
Per 05-… Gate A + Gate B; no final pick. |
| trace_id propagation through input → staging → canonicalizer | reuse | W3C shape per MP-D1 | Already invariant. |
| Permission filter on input gateway | reuse | Điều 37 v3.3 surface | No new permission concept. |
No row above introduces double-ownership. All paper-only additions are tracked in 06-… §S18 (patched).
§9. IU ↔ PG ↔ queue/event relation review (binding)
For each MP-D11..MP-D15 surface we re-verify the IU singleton + PG SoT + refs-only-queue / event invariants.
| Question | Answer |
|---|---|
| Does Kaizen ever duplicate IU body? | No. The user's free-text suggestion lives only in input_submission.raw_text (a staging field) or attachments_ref. If the Kaizen is approved and rewrites IU narrative, the new IU narrative is authored by the IU author via Điều 38/39 surface and produces a new iu_version row. Staging row is closed by reference. |
| Does the staging row carry IU body bytes? | No body bytes that would duplicate canonical IU. The staging row holds the user's suggestion text (which is a proposal, not canonical IU content) and references to IU it targets via target_artifact_ref. |
| Does any event payload carry IU body / audio / attachment bytes? | No. MP-D8 deny-list applies to all input.* events; size cap enforced (paper dot_config event_payload.max_size_bytes.input.*, default 4 KB). |
| Does the queue carry body? | No. Job queue rows for canonicalization, transcription, attachment indexing carry only staging_id + executor_class_ref + idempotency_key + W3C trace context (03-… §4.2 substrate). |
| Does PG canonicalization happen via DOT pair when mutating? | Yes per Điều 35. Canonicalizer worker for direct branch calls a dot_iu_command_catalog entry when the canonical write is governance-relevant; lighter direct ingest (e.g. task_comments INSERT) uses a typed RPC that emits the standard producer events. |
| Does IU evidence learn from Kaizen + task outcomes? | Yes — extends iu_usage_evidence 8 signals (03-… §9). New paper signals: (a) Kaizen volume targeting an IU, (b) Kaizen approval rate for an IU's bound workflow, (c) repeated cannot_complete on tasks bound to an IU. Feeds KG feedback proposals; never auto-mutates IU. |
| Cross-IU vector pollution risk? | None. Kaizen / input never touches iu_vector_* substrate; mirror-to-vector mapping rules (03-… §3.4 + Rev2 §13) unchanged. iu_vector_sync_enabled=false respected. |
| Does Nuxt ever write PG directly from input shell? | Never. Nuxt input shell POSTs to backend input gateway. Backend gateway is the only writer to staging and to canonical (via DOT pair / RPC). Sentinel: Nuxt code grep for direct PG writes returns zero. |
| Does Directus own any input lifecycle state? | No. Directus may host an admin view over input_submission (read + soft-edit for reviewer triage) and over proposal, but the state column is owned by the canonicalizer worker / approval surface, not Directus flows. Directus never advances processing_state autonomously. |
| Does the MOW canvas trigger any event that re-orders queue priority? | No. Canvas is read-only; it never emits to job_queue. Kaizen submit from canvas goes through input gateway (separate path). |
| Does MOT/JFT materialization create cross-IU body duplication? | No. MOT envelope renders instruction region via render_iu_body (MP-D6); the task_run row does not store IU body. |
All answers preserve 00-… §3 invariants 1, 6, 7, 11, 20 verbatim.
§10. Law / no-double-ownership matrix per MP
Format: owner law/principle | what patch does | what patch must NOT do | sentinel test.
MP-D11 (Bidirectional flow + staging)
| Owner | Patch does | Patch must NOT | Sentinel |
|---|---|---|---|
| Điều 33 v2.1 (3-layer / Nuxt boundary) | Adds explicit input-write path Nuxt → backend gateway → staging | Let Nuxt write PG; let Directus carry SoT | grep Nuxt source for direct PG writes returns zero |
| Hiến pháp v4.6.3 PG-first | Keeps PG as canonical SoT; staging declared mediation | Promote staging to SoT | input_submission.processing_state value never the basis for canonical reads |
| Điều 35 (DOT) | Canonicalizer uses DOT pair for governance-relevant writes | Bypass DOT for IU/registry mutations | every governance-relevant canonicalization has a dot_iu_command_run row |
| Điều 31 (integrity/audit) | Staging row auditable via trace_id; every transition emits event | Skip audit on rejection | every staging row has at least input.submitted event |
| Điều 30 (reversibility) | Staging reversible pre-canonicalization | Allow non-reversible canonical writes from staging | direct-branch artifact rows have soft-delete/audit per their own table contract |
MP-D12 (MOW canvas T6→T1)
| Owner | Patch does | Patch must NOT | Sentinel |
|---|---|---|---|
| Điều 28 (Nuxt render shell) | Single <MowHierarchyCanvas> component, six tier modes |
Embed permission decisions in Nuxt | tier branches in component code = zero; permission filter on backend |
| Điều 37 v3.3 (governance org) | Backend permission filter per tier | Bypass permission via super-admin override in component | super-admin still hits the same backend permission predicate |
| Điều 7 (Assembly First) | Reuses workflows + workflow_categories + existing tenant/department/specialty rows |
Create parallel hierarchy SoT | tier sources mapped to existing rows (or paper-only extensions surveyed before Phase 1) |
| Điều 38/39 (IU) | Cards may bind IU via render_iu_body |
Duplicate IU body in card metadata | card payload references iu_unit_id + iu_version_id only |
MP-D13 (Kaizen intake)
| Owner | Patch does | Patch must NOT | Sentinel |
|---|---|---|---|
| Điều 28 (Nuxt input shell) | Adds inline Kaizen UX | Embed schema / BPMN / registry logic | user-facing strings contain zero internal vocabulary |
| Điều 32 (approval) | Workflow-branch Kaizen lands as proposal; merge requires Điều 32 | Auto-apply Kaizen | every workflow-branch Kaizen has proposal_state initially submitted; merge requires approval_id |
| Điều 38/39 (IU) | Kaizen may target IU but only via proposal | Mutate IU body from Kaizen | IU edits route through author lifecycle, not direct from staging |
| Điều 31 (audit) | Auto-captured context preserved in captured_context_jsonb |
Drop context to reduce row size | required-field list in §5.3 enforced at gateway |
| Hiến pháp v4.6.3 (DOT 100% / no hardcode) | Routing decisions live in input_routing_policy config table |
Hardcode routing in worker code | routing function reads policy table, never embeds rules |
MP-D14 (MOT/JFT matrix)
| Owner | Patch does | Patch must NOT | Sentinel |
|---|---|---|---|
| Future Điều XX (4 Mothers app layer) | Adds task_template / assignee_policy / deadline_policy / escalation_policy paper registries | Enact law text now | listed as future Điều XX referent only; no clause text drafted |
| Điều 45 v1.0 | Reuses executor_class_registry + state_machine_registry + event_subscription | Re-implement state machine / queue | task_run transitions go through fn_state_transition_validate; trigger via subscription |
| Điều 32 (approval) | Action region routes approval to Điều 32 | Embed approval logic in MOT | grep MOT code for approval logic = zero |
| Điều 38/39 (IU) | Instruction region binds IU/bundle via render_iu_body (MP-D6) |
Embed IU body in template | template carries instruction_iu_or_bundle_ref only |
| Điều 31 (audit) | Every task_run carries materialized_from_template_id + trigger_event_id |
Generate tasks without provenance | sentinel: task_run orphan rows refused |
MP-D15 (Governance at scale)
| Owner | Patch does | Patch must NOT | Sentinel |
|---|---|---|---|
| Điều 37 v3.3 (governance org) | Permission filter on every Cockpit + Agent Ops query | Bypass for super-admin | same backend predicate enforces visibility |
| Điều 32 (approval) | Operator actions on agent/DLQ replay/escalation gated by Điều 32 policy | Allow direct mutating actions without approval | every governance-driven mutation has approval_id |
| Điều 31 (audit) | Every Cockpit drill-down resolves to vw_audit_event_timeline(trace_id) |
Surface raw event tail | UI has zero "raw outbox" view |
| Hiến pháp v4.6.3 (no hidden SoT) | OSS adapters use SoT-pointback rows | Adopt OSS as state authority | every adopted tool has external_tool_registry row pointing back to PG |
| Điều 45 (event substrate) | Cockpit aggregates from event_outbox / job_dead_letter / queue_heartbeat | Mutate substrate from Cockpit | Cockpit actions emit events through standard producers |
No matrix row introduces double-ownership; future Điều XX is the only NEW concern referent and only as paper-only future framework law per existing Master Design Rev2 §11.
§11. Remaining gaps / open decisions
| Gap | Type | Resolution path |
|---|---|---|
| Tier registries above T2 (T6/T5/T4/T3) — existing rows? extension? | survey gap | A separate document-only macro IU_4MOTHERS_TIER_REGISTRY_SURVEY_DOCUMENT_ONLY_*X reads existing tenant/company/department/specialty tables (read-only via mcp__claude_ai_Incomex_VPS__query_pg) before Phase 2 MOW canvas implementation. |
task_template / assignee_policy / deadline_policy / escalation_policy registries |
paper-only, Phase 2 DDL | Tracked in 06-… §S18 (patched). Each requires birth row + Điều 0-G. |
input_routing_policy config table |
paper-only, Phase 1 | Tracked in 06-… §S18. |
audio_file_registry / attachment_registry + worker.transcription / worker.attachment_index executor classes |
paper-only, Phase 2 | Add to executor_class_registry Phase 1; concrete worker classes Phase 2. |
| Kaizen quality metrics functions | paper-only, Phase 2 | Tracked in 06-… §S18 (new views vw_governance_kaizen_*). |
| Agent Ops console agent_run table shape | paper-only, Phase 2 | Survey existing AI command run history (dot_iu_command_run filtered to AI commands) before defining new table. |
| OSS observability adapter selection | open | Per 05-… Gate A + Gate B + Council Round; no pick in this macro. |
| OD1 (Điều 34) | Council | Unchanged per MP-D10. Master Design Rev2 (incl. this addendum) does not depend on OD1. |
| MP-D7 sentinel (CRS gate) | open | Affects MOT matrix (MOIT/MOUT contracts) — survey macro must close G7 before Phase 1 references these by name. |
| Bidirectional flow performance / size cap defaults | paper, Phase 1 | Initial proposal: event_payload.max_size_bytes.input.* = 4 KB; staging.raw_text.max_bytes = 64 KB; staging.audio.max_seconds = 180; staging.attachments.max_count = 5. Tunable per Phase 1 operator feedback. |
None of these gaps blocks Master Design Rev2 approval. Each is paper-only or survey-only forward work.
§12. Cross-document anchors (this addendum points back to)
- Top-level invariants & forbidden compliance —
00-master-design-rev2.md§3 + §11 + §12 + §13. - State machine + transitions + governance UI —
02-step-state-machine-and-workflow-ui-design.md§3 / §4 / §7. - Event 5-layer + payload policy + realtime gateway —
03-event-5layer-realtime-dlq-design.md§3 / §4 / §6 / §7. - IU brick + bundle + 4 Mothers binding + Directus boundary —
04-iu-centered-4mothers-binding-design.md§2 / §3 / §4. - Open decisions + extension registries summary + Phase sequencing —
06-open-decisions-and-readiness.md§S2 / §S16 / §S18 / §S20. - Patch log —
07-master-design-rev2-report.md§13 (extended in this rev with MP-D11..MP-D15).
§13. Acceptance for this addendum
A1. MP-D11 bidirectional flow + staging shape declared §3; direct vs workflow branch explicit §3.3; refs-only event family §3.4.
A2. MP-D12 unified T6→T1 canvas single-component pattern §4; tier→source mapping with reuse-first §4.3; explicit "not the super-admin cockpit" boundary §4.4.
A3. MP-D13 inline Kaizen UX five-decision binding §5.1 + §5.2; auto-context-capture field list §5.3; routing direct vs workflow §5.4; complexity-stays-in-backend §5.5.
A4. MP-D14 MOT envelope six regions §6.1; matrix row binding §6.2; JFT semantics §6.3; exact-gap list before mass generation §6.4; MOT boundary preserved §6.5.
A5. MP-D15 four UI surfaces §7.2; Governance Cockpit 11 panels §7.3; AI/Agent Ops Console §7.4; Kaizen quality metrics §7.5; OSS adapter slots only §7.6; boundary §7.7.
A6. Existing infra reuse decision matrix §8 — every concept marked reuse | extend | paper-only-new with reason.
A7. IU↔PG↔queue relation review §9 — preserves invariants 1, 6, 7, 11, 20.
A8. Law / no-double-ownership matrix per MP §10 — sentinel test on each row.
A9. Remaining gaps §11 — explicit + non-blocking.
A10. Forbidden compliance: no PG mutation, no Directus mutation, no Qdrant/vector write, no migration, no DOT command run, no law enactment, no implementation, no UI deployment, no final OSS tool pick, no dot_config gate change, no schema creation, no code generation. All schemas paper-only.
§14. Cross-link to 09-… (rev4 MP-D16..MP-D22 hardening)
This rev3 addendum is hardened by the rev4 second-order governance/operability/observability addendum 09-governance-operability-observability-addendum.md. The mapping of MP-D16..MP-D22 onto the surfaces introduced here:
09-… patch |
Hardens (in this addendum) |
|---|---|
| MP-D16 — Điều 5 five-tier ↔ T6→T1 mapping + readiness matrix | §4 MOW Hierarchy Canvas T6→T1 — clarifies that T6→T1 is the business operating axis, distinct from the Điều 5 architecture axis; gives the per-surface readiness matrix (09-… §3.3). |
| MP-D17 — Governance problem queue taxonomy + lifecycle | §7 Governance Cockpit — adds the typed governance_problem queue (16 classes, 5 severities, 12+3 lifecycle states) the 11 panels read; incident/problem/change separation; ack≠resolution; auto-resolve needs source event (09-… §4). |
| MP-D18 — Kaizen anti-noise + duplicate-control + review lifecycle | §5 Inline Kaizen — adds the backend review lifecycle + duplicate detector + anti-noise controls + metrics; the five-click user flow (§5.1) is unchanged (09-… §5). |
| MP-D19 — Direct canonicalization policy + data-quality guardrails | §3 Bidirectional flow / direct branch — adds allow/deny conditions, data lineage (staging↔canonical), retention/PII/security, correction model (09-… §6). |
| MP-D20 — Minimum Observability Profile | §7 cockpit + AI/Agent Ops — binds the minimum machine-metric set + human-visible vs machine-only split + freshness rules (09-… §7 / 03-… §12). |
| MP-D21 — Raw PG-event tool reconciliation | §7.6 OSS adapter slots — gives the explicit raw-doc tool reconciliation table (09-… §8 / 05-… §7). |
| MP-D22 — Governance Ops Survey | §11 gaps — adds the third survey (Governance Ops) to the sequence before cockpit/agent-ops implementation (09-… §9 / 06-… §S20.1). |
§15. Cross-link to 10-… (rev5 MP-D23..MP-D30 cross-law / industrial-birth binding)
The surfaces and artifacts introduced in this addendum are bound by the rev5 cross-law patch 10-industrial-birth-cross-law-addendum.md:
10-… patch |
Binds (in this addendum) |
|---|---|
| MP-D23 — Điều 28 template binding | §3.x staging/input shell, §4 MOW Hierarchy Canvas, §5 inline Kaizen widget, §7 Governance Cockpit + AI/Agent Ops Console are each a registered design_templates row + product-from-template record (TPL-staging-review, TPL-mow-hierarchy-canvas, TPL-kaizen-inline-widget, TPL-governance-cockpit, TPL-agent-ops-console); no bespoke Nuxt; config-driven routes; lifecycle + 5/5 tests + coverage scanner; field allowlist for cockpit/AI-ops (10-… §3.1). |
| MP-D24 — Điều 36/0-G/29 birth | Every artifact these surfaces generate (proposal, task_template, input_submission canonical target, governance_problem, agent_run, tier-node projection) is born under the Industrial Birth Contract — birth_registry + collection_registry + species + governance_role (10-… §4). Staging rows remain mediation (not SoT, MP-D11); their canonical outputs are born. |
| MP-D25 — Mothers as factories | The Kaizen/staging path is the MOIT factory's input surface; the canvas is the MOW factory's navigation surface; the cockpit/console are governance/AI-ops agency surfaces — each registered as / linked to an Điều 37 factory/governance agency (10-… §5). |
| MP-D26 — Điều 37 jurisdiction | All four surfaces are jurisdiction-bound: same UI, backend-filtered slices (staff/dept-triage/super-admin), Layer A Điều 37 + Layer B Directus role/field-allowlist + Điều 32 (10-… §6). |
| MP-D29 — no "đẻ rơi" | Kaizen/staging-originated objects never reach active without birth+collection/species+owner law; "đẻ rơi" = orphan/phantom/nhầm chuồng detectors (10-… §9). |
End addendum.