Skip to main content

Overview

Tool / Contract Summary​

jhf-deployment is the deploy/verify repository for Helpifyr/OpenClaw integration and rollout checks. It codifies execution paths and evidence contracts; it does not own product-runtime semantics.

Canonical machine-readable feature truth: docs/MODULE_FEATURES.md.

When To Use Deployment​

Use jhf-deployment when the task is about rollout execution, deployment guardrails, IaC-driven environment materialization, or deployment-owned verification evidence. It is the right module for checking whether a stack slice can be created, verified, reset, or blocked safely without taking ownership of the product runtime semantics themselves.

What Deployment Owns​

  • IaC environments, lifecycle scripts, and deployment-side verify flows.
  • Deployment-owned host preflight/postdeploy guardrails and evidence contracts.
  • Read-only consumer verification for upstream Fabric, identity, and runtime-owner truth during rollout.

What Deployment Does Not Own​

  • Product-runtime semantic truth for the deployed tools.
  • Fabric semantic or governance authoring truth.
  • Secret source-of-truth lifecycle.
  • Public docs publishing or downstream docs materialization ownership.

Business Value​

  • deterministic rollout verification before promotion
  • fail-fast drift detection on shared hosts
  • explicit producer/consumer boundaries across repos

Current Verified State​

  • canonical execution lane exists in environments/test/scripts/
  • host preflight/postdeploy gates are active and issue-driven
  • Fabric contract/combinations truth is consumed read-only

Available now​

  • IaC-backed lifecycle (preflight, plan, create, verify, destroy, reset)
  • runtime drift and stack-ownership checks
  • optional-slice checks (including disabled-not-required semantics)
  • Vaultwarden write-path and projection verification
  • HERP/Swatch seed-aware sandbox profile execution gates

Optional / Extended​

  • package publish/verify lanes when credentials are present
  • expanded Terratest profiles beyond smoke
  • bounded staging skeleton in environments/hetzner-staging

Planned / Not in current scope​

  • no runtime API ownership
  • no Fabric semantic truth authoring
  • no secret-authority responsibilities

Public Surfaces​

  • script surfaces: environments/test/scripts/*.sh
  • validator surfaces: scripts/*.py, maintenance/*.py
  • evidence surfaces: test-results/*.json, *.junit.xml

Contract Families​

  • host runtime preflight/postdeploy contracts
  • stack ownership and drift contracts
  • Fabric governance/combinations contract consumption
  • optional carrier slice readiness contracts

Producer-/Consumer-Zuordnung​

  • Producer repos:
    • helpifyr-fabric (contract/combinations truth)
    • specialist runtime repos (runtime semantics)
  • Consumer/materializer:
    • jhf-deployment

Compatibility Window​

  • accepted contract families/versions are pinned in
    • maintenance/fabric-contract-consumption.json

Lifecycle Status​

  • status: active
  • operating mode: issue-driven deployment verification

Readiness / Drift / Monitoring​

  • readiness is evidence-based (script output + JSON artifacts)
  • deployment-owned drift is fail-fast
  • external drift is classified and routed via issue linkage

Deployment / Verify​

bash environments/test/scripts/preflight.sh
bash environments/test/scripts/plan.sh
bash environments/test/scripts/create.sh
bash environments/test/scripts/verify.sh

Host verification:

bash environments/test/scripts/verify-host-runtime-preflight.sh --host <internal-runtime-redacted> --output test-results/host-runtime-preflight.json
bash environments/test/scripts/verify-host-postdeploy-runtime-state.sh --host <internal-runtime-redacted> --allow-blocked --output test-results/host-postdeploy-runtime-state.json

How To Verify The Current Repo-Owned Source Truth​

python3 scripts/validate-doc-governance.py --repo-root "$(git rev-parse --show-toplevel)"
python3 scripts/export-fabric-metadata.py --check
python3 maintenance/verify-maintenance-contracts.py
python <local-workspace-redacted>/helpifyr-fabric/scripts/docs/validate_repo_docs_skeleton.py --repo <local-workspace-redacted>/_worktrees/jhf-deployment/402-wave6-public-docs-source-curation

These checks validate the current public-safe source docs, metadata posture, and required docs skeleton without claiming that foreign runtime-owner lanes are healthy.

Known Limits​

  • live verification depends on host/runtime availability and SSH access
  • external owner outages remain external blockers

Exceptions / Waivers​

  • only explicit, issue-linked, time-bounded waivers are valid
  • operational closure history: docs/issues/

License: AGPLv3 Source and governance: https://helpifyr.com

Docs Platform v1.6 Base Family​

  • README.md
  • docs/OVERVIEW.md
  • docs/INSTALL.md
  • docs/CONFIGURATION.md
  • docs/OPERATIONS.md
  • docs/TROUBLESHOOTING.md
  • docs/RELEASE_NOTES.md
  • docs_manifest.yml