PMFlow/docs/architecture/API_CONTRACTS.md

API CONTRACTS

PMFlow OS

POST /pmflow-os/projects/{project_id}/execution-progress-events

• Purpose: record Codex / IDE / Local Bridge / GitHub agent execution results after an execution handoff has been consumed.
• Auth: project member, OWNER, or REVIEWER; tenant comes from JWT.
• Request body:
  • task_id: string required; must belong to the current project.
  • event_type: "branch_created" | "commit" | "pr_opened" | "pr_synced" | "test_passed" | "test_failed" | "checks_passed" | "failed" | "blocked" | "merged" | "accepted" | "manual_progress".
  • source?: "pmflow_os" | "local_bridge" | "codex" | "github_agent" | "manual".
  • repo_binding_id?: string | null.
  • branch_name?: string | null, commit_sha?: string | null, pr_number?: number | null.
  • test_summary?: string | null, blocker_summary?: string | null.
  • execution_status?: "queued" | "pushed" | "coding" | "pr_open" | "testing" | "synced" | "failed".
  • workflow_state?: string | null, summary?: string | null, event_source_id?: string | null, occurred_at?: string | null.
• Behavior:
  • Creates a ProgressEvent only; it does not run commands, push branches, create PRs, publish releases, or create formal tasks.
  • Stores a backward-compatible flat payload plus protocol_version: "execution_result_protocol_v1" and execution_result envelope with {eventType, source, status, branchName, commitSha, prNumber, testSummary, blockerSummary, repositoryFullName}.
  • Returns the latest ExecutionSummaryProjection, allowing execution, releaseGate, and Team Feed projection to consume the same standardized result metadata.
  • failed / blocked / test_failed events fail-closed into releaseGate.status="blocked"; test_passed / checks_passed can move the gate to ready or needs_confirmation depending on PR/sync evidence.
• Failure semantics:
  • 404 task_not_found
  • 422 repo_binding_not_found

POST /pmflow-os/projects/{project_id}/extractions

• Purpose: turn a project thread message into an open ChangeSet with pending_review ChangeItems.
• Auth: project member, OWNER, or REVIEWER; tenant comes from JWT.
• Request body:
  • thread_id: string
  • message_id: string
  • scope?: string, default latest_message
  • summary?: string, headline?: string
  • routing_meta?: object, audit/routing metadata only
  • llm_call_id?: string
  • proposed_items?: PMFlowProposedChangeItem[]
• Behavior:
  • If proposed_items is present and non-empty, the endpoint preserves the existing explicit ChangeSet draft path.
  • If proposed_items is omitted or empty, the backend runs real structured AI extraction through llm_service.generate_structured_object using the dedicated change_review protected scene, pmflow_change_review_extraction_v1 Function Runtime Profile, and PROMPT_PMFLOW_CHANGE_REVIEW_EXTRACTION prompt asset, then normalizes requirements/tasks/risks/decisions into ChangeItems.
  • Success creates one pmflow_change_sets row with status=open, pending_review pmflow_change_items, and a pmflow_evidence_links row pointing to the source thread message.
  • Failure is fail-closed: no ChangeSet or ChangeItem is created. The API returns product-semantic errors such as ai_extraction_failed or extraction_evidence_insufficient.
  • This endpoint never commits Project Memory. ChangeReview remains responsible for accept/edit/defer and ChangeSet commit.
• Response data: PMFlowChangeSetDetailResponse
  • changeSet: serialized open ChangeSet with routingMeta.aiExtraction when AI extraction was used.
  • items[]: pending_review ChangeItems.
  • evidence[]: source thread message evidence.
  • approvals[]: initially empty unless later review actions were recorded.
• Failure semantics:
  • 404 message_not_found
  • 409 extraction_evidence_insufficient
  • 502 ai_extraction_failed

POST /pmflow-os/change-sets/{change_set_id}/commit

• Purpose: commit reviewed ChangeSet items into the official project truth layer.
• Auth: project member, OWNER, or REVIEWER; tenant comes from JWT.
• Request body:
  • item_ids?: string[] optional; default commits all accepted / edited items.
  • mode: "atomic" required for C2 V1.
  • note?: string audit note only.
• Behavior:
  • Processes only accepted / edited ChangeItems.
  • C2 V1 is atomic: any eligible item write failure rolls back the whole commit.
  • Required C2 objectType support: Requirement / Decision / Task / Risk.
  • Optional C2 objectType support: Release.
  • Unsupported for C2 V1: ModelDecision / MetricSignal, which must fail with 422 unsupported_object_type.
  • Requirement / Decision / Risk / Release write to truth_nodes.
  • Task writes truth_nodes(node_type='task') plus tasks.truth_node_id.
  • High-risk items require item-level approval with decision in ('approved','edited') and after_status in ('accepted','edited').
• Response data:
  • changeSet: { id, status, rawStatus, committedAt, writebackAt, committedById, committedBy, committedItemIds, skippedItemIds, failedItemIds }
  • committedItems[]: { changeItemId, objectType, targetType, targetId, status, evidenceIds, semanticFactStatus, committedAt, committedById, committedBy }
  • skippedItems[]: { changeItemId, objectType, status, reason }
  • failedItems[]: { changeItemId, objectType, code, message }
  • projectTruthState?: optional backend projection after commit.
• Failure semantics:
  • 404 changeset_not_found
  • 409 changeset_not_reviewed
  • 409 changeset_already_committed
  • 409 no_accepted_items
  • 409 high_risk_approval_required
  • 422 invalid_commit_item_ids
  • 422 unsupported_object_type
  • 422 invalid_change_payload
  • 500 commit_failed

Personal Space

Saved Ideas

• Purpose: keep pre-project idea seeds visible in /space without polluting Project Memory or PMFlow OS truth objects.
• Boundary:
  • saved_ideas stores raw input, source, summary, readiness, missing questions, status, enrichment metadata, and optional Project Launch draft linkage.
  • Enrichment metadata is explicit: enrichment_status="ai_enriched" means the AI structured completeness pass succeeded; ai_failed means AI did not complete and the row is showing deterministic baseline fields; baseline means no AI enrichment is present.
  • Saving an idea never creates a project, task, ChangeSet, Project Memory entry, execution event, release signal, or capacity item.
  • Promoting an idea only generates a Project Launch draft and returns the user to human review. Project creation still requires POST /pmflow-launch/drafts/{draft_id}/confirm.

GET /space/saved-ideas

• Auth: logged-in user; tenant comes from JWT.
• Query:
  • limit?: number, default 20, max 100
  • include_archived?: boolean, default false
• Response data: { items: SavedIdeaRead[] }. SavedIdeaRead includes id/title/raw_text/summary/source_type/source_ref/input_mode/attachments/status/status_label/ai_summary/missing_questions/readiness_score/enrichment_status/enrichment_payload/enrichment_error/enriched_at/launch_draft_id/promoted_project_id/created_at/updated_at/href.

POST /space/saved-ideas

• Auth: logged-in user; tenant comes from JWT.
• Request body:
  • raw_text: string
  • title?: string
  • summary?: string
  • source_type?: "project_launch" | "ai_concierge" | "logout_guard" | "feishu" | "upload" | "manual"
  • source_ref?: string
  • input_mode?: "idea" | "import" | "template"
  • attachments?: SavedIdeaAttachment[]
