PMFlow/docs/architecture/API_CONTRACTS.md

API CONTRACTS

PMFlow OS

Client presentation boundary:

• frontend/src/api/pmflowOs.ts and frontend/src/features/pmflow-os/store.tsx must convert auth/permission/access/server failures into customer-safe PMFlow OS messages. User-facing PMFlow OS pages must not expose raw provider, Axios, FastAPI credential, HTTP 401, or Could not validate credentials text.

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, delivery_id?: string | null, event_source_id?: string | null, occurred_at?: string | null.
  • delivery_artifacts?: { changed_files?: ChangedFile[], commands_run?: CommandRun[], test_outputs?: TestOutput[], screenshots?: Screenshot[], logs?: LogSnippet[], risk_notes?: RiskNote[], review_checklist?: ReviewChecklistItem[] } | null.
  • ChangedFile: { path, change_type?: "added" | "modified" | "deleted" | "renamed" | "unknown", summary?, risk_level?: "low" | "medium" | "high" }.
  • CommandRun / TestOutput: status 只允许 "passed" | "failed" | "skipped" | "blocked" | "unknown"；命令输出只保存摘要或引用，不保存无限长日志。
• 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, delivery_artifacts}.
  • External runtimes should pass a stable delivery_id and/or event_source_id; PMFlow treats either value as an idempotency key within the same tenant/project/task and reuses the existing ProgressEvent on retry instead of creating duplicate evidence.
  • Returns the latest ExecutionSummaryProjection, allowing execution, deliveryArtifacts, artifactCompleteness, releaseGate, Team Feed, /space next action, and execution memory writeback projection to consume the same standardized result metadata.
  • artifactCompleteness is empty / incomplete / blocked / ready。缺 changed files、commands run、test outputs、UI 改动截图或 required review checklist 时保持 incomplete；failed/blocked command、test 或 checklist 进入 blocked。
  • failed / blocked / test_failed events fail-closed into releaseGate.status="blocked"; test_passed / checks_passed can only move the gate to needs_confirmation until human acceptance and execution_memory_writeback_v1 are both recorded.
  • Even after acceptance and execution memory writeback, release readiness requires artifactCompleteness.status="ready"; PMFlow does not treat a free-text test_summary alone as sufficient delivery evidence.
• Failure semantics:
  • 404 task_not_found
  • 422 repo_binding_not_found

POST /pmflow-os/projects/{project_id}/execution-artifact-review-actions

• Purpose: record a human or PMFlow-side review action for incomplete/blocked delivery artifacts.
• Auth: project member, OWNER, or REVIEWER; tenant comes from JWT.
• Request body:
  • task_id: string required.
  • action: "request_fix" | "record_fix" | "mark_recheck_ready".
  • review_item_ids?: string[], optional subset of current ExecutionSummaryProjection.artifactReview.items[].id.
  • note?: string | null.
• Behavior:
  • Reads current artifactReview from ExecutionSummaryProjection.
  • Writes ProgressEvent(event_type="artifact_review_requested" | "artifact_fix_recorded" | "artifact_recheck_ready", payload.protocol_version="artifact_review_action_v1").
  • Returns latest ExecutionSummaryProjection; artifactReview.actionHistory restores the action from dev-sync summary.
  • This endpoint only records review/rework intent. It does not run commands, generate a branch, push code, open or merge PRs, deploy, publish, create formal tasks, or write Project Memory.
• Failure semantics:
  • 404 task_not_found
  • 422 invalid_artifact_review_item_ids

POST /pmflow-os/projects/{project_id}/execution-artifact-rework-packages

• Purpose: create a new runtime-pullable rework execution package from current artifact review items.
• Auth: project member, OWNER, or REVIEWER; tenant comes from JWT.
• Request body:
  • task_id: string required.
  • repo_binding_id?: string | null.
  • runtime_target?: "local_bridge" | "codex" | "github_agent", default local_bridge.
  • review_item_ids?: string[], optional subset of current ExecutionSummaryProjection.artifactReview.items[].id; empty means all open items.
  • note?: string | null.
