krisolo/storyforge
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
cb17fb07603e0fd64ad49ef30d707b7a2bc73e87
storyforge/docs/superpowers/plans/2026-03-29-main-agent-governance-foundation.md
kris cb17fb0760 feat: add main agent governance foundation
2026-03-29 16:13:50 +08:00

8.8 KiB
Raw Blame History

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
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:

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:

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:

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:

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:

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:

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:

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

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 scripts/deploy_fnos_storyforge_lan_stack.sh
  • Step 3: Run fnOS smoke
bash scripts/smoke_fnos_storyforge_lan.sh
  • Step 4: Commit and push
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