.specify/memory/constitution.md

@@ -1,33 +1,37 @@
 <!--
 Sync Impact Report
 
-- Version change: 2.1.0 -> 2.2.0
+- Version change: 2.2.0 -> 2.3.0
 - Modified principles:
-  - UI-SURF-001: broadened to require one explicit broad action-surface
-    class before detailed surface typing
-  - UX-001 (Layout & IA): header-action guidance aligned to
-    ACTSURF-001 / HDR-001 instead of a generic max-two-actions rule
-  - HDR-001: expanded and refocused as the record/detail/edit-specific
-    specialization of the wider action-surface discipline addendum
-  - UI-REVIEW-001: spec and PR review gates expanded to require action
-    hierarchy, next-step clarity, and justified exceptions
+  - UI-CONST-001: expanded to make TenantPilot's decision-first
+    governance identity explicit
+  - UI-REVIEW-001: spec and PR review gates expanded for surface role,
+    human-in-the-loop justification, workflow-vs-storage IA, and
+    attention-load reduction
+  - Immediate Retrofit Priorities: expanded with a classification-first
+    wave for existing surfaces
 - Added sections:
-  - Action Surface Discipline (ACTSURF-001)
+  - Decision-First Operating Model & Progressive Disclosure
+    (DECIDE-001)
 - Removed sections: None
 - Templates requiring updates:
   - ✅ .specify/memory/constitution.md
   - ✅ .specify/templates/plan-template.md (Constitution Check updated for
-    ACTSURF-001 / HDR-001)
-  - ✅ .specify/templates/spec-template.md (surface classification +
-    requirements updated for action-surface discipline)
+    decision-first surface roles, workflow-first IA, and calm-surface
+    review)
+  - ✅ .specify/templates/spec-template.md (surface role classification,
+    operator contract, and requirements updated for decision-first
+    governance)
   - ✅ .specify/templates/tasks-template.md (implementation task guidance
-    updated for action hierarchy, grouping, and exception handling)
-  - ✅ docs/product/standards/README.md (Constitution index updated for the
-    new action-surface principle)
+    updated for progressive disclosure, single-case context, and
+    attention-load reduction)
+  - ✅ docs/product/standards/README.md (Constitution index updated for
+    DECIDE-001)
 - Commands checked:
   - N/A `.specify/templates/commands/*.md` directory is not present in this repo
 - Follow-up TODOs:
-  - None.
+  - Create a dedicated surface / IA classification spec to retrofit
+    existing surfaces against DECIDE-001.
 -->
 
 # TenantPilot Constitution
@@ -327,10 +331,174 @@ ### Operator-Facing UI/UX Constitution v1 (UI-CONST-001)
 
 Purpose and scope
 - This section governs operator-facing admin UI semantics across TenantPilot / TenantAtlas.
-- It defines allowed surface types, allowed interaction models, primary/secondary/destructive action hierarchy, list/detail/queue semantics, scope and context signals, canonical navigation and naming rules, visibility of critical operational truth, scanability and density rules, exception handling, and review and enforcement requirements.
+- It defines decision-first prominence roles, allowed surface types,
+  allowed interaction models, primary/secondary/destructive action
+  hierarchy, list/detail/queue semantics, scope and context signals,
+  canonical navigation and naming rules, visibility of critical
+  operational truth, scanability and density rules, exception handling,
+  and review and enforcement requirements.
 - It does not govern branding, colors, typography, spacing tokens, marketing or landing pages, implementation details without UX effect, purely cosmetic copy changes, or backend architecture except where backend design would create false UI mental models.
 - This section is governance, not a style guide. Its purpose is to prevent ambiguity, operator risk, and UI drift before they spread through the product.
 