• Behavior:
  • Creates a new PromptPackage(package_kind="execution_handoff", package_payload.handoff_type="artifact_rework").
  • Package payload includes rework_contract, selected artifact_review items, current artifact_completeness, and previous delivery_artifacts.
  • Writes ProgressEvent(event_type="artifact_rework_package_created", payload.protocol_version="artifact_rework_package_v1").
  • Existing signed POST /pmflow-os/runtime/execution-packages can pull this package and returns package.reworkContract plus the usual callback contract.
  • When the runtime later posts signed /pmflow-os/runtime/execution-results with the same prompt_package_id, ExecutionSummaryProjection.artifactReview.closure links the package, pull event, result event, and current evidence coverage.
  • Closure uses latest same-name command/test/checklist evidence for blocking status, so a later passed result can close an earlier failed rework item without deleting historical evidence.
  • ExecutionSummaryProjection.releaseGate.releaseReadinessProof and acceptance.evidenceProof consume the same closure and artifact status. Once closure is resolved and artifacts are ready, historical failed artifact metadata no longer blocks release recheck, acceptance, or memory writeback; explicit failed / blocked / test_failed events remain release blocking.
  • execution_memory_writeback_v1 stores writeback_proof, release_readiness_proof, artifact_review, and artifact_completeness in Project Memory writeback metadata.
  • This endpoint creates context only. It does not execute commands, create branches, push, open or merge PRs, deploy, publish, create formal tasks, or write Project Memory.
• Failure semantics:
  • 404 task_not_found
  • 409 artifact_review_empty
  • 422 repo_binding_not_found
  • 422 invalid_artifact_review_item_ids

POST /pmflow-os/projects/{project_id}/execution-handoffs/{prompt_package_id}/runtime-credential

• Purpose: create a short-lived runtime ingest credential bound to one execution handoff package.
• Auth: project member, OWNER, or REVIEWER; tenant comes from JWT.
• Request body:
  • runtime_target?: "local_bridge" | "codex" | "github_agent", defaults from the handoff package when present.
  • allowed_sources?: ("pmflow_os" | "local_bridge" | "codex" | "github_agent" | "manual")[], defaults to the selected runtime target.
  • expires_in_seconds?: number, accepted range 300..604800, default 86400.
  • note?: string | null, audit/display hint only.
• Behavior:
  • Loads the existing PromptPackage(package_kind="execution_handoff") and validates its project/task/repo binding.
  • Writes pmflow_execution_runtime_credentials with tenant_id / key_id / secret_hash / project_id / task_id / prompt_package_id / repo_binding_id / runtime_target / allowed_sources / status / expires_at.
  • Returns the raw secret only once. The database stores only secret_hash; runtime verification recomputes the server-side secret from SECRET_KEY + key_id and validates the stored hash.
  • Response includes keyId, secretPreview, packageEndpoint="/api/pmflow-os/runtime/execution-packages", ingestEndpoint="/api/pmflow-os/runtime/execution-results", signingAlgorithm="hmac-sha256", signatureBase="{timestamp}.{raw_body}", example headers, package pull payload, and result ingest payload.
  • Creating a credential does not execute commands, open branches, push code, create PRs, publish releases, or write Project Memory.
• Failure semantics:
  • 404 prompt_package_not_found
  • 422 execution_handoff_required

POST /pmflow-os/runtime/execution-packages

• Purpose: unauthenticated but signed runtime package pull for Codex / Local Bridge / GitHub agent before execution starts.
• Auth: no JWT. The request must pass the same HMAC credential validation as runtime result ingest.
• Required headers:
  • X-PMFlow-Key-Id
  • X-PMFlow-Timestamp, unix timestamp, accepted skew 300 seconds.
  • X-PMFlow-Signature, HMAC-SHA256 over "{timestamp}.{raw_body}"; sha256=<hex> and raw hex are both accepted.
  • X-PMFlow-Delivery-Id, optional stable idempotency key when body omits delivery_id.
