Critical Flows and Onboarding Paths (Implemented State)

Purpose

Capture current implemented behavior across API, workers, and dashboard onboarding so rollout docs stay in sync with the codebase.

Product Surfaces (Implemented)

• API + MCP Worker: decision lifecycle, policy checks, MCP tools/transport, org/admin controls, auth/session flows.
• Gatekeeper Worker: GitHub webhook ingress, signature verification, idempotency, queue handoff, queued check-run.
• Jobs Worker: async policy evaluation, ADR ingestion, metering rollups, digest dispatch, audit cleanup.
• Dashboard Web: onboarding path selector, token/session setup, Decisions, PR Checks, Drift Trends, settings/integration controls.

Actors

• Architect/Approver: curates decisions and policy posture.
• Contributor/Developer: links decisions to PRs, requests overrides, uses checks feedback.
• Agent: calls MCP tools for context/conflicts/drafts/linking.
• Platform Admin: configures integrations, policy mode, tokens, and promotion cadence.

Core Data Objects

• Decision: proposed | accepted | deprecated | superseded, origin human | agent.
• PolicyRun: pass | warn | fail with score, repo, actor, and timestamps.
• Override: PR-level exception with reason + actor.
• RepoPolicy: per-repo advisory | soft_block | hard_block with threshold/path settings.
• UsageMeteringDaily: checks, MCP calls, token usage, and rate metrics.

Critical Flows (Current)

1) Decision lifecycle

1. Create decision via POST /v1/decisions.
2. Update decision fields via PATCH /v1/decisions/:id (including status when provided).
3. Promote via POST /v1/decisions/:id/approve (allowed transitions only).
4. Supersede via POST /v1/decisions/:id/supersede (allowed transitions only).
5. Record audit events for create/update/approve/supersede.

2) MCP agent workflow

1. Discover tools via GET /v1/mcp/tools or use stream transport via ALL /mcp.
2. Resolve context with decisions.resolve_for_diff.
3. Evaluate conflicts with decisions.check_conflicts.
4. Draft/link with decisions.create_draft and decisions.link_pr.
5. Emit MCP usage into audit + metering.

3) GitHub PR gatekeeper

1. Receive POST /webhooks/github.
2. Verify signature and deduplicate by delivery id.
3. Fetch PR diff/files with installation token (when available) and enqueue policy job.
4. Jobs worker evaluates conflict + coverage and writes policy_runs/findings.
5. Publish final DecisionRecord Policy Check check-run summary.
6. Respect mode semantics: advisory non-blocking, soft/hard block enforce thresholds.

4) Override handling

1. Create override with POST /v1/pr/override.
2. Resolve latest override with GET /v1/pr/override?repoId=<owner/repo>&prNumber=<n>.
3. Jobs pipeline forces success conclusion when valid override exists.
4. Persist audit + metering signals.

5) ADR ingestion

1. Submit markdown payload to POST /internal/ingest.
2. Parse frontmatter/body into title/status/scope/constraints.
3. Insert or update decision record + append decision_versions.
4. Make ingested decisions available to MCP and policy checks.

6) Observability + burn-in

1. Scheduled jobs roll up daily usage and process digest subscriptions.
2. Dashboard reads:
   • /v1/metrics/overview
   • /v1/metrics/drift
   • /v1/admin/burn-in
3. Burn-in report computes advisory failure/override rates and suggested policy mode.
4. Admin can promote mode through POST /v1/admin/policies/:repoId/promote.

Onboarding Paths In Product (/onboarding)

Implemented path selector

• Dashboard First
• GitHub First
• Agent / MCP First
• ADR Import First
• API First

Implemented onboarding helpers

• Token connect panel with validation against /v1/admin/policies.
• Readiness checklist from GET /v1/admin/setup-status.
• One-click launcher command copy for selected path.
• Path-specific quick actions:
  • Run Policy Check for dashboard/github/api-first paths.
  • Generate Hooks for MCP-first path (GET /v1/agent-hooks/:repoId).
• Deep links into Decisions, PR Checks, Drift, Login, and Settings.

Current Gaps

• ADR import remains API-driven (/internal/ingest); no in-dashboard bulk file upload UI yet.
• Onboarding Run Policy Check validates policy evaluation API, not full webhook-to-check-run loop.
• GitHub webhook health and queue lag are not exposed as first-class onboarding readiness checks.

Suggested Rollout Metrics

• Time to first accepted decision.
• Time to first policy run and first burn-in report.
• Time to first MCP call.
• Share of repos promoted from advisory after burn-in.
• Onboarding path distribution and completion rate.

Next Candidates

1. Add explicit webhook/queue health checks into /v1/admin/setup-status.
2. Add guided ADR import workflow (multi-file upload + parser feedback).
3. Add first-run capture of selected onboarding path and completion milestones.