+#### Decision-First Operating Model & Progressive Disclosure (DECIDE-001)
+
+Goal: TenantPilot is primarily a governance and decision platform, not
+a browser for internal technical detail objects. This section governs
+surface prominence and default information depth. It is orthogonal to
+UI-SURF-001 and ACTSURF-001: every operator-facing surface MUST declare
+both its interaction model and its decision-role prominence.
+
+##### Surface prominence roles
+
+- Every operator-facing surface MUST declare exactly one decision-role
+  prominence:
+  - Primary Decision Surface
+  - Secondary Context Surface
+  - Tertiary Evidence / Diagnostics Surface
+- Decision-role prominence is separate from action-surface class and
+  detailed surface type.
+- Prominence determines what deserves top-level navigation, default
+  emphasis, and default-visible information depth.
+
+##### Primary surfaces are for human decisions
+
+- Primary Decision Surfaces MUST support a clear human-in-the-loop
+  moment such as attention prioritization, approval, risk acceptance or
+  rejection, drift / findings / exception triage, review completion,
+  evaluation of blocked or failed automations, or execution /
+  escalation of the next governance action.
+- A prominent surface MUST NOT exist primarily to display internal
+  model objects, raw data, diagnostics, or technical object hubs
+  without clear operator value.
+- Every proposed primary surface MUST answer: what concrete decision or
+  operator action does this surface support?
+
+##### Detail surfaces are evidence surfaces
+
+- OperationRun detail, evidence detail, policy version detail, audit
+  log detail, JSON / payload / diff views, and deep diagnostic contexts
+  are normally Secondary Context or Tertiary Evidence / Diagnostics
+  surfaces.
+- These surfaces remain essential for verification, diagnosis, and
+  auditability, but they MUST NOT dominate default operator workflows
+  or primary navigation merely because the underlying objects exist.
+
+##### Default to decisions, not details
+
+- Default-visible information MUST first answer what happened, why it
+  matters, how urgent it is, what the system recommends, what impact
+  the decision has, and what action or approval is required now.
+- Internal IDs, relation depth, raw payloads, full snapshot history,
+  debug views, and unstructured technical detail MUST stay secondary
+  unless they are required for the first decision.
+
+##### Progressive disclosure is the default
+
+- Depth MUST be preserved but revealed on demand through
+  expand/collapse, drawers, tabs, side panels, explicit "Show details"
+  affordances, or focused drill-downs from a clear decision context.
+- The default workflow SHOULD let the operator decide before navigating
+  through diagnostic depth.
+- Primary flows MUST NOT force operators through multiple technical
+  subpages before a single governance decision can be made.
+
+##### Navigation follows workflows, not storage structures
+
+- Primary navigation and prominent entry points MUST follow operator
+  workflows such as pending decisions, alerts / escalations, reviews,
+  exceptions / accepted risks, governance priorities, and blocked or
+  failed automations.
+- Internal persistence terms such as OperationRuns, EvidenceItems,
+  PolicyVersions, StoredReports, or relational chains MAY exist as
+  supporting surfaces, but they do not earn primary information
+  architecture status by default.
+- Every navigation proposal MUST answer: does this reflect a working
+  task or only an internal storage structure?
+
+##### Meaning comes before model names
+
+- Operator-facing surfaces MUST prefer governance language such as
+  "Drift detected", "Exception expires soon", "Evidence incomplete",
+  "Review ready", "Remediation recommended", or "Further review
+  required".
+- Model names, table/entity language, relation terminology, and
+  implementation-first state labels MUST NOT be the primary UX
+  language when business meaning can be expressed directly.
+
+##### One case, one decision context
+
+- A single governance case SHOULD be decidable within one focused
+  context that brings together the problem, risk or relevance,
+  recommendation, impact, ownership, next action, approval options, and
+  optional detail beneath or beside the decision.
+- Operators MUST NOT be forced to reconstruct one decision across
+  multiple equal-rank Run, Evidence, Policy, Audit, and Finding pages
+  when the product can present one coherent decision context.
+
+##### Audit depth is mandatory; dominance is not
+
+- Enterprise-grade evidence, verification, and audit depth MUST remain
+  available.
+- Audit requirements do NOT justify default surfaces that look or
+  behave like forensic diagnostics consoles.
+- The standard operator flow SHOULD remain calm, prioritized, and
+  decision-led even when deep proof is available.
+
+##### New primary surfaces require strict justification
+
+- Every new top-level or otherwise prominent surface MUST justify:
+  1. which human-in-the-loop moment it supports,
+  2. why an existing surface is insufficient,
+  3. why a drawer, panel, tab, or embedded decision context is
+     insufficient,
+  4. what search, review, or click work it removes.
+- If those answers are weak, the work MUST reuse an existing decision
+  context or remain secondary/tertiary.
+
+##### Automation must reduce attention load
+
+- New automation, notification, or autonomous governance behavior MUST
+  measurably reduce search work, review work, or click load.
+- Automation that primarily creates extra lists, statuses, surfaces, or
+  detail work is non-conformant even if technically correct.
+- The review question is: does this make the platform quieter and
+  clearer, or merely larger?
+
+##### Calm default surfaces
+
+- The default workspace experience MUST distinguish clearly between
+  immediately actionable work, worth-watching context, and
+  reference-only information.
+- Unranked warning floods, parallel attention entry points, and
+  perpetual visual escalation are forbidden on primary surfaces.
+- A surface that only creates noise instead of priority is
+  non-conformant.
+
+##### Retrofit requirement
+
+- DECIDE-001 applies to existing as well as new surfaces.
+- Existing surfaces MUST be reclassified as Primary Decision,
+  Secondary Context, or Tertiary Evidence / Diagnostics surfaces and
+  then reviewed for prominence, disclosure, consolidation, and
+  workflow alignment.
+- Surface retrofit work SHOULD prefer reclassification and
+  consolidation before creating new navigation branches.
+
+##### Review gate
+
+Every operator-facing spec or PR that changes a surface MUST answer:
+1. What concrete decision or operator action does this support?
+2. Who is the human in the loop?
+3. What MUST be immediately visible for the first decision?
+4. What is preserved but only revealed on demand?
+5. Is this a Primary Decision Surface, Secondary Context Surface, or
+   Tertiary Evidence / Diagnostics Surface?
+6. If it is primary, why can it not live inside an existing decision
+   context?
+7. Does the navigation reflect a workflow or only storage structure?
+8. Does this reduce search, review, or click work?
+9. Does this make the product calmer and clearer instead of louder?
+
 #### Surface Taxonomy (UI-SURF-001)
 
 Every new admin surface MUST be assigned exactly one broad action-surface