• Request body:
  • prompt_package_id: string
  • task_id: string
  • source: "local_bridge" | "codex" | "github_agent" | "manual"
  • delivery_id?: string | null
  • event_source_id?: string | null
• Behavior:
  • Loads the runtime credential by key_id, recovers tenant/project/task/package binding from the credential, verifies status, expiry, source allowlist, handoff package and signature.
  • Returns a machine-readable package containing project, formal task, repo binding, PromptPackage, Project Memory context, quality contract, constraints, forbidden actions, callback contract, and audit metadata.
  • Records ProgressEvent(event_type="execution_package_pulled", payload.protocol_version="runtime_execution_package_pull_v1") and reuses the same D8 idempotency rule for delivery_id / event_source_id.
  • This endpoint only returns execution context and records package pickup. It never runs commands, writes host config, opens branches, pushes code, merges, deploys, publishes, or writes Project Memory.
• Failure semantics:
  • 401 runtime_signature_invalid
  • 401 runtime_credential_expired
  • 401 runtime_source_not_allowed
  • 401 runtime_handoff_mismatch
  • 404 runtime_credential_not_found
  • 422 runtime_package_payload_invalid

POST /pmflow-os/runtime/execution-results

• Purpose: unauthenticated but signed runtime ingress for Codex / Local Bridge / GitHub agent execution result metadata.
• Auth: no JWT. The request must pass HMAC credential validation.
• Required headers:
  • X-PMFlow-Key-Id
  • X-PMFlow-Timestamp, unix timestamp, accepted skew 300 seconds.
  • X-PMFlow-Signature, HMAC-SHA256 over "{timestamp}.{raw_body}"; sha256=<hex> and raw hex are both accepted.
  • X-PMFlow-Delivery-Id, optional stable idempotency key when body omits delivery_id.
• Request body: same execution result payload as /execution-progress-events, including optional delivery_artifacts, plus required prompt_package_id.
• Behavior:
  • Loads the runtime credential by key_id, recovers tenant/project/task/package binding from the credential, verifies status, expiry, source allowlist, repo binding, handoff package and signature.
  • Fills delivery_id from X-PMFlow-Delivery-Id when omitted, then delegates to the existing execution_result_protocol_v1 ProgressEvent write path.
  • Reuses the D8 idempotency rule: stable delivery_id or event_source_id under the same tenant/project/task returns the existing event instead of creating duplicate evidence.
  • Updates credential last_used_at/use_count; it still records metadata only and never executes code, deploys, merges, or writes Project Memory. delivery_artifacts must be metadata summaries or external artifact refs, not raw binary screenshots, unbounded logs, secrets, or host files.
• Failure semantics:
  • 401 runtime_auth_missing
  • 401 runtime_signature_invalid
  • 401 runtime_credential_expired
  • 401 runtime_source_not_allowed
  • 401 runtime_handoff_mismatch
  • 404 runtime_credential_not_found
  • 422 invalid_runtime_result_payload

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

PMFlow AI Dual-Brain Contracts

These contracts are the baseline for AI-Dual-00 and all later Space AI / Project Copilot work. PMFlow AI is one user-facing AI with two product work surfaces:

• space_ai: the Space-level Operating Partner for cross-project attention, idea incubation, pending confirmation aggregation, AI work monitoring, and routing.
• project_copilot: the project-level truth-bound copilot for ProjectTruthState explanation, candidate changes, evidence review, execution handoff preparation, and writeback guardrails.

Common envelope

