Skip to main content

Helpifyr Fabric Project Plan

Documentation Map​

Helpifyr Fabric Project Plan

Summary​

This document is the canonical production-readiness plan for helpifyr-fabric.

helpifyr-fabric already has a strong foundation:

  • dedicated Docker stack on <internal-runtime-redacted>
  • minimal FastAPI control-plane service
  • read-only OpenClaw provider discovery
  • fixture-first n8n-operator topology-sync contract surfaces
  • read-only product adapter baselines for ClawLedger and Mission Control

It is not production-ready yet.

The remaining work is concentrated in turning the current foundation into a real control plane with:

  • durable state
  • real eventing
  • real product contracts
  • safe runtime mutation
  • governance and operator safety
  • full end-to-end verification

Delivery Principles​

  • Gitea is the source of truth for verified progress.
  • Slices must remain issue-sized, testable, and directly pushable.
  • Dapr is middleware plumbing, not the owner of domain logic.
  • JetStream is the durable async backbone.
  • MCP is an access layer, not the system of record.
  • OpenClaw remains provider 1, not the permanently hardcoded center.
  • Other repositories may be inspected for contract alignment, but not modified from this program.

Current State​

Completed baseline slices​

  • HF-001 Foundation bootstrap
  • HF-002 Host stack bring-up
  • HF-003 OpenClaw provider read-only contract
  • HF-004 n8n-operator topology-sync contract baseline
  • HF-005 ClawLedger setup-profile baseline
  • HF-006 Mission Control operator-summary baseline

Current in-progress slice​

  • HF-007 oc-agent-manager runtime-inventory baseline

Gaps remaining before production readiness​

  • no durable operational state model for graph revisions, syncs, rollouts, drift, or audit
  • no migration-owned persistence bootstrap
  • Dapr and JetStream are present in the stack but not yet active application backbones
  • OpenClaw support is still mostly read-only
  • n8n-operator sync is still preview/export/fixture-first
  • ClawLedger and Mission Control product adapters are still read-only
  • no real MCP surface backed by the API
  • governance, auth, secrets, and audit safety are still incomplete
  • no final production operations and signoff queue has been executed

Production-Ready Queue​

Phase 1 - Finish the baseline adapter layer​

HF-007 oc-agent-manager runtime-inventory baseline​

Goal:

  • expose the first read-only Fabric-owned runtime-inventory summary for oc-agent-manager
  • keep the slice read-only and non-conflicting with oc-agent-manager ownership

Exit signal:

  • stable endpoint, typed response, tests, and host verification are green

HF-008 API contract normalization and OpenAPI baseline​

Goal:

  • normalize all existing Fabric routes under a clear canonical v1 contract
  • add missing typed response models for current provider and product surfaces
  • add explicit OpenAPI/schema export and route-level contract verification

Exit signal:

  • current API is typed, versioned, and contract-tested

Phase 2 - Durable control-plane state​

HF-009 persistence layer and migrations​

Goal:

  • add real persistence for graph revisions, sync history, rollout history, drift snapshots, audit events, and product requests
  • introduce migration ownership and startup-safe schema bootstrap

Exit signal:

  • Fabric no longer depends on static or generated-only state for core history

HF-010 Dapr-backed invocation and state usage​

Goal:

  • wire real Dapr invocation and state usage into the application where the architecture intends it
  • keep domain decisions inside Fabric services

Current verified status:

  • the Fabric now exposes host-verified Dapr runtime, state-probe, invocation-probe, contract, dashboard, and integration-readiness surfaces as the current middleware integration baseline
  • the current operations entrypoint for this baseline is documented in docs/operations/DAPR_BASELINE_RUNBOOK.md and docs/operations/DAPR_BASELINE_VERIFICATION.md
  • this baseline is now cross-linked consistently across the README, architecture notes, project plan, and operations docs
  • the direct issue-owned handoff note for this baseline is docs/issues/HF-010-dapr-backed-invocation-and-state-usage.md
  • this issue-owned handoff path is now mirrored repo-wide and pinned by repo tests as the shared status path for the current middleware baseline
  • the middleware baseline is now documented end-to-end as a repo-wide handoff path for the next HF-010 integration layer
  • this stable documentation layer is now the documented transition point into the next concrete HF-010 integration slice
  • this explicit start marker is now mirrored identically across the complete HF-010 documentation path

Exit signal:

  • Dapr is used intentionally by the app, not only shipped in Docker

HF-011 JetStream outbox and event publishing​

Goal:

  • implement the documented event/outbox pipeline for topology, rollout, sync, drift, approval, and residual-risk events

