unuforge 0.3.0

Shared preset-backed automation core for the unu product family

unuforge

Shared preset-backed automation core for the unu product family.

What This Repo Owns

• preset schema and normalization
• the machine-facing CLI
• profile and action dispatch contracts
• host-adapter integration boundaries

What It Does Not Own

• product-specific manifests and release scripts
• product-specific business-domain logic
• host repository runtime internals
• portfolio governance responsibilities owned by unuOS

For repo-local positioning and admission rules, see docs/superpowers/specs/2026-03-20-unuforge-positioning-guardrails-design.md.

Source Of Truth

• this README for contributor-facing repo overview and verification entrypoints
• docs/releasing.md for maintainer release and publishing requirements
• docs/release-policy.md for maintainer versioning, manual merge gate, and upgrade-notice policy
• docs/consumer-contract.md for the downstream consumer template and official sample consumer contract
• docs/portfolio-adoption.md for the current downstream rollout state
• fixtures/presets/v2-sample.json for the checked-in sample preset contract

Workspace Layout

• src/unuforge/ - CLI, runtime dispatch, host-adapter, and preset logic
• tests/ - unit, distribution, and stub-host contract tests
• fixtures/presets/ - sample preset fixtures used by verification commands
• scripts/ - local distribution build helpers
• docs/ - release notes and design / implementation history

Human Entrypoints

• source-based local verification:
  • PYTHONPATH=src python3 -m unittest discover -s tests
• local CLI inspection:
  • PYTHONPATH=src python3 -m unuforge.cli --help
• local artifact build:
  • python3 scripts/build_distribution.py --out-dir dist --json
• optional installed-artifact check:
  • python3 -m pip install dist/unuforge-0.3.0-py3-none-any.whl
  • unuforge --help

Published Release Contract

• official external install contract:
  • python3 -m pip install unuforge==0.3.0
  • unuforge --help
• contributors should continue to use source-based execution from the repo checkout
• GitHub Releases remain the tagged source record with built artifacts attached

Machine Entrypoints

• current machine-facing contract example:
  • PYTHONPATH=src python3 -m unuforge.cli preset inspect --preset fixtures/presets/v2-sample.json --json
• additional machine-entrypoint examples:
  • PYTHONPATH=src python3 -m unuforge.cli profiles list --preset fixtures/presets/v2-sample.json --json
  • PYTHONPATH=src:tests python3 -m unuforge.cli profiles run sample.profile --preset fixtures/presets/v2-sample.json --host-adapter stub_host --dry-run --json -- --flag
  • PYTHONPATH=src:tests python3 -m unuforge.cli actions run promote --preset fixtures/presets/v2-sample.json --host-adapter stub_host --dry-run --json -- --with-web

Release Overview

Contributors should continue to use source-based execution from the repository checkout. The published PyPI version is the supported interface for external consumers, and GitHub Releases are the tagged source record with the built artifacts attached for that release.

Maintainer release steps and publishing requirements live in docs/releasing.md. The maintainer-facing versioning, manual merge gate, and upgrade-notice policy live in docs/release-policy.md. The downstream consumer template and official sample consumer contract live in docs/consumer-contract.md, and the current portfolio rollout state lives in docs/portfolio-adoption.md.

Verification

• Gate level: L2
• Minimum local verification:
  • PYTHONPATH=src python3 -m unittest discover -s tests
• Standard pre-merge verification:
  • PYTHONPATH=src python3 -m unittest discover -s tests
  • PYTHONPATH=src python3 -m unittest tests.test_distribution -v
  • python3 scripts/build_distribution.py --out-dir dist --json
  • PYTHONPATH=src python3 -m unuforge.cli preset inspect --preset fixtures/presets/v2-sample.json --json
  • PYTHONPATH=src python3 -m unuforge.cli profiles list --preset fixtures/presets/v2-sample.json --json
  • PYTHONPATH=src:tests python3 -m unuforge.cli profiles run sample.profile --preset fixtures/presets/v2-sample.json --host-adapter stub_host --dry-run --json -- --flag
  • PYTHONPATH=src:tests python3 -m unuforge.cli actions run promote --preset fixtures/presets/v2-sample.json --host-adapter stub_host --dry-run --json -- --with-web
• Release or consumer-contract verification:
  • python3 scripts/verify_consumer_contracts.py --consumer all
  • by default this expects sibling checkouts at ../unudispatch and ../unuidentity
  • if your local layout differs, set UNUDISPATCH_REPO_ROOT and UNUIDENTITY_REPO_ROOT

The fixture/stub-host adapter used above lives in tests/stub_host.py and exists only to validate the thin-core dispatch contract locally. The real downstream contract check is python3 scripts/verify_consumer_contracts.py --consumer all, which exercises the official unudispatch, unuidentity, and unuvault sample consumers documented in docs/consumer-contract.md. By default that script expects sibling checkouts at ../unudispatch, ../unuidentity, and ../unuvault. If your local layout differs, set UNUDISPATCH_REPO_ROOT, UNUIDENTITY_REPO_ROOT, and UNUVAULT_REPO_ROOT before running it.

GitHub Actions now runs a blocking consumer-contract job that uses the same consumer contract verification command against checked-out sample consumers. That job requires a repository secret named CROSS_REPO_READ_TOKEN with read-only access to unundoTeam/unudispatch, unundoTeam/unuidentity, and unundoTeam/unuvault.

Because this private repo cannot currently enable GitHub required checks on the active plan, merge discipline still depends on the manual maintainer gate documented in docs/release-policy.md.

Manual Merge Gate

unundoTeam/unuforge currently cannot enforce GitHub required checks through branch protection on its current plan, so main continues to use a manual merge gate.

Before merge, all of the following must be true:

• test is green
• consumer-contract is green
• the checks are for the current PR head commit
• the author has completed self-review
• changes touching CLI, preset, host-adapter, distribution, or release shape have an explicit technical review conclusion on the PR

Do not merge when any required check is red, missing, stale, or still running.

Review Model

unuforge follows the portfolio review baseline:

• approved design for behavior, contract, or release-shape changes
• author self-review
• Codex automatic review by default
• passing automation gates before merge

Human review is optional and is mainly recommended for release flow, preset schema, and host-adapter contract changes.

Cross-Repo Dependencies

• downstream product repos consume unuforge for machine-entrypoint execution
• unuOS owns the shared portfolio automation, verification, and governance contract layer around this thin core
• host repositories own execution-specific adapters while unuforge stays focused on dispatch plumbing

Current Risks / Migration Status

• Repo lifecycle: active
• Contract maturity:
  • automation contract: portfolio-standard
  • verification contract: adopted
• downstream rollout is still uneven across product repos even though unuforge now defines the canonical thin-core machine surface
• the main risk is allowing unuforge to absorb product-specific behavior or governance responsibilities that belong elsewhere
• the package install contract is now real, but contributors should still treat source-based execution from the repo checkout as the primary development path