• Every user-facing AI answer must remain customer-safe and may expose only product-language sources, business object anchors, next actions, limitations, and process steps.
• raw_question must stay separate from structured context. Frontends must not prepend hidden prompt text to the question.
• Runtime payloads must carry surface_context or a stricter packet; answers must bind to visible objects whenever possible.
• Responses should prefer answer_canvas, customer_interaction_context_packet, and answer_process_packet over free-text-only answers.
• AI failures, insufficient evidence, structured parsing failures, and missing context must be explicit. No default objects, fake actions, or template success states are allowed.
• Customer-facing AI surfaces must not expose provider, model, prompt body/key, raw trace, function name, table/field name, SQL, backend file path, raw source label, or platform diagnostics.

space_operating_packet v1

• Producer: SpaceRuntimeContextBuilder plus controlled backend projections.
• Scope: current tenant/user visible Space facts only.
• Minimum shape:
  • packet_version: "space_operating_packet.v1"
  • visible_projects[]: {id, title, status, summary?, next_action?, health?, pending_count?, ai_work_status?}
  • saved_ideas[]: customer-safe idea seeds with {id, title, summary?, readiness?, status?, missing_questions?, recommended_next_action?}
  • pending_confirmations[]: customer-safe summaries, deep links and object_anchor; no ChangeSet commit authority.
  • ai_work_items[]: {object_ref, object_anchor?, status, summary, blocker?, next_action?}
  • drafts[]: Project Launch draft summaries; creation still requires human confirmation.
  • attention_queue[]: ordered items with {kind, object_ref, object_anchor?, reason, urgency, next_action, href?}
  • object_anchor: customer-safe object pointer {object_ref, object_type, object_id, surface, project_id, project_title, href, parent_object_ref?} used to route Space attention items back into Project Copilot surfaces without exposing raw tables, traces or backend internals.
  • automation_policy: policy_version="ai_dual_04_low_risk_proactive.v1", mode="suggest_only", low-risk levels suggest_only / prepare_only, and explicit confirmation requirements before project creation, Project Memory write, ChangeSet commit, execution handoff, external command execution, publish or deploy.
  • proactive_suggestions[]: low-risk suggestions derived from attention_queue, each with {title, reason, why_now, source_objects[], risk_level, required_confirmation, audit_event, action, href, object_ref, object_anchor?, automation_level, requires_user_confirm=true, blocked_automation[]}. These suggestions may rank, summarize, prepare navigation or prepare a preview, but they are not permission to write, publish or execute.
  • counts: project, saved idea, pending, draft, AI work, blocked/risk counts.
  • readiness: customer-visible AI availability and degradation state.
  • surface_hint?: frontend-only counts or UI hints that may supplement but must not override backend facts.
• Allowed outputs:
  • read-only Space summary, today brief, attention ordering, idea readiness explanation, route-to-project/launch/review suggestions, AI work monitor explanation.
• Forbidden outputs:
  • Project Memory write, ChangeSet commit, formal task creation, execution handoff, release/publish action, provider/model/prompt/platform diagnosis.
• Audit:
  • Space AI turns must persist the final PMFlowAITurnState, runtime steps, evidence actions, model call count, and prompt attribution for every LLM call. Legacy source_strategy / allowed_executors / surface_direct_eligible fields may appear only in compatibility payloads or old logs and must not drive the Space API main chain.

project_copilot_context_packet v1