Exit signal:

  • Fabric events are durably recorded and publishable through the intended backbone

Phase 3 - OpenClaw provider from read-only to safe control​

HF-012 OpenClaw runtime adapter hardening​

Goal:

  • harden runtime identity, capability, topology, SSH-mode, and config-path handling

Exit signal:

  • runtime discovery is stable, version-aware, and safe across supported modes

HF-013 topology diff and patch planning​

Goal:

  • implement desired-vs-actual graph diffing and deterministic dry-run patch plans

Exit signal:

  • planning works from real runtime inputs with explicit risk semantics

HF-014 safe apply, reload, verify, and rollback evidence​

Goal:

  • add backup, write, reload, verify, and rollback-aware apply flow for OpenClaw

Exit signal:

  • Fabric can safely reconcile runtime state on the documented host path with audit evidence

HF-015 drift and rollout surfaces​

Goal:

  • expose real drift summaries, rollout history, and rollout audit endpoints

Exit signal:

  • operator consumers can rely on dedicated drift and rollout surfaces

Phase 4 - Real product adapters for the starting systems​

HF-016 ClawLedger setup-request contract​

Goal:

  • replace the read-only profile-only baseline with a real Fabric-owned setup-request contract for ClawLedger

Exit signal:

  • ClawLedger has a consumer-ready setup contract with recommended team and verification guidance

HF-017 Mission Control setup, topology diff, and rollout summary contract​

Goal:

  • add the real Mission Control-facing setup, topology-summary, drift-summary, and rollout-summary surfaces

Exit signal:

  • Mission Control can consume Fabric as its operator control plane

HF-018 n8n-operator real topology-sync delivery​

Goal:

  • upgrade the preview/export contract into a real persisted downstream sync pipeline

Exit signal:

  • Fabric owns topology intent and n8n-operator can consume it concretely

HF-019 oc-agent-manager compatibility and migration shim​

Goal:

  • define how oc-agent-manager coexists with or hands off to Fabric without duplicate orchestration logic

Exit signal:

  • the current starting-systems story is coherent and explicitly documented

HF-020 openclaw-mem0-localai-kit capability adapter​

Goal:

  • add optional memory-capability metadata handling

Exit signal:

  • memory capability is representable without becoming a hard dependency

Phase 5 - MCP, governance, and production safety​

HF-021 MCP read tools​

Goal:

  • add MCP read tools backed strictly by the API

Exit signal:

  • MCP exposes read-only topology, drift, rollout, and product views without duplicating logic

HF-022 MCP safe action tools​

Goal:

  • add guarded MCP mutation tools for plan/apply/sync flows with audit preservation

Exit signal:

  • guarded actions remain traceable and policy-checked

HF-023 governance packs and gates​

Goal:

  • turn governance models into real policy packs, review gates, escalation hooks, and residual-risk records

Exit signal:

  • risky changes can be routed through explicit control points

HF-024 auth, secrets, and operator safety​

Goal:

  • add API auth, secret sourcing, redaction, and operator-safe rate-limited behavior

Exit signal:

  • production use no longer depends on open or weak internal assumptions

Phase 6 - Production operations and signoff​

HF-025 observability, readiness, and runbook hardening​

Goal:

  • add structured logs, metrics-ready hooks, clearer readiness/health surfaces, and stronger operator runbooks

Exit signal:

  • operators can safely observe and diagnose the stack

HF-026 backup, restore, and stack hardening​

Goal:

  • harden Postgres, NATS, Dapr, and Fabric deployment posture, backup, and restore expectations

Exit signal:

  • the Fabric stack is operationally recoverable

HF-027 end-to-end integration and production signoff​

Goal:

  • run full local, host-adjacent, and contract-level verification
  • include read-only interface checks against ClawLedger, n8n-operator, Mission Control, and oc-agent-manager
  • document interface suggestions in the Fabric repo only

Exit signal:

  • all production gates are satisfied and evidence is committed

Production Gates​

helpifyr-fabric is production-ready only when all of the following are true:

  • Fabric owns durable state for sync, graph, rollout, drift, and audit
  • Dapr and JetStream are actively used by the application, not just present in Docker
  • OpenClaw provider supports safe plan/apply/verify with rollback evidence
  • n8n-operator sync is real, persisted, and delivery-evidenced
  • ClawLedger and Mission Control have real Fabric consumer contracts
  • MCP read and safe-action layers are live and API-backed
  • governance gates, auth, secrets, and audit safety are in place
  • host stack, backup/restore, and runbooks are production-credible
  • end-to-end verification on <internal-runtime-redacted> is green

License​