API Reference

API

Runtime Entry Surfaces

Read-only service contract

Endpoint	Method	Auth	Purpose	Stability
`/healthz`	`GET`	none	liveness	stable
`/readyz`	`GET`	none	readiness	stable
`/versionz`	`GET`	none	version and identity	stable
`/contractz`	`GET`	none	read-only contract view	stable
`/fabric-presencez`	`GET`	none	fabric discovery presence	stable
`/fabric-compatibilityz`	`GET`	none	fabric compatibility/policy hints	stable
`/fabric-manifest.json`	`GET`	none	runtime-served manifest	stable
`/fabric-plane-workspace-facts`	`GET`	none	Pattern-owned Plane workspace and project binding facts for Fabric polling	stable
`/fabric-plane-membership-facts`	`GET`	none	Pattern-owned session and role-mapping facts for Fabric polling	stable
`/fabric-agent-workflow-compliance-contract`	`GET`	none	Pattern-owned readback contract for Fabric-backed workflow compliance materialization	stable
`/fabric-agent-workflow-compliance-readback`	`GET`	none	Pattern-owned runtime readback for the current Fabric-backed workflow compliance instance	stable
`/fabric-agent-workflow-operator-view`	`GET`	none	Pattern-owned operator view shape for workflow blockers and stale projection posture	stable
`/fabric-agent-workflow-pr-ready-readback`	`GET`	none	Pattern-owned runtime projection of the current Fabric PR-ready gate, including blocker and stale/conflict posture	stable
`/fabric-agent-workflow-execution-closure-readback`	`GET`	none	Pattern-owned runtime projection of current Fabric execution-closure truth	stable
`/fabric-work-operating-e2e-live-boundary-contract`	`GET`	none	Pattern-owned boundary contract for the Fabric W8 live acceptance matrix facade	stable
`/fabric-work-operating-e2e-live-readback`	`GET`	none	Pattern-owned runtime projection of Fabric W8 live acceptance flow visibility plus additive Fabric acceptance-status visibility with no-green-by-projection semantics	stable
`/fabric-execution-model-brownfield-boundary-contract`	`GET`	none	Pattern-owned boundary contract for the Fabric Wave-9 brownfield execution-model backfill facade	stable
`/fabric-execution-model-brownfield-readback`	`GET`	none	Pattern-owned read-only projection of Fabric Wave-9 brownfield migration, version-compatibility, and projected-work fail-closed posture	stable
`/fabric-agent-platform-maturity-boundary-contract`	`GET`	none	Pattern-owned boundary contract for advisory trajectory-review and knowledge-spoke maturity materialization	stable
`/fabric-agent-platform-maturity-readback`	`GET`	none	Pattern-owned advisory projection of Fabric agent-platform maturity truth for trajectory review and knowledge hub/spoke layers	stable
`/fabric-agent-universal-program-boundary-contract`	`GET`	none	Pattern-owned boundary contract for Fabric universal intent-to-program issue/wave materialization	stable
`/fabric-agent-universal-program-readback`	`GET`	none	Pattern-owned advisory readback for Fabric universal program waves, dependencies, operator progress, and additive universal closeout acceptance visibility	stable
`/fabric-master-program-boundary-contract`	`GET`	none	Pattern-owned boundary contract for advisory Fabric master-program completion visibility	stable
`/fabric-master-program-readback`	`GET`	none	Pattern-owned advisory readback for Fabric master-plan completion-status truth	stable
`/fabric-operator-work-projection-boundary-contract`	`GET`	none	Pattern-owned boundary contract for Wave-6 operator-work projection and mission-control context consumption	stable
`/fabric-operator-work-projection-readback`	`GET`	none	Pattern-owned read-only projection of Fabric operator-work states and mission-control context bindings with fail-closed live-followthrough posture	stable
`/fabric-weft-work-item-visibility-boundary-contract`	`GET`	none	Pattern-owned boundary contract for read-only Weft candidate visibility, confidence routing, retry, blocker, and reminder follow-up posture	stable
`/fabric-weft-work-item-visibility-readback`	`GET`	none	Pattern-owned read-only facade for Weft capability visibility, confidence routing, retries, blockers, and reminder follow-up posture	stable
`/fabric-weft-runtime-consumer-boundary-contract`	`GET`	none	Pattern-owned boundary contract for bounded native Weft runtime consumer readback	stable
`/fabric-weft-runtime-consumer-readback`	`GET`	`record_id`, `source_suffix`	Pattern-owned readback that consumes one live Weft Pattern queue item, reads the Pattern payload, and submits a bounded native consumer receipt	stable
`/fabric-plan-studio-boundary-contract`	`GET`	none	Pattern-owned boundary contract for the Fabric-backed Plan Studio intent-ingestion-to-program operator facade	stable
`/fabric-plan-studio-readback`	`GET`	none	Pattern-owned read-only projection of the Fabric-backed Plan Studio intent-ingestion-to-program session, graph, readiness, and execution-context posture	stable
`/pattern-event-modeling-truth-registry`	`GET`	none	Pattern-owned Event Modeling truth registry contract	stable
`/api/v1/event-modeling/truth-registry`	`GET`	none	Pattern-owned Event Modeling truth registry readback and remaining-gap posture	stable
`/api/v1/event-modeling/standard`	`GET`	none	Pattern-local readback of the canonical Fabric Event Modeling standard truth	stable
`/api/v1/event-modeling/catalog`	`GET`	none	Pattern-owned Event Modeling catalog for local consumer readback	stable
`/api/v1/event-modeling/catalog/compatibility`	`GET`	none	Pattern-local readback of the canonical Fabric Event Modeling catalog truth	stable
`/api/v1/event-modeling/issue-spec-export`	`GET`	none	Pattern-local readback of the canonical Fabric Event Modeling issue-spec export	stable
`/api/v1/events/issue-spec-export/contracts`	`GET`	none	Pattern-local compatibility wrapper for the canonical Fabric Event Modeling issue-spec export contract family	stable
`/api/v1/event-modeling/readiness`	`GET`	none	Pattern-owned Event Modeling readiness posture for local consumer readback	stable
`/api/v1/event-modeling/readiness/compatibility`	`GET`	none	Pattern-local readback of the canonical Fabric Event Modeling readiness truth	stable
`/api/v1/event-modeling/standard-health-report`	`GET`	none	Pattern-local readback of the canonical Fabric Event Modeling standard health report	stable
`/api/v1/event-modeling/companion-surfaces-contract`	`GET`	none	Pattern-local readback of the canonical Fabric companion surfaces contract	stable
`/api/v1/event-modeling/audit-aggregation-contract`	`GET`	none	Pattern-local readback of the canonical Fabric audit aggregation contract	stable
`/api/v1/event-modeling/defaults`	`GET`	none	Pattern-local readback of canonical Fabric Event Modeling defaults	stable
`/api/v1/event-modeling/standard-versioning-policy`	`GET`	none	Pattern-local readback of canonical Fabric Event Modeling versioning policy	stable
`/api/v1/event-modeling/tenant-bootstrap-contract`	`GET`	none	Pattern-local readback of canonical Fabric tenant bootstrap contract	stable
`/api/v1/event-modeling/companion-consumer-contract`	`GET`	none	Pattern-local readback of canonical Fabric companion consumer contract	stable
`/api/v1/event-modeling/human-event-schema`	`GET`	none	Pattern-local readback of canonical Fabric human event schema	stable
`/api/v1/event-modeling/notification-contract`	`GET`	none	Pattern-local readback of canonical Fabric notification contract	stable
`/api/v1/event-modeling/compliance-mapping`	`GET`	none	Pattern-local readback of canonical Fabric compliance mapping	stable
`/api/v1/event-modeling/forensic-replay`	`GET`	none	Pattern-local readback of canonical Fabric forensic replay contract	stable
`/metrics`	`GET`	none	Prometheus-ready sync and contract observability surface	stable
`/openapi.json`	`GET`	none	FastAPI schema	internal