• Producer: PMFlow OS projection layer and project copilot adapter.
• Scope: exactly one current project plus the selected surface/object anchor.
• Minimum shape:
  • packet_version: "project_copilot_context_packet.v1"
  • project_ref: {id, title, status, summary?}
  • surface: command_center | structured_extraction | change_review | project_memory | work_graph | execution_bridge | team_layer | release_growth
  • object_anchor?: current Requirement / ChangeItem / Task / Evidence / ExecutionPackage / ReleaseSignal / ProjectMemory node.
  • Project surfaces must restore object_anchor from customer-safe deep-link params when present: changeSetId + itemId, taskId, releaseId, or evidenceId.
  • truth_projection: customer-safe ProjectTruthState summary, not raw ORM rows.
  • change_context?: open ChangeSet, selected ChangeItem, evidence, approvals, risk and commit gate.
  • execution_context?: formal task, repo binding, prompt package, reviewer gate, artifact completeness, release readiness proof.
  • release_context?: release gate, validation, feedback, revenue/ROI/compliance/recommendation signals.
  • allowed_actions[]: answer | draft_change | review_explain | prepare_execution_handoff | route_to_surface.
  • forbidden_actions[]: explicit blocked actions and reasons.
  • automation_policy: the AI-Dual-04 low-risk proactive contract, always mode="suggest_only" for customer surfaces.
  • proactive_suggestions[]: customer-safe suggested next moves with why_now / source_objects / risk_level / required_confirmation / audit_event, automation_level=suggest_only|prepare_only, and requires_user_confirm=true.
  • limitations[]: evidence/context gaps and required human confirmations.
• Allowed outputs:
  • project truth explanation, evidence/risk review, candidate ChangeSet draft, execution handoff preparation, release/growth fit analysis, route-to-surface suggestions.
• Forbidden outputs:
  • cross-project portfolio ranking, platform provider/model/prompt diagnosis, ChangeSet commit, Project Memory write, external command execution, publish/deploy/delete/permission changes, or direct handoff from pending ChangeItem.
• Audit:
  • every answer or action must preserve project_id, surface, object_anchor, action_ladder_level, allowed_actions, blocked_actions, prompt attribution, and customer-safe evidence packet references.

Prompt migration baseline

• Runtime-migrated guarded/query/presentation prompts: PROMPT_CUSTOMER_ANSWER_COMPOSER, PROMPT_CUSTOMER_ANSWER_VERIFIER, PROMPT_RAG_QUERY_SEMANTICS, PROMPT_RAG_FOLLOWUP_ANCHOR_SEMANTICS, PROMPT_RAG_PENDING_CLARIFICATION_SELECTION_SEMANTICS, and PMFLOW_SEMANTIC_CONTEXT_DECISION_PROMPT. PROMPT_PMFLOW_AI_ROUTE_PLANNER is retained only as a legacy/deprecated prompt key placeholder for migration inventory and offline replay references; Space AI runtime must not call it for source, route, executor, analyzer, clarification, or answer-shape decisions.
• Space AI prompt work for AI-Dual-01: Turn Runtime must understand attention, idea_incubation, route_to_project, ai_work_monitor, cross_project_summary, and external_research as goal/evidence states instead of route-planner enums; answer composer/renderers must consume final TurnState and customer-safe evidence packets.
• Project Copilot prompt work for AI-Dual-02: prompts must consume project_copilot_context_packet, preserve action ladder boundaries, and return evidence, limitations, recommended actions, and blocked actions. Existing static frontend copilot copy is not a substitute for this contract.
• Prompt release and replay remain platform-only. Customer Space, Project Launch, and project-level copilot surfaces must not expose prompt bodies or prompt keys.

Project Copilot

POST /pmflow-os/projects/{project_id}/project-copilot/ask

• Purpose: project-level PMFlow AI copilot for one current project, one current surface, and one selected object anchor.
• Auth: logged-in project member or manager; tenant comes from JWT and project membership check.
• Request:
  • question: string is the raw user question only.
  • surface: command_center | structured_extraction | change_review | project_memory | work_graph | execution_bridge | team_layer | release_growth.
  • intent: ask | supplement | command.
  • object_anchor?: {type, id, title?} where type is project | change_set | change_item | task | release | evidence.
  • context_packet?: optional frontend packet hint. The backend must rebuild the authoritative project_copilot_context_packet.v1 from PMFlow OS projection and may only use this as a hint.
