Skip to main content

OSS Inventory, Version Truth, and Upgrade Readiness

Documentation Map​

OSS Inventory, Version Truth, and Upgrade Readiness

This page defines the repo-owned machine-readable OSS inventory and version truth for jhf-pattern.

Primary artifacts:

  • maintenance/oss-inventory.json
  • maintenance/oss-version-truth.json
  • maintenance/oss-upgrade-policy.json
  • maintenance/oss-upgrade-evidence-truth.json
  • scripts/verify_oss_inventory_version_truth.py
  • scripts/oss-inventory-selfcheck.sh
  • scripts/verify_fabric_oss_upgrade_consumer_contract.py
  • scripts/fabric-oss-upgrade-consumer-selfcheck.sh

Fabric Canonical Consumer Binding​

jhf-pattern consumes Fabric-owned OSS update/upgrade truth and must not re-interpret that truth locally.

Canonical Fabric sources for this consumer posture:

  • contracts/platform/platform_version_truth.json
  • contracts/platform/platform_projection_catalog.json
  • contracts/platform/platform_oss_upgrade_governance_v1.json
  • contracts/platform/platform_oss_upgrade_compatibility_matrix_v1.json
  • contracts/platform/platform_oss_upgrade_evidence_contract_v1.json
  • contracts/platform/helpifyr_stack_module_identity_v1.json
  • contracts/platform/stack_tool_oss_inventory_directory.json
  • docs/contracts/HELPIFYR_PLATFORM_OSS_UPGRADE_GOVERNANCE.md
  • docs/contracts/HELPIFYR_STACK_MODULE_IDENTITY.md
  • docs/contracts/HELPIFYR_STACK_TOOL_OSS_INVENTORY_DIRECTORY.md

Fail-closed consumer verify path:

  • python scripts/verify_fabric_oss_upgrade_consumer_contract.py --strict
  • bash scripts/fabric-oss-upgrade-consumer-selfcheck.sh

The verifier fails closed if required Fabric sources are missing/unreadable or if jhf-pattern consumer posture is inconsistent in Fabric module identity or stack tool directory truth.

Tool / Contract Summary​

  • Inventory and version truth are tracked as repo-owned JSON artifacts.
  • Every repo-owned component carries explicit owner-upgrade fields:
    • current_version
    • target_version
    • allowed_version_range
    • pinning_posture
    • compatibility_window_ref
    • preflight_assertion_refs
    • postdeploy_assertion_refs
    • rollback_contract_ref
    • evidence_contract_ref
  • Drift verification is fail-closed for:
    • runtime/base images using latest or floating major tags
    • CI action refs that are only major tags
    • non-exact direct Python and Node dependency pins
    • missing required external owner blocker references
    • missing owner-upgrade field model on repo-owned components
    • missing or incomplete evidence/rollback truth

Business Value​

  • Removes silent dependency drift in runtime, base images, and CI actions.
  • Makes upgrade ownership explicit for repo-owned and external-owner surfaces.
  • Provides deterministic verify paths for CI and local pre-push checks.

Current Verified State​

  • Runtime/base image refs are exact-tag pinned in repo-owned files.
  • CI action refs are semver-tag pinned.
  • Direct Python and Node dependencies are exact pinned.
  • External owner blockers are classified explicitly, not mirrored as local truth.
  • Plane is explicitly classified as an external-owner OSS/runtime dependency in maintenance/oss-inventory.json (component_key: external.plane).

Available now​

  • Machine-readable inventory (maintenance/oss-inventory.json).
  • Machine-readable version truth (maintenance/oss-version-truth.json).
  • Upgrade policy and fail conditions (maintenance/oss-upgrade-policy.json).
  • Upgrade evidence and rollback posture (maintenance/oss-upgrade-evidence-truth.json).
  • Strict verifier (python scripts/verify_oss_inventory_version_truth.py --strict).
  • Shell selfcheck (bash scripts/oss-inventory-selfcheck.sh).

Planned / Not in current scope​

  • Stack-global OSS arbitration remains outside this repo.
  • Plane runtime/version ownership is external to jhf-pattern; this repo integrates Plane and documents the boundary but does not define Plane release truth or pin Plane runtime versions stack-wide.
  • This repo does not redefine owner truth in:
    • helpifyr-fabric
    • Plane (upstream OSS)
    • jhf-openclaw-env
    • jhf-deployment
    • jhf-spindle
    • jhf-heddle
    • jhf-warp
    • jhf-keystore
    • jhf-shuttle
    • jhf-reed

Public Surfaces​

  • No new external API route is introduced by this slice.
  • Verification surfaces are repo-owned scripts and CI checks.

Producer-/Consumer-Zuordnung​

  • Producer (repo-owned truth):
    • jhf-pattern publishes inventory/version/policy JSON files.
  • Consumers:
    • local/CI verification lanes
    • operators using repository validation paths
  • External truth consumers remain explicit and referenced by owner issues only.

Lifecycle Status​

  • status: active
  • contract posture: strict verification, fail-closed drift detection

Readiness / Drift / Monitoring​

  • Use strict verifier for every upgrade/pinning mutation:
    • python scripts/verify_oss_inventory_version_truth.py --strict
  • CI lane includes inventory/version verification.

Deployment / Verify​

Repo checks:

python scripts/verify_oss_inventory_version_truth.py --strict
bash scripts/oss-inventory-selfcheck.sh
python scripts/verify_fabric_oss_upgrade_consumer_contract.py --strict
bash scripts/fabric-oss-upgrade-consumer-selfcheck.sh
python -m pytest -q tests/test_oss_inventory_version_truth.py
python -m pytest -q tests/test_release_readiness.py
python -m pytest -q tests/test_fabric_oss_upgrade_consumer_contract.py

CI checks:

  • .gitea/workflows/ci.yml executes release-readiness checks that include OSS truth artifacts and verifier presence.
  • expected green signal for this slice:
    • python -m pytest -q tests/test_release_readiness.py
    • OSS verifier path above remains green in CI-equivalent local run.

Live check (read-only evidence):

ssh <internal-runtime-redacted><internal-runtime-redacted> "docker ps --format '{{.Names}}|{{.Image}}' | grep jhf-pattern"

Issue #174 Completion Checklist​

  • OSS truth doc exists and is current: yes (docs/OSS_INVENTORY.md)
  • AGENTS hint exists and is mandatory: yes (AGENTS.md, "OSS Inventory And Version Truth Rule")
  • verify path is explicit and executable: yes (repo checks + CI checks + live read-only evidence path)
  • no local workaround for external-owner truth: yes

Known Limits​

  • This repo can verify only repo-owned references plus explicit owner issue links.
  • External owner repos may advance their own truth independently; this repo only tracks explicit blocker links and classification.
  • For Plane specifically, the inventory classification is explicit, but version pinning and runtime release ownership remain outside this repo by design.
  • jhf-pattern#174
  • jhf-pattern#176
  • helpifyr-fabric#289
  • jhf-openclaw-env#209
  • jhf-deployment#270
  • jhf-spindle#208
  • jhf-heddle#117
  • jhf-warp#257
  • jhf-keystore#82
  • jhf-shuttle#138
  • jhf-reed#13

License: AGPLv3

Helpifyr: https://helpifyr.com