docs: add decision-first operating foundations (#228)

## Summary
- add the decision-first operating constitution foundation and update the Spec Kit templates to enforce it
- extend the product roadmap with staged decision-based operating foundations and a later human-in-the-loop autonomous governance lane
- add matching spec candidates for constitution hardening, workflow-first surface classification, and a governance inbox / autonomous governance track

## Testing
- not run (documentation and template changes only)

Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de>
Reviewed-on: #228

.specify/memory/constitution.md

@@ -1,24 +1,37 @@
 <!--
 Sync Impact Report
 
-- Version change: 2.0.0 -> 2.1.0
+- Version change: 2.2.0 -> 2.3.0
 - Modified principles:
-  - UX-001 (Layout & IA): header action line strengthened from SHOULD to MUST
-    with cross-reference to new HDR-001
+  - 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:
-  - Header Action Discipline & Contextual Navigation (HDR-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: HDR-001 added)
-  - ✅ .specify/templates/tasks-template.md (Filament UI section: HDR-001 added)
-  - ⚠ .specify/templates/spec-template.md (no changes needed; existing
-    UI/UX Surface Classification and Operator Surface Contract tables already
-    cover header action placement implicitly)
+  - ✅ .specify/templates/plan-template.md (Constitution Check updated for
+    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 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
@@ -318,13 +331,189 @@ ### 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 surface type before implementation. Ad-hoc interaction models are forbidden.
+Every new admin surface MUST be assigned exactly one broad action-surface
+class before implementation. Ad-hoc interaction models are forbidden.
+
+The allowed broad action-surface classes are:
+- Record / Detail / Edit
+- Monitoring / Queue / Workbench
+- List / Table / Bulk
+- Wizard / Flow
+- Utility / System
+
+Operator-facing surfaces MUST also declare exactly one detailed surface
+type from the taxonomy below. The broad class determines the action
+hierarchy first; the detailed surface type refines it.
 
 ##### CRUD / List-first Resource
 - Purpose: scan, find, open, and selectively mutate many business records.
@@ -377,6 +566,157 @@ ##### Detail-first Operational Surface
 - Destructive actions: detail header or grouped header actions only, always with confirmation.
 - Row click and explicit View/Inspect: not applicable.
 
+#### Action Surface Discipline (ACTSURF-001)
+
+Goal: actions across all surfaces MUST make the next sensible operator
+step obvious, keep safe navigation distinct from mutation, and prevent
+dangerous or governance-relevant actions from sitting casually beside
+harmless context changes.
+
+##### Surface class first
+
+- Every new or materially changed surface MUST declare exactly one broad
+  action-surface class before actions are designed.
+- Different surface classes MAY use different action models only when
+  the difference is deliberate, documented, and justified by the
+  workflow.
+- Detailed surface types refine the rule set; they do not replace the
+  broad class requirement.
+
+##### Record / Detail / Edit surfaces
+
+- Classic record/detail/edit pages MUST expose at most one visible
+  primary header action.
+- Pure navigation MUST NOT live in the header when it can be placed
+  inline at summary, field, badge, status, or related-context level.
+- Secondary, rare, or administrative actions MUST be grouped.
+- Multiple equally weighted mutation buttons in the header are
+  forbidden.
+- Destructive, irreversible, or governance-relevant actions MUST be
+  clearly separated from routine actions.
+- The likely next operator step MUST be recognizable within seconds.
+- HDR-001 is the binding specialization for record/detail/edit headers.
+
+##### Monitoring / Queue / Workbench surfaces
+
+- Surface-level context, scope context, navigation, selection actions,
+  and object actions MUST NOT be mixed as one flat header strip.
+- Scope indicators are context signals, not ordinary calls to action.
+- Selection-dependent actions SHOULD become prominent only when a
+  selection or focused object actually exists.
+- Record-page header rules MUST NOT be copied blindly onto workbench
+  surfaces.
+- Workbench surfaces MAY use a different action model, but that model
+  MUST be explicit, repeatable, and internally consistent.
+
+##### List / Table / Bulk surfaces
+
+- Inspect/open affordances MUST remain consistent within the same
+  surface class.
+- Bulk actions are allowed only for genuine multi-record work.
+- Row actions MUST NOT dominate reading and scanning.
+- Rare, destructive, or governance-relevant actions MUST NOT accumulate
+  casually in default row actions.
+- Tables exist primarily to scan, filter, compare, and decide; they
+  MUST NOT become unstructured action stockpiles.
+
+##### Wizard / Flow surfaces
+
+- Wizard actions MUST reflect staged progression, explicit back/cancel
+  semantics, and safe confirmation at the step where risk becomes real.
+- Wizard pages MAY expose more than one visible action when the flow
+  genuinely requires progression, backtracking, or guarded cancellation.
+- Even in a wizard, the next primary step MUST remain obvious.
+
+##### Utility / System surfaces
+
+- Utility and system pages MAY use narrower tooling-oriented action
+  sets, but they MUST still separate safe navigation, routine control,
+  and dangerous intervention.
+- System or recovery status does not justify casual placement of
+  destructive or governance-changing actions.
+
+##### Action grouping and order
+
+- Actions MUST be ordered by meaning, frequency, and risk.
+- The preferred order is:
+  1. primary next step
+  2. common secondary action
+  3. rare or contextual action
+  4. dangerous or irreversible action
+- An `ActionGroup` / More menu is not a junk drawer. Navigation,
+  mutation, external links, and destructive actions inside a group MUST
+  still be named, ordered, and separated coherently.
+
+##### Navigation vs mutation
+
+- Navigation and mutation are different intent classes and MUST NOT
+  appear as equal-weight peers without explicit hierarchy.
+- Harmless context switches MUST NOT visually overpower
+  governance-relevant actions.
+- Pure context navigation SHOULD live near the content it concerns
+  rather than as header filler.
+
+##### Governance friction
+
+- Actions with risk, blast radius, or irreversible effect MUST use
+  shared governance-friction rules rather than per-surface improvisation.
+- Depending on impact, the required friction is confirmation, optional
+  reason, mandatory reason, typed confirmation, or staged flow.
+- Clear danger semantics and separated placement are mandatory for
+  dangerous or governance-changing actions.
+
+##### Exceptions require explicit reason
+
+- New surfaces MAY deviate only when the surface class or workflow truly
+  requires it.
+- Allowed justification labels are:
+  - Special type
+  - Workflow hub
+  - Wizard
+  - Utility / System surface
+  - Another clearly defined exception documented in the governing spec
+- "Historically grew this way" and "it was easy to add to the header"
+  are invalid reasons.
+
+##### Reuse before invention
+
+- New features MUST reuse existing disciplined patterns, reference
+  architectures, and shared primitives when they fit the chosen surface
+  class.
+- Reference patterns are reuse baselines, not automatic mandates for
+  every surface.
+
+##### Constitution over convenience
+
+- Local implementation speed MUST NOT override consistent action
+  hierarchy.
+- No new feature may introduce:
+  - multiple equal-rank header mutations without a clear primary
+  - navigation as casual header filler
+  - unreflective mixing of record, workbench, and governance patterns
+  - new local exceptions without explicit rationale
+
+##### Review gate
+
+Every new or materially changed surface with actions MUST answer:
+1. What broad action-surface class is it?
+2. What is the one most likely next operator action?
+3. Is navigation cleanly separated from mutation?
+4. Are rare or risky actions removed from the primary plane?
+5. Is the hierarchy scanable in a few seconds?
+6. Is this a real special type or just an unordered exception?
+
+If those answers are not clear, the surface is non-conformant.
+
+##### Canonical outcome
+
+- The goal is not the smallest possible number of buttons.
+- A conformant surface highlights the next sensible step, separates
+  context, navigation, mutation, and danger cleanly, remains structured
+  as capability grows, and applies the same principles consistently
+  across the product.
+
 #### Hard Rules (UI-HARD-001)
 
 ##### Primary inspect model
@@ -509,6 +849,8 @@ #### Filament UI — Action Surface Contract (NON-NEGOTIABLE)
 
 Behavior over declaration
 - Every spec MUST include both a UI/UX Surface Classification and a UI Action Matrix.
+- Every changed operator-facing surface MUST declare its broad
+  action-surface class and the one most likely next operator action.
 - Custom action-surface contracts are legitimate only when they validate rendered behavior, not only declarations or slot counts.
 - A change is not Done unless the implemented interaction semantics conform to the declared surface type or an approved exception documents and tests the deviation.
 
@@ -532,7 +874,10 @@ #### Filament UI — Layout & Information Architecture Standards (UX-001)
 - When records exist, that primary CTA moves to the header and MUST NOT be duplicated in the empty state shell.
 
 Actions and flows
-- Pages MUST expose at most one primary header action and one secondary header action; all others belong in groups (see HDR-001 for the full header discipline rule).
+- Record / Detail / Edit pages MUST expose at most one visible primary
+  header action. Any additional visible secondary header action requires
+  explicit justification under ACTSURF-001 / HDR-001; the rest belong in
+  groups or contextual placement.
 - Multi-step or high-risk flows MUST use a wizard or an equivalent staged flow with preview and confirmation.
 - Destructive actions remain non-primary and confirmed.
 
@@ -545,9 +890,12 @@ #### Filament UI — Layout & Information Architecture Standards (UX-001)
 - Shared layout builders such as `MainAsideForm`, `MainAsideInfolist`, and `StandardTableDefaults` SHOULD be reused where available.
 - A change is not Done unless UX-001 is satisfied or an approved exception documents why not.
 
-#### Header Action Discipline & Contextual Navigation (HDR-001)
+#### Record / Detail / Edit Header Discipline & Contextual Navigation (HDR-001)
+
+Goal: record, detail, and edit pages MUST be comprehensible within
+seconds. HDR-001 is the binding record/detail/edit specialization of
+ACTSURF-001.
 
-Goal: record and detail pages MUST be comprehensible within seconds.
 Header actions are reserved for the primary workflow of the current page
 and MUST NOT become a dumping ground for every available action or
 navigation jump.
@@ -565,6 +913,8 @@ ##### Maximum one primary visible header action
   primary visible header action.
 - That action MUST represent the most obvious next operator step on
   exactly this page.
+- Multiple equally weighted mutation buttons in the header are
+  forbidden.
 
 ##### Navigation does not belong in headers
 
@@ -594,6 +944,8 @@ ##### Rare secondary actions belong in an Action Group
   or are only occasionally needed MUST NOT appear as equally weighted
   visible header buttons.
 - They MUST be placed in an Action Group.
+- The Action Group itself MUST remain structured; it MUST NOT become an
+  unlabelled mix of navigation, external links, mutations, and danger.
 
 ##### Header clarity over implementation convenience
 
@@ -744,17 +1096,58 @@ #### Spec Scope Fields (SCOPE-002)
 #### Enforcement Model (UI-REVIEW-001)
 
 Spec review requirements
-- Every spec that changes an operator-facing surface MUST answer: surface type, primary inspect/open model, row-click rule, whether explicit View/Inspect exists or is forbidden, where secondary actions live, where destructive actions live, 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.
+- 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, 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
-- A PR MUST NOT pass when it introduces more than one primary inspect model, redundant View beside row click, destructive inline actions beside inspect on standard lists, empty overflow or bulk groups, long workflow labels in dense rows, misleading scope chips, drifting domain nouns, hidden critical operational truth, or undocumented exceptions without dedicated tests.
+- A PR MUST NOT pass when it introduces more than one primary inspect
+  model, redundant View beside row click, destructive inline actions
+  beside inspect on standard lists, empty overflow or bulk groups, long
+  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, 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.
@@ -768,6 +1161,23 @@ #### 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.
 - Every list has exactly one primary inspect/open model.
 - CRUD and Registry surfaces use one-click open.
@@ -777,6 +1187,10 @@ #### Appendix A - One-page Condensed Constitution
 - Destructive actions never sit openly beside inspect on standard lists.
 - Overflow is standardized per surface class and is never empty.
 - Bulk exists only when it is genuinely useful.
+- Navigation and mutation do not share equal visual weight without
+  explicit hierarchy.
+- Monitoring and workbench surfaces separate scope/context, selection,
+  navigation, and object actions.
 - Scope chips must be truthful.
 - Domain nouns are canonical and stable.
 - Critical operational truth is default-visible.
@@ -788,11 +1202,24 @@ #### Appendix A - One-page Condensed Constitution
 
 #### Appendix B - Feature Review Checklist
 
-- Surface type is declared.
+- 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.
 - Primary inspect/open model is defined.
 - Row-click rule is decided.
 - View/Inspect is correctly present or correctly forbidden.
 - Edit-as-inspect is used only when allowed.
+- Navigation and mutation are separated intentionally.
 - Secondary actions are grouped correctly.
 - Destructive actions are placed correctly.
 - Overflow is not empty.
@@ -806,18 +1233,32 @@ #### Appendix B - Feature Review Checklist
 - Header passes the 5-second scan rule (HDR-001).
 - No pure navigation in the header.
 - Governance-changing actions have extra friction.
+- Any special type or workflow-hub exception is real and justified.
 
 #### 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.
 - More menus or bulk menus are empty.
+- A More menu becomes a mixed junk drawer with no ordering logic.
 - Scope chips have no real scope effect.
 - Runs and Operations are used as competing primary collection nouns.
 - Long workflow labels live in dense tables.
 - Edit is used as default inspect even though a true View surface exists.
 - Queue surfaces throw the operator out of context through row click.
+- A workbench surface mixes scope, selection, navigation, and object
+  actions as one flat header rail.
 - Critical health or operability truth is hidden by default.
 - A contract claims conformance while the rendered UI behaves differently.
 - Header has multiple equally weighted buttons without clear prioritization.
@@ -893,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.
 
@@ -906,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.1.0 | **Ratified**: 2026-01-03 | **Last Amended**: 2026-04-07
+**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
@@ -71,7 +79,14 @@ ## Constitution Check
 - Operator surfaces (OPSURF-001): each new or materially refactored operator-facing page defines a page contract covering persona, surface type, operator question, default-visible info, diagnostics-only info, status dimensions, mutation scope, primary actions, and dangerous actions
 - Filament UI Action Surface Contract: for any new/modified Filament Resource/RelationManager/Page, define Header/Row/Bulk/Empty-State actions, ensure every List/Table has a surface-appropriate inspect affordance, remove redundant View when row click or identifier click already opens the same destination, keep standard CRUD/Registry rows to inspect plus at most one inline safe shortcut, group or relocate the rest to “More” or detail header, forbid empty bulk/overflow groups, require confirmations for destructive actions, write audit logs for mutations, enforce RBAC via central helpers (non-member 404, member missing capability 403), and ensure CI blocks merges if the contract is violated or not explicitly exempted
 - Filament UI UX-001 (Layout & IA): Create/Edit uses Main/Aside (3-col grid, Main=columnSpan(2), Aside=columnSpan(1)); all fields inside Sections/Cards (no naked inputs); View uses Infolists (not disabled edit forms); status badges use BADGE-001; empty states have specific title + explanation + 1 CTA; max 1 primary + 1 secondary header action (see HDR-001); tables provide search/sort/filters for core dimensions; shared layout builders preferred for consistency
-- Header action discipline (HDR-001): record/detail pages expose at most 1 primary visible header action; pure navigation (Open finding, Open tenant, View related run, etc.) is placed at the relevant field/badge/relation, NOT in the header; destructive or governance-changing actions are separated and require friction; rare actions live in Action Groups; every record/detail page passes the 5-second scan rule
+- Action-surface discipline (ACTSURF-001 / HDR-001): every changed
+  surface declares one broad action-surface class; the spec names the
+  one likely next operator action; navigation is separated from
+  mutation; record/detail/edit pages keep at most one visible primary
+  header action; monitoring/workbench surfaces separate scope/context,
+  selection actions, navigation, and object actions; risky or rare
+  actions are grouped and ordered by meaning/frequency/risk; any special
+  type or workflow-hub exception is explicit and justified
 ## Project Structure
 
 ### Documentation (this feature)

.specify/templates/spec-template.md

@@ -35,22 +35,37 @@ ## 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.
+fill out one row per affected surface. Declare the broad Action Surface
+Class first, then the detailed Surface Type. Keep this table in sync
+with the Decision-First Surface Role section above.
 
-| Surface | Surface Type | 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 |
-|---|---|---|---|---|---|---|---|---|---|---|---|
-| e.g. Tenant policies page | CRUD / List-first Resource | Full-row click | required | One inline safe shortcut + More | More / detail header | /admin/t/{tenant}/policies | /admin/t/{tenant}/policies/{record} | Tenant chip scopes rows and actions | Policies / Policy | Policy health, drift, assignment coverage | none |
+| 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 |
+|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
+| e.g. Tenant policies page | List / Table / Bulk | CRUD / List-first Resource | Open policy for review | Full-row click | required | One inline safe shortcut + More | More / detail header | /admin/t/{tenant}/policies | /admin/t/{tenant}/policies/{record} | Tenant chip scopes rows and actions | Policies / Policy | Policy health, drift, assignment coverage | none |
 
 ## 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)*
 
@@ -199,19 +214,50 @@ ## 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 (UI-CONST-001 / UI-SURF-001 / UI-HARD-001 / UI-EX-001 / UI-REVIEW-001):** If this feature adds or changes an operator-facing surface, the spec MUST describe:
-- the chosen surface type and why it is the correct classification,
+**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,
+- the one most likely next operator action,
 - the one and only primary inspect/open model,
 - whether row click is required, allowed, or forbidden,
 - whether explicit View or Inspect is present, and why it is present or forbidden,
+- where pure navigation lives and why it is not competing with mutation,
 - where secondary actions live,
 - where destructive actions live,
+- how grouped actions are ordered by meaning, frequency, and risk,
 - the canonical collection route and canonical detail route,
 - the scope signals shown to the operator and what real effect each one has,
 - the canonical noun used across routes, labels, runs, notifications, and audit prose,
 - which critical operational truth is visible by default,
 - and any catalogued exception type, rationale, and dedicated test coverage.
 
+**Constitution alignment (ACTSURF-001 - action hierarchy):** If this
+feature adds or materially changes header actions, row actions, bulk
+actions, or workbench controls, the spec MUST describe:
+- how navigation, mutation, context signals, selection actions, and
+  dangerous actions are separated,
+- why any visible secondary action deserves primary-plane placement,
+- why any ActionGroup is structured rather than a mixed catch-all,
+- and why any workflow-hub, wizard, system, or other special-type
+  exception is genuine rather than a convenience shortcut.
+
 **Constitution alignment (OPSURF-001):** If this feature adds or materially refactors an operator-facing surface, the spec MUST describe:
 - how the default-visible content stays operator-first on `/admin` and avoids raw implementation detail,
 - which diagnostics are secondary and how they are explicitly revealed,

.specify/templates/tasks-template.md

@@ -39,30 +39,62 @@ # 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.
 **Filament UI Action Surfaces**: If this feature adds/modifies any Filament Resource / RelationManager / Page, tasks MUST include:
 - filling the spec’s “UI Action Matrix” for all changed surfaces,
+- assigning exactly one broad action-surface class to every changed
+  operator-facing surface and keeping the detailed surface type in sync
+  with the spec,
+- identifying the one likely next operator action for each changed
+  surface and shaping the visible hierarchy around it,
 - implementing required action surfaces (header/row/bulk/empty-state CTA for lists; header actions for view; consistent save/cancel on create/edit),
 - ensuring every List/Table has exactly one primary inspect/open model with the correct surface-appropriate affordance,
 - removing redundant View/Inspect actions when row click or identifier click already opens the same destination,
 - keeping standard CRUD / Registry rows to inspect/open plus at most one inline safe shortcut,
+- separating navigation from mutation so pure context changes do not
+  compete visually with state-changing actions,
 - moving additional secondary actions into More or the detail header,
+- ordering visible actions and grouped actions by meaning, frequency,
+  and risk rather than append order,
 - placing destructive actions in More or the detail header for standard lists and using catalogued exceptions only where allowed,
+- ensuring workbench and monitoring surfaces separate scope/context,
+  selection actions, navigation, and object actions instead of mixing
+  them into one flat header zone,
 - grouping bulk actions via BulkActionGroup,
 - preventing empty `ActionGroup` / `BulkActionGroup` placeholders,
 - adding confirmations for destructive actions (and typed confirmation where required by scale),
 - adding `AuditLog` entries for relevant mutations,
 - using native Filament components or shared UI primitives before any local Blade/Tailwind assembly for badges, alerts, buttons, and semantic status surfaces,
 - avoiding page-local semantic color, border, rounding, or highlight styling when Filament props or shared primitives can express the same state,
+- documenting any workflow-hub, wizard, utility/system, or other
+  special-type exception in the spec/PR and adding dedicated test
+  coverage,
 - documenting any catalogued UI exception in the spec/PR and adding dedicated test coverage,
 - documenting any UI-FIL-001 exception with rationale in the spec/PR,
 - adding/updated tests that enforce the contract and block merge on violations, OR documenting an explicit exemption with rationale.
@@ -71,8 +103,13 @@ # Tasks: [FEATURE NAME]
 - ensuring all form fields are inside Sections/Cards (no naked inputs at root schema level),
 - ensuring View pages use Infolists (not disabled edit forms); status badges use BADGE-001,
 - ensuring empty states show a specific title + explanation + exactly 1 CTA; non-empty tables move CTA to header,
-- capping header actions to max 1 primary + 1 secondary (rest grouped),
-- enforcing HDR-001 header action discipline: at most 1 primary visible action per record/detail page; pure navigation (Open finding, Open tenant, View related run, etc.) placed at the relevant field/badge/relation, NOT in the header; destructive or governance-changing actions separated and requiring friction; rare actions in Action Groups; every record/detail page passing the 5-second scan rule,
+- enforcing ACTSURF-001 / HDR-001 action discipline: record/detail/edit
+  pages keep at most 1 visible primary header action; pure navigation
+  moves to contextual placement; destructive or governance-changing
+  actions are separated and require friction; monitoring/workbench
+  surfaces use their own layered hierarchy; rare actions live in
+  structured Action Groups; every affected surface passes the few-second
+  scan rule,
 - using shared layout builders (e.g., `MainAsideForm`, `MainAsideInfolist`, `StandardTableDefaults`) where available,
 - OR documenting an explicit exemption with rationale if UX-001 is not fully satisfied.
 **Badges**: If this feature changes status-like badge semantics, tasks MUST use `BadgeCatalog` / `BadgeRenderer` (BADGE-001),

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-03-28
+**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, UI-HARD-001, UI-EX-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) |