• Behavior:
  • The backend rebuilds ProjectTruthState through PMFlowOSProjectionService, optionally reads execution-summary, resolves the requested object anchor against the current project, and returns a server-authored project_copilot_context_packet.v1.
  • The current implementation uses a deterministic renderer with model_calls=0 for low-risk truth-bound answers. It returns answer_canvas, customer_interaction_context_packet, answer_process_packet, allowed_actions, blocked_actions, and limitations.
  • AI-Dual-04 proactive behavior is represented only as automation_policy and proactive_suggestions[] in project_copilot_context_packet.v1 and response payload. Allowed levels are suggest_only and prepare_only; every suggestion carries requires_user_confirm=true. The service may prepare a navigation target, review explanation, candidate direction, or execution context preview, but may not commit ChangeSets, write Project Memory, trigger execution handoff, run external commands, publish/deploy, delete, or change permissions.
  • The route is read-only. It must not create thread messages, trigger extraction, commit ChangeSet, write Project Memory, create tasks, prepare real execution handoff, execute external commands, publish, deploy, delete, or modify permissions.
  • Frontend ProjectCopilot in real project mode must call this route instead of routing copilot questions through thread-message send + extraction. Demo mode may keep local simulated replies.
• Failure semantics:
  • Missing project returns 404; non-member returns 403.
  • User-visible failure messages must be product semantic and must not expose traceback, prompt key, provider payload, function name, ORM rows, or raw source labels.
• Next prompt step:
  • When model-composed project copilot answers are introduced, composer/verifier prompts must consume only project_copilot_context_packet.v1 and customer-safe evidence fields, record prompt attribution, and preserve the same action ladder and blocked action contract.

Personal Space

POST /space/pmflow-ai/threads

• Purpose: create a user-visible PMFlow AI thread and send the first message for ordinary conversation, space/project inspection, project operating guidance, cross-project operating work, external research and AI capability status.
• Auth: logged-in user; tenant comes from JWT.
• Request body extends the existing Space ask body:
  • question: string is the raw user question only. Frontend must not prepend a prompt blob.
  • thinking_mode?: "auto" | "normal" | "deep".
  • action_mode?: "auto" | "standard" | "deep".
  • surface_context?: object, structured page/workbench/readiness context from the current surface.
• Behavior:
  • The route creates or resolves a PMFlow AI thread/message projection and enters PMFlowAgentRuntimeService.run_space_turn() to create one internal pmflow_agent_runs execution record for the assistant turn.
  • Runtime executes Dynamic Agent Workspace -> LLM Step Planner -> typed read/probe/specialist tool -> Observation Ledger -> State Critic -> replan/continue/stop -> Terminal Answer Runtime.
  • PMFlowAgentRuntimeService then persists the real dynamic steps into pmflow_agent_steps / observations / artifacts / verifications / memories.
  • Runtime tools only produce observations/artifacts/deliverables. They do not directly write final customer answers.
  • Strong project operations read project world state only when explicit page/session/object anchors exist. Visible projects are candidates only.
  • Open external/market/opportunity questions must not be answered from PMFlow capability or space project list alone; the planner must use public-source tools and opportunity-discovery review or return a clear evidence boundary.
  • User-visible payloads must not expose internal labels such as project_object_required_for_world_state, world_state, packet, trace, prompt, function, route_plan, model/provider metadata, raw source labels or table/field names.
• Response data must include:
  • thread_id
  • title
  • messages[]
  • assistant_message
• Assistant message data may include:
  • content
  • run_id
  • work_log[] with customer-safe Chinese labels and summaries
  • artifacts[]
  • actions[]
  • confirmations[]
• Failure semantics:
  • Upstream/runtime exceptions return a product-semantic failure message.
  • Failed steps are persisted as verifications when possible.
  • Raw traceback, prompt key, function name, provider payload, ORM row and route diagnostics must not appear in customer payloads.

POST /space/pmflow-ai/threads/stream

