decision: gate SR-04 behind V1R4C4 reliability freeze

docs/proposals/V1R4C4-SR04-portal-aios-visibility-gap.md

@@ -1,168 +0,0 @@
-# V1R4C4 SR-04: Portal AIOS Visibility Gap
-
-Status: visibility gap confirmed; activation decision required
-
-Priority: P1 / user-visible integration
-
-Risk: medium
-
-## User Report
-
-The authenticated user portal entry does not show the expected new AIOS features:
-
-```text
-/portal/me/
-```
-
-## Current Finding
-
-The current baseline is V1R4C3.
-
-V1R4C3 completed several backend and governance capabilities, but the Portal AIOS Integration Merge was explicitly deferred. Therefore, the user portal not showing new AIOS modules is consistent with the current deployment state.
-
-This is not primarily a browser cache issue. It is a merge/deploy visibility gap.
-
-## Evidence
-
-A related branch already contains portal integration work:
-
-```text
-patch/user-portal-me-route-diagnostics-20260709
-```
-
-Observed contents include:
-
-- `active-runtime/app/portal_aios_module_registry.py`
-- `active-runtime/app/portal_aios_navigation.py`
-- `active-runtime/app/portal_aios_dashboard_api.py`
-- `active-runtime/app/portal_aios_module_api.py`
-- `active-runtime/app/portal_integration_api.py`
-- `active-runtime/app/portal_integration_health.py`
-- `active-runtime/app/portal_system_health_adapter.py`
-- `config/portal-aios-frontend-contract.yaml`
-- `acceptance/portal-aios-integration-matrix.yaml`
-
-The branch defines expected portal APIs:
-
-```text
-/portal/me/aios/manifest
-/portal/me/aios/dashboard
-/portal/me/aios/health
-```
-
-It also defines role-visible AIOS modules, including:
-
-- Task Center
-- Operations
-- System Health
-- Search Governance
-- Agent Observability
-- Architecture Changes
-- Architect Research
-- Governance
-
-## Diagnosis
-
-Current state:
-
-```text
-AIOS backend/governance features exist or are staged
-        ↓
-Portal integration branch exists
-        ↓
-Portal integration is not in current baseline/main deployment
-        ↓
-/portal/me/ does not display new modules
-```
-
-Therefore, the missing portal feature is expected until SR-04 is integrated and deployed.
-
-## Required Fix
-
-Activate SR-04 as a controlled portal integration task after reliability guardrails are satisfied, or explicitly approve fast-track portal visibility integration if user-visible delivery is now higher priority.
-
-Minimum integration requirements:
-
-1. Backend route registration for:
-
-```text
-/portal/me/aios/manifest
-/portal/me/aios/dashboard
-/portal/me/aios/health
-```
-
-2. Portal frontend route/menu integration under:
-
-```text
-/portal/me/
-```
-
-3. API proxy configuration from user portal to AIOS backend routes.
-
-4. RBAC mapping:
-
-```text
-user -> task center / authorized modules only
-group_admin -> operations, health, search, agents
-owner -> governance, architecture, owner modules
-```
-
-5. Production deployment refresh.
-
-## Acceptance Criteria
-
-After login, the portal must show the expected modules by role.
-
-### User
-
-- sees authorized user modules;
-- does not see owner-only modules.
-
-### Group admin
-
-- sees task center;
-- sees operations;
-- sees system health;
-- sees search;
-- sees agents.
-
-### Owner
-
-- sees all AIOS modules;
-- sees governance and architecture modules;
-- sees owner gate / approval modules.
-
-### APIs
-
-The following must return valid data after authentication/proxy:
-
-```text
-/portal/me/aios/manifest
-/portal/me/aios/dashboard
-/portal/me/aios/health
-```
-
-## Safety Constraints
-
-- Do not combine SR-04 with SR-01 root-cause repair unless explicitly approved.
-- Do not bypass RBAC checks to make the UI visible.
-- Do not deploy portal integration without confirming auth callback and proxy routes.
-- Do not treat backend route existence as frontend visibility; both must be verified.
-
-## Recommended Path
-
-Because the user has now observed that new functionality is not visible, SR-04 should move from `deferred` to `activation-ready`.
-
-Recommended execution order:
-
-1. Complete or confirm SR-01 reliability guardrails.
-2. Integrate SR-02 watcher cleanup if already green.
-3. Start SR-04 portal visibility integration as P1 user-visible work.
-4. Validate portal modules after login.
-5. Include successful SR-04 in V1R4C4 or a follow-up V1R4C5 if reliability gating requires separation.
-
-## Current Decision Needed
-
-If user-visible portal delivery is required now, approve activation of SR-04.
-
-If reliability remains the only priority for V1R4C4, keep SR-04 deferred and record this report as expected-not-yet-deployed behavior.

