M-002 Phase 2A Report — DSL + Governance Foundation

Date: 2026-03-03 Agent: codex Repos: web-test, agent-data-test PRs: #424 (foundation), #425 (workflow API proxy hotfix)

Scope

• Built Phase 2A foundation only: DSL as SSOT, block library, WCR governance, migration, and viewer integration.
• Explicitly excluded Phase 2B overlays/color/zoom and Phase 3 execution.
• Kept Phase 1 Viewer/Modeler/Annotations working.

Schema + DOT

• Created 4 Directus collections with DOT: workflow_steps, workflow_step_relations, block_library, workflow_change_requests.
• Added Directus relations for workflows, blocks, and task linkage.
• Granted AI-agent permissions: RW for steps/relations, RO for block library, restricted RW for WCR fields.
• Seeded 5 blocks: planning_council, ai_review_block, code_review_loop, approval_with_retry, agent_dispatch_block.
• Extended OPS Proxy + OpenAPI to expose the 4 new collections for Codex/GPT.

DSL Engine + Governance

• Added deterministic server-side DSL→BPMN generator and BPMN→DSL migration/parser utilities.
• Added WCR intake, integrity scan, apply pipeline, and status update endpoints.
• Added integrity checks for duplicate step_key, orphan steps, missing condition branches, and loop exit coverage.
• Wired WCR lifecycle comments into task governance flow.
• Updated WorkflowViewer to render from DSL-backed diagram API instead of reading workflows.bpmn_xml directly.
• Updated WorkflowModeler to block direct BPMN saves when DSL exists.

Migration + Functional Tests

• Migrated workflow #1 from BPMN XML into DSL records.
• Fixed BPMN generator tag casing bug so migration comparison became structurally equivalent.
• WCR #1 (add_step) applied successfully: workflow version 3, 6 steps, 5 relations.
• WCR #2 (add_block with ai_review_block) applied successfully: workflow version 4, 10 steps, 10 relations.
• WCR #3 orphan test produced the expected orphan_step schema warning.
• Governance comments were created on task #10 for planning and verify tabs.

Build + CI Verification

• Local validation passed: pnpm typecheck, targeted ESLint, pnpm build.
• main after PR #424 and PR #425 completed green on Nuxt 3 CI, Terraform Deploy, Firebase Deploy, Deploy to VPS, and E2E Tests.
• VPS verification scripts passed:
  • test-agent-connections.sh: 37/37 PASS
  • test-all-connections.sh: 20/20 PASS

Production Evidence

Before

• Before PR #425, GET /api/workflows/1/diagram returned 404 because nginx still routed /api/workflows/* to Agent Data.
• After the proxy hotfix deployed, the endpoint resolved but returned source="bpmn_cache" and dslAvailable=false.
• Root cause of the second issue: running incomex-nuxt container on VPS did not have NUXT_DIRECTUS_SERVICE_TOKEN, even though the committed compose config rendered that variable.

After

• Recreated the nuxt service from the committed compose config on VPS.
• Verified the running container now includes NUXT_DIRECTUS_SERVICE_TOKEN.
• Verified production endpoint result:
  • workflow #1
  • source="dsl"
  • dslAvailable=true
  • stepCount=10
  • relationCount=10
• Confirmed https://ai.incomexsaigoncorp.vn/knowledge/modules/10 is now backed by DSL-generated BPMN.

Tech Debt Recorded

• TD-058: workflow_steps.step_key uniqueness is enforced in governance/apply logic, but not yet at DB composite-constraint level.
• TD-059: Deploy pipeline can report success while the running nuxt container still has env drift from compose, which caused production DSL fallback until manual recreate.

Mission Outcome

• Phase 2A foundation is live.
• DSL and governance shipped together, with WCR gate preserved.
• Workflow #1 is migrated and rendering from DSL in production.
• No Phase 2B or Phase 3 scope was included.