@@ -928,15 +1096,19 @@ #### Spec Scope Fields (SCOPE-002)
 #### Enforcement Model (UI-REVIEW-001)
 
 Spec review requirements
-- Every spec that changes an operator-facing surface MUST answer: broad
+- Every spec that changes an operator-facing surface MUST answer:
+  decision-role prominence, human-in-the-loop moment, immediate-visible
+  decision information, on-demand evidence/diagnostics boundary,
+  whether a new primary surface is actually justified, broad
   action-surface class, detailed surface type, one likely next operator
   action, primary inspect/open model, row-click rule, whether explicit
   View/Inspect exists or is forbidden, where navigation lives, where
   secondary actions live, where destructive actions live, how grouped
   actions are ordered, canonical collection route, canonical detail
   route, scope signals and their exact meaning, canonical noun,
-  critical truth visible by default, and whether an exception type is
-  used.
+  critical truth visible by default, workflow-vs-storage IA
+  justification, attention-load reduction, and whether an exception
+  type is used.
 - Missing any of those answers makes the spec incomplete.
 
 PR review requirements
@@ -946,14 +1118,36 @@ #### Enforcement Model (UI-REVIEW-001)
   workflow labels in dense rows, misleading scope chips, drifting domain
   nouns, hidden critical operational truth, flat record headers with
   multiple equal-weight mutations, workbench headers that mix scope,
-  selection, navigation, and object actions as peers, or undocumented
+  selection, navigation, and object actions as peers, a primary surface
+  with no clear human-in-the-loop purpose, detail/evidence objects
+  promoted into primary navigation without justification, one case
+  fragmented across multiple equal-rank pages, new automation that adds
+  attention surfaces without reducing operator work, noisy default
+  surfaces with no action/watch/reference hierarchy, or undocumented
   exceptions without dedicated tests.
 
 Guard tests
-- Repository guards SHOULD validate: declared surface type, conformant primary inspect model, absence of redundant View actions, presence of explicit Inspect on Queue / Review and History / Audit surfaces, absence of empty `ActionGroup` or `BulkActionGroup`, correct placement of destructive actions, truthful scope signals, stable canonical nouns across shells, and dedicated tests for every approved exception.
+- Repository guards SHOULD validate: declared surface type, declared
+  decision-role prominence where specs or metadata expose it,
+  conformant primary inspect model, absence of redundant View actions,
+  presence of explicit Inspect on Queue / Review and History / Audit
+  surfaces, absence of empty `ActionGroup` or `BulkActionGroup`,
+  correct placement of destructive actions, truthful scope signals,
+  stable canonical nouns across shells, and dedicated tests for every
+  approved exception.
 
 #### Immediate Retrofit Priorities
 
+Wave 0 - Surface role classification
+- First classify existing surfaces as Primary Decision, Secondary
+  Context, or Tertiary Evidence / Diagnostics surfaces.
+- For each surface, determine whether its current prominence is
+  justified, which detail can move into progressive disclosure, and
+  whether several technical pages should collapse into one decision
+  context.
+- Wave 0 is done only when primary navigation candidates are grounded
+  in workflows rather than storage structures.
+
 Wave 1 - Interaction normalization
 - First fixes target redundant row click plus View, destructive row actions on standard lists, empty overflow or bulk groups, and rows that have become pseudo-control centers.
 - First-slice focus surfaces are Tenants, Workspaces, Policies, Alert Deliveries, and other CRUD-first list surfaces with the same drift pattern.
@@ -967,6 +1161,21 @@ #### Immediate Retrofit Priorities
 
 #### Appendix A - One-page Condensed Constitution
 
+- Every operator-facing surface declares one decision role:
+  Primary Decision, Secondary Context, or Tertiary Evidence /
+  Diagnostics.
+- Primary surfaces exist to help a human prioritize, judge, approve,
+  reject, escalate, or act.
+- Evidence and diagnostics remain available but do not dominate the
+  default workflow.
+- Default to decisions, not details.
+- Progressive disclosure preserves depth without forcing it into the
+  first decision.
+- Navigation follows workflows, not storage structures.
+- One governance case should be decidable in one focused context.
+- Automation must reduce attention load.
+- Default surfaces stay calm, prioritized, and explicit about what is
+  actionable, worth watching, and reference-only.
 - Every new or materially changed surface declares one broad
   action-surface class first.
 - Every admin surface has one surface type.
@@ -993,6 +1202,16 @@ #### Appendix A - One-page Condensed Constitution
 
 #### Appendix B - Feature Review Checklist
 
