unuforge 0.4.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/maintainer-status.md for the current maintainer-facing repo and rollout snapshot
• docs/manual-merge-gate-checklist.md for the maintainer merge checklist used while branch protection is unavailable
• docs/consumer-contract.md for the downstream consumer template and official sample consumer contract
• docs/portfolio-adoption.md for the current downstream rollout state
• docs/installed-package-coverage.md for the installed-package gate coverage ledger and deferred machine-surface boundaries
• fixtures/presets/v2-sample.json for the checked-in sample preset contract
• the sibling unuOS repo's docs/portfolio/README.md for portfolio overview and cross-repo authority
• the sibling unuOS repo's design foundation contract and common component contract for the future user-facing UI baseline; this repo has no managed product UI adoption requirement today

Design Authority

• First design read: /Users/yuchen/Code/unu/unuOS/docs/portfolio/design-operating-index.md; it is the only first-read design authority.
• Current design status: pending.
• Small UI copy or polish uses the Lightweight UI Path in the portfolio Pencil gate.
• Historical design specs are planning context only unless the operating index or this repo-local entrypoint explicitly routes to them.
• The legacy positioning spec named above is routed only through /Users/yuchen/Code/unu/unuOS/docs/portfolio/design-specs-inventory.md as current-routed positioning and admission guardrail context; it is not active Pencil or current UI authority.
• Register a current/draft pair only if this repo adds user-facing UI; no placeholder design-system frame is required for the current automation core.

Release and downstream-consumer routing should stay in the docs above rather than becoming extra top-level README sections.

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.4.0-py3-none-any.whl
  • unuforge --help
• official external install contract:
  • python3 -m pip install unuforge==0.4.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

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 heavy verification:
  • python3 scripts/verify_consumer_contracts.py --consumer all
  • by default this expects sibling checkouts at ../unudispatch, ../unuidentity, and ../unuvault
  • if your local layout differs, set UNUDISPATCH_REPO_ROOT and UNUIDENTITY_REPO_ROOT, and UNUVAULT_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.

If the GitHub-hosted runner is unavailable because of account billing or spending-limit control-plane state, the hosted run is not code-failure evidence, but it is also not green evidence. The non-payment path is the local maintainer gate: run current-head test and consumer-contract equivalents locally, then record the exact status github-hosted runner unavailable; local maintainer gate used with the local commands in the maintainer fallback note.

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. The practical per-PR checklist lives in docs/manual-merge-gate-checklist.md.

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
• the High-Risk PR Review workflow classifies whether a PR touches the repo-local high-risk scope before merge

Agent-led delivery status, review-status reporting, commit closeout, push, and cleanup defaults follow the portfolio delivery authority in /Users/yuchen/Code/unu/unuOS/docs/portfolio/agent-delivery-defaults.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 has current-head pass evidence from hosted checks or the local maintainer gate
• consumer-contract has current-head pass evidence from hosted checks or the local maintainer gate
• 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

The maintainer should be able to identify the reviewed head commit and confirm that test and consumer-contract are green or locally passed on that same commit.

The PR handoff should make three evidence shapes explicit:

• current head commit evidence with reviewed head commit and checks verified on that commit
• secret-sensitive consumer-contract evidence with consumer-contract path status and maintainer fallback note
• a release-sensitive technical review conclusion with release-sensitive or machine-facing change, downstream contract surface changed or unchanged, evidence used, and why merge is still safe

Use the exact PR-template values so the handoff stays machine-readable:

• reviewed head commit: current PR head SHA or matching prefix, minimum 7 hexadecimal characters
• checks verified on that commit: must explicitly include both test and consumer-contract; hosted checks must be green on that same commit, or the local maintainer gate must have passed on that same commit when the GitHub-hosted runner was unavailable
• consumer-contract path status: exactly ran real secret-available path, maintainer-confirmed fallback, or github-hosted runner unavailable; local maintainer gate used
• maintainer fallback note: n/a for the real path, or a short maintainer confirmation note when a fallback or local maintainer gate was required
• release-sensitive or machine-facing change: exactly yes or no
• if the answer is no, the remaining technical conclusion fields should all be not applicable
• if the answer is yes, the remaining technical conclusion fields should all explain downstream contract impact, the evidence used, and why merge is still safe

A non-blocking manual-merge-gate-advisory workflow now runs python3 scripts/check_manual_merge_gate.py --event-json "$GITHUB_EVENT_PATH" on PR updates to catch stale or incomplete evidence shells early. It does not replace maintainer judgment, and it does not replace live CI review.

The High-Risk PR Review workflow runs python3 scripts/check_high_risk_pr_review.py on PR updates. It classifies changes that touch CLI behavior, preset loading, host-adapter dispatch, distribution behavior, consumer-contract shape, installed-package gate wiring, or release workflow logic. Record its high-risk review status in the PR handoff as completed or not_applicable; it does not replace maintainer judgment or the manual merge gate.

If the real secret-available path did not run, do not treat the change as equivalent to a normal green maintainer-branch run until a maintainer-confirmed fallback or github-hosted runner unavailable; local maintainer gate used status is recorded with the maintainer note.

Do not merge when any required check is red, missing, stale, or still running. The only documented no-payment exception is a hosted job that did not start because the GitHub-hosted runner was unavailable due to billing or spending-limit control-plane state; that exception still requires local current-head test and consumer-contract evidence before merge. Use docs/manual-merge-gate-checklist.md as the maintainer operating sheet for applying this gate on a live PR.

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
• the next maintenance should strengthen governance mechanics and deeper installed-package surface coverage rather than reopening core distribution capability work
• downstream-upgrade automation and a calendar-based release cadence remain deferred follow-up governance work while the current thin-core release contract stays stable