API Prefix

/api/v1

Frontend Backend Boundary

The React frontend consumes Mission Control product routes through frontend/src/api.ts. The canonical boundary contract for frontend request behavior, backend router mounting, and route-family ownership is:

contracts/frontend_backend/pattern_frontend_backend_boundary_v1.json

The contract is validated by:

python scripts/validate_frontend_backend_boundary_contract.py

Frontend views must not call Plane, Git provider, Fabric, or runtime transport APIs directly. Provider and runtime protocol details stay behind backend routers and services so audit, auth, and degraded-state behavior remain centralized.

Router CI Coverage

The canonical FastAPI router coverage inventory is:

contracts/testing/router_ci_coverage_v1.json

The inventory is validated by:

python scripts/validate_router_ci_coverage.py
python -m pytest -q backend/tests/test_router_ci_coverage.py

The Gitea smoke job runs the pytest guard so new router modules must be added to the coverage inventory with at least one existing primary regression path.

Fabric Pull Publications

These two routes exist so Fabric can read Pattern-owned local facts without forcing Plane, Heddle, or downstream consumers to scrape internal operator surfaces directly.

GET /fabric-plane-workspace-facts
- exports local workspace, Plane project binding, sync-mode, and webhook posture facts
- truth owner stays jhf-pattern
- this route does not invent Fabric, Plane, or identity truth
GET /fabric-plane-membership-facts
- exports local OIDC client, role-mapping, and membership-visibility contract facts
- truth owner stays jhf-pattern-session-contract
- Plane visibility truth still belongs to Fabric
- Mission Control v2 is published here as an admitted SSO surface with:
  - auth_mode
  - admitted_surface
  - role_admin_posture
  - verify_paths