• Purpose: create a PMFlow AI thread with the same business semantics as POST /space/pmflow-ai/threads, but stream customer-safe process events and final answer chunks to the workspace UI.
• Transport: text/event-stream over authenticated POST; frontend uses fetch + ReadableStream so it can send JSON body and auth headers. This endpoint is not an unauthenticated EventSource URL.
• Event contract:
  • run.started: PMFlow AI has accepted the turn.
  • step.started / step.completed: one customer-safe Agent OS process step. step contains id/key/label/status/status_label/display_summary/duration_ms/blocking and must not expose prompt key, provider/model, trace id, table/field names, function names or raw tool payload.
  • answer.started: final answer has passed customer payload gates and is ready to output.
  • answer.delta: one chunk of the final customer-safe answer.
  • answer.completed: complete final answer text.
  • thread.completed: authoritative persisted thread detail; frontend must replace local streaming state with this payload.
  • error: product-semantic failure message.
• Behavior:
  • The same runtime and persistence path as the non-streaming endpoint is used. SSE is a projection of the real Agent OS execution, not a separate mock process.
  • Process events are emitted from PMFlowAIAgentRunService as the runtime completes real steps.
  • Final answer chunks are emitted only after the answer has been generated, sanitized, persisted and projected as customer-safe payload.

POST /space/pmflow-ai/threads/{thread_id}/messages

• Purpose: continue the same PMFlow AI thread with a new user message.
• Behavior: appends user/assistant messages to the same thread and creates a new internal Agent OS run for the assistant turn. It must not create a new visible conversation for every user message.
• Response shape is the same thread detail shape as POST /space/pmflow-ai/threads.

POST /space/pmflow-ai/threads/{thread_id}/messages/stream

• Purpose: continue an existing PMFlow AI thread with the same event contract as POST /space/pmflow-ai/threads/stream.
• Behavior: preserves the existing thread/session anchor, emits customer-safe process events during the new assistant turn, and ends with thread.completed containing the updated persisted thread detail.

GET /space/pmflow-ai/threads

• Purpose: list PMFlow AI threads for the current tenant/user.
• Response data contains items[] with thread_id, title, message count, last message preview, current object refs and timestamps.

GET /space/pmflow-ai/threads/{thread_id}

• Purpose: read one PMFlow AI thread with continuous messages and customer-safe per-assistant-message projections.

/space/pmflow-ai/runs*

• Purpose: compatibility/debug read surface for durable internal Agent OS runs. Product UI must use /space/pmflow-ai/threads* as the primary conversation surface.

POST /space/ai-concierge/ask

• Purpose: compatibility endpoint for older Space AI callers.
• Behavior: must call the same PMFlowAgentRuntimeService.run_space_turn() path and return the same customer-safe Agent OS projection. It must not restore old route planner, task graph, executor enum, answer contract or presentation early-return as the main control path.

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.

Agent run full-chain audit

• Scope: /agent-run-audits* is platform-only and requires platform.audit.view. It is not a customer workspace surface and must not be exposed in Space, Project Launch or project-level AI copilot.
• Read endpoints:
  • GET /agent-run-audits
  • GET /agent-run-audits/{public_run_id}
• Data sources:
  • pmflow_agent_runs for one user-triggered PMFlow AI turn.
  • pmflow_agent_steps / pmflow_agent_observations / pmflow_agent_artifacts / pmflow_agent_verifications / pmflow_agent_memories for Agent OS nodes, facts, gaps, deliverables and gates.
  • pmflow_ai_messages for the user/assistant transcript projection attached to the run.
  • ai_call_logs.agent_run_id / agent_step_key for external model/API calls made under the same run.
• Runtime attribution:
  • PMFlowAgentRuntimeService.run_space_turn() binds the durable public_run_id into runtime audit context before delegating to PMFlowAIAgentRunService.
  • GoalFrame, Step Planner, Evidence Normalizer, State Critic and Answer Runtime bind their node key before calling llm_service.
  • llm_service._log_ai_call() persists agent_run_id, agent_step_key, latency, routing metadata and provider request/response/attempt payloads.