• Behavior: writes one saved_ideas row for the current user and workspace. The service first tries space_saved_idea_enrichment_v1 structured AI enrichment for summary / target_user / problem / value_hypothesis / validation_signal / constraints / missing_questions / readiness_score / status / confidence; if AI is unavailable or parsing fails, it stores enrichment_status="ai_failed" with a deterministic system_baseline payload instead of pretending AI succeeded.
• Response data: SavedIdeaRead.

PATCH /space/saved-ideas/{idea_id}

• Purpose: update title/raw text/summary/status for the current user's own idea. When raw_text changes, the same structured enrichment attempt runs again and refreshes readiness, missing questions, status and enrichment metadata.
• Response data: SavedIdeaRead.

POST /space/saved-ideas/{idea_id}/archive

• Purpose: remove a saved idea from active Space lists while preserving audit/history.
• Response data: SavedIdeaRead with status="archived".

POST /space/saved-ideas/{idea_id}/promote

• Purpose: convert a saved idea into a reviewable Project Launch draft.
• Behavior:
  • Calls the same structured draft generation path as POST /pmflow-launch/drafts.
  • Updates saved_ideas.status="promoted" and stores launch_draft_id.
  • Does not confirm the draft or create a project.
• Response data: { idea: SavedIdeaRead, draft: PMFlowLaunchDraftResponse, redirect_url: "/project-launch?state=human_review" }.
• POST /pmflow-launch/drafts rejects low-information launch input before calling the LLM with 422 and message prefix input_needs_more_info, so pure greetings or inputs without enough product/user/problem evidence stay in the supplement-input path instead of producing an empty draft.
• Project Launch taskized generation:
  • POST /pmflow-launch/draft-jobs creates a pmflow_launch_draft_jobs row with job_id / revision_id / status=queued, supersedes active jobs for the same user, and starts the structured generation worker. Response returns job status only; clients must poll.
  • GET /pmflow-launch/draft-jobs/{job_id} returns queued | running | superseded | completed | failed | cancelled; completed includes the generated PMFlowLaunchDraftResponse and changed_fields.
  • POST /pmflow-launch/draft-jobs/{job_id}/cancel marks a queued/running job as cancelled. If the provider call already completed, workers must ignore non-running jobs before persisting a draft.
  • POST /pmflow-launch/drafts/{draft_id}/revise creates a new merge_supplement job using the parent draft plus the user's supplement; it does not confirm or write a project.
• Project Launch draft generation uses the managed PROMPT_PMFLOW_LAUNCH_DRAFT active release when available. The expected structured draft is a monetizable MVP launch plan, targeting 7-10 requirements, 10-16 tasks, 4-7 risks and 3-6 decisions; count or business-loop gaps are surfaced in draft warnings instead of silently accepting a thin feature-demo plan.

AI Readiness

GET /ai-readiness/project-launch

• Purpose: derive the customer-facing Project Launch AI readiness state from backend runtime facts, not from frontend local state.
• Auth: logged-in user; tenant comes from JWT.
• Behavior:
  • Reads platform runtime configuration from the platform runtime tenant, including integrations(type='llm_engine') and published integrations(type='ai_capability_slots').active.slots.
  • Verifies the Project Launch scene contract, the published structured slot, the bound runtime connection state, structured output / JSON Schema capability evidence, and the latest tenant-scoped ai_call_logs(function_name='pmflow_launch_draft_v1').
  • Returns customer-safe copy and actions by default. Supplier, slot, probe, recent call, raw status and platform repair actions are exposed only inside platform / platform_diagnostic for platform operations views.
  • can_generate_project_draft=true only when the required runtime, structured slot, capability evidence and latest draft smoke/call evidence are all healthy. Missing active structured slot, unavailable runtime or missing capability proof keeps Project Launch draft generation blocked.
• Response data: AIReadiness
  • scene: "project_launch"
  • status: "ready" | "blocked" | "recovering" | "unknown"
  • customer_state, title, summary, short_label, updated_at_label
  • can_generate_project_draft: boolean
  • blockers[], customer_actions[], workspace_owner_actions[]
  • platform.checks, platform.blockers, platform.latest_call, platform.last_checked_at
  • platform_diagnostic

POST /ai-readiness/project-launch/check

• Purpose: run a protected Project Launch smoke check without creating a draft or project.
• Auth: platform AI operations capability, via platform.ai_routing.manage.
• Behavior:
  • Calls the same pmflow_launch_draft_v1 structured generation path used by real Project Launch, with routing_meta.tier_alias="structured" and source="system_smoke".
  • Normalizes and validates the generated draft payload, but does not write pmflow_launch_drafts, projects, Project Memory, tasks, ChangeSet or semantic facts.
  • Updates the returned readiness payload from the fresh smoke result and latest ai_call_logs evidence.
• Response data: same as GET /ai-readiness/project-launch, with platform.last_smoke_error when the smoke check fails.

Platform AI Operations

Provider code boundary

• Runtime provider identity must come from configured integrations(type='llm_engine').config.engines[*].provider; UI, API, audit and routing code may display product labels, but must preserve the raw configured provider code separately.
• DashScope/Qwen runtime provider code is dashscope. The old internal provider code glm has been removed and must not be reintroduced as an alias, fallback, display value or audit value. glm-5 may still appear only as a model name when a configured provider points to that model.
• Historical integrations.config and ai_call_logs rows are migrated by backend/alembic/versions/20260429_rename_glm_provider_to_dashscope.py; new writes must persist dashscope for DashScope/Qwen suppliers and keep provider_label / runtime_label / engine_name as display-only fields.

Prompt operations center

• Scope: /prompt-assets* is platform-only and requires platform.ai_routing.manage. It is not a customer workspace Prompt strategy surface and must not be exposed in Space, Project Launch or project-level AI copilot.
• Main read endpoints:
  • GET /prompt-assets
  • GET /prompt-assets/{prompt_key}
  • GET /prompt-assets/{prompt_key}/quality-summary
  • GET /prompt-assets/{prompt_key}/golden-cases
  • GET /prompt-assets/{prompt_key}/releases/{release_id}/checks
  • GET /prompt-assets/{prompt_key}/releases/{release_id}/replay-runs
  • GET /prompt-assets/{prompt_key}/replay-runs/{run_id}
  • GET /prompt-assets/{prompt_key}/releases/{release_id}/watch-summary
• Main write endpoints:
  • POST /prompt-assets/{prompt_key}/releases
  • POST /prompt-assets/{prompt_key}/releases/{release_id}/activate
  • POST /prompt-assets/{prompt_key}/releases/{release_id}/rollback
  • POST /prompt-assets/{prompt_key}/releases/{release_id}/checks/run
  • POST /prompt-assets/{prompt_key}/golden-cases
  • POST /prompt-assets/{prompt_key}/golden-cases/from-call/{ai_call_log_id}
  • POST /prompt-assets/{prompt_key}/releases/{release_id}/replay-runs
• Golden case request supports case_type, priority, scenario_key and tags. priority=blocking failures block guarded release activation; important/observation failures are warning-only and require human review.
• Replay request supports mode=contract_smoke|compare|llm_compare, include_llm, judge_enabled, case_status and max_cases. include_llm=true forces llm_compare and caps max cases. LLM replay must call llm_service with explicit routing_meta (prompt_key, prompt_release_id, prompt_source, tier_alias, scene_key, run_id) and must not hardcode provider/model.
• Replay case results persist deterministic contract status plus optional baseline_ai_call_log_id, candidate_ai_call_log_id, judge_score, judge_label, judge_reason, risk_flags_json, latency and cost estimate. Judge rubric comes from backend/app/config/ai_prompt_eval_rubrics.py.
• Release watch summary returns 24h/7d quality windows, structured_invalid_24h, fallback_rate_24h, recent failures and recommendation=healthy|watch|needs_review|rollback_suggested. It is advisory only and must not auto-rollback.
• inline_discovered and needs_migration assets are read-only inventory until their runtime call sites are migrated to PromptRuntimeService / PromptReleaseService; UI and API copy must not imply these prompts are already configurable in production runtime.