docs/proposals/V1R4C4-reliability-freeze-before-SR04.md

@@ -0,0 +1,116 @@
+# V1R4C4 Reliability Freeze Before SR-04
+
+Status: accepted
+
+Decision date: 2026-07-10
+
+Current baseline: V1R4C3
+
+## Decision
+
+V1R4C4 will complete reliability freeze before merging Portal AIOS Integration.
+
+SR-04 remains `activation-ready`, but it must not be merged or deployed before SR-01 and SR-02 are complete and accepted.
+
+## Scope Ordering
+
+```text
+SR-01 Gitea Branch Sync Fix
+        ↓
+SR-02 Watcher State Cleanup
+        ↓
+SR-04 Portal AIOS Integration Merge
+```
+
+## SR-01 Gate
+
+SR-01 must complete the P0 reliability work for Gitea branch sync and metadata drift.
+
+Required outcomes:
+
+1. branch_sync remains independent of Gitea branch API pagination.
+2. bare repository refs, Gitea DB branch metadata, and Gitea API visible state are checked for consistency.
+3. branch metadata drift triggers autonomous safe mode.
+4. recovery procedure favors minimal repair over default restart.
+5. runtime acceptance passes.
+
+Acceptance sequence:
+
+```text
+getRuntimeStatus
+    ->
+getBaseline
+    ->
+createBranch
+    ->
+createPatch
+```
+
+## SR-02 Gate
+
+SR-02 must complete watcher state cleanup integration.
+
+Current known test signal:
+
+```text
+11 / 11 tests pass
+```
+
+Required outcomes:
+
+1. stuck command detection reads parsed timestamps correctly.
+2. `.json` command state files are handled correctly.
+3. `.md` command state files are handled correctly.
+4. file mtime semantics are aligned with stored stuck timestamps in tests.
+5. watcher cleanup is integrated behind the reliability assumptions introduced by SR-01.
+
+## SR-04 Status
+
+SR-04 remains:
+
+```text
+activation-ready
+```
+
+But SR-04 is explicitly blocked from merge/deploy until SR-01 and SR-02 gates are green.
+
+SR-04 may continue with planning, diff review, and acceptance design, but may not perform production portal deployment.
+
+## Reason
+
+The user-visible portal feature gap is real, but the system recently experienced a stop-the-line reliability incident involving Gitea branch metadata drift. Reliability freeze must complete first to avoid combining production portal changes with unresolved GitOps/Gitea consistency risk.
+
+## Allowed During Freeze
+
+Allowed:
+
+- SR-04 planning;
+- SR-04 diff review;
+- frontend/backend contract review;
+- RBAC acceptance design;
+- non-production validation;
+- documentation updates.
+
+Not allowed before SR-01/SR-02 acceptance:
+
+- merging SR-04 to main;
+- deploying SR-04 to production;
+- bypassing RBAC to expose modules;
+- combining portal integration with Gitea DB repair;
+- bulk merging old portal branches.
+
+## SR-04 Release Gate
+
+SR-04 may enter merge/deploy only after:
+
+1. SR-01 acceptance is green.
+2. SR-02 acceptance is green.
+3. GitOps runtime acceptance is green.
+4. Gitea consistency sentinel is deployed or explicitly deferred with owner approval.
+5. Portal RBAC acceptance plan is approved.
+
+## Final Rule
+
+V1R4C4 is reliability-first.
+
+Portal AIOS Integration remains prepared but gated until reliability freeze is complete.