+- Decision-role prominence is declared.
+- The human-in-the-loop moment is explicit.
+- Immediate-visible decision information is explicit.
+- On-demand evidence / diagnostics boundaries are explicit.
+- Any new primary surface is justified against an existing decision
+  context.
+- Navigation reflects a workflow rather than storage structure.
+- One governance case stays decidable in one focused context.
+- The feature reduces search, review, or click work.
+- The resulting surface is calmer and clearer, not merely larger.
 - Broad action-surface class is declared.
 - Detailed surface type is declared.
 - The one most likely next operator action is explicit.
@@ -1018,6 +1237,16 @@ #### Appendix B - Feature Review Checklist
 
 #### Appendix C - Red Flags for Future PRs
 
+- A primary surface has no clear human-in-the-loop moment.
+- A technical object hub is promoted into primary navigation without
+  workflow justification.
+- Default-visible content behaves like a diagnostics console instead of
+  a decision surface.
+- The operator must assemble one decision from multiple equal-rank Run,
+  Evidence, Policy, Audit, or Finding pages.
+- A feature adds automation, alerts, or statuses that increase net
+  attention load.
+- The surface creates more noise than priority.
 - Row click and View open the same destination.
 - A row becomes a control center.
 - Archive or Delete sits openly beside View or Inspect on a standard list.
@@ -1105,6 +1334,9 @@ ### Scope, Compliance, and Review Expectations
 - This constitution applies across the repo. Feature specs may add stricter constraints but not weaker ones.
 - Restore semantics changes require: spec update, checklist update (if applicable), and tests proving safety.
 - Specs and PRs that introduce new persisted truth, abstractions, states, DTO/presenter layers, or taxonomies MUST include the proportionality review required by BLOAT-001.
+- Specs and PRs that change operator-facing surfaces MUST classify each
+  affected surface under DECIDE-001 and justify any new Primary
+  Decision Surface or workflow-first navigation change.
 - Review and approval MUST favor simplification, replacement, and absorption over additive semantic layering.
 - Future-release preparation alone is not sufficient justification for new persistence or frameworkization unless security, tenant isolation, auditability, compliance evidence, or queue correctness already require it.
 
@@ -1118,4 +1350,4 @@ ### Versioning Policy (SemVer)
 - **MINOR**: new principle/section or materially expanded guidance.
 - **MAJOR**: removing/redefining principles in a backward-incompatible way.
 
-**Version**: 2.2.0 | **Ratified**: 2026-01-03 | **Last Amended**: 2026-04-11
+**Version**: 2.3.0 | **Ratified**: 2026-01-03 | **Last Amended**: 2026-04-12

.specify/templates/plan-template.md

@@ -58,6 +58,14 @@ ## Constitution Check
 - Badge semantics (BADGE-001): status-like badges use `BadgeCatalog` / `BadgeRenderer`; no ad-hoc mappings; new values include tests
 - Filament-native UI (UI-FIL-001): admin/operator surfaces use native Filament components or shared primitives first; no ad-hoc status UI, local semantic color/border decisions, or hand-built replacements when native/shared semantics exist; any exception is explicitly justified
 - UI/UX surface taxonomy (UI-CONST-001 / UI-SURF-001): every changed operator-facing surface is classified as exactly one allowed surface type; ad-hoc interaction models are forbidden
+- Decision-first operating model (DECIDE-001): each changed
+  operator-facing surface is classified as Primary Decision,
+  Secondary Context, or Tertiary Evidence / Diagnostics; primary
+  surfaces justify the human-in-the-loop moment, default-visible info
+  is limited to first-decision needs, deep proof is progressive
+  disclosed, one governance case stays decidable in one context where
+  practical, navigation follows workflows not storage structures, and
+  automation / alerts reduce attention load instead of adding noise
 - UI/UX inspect model (UI-HARD-001): each list surface has exactly one primary inspect/open model; redundant View beside row click or identifier click is forbidden; edit-as-inspect is limited to Config-lite resources
 - UI/UX action hierarchy (UI-HARD-001 / UI-EX-001): standard CRUD and Registry rows expose at most one inline safe shortcut; destructive actions are grouped or in the detail header; queue exceptions are catalogued, justified, and tested
 - UI/UX scope, truth, and naming (UI-HARD-001 / UI-NAMING-001 / OPSURF-001): scope signals are truthful, canonical nouns stay stable across shells, critical operational truth is default-visible, and standard lists remain scanable

.specify/templates/spec-template.md

@@ -35,11 +35,22 @@ ## Spec Scope Fields *(mandatory)*
 - **Default filter behavior when tenant-context is active**: [e.g., prefilter to current tenant]
 - **Explicit entitlement checks preventing cross-tenant leakage**: [Describe checks]
 