Signal & SSTC

All /projects/{project_id}/... SSTC and model-capability context read endpoints must enforce project visibility before returning business data: project member, OWNER, or REVIEWER. This includes overview, stages, risks, governance, chain, charters, signals, tasks, releases, reviews, truth nodes, and experiments.

Workspace / Membership

Product language uses workspace/space; the compatibility table name remains tenants.

POST /auth/phone/send-code

• Purpose: send an SMS-style verification code for phone login, self-registration, or invitation binding.
• Request body:
  • phone_country_code: string, default +86
  • phone_number: string
  • purpose?: "login" | "bind_invitation" | "reset"
  • invite_token?: string
• Behavior:
  • Phone is normalized to global users.phone_e164; duplicate accounts for the same verified phone are not allowed.
  • Development environments may return dev_code to keep local verification testable. Production must not expose the code to users.

POST /auth/phone/verify

• Purpose: verify the phone code, log in the account, and create the account if it does not exist.
• Request body:
  • phone_country_code: string, default +86
  • phone_number: string
  • code: string
  • purpose?: "login" | "bind_invitation" | "reset"
  • name?: string
  • invite_token?: string
• Behavior:
  • If the phone has no existing account, the backend creates a global user account plus a personal workspace.
  • If invite_token is present and bound to the same verified phone, the backend accepts the team invitation and switches the active workspace to that team.
  • Existing users keep their personal workspace; joining or leaving a team never transfers ownership of the account itself.
• Response data: regular login payload with access_token, token_type, user.workspace_context, and user.platform_context.
  • workspace_context describes the customer's active personal/team workspace membership.
  • platform_context is PMFlow-internal access only: { has_platform_access, roles, capabilities }. A customer workspace OWNER does not imply any platform capability.

POST /auth/register

• Purpose: create a global account plus that user's personal workspace.
• Behavior: compatibility username/password registration path. The preferred user-facing path is phone verification via /auth/phone/verify. The new user becomes OWNER of the personal workspace; this workspace is not removed when the user later leaves team workspaces.

Platform membership

• Table/model: platform_memberships.
• Purpose: grant PMFlow-internal operators access to the platform AI operations control plane.
• Roles: PLATFORM_OWNER, PLATFORM_ADMIN, AI_OPS, SUPPORT, BILLING_OPS, SECURITY_AUDITOR.
• Shape: one user may hold multiple platform roles; uniqueness is user_id + role, and platform_context.capabilities is the union of active roles.
• Boundary: platform roles are not workspace roles. They never come from tenant_memberships.role or legacy users.role.
• Bootstrap: PMFLOW_PLATFORM_ADMIN_USERS and PMFLOW_AI_OPS_USERS may grant temporary env-based platform access before DB grants exist.

GET /workspaces/me

• Purpose: list all active workspaces for the current account.
• Response data: { active_workspace, workspaces[] }; each workspace includes workspace_type (personal or team) and membership role.

POST /workspaces/teams

• Purpose: create a small-team workspace from a solo account.
• Behavior: current user becomes OWNER and the new team workspace becomes active.

POST /workspaces/invitations

• Purpose: invite a member by phone into the current team workspace.
• Auth: active workspace role must be OWNER or REVIEWER; only OWNER may invite REVIEWER.
• Request body:
  • phone_country_code: string, default +86
  • phone_number: string
  • role: "OWNER" | "BUILDER" | "OPERATOR" | "REVIEWER"
  • email?: string, optional compatibility/contact field
  • project_ids?: number[]
• Behavior: invite may include initial project_ids to create project membership after acceptance. Re-inviting the same pending tenant_id + phone_e164 refreshes the token and role instead of creating duplicate pending invitations.

POST /workspaces/invitations/accept

• Purpose: accept a team invitation.
• Behavior: legacy token acceptance remains supported. Phone-bound invitations require the accepting account's verified phone to match the invitation phone. Existing users keep their personal workspace; new users created from an invitation also receive a personal workspace before joining the team.

POST /workspaces/{tenant_id}/leave

• Purpose: leave a team workspace.
• Boundary: personal workspaces cannot be left; the last OWNER of a team must transfer ownership before leaving.

GET /projects/

• Purpose: list project rows or summary rows for project index and personal Space aggregation.
• Auth: logged-in user; tenant comes from JWT.
• Query:
  • summary?: 0 | 1
  • status?: string
  • assigned_role?: string
• Visibility:
  • OWNER and REVIEWER receive all non-filtered projects in the current tenant.
  • Other roles only receive projects they own (projects.owner_id) or projects linked through user_projects.
  • The same visibility rule applies to GET /projects/{project_id}; inaccessible projects return 404 rather than leaking existence.
• Response data:
  • summary=1: { projects: ProjectSummary[] }
  • otherwise: Project[]

POST /projects/

• Purpose: create a project shell/title and membership record. This endpoint does not generate requirements, tasks, risks, or Project Memory.
• Auth: OWNER or REVIEWER; tenant comes from the active workspace membership.
• Request body:
  • title: string
  • description?: string
  • status?: string, default active
  • domain_id?: number
  • assigned_role?: string
  • member_user_ids?: number[]
• Behavior:
  • Project titles are compacted and must be unique per tenant_id across non-inactive projects.
  • A duplicate title returns 409 project title already exists.
  • The endpoint never calls AI and never writes truth_nodes, tasks, ChangeSets, or semantic facts.
• Response data: serialized project row { id, title, description, status, domain_id, assigned_role, signal_count, created_at, updated_at }

GET /ai-pmo/work-items

• Purpose: compatibility read model for Space legacy manual gates and draft confirmations.
• Auth: logged-in user; tenant comes from JWT.
• Visibility:
  • OWNER and REVIEWER may inspect tenant-level legacy work items.
  • Other roles only receive work items owned by themselves (work_items.owner_user_id) or bound to a project they can access through user_projects.
  • Unbound legacy work items without owner_user_id are hidden from non-manager users.
• Boundary: this endpoint is not a team inbox product surface; Space consumes it only as a compatibility adapter.

GET /projects/{project_id}/signals

• Response data:
  • items[] includes planner fields:
    • planner_status: "pending" | "completed" | "failed"
    • planner_analyzed_at: string | null
    • planner_assignee_user_id: string | null
    • strategic_analysis: object

Model Routing

GET /model-routing/functions/{function_name}

• Purpose: query function-level routing diagnostics for hidden Route Lab. This is not shown in member, team-lead, or regular AI Ops navigation.
• Auth: PMFlow platform capability platform.ai_routing.manage.
• Response data:
  • function_name
  • tier
  • source: "default" | "override"

PUT /model-routing/functions/{function_name}

• Auth: PMFlow platform capability platform.ai_routing.manage.
• UI exposure: hidden from the current Route Lab UI. Future exposure must add reason, TTL, dry-run, audit review, and auto-expiry controls before operators can edit function-level overrides.
• Request body:
  • tier_alias: "low" | "high"
• Side effects:
  • persist override into integrations(type='model_routing')
  • append audit to operation_logs
