feat: add main agent governance foundation

2026-03-29 16:13:50 +08:00
parent dff369aafd
commit cb17fb0760
7 changed files with 2574 additions and 7 deletions
--- a/docs/superpowers/plans/2026-03-29-main-agent-governance-foundation.md
+++ b/docs/superpowers/plans/2026-03-29-main-agent-governance-foundation.md
@@ -0,0 +1,284 @@
+# Main Agent Governance Foundation Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Build the first production-ready governance foundation for StoryForge main-agent policy layers, versioning, admin overrides, rollback, and minimal governance UI.
+
+**Architecture:** Add dedicated governance tables and endpoints inside `oneliner_features.py`, compute effective policy layers at runtime for OneLiner context, then expose a minimal read/write UI in the existing Agent page and Admin Workbench without redesigning the shell.
+
+**Tech Stack:** FastAPI, SQLite, existing StoryForge Web V4 vanilla JS, Node test runner, Python unittest
+
+---
+
+### Task 1: Spec + plan docs
+
+**Files:**
+- Create: `docs/superpowers/specs/2026-03-29-main-agent-governance-foundation-design.md`
+- Create: `docs/superpowers/plans/2026-03-29-main-agent-governance-foundation.md`
+
+- [ ] **Step 1: Save the approved design**
+
+Write the governance design into the spec file above.
+
+- [ ] **Step 2: Save this implementation plan**
+
+Write this plan file and keep it committed with the implementation.
+
+- [ ] **Step 3: Commit docs checkpoint**
+
+```bash
+git add docs/superpowers/specs/2026-03-29-main-agent-governance-foundation-design.md docs/superpowers/plans/2026-03-29-main-agent-governance-foundation.md
+git commit -m "docs: add main agent governance foundation spec"
+```
+
+### Task 2: Add failing backend governance tests
+
+**Files:**
+- Create: `tests/test_main_agent_governance.py`
+- Modify: `tests/test_production_baseline.py`
+
+- [ ] **Step 1: Write failing tests for scope creation and runtime layering**
+
+Add tests that verify:
+- system default policy can be written and read
+- user global policy overrides system default
+- user platform policy overrides user global for one platform
+- admin override wins over user layers
+- rollback creates a new version instead of mutating history
+
+- [ ] **Step 2: Run the failing test file**
+
+Run:
+
+```bash
+python3 -m unittest tests.test_main_agent_governance -v
+```
+
+Expected: failures because governance tables and endpoints do not exist yet.
+
+### Task 3: Add backend schema and payload helpers
+
+**Files:**
+- Modify: `collector-service/app/oneliner_features.py`
+
+- [ ] **Step 1: Add schema tables**
+
+Add table creation SQL for:
+- `agent_policy_scopes`
+- `agent_policy_versions`
+- `agent_policy_effectivity`
+- `agent_policy_audit_logs`
+
+- [ ] **Step 2: Add policy helper functions**
+
+Implement helpers for:
+- scope payload
+- version payload
+- audit payload
+- system scope ensure
+- current active version lookup
+- effective layer merge
+
+- [ ] **Step 3: Re-run failing governance tests**
+
+Run:
+
+```bash
+python3 -m unittest tests.test_main_agent_governance -v
+```
+
+Expected: some tests still fail because endpoints are missing, but schema-related failures should move forward.
+
+### Task 4: Add governance write/read endpoints
+
+**Files:**
+- Modify: `collector-service/app/oneliner_features.py`
+
+- [ ] **Step 1: Add user-side endpoints**
+
+Implement:
+- `GET /v2/oneliner/governance/effective`
+- `GET /v2/oneliner/governance/user/global`
+- `PUT /v2/oneliner/governance/user/global`
+- `GET /v2/oneliner/governance/user/global/versions`
+- `POST /v2/oneliner/governance/user/global/rollback`
+- `GET /v2/oneliner/governance/user/platforms/{platform}`
+- `PUT /v2/oneliner/governance/user/platforms/{platform}`
+- `GET /v2/oneliner/governance/user/platforms/{platform}/versions`
+- `POST /v2/oneliner/governance/user/platforms/{platform}/rollback`
+
+- [ ] **Step 2: Add admin-side endpoints**
+
+Implement:
+- `GET /v2/admin/oneliner/governance/system/main-agent`
+- `PUT /v2/admin/oneliner/governance/system/main-agent`
+- `GET /v2/admin/oneliner/governance/system/main-agent/versions`
+- `POST /v2/admin/oneliner/governance/system/main-agent/rollback`
+- `GET /v2/admin/oneliner/governance/system/platforms/{platform}`
+- `PUT /v2/admin/oneliner/governance/system/platforms/{platform}`
+- `GET /v2/admin/oneliner/governance/system/platforms/{platform}/versions`
+- `POST /v2/admin/oneliner/governance/system/platforms/{platform}/rollback`
+- `GET /v2/admin/oneliner/governance/overrides`
+- `POST /v2/admin/oneliner/governance/overrides`
+- `GET /v2/admin/oneliner/governance/overrides/versions`
+- `POST /v2/admin/oneliner/governance/overrides/rollback`
+
+- [ ] **Step 3: Add audit logging inside every governance mutation**
+
+Record actor, target, scope, version, reason, and rollback source where relevant.
+
+- [ ] **Step 4: Run governance backend tests**
+
+Run:
+
+```bash
+python3 -m unittest tests.test_main_agent_governance -v
+```
+
+Expected: backend governance tests pass.
+
+### Task 5: Connect runtime layering into OneLiner context
+
+**Files:**
+- Modify: `collector-service/app/oneliner_features.py`
+- Test: `tests/test_main_agent_governance.py`
+
+- [ ] **Step 1: Inject runtime policy into session context**
+
+Extend the OneLiner context builder so the runtime payload includes:
+- effective merged policy
+- ordered policy layers
+- active admin override notice
+
+- [ ] **Step 2: Make OneLiner reply builder surface active governance context**
+
+Use the runtime policy payload to explain active strategy layers in the result payload, without rewriting all prompt logic.
+
+- [ ] **Step 3: Add tests for runtime payload**
+
+Verify the runtime endpoint and OneLiner context expose the merged policy stack.
+
+- [ ] **Step 4: Run backend tests**
+
+Run:
+
+```bash
+python3 -m unittest tests.test_main_agent_governance tests.test_production_baseline -v
+```
+
+Expected: pass.
+
+### Task 6: Add minimal governance UI loading and rendering
+
+**Files:**
+- Modify: `web/storyforge-web-v4/assets/app.js`
+- Modify: `web/storyforge-web-v4/tests/workbench-pages.test.mjs`
+
+- [ ] **Step 1: Write failing frontend tests**
+
+Add assertions that:
+- Agent workspace references effective policy summary
+- Admin Workbench Agent governance tab references system policy, user overrides, and audit history
+
+- [ ] **Step 2: Run frontend tests and verify failure**
+
+Run:
+
+```bash
+node --test web/storyforge-web-v4/tests/workbench-pages.test.mjs
+```
+
+Expected: fail on missing governance UI text and loaders.
+
+- [ ] **Step 3: Load governance payloads in app state**
+
+Add app state fields and data loading for:
+- current runtime policy
+- current user version history
+- admin governance overview
+
+- [ ] **Step 4: Render minimal governance panels**
+
+Render:
+- user-side policy summary + version list in `Agent -> 当前 Agent 工作台`
+- admin-side system default, user override, audit summary in `管理员配置台 -> Agent 治理`
+
+- [ ] **Step 5: Re-run frontend tests**
+
+Run:
+
+```bash
+node --test web/storyforge-web-v4/tests/workbench-pages.test.mjs
+node --check web/storyforge-web-v4/assets/app.js
+```
+
+Expected: pass.
+
+### Task 7: Add minimal edit flows for first batch
+
+**Files:**
+- Modify: `web/storyforge-web-v4/assets/app.js`
+- Modify: `web/storyforge-web-v4/tests/workbench-pages.test.mjs`
+
+- [ ] **Step 1: Add user edit entrypoints**
+
+Provide modal actions for:
+- update user global strategy
+- update current platform strategy
+
+- [ ] **Step 2: Add admin edit entrypoints**
+
+Provide modal actions for:
+- update system default main-agent strategy
+- update system default platform strategy
+- update admin override strategy for selected user/platform
+- rollback selected scope version
+
+- [ ] **Step 3: Keep first batch UI intentionally small**
+
+Do not build a full-blown designer. Use the existing modal patterns with JSON textarea + summary/reason fields if needed.
+
+- [ ] **Step 4: Re-run frontend tests**
+
+Run:
+
+```bash
+node --test web/storyforge-web-v4/tests/workbench-pages.test.mjs
+```
+
+Expected: pass.
+
+### Task 8: Full verification, deploy, and publish
+
+**Files:**
+- Modify as needed from previous tasks only
+
+- [ ] **Step 1: Run full repo checks**
+
+```bash
+python3 -m unittest tests.test_platform_contracts tests.test_production_baseline tests.test_main_agent_governance -v
+node --test web/storyforge-web-v4/tests/dashboard-home.test.mjs web/storyforge-web-v4/tests/workbench-pages.test.mjs
+node --check web/storyforge-web-v4/assets/app.js
+python3 -m compileall collector-service/app tests
+git diff --check
+```
+
+- [ ] **Step 2: Deploy to fnOS**
+
+```bash
+bash scripts/deploy_fnos_storyforge_lan_stack.sh
+```
+
+- [ ] **Step 3: Run fnOS smoke**
+
+```bash
+bash scripts/smoke_fnos_storyforge_lan.sh
+```
+
+- [ ] **Step 4: Commit and push**
+
+```bash
+git add collector-service/app/oneliner_features.py web/storyforge-web-v4/assets/app.js tests/test_main_agent_governance.py tests/test_production_baseline.py web/storyforge-web-v4/tests/workbench-pages.test.mjs docs/superpowers/specs/2026-03-29-main-agent-governance-foundation-design.md docs/superpowers/plans/2026-03-29-main-agent-governance-foundation.md
+git commit -m "feat: add main agent governance foundation"
+git push gitea codex/storyforge-live-orchestrator-sync-20260323
+```