GIA/artifacts/plans/2026-03-07-settings-integrity-and-controls-reorg.md

Plan: Settings Integrity and Controls Reorganization

Objective

Create a single coherent configuration model for Security, Commands, and Tasks so UI labels, enforcement behavior, docs, and navigation all match actual runtime behavior.

Current Integrity Findings

1) Scope Registry and Enforcement Are Out of Sync

• Gateway command routes enforce scopes that are not exposed in Fine-Grained Security Scopes:
  • gateway.contacts
  • gateway.help
  • gateway.whoami
• Fine-Grained Security Scopes currently expose only:
  • gateway.tasks, gateway.approval, tasks.submit, tasks.commands, command.bp, command.codex, command.claude
• Result: users cannot configure all enforced gateway capabilities from the UI.

2) “Require Trusted Fingerprint” Semantics Are Incorrect

• UI and labels imply trust-list based enforcement.
• Runtime policy enforcement checks UserXmppOmemoState.latest_client_key equality, not UserXmppOmemoTrustedKey trust records.
• Result: behavior is “match latest observed key,” not “require trusted fingerprint.”

3) Command Surfaces Are Split Across Inconsistent Places

• Command Routing UI create flow exposes command slugs: bp, codex.
• Runtime command engine auto-bootstraps claude profile and bindings.
• Security scopes include command.claude, but Command Routing create UI does not.
• Result: commands are partially configurable depending on entrypoint.

4) Task and Command Control Planes Interlock Implicitly, Not Explicitly

• Task settings contain provider approval routing (Codex/Claude approver service/identifier).
• Security permissions contain policy gates (tasks.*, command.*, gateway.*).
• Command Routing controls profile/binding/variant policy.
• These are tightly coupled but not represented as one layered model in UI/docs.

5) Settings Shell Coverage Is Incomplete

• Shared settings hierarchy nav is context-processor driven and route-name based.
• Settings routes missing from modules/general/security group coverage include:
  • codex_settings
  • codex_approval
  • translation_preview
• Result: some settings pages can miss expected local tabs/title context.

6) Documentation Drift

• Undocumented or under-documented features now in production behavior:
  • Fine-Grained Security Scopes + Global Scope Override
  • OMEMO trust management and per-direction encryption toggles
  • Business Plan Inbox under Settings Modules
• Potentially misleading documentation:
  • Security wording implies trusted-key enforcement that is not implemented.

Reorganization Principles

1. One capability registry, reused by:
   • Security Permissions UI
   • command/task/gateway dispatch
   • documentation generation
2. One settings-shell contract for every /settings/* page:
   • title
   • category tabs
   • breadcrumb
3. Explicit layered model:
   • Layer A: transport encryption/security
   • Layer B: capability permissions (scope policy)
   • Layer C: feature configuration (tasks/commands/providers)
4. No hardcoded duplicated scope lists in multiple files.

Target Information Architecture

Security

• Encryption: OMEMO transport controls + trust management.
• Permissions: Fine-Grained Security Scopes (capability policy only).
• 2FA: account factor settings.

Modules

• Commands: command profiles, bindings, variant policies.
• Tasks: extraction/defaults/overrides/provider pipelines.
• Translation: translation bridge settings.
• Availability: adapter availability controls.
• Business Plans: inbox/editor for generated artifacts.

General

• Notifications
• System
• Accessibility

AI

• Models
• Traces

Phased Execution Plan

Phase 1: Canonical Capability Registry

1. Add a central capability registry module (single source of truth):
   • key
   • label
   • description
   • group (gateway, tasks, commands, agentic, etc.)
   • owning feature page URL
2. Migrate SecurityPage scope rendering to this registry.
3. Migrate gateway/command/task dispatchers to reference registry keys.
4. Add automated integrity test:
   • every enforced scope key must exist in registry
   • every registry key marked user-configurable must appear in Permissions UI

Phase 2: Trusted Key Enforcement Correction

1. Define authoritative trust policy behavior:
   • require_trusted_fingerprint must validate against UserXmppOmemoTrustedKey.
2. Preserve backwards compatibility via migration path:
   • existing latest-key behavior can be temporarily represented as an optional fallback mode.
3. Update labels/help to match exact behavior.
4. Add tests:
   • trusted key allows
   • untrusted key denies
   • unknown key denies

Phase 3: Commands/Tasks Control Plane Alignment

1. Unify command surface definitions:
   • Command Routing create/edit options include all supported command slugs (bp, codex, claude).
2. Add explicit cross-links:
   • Tasks settings references Command Routing and Permissions scopes directly.
   • Command Routing references Permissions scopes affecting each profile.
3. Introduce capability-impact preview panel:
   • for each command/task action, show effective allow/deny by scope and channel.

Phase 4: Settings Shell Normalization

1. Replace route-name allowlists in settings_hierarchy_nav with category mapping table.
2. Ensure all /settings/* pages declare category + tab metadata.
3. Include missing routes (codex_settings, codex_approval, translation_preview) in shell.
4. Add test to fail when a /settings/* route lacks shell metadata.

Phase 5: Documentation Synchronization

1. Add a settings matrix doc generated (or validated) from the capability registry:
   • capability key
   • UI location
   • enforced by code path
2. Update README.md and INSTALL.md security/modules sections.
3. Add "policy semantics" section clarifying:
   • encryption-required vs per-scope OMEMO requirements
   • trusted key behavior
   • global override precedence

Acceptance Criteria

• Every enforced scope is user-visible/configurable (or intentionally internal and documented).
• “Require Trusted Fingerprint” enforcement uses trust records, not only latest observed key.
• Command Routing and runtime-supported command slugs are aligned.
• All /settings/* pages show consistent settings shell navigation.
• Security/tasks/commands docs reflect real behavior and pass integrity checks.

Risks and Mitigations

• Risk: policy behavior change blocks existing workflows.
  • Mitigation: add compatibility flag and staged rollout.
• Risk: registry migration introduces missing scope mappings.
  • Mitigation: integrity test that compares runtime-enforced keys vs registry.
• Risk: UI complexity increase.
  • Mitigation: keep layered model with concise, context-aware summaries.

Implementation Notes

• Keep migration incremental; avoid big-bang rewrite.
• Prioritize Phase 1 + Phase 2 first, because they are correctness and security semantics issues.
• Do not add new transport-specific branches; keep service-agnostic evaluation path in policy engine.