GET /fabric-agent-workflow-compliance-contract
- exports the revision-bound Pattern readback contract for the Fabric-owned workflow phase model
- Fabric remains workflow truth owner
GET /fabric-agent-workflow-compliance-readback
- exports the current revision-bound Pattern runtime readback for one Fabric-backed workflow compliance instance
- includes current phase, workflow run id, artifact/gate posture, and ready-for-review status without inventing local workflow authority
GET /fabric-agent-workflow-operator-view
- exports the operator-facing section layout for workflow phase, blockers, stuck phases, and stale projection visibility
GET /fabric-agent-workflow-pr-ready-readback
- exports the revision-bound Pattern runtime projection for Fabric-owned PR-ready gate status and blocker reasons
- includes fail-closed phase-conflict posture when Fabric bootstrap and gate truth disagree
- ready-for-review may only be shown when the Fabric gate evaluates green
GET /fabric-agent-workflow-execution-closure-readback
- exports the revision-bound Pattern runtime projection for Fabric-owned execution-closure and final say-it-once blocker posture
- Pattern may not reinterpret blocked-external closure reasons locally
GET /fabric-work-operating-e2e-live-boundary-contract
- exports the Pattern-owned facade contract for the Fabric W8 acceptance matrix
- Pattern remains materialize-only and may not emit a final closeout verdict
GET /fabric-work-operating-e2e-live-readback
- exports per-flow visibility for software_change, invoice_payment, customer_onboarding, and support_case
- includes required owner readbacks, currently open readbacks, explicit non-authoritative projection posture, and additive Fabric W8 acceptance-status visibility
- missing owner evidence or missing Fabric acceptance truth remains blocked instead of green
GET /fabric-execution-model-brownfield-boundary-contract
- exports the Pattern-owned boundary contract for the Fabric Wave-9 brownfield migration/backfill policy
- Pattern remains materialize-only and may not rebind active instances, promote new-run versions, or become runtime migration authority
GET /fabric-execution-model-brownfield-readback
- exports advisory-only brownfield classification posture for projected open work
- keeps active-instance admitted-version posture and new-run latest-version posture explicit and fail closed
- missing projected-instance inventory or missing owner readback blocks green interpretation instead of letting projection-only migration claims pass
GET /fabric-agent-platform-maturity-boundary-contract
- exports the Pattern-owned facade contract for the Fabric agent-platform maturity program
- Pattern remains materialize-only and may not promote local maturity truth into gate or closeout authority
GET /fabric-agent-platform-maturity-readback
- exports advisory-only maturity readback for Trajectory Review and Knowledge Hub · Hub & Spoke
- consumes the canonical Fabric plan and normalization contracts through checkout truth
- no local second authority is introduced
GET /fabric-agent-universal-program-boundary-contract
- exports the Pattern-owned facade contract for Fabric universal intent-to-program truth
- Pattern remains materialize-only and may not become intent, assignment, or closeout authority
GET /fabric-agent-universal-program-readback
- exports advisory-only wave, dependency, and operator progress readback for the universal autonomy program
- consumes the canonical Fabric plan plus universal-intent and delegated-closeout contracts and the additive Fabric universal closeout acceptance surface
- passes through Fabric-published artifact_profiles, artifact_bundle_profiles, and visual_evidence_policies so downstream consumers can read current artifact and closeout policy truth without local reinterpretation
- consumes the canonical Fabric plan plus universal-intent and delegated-closeout contracts and the additive Fabric universal closeout acceptance surface
- missing Fabric truth, missing acceptance truth, or missing issue-state readback blocks green interpretation instead of inventing local progress truth
python scripts/validate_agent_universal_program_facade.py --require-exact-main --output artifacts/agent-universal-program-owner-followthrough.json
- emits the repo-owned owner-followthrough evidence artifact for the universal program facade
- fails closed unless both public facade routes match repo truth and the checkout is exact main
GET /fabric-master-program-boundary-contract
- exports the Pattern-owned facade contract for advisory Fabric master-program completion visibility
- Pattern remains materialize-only and may not promote local stack completion claims
GET /fabric-master-program-readback
- exports advisory-only Fabric master-plan completion visibility, including active blocking subplans and stack-consistent completion-claim posture
- missing Fabric completion-status truth blocks green interpretation instead of inventing local completion semantics
GET /fabric-weft-work-item-visibility-boundary-contract
- exports the Pattern-owned boundary contract for Weft candidate visibility, confidence routing, retries, blockers, and reminder follow-up posture
- Pattern remains visibility-only and may not become Weft, Spindle, Loom, or executor truth owner
GET /fabric-weft-work-item-visibility-readback
- exports advisory-only Weft capability visibility, confidence routing, retry, blocker, and reminder follow-up posture for downstream Pattern/Lantern consumers
- consumes canonical Weft plan and workspace classification policy truth through local checkout or raw Gitea fallback
- missing Weft truth or missing required plan markers blocks green interpretation instead of inventing local completion or candidate authority
GET /fabric-weft-runtime-consumer-boundary-contract
- exports the Pattern-owned boundary contract for bounded native Weft runtime consumer readback
- Pattern remains consumer-readback-only and may not become Weft, Spindle, Loom, or business-done truth owner
GET /fabric-weft-runtime-consumer-readback
- consumes one live Weft Pattern work-queue item, reads the actual Pattern payload, and submits a bounded native consumer receipt keyed to the current handoff-manifest payload sha
- missing queue selection, missing handoff payload sha, or missing Pattern payload readback blocks native receipt submission instead of inventing downstream consumption
- the route may not upgrade closeout, Spindle, or Loom truth; it only proves bounded downstream consumption
GET /fabric-plan-studio-boundary-contract
- exports the Pattern-owned boundary contract for the admitted Plan Studio intent-ingestion-to-program operator facade
- Pattern remains readback-only and may not become planning, review, admission, execution, or closeout authority
- the published route_posture_snapshot must describe Lantern as a consumer/initiator surface for the admitted lane instead of stale generic route-read-only posture
GET /fabric-plan-studio-readback
- exports advisory-only session, program-graph, materialization-readiness, execution-context posture, v1/v2 rubric dual-read state, and consumer-safe revision/review/timeline/evidence detail projection for the Plan Studio intent-ingestion-to-program facade
- prefers the canonical live Fabric /api/v1/planning/* family and falls back to checkout/raw truth only when live planning API readback is unavailable
- keeps v1 primary during the Fabric-defined dual-read period; a missing v2 contract or unexplained rubric/gate/matrix semantic diff is visible as fail-closed readback, never a Pattern-selected fallback
- missing upstream truth or missing issue-state readback blocks green interpretation instead of inventing local planning progress, and detail projections fall back to explicit future_contract posture when upstream admitted detail truth is absent
- includes Fabric C10 owner-decision packet/readback projection with deterministic approved, rejected, and needs_more_context resume posture; missing consumer auth or incomplete upstream truth remains explicitly fail-closed and never enables Pattern writes

Core Product Groups

Projects

/api/v1/projects
/api/v1/projects/{project_id}
/api/v1/projects/{project_id}/active-workflow
/api/v1/projects/{project_id}/board
/api/v1/projects/{project_id}/doctor
/api/v1/projects/{project_id}/operator-dashboard
/api/v1/projects/{project_id}/plan-studio/sessions
/api/v1/projects/{project_id}/plan-studio/sessions/{session_id}
/api/v1/projects/{project_id}/plan-studio/sessions/{session_id}/program-graph
/api/v1/projects/{project_id}/plan-studio/sessions/{session_id}/execution-context
/api/v1/projects/{project_id}/plan-studio/sessions/{session_id}/materialization-readiness
/api/v1/projects/{project_id}/plan-studio/sessions/{session_id}/materialization-request-boundary
/api/v1/projects/{project_id}/plan-studio/sessions/{session_id}/materialization-requests
auth:
- operator session
stability:
- active
example request:

GET /api/v1/projects/ops-signal-orchestra/operator-dashboard HTTP/1.1
Cookie: pm_session=&lt;session&gt;

example response shape:

&#123;
  "project_id": "ops-signal-orchestra",
  "mode": "active",
  "doctor": &#123;&#125;,
  "integrations": &#123;&#125;
&#125;

plan studio intent-ingestion-to-program summary:
- routes:
  - GET /api/v1/projects/{project_id}/plan-studio/sessions
  - GET /api/v1/projects/{project_id}/plan-studio/sessions/{session_id}
  - GET /api/v1/projects/{project_id}/plan-studio/sessions/{session_id}/program-graph
  - GET /api/v1/projects/{project_id}/plan-studio/sessions/{session_id}/execution-context
  - GET /api/v1/projects/{project_id}/plan-studio/sessions/{session_id}/materialization-readiness
  - GET /api/v1/projects/{project_id}/plan-studio/sessions/{session_id}/materialization-request-boundary
  - POST /api/v1/projects/{project_id}/plan-studio/sessions/{session_id}/materialization-requests
- purpose:
  - project-scoped readback for the Fabric-backed admitted Plan Studio lane, including intent-to-program session truth, admitted program graph nodes, fail-closed materialization readiness posture, admitted execution-context identity, current revision detail, review detail, timeline/evidence projection, and the current materialization-request boundary
  - current M8 followthrough is tracked through helpifyr-fabric#739, helpifyr-fabric#740, helpifyr-fabric#784, jhf-pattern#432, jhf-pattern#434, and jhf-pattern#446
- notes:
  - session and program truth remain Fabric-owned
  - materialization-request POST stays non-mutating in Pattern and returns the current readback idempotently when the bounded lane is already materialized
  - Pattern still does not perform live issue writes or execution handoff locally
  - missing upstream Fabric truth or owner-issue readback keeps readiness blocked
GET /api/v1/projects summary contract notes:
- project summaries now include bounded workspace freshness and integration posture hints:
  - task_count
  - open_task_count
  - latest_task_updated_at
  - plane_connected
  - repo_connected
  - repo_auth_state
  - workspace_health
  - workspace_health_note
- these fields exist so Mission Control can demote stale dormant workspaces and surface why an empty workspace is degraded instead of silently treating it as healthy active work
active workflow summary:
- route:
  - GET /api/v1/projects/{project_id}/active-workflow
- purpose:
  - machine-readable ownership, work-class, state-vocabulary, mutation, sync, and remediation contract for the active project workflow
- example response shape:

&#123;
  "workspace_model": "single_primary_repo",
  "primary_repo_ref": &#123;
    "provider": "gitea",
    "full_name": "JaddaHelpifyr/jhf-pattern"
  &#125;,
  "supported_work_classes": ["project_work", "case_linked_work", "system_runtime_work"],
  "state_contract": &#123;
    "priority_order": ["conflicted", "quarantined", "approval_required"]
  &#125;,
  "mutation_contract": &#123;
    "requires_expected_version": true,
    "silent_overwrite": false,
    "manual_override_requirements": ["why", "expected_version"]
  &#125;,
  "sync_contract": &#123;
    "git_inbound": "webhook_first",
    "git_poll_fallback_minutes": 5,
    "webhook_liveness_supported": true
  &#125;,
  "fabric_consumer_contract": &#123;
    "available": true,
    "state": "healthy",
    "contract_family": "helpifyr-support-pattern-consumer-contract",
    "workflow_scope": "next-active-project-workflow-wave",
    "workflow_wave": "wave-4-hard-enforcement-and-lifecycle-completion",
    "case_linked_work_semantics": ["conflicted", "degraded", "verification_required"],
    "lifecycle_states": ["active", "stale", "forced-review-required", "reopen-eligible", "archive-eligible", "remain-open"],
    "writeback_rules": [&#123;"name": "verification-required-or-conflicted-or-quarantined"&#125;],
    "failure_heatmap": &#123;"heatmap_mode": "consumer-visible"&#125;,
    "case_timeline": &#123;"timeline_mode": "consumer-visible"&#125;
  &#125;,
  "fabric_combination_profiles": &#123;
    "available": true,
    "state": "healthy",
    "contract_family": "fabric-combination-profiles",
    "owner_repo": "JaddaHelpifyr/helpifyr-fabric",
    "consumer_repository": "JaddaHelpifyr/jhf-pattern",
    "relevant_profile_keys": ["fabric-warp-shuttle", "fabric-all"],
    "required_profile_keys": ["fabric-all"],
    "optional_profile_keys": ["fabric-warp-shuttle"],
    "published_invariant_keys": ["fabric-truth-owner", "no-local-bundle-semantic"]
  &#125;,
  "plane_fabric_drift": &#123;
    "state": "degraded",
    "partial_visibility": true
  &#125;,
  "external_truth_summary": &#123;
    "state": "blocked",
    "external_truth": true
  &#125;,
  "case_linked_lifecycle": &#123;
    "states": ["active", "stale", "forced-review-required", "reopen-eligible", "archive-eligible", "remain-open"]
  &#125;,
  "writeback_guardrails": &#123;
    "requires_expected_version": true,
    "allowed_remediation_actions": ["retry_writeback", "refresh_metadata", "escalate_to_manual"]
  &#125;,
  "workspace_risks": &#123;
    "duplicate_attachment_risk": false
  &#125;,
  "lifecycle_visibility": &#123;
    "source_missing_count": 0
  &#125;,
  "branch_pr_pressure": &#123;
    "actionable_review_pressure": 1
  &#125;
&#125;

Tasks and Lanes

/api/v1/projects/{project_id}/tasks
/api/v1/projects/{project_id}/lanes
auth:
- operator session
stability:
- active
example request:

PATCH /api/v1/projects/ops-signal-orchestra/tasks/OPS-001 HTTP/1.1
Cookie: pm_session=&lt;session&gt;
Content-Type: application/json

&#123;"lane":"backlog","expected_version":"2026-04-01T00:00:00Z"&#125;

Support Orchestration Materialization

POST /api/v1/support-orchestration/projects/{project_id}/work-items/materialize
POST /api/v1/support-orchestration/projects/{project_id}/meeting-room-items/materialize
auth:
- bearer token matching PLANE_API_TOKEN
stability:
- internal
purpose:
- materialize one bounded support-derived Pattern work item from canonical support triage output
- return explicit readback when no Pattern work item is required
contract notes:
- fail-closed when Fabric correlation and case references are both absent
- idempotent reruns reuse the existing support-derived task instead of creating duplicates
- task and support-derived readbacks expose quality_brief when the upstream payload supplied brief attachment metadata
- bounded live Host172 verify is automated in python scripts/verify_issue612_support_orchestration_materialization.py --host <internal-runtime-redacted> --user administrator

Meeting Room Materialization

POST /api/v1/support-orchestration/projects/{project_id}/meeting-room-items/materialize
GET /api/v1/projects/{project_id}/tasks/meeting-room-derived
GET /api/v1/projects/{project_id}/tasks/{task_key}/meeting-room-derived
auth:
- bearer token matching PLANE_API_TOKEN for materialization
- operator session for readback routes
stability:
- internal
purpose:
- materialize exactly one Pattern-owned meeting_room work item for an admitted Jadda meet success lane
- expose bounded readback by task, correlation_id, room_sid, or room_name
- contract notes:
  - fail-closed when correlation_id, room_ref.room_sid, and room_ref.room_name are all absent
  - idempotent reruns reuse the existing meeting-room-derived task instead of creating duplicates
  - duplicate suppression matches on task_key, correlation_id, idempotency_key, room_ref.room_sid, and room_ref.room_name
  - participant and execution join payloads are scrubbed so raw token values are never echoed back; readback exposes token_present=true instead
  - readback publishes owner issue JaddaHelpifyr/jhf-pattern#632 and blocked program JaddaHelpifyr/jhf-jadda-interface#122 so the Jadda V4 closeout can reference Pattern-owned truth directly
  - Pattern remains materialization-only and does not become room, token, or meeting policy truth owner
example response shape:

&#123;
  "accepted": true,
  "authenticated": true,
  "project_id": "ops-signal-orchestra",
  "status": "materialized",
  "materialized": true,
  "existing_task": false,
  "idempotent_replay": false,
  "task_key": "MEET-corr-meet-001",
  "meeting_room_work": &#123;
    "task_key": "MEET-corr-meet-001",
    "correlation_id": "corr-meet-001",
    "owner_issue_ref": "JaddaHelpifyr/jhf-pattern#632",
    "blocked_program_ref": "JaddaHelpifyr/jhf-jadda-interface#122",
    "room_ref": &#123;
      "room_sid": "RM_12345",
      "room_name": "team-sync"
    &#125;,
    "participants_ref": [
      &#123;
        "role": "host",
        "join": &#123;
          "url": "https://calls.example.test/join/operator",
          "token_present": true
        &#125;
      &#125;
    ]
  &#125;,
  "readback": &#123;
    "decision": "meeting_room_work_materialized",
    "correlation_id": "corr-meet-001",
    "room_sid": "RM_12345",
    "room_name": "team-sync"
  &#125;
&#125;

example response shape:

&#123;
  "accepted": true,
  "authenticated": true,
  "project_id": "ops-signal-orchestra",
  "followup_required": true,
  "status": "materialized",
  "materialized": true,
  "existing_task": false,
  "idempotent_replay": false,
  "task_key": "SUP-fab-case-001",
  "support_work": &#123;
    "task_key": "SUP-fab-case-001",
    "fabric_case_ref": "FAB-CASE-001",
    "quality_brief": &#123;
      "attachment_status": "consumed",
      "consumed_before_task_start": true
    &#125;
  &#125;,
  "readback": &#123;
    "decision": "work_item_materialized",
    "fabric_case_ref": "FAB-CASE-001"
  &#125;
&#125;

GET /api/v1/auth/oidc/status
- purpose:
  - runtime-readable OIDC config plus admitted-surface posture
GET /api/v1/auth/oidc/session-contract
- purpose:
  - current session freshness, audience, scopes, role, admin posture, and verify-path contract
GET /api/v1/settings/app-login
- purpose:
  - identity summary plus admitted Mission Control app-login contract
admitted-surface contract:
- surface_key
  - mission-control-v2
- auth_mode
  - oidc_claim_projection
- consumer_posture
  - native_oidc_session_consumer
- local session truth owner
  - jhf-pattern-session-contract
- upstream readiness owner
  - jhf-heddle
- projection truth owner
  - helpifyr-fabric

Reed Owner Facts

GET /api/v1/reed/owner-facts
auth:
- operator session or equivalent admitted operator auth
stability:
- active
purpose:
- authenticated read-only owner surface for Reed to consume Pattern-owned adapter facts without mutation
fail-closed auth posture:
- missing auth returns 401
- stale OIDC operator auth returns 401
- insufficient role returns 403
source truth:
- contracts/reed/module-adapter-manifest.v2.json
example response shape:

&#123;
  "schema_version": "1",
  "surface_key": "pattern-reed-owner-facts-v1",
  "read_only": true,
  "auth_required": true,
  "stale_auth_fails_closed": true,
  "source_truth_owner": "JaddaHelpifyr/jhf-pattern",
  "manifest": &#123;
    "schema_version": "2.0",
    "manifest_key": "pattern-reed-module-adapter-manifest-v2",
    "path": "contracts/reed/module-adapter-manifest.v2.json"
  &#125;,
  "adapters": [
    &#123;
      "module_kind": "project",
      "adapter_key": "pattern-project-adapter-v2",
      "primary_surface": "/api/v1/projects/&#123;project_id&#125;/active-workflow",
      "supported_modes": ["dry_run", "admitted"]
    &#125;
  ],
  "discovery": &#123;
    "api_surface": "/api/v1/reed/owner-facts",
    "docs_ref": "docs/REED_OWNER_FACTS.md"
  &#125;
&#125;

example response shape:

&#123;
  "id": "OPS-001",
  "lane": "backlog",
  "work_class": "project_work",
  "work_item_truth_owner": "jhf-pattern",
  "source_truth_owner": "gitea",
  "source_reference_type": "issue",
  "version_token": "2026-04-01T00:00:00Z",
  "workflow_state": "partial_visibility",
  "external_truth_state": null,
  "external_truth": false,
  "missing_context": false,
  "partial_visibility": true,
  "writeback_guard_state": "pending_confirmation",
  "case_lifecycle_guard": null,
  "lifecycle_completion_guard": null,
  "consumer_remediation_actions": ["refresh_metadata"],
  "updated_at": "2026-04-01T00:00:00Z"
&#125;

Wave 3 workflow enforcement metadata:
- workflow_state
- external_truth_state
- external_truth
- missing_context
- partial_visibility
writeback_guard_state
case_lifecycle_guard
lifecycle_completion_guard
consumer_remediation_actions
quality_brief
- brief_ref
- attachment_status
- attached
- attached_at
- consumed
- consumed_at
- consumed_before_task_start
- source_truth_owner
Wave 4 hard-enforcement additions:
- task and review-action writebacks require expected_version
- stale or missing revision tokens return 409 with machine-readable remediation metadata
- successful review writebacks return readback_required, expected_version, and current_version
- lifecycle completion projection carries archive-eligible, remain-open, reopen-eligible, and forced-review-required as consumer-visible guards
these fields are exposed on both project-task payloads and support-derived work payloads
they are consumer-facing projections and do not redefine upstream Fabric ownership
quality_brief is owner readback only; Fabric event-family truth still stays external
the completed cross-repo closure for the previous plan slice is documented in:
- helpifyr-fabric#135
- jhf-pattern#107
the next Plane-owned contract and implementation slice now continues in:
- jhf-pattern#108
- jhf-pattern#109
the Plane-owned enforcement wave in jhf-pattern#109 adds:
- planning sync routes accept expected_version and reject stale writebacks with 409 conflict detail metadata
- planning sync and discovery payloads surface workflow_state, writeback_guard_state, external_truth_state, partial_visibility, missing_context, and consumer_remediation_actions
- Plane fallback and mirror mode readbacks expose last_origin_system, pending_confirmation, readback_required, and owner-visible fallback metadata instead of treating issue-mirror fallback as healthy hidden sync
the final Plane-owned closure pass is complete in:
- jhf-pattern#110
no additional repo-local API/MCP closure remainder was found for this plan slice

Agents and Handoffs

/api/v1/projects/{project_id}/agents
/api/v1/projects/{project_id}/handoffs
fail-closed handoff resolution:
- POST /api/v1/projects/{project_id}/handoffs/{handoff_id}/resolve now requires explicit completion attestation plus a non-empty completion note
- unresolved or partially completed work must stay open instead of being marked resolved with a generic quick-action note
- payloads that still carry continuation or blocker fields return 409 and preserve the open handoff

Planning

/api/v1/projects/{project_id}/planning/cycles
/api/v1/projects/{project_id}/planning/modules
/api/v1/projects/{project_id}/planning/pages
/api/v1/projects/{project_id}/planning/pages/sync-from-repo
/api/v1/projects/{project_id}/planning/pages/{slug}/pull-from-repo
/api/v1/projects/{project_id}/planning/pages/{slug}/push-to-repo
auth:
- operator session
stability:
- active
example request:

POST /api/v1/projects/ops-signal-orchestra/planning/pages/readme/pull-from-repo HTTP/1.1
Cookie: pm_session=&lt;session&gt;

example response shape:

&#123;
  "slug": "readme",
  "sync_state": "in_sync",
  "repo_path": "README.md"
&#125;

Delivery

/api/v1/projects/{project_id}/delivery/pipelines
/api/v1/projects/{project_id}/delivery/deployments
/api/v1/projects/{project_id}/delivery/releases
/api/v1/projects/{project_id}/delivery/environments
/api/v1/projects/{project_id}/delivery/review-queue
/api/v1/projects/{project_id}/delivery/review-queue/{provider}/{external_id}/create-task
/api/v1/projects/{project_id}/delivery/review-queue/{provider}/{external_id}/actions
/api/v1/projects/{project_id}/delivery/branch-queue
/api/v1/projects/{project_id}/delivery/release-readiness
/api/v1/projects/{project_id}/delivery/health-summary
/api/v1/projects/{project_id}/delivery/branch-queue/{provider}/{branch_name}/create-task
auth:
- operator session
stability:
- active
example request:

GET /api/v1/projects/ops-signal-orchestra/delivery/review-queue HTTP/1.1
Cookie: pm_session=&lt;session&gt;

example response shape:

&#123;
  "items": [
    &#123;
      "provider": "gitea",
      "repository_label": "JaddaHelpifyr/ops-signal-orchestra",
      "review_decision": "changes_requested",
      "approval_count": 0,
      "requested_reviewer_count": 1,
      "changes_requested_count": 1,
      "comment_count": 3,
      "cycle_keys": ["sprint-1"],
      "module_keys": ["api"],
      "linked_tasks": [&#123;"task_key": "GITEA-REV-12"&#125;]
    &#125;
  ],
  "repository_groups": ["JaddaHelpifyr/ops-signal-orchestra"],
  "cycle_groups": ["sprint-1"],
  "module_groups": ["api"]
&#125;

example branch hygiene response:

&#123;
  "items": [
    &#123;
      "provider": "gitea",
      "repository_label": "JaddaHelpifyr/ops-signal-orchestra",
      "name": "feat/runtime-cleanup",
      "freshness_state": "stale",
      "age_days": 37,
      "risk_reasons": ["stale-branch"],
      "linked_tasks": [&#123;"task_key": "GITEA-BR-FEAT-RUNTIME-CLEANUP"&#125;]
    &#125;
  ],
  "repository_groups": ["JaddaHelpifyr/ops-signal-orchestra"],
  "freshness_groups": ["stale", "aging", "fresh", "default"]
&#125;

example release readiness response:

&#123;
  "items": [
    &#123;
      "provider": "gitea",
      "external_id": "42",
      "name": "Release 1",
      "tag": "v1.0.0",
      "gate_state": "review",
      "cycle_key": "release-1",
      "module_key": "api",
      "latest_pipeline_status": "succeeded",
      "latest_deployment_status": "succeeded",
      "linked_review_count": 1,
      "risky_review_count": 1,
      "gate_reasons": ["candidate-release", "reviews-need-attention"]
    &#125;
  ],
  "blocked_count": 0,
  "review_count": 1,
  "ready_count": 0,
  "published_count": 0
&#125;

example review action request:

POST /api/v1/projects/ops-signal-orchestra/delivery/review-queue/gitea/77/actions HTTP/1.1
Cookie: pm_session=&lt;session&gt;
Content-Type: application/json

&#123;"state_action":"close","actor":"operator","expected_version":"2026-04-01T00:00:00Z"&#125;

example review action response:

&#123;
  "provider": "gitea",
  "external_id": "77",
  "requested_actions": ["close"],
  "applied": true,
  "details": &#123;"state": "closed"&#125;,
  "expected_version": "2026-04-01T00:00:00Z",
  "current_version": "2026-04-01T00:03:00Z",
  "readback_required": true,
  "writeback_guard_state": "pending_confirmation",
  "workflow_state": "verification_required",
  "external_truth_state": "verification_required",
  "consumer_remediation_actions": ["refresh_metadata", "retry_writeback", "open_diff_and_resolve", "mark_verification_complete", "escalate_to_manual"]
&#125;

reviewer mutations on Gitea PRs are now fail-closed against the target repo's AGENTS.md review authority truth:
- explicit Review identities entries are used when present
- otherwise Owner-Agent plus Supporting agents are used as the fallback allow-set
- Owner-Agent, Supporting agents, and Review identities only consume their immediately attached indented list items; later unrelated nested bullets do not expand the allow-set
- only Gitea users that actually exist, are active, and are not login-blocked remain eligible
- a reviewer outside that repo-owned active allow-set returns 409 reviewer_policy_blocked and no provider mutation is applied
example delivery health summary response:

&#123;
  "failing_pipelines": 1,
  "failed_deployments": 1,
  "active_environments": 2,
  "releases_needing_attention": 1,
  "latest_pipeline_green": false,
  "deployment_healthy": false,
  "risky_reviews_unresolved": true,
  "open_handoffs": 1,
  "doctor_errors": 0
&#125;

Integrations

/api/v1/projects/{project_id}/integrations/gitea/*
/api/v1/projects/{project_id}/integrations/github/*
/api/v1/projects/{project_id}/integrations/gitlab/*
/api/v1/projects/{project_id}/integrations/plane*
/api/v1/projects/{project_id}/integrations/n8n-expert*
/api/v1/projects/{project_id}/integrations/n8n-operator*
auth:
- operator session plus configured provider/integration credentials
stability:
- mixed active/internal
example request:

POST /api/v1/projects/ops-signal-orchestra/integrations/plane/sync HTTP/1.1
Cookie: pm_session=&lt;session&gt;

example response shape:

&#123;
  "project_id": "ops-signal-orchestra",
  "sync_mode": "auto",
  "result": "ok"
&#125;

Plane sync response notes:

repo_task_issue_sync_results lists successful follow-up repository issue mirror writes triggered after Plane sync.
repo_task_issue_sync_errors lists fail-visible repository follow-up failures. Plane updates that were already pulled into Mission Control remain visible instead of being hidden behind an unhandled repo writeback exception. Operators should retry repository task issue sync after fixing provider credentials or availability.

Adapter Sandbox Writes

/api/v1/projects/{project_id}/adapter-sandbox/writes
/api/v1/projects/{project_id}/adapter-sandbox/writes/{scenario}/{idempotency_key}
auth:
- admin operator session
stability:
- active (sandbox-only contract)
safety posture:
- fail-closed unless ADAPTER_SANDBOX_WRITE_ENABLED=true
- fail-closed unless project_id matches ADAPTER_SANDBOX_PROJECT_PREFIX (default sandbox-)
- owner repo must be JaddaHelpifyr/jhf-pattern
supported scenarios:
- project
- support
- qa
- release
write contract guarantees:
- idempotency by (project_id, scenario, idempotency_key)
- bounded retry + timeout contract
- readback payload with target key and target summary
- evidence payload with operator action reference
handoff-aware write contract:
- optional handoff_context for project/support scenarios
- handoff_context.handoff_id must exist in the same project
- handoff task/agent mismatch returns 409 and no mutation
- response carries:
  - handoff_context
  - readback.target_summary.handoff_context
  - evidence.handoff
example request:

POST /api/v1/projects/sandbox-acp-write/adapter-sandbox/writes HTTP/1.1
Cookie: pm_session=&lt;session&gt;
Content-Type: application/json

&#123;
  "scenario": "project",
  "idempotency_key": "sandbox-write-001",
  "timeout_ms": 1500,
  "retry": &#123; "max_attempts": 2, "backoff_ms": 0 &#125;,
  "owner_attribution": &#123;
    "owner_repo": "JaddaHelpifyr/jhf-pattern",
    "owner_actor": "sandbox-admin",
    "owner_reason": "acp_w3_sandbox"
  &#125;,
  "handoff_context": &#123;
    "handoff_id": "H-ADAPTER-001",
    "task_key": "SBX-PROJ-001",
    "from_agent": "agent-main",
    "to_agent": "agent-support"
  &#125;,
  "operation": &#123;
    "task_key": "SBX-PROJ-001",
    "title": "Sandbox project write",
    "lane": "backlog",
    "status": "open"
  &#125;
&#125;

example response shape:

&#123;
  "scenario": "project",
  "idempotency_key": "sandbox-write-001",
  "status": "applied",
  "idempotent_replay": false,
  "attempts": 1,
  "timeout_ms": 1500,
  "owner_attribution": &#123;
    "owner_repo": "JaddaHelpifyr/jhf-pattern",
    "owner_actor": "sandbox-admin",
    "owner_reason": "acp_w3_sandbox"
  &#125;,
  "handoff_context": &#123;
    "handoff_id": "H-ADAPTER-001",
    "task_key": "SBX-PROJ-001",
    "from_agent": "agent-main",
    "to_agent": "agent-support",
    "status": "open",
    "ownership_link_state": "linked"
  &#125;,
  "readback": &#123;
    "target_type": "task",
    "target_key": "SBX-PROJ-001",
    "target_summary": &#123;
      "task_key": "SBX-PROJ-001",
      "lane": "backlog",
      "status": "open",
      "handoff_context": &#123;
        "handoff_id": "H-ADAPTER-001",
        "task_key": "SBX-PROJ-001",
        "from_agent": "agent-main",
        "to_agent": "agent-support",
        "status": "open",
        "ownership_link_state": "linked"
      &#125;
    &#125;
  &#125;,
  "evidence": &#123;
    "event": "adapter_sandbox_write_applied",
    "project_id": "sandbox-acp-write",
    "handoff": &#123;
      "handoff_id": "H-ADAPTER-001",
      "task_key": "SBX-PROJ-001",
      "from_agent": "agent-main",
      "to_agent": "agent-support",
      "status": "open",
      "ownership_link_state": "linked"
    &#125;
  &#125;
&#125;

inbound webhook auth contract:
- Plane webhook:
  - route: /api/v1/projects/{project_id}/integrations/plane/webhook
  - preferred secret header: X-Plane-Webhook-Secret
  - compatibility inputs still accepted: X-Webhook-Secret, query secret
  - failure status when configured secret mismatches: 403
- ClawLedger approval callbacks:
  - routes:
    - canonical spindle pending read:
      - GET /api/approvals/jhf-spindle/pending
    - canonical spindle sync writeback:
      - POST /api/approvals/jhf-spindle/sync
    - legacy clawledger approval contract:
      - POST /api/approvals/clawledger
      - GET /api/approvals/clawledger/pending
      - POST /api/approvals/clawledger/sync
      - POST /api/approvals/clawledger/{project_id}/{task_key}/decision
      - POST /api/approvals/clawledger/decision
    - compatibility aliases:
      - GET /api/v1/approvals/jhf-spindle/pending
      - GET /api/v1/approvals/clawledger/pending
  - required header when configured: X-ClawLedger-Token
  - failure status when configured secret mismatches: 401
  - dedicated approval workspace rule:
    - when CLAWLEDGER_APPROVAL_PROJECT_ID points at a dedicated queue such as clawledger-approvals, the inbound hook normalizes that project into a ClawLedger-only review workspace
    - imported sample/bootstrap tasks and sample source metadata are removed instead of being preserved beside live approval packets

Spindle Pending Approvals

canonical route:
- GET /api/approvals/jhf-spindle/pending
canonical sync route:
- POST /api/approvals/jhf-spindle/sync
legacy aliases:
- GET /api/approvals/clawledger/pending
- GET /api/v1/approvals/jhf-spindle/pending
- GET /api/v1/approvals/clawledger/pending
auth:
- header X-ClawLedger-Token when CLAWLEDGER_APPROVAL_SHARED_SECRET is configured
- no cookie or operator session required for the inbound consumer path
query params:
- project_id optional
- limit optional, default 50, range 1-200
response fields per item:
- project_id
- task_key
- packet_id
- packet_name
- packet_type
- company
- risk_level
- target_doctype
- target_name
- lane
- status
- callback_url
- created_at
- updated_at
callback token handling:
- approval callback tokens remain internal task metadata for outbound decision writeback only
- API and mirror/readback surfaces redact metadata_json.callback.token
- outward task truth may expose metadata_json.callback.token_redacted=true together with non-secret callback fields such as url and method
error codes:
- 200 pending approvals returned
- 401 shared secret configured and header mismatch
- 422 invalid query parameter shape

Auth

/api/v1/auth/me
/api/v1/auth/dev-login
/api/v1/auth/logout
/api/v1/auth/gitea/*
/api/v1/auth/github/*
/api/v1/auth/gitlab/*
/api/v1/auth/oidc/*
auth:
- none for callback entry, operator/session/config dependent elsewhere
stability:
- internal
/api/v1/auth/oidc/status
- returns the configured OIDC issuer, canonical client id, redirect URI, scopes, and discovered authorization endpoint used by Mission Control

Recovery / Operations

/api/v1/projects/{project_id}/freeze
/api/v1/projects/{project_id}/unfreeze
/api/v1/projects/{project_id}/snapshots
/api/v1/projects/{project_id}/restore
/api/v1/projects/{project_id}/audit
auth:
- operator session
stability:
- active

Auth

default write/read product access:
- operator session cookie
development-only path:
- dev login when enabled
callback/webhook surfaces:
- integration-specific secrets

Versioning

product API prefix:
- /api/v1
no stronger public semver guarantee is claimed for the full REST surface
breaking product contract changes should be documented in:
- CHANGELOG.md
- docs/INTEGRATIONS.md
- docs/FABRIC_TOOL_PROFILE.md

Examples

curl http://&lt;internal-runtime-redacted&gt;:18081/healthz
curl http://&lt;internal-runtime-redacted&gt;:18081/versionz
curl http://&lt;internal-runtime-redacted&gt;:18081/contractz
curl http://&lt;internal-runtime-redacted&gt;:18081/fabric-manifest.json

For schema detail, use /openapi.json.

License: AGPLv3

Helpifyr: https://helpifyr.com

API

Runtime Entry Surfaces​

Read-only service contract​

API Prefix​

Frontend Backend Boundary​

Router CI Coverage​

Fabric Pull Publications​

Core Product Groups​

Projects​

Tasks and Lanes​

Support Orchestration Materialization​

Meeting Room Materialization​

Auth / App Login​

Reed Owner Facts​

Agents and Handoffs​

Planning​

Delivery​

Integrations​

Adapter Sandbox Writes​

Spindle Pending Approvals​

Auth​

Recovery / Operations​

Auth​

Versioning​

Examples​

Runtime Entry Surfaces

Read-only service contract

API Prefix

Frontend Backend Boundary

Router CI Coverage

Fabric Pull Publications

Core Product Groups

Projects

Tasks and Lanes

Support Orchestration Materialization

Meeting Room Materialization

Auth / App Login

Reed Owner Facts

Agents and Handoffs

Planning

Delivery

Integrations

Adapter Sandbox Writes

Spindle Pending Approvals

Auth

Recovery / Operations

Auth

Versioning

Examples