• Response behavior:
  • List returns run summaries, status counts, step/observation/artifact/verification counts and linked AI-call counts.
  • Detail returns transcript messages, chronological timeline, node payloads, observations, artifacts, verifications, memories and linked AI-call details with redacted provider payloads.
  • Platform detail may expose provider/model/prompt/routing diagnostics and redacted API payloads. Customer payloads must not expose raw run ids, step ids, prompt keys, provider payloads, tool trace or internal exceptions.

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.
• Runtime migrated governance/query/presentation prompts: PMFLOW_SEMANTIC_CONTEXT_DECISION_PROMPT, PROMPT_CUSTOMER_ANSWER_COMPOSER, PROMPT_CUSTOMER_ANSWER_VERIFIER, PROMPT_RAG_QUERY_SEMANTICS, PROMPT_RAG_FOLLOWUP_ANCHOR_SEMANTICS, and PROMPT_RAG_PENDING_CLARIFICATION_SELECTION_SEMANTICS read the current tenant active release at runtime and record prompt_key / prompt_release_id / prompt_source in AI call logs; missing active releases fall back to the default seed template. PROMPT_PMFLOW_AI_ROUTE_PLANNER is a legacy/deprecated inventory key only and must not be used by Space AI runtime.

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

• Addition: response data includes qualityContract and acceptance.
• qualityContract: deterministic execution quality contract with required test levels, release-blocking test cases, test environment, evidence requirements, acceptance gate and computed test-case status.
• acceptance: human acceptance / technical review projection from progress events; canEnterReleaseGate=false keeps releaseGate in needs_confirmation even when tests pass.

POST /pmflow-os/projects/{project_id}/execution-acceptance-decisions

• Purpose: record user acceptance or technical review decision for a formal execution task.
• Request body: { task_id, decision, note?, evidence_event_ids? }, where decision is accept | request_changes | reject | request_technical_review | approve_technical_review.
• Response data: latest ExecutionSummaryProjection.
• Errors: 404 task_not_found, 409 acceptance_test_evidence_required, 409 technical_review_required.
• Boundary: writes an execution_acceptance_decision_v1 ProgressEvent only; does not merge, deploy, release, commit Project Memory, or execute local commands.

POST /pmflow-os/projects/{project_id}/execution-memory-writebacks

• Purpose: after execution evidence and human acceptance are complete, write the accepted execution result back into PMFlow Project Memory / Work Graph read models.
• Request body: { task_id, progress_event_ids?, result?, note? }, where result is completed | blocked | changes_requested and defaults to completed.
• Behavior:
  • Requires the task's acceptance.status="accepted" and userAccepted=true; technical-review-only approval is not enough.
  • Requires at least one execution result evidence event such as branch/commit/PR/test/check/merged/blocked/failed; acceptance events alone are not evidence.
  • Writes ProgressEvent(event_type="execution_memory_writeback", source="pmflow_os", payload.protocol_version="execution_memory_writeback_v1").
  • Updates task stable status: completed -> done, blocked / changes_requested -> blocked; completed also writes completed_at.
  • Adds audit metadata to Task.manual_overrides.latest_execution_memory_writeback.
  • Returns { writeback, executionSummary, projectTruthState }; writeback also appears in GET /project-memory/writebacks.
  • releaseGate remains needs_confirmation / 等待写回项目记忆 after acceptance and becomes ready only after this writeback is present together with test and sync evidence.
• Errors: 404 task_not_found, 409 execution_acceptance_required, 409 execution_evidence_required, 409 writeback_already_exists, 409 unresolved_blocker_exists, 422 invalid_progress_event_ids.
• Boundary: does not merge, deploy, publish, execute local commands, create tasks, or commit ChangeSets. It only records PMFlow's accepted execution fact.

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