decision: gate SR-04 behind V1R4C4 reliability freeze

2026-07-10 09:14:40 +08:00
4 changed files with 116 additions and 196 deletions
@@ -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.
@@ -1,155 +0,0 @@
-# V1R4C4 SR-01 Deployment Acceptance: Gitea Branch Consistency Sentinel
-
-Date: 2026-07-10
-
-Status: healthy
-
-Baseline at validation: V1R4C3
-
-Runtime status at record time: active
-
-## Acceptance Summary
-
-The Gitea branch consistency sentinel is deployed and operating successfully.
-
-Observed service result:
-
-```json
-{
-  "status": "healthy",
-  "unhealthy_checks": []
-}
-```
-
-No unhealthy checks were reported.
-
-## Implemented Components
-
-### 1. Sentinel script
-
-Path:
-
-```text
-/data/aios-gitops/workspace/scripts/reliability/gitea_branch_consistency_sentinel.py
-```
-
-Purpose:
-
- compare Gitea branch metadata against actual Git branch state;
- detect branch metadata drift;
- emit structured JSON result;
- optionally emit autonomous safe-mode state when unhealthy.
-
-The deployed check compares Gitea branch metadata available through the local Gitea endpoint against the actual git branches in the repository directory.
-
-Endpoint used:
-
-```text
-127.0.0.1:3000
-```
-
-### 2. Safe-mode helper
-
-Path:
-
-```text
-/data/aios-gitops/workspace/scripts/reliability/autonomous_safe_mode.py
-```
-
-Purpose:
-
- provide safe-mode output/formatting helper;
- support autonomous controller behavior when drift is detected.
-
-### 3. systemd timer
-
-Unit:
-
-```text
-gitea-branch-consistency-sentinel.timer
-```
-
-Schedule:
-
-```text
-every 5 minutes
-```
-
-Purpose:
-
- continuously monitor Gitea branch consistency;
- reduce mean time to detection for branch metadata drift;
- provide recurring health evidence.
-
-### 4. systemd service
-
-Unit:
-
-```text
-gitea-branch-consistency-sentinel.service
-```
-
-Execution:
-
-```text
-gitea_branch_consistency_sentinel.py --emit-safe-mode --json
-```
-
-Purpose:
-
- execute consistency sentinel;
- log structured JSON output;
- emit safe-mode state when the sentinel becomes unhealthy.
-
-### 5. Workspace symlink fix
-
-A broken `reliability` directory symlink pointing outside the workspace was replaced with actual files.
-
-Reason:
-
- systemd sandboxing prevents following the prior external symlink safely;
- deploying actual files inside the workspace makes service execution deterministic.
-
-## Reliability Impact
-
-This closes the core SR-01 monitoring gap:
-
-```text
-Gitea branch metadata drift
-        ↓
-detected within timer interval
-        ↓
-structured JSON health record
-        ↓
-autonomous safe-mode emission if unhealthy
-```
-
-The timer now provides continuous verification every 5 minutes.
-
-## Current Result
-
-```text
-status: healthy
-unhealthy_checks: none
-timer: active every 5 minutes
-service: emits JSON with --emit-safe-mode
-```
-
-## Acceptance Decision
-
-SR-01 deployment guardrail is accepted as healthy for V1R4C4 reliability freeze readiness.
-
-This does not yet promote V1R4C4. It provides one required acceptance input for V1R4C4.
-
-## Remaining Before V1R4C4 Promotion
-
-1. Confirm SR-02 watcher cleanup remains test-green after integration.
-2. Run GitOps runtime acceptance:
-
-```text
-getRuntimeStatus -> getBaseline -> createBranch -> createPatch
-```
-
-3. Confirm no new Gitea branch metadata drift after acceptance writes.
-4. Prepare V1R4C4 reliability baseline proposal.
-5. Keep SR-04 Portal AIOS Integration gated until SR-01 and SR-02 are both accepted.
@@ -1,17 +0,0 @@
-# Copy to /etc/aios/gitea-branch-consistency-sentinel.env
-# and adjust paths for the deployment host.
-
-AIOS_REPO_ROOT=/data/aios-gitops/workspace
-GITEA_REPO_DIR=/data/aios-gitops/runtime/gitea-bin/data/repositories/aios/aios.git
-GITEA_DB_PATH=/data/aios-gitops/runtime/gitea-bin/data/gitea.db
-GITEA_REPO_ID=1
-GITEA_API_URL=http://127.0.0.1:3000/api/v1/repos/aios/aios/branches
-
-GITEA_SENTINEL_REPORT_FILE=/data/aios-gitops/runtime/state/gitea-branch-consistency-report.json
-AUTONOMOUS_SAFE_MODE_FILE=/data/aios-gitops/runtime/state/autonomous-safe-mode.json
-
-GITEA_SENTINEL_TIMEOUT_SECONDS=10
-GITEA_DOCTOR_REQUIRED=false
-
-# Optional:
-# GITEA_API_TOKEN_FILE=/path/to/token
@@ -1,24 +0,0 @@
-[Unit]
-Description=Gitea branch metadata consistency sentinel
-Documentation=file:docs/reliability/gitea-controller-guardrails.md
-Wants=network-online.target
-After=network-online.target
-
-# Read-only consistency check. Emits safe mode on detected drift.
-
-[Service]
-Type=oneshot
-Environment="AIOS_REPO_ROOT=/data/aios-gitops/workspace"
-EnvironmentFile=-/etc/aios/gitea-branch-consistency-sentinel.env
-WorkingDirectory=/data/aios-gitops/workspace
-ExecStart=/bin/sh -lc 'cd "$AIOS_REPO_ROOT" && exec /usr/bin/python3 "$AIOS_REPO_ROOT/scripts/reliability/gitea_branch_consistency_sentinel.py" --emit-safe-mode --json'
-TimeoutStartSec=90
-Nice=10
-IOSchedulingClass=best-effort
-IOSchedulingPriority=7
-NoNewPrivileges=true
-PrivateTmp=true
-ProtectHome=true
-ProtectSystem=full
-ReadWritePaths=/data/aios-gitops/runtime/state
-ReadOnlyPaths=/data/aios-gitops/runtime/gitea-bin/data