# 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`](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.2.0-py3-none-any.whl`
  - `unuforge --help`

## Published Release Contract

- official external install contract:
  - `python3 -m pip install unuforge==0.2.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](docs/releasing.md). The maintainer-facing versioning,
manual merge gate, and upgrade-notice policy live in
[docs/release-policy.md](docs/release-policy.md). The downstream consumer
template and official sample consumer contract live in
[docs/consumer-contract.md](docs/consumer-contract.md), and the current
portfolio rollout state lives in
[docs/portfolio-adoption.md](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](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
