Metadata-Version: 2.4
Name: unuforge
Version: 0.4.0
Summary: Shared preset-backed automation core for the unu product family
Requires-Python: >=3.11
Description-Content-Type: text/markdown

# 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/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`](https://github.com/unundoTeam/unuos/blob/main/docs/portfolio/README.md)
  for portfolio overview and cross-repo authority
- [the sibling `unuOS` repo's design foundation contract](https://github.com/unundoTeam/unuos/blob/main/docs/portfolio/design-foundation-contract.md)
  and [common component contract](https://github.com/unundoTeam/unuos/blob/main/docs/portfolio/common-component-contract.md)
  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](docs/release-policy.md). The practical
per-PR checklist lives in
[docs/manual-merge-gate-checklist.md](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](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
