OBLITERATUS/WORKSPACE.md

# WORKSPACE.md
<!-- aiwg-managed -->
<!-- Generated structure by AIWG; operator content is protected by markers. -->

<!-- AIWG:workspace-context:start -->

## AIWG Context Graph

This file is the canonical provider-neutral home for project and operator context.
Provider startup files are generated adapters: they direct the harness here first,
then to AIWG.md for framework discovery and routing.

### Precedence

1. Provider, system, and organization instructions retain their native authority.
2. Root WORKSPACE.md supplies shared project/operator context.
3. AIWG.md supplies generated framework/discovery context.
4. Narrower linked files and provider-native subtree instructions govern their declared scope.

### Ownership

- Edit project-neutral notes only inside the protected Project Context section below.
- Keep detailed policies, runbooks, hooks, and quickrefs in linked files.
- Keep provider-only directives in `.aiwg/context/providers/`.
- Never store secrets, tokens, credentials, or machine-local sensitive values here.

### Linked Context

- [AIWG framework context](./AIWG.md)
- [AIWG project configuration](.aiwg/aiwg.config)
- [Project-local quickref](.aiwg/quickref.json) (when configured)

<!-- AIWG:workspace-context:end -->

<!-- AIWG:workspace-operator:start -->

## Project Context

OBLITERATUS is a Python research tool. The default pull-request baseline must be
CPU-safe, deterministic, and must not download models or require network,
accelerator, or remote-execution credentials.

Canonical pull-request checks:

- the exact Ruff F and actionlint command set in [.github/workflows/ci.yml](.github/workflows/ci.yml);
- the versioned core suite plus tests selected from the exact diff through
  [ci/test-risk-map.json](ci/test-risk-map.json) and
  [ci/pr-test-policy.json](ci/pr-test-policy.json);
- at least 50% changed executable-line coverage, with behavior changes required
  to exercise relevant tests rather than relying on the smoke suite alone;
- `python -m build --sdist --wheel` when package inputs change;
- `python -c 'import obliteratus; print(obliteratus.__version__)'`
- `python -m obliteratus --help`

The exhaustive gate runs for `v*` tags and explicit manual release validation,
not ordinary pull requests. It runs the full Python 3.10-3.12 suite with at least
75% repository line coverage and 60% branch coverage; exact-base touched-module
regression and 80%/75% new-module floors; 94%/84% mature CPU-scope coverage;
selective mutation at 85%; repeat and duration budgets; Windows checkpoint
contracts; packaging; and supply-chain certification.

Before a tag is created, run the BT6 release-readiness workflow against the
previous release or configured comparison base. It inventories merged behavior,
runs all locally applicable release-depth gates, and repairs coverage,
correctness, documentation, packaging, and policy gaps. After tagging, run
exact-tag release validation; pre-tag readiness is never promotion evidence.

Canonical integrations must retain a verifiable commit signature. The repository
profile permits merge integration, not GitHub rebase integration, because rebase
can recreate an audited signed head as an unsigned canonical commit. Verify the
actual `main` commit after every merge; never rewrite `main` to repair history.

Release CI creates one deterministic ZIP of the exact tested repository commit.
The ZIP is a source snapshot and release-quality marker, not an installable or
compiled distribution. Immutable CI action/tool pins are recorded in
[ci/digests.txt](ci/digests.txt).

The package job is the sole source-snapshot producer. It binds the ZIP and
CycloneDX source SBOM digests into `SHA256SUMS`, creates keyless
Sigstore-backed SLSA and SBOM attestations, and retains their bundles.
Downstream supply-chain and publication jobs must verify and reuse that exact
ZIP rather than recreating an equivalent-looking archive.

The source-to-test ownership graph is versioned in
[ci/test-risk-map.json](ci/test-risk-map.json). Coverage, JUnit, repeat, and
mutation trends are normalized into project-owned JSON and retained for 90
days. Flake history and time-bounded quarantines are governed by
[ci/test-quality-policy.json](ci/test-quality-policy.json); a test observed
flaking twice in 30 days requires an active owner/issue-linked quarantine.

Python CI resolution is locked by `uv.lock`, including the official CPU-only
PyTorch source for Linux and Windows. The required Supply chain job scans all
supported Python versions for known vulnerabilities, scans the checkout for
secrets with fully redacted evidence, enforces the dependency license allow
list, and binds a CycloneDX source SBOM to the repository ZIP. Exception and update
rules are documented in [docs/SUPPLY_CHAIN_POLICY.md](docs/SUPPLY_CHAIN_POLICY.md).

GPU, MPS, MLX, model-download, external-evaluation, network, operator-UI, and
remote-execution checks are conditional release or risk-surface gates, not part
of the default CPU job.

Use [.aiwg/bt6-maintainer.yaml](.aiwg/bt6-maintainer.yaml) and the project-local
`bt6-maintainer` bundle for issue, pull-request, provider, and merge-train work.
Contributors should include focused tests and must not submit behavior changes with
zero relevant coverage. A passing PR gate makes a submission reviewable, not
automatically merge-ready. Maintainers own any additional tests, compatibility
hardening, and full-suite validation needed before merge, and the tagged release
gate remains the final certification boundary.

<!-- AIWG:workspace-operator:end -->