Skip to main content

Overview

Tool / Contract Summary​

jhf-beam is the Helpifyr safety, upgrade, rollback, and verification repository. It is not a product runtime service and not a Fabric runtime member. It owns verification contracts, evidence contracts, and operational governance for issue-driven certification waves.

When To Use Beam​

Use Beam when a change wave needs independent certification, rollback posture, evidence integrity, or staged upgrade verification across owner repositories. Beam is the right module when the question is whether a change is safe, repeatable, and sufficiently evidenced, not when the question is where runtime or business truth lives.

What Beam Owns​

  • Certification standards, promotion contracts, and verification wave structure.
  • Repo-owned evidence, verdict, lock, and maintenance governance contracts.
  • Read-only validation of upstream truth surfaces needed for safety and certification decisions.

What Beam Does Not Own​

  • Runtime truth for product services or shared hosts.
  • Fabric contract authoring or canonical business/domain truth.
  • Deployment orchestration truth for foreign repositories.
  • Public docs publishing or downstream materialization ownership.

Business Value​

  • Turns change risk into explicit, auditable evidence.
  • Keeps runtime truth with owner repos while Beam provides independent safety validation.
  • Standardizes full validation, bulletproof rerun, upgrade certification, and monitoring-trigger certification waves.
  • Preserves the shared-service-boundary so shared context does not silently become tool-owned runtime or storage truth.

Current Verified State​

  • Implemented OpenClaw path: 2026.3.13 -> 2026.3.24 with reproducible evidence and compatibility export.
  • Generic upgrade-suite structure is present and schema/policy verifiable.
  • Fabric combination and contract-family truth is consumed read-only and validated in repo and live-readback modes.
  • Stage-3 promotion bridge, lock evidence, idempotency guards, and host-readback paths are implemented.

Available now​

  • Installation and configuration docs for the v1.6 docs platform baseline.
  • Certification standards under docs/testing/.
  • Machine-readable contracts under maintenance/ and schemas/.
  • Verification scripts under maintenance/, ops/host/, and scripts/testing/.
  • Packaging contracts and reproducible source-bundle build/publish scripts.

Optional / Extended​

  • External-installation baseline (preflight/postflight/supportability/package policy) via docs/testing/ and maintenance artifacts.
  • Host timer and artifact sync operations for bounded maintenance tasks.

Planned / Not in current scope​

  • No Beam-owned runtime API service.
  • No Beam-owned deployment control plane.
  • No local second source of truth for Fabric contract families or bundle detection.
  • jhf-beam-light consumption path is prepared but remains planned.

Public Surfaces​

  • Repo artifacts:
    • README.md
    • docs/INSTALL.md
    • docs/CONFIGURATION.md
    • docs/TROUBLESHOOTING.md
    • docs/RELEASE_NOTES.md
    • docs/CAPABILITIES.md
    • maintenance/*.json
    • upgrade-runs/
  • Read-only external surfaces:
    • GET /api/v1/combinations/profiles
    • GET /api/v1/contracts/matrix
    • GET /api/v1/contracts/docs-standard
    • GET /api/v1/voice/contracts/events

Contract Families​

  • upgrade-suite contracts
  • promotion/live-feedback contracts
  • Fabric docs-standard and voice-events consumer contracts

Producer-/Consumer-Zuordnung​

  • Producer: helpifyr-fabric (contract/bundle truth)
  • Producer: jhf-deployment (stage-2 promotion payload/evidence)
  • Consumer/validator: jhf-beam

Compatibility Window​

  • maintenance/compatibility-windows.json
  • maintenance/latest-known-good.json

Lifecycle Status​

  • Stable: repository governance and verification model.
  • Transitional: external-installation packaging/distribution depth.

Readiness / Drift / Monitoring​

  • Inventory and drift generation:
    • maintenance/pull_oss_inventory.py
    • maintenance/runtime-drift-*.json
  • Readiness verification:
    • maintenance/verify-upgrade-suite.py
    • maintenance/verify-fabric-combination-safety.py
    • maintenance/verify-voice-governance.py

Deployment / Verify​

  • Stage 1: repo-level verify
  • Stage 2: deployment-owned staging verification
  • Stage 3: Beam host-bound live verify and issue feedback publish

How To Verify The Current Repo-Owned Source Truth​

  • python3 maintenance/verify-docs-inventory-adoption.py
  • python3 maintenance/verify-maintenance-contracts.py
  • python3 maintenance/verify-beam-terminology.py
  • python <local-workspace-redacted>/helpifyr-fabric/scripts/docs/validate_repo_docs_skeleton.py --repo <local-workspace-redacted>/_worktrees/jhf-beam/234-wave6-public-docs-source-curation

These checks validate the current public-safe source docs and Beam-owned governance surfaces without claiming ownership over live runtime behavior in other repositories.

Known Limits​

  • No Beam-owned service runtime to monitor directly.
  • No write-back to Fabric truth surfaces.
  • Multi-tool deep execution coverage is partial and owner-dependent.

Exceptions / Waivers​

  • Exceptions are issue-driven and must be explicitly referenced in run evidence or maintenance artifacts.
  • jhf-beam#89
  • jhf-beam#119
  • jhf-beam#120
  • jhf-beam#126
  • jhf-beam#138

License​

AGPLv3. See ../LICENSE (LICENSE).

Learn more at helpifyr.com.