{ "schema_version": "1.0", "baseline": "A-ia-governance-v1", "updated_at": "2026-04-18", "owner": "session_a", "purpose_th": "กฎมาตรฐาน naming / path / owner matrix สำหรับ Main Console · Sub-Portals · KB · Planning · Runtime · และ future App/Admin layers", "purpose_en": "Standard naming · path · owner matrix rules for Main Console · Sub-Portals · KB · Planning · Runtime · and future App/Admin layers", "hard_rules": [ "Main console is A-owned · top-level must stay small · never crowd with sub-domain entries", "/kb/* is B-owned · A links only · never modifies content or structure", "/planning/* and /runtime/* are A-owned · B references only", "Every surface must declare Live / Shell / Soon honestly · no production claim without runtime + data + approval", "Word 'Dashboard' is reserved for real dashboard experiences (charts · drilldown · interactive) · not a container word", "Umbrella groups use 'Portal' naming · not 'Dashboard'", "When B renames /kb/* route · A updates link only · never reinterprets B logic" ], "naming_rules": [ { "term": "Dashboard", "reserved_for": "Real dashboard experience with charts, filters, drilldown, interactive analytics", "do_not_use_for": "Container/umbrella groups · folder labels · abstract landing pages", "example_valid": "/kb/dashboard.html (17 real dashboards spec)", "example_invalid": "Calling the Operations Portal a Dashboard" }, { "term": "Operations", "reserved_for": "Umbrella name for the operational/runtime-adjacent group on main console", "do_not_use_for": "Individual dashboards · single tools · single contracts", "example_valid": "Main console button 'Operations' → /operations-portal.html", "example_invalid": "/kb/operations.html (B does not own this naming)" }, { "term": "Portal", "reserved_for": "Group landing pages that fan out to multiple related sub-entries (sub-portals)", "do_not_use_for": "A single page of content · a single contract viewer", "example_valid": "Operations Portal · Feature Portal · Stakeholder Portal", "example_invalid": "Calling a single contract page a 'Portal'" }, { "term": "Planning", "reserved_for": "RFC / design / field mapping / implementation scope documents (A-owned)", "do_not_use_for": "Live runtime · production data · admin plane", "example_valid": "/planning/feature-flags.html", "example_invalid": "/planning/live-dashboard.html (no live data here)" }, { "term": "Runtime", "reserved_for": "Preview · debug · scaffolding · implementation-facing surfaces (A-owned, not production)", "do_not_use_for": "B-owned spec viewers · canonical contracts · marketing pages", "example_valid": "/runtime/feature-flags/ (registry + simulator)", "example_invalid": "Claiming /runtime/* is production" }, { "term": "KB", "reserved_for": "B-owned knowledge · contract · shell · spec viewer pages", "do_not_use_for": "A runtime · A admin plane · A planning RFC", "example_valid": "/kb/dashboard.html · /kb/cases.html · /kb/lexicon.html", "example_invalid": "/kb/admin-control-plane.html (A-owned admin belongs in /app/ or /admin/)" }, { "term": "App", "reserved_for": "Future user-facing A-owned application runtime (production)", "do_not_use_for": "Planning docs · spec viewers", "example_valid": "Future: /app/wizard/ (real wizard runtime)", "example_invalid": "/app/ used for planning RFCs" }, { "term": "Admin", "reserved_for": "Future admin plane A-owned runtime (approvals · audit · sign-off)", "do_not_use_for": "Public-facing content", "example_valid": "Future: /admin/approvals/", "example_invalid": "/admin/ used for demos" }, { "term": "Ops", "reserved_for": "Future operational tooling A-owned runtime (flag flips · deploys · incident)", "do_not_use_for": "B-owned KB · planning docs", "example_valid": "Future: /ops/flags/ (admin UI for feature flags)", "example_invalid": "/ops/ used for marketing" } ], "path_rules": [ { "path": "/", "owner": "A", "purpose": "Main console (executive entry)", "may_contain": "6 top-level buttons max (soft cap)", "must_not_contain": "Per-module crowding · runtime admin UI", "current_state": "6 buttons: Links · Hub · Portal · Merchant · Knowledge · Operations" }, { "path": "/operations-portal.html", "owner": "A", "purpose": "Operations sub-portal · groups dashboard/cases/generate/tenant/planning", "may_contain": "5 sub-entries · Live/Shell clear labels", "must_not_contain": "Live runtime · write operations", "current_state": "5 sub-entries · 5 Shell" }, { "path": "/links.html · /hub.html · /portal.html · /ai-content-dashboard.html", "owner": "A", "purpose": "Legacy A-owned surfaces (Live)", "may_contain": "Live content or legacy demos", "must_not_contain": "New content unless governance-reviewed", "current_state": "Live · stable" }, { "path": "/kb/*", "owner": "B", "purpose": "B-owned knowledge base · contracts · spec viewers · shell pages", "may_contain": "KB pages · data files (docs/kb/data/*) · kb assets (kb.js · kb.css)", "must_not_contain": "A runtime · A admin plane · A-defined flags", "current_state": "Phase 12 closed · 87 docs validated" }, { "path": "/planning/*", "owner": "A", "purpose": "A-owned RFC · design docs · field mapping · implementation planning", "may_contain": "Design HTML · ER diagrams · API sketches · sequence flows · binding tables", "must_not_contain": "Live data · production runtime · admin operations", "current_state": "v0.2 · 5 runtime + 4 cross-cutting + IA governance" }, { "path": "/runtime/*", "owner": "A", "purpose": "A-owned runtime preview · debug · scaffolding · implementation-facing surfaces", "may_contain": "Registry JSON · schemas · simulator HTML · debug tools", "must_not_contain": "Production traffic · admin flip UI · published app", "current_state": "Phase 1 · feature-flags (registry live · evaluator not bound)" }, { "path": "/app/* (future)", "owner": "A", "purpose": "User-facing A-owned application runtime (production)", "may_contain": "Real product runtime · real data · real auth", "must_not_contain": "Planning docs · spec viewers", "current_state": "Not yet created" }, { "path": "/admin/* (future)", "owner": "A", "purpose": "A-owned admin plane runtime", "may_contain": "Approval queue · sign-off UI · audit viewer · tenant mgmt", "must_not_contain": "Public-facing content", "current_state": "Not yet created · planned in admin-control-plane.html" }, { "path": "/ops/* (future)", "owner": "A", "purpose": "Operational tooling · flag flips · incident actions", "may_contain": "Flag admin UI · deploy kanban · rollback tools", "must_not_contain": "Planning docs · spec viewers", "current_state": "Not yet created" } ], "owner_matrix": [ { "surface": "Main Console (docs/index.html)", "owner": "A", "purpose": "Executive entry · 6 top-level gateways", "can_link_to": ["/kb/*", "/planning/*", "/runtime/*", "/operations-portal.html", "/links.html", "/hub.html", "/portal.html", "/ai-content-dashboard.html"], "must_not_contain": ["per-runtime sub-buttons", "live admin controls", "B-owned structure"], "note": "Keep small · collapse new groups into a Portal" }, { "surface": "Operations Portal (docs/operations-portal.html)", "owner": "A", "purpose": "Sub-portal landing for operational/runtime-adjacent group", "can_link_to": ["/kb/dashboard.html", "/kb/cases.html", "/kb/generated.html", "/kb/enterprise-upload.html", "/planning/"], "must_not_contain": ["write operations", "live admin flip"], "note": "Linking-only layer · no runtime logic" }, { "surface": "Knowledge Base (/kb/*)", "owner": "B", "purpose": "Canonical knowledge · contract viewers · shell pages", "can_link_to": ["other /kb/*"], "must_not_contain": ["A runtime code", "A admin plane", "A-coined naming reused as labels"], "note": "A links only · never edits" }, { "surface": "Planning Pack (/planning/*)", "owner": "A", "purpose": "RFC · design · mapping · implementation scope", "can_link_to": ["/kb/* (ref)", "/runtime/* (implementation pointer)", "/operations-portal.html"], "must_not_contain": ["live data fetch", "production runtime", "write operations"], "note": "Consumes B contracts via anchor/text ref · never fetches at runtime" }, { "surface": "Runtime Phase Pack (/runtime/*)", "owner": "A", "purpose": "Debug · scaffolding · registry · simulator", "can_link_to": ["/planning/* (spec)", "/kb/* (contract ref)"], "must_not_contain": ["production traffic handlers", "admin flip UI (belongs in /admin/)"], "note": "Must declare Live vs mock/mapped-not-bound/placeholder/derived per entity" }, { "surface": "Future /app/*", "owner": "A", "purpose": "User-facing A-owned production runtime", "can_link_to": ["/api/* (backend)"], "must_not_contain": ["planning docs", "spec viewers"], "note": "Requires feature-flag gate + admin control plane before launch" }, { "surface": "Future /admin/*", "owner": "A", "purpose": "Admin plane · approvals · audit · tenant mgmt", "can_link_to": ["/ops/*", "/api/admin/*"], "must_not_contain": ["public-facing content", "/kb/* editing UI (B-owned)"], "note": "All writes go through approval matrix" }, { "surface": "Future /ops/*", "owner": "A", "purpose": "Operational tooling · flag flips · deploys", "can_link_to": ["/admin/*", "/api/admin/*", "/runtime/* (read-only)"], "must_not_contain": ["B-owned content", "public marketing"], "note": "Gated by admin tier · audit-logged" } ], "portal_hierarchy_examples": [ { "level": "main_console", "path": "/", "items": [ { "label": "Links", "target": "/links.html", "status": "Live", "owner": "A" }, { "label": "Hub", "target": "/hub.html", "status": "Live", "owner": "A" }, { "label": "Portal", "target": "/portal.html", "status": "Live", "owner": "A" }, { "label": "Merchant", "target": "/ai-content-dashboard.html","status": "Live", "owner": "A" }, { "label": "Knowledge", "target": "/kb/", "status": "Live", "owner": "B" }, { "label": "Operations", "target": "/operations-portal.html", "status": "Shell", "owner": "A", "expands_to": "operations_portal" } ] }, { "level": "sub_portal", "id": "operations_portal", "path": "/operations-portal.html", "items": [ { "label": "Dashboard", "target": "/kb/dashboard.html", "status": "Shell", "owner": "B" }, { "label": "Cases", "target": "/kb/cases.html", "status": "Shell", "owner": "B" }, { "label": "Generate", "target": "/kb/generated.html", "status": "Shell", "owner": "B" }, { "label": "Tenant", "target": "/kb/enterprise-upload.html","status": "Shell", "owner": "B" }, { "label": "Planning", "target": "/planning/", "status": "Shell", "owner": "A" } ] }, { "level": "content_layer", "path": "/planning/", "categories": ["5 runtime pages (dashboard/cases/generate/tenant/wizard)", "4 cross-cutting (admin/flags/hints/signal)", "IA governance (this page)"] }, { "level": "runtime_layer", "path": "/runtime/", "categories": ["feature-flags (Phase 1)"] } ], "live_shell_soon_policy": { "live": { "criteria": [ "Backed by real runtime + real data", "Tested in staging at minimum", "Feature flag exists and is internal+ for the linked surface", "No production claim beyond actual rollout stage" ], "examples_current": ["Links", "Hub", "Portal", "Merchant", "Knowledge"] }, "shell": { "criteria": [ "Contract viewer · RFC · planning · spec page", "No runtime bound OR runtime flag still in draft/internal", "No production traffic uses it", "Honest note present on page" ], "examples_current": ["Operations (on main console)", "Dashboard · Cases · Generate · Tenant · Planning (inside Operations Portal)"] }, "soon": { "criteria": [ "Route placeholder · target page does not exist yet", "Clear ETA or blocked-by citation", "Do not link if the target 404s · keep as disabled card" ], "examples_current": [] }, "rules": [ "Every button on main console OR any sub-portal MUST carry exactly one of: Live / Shell / Soon", "Never promote Shell → Live without feature-flag evidence and approval ref", "If a Shell page has partial runtime (e.g. registry live · evaluator not bound), stay Shell at button level; honest note inside explains detail", "Page-internal binding uses 5-status vocabulary: live / mock / mapped-not-bound / placeholder / derived (see /planning/ binding legend)" ] }, "change_control": { "kb_route_rename": { "scenario": "B renames a /kb/* route (e.g., cases → case-board)", "a_action": [ "Update the href in operations-portal.html and any planning/runtime doc that anchors it", "Do NOT rename A-owned labels to match · label naming is A-governed", "Add a SYNC.md entry noting the sync", "Never reinterpret what the renamed page does · B is source of truth for B content" ], "forbidden": [ "Editing the B page itself", "Duplicating B content into A", "Renaming A-owned labels to mirror B internal renames" ] }, "a_new_top_level_request": { "scenario": "New business need wants a new top-level button on main console", "a_action": [ "FIRST · check if it fits an existing Portal (collapse inside sub-portal)", "If genuinely a new umbrella · propose Portal name per naming_rules", "Add governance entry to this file · describe surface/owner/purpose/can-link-to/must-not", "Update owner_matrix · path_rules · portal_hierarchy_examples", "Only then edit docs/index.html" ], "forbidden": [ "Adding top-level without governance review", "Using reserved terms (Dashboard · KB · Admin · Ops) as a button label for unrelated content" ] }, "deprecation": { "scenario": "A page is no longer needed", "a_action": [ "Mark with Soon badge + deprecation notice for 1 release cycle", "Remove only after stakeholder review", "Keep redirect or 410 Gone", "Append SYNC entry" ] } }, "soft_caps": { "main_console_top_level": 8, "sub_portal_entries": 6, "planning_pages_per_pack": 10, "runtime_phase_deliverables_per_batch": 3 }, "honest_note_th": "เอกสาร governance นี้เป็น A-owned reference · ใช้คุมโครงสร้างหน้าและการตั้งชื่อเพื่อไม่ให้สับสนในอนาคต · ถ้า B เปลี่ยน route/path ของ /kb/* · A update link only · ห้าม reinterpret B contracts", "honest_note_en": "This governance pack is A-owned reference for IA + naming + path + owner discipline · prevents console drift · if B renames /kb/* routes, A updates link only · never reinterpret B contracts" }