• Boundary:
  • The API only accepts slot aliases, not provider/model/base URL strings; arbitrary model-name editing remains owned by provider connection setup.
  • Protected high-requirement functions such as requirement planning and assignee matching cannot be downgraded to low; the service returns a validation error instead of saving an override that would violate scene-slot capability requirements.

AI Routing & Providers

• UI placement: split by control plane.
  • Customer workspace UI under /ai-config only shows AI usage settings: readiness, team policy, input sources, knowledge, MCP template use, and quotas.
  • PMFlow platform AI operations UI under /platform/* owns provider health, global routing, route/context governance, semantic facts, prompt/eval diagnostics, and cross-tenant operations metrics.
  • Project pages consume AI state only through AI 副驾 status and read-only inherited policy summaries.
• Platform AI Ops UI is now menu-split under the AI runtime layer:
  • /platform: platform runtime overview, affected scenes, diagnostics, and next actions; old /platform/ai-routing-console redirects here for compatibility.
  • /platform/ai-routing-providers: provider/runtime connection, independent enable/disable state, masked credential state, connection test state, normalized capability matrix, executable capability probe evidence, and one global default fallback runtime.
  • /platform/ai-routing-slots: PMFlow capability slots; fast/deep are configurable now, structured is consumed by llm_service.generate_structured_object once published active, long-context is consumed only by explicit long-document/long-thread/cross-project-context calls, and tool is consumed only by explicit tool-calling or MCP execution-planning calls. External-query/private/multimodal remain reserved candidate slots. A slot consumes enabled supplier runtimes through primary runtime + fallback chain, publish validation checks provider capabilities and probe evidence, and business/runtime code consumes published active slots instead of hardcoded model names.
  • /platform/ai-routing-scenes: business-scene to capability-slot matrix; advanced function details are hidden by default.
  • /platform/ai-routing-costs: call cost, upgrade cost, quota/cache gaps, and provider usage integration gaps.
  • /platform/ai-routing-failures: sanitized risk diagnostics and recent failure samples.
  • /platform/ai-call-traces: AI call trace ledger for provider/model invocations, redacted prompt/response previews, routing metadata, slot evidence, latency/token/cost estimates, and trace detail drill-down.
  • /platform/prompt-assets: Prompt asset inventory and operation view; lists registry prompts, default seed prompt availability, active/draft prompt releases, call sites, risk level, release policy, and inline prompt migration gaps.
• These platform menus consume GET /ai-routing/admin-console, GET/PUT/POST /ai-routing/capability-slots*, POST /ai-routing/diagnostics/run, GET /ai-call-traces*, and GET/POST /prompt-assets*; provider writes are owned by /ai-steward/llm-engines. Runtime route mutation remains restricted to platform AI Ops. Provider rows expose available_actions so the UI only renders operations that are valid for the saved connection state.

LLM Engine Provider Connections

• Auth: PMFlow platform capability platform.ai_routing.manage.
• Storage: integrations(type='llm_engine') under the platform AI Ops runtime scope. The database table remains tenant-scoped for compatibility, but platform supplier/runtime config is pinned to the internal platform runtime scope (PMFLOW_PLATFORM_RUNTIME_TENANT_ID, default 1) and is not a customer workspace setting. Existing active_engine_id is treated as legacy compatibility for default_fallback_engine_id.
• Runtime semantics:
  • Multiple supplier connections may be enabled at the same time.
  • enabled=false connections are retained for editing/testing history but skipped by runtime routing, low/high tier selection, and low-to-high escalation.
  • default_fallback_engine_id is the global fallback when no function rule, capability slot, or tier route resolves. It is not a supplier enable switch.
  • Connection tests update connection_status, last_test_status, last_test_at, and last_error_summary; they do not by themselves make a connection the default fallback.
  • Each connection stores a normalized capabilities object inside integrations(type='llm_engine').config.engines[*]; legacy rows without capabilities are normalized at read time using provider/model defaults so UI and validation do not crash.
  • Capability fields currently include structured_output, json_schema, tool_calling, long_context, max_context_tokens, vision, audio, local_only, private_deployment, external_search_ready, avg_latency_ms, cost_tier, and reliability_tier.
  • Capability audit fields include the normalized nested capability_probe object plus backward-compatible flat fields capability_source, capability_probe_status, capability_last_verified_at, capability_blocking_reasons, and capability_evidence. capability_probe is stored inside the engine config and has {status, last_verified_at, verified_capabilities, evidence, source} where source is inferred | manual | probed; each evidence row records status/method/evidence_strength/request_summary/response_summary/failure_code/latency_ms and may carry operator evidence metadata (source_type/source_url/source_note/verified_by/verified_at/expires_at). Read responses also expose declared_capabilities and backend-derived effective_capabilities; legacy rows without capability_probe normalize to status=untested and do not crash old runtime reads.
• Endpoints:
  • GET /ai-steward/llm-engines: list masked connections, settings, normalized capabilities, available_actions, and default_fallback_engine_id.
  • POST /ai-steward/llm-engines: create an enabled supplier connection; accepts optional capabilities; optional set_active remains accepted for backward compatibility and now means “set as default fallback”.
  • PUT /ai-steward/llm-engines/{engine_id}: update name/provider/model/base URL/key/capabilities and reset connection test state when runtime fields change.
  • PUT /ai-steward/llm-engines/{engine_id}/enabled: enable or disable a saved connection.
  • POST /ai-steward/llm-engines/{engine_id}/default-fallback: set the global fallback runtime; only enabled connections with connection_status=available can be selected.
  • POST /ai-steward/llm-engines/{engine_id}/test: test one enabled saved connection using its saved provider/model/base URL/key.
  • POST /ai-steward/llm-engines/{engine_id}/capability-probe: only runs for enabled connections that already passed connection test; accepts mode=quick|full|advanced, optional targets[], and allow_high_cost. The default full plan runs basic chat, a low-cost model self-report reference call, plus the declared capability scope: structured JSON parse, independent JSON Schema parameter, tool-calling, streaming observability, and long-context declared-window gates only when long-context is declared or explicitly targeted. Model self-report is stored as status=declared_only/evidence_strength=model_self_report; it is visible in provider evidence and AI call audit because it is a real upstream call, but it never counts as protected slot verified evidence or aggregate probe pass/partial/fail status. Provider UI must render model self-report only as a separate reference card, not as a probe-detail capability pill; the long-context probe-detail row is the single user-facing capability item for context window status. Streaming is a transport/runtime trait for stream=true incremental responses, not a declared model capability matrix item; provider UI may show it in probe detail and a separate runtime traits area, but must not mix it into the verified model capability list. Declared capabilities must be displayed without arbitrary truncation; if any declared capability lacks live/provider-contract/operator evidence, aggregate status cannot be passed and must stay partial or untested. Undeclared optional capabilities do not produce blocking failures or downgrade the aggregate probe status. Long-context gates read the configured max_context_tokens; provider/model specs that PMFlow knows from official contracts, such as DashScope qwen-plus, are stored as status=verified/evidence_strength=provider_contract without sending high-cost long text to the endpoint. Unknown provider declared windows remain declared_only and do not count as verified slot evidence. A verified higher long-context window covers lower threshold rows such as 32K/128K for aggregate status and UI display. Results write back into capabilities.capability_probe, capability_evidence, and derived effective_capabilities without adding a migration.
  • POST /ai-steward/llm-engines/{engine_id}/capability-attest: platform operator manually confirms a high-cost capability evidence item, currently scoped to capability_key=long_context. The request records tested_tokens, evidence source type, optional source URL/note, and optional expiry. It writes evidence_strength=operator_verified/method=operator_attestation into capability_probe.evidence and compatibility capability_evidence, updates derived effective_capabilities, and can satisfy long-context protected slot publishing until the evidence expires. This endpoint does not call the upstream provider endpoint and therefore does not create an ai_call_logs row; AI call audit continues to show only real upstream endpoint interactions.
  • DELETE /ai-steward/llm-engines/{engine_id}: delete a saved connection only after it is disabled and is not the default fallback.

Capability Slots

• Auth: PMFlow platform capability platform.ai_routing.manage.
• Storage: integrations(type='ai_capability_slots') under the same platform runtime scope as provider connections (PMFLOW_PLATFORM_RUNTIME_TENANT_ID, default 1).
• Runtime semantics:
  • Provider connections are the runtime inventory; capability slots bind enabled provider connections into PMFlow ability abstractions.
  • Slot config is release-controlled: edits write draft.slots; only publish promotes the draft into active.slots. Runtime code reads active slots only and never consumes unpublished draft.
  • low/high tier resolution, control-plane rule resolution, function override resolution, and low-to-high escalation first consume active slot binding when present.
  • backend/.control_plane/pmflow-routing-rules.json remains the baseline/default rule pack and cold-start fallback, not the only live binding source once a slot is configured.
  • Disabled provider connections cannot be saved as primary or fallback slot runtimes.
  • Draft validation applies SLOT_REQUIREMENTS from backend/app/services/ai_routing_governance_service.py: high forbids local-only/Ollama, structured requires structured_output + json_schema, long-context requires long_context and max_context_tokens >= 32768, and tool requires tool_calling. Structured/tool/long-context are configurable draft slots; external/private/multimodal remain non-configurable candidate slots and cannot be saved as runtime bindings.
  • Provider capability probing treats long_context as the provider's configured max_context_tokens window, not as a hard-coded 32K test. A provider configured with 16K verifies that declared 16K window when the provider/model has a known official contract covering it, but it still cannot satisfy the long-context slot publish gate unless max_context_tokens >= 32768; long_context_32k/128k are explicit threshold probes and slot-publish gates only. Editing provider/model/base URL/API key or declared capabilities invalidates previous capability probe evidence and resets the engine to capability_probe_status=untested; name-only edits preserve evidence.
  • For structured/tool/long-context slots, validation distinguishes missing capability, missing probe evidence, and stale probe evidence: *_capability_missing means the normalized declared capability is false or below threshold; *_capability_evidence_missing means labels claim support but no verified capability_probe.evidence/compatibility capability_evidence with live, provider-contract, or operator-verified evidence strength exists; *_capability_evidence_stale means verified evidence is older than AI_CAPABILITY_PROBE_EVIDENCE_TTL_DAYS (default 90) or its explicit expires_at has passed. declared_only/manual/inferred/model_self_report evidence never satisfies protected slot publishing. low can publish without probe evidence but returns a warning.
  • Runtime effect is release-controlled: generate_structured_object only consumes the published active structured slot. Draft structured bindings are visible for validation/review but do not affect runtime until publish succeeds. When an active structured slot exists, runtime tries the structured primary first and then its fallback chain, skipping disabled/deleted runtimes and runtimes that do not satisfy structured_output + json_schema. If all configured structured slot runtimes fail after invocation, the call fails explicitly instead of falling back to templates or an unrelated low/high route. If the published active structured slot is configured but has no usable runtime before invocation, protected structured functions fail explicitly with a structured-slot runtime error; non-protected structured calls may fall back to the existing high/low/default path only with degraded routing metadata.
  • Long-context and tool runtime effects are narrower than structured: runtime consumes active long_context only when routing_meta explicitly requests slot_key/planned_tier/tier_alias=long_context, and consumes active tool only when routing_meta explicitly requests tool or uses MCP execution-planning modes execution_mode=local_planner|local_worker. These slots skip disabled/deleted runtimes and runtimes missing long_context + max_context_tokens >= 32768 or tool_calling. If the requested active slot is configured but has no usable runtime, the call fails with {slot}_slot_runtime_unavailable; if no active slot is published, the existing low/high/control-plane path remains in force. External-query/private/multimodal slots are not runtime consumers in this phase even if an active candidate binding exists.
  • Capability slot routing metadata includes slot_key, slot_version, slot_runtime_source=active_slot, slot_fallback_index, and slot_degraded=false; degraded non-protected structured fallback uses slot_runtime_source=active_slot_degraded and slot_degraded=true.
  • Slot detail payloads expose candidate_engines[] for runtimes satisfying the slot requirements and blocked_candidate_engines[] with product-level gap_reasons[] for enabled runtimes that are missing capability, missing probe evidence, or stale evidence.
  • Deep/high slot is protected and cannot enable customer-space downgrade; high slot cannot publish a local Ollama runtime.
  • Existing legacy {slots: ...} configs are read as both active and draft during normalization so upgrades do not drop live routing.
• Endpoints:
  • GET /ai-routing/capability-slots: returns active_version, draft_version, dirty, validation, history, active_slots, draft_slots, configurable runtime slots, external-query provider-chain slots, and non-configurable candidate slots with masked runtime metadata.
  • PUT /ai-routing/capability-slots/{slot_key}/draft: update primary_engine_id, fallback_engine_ids, failure_policy, and allow_scene_downgrade for configurable low/high/structured/tool/long_context draft slots; for external_query, the same request fields carry primary_provider_id and fallback_provider_ids and are normalized into the slot binding as primary_provider_id / fallback_provider_ids / verifier_required=true / source_filtering_required=true / failure_policy=explicit_fail. The endpoint appends operation_logs(entity_type='ai_capability_slot', action='draft_update'). private/multimodal return a product error because they are candidate slots and do not consume runtime in this phase.
  • PUT /ai-routing/capability-slots/{slot_key}: backward-compatible alias for draft update; it no longer makes runtime routing immediately consume the change.
  • POST /ai-routing/capability-slots/validate: validate draft slots for missing/disabled/test-failed runtimes, duplicate fallback, high-slot Ollama, protected downgrade, capability requirement misses, missing capability evidence, and stale capability evidence.
  • POST /ai-routing/capability-slots/publish: promote draft slots to active when validation has no critical item, generate a release version, and append operation_logs(entity_type='ai_capability_slot_release', action='publish').
  • POST /ai-routing/capability-slots/rollback: restore a prior published slot snapshot as a new active version and append operation_logs(entity_type='ai_capability_slot_release', action='rollback').

GET /ai-routing/overview

• Purpose: platform AI routing overview for PMFlow AI operators.
• Auth: PMFlow platform capability platform.ai_routing.manage.
• Response data:
  • config_version, config_updated_at, source_of_truth
  • slots[]: low/high slot summaries with Chinese labels, provider/model display summary, connection state, capability coverage, and masked key status.
  • capability_slots[]: configurable low/high/structured/tool/long_context/external_query slots and candidate private/multimodal slots. LLM slots include primary_engine_id, fallback chain, failure policy, protected state, requirements, capability coverage, candidate count, candidate runtime previews, and blocked candidate reasons. external_query includes primary_provider_id, fallback_provider_ids, verifier_required, source_filtering_required, and external_provider_registry status for MCP adapter, bounded live search fallback, verifier, and fail-closed source filtering.
  • metrics: recent 24h/7d calls, failures, failure rate, escalation rate, structured failure rate, average latency, and cost estimate.
  • diagnostics[]: risk cards such as high slot unavailable, same runtime for low/high, protected downgrade, structured failure spike, or local Ollama scope risk.
• Boundary: no cleartext key, api_env, prompt, raw provider secret, raw error, or raw routing meta.

GET /ai-routing/team-policy

• Purpose: team-lead-facing business policy view for project launch, requirement structuring, task breakdown, assignee matching, internal QA, external query, Feishu understanding, and Feishu reply.
• Auth: current workspace OWNER or REVIEWER.
• Response data:
  • strategy: quality_first | balanced | speed_first
  • scenes[]: Chinese business scene policies, preferred mode, escalation rule, fallback behavior, and editable business note.
  • automation_boundary, budget_guard, quality_targets, updated_at, updated_by
• Boundary: team policy is saved product governance state only; it does not rewrite llm_service runtime routing in v1.

PUT /ai-routing/team-policy

• Purpose: save team AI policy display/governance state.
• Auth: current workspace OWNER only via can_approve_ai_routing_change.
• Request body:
  • strategy?: "quality_first" | "balanced" | "speed_first"
  • scenes?: [{ key, policy, mode?, human_confirmation?, protected? }]
  • automation_boundary?: string
  • budget_guard?: { enabled?: boolean, monthly_budget_cny?: number | null, alert_threshold_ratio?: number }
  • quality_targets?: string[]
• Side effects:
  • persist into integrations(type='ai_team_policy')
  • append operation_logs(entity_type='ai_routing_policy')
• Boundary: never writes backend/.control_plane/pmflow-routing-rules.json, provider secrets, or model-routing overrides; audit payload contains business policy only, not provider/model/runtime fields.

GET /ai-routing/admin-console

• Purpose: AI admin/operator console aggregating provider connection summaries, capability slots, post-publish slot observability, business-scene routes, recent failure samples, protected scenes, and supplier/runtime diagnostics.
• Auth: PMFlow platform capability platform.ai_routing.manage.
• Response data:
  • providers[]: display-only provider health, enable state, fallback marker, connection test state, masked key state, normalized capability tags, capability source, probe status, last verified time, probe error summaries, probe blocking reasons, and state-derived available_actions.
  • capability_slots[]: configurable low/high/structured/tool/long_context/external_query slot binding summaries and candidate private/multimodal placeholders with requirements, coverage, missing capability labels, missing evidence labels, stale evidence labels, candidate runtimes, and external provider registry state for the external-query slot.
  • capability_slot_release: release-control payload from GET /ai-routing/capability-slots; the UI uses draft slots for editing and active slots for current runtime display.
  • slot_observability[]: post-publish read model for active low/high/structured/long_context/tool/external_query slots. Each item includes slot_key, slot_label, active_version, active_runtime, and windows.last_24h / windows.last_7d with status=sampled|empty, total_calls, failed_calls, failure_rate, fallback_hits, fallback_rate, degraded_calls, degraded_rate, active_slot_calls, active_slot_degraded_calls, average_latency_ms, estimated_cost, source labels, and sanitized recent_failure_samples[]. Aggregation is based on ai_call_logs routing metadata when present (slot_key, slot_runtime_source, slot_fallback_index, slot_degraded) and compatible slot columns (planned_tier/executed_tier/routing_decision) for old logs. Empty windows return zero counts and sample_state_label=暂无运行样本; cost and latency are operational estimates from logs, not provider bills or SLA measurements.
  • external_query publish validation fails closed when no external provider is available, neither MCP adapter nor bounded live search fallback is available, verifier is unavailable, source filtering is not fail-closed, or failure policy is not explicit_fail. Runtime only consumes the active external-query slot after route_mode=external; internal query and unpublished drafts do not consume it.
  • scene_routes[]: scene label, mode, backend scene_contract, protection state, lifecycle, and diagnostic function mapping; raw function_name may only be present in admin data and must not be shown in the business-scene route UI.
  • scene_slot_matrix[]: explainability matrix for operators. Each row includes scene_key, scene_label, scene_contract, lifecycle, scene_family, current_slot, required_slot, current_slot_label, required_capabilities[], protected, active_runtime, active_slot_runtime, draft_runtime, draft_slot_runtime, active_version, draft_dirty, capability_gap, recent_failure_rate, recent_failure_count, recent_failed_calls, recent_total_calls, scene_health, release_gate, impact_summary, aggregate risk_level/risk_label, slots[], and advanced functions[]. scene_contract includes business goal, input contract, output contract, success criteria, failure policy, confirmation policy, evidence policy, protected reason, expected slot, scene family, owner, and lifecycle. scene_health includes status=healthy|warning|blocked|unknown, score, blockers, warnings, and evidence summary. release_gate includes whether publish is blocked, blocking reason, draft impact, protected-scene regression, and suggested action. active_runtime / active_slot_runtime and draft_runtime / draft_slot_runtime summarize slot key/label, release version, configured state, runtime label/source, and primary runtime id. capability_gap distinguishes missing capability, missing probe evidence, stale evidence, and human-readable blocking reasons for release review. Each slot row includes slot_key, slot label, whether it is required by the scene, active runtime/source, release version, capability coverage, and risk reasons such as missing active binding, missing capability, missing probe evidence, stale probe evidence, or protected-scene downgrade. functions[] is diagnostic payload only; business-scene route UI must stay at scene/slot level, consume backend scene contracts, and route function-level inspection to hidden Route Lab.
  • recent_failures[]: sanitized failure samples without raw error or prompt; includes scene_key / scene_label when the function belongs to a registered business scene so /platform/ai-routing-failures?scene=... can filter deterministically.
  • protected_scenes[], diagnostics[]
• Boundary: this is the only user-facing surface that may show provider/model/base URL summaries, and all secrets must remain masked; PMFlow business pages must consume only business policy/mode/trust state.

GET /ai-call-traces

• Purpose: platform AI call trace ledger for PMFlow AI operators to inspect provider/model call history, sanitized request/response evidence, runtime routing metadata, slot usage, latency, tokens, cost estimates, and recent failure context.
• Auth: PMFlow platform capability platform.ai_routing.manage.
• Storage: reads from ai_call_logs; new runtime writes should populate trace_id, user_id when the request has an authenticated operator, raw configured provider code, model, latency_ms, routing_meta, prompt attribution fields prompt_key / prompt_release_id / prompt_source, and true upstream provider payload fields provider_request_payload / provider_response_payload / provider_attempts in addition to existing prompt/response/token/cost/status fields. Operator-facing responses must distinguish raw provider code from product/runtime display labels; DashScope/Qwen calls must persist provider code dashscope, never the removed historical code glm.
• Query params:
  • page, page_size
  • status
  • provider, model
  • function_name, scene_key, slot_key
  • prompt_key, prompt_source, prompt_release_id
  • trace_id
  • tenant_id
  • keyword
  • since_hours
• Response data:
  • summary: total calls, failed calls, total tokens, estimated cost, average latency, and top provider codes/display labels for the current filter set.
  • items[]: log id, trace id, tenant/user, created time, raw function_name plus Chinese function_label, scene display metadata, status, raw provider_code, provider_label, runtime_label, optional engine_id/engine_name, model, slot key/label, prompt key/release/source, routing decision/source/rule, token/cost/latency metrics, upstream usage-derived prompt_tokens / completion_tokens / total_tokens, request max_tokens, finish_reason, Function Runtime Profile version/max token metadata, redacted trigger preview, and error summary.
  • page, page_size, total, has_next.
• Capability probe display: AI call audit follows the real upstream endpoint interaction boundary. New provider capability probes do not write an extra probe_engine_capabilities aggregate log. Rows whose function_name starts with probe_capability_ are visible by default only when they correspond to an upstream provider call; the model self-report probe is shown because it is a short upstream call, while non-upstream declared/contract gates are stored in provider capability evidence but are not written as AI call logs. Historical probe_engine_capabilities aggregate rows are hidden from default list/summary results and remain queryable only through an explicit function_name filter.
• Boundary: prompt, response, and provider payload content are always redacted before returning to the UI. Provider secrets, cleartext bearer tokens, API keys, phone numbers, emails, and raw transport headers must not be returned. The database stores compatibility prompt/response for legacy search and previews, but operator detail UI should prioritize true upstream provider_request_payload / provider_response_payload / provider_attempts and routing/probe metadata. This view is platform-only and must not appear in customer workspace AI settings, Project Launch, Space, or project-level AI copilot surfaces.

GET /ai-call-traces/{trace_id_or_log_id}

• Purpose: open one AI call trace detail by trace_id or numeric ai_call_logs.id.
• Auth: PMFlow platform capability platform.ai_routing.manage.
• Response data:
  • trace: list-row fields plus routing metadata, probe metadata, redacted upstream payload evidence, and audit policy notes.
  • trace.raw_payload_available=true when ai_call_logs.provider_request_payload, provider_response_payload, or provider_attempts exists; detail response includes request.provider_request_payload_redacted, response.provider_response_payload_redacted, and response.provider_attempts_redacted. Raw encrypted provider payload replay/export is not part of this API.
• Boundary: 404 returns the standard response envelope with data=null; details follow the same redaction and platform-only visibility rules as the list endpoint.

GET /prompt-assets

• Purpose: platform Prompt asset center for PMFlow AI operators to inspect all registered and discovered runtime prompts, release state, and migration gaps before editing or optimizing prompt behavior.
• Auth: PMFlow platform capability platform.ai_routing.manage.
• Storage/read model: combines backend/app/config/ai_prompt_registry.py, default templates exported by backend/app/config/ai_prompts.py, tenant-scoped prompt_releases, prompt release gate checks in prompt_release_checks, golden cases in prompt_golden_cases, replay runs/results in prompt_replay_runs / prompt_replay_case_results, and prompt-attributed quality metrics from ai_call_logs. It does not expose secrets or raw provider payloads.
• Query params:
  • family: classification | extraction | planning | response | governance
  • runtime_source: catalog | ai_prompts | inline_discovered
  • editable_policy: managed_release | guarded_release | needs_migration
  • keyword: matches prompt key, business scenario, module, or call site.
• Response data:
  • summary: total assets, active release count, needs-migration count, and guarded count for the current tenant.
  • items[]: prompt key, module, business scenario, call sites, input/output contract, family, responsibility scope, priority/audience, runtime source, editable policy, risk level, template variables, default template hash/preview, active release summary, latest release summary, release gate summary, latest replay run summary, draft count, release count, and migration status.
• Boundary: this is a platform-only operational inventory. inline_discovered means the prompt has been found in code but the runtime call site still needs migration to read active releases; the UI must not present such entries as already configurable or active. Customer workspace settings, Space, Project Launch, and project-level AI copilot surfaces must not expose prompt bodies.

GET /prompt-assets/{prompt_key}

• Purpose: open one prompt asset detail, including the default template body when available, active/draft release state, call sites, contracts, and migration status.
• Auth: PMFlow platform capability platform.ai_routing.manage.
• Response data:
  • Same fields as the list item, plus default_template_body, release body_snapshot values for platform-side review and diff, and a 7-day quality_summary based on ai_call_logs.prompt_key.
• Boundary: 404 returns the standard response envelope with data=null. Guarded prompts are visible for audit, but activation policy still belongs to the prompt release / replay / evaluation workflow and must not bypass release review.

POST /prompt-assets/{prompt_key}/releases

• Purpose: create a tenant-scoped draft prompt release for a managed or guarded prompt asset.
• Auth: PMFlow platform capability platform.ai_routing.manage.
• Request data:
  • body_snapshot: required prompt template body.
  • notes: optional release note / change reason.
• Validation:
  • prompt_key must exist in ai_prompt_registry.
  • Only editable_policy=managed_release | guarded_release and non-inline assets with a default template can create releases.
  • Template placeholders must not introduce variables outside the default template contract.
• Boundary: needs_migration and inline_discovered return the standard error envelope and remain read-only until runtime migration is implemented. guarded_release can create candidate releases, but cannot activate until release gate checks pass.

POST /prompt-assets/{prompt_key}/releases/{release_id}/activate

• Purpose: activate a draft prompt release for the current tenant; any existing active release for the same prompt becomes archived.
• Auth: PMFlow platform capability platform.ai_routing.manage.
• Boundary: managed releases can activate directly. Guarded releases require passing gate checks before activation; golden_replay remains blocking when no active golden cases exist, and with active cases it requires a completed release replay run with zero failed cases. Current replay mode is deterministic contract smoke and explicitly records that no real LLM replay was executed.

POST /prompt-assets/{prompt_key}/releases/{release_id}/rollback

• Purpose: reactivate an archived managed prompt release as a rollback target.
• Auth: PMFlow platform capability platform.ai_routing.manage.
• Boundary: only archived releases can be rolled back. Draft releases must use activate, and guarded prompts remain blocked until release gates exist.

GET /prompt-assets/{prompt_key}/quality-summary

• Purpose: aggregate prompt-attributed AI call quality for one prompt asset.
• Auth: PMFlow platform capability platform.ai_routing.manage.
• Query params:
  • window: 24h | 7d | 30d, default 7d.
  • status: optional status filter.
  • release_id: optional prompt release id filter.
• Response data: total_calls, failed_calls, failure_rate, fallback_calls, active_release_calls, default_fallback_calls, average_latency_ms, estimated_cost, recent_failures, and release_breakdown.
• Boundary: no attributed call rows returns zero metrics and empty samples; the API must not infer quality from unrelated function names or raw prompt text.

GET /prompt-assets/{prompt_key}/golden-cases

• Purpose: list deterministic golden cases for a prompt asset.
• Auth: PMFlow platform capability platform.ai_routing.manage.
• Query params: status, default can be omitted; UI usually reads active.
• Response data: items[], total, active_count.

POST /prompt-assets/{prompt_key}/golden-cases

• Purpose: create a manual golden case for future replay and current guarded release gate.
• Auth: PMFlow platform capability platform.ai_routing.manage.
• Request data: case_name, input_payload, optional expected_contract, expected_contains, notes.
• Boundary: stores JSON contracts only; it does not execute an LLM and does not publish a prompt.

POST /prompt-assets/{prompt_key}/golden-cases/from-call/{ai_call_log_id}

• Purpose: convert a prompt-attributed AI call log into a golden case seed.
• Auth: PMFlow platform capability platform.ai_routing.manage.
• Boundary: the source call must have the same prompt_key. The generated case stores compact prompt/response previews and metadata, not raw provider payloads or secrets.

GET /prompt-assets/{prompt_key}/releases/{release_id}/checks

• Purpose: list release gate checks for one prompt release and return the derived gate summary.
• Auth: PMFlow platform capability platform.ai_routing.manage.
• Response data:
  • items[]: check id, prompt key, release id, check type, status, severity, summary, details, creator, created/completed time.
  • gate: derived status not_run | passed | blocked, blocking reasons, required checks.

POST /prompt-assets/{prompt_key}/releases/{release_id}/checks/run

• Purpose: run MVP prompt release gate checks for a candidate release.
• Auth: PMFlow platform capability platform.ai_routing.manage.
• Current checks:
  • variable_contract: verifies the candidate template does not introduce placeholders outside the default template contract.
  • schema_smoke: checks whether structured/JSON prompt contracts declare JSON/schema constraints.
  • golden_replay: records blocking skipped/no_cases when no active golden cases exist; with active cases it remains blocking until a release replay run exists, and passes only when the latest completed replay run has zero failed cases. Warnings are recorded for human review and do not pretend to be real LLM replay evidence.
• Boundary: this endpoint does not call an LLM, does not mutate runtime routing, and does not automatically activate a release. Guarded releases stay blocked unless all required checks pass.

POST /prompt-assets/{prompt_key}/releases/{release_id}/replay-runs

• Purpose: run deterministic replay review for one prompt release against active golden cases.
• Auth: PMFlow platform capability platform.ai_routing.manage.
• Request data:
  • mode: default contract_smoke.
  • case_status: default active.
  • max_cases: default 20, max 100.
  • include_llm: must be false in this phase; true returns a standard error.
  • reason: optional audit note.
• Behavior:
  • Renders candidate release templates with golden case input_payload.
  • Optionally renders the current active release as baseline when present.
  • Evaluates deterministic expected_contract fields such as required_input_keys, required_prompt_contains, expected_contains, and forbidden_terms.
  • Persists one prompt_replay_runs row and per-case prompt_replay_case_results rows.
• Response data: replay run summary with run_status, counts, risk flags, summary, baseline release id, and case results.
• Boundary: does not call an LLM, does not write runtime routing, and does not activate a release. Missing active golden cases, unsupported replay mode, or include_llm=true fail closed.

GET /prompt-assets/{prompt_key}/releases/{release_id}/replay-runs

• Purpose: list replay runs for one prompt release.
• Auth: PMFlow platform capability platform.ai_routing.manage.
• Response data: { prompt_key, release_id, items[], total }; item rows include run status, counts, summary and risk flags without per-case results.

GET /prompt-assets/{prompt_key}/replay-runs/{run_id}

• Purpose: read one replay run with per-case results.
• Auth: PMFlow platform capability platform.ai_routing.manage.
• Boundary: 404 returns the standard response envelope with data=null; replay result payloads contain rendered prompt snapshots and must remain platform-only.

POST /ai-routing/diagnostics/run

• Purpose: run read-only diagnostics for routing/provider health.
• Auth: PMFlow platform capability platform.ai_routing.manage.
• Side effects: none; does not modify provider, slot, team policy, or runtime routing.

PMFlow OS Project Memory Read Models

All endpoints return { code, message, data } and require project visibility through membership or manager access. These endpoints are read-only: they must not commit ChangeSets, mutate truth nodes, execute AI actions, or write Project Memory.

GET /pmflow-os/projects/{project_id}/project-memory/overview

• Purpose: return the Project Knowledge Hub overview for the memory homepage.
• Response data: { projectId, projectName, generatedAt, metrics[], facts[], requirements[], decisions[], constraints[], evidence[], contextPacks[], writebacks[], aiSuggestions[], warnings[] }.
• Boundary: overview is a backend read model over confirmed truth, indexed assets, context pack projections, and writeback audit rows; frontend must not reconstruct the authoritative memory overview from raw truth-state except as a degraded fallback.

GET /pmflow-os/projects/{project_id}/project-memory/items

• Purpose: list confirmed project memory objects across facts, requirements, decisions, risks, constraints, tasks, tests, releases, and metrics.
• Query params: category, stage, source_type, status, query, limit, offset.
• Response data: { projectId, total, limit, offset, items[] }; each item includes evidenceRefs, impactRefs, timestamps, status, and metadata.

GET /pmflow-os/projects/{project_id}/project-memory/items/{item_id}

• Purpose: read one memory item for detail drawers or deep inspection.
• Response data: { projectId, item }.

GET /pmflow-os/projects/{project_id}/project-memory/assets

• Purpose: list project assets such as conversation evidence, documents, code/PR evidence, tests, release records, feedback, metrics, and external research assets.
• Query params: asset_type, source_type, status, query, limit, offset.
• Boundary: assets may be indexed automatically, but they do not become Project Truth until a Change Review or trusted rule confirms them.

GET /pmflow-os/projects/{project_id}/project-memory/context-packs

• Purpose: list AI-readable context packs grouped by execution scenario.
• Response data: { projectId, total, contextPacks[] }; packs expose included item/asset ids, usage, warnings, and freshness.

GET /pmflow-os/projects/{project_id}/project-memory/writebacks

• Purpose: list ChangeSet writeback/version audit rows.
• Response data: { projectId, total, limit, offset, writebacks[] }; rows include item counts, committed/skipped/pending status, source ChangeSet id, committer display fields (committedBy / committedById), and item summaries.

PMFlow OS Adaptive Capacity

All endpoints return { code, message, data }. Project members may read. Override simulate/apply requires OWNER or REVIEWER; write endpoints only persist capacity override audit records and must not assign tasks, request review, write ChangeSet, or mutate Project Memory.

GET /pmflow-os/projects/{project_id}/capacity-plan?date=YYYY-MM-DD

• Purpose: compute the daily adaptive human capacity plan from current truth-state, reviewer routing, execution summary, workspace bindings, user projects, legacy workload reference, and active overrides.
• Response data:
  • projectId, date, generatedAt
  • teamDemandMix
  • teamEffectiveMinutes, teamPlannedTouchMinutes
  • memberPlans[]: base/effective minutes, dynamic suggestedBaseline, current mix, planned touch minutes, status, remaining minutes, bottleneck, fatigue risk, risk density, canTakeMore, manual override, explanations
  • humanTouches[]: source, target href, work type, estimated minutes, risk, urgency, binding, assigned user, context readiness, AI reduction potential
  • warnings, recommendations
• Boundary: daily plan is computed at read time. Do not persist fixed baselines or daily snapshots.

POST /pmflow-os/projects/{project_id}/capacity-overrides/simulate

• Purpose: simulate a manager capacity override before applying it.
• Request body: PMFlowCapacityOverridePayload
• Response data: { beforePlan, afterPlan, impactSummary, warnings }
• Boundary: no database write and no assignment side effect.

POST /pmflow-os/projects/{project_id}/capacity-overrides

• Purpose: apply a manager override and persist audit in human_capacity_overrides.
• Request body: PMFlowCapacityOverridePayload
• Response data: PMFlowCapacityOverrideRecord
• Side effects: insert one override audit row only.
• Boundary: reason is required; default expiry is same day 23:59 if omitted. Overtime increases time budget but must not clear fatigue or quality risk.

GET /pmflow-os/projects/{project_id}/capacity-overrides?date=YYYY-MM-DD

• Purpose: list override audit records for the given day.
• Response data: PMFlowCapacityOverrideRecord[]

GET /pmflow-os/projects/{project_id}/execution-capabilities

• Addition: response data may include adaptiveCapacitySummary: DailyCapacityPlan.

Task Briefs

GET /task-briefs/center

• Purpose: list generated brief cards

GET /task-briefs/templates

• Purpose: list templates

POST /task-briefs/templates

• Purpose: create template

PUT /task-briefs/templates/{template_id}

• Purpose: update template

GET /task-briefs/runs

• Purpose: list generation runs

POST /task-briefs/generate

• Purpose: generate one task brief run

GET /task-briefs/contract-sync

• Purpose: expose docs/contract sync status snapshot