+## Decision-First Surface Role *(mandatory when operator-facing surfaces are changed)*
+
+If this feature adds or materially changes an operator-facing surface,
+fill out one row per affected surface. This role is orthogonal to the
+Action Surface Class / Surface Type below.
+
+| Surface | Decision Role | Human-in-the-loop Moment | Immediately Visible for First Decision | On-Demand Detail / Evidence | Why This Is Primary or Why Not | Workflow Alignment | Attention-load Reduction |
+|---|---|---|---|---|---|---|---|
+| e.g. Review inbox | Primary Decision Surface | Review and release queued governance work | Case summary, severity, recommendation, required action | Full evidence, raw payloads, audit trail, provider diagnostics | Primary because it is the queue where operators decide and clear work | Follows pending-decisions workflow, not storage objects | Removes search across runs, findings, and audit pages |
+
 ## UI/UX Surface Classification *(mandatory when operator-facing surfaces are changed)*
 
 If this feature adds or materially changes an operator-facing list, detail, queue, audit, config, or report surface,
 fill out one row per affected surface. Declare the broad Action Surface
-Class first, then the detailed Surface Type.
+Class first, then the detailed Surface Type. Keep this table in sync
+with the Decision-First Surface Role section above.
 
 | Surface | Action Surface Class | Surface Type | Likely Next Operator Action | Primary Inspect/Open Model | Row Click | Secondary Actions Placement | Destructive Actions Placement | Canonical Collection Route | Canonical Detail Route | Scope Signals | Canonical Noun | Critical Truth Visible by Default | Exception Type / Justification |
 |---|---|---|---|---|---|---|---|---|---|---|---|---|---|
@@ -47,11 +58,14 @@ ## UI/UX Surface Classification *(mandatory when operator-facing surfaces are ch
 
 ## Operator Surface Contract *(mandatory when operator-facing surfaces are changed)*
 
-If this feature adds a new operator-facing page or materially refactors one, fill out one row per affected page/surface.
+If this feature adds a new operator-facing page or materially refactors
+one, fill out one row per affected page/surface. The contract MUST show
+how one governance case or operator task becomes decidable without
+unnecessary cross-page reconstruction.
 
-| Surface | Primary Persona | Surface Type | Primary Operator Question | Default-visible Information | Diagnostics-only Information | Status Dimensions Used | Mutation Scope | Primary Actions | Dangerous Actions |
-|---|---|---|---|---|---|---|---|---|---|
-| e.g. Tenant policies page | Tenant operator | List/detail | What needs action right now? | Policy health, drift, assignment coverage | Raw payloads, provider IDs, low-level API details | lifecycle, data completeness, governance result | TenantPilot only / Microsoft tenant / simulation only | Sync policies, View policy | Restore policy |
+| Surface | Primary Persona | Decision / Operator Action Supported | Surface Type | Primary Operator Question | Default-visible Information | Diagnostics-only Information | Status Dimensions Used | Mutation Scope | Primary Actions | Dangerous Actions |
+|---|---|---|---|---|---|---|---|---|---|---|
+| e.g. Tenant policies page | Tenant operator | Decide whether policy state needs follow-up | List/detail | What needs action right now? | Policy health, drift, assignment coverage | Raw payloads, provider IDs, low-level API details | lifecycle, data completeness, governance result | TenantPilot only / Microsoft tenant / simulation only | Sync policies, View policy | Restore policy |
 
 ## Proportionality Review *(mandatory when structural complexity is introduced)*
 
@@ -200,6 +214,23 @@ ## Requirements *(mandatory)*
 - how the same domain vocabulary is preserved across button labels, modal titles, run titles, notifications, and audit prose,
 - and how implementation-first terms are kept out of primary operator-facing labels.
 
+**Constitution alignment (DECIDE-001):** If this feature adds or changes operator-facing surfaces, the spec MUST describe:
+- whether each affected surface is a Primary Decision Surface,
+  Secondary Context Surface, or Tertiary Evidence / Diagnostics
+  Surface, and why,
+- which human-in-the-loop moment each primary surface supports,
+- what MUST be visible immediately for the first decision,
+- what is preserved but only revealed on demand,
+- why any new primary surface cannot live inside an existing decision
+  context,
+- how navigation follows operator workflows rather than storage
+  structures,
+- how one governance case remains decidable in one focused context,
+- how any new automation, notifications, or autonomous governance logic
+  reduce search/review/click load,
+- and how the resulting default experience is calmer and clearer rather
+  than merely larger.
+
 **Constitution alignment (UI-CONST-001 / UI-SURF-001 / ACTSURF-001 / UI-HARD-001 / UI-EX-001 / UI-REVIEW-001 / HDR-001):** If this feature adds or changes an operator-facing surface, the spec MUST describe:
 - the chosen broad action-surface class and why it is the correct classification,
 - the chosen detailed surface type and why it is the correct refinement,

.specify/templates/tasks-template.md

@@ -39,13 +39,30 @@ # Tasks: [FEATURE NAME]
 - aligning button labels, modal titles, run titles, notifications, and audit prose to the same domain vocabulary,
 - removing implementation-first wording from primary operator-facing copy.
 **Operator Surfaces**: If this feature adds or materially refactors an operator-facing page or flow, tasks MUST include:
+- classifying each affected surface as Primary Decision, Secondary
+  Context, or Tertiary Evidence / Diagnostics and keeping that role in
+  sync with the governing spec,
+- defining the human-in-the-loop moment and justifying any new Primary
+  Decision Surface against existing decision contexts,
 - filling the spec’s UI/UX Surface Classification for every affected surface,
 - filling the spec’s Operator Surface Contract for every affected page,
+- keeping default-visible content limited to first-decision needs and
+  moving proof, payloads, and diagnostics into progressive disclosure,
 - making default-visible content operator-first and moving JSON payloads, raw IDs, internal field names, provider error details, and low-level metadata into explicitly revealed diagnostics surfaces,
+- keeping each governance case decidable in one focused context where
+  practical instead of forcing cross-page reconstruction,
 - modeling execution outcome, data completeness, governance result, and lifecycle/readiness as distinct status dimensions when applicable,
 - making mutation scope legible before execution for every state-changing action (`TenantPilot only`, `Microsoft tenant`, or `simulation only`),
 - implementing the safe-execution flow for dangerous actions (configuration, safety checks/simulation, preview, hard confirmation where required, execute) or documenting an approved exemption,
 - keeping canonical nouns stable across routes, buttons, run titles, notifications, and audit prose,
+- keeping navigation aligned to operator workflows rather than storage
+  structures,
+- ensuring new automation, alerts, or autonomous flows reduce
+  search/review/click load instead of adding noise, extra lists, or
+  extra detail work,
+- preserving a calm, prioritized default state that distinguishes
+  actionable work from worth-watching context and reference-only
+  information,
 - keeping scope signals truthful and ensuring critical operational truth is visible by default,
 - keeping standard CRUD / Registry rows scanable rather than prose-heavy,
 - keeping workspace and tenant context explicit in navigation, actions, and page semantics so tenant pages do not silently expose workspace-wide actions.

docs/product/roadmap.md

@@ -3,7 +3,7 @@ # Product Roadmap
 > Strategic thematic blocks and release trajectory.
 > This is the "big picture" — not individual specs.
 
-**Last updated**: 2026-04-09
+**Last updated**: 2026-04-12
 
 ---
 
@@ -90,10 +90,24 @@ ### Platform Operations Maturity
 
 ## Mid-term (2–3 Quarters)
 
+### Decision-Based Operating Foundations
+Constitution hardening for decision-first governance, workflow-first navigation, surface taxonomy, and primary-vs-evidence surface refactoring.
+**Goal**: Prepare TenantPilot for a quieter, decision-centered operating model where primary surfaces ask for action and deeper technical detail stays available on demand.
+**Why it matters**: Governance inboxes, actionable alerts, and later autonomous-governance features will fail if they land on top of detail-heavy, entity-first navigation. This is the UX/product prerequisite layer for the later MSP Portfolio OS direction.
+**Depends on**: Current constitution and action-surface hardening, operator-truth work, existing navigation/context specs.
+**Scope direction**: First the constitution/rule delta, then a surface / IA classification of current product surfaces, then bounded retrofits that demote detail-first flows behind progressive disclosure instead of creating more top-level pages.
+
 ### MSP Portfolio & Operations (Multi-Tenant)
 Multi-tenant health dashboard, SLA/compliance reports (PDF), cross-tenant troubleshooting center.
 **Source**: 0800-future-features brainstorming, identified as highest priority pillar.
-**Prerequisite**: Cross-tenant compare (Spec 043 — draft only).
+**Prerequisites**: Decision-Based Operating Foundations, Cross-tenant compare (Spec 043 — draft only).
+
+### Human-in-the-Loop Autonomous Governance (Decision-Based Operating)
+Continuous detection, triage, decision drafting, approval-driven execution, and closed-loop evidence for governance actions across the workspace portfolio.
+**Goal**: Reduce operator work from searching and correlating to approving, rejecting, deferring, or time-boxing deviations while TenantPilot handles the mechanical follow-through.
+**Why it matters**: This is the longer-term MSP Portfolio OS layer. TenantPilot becomes the decision control plane for accountable governance, not just a browser for runs, evidence, and tenant state.
+**Depends on**: Decision-Based Operating Foundations, MSP Portfolio & Operations surfaces, drift/findings/exception maturity, actionable alerts with structured payloads, canonical operation/evidence truth.
+**Scope direction**: Start with governance inbox + decision packs + actionable alerts. Later add automation policies, guardrails, maintenance windows, dual approval, and before/after evidence automation. Keep human approval and auditability central; avoid blind autopilot remediation.
 
 ### Drift & Change Governance ("Revenue Lever #1")
 Change approval workflows (DEV→PROD with audit pack), guardrails/policy freeze windows, tamper detection.

docs/product/spec-candidates.md

@@ -5,7 +5,7 @@ # Spec Candidates
 >
 > **Flow**: Inbox → Qualified → Planned → Spec created → moved to `Promoted to Spec`
 
-**Last reviewed**: 2026-04-10 (added Compliance Control Catalog & Interpretation Foundation)
+**Last reviewed**: 2026-04-12 (added decision-based operating foundations and autonomous governance track)
 
 ---
 
@@ -708,6 +708,36 @@ ### Recovery Confidence — Automated Restore Testing & Readiness Reporting
 - **Dependencies**: Restore pipeline stable (Spec 011 and follow-ups), backup infrastructure mature, dry-run/preview infrastructure (restore preview), audit log foundation (Spec 134), RBAC/capability system (066+), evidence/reporting direction for downstream consumption
 - **Priority**: medium (high strategic value and strong product differentiation potential, but depends on restore pipeline maturity and is realistically sequenced after current hardening work)
 
+### Decision-First Operating Constitution Hardening
+- **Type**: foundation
+- **Source**: product strategy discussion 2026-04-12, constitution delta analysis against the decision-first operating model
+- **Problem**: TenantPilot already has strong constitution rules around truth, action surfaces, and progressive disclosure, but the product identity and review gates needed for a decision-first governance model are still distributed across separate rules. Upcoming MSP portfolio and governance-inbox work could otherwise reproduce entity-first, detail-heavy surfaces under a new label.
+- **Why it matters**: This is the rules-before-features step. Without it, later governance automation lands on the wrong UX contract and the product keeps growing by adding more pages instead of reducing operator attention load.
+- **Proposed direction**:
+  - Make TenantPilot's decision-first governance identity explicit in the constitution
+  - Add workflow-first navigation and "one case, one decision context" as binding principles
+  - Add an automation guardrail: automation must reduce attention load, not create more UI
+  - Extend spec/PR review gates with surface-role classification, human-in-the-loop justification, immediate-vs-on-demand information checks, and explicit search/click-load questions
+  - Treat this as a targeted evolution of the existing constitution, not as a second parallel manifesto
+- **Explicit non-goals**: Not a visual redesign. Not a rewrite of every current screen. Not a second constitution document.
+- **Dependencies**: Existing constitution baseline, action surface contract work, operator-truth vocabulary, current navigation/context hardening specs
+- **Priority**: high
+
+### Surface Taxonomy & Workflow-First IA Classification
+- **Type**: foundation
+- **Source**: product strategy discussion 2026-04-12, decision-first operating follow-up
+- **Problem**: TenantPilot has grown strong per-domain depth across operations, evidence, baselines, reviews, alerts, and tenant detail surfaces, but there is no canonical classification of which screens are primary decision surfaces, which are secondary context surfaces, and which are tertiary evidence/diagnostic surfaces. Existing navigation and prominence can still mirror entities and implementation structure more than operator workflows.
+- **Why it matters**: Without a classification-first audit, retrofits will stay local and future governance automation will just add another layer on top of the current detail-page landscape. This candidate produces the target IA truth before new inbox or portfolio-operating surfaces land.
+- **Proposed direction**:
+  - Catalogue major existing surfaces and classify them as primary decision, secondary context, or tertiary evidence/diagnostic
+  - Evaluate which information must be immediate versus on-demand per surface
+  - Identify where multiple pages should collapse into one decision context, and where detail should move behind tabs, drawers, or expansion
+  - Produce a workflow-first target IA and a bounded retrofit map rather than one umbrella redesign
+  - Reuse existing implemented/draft specs where they already solve local parts of the problem instead of inventing a second parallel IA program
+- **Explicit non-goals**: Not immediate implementation of all retrofits. Not a mass rewrite of every navigation group in one release. Not a justification for deleting audit or diagnostic depth.
+- **Dependencies**: Decision-First Operating Constitution Hardening, existing navigation/context/action-surface specs, product surface inventory
+- **Priority**: high
+
 ### MSP Multi-Tenant Portfolio Dashboard & SLA Reporting
 - **Type**: feature
 - **Source**: roadmap-to-spec coverage audit 2026-03-18, 0800-future-features brainstorming (pillar #1 — MSP Portfolio & Operations), product positioning for MSP portfolio owners
@@ -723,9 +753,26 @@ ### MSP Multi-Tenant Portfolio Dashboard & SLA Reporting
 - **Explicit non-goals**: Not a replacement for per-tenant dashboards or detail views (those remain the primary tenant-level surfaces). Not a generic BI/data warehouse initiative or a drag-and-drop report builder. Not a customer-facing analytics suite — this is an operator/MSP-internal tool. Not a cross-tenant compare/diff/promotion surface (that is the Cross-Tenant Compare & Promotion candidate). Not a system-console-level platform triage view (that is the System Console Multi-Workspace Operator UX candidate). Not a replacement for alerting (Specs 099/100 handle event-driven notifications; this is a review/monitoring surface).
 - **Boundary with Cross-Tenant Compare & Promotion**: Portfolio Dashboard = fleet-level monitoring, health aggregation, SLA reporting, operational overview. Cross-Tenant Compare = policy-level diff, staging-to-production promotion, configuration comparison. They share the multi-tenant dimension but solve fundamentally different problems.
 - **Boundary with System Console Multi-Workspace Operator UX**: Portfolio Dashboard = workspace-scoped MSP operator view, health/SLA/governance focus. System Console = platform-level triage, cross-workspace operator tooling, infrastructure focus. Different audiences, different panels.
-- **Dependencies**: Per-tenant operational health signals (backup, sync, drift, findings, provider connection status), workspace model, tenant inventory, alerting foundations (Specs 099/100), RBAC/capability system (066+)
+- **Dependencies**: Decision-First Operating Constitution Hardening, Surface Taxonomy & Workflow-First IA Classification, per-tenant operational health signals (backup, sync, drift, findings, provider connection status), workspace model, tenant inventory, alerting foundations (Specs 099/100), RBAC/capability system (066+)
 - **Priority**: medium (high strategic value, significant data aggregation effort; depends on per-tenant signal maturity)
 
+### Human-in-the-Loop Autonomous Governance / Governance Inbox
+- **Type**: feature
+- **Source**: product strategy discussion 2026-04-12, MSP Portfolio OS direction
+- **Problem**: Operators still have to pull together drift, evidence, operation runs, policy versions, alerts, and exception history themselves to decide what to do next. Alerting can notify, but the product does not yet provide a workspace-level decision inbox, structured action payloads, recommended next steps, or controlled execution contracts that let the system continue after approval.
+- **Why it matters**: This is the long-term decision-based operating moat. TenantPilot stops being just a place to inspect tenant state and becomes the system that detects, triages, drafts the decision, collects approval, executes within guardrails, and preserves the full evidence chain. That is much harder for generic AI tooling to replace than simple configuration explainability.
+- **Proposed direction**:
+  - Governance inbox for pending decisions across tenants and workflows
+  - Actionable alerts/events with structured payloads that open directly into a decision context rather than a generic detail page
+  - Continuous detection and auto-triage against baselines, findings, accepted deviations, run history, and risk signals
+  - Decision packs: what changed, why it matters, recommended action, blast radius, confidence, approvals required, rollback path
+  - Controlled execution after approval: approve, reject, defer, or accept deviation, with automation policies, maintenance windows, dual approval, and scope guardrails where needed
+  - Closed-loop evidence: before snapshot, approval record, execution run, after snapshot, audit trail, review-pack linkage
+- **Explicit non-goals**: Not blind autopilot remediation. Not a chat-first admin experience. Not a replacement for drift/change governance, findings, or exception workflows; it orchestrates across them.
+- **Boundary with Drift Change Governance**: Drift Change Governance owns drift-specific approval, freeze-window, and tamper rules. This candidate owns the broader operating model: inbox, decision routing, recommended actions, controlled execution, and evidence closure across drift, evidence, review, and operational workflows.
+- **Dependencies**: Decision-First Operating Constitution Hardening, Surface Taxonomy & Workflow-First IA Classification, MSP Multi-Tenant Portfolio Dashboard & SLA Reporting, drift/findings/exception workflow maturity, actionable alert/event payloads, canonical operation/evidence truth
+- **Priority**: medium (high strategic value, intentionally sequenced after the decision-first foundations)
+
 ### Policy Lifecycle / Ghost Policies (Spec 900 refresh)
 - **Type**: feature
 - **Source**: Spec 900 draft (2025-12-22), HANDOVER risk #9

docs/product/standards/README.md

@@ -4,7 +4,7 @@ # Product Standards
 > Specs reference these standards; they do not redefine them.
 > Guard tests enforce critical constraints automatically.
 
-**Last reviewed**: 2026-04-11
+**Last reviewed**: 2026-04-12
 
 ---
 
@@ -42,7 +42,7 @@ ## Related Docs
 
 | Document | Location | Purpose |
 |---|---|---|
-| Constitution | `.specify/memory/constitution.md` | Permanent principles (PROP-001, BLOAT-001, UI-CONST-001, UI-SURF-001, ACTSURF-001, UI-HARD-001, UI-EX-001, HDR-001, OPSURF-001, UI-FIL-001, UX-001, Action Surface Contract, RBAC-UX) |
+| Constitution | `.specify/memory/constitution.md` | Permanent principles (PROP-001, BLOAT-001, UI-CONST-001, DECIDE-001, UI-SURF-001, ACTSURF-001, UI-HARD-001, UI-EX-001, HDR-001, OPSURF-001, UI-FIL-001, UX-001, Action Surface Contract, RBAC-UX) |
 | Product Principles | `docs/product/principles.md` | High-level product decisions |
 | Table Rollout Audit | `docs/ui/filament-table-standard.md` | Rollout inventory and implementation state from Spec 125 |
 | Action Surface Contract | `docs/ui/action-surface-contract.md` | Original action surface reference (now governed by this standard) |