underwrite 0.1.1__tar.gz → 0.2.0__tar.gz

{underwrite-0.1.1 → underwrite-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: underwrite
-Version: 0.1.1
+Version: 0.2.0
 Summary: Local evidence normalization, measurement, and acceptance checks
 License-Expression: Apache-2.0
 License-File: LICENSE
@@ -21,7 +21,7 @@ Description-Content-Type: text/markdown
 
 Find mismatches. Keep missing evidence visible. Know what to check next.
 
-**Local CLI & Python library · Typed JSON · No server or model calls**
+**Local CLI & Python library · JSON results · No server or model calls**
 
 [![CI](https://github.com/ntts9990/underwrite/actions/workflows/ci.yml/badge.svg)](https://github.com/ntts9990/underwrite/actions/workflows/ci.yml)
 [![PyPI](https://img.shields.io/pypi/v/underwrite)](https://pypi.org/project/underwrite/)
@@ -34,25 +34,24 @@ Find mismatches. Keep missing evidence visible. Know what to check next.
 
 </div>
 
-Already have evaluation exports from **goppi, Langfuse, DeepEval, or Promptfoo**?
-A score or summary alone does not show whether supplied rows match declared
-totals or whether the planned case inventory is complete. For supported local
-profiles, underwrite checks relationships it can verify and makes unknown
-coverage explicit. It returns typed CLI/Python results with findings, input
-identity, and interpretation limits. You or your agent can use them to request
-the next piece of evidence.
-
-Underwrite complements the tools that run evaluations: goppi owns execution,
-trace/verifier binding, and reruns; other producers own their exports and scores.
-Underwrite examines supplied artifacts and can retain selected bytes. It does
-not rerun an agent, independently authenticate a producer, or assign a universal
-quality score. No Docker, dashboard, or provider credentials are needed to
-inspect the supported local files.
+Evaluation tools run evaluations and export result files. Underwrite reads the
+local files it supports and shows what those files establish, what remains
+unknown, and what evidence to check next. For example, it checks whether
+Promptfoo’s reported totals agree with its supplied result rows. You or your
+coding agent use the JSON result to investigate and decide. You can also save
+selected inputs with the result for later review.
+
+Underwrite does not rerun evaluations, independently prove a producer's verdict,
+or assign one quality score across tools. Checking supported local files needs
+no Docker, dashboard, or provider credentials.
 
 > [!NOTE]
-> **This guide targets `underwrite==0.1.1`.** Its CLI and Python workflows work
-> without a checkout. The older `0.0.1` artifacts lack these workflows and have
-> a separate `pins refresh` caution; see [Install](#install).
+> **This guide targets `underwrite==0.2.0`.** [Install the CLI](#installed-package--020)
+> for automatic input handling, focused evidence views and retained trajectory review.
+> A [source checkout](#development-checkout--current-main) is optional for repository
+> examples and development. Use `capabilities --json` to confirm the installed routes.
+> Upgrading from 0.1.1? Read the [migration guide](https://github.com/ntts9990/underwrite/blob/main/MIGRATION.md).
+> The older `0.0.1` has a separate pin-manifest caution; see [Install](#install).
 
 ## Quickstart
 
@@ -61,18 +60,19 @@ synthetic download below uses `curl`.
 File-based CLI workflows are tested with CPython 3.12 on Linux and macOS. They
 require Unix/POSIX file APIs, including for ordinary artifact reads.
 
+### Installed package · 0.2.0
+
 **1. Install and check a file.** The app-only install resolves a compatible
 `underwrite-core` automatically. Download the public synthetic example; no
 checkout or API key is needed:
 
 ```sh
-uv tool install 'underwrite==0.1.1'
+uv tool install 'underwrite==0.2.0'
 underwrite capabilities --json
 example_dir=$(mktemp -d)
 curl -fsSLo "$example_dir/promptfoo.json" \
   https://raw.githubusercontent.com/ntts9990/underwrite/cb913d39bce628b93dcd3b06fcc4ce36f9dc66af/fixtures/examples/evidence/synthetic-promptfoo-count-mismatch.json
-underwrite audit-promptfoo "$example_dir/promptfoo.json" \
-  --version 0.123.0 --json
+underwrite audit-promptfoo "$example_dir/promptfoo.json" --json
 ```
 
 The same `uv tool install` command updates an older uv-managed `underwrite`
@@ -86,7 +86,7 @@ from its actual output:
 
 ```json
 {
-  "schema": "promptfoo_accounting.v1",
+  "schema": "promptfoo_accounting.v2",
   "declared_relation": "inconsistent",
   "producer_stats": {"errors": 1, "failures": 1, "successes": 1, "total": 3},
   "row_tallies": {"errors": 1, "failures": 0, "successes": 1, "total": 2},
@@ -98,6 +98,8 @@ from its actual output:
     "PLANNED_DENOMINATOR_UNKNOWN",
     "CAUSE_UNKNOWN",
     "SOURCE_CLAIMS_UNVERIFIED",
+    "UNCONSUMED_FIELDS_AND_POPULATIONS_NOT_ANALYZED",
+    "SOURCE_HASH_AND_VERSION_LINKABLE",
     "NO_APPROVAL_AUTHORITY"
   ]
 }
@@ -110,21 +112,40 @@ explicit. Exit `0` means the report was produced, not that the counts agree or
 the source's verdict was verified. To keep the input and analysis together,
 [save them in a local record](#keep-results-you-can-return-to).
 
-For your own completed Promptfoo export, replace the example path and select its
-supported source version. The synthetic download above is a constructed example,
-not an unchanged producer export.
+For your own completed Promptfoo export, replace the path and use a
+[supported input shape](#supported-formats). The downloaded file is a
+constructed example, not an unchanged producer export.
 
-<details>
-<summary><strong>Try the native measurement → acceptance workflow</strong></summary>
+### Development checkout · current main
 
-This example uses policies and fixtures in the GitHub checkout; they are not
-included in the installed package. To run it, prepare a checkout first:
+Use a checkout to work on the source or run repository examples. Run its commands
+through `uv run` inside that directory, keeping the installed tool separate. If you
+already have a checkout, open its root and start at `uv sync` below:
 
 ```sh
 git clone https://github.com/ntts9990/underwrite.git
 cd underwrite
 uv sync --frozen --all-groups
+uv run --frozen --no-sync underwrite capabilities --json
+uv run --frozen --no-sync underwrite audit-promptfoo \
+  fixtures/examples/evidence/synthetic-promptfoo-count-mismatch.json --json
+```
+
+This uses the same synthetic counts as above: 3 declared results versus 2 rows.
+The automatic reader produces `promptfoo_accounting.v2` and preserves this
+fixture's declared `0.123.0` version as an unverified source claim. Inputs without
+a version declaration retain an unknown release. No version flag, producer
+installation, Goppi, or provider call is needed for this example.
+Use this `uv run --frozen --no-sync underwrite` prefix for all checkout commands.
+See [included workflows](#included-in-020) for the other routes.
 
+<details>
+<summary><strong>Try the native measurement → acceptance workflow</strong></summary>
+
+After preparing the checkout above, run this example from its root. Its policies
+and fixtures live in the repository, outside the installed package:
+
+```sh
 mkdir -p output
 uv run --frozen --no-sync underwrite ingest \
   --format underwrite.evidence-bundle --version v1 \
@@ -154,53 +175,46 @@ See [measurement meaning](https://github.com/ntts9990/underwrite/blob/main/AGENT
 
 | Question after an evaluation | What underwrite gives you |
 | --- | --- |
-| Does the summary match the supplied records? | Profile-specific accounting: Promptfoo count deltas, DeepEval evaluator errors, or Langfuse score associations. |
-| What is still unknown? | Explicit missingness and limits such as an unknown planned denominator or unverified source claim, so a zero is not silently substituted. |
-| Can this evidence support a measurement? | A separate native binary-event path with declared semantics and policy; external scores do not become a universal quality verdict. |
-| Can I revisit the conclusion? | Typed CLI/Python JSON and optional private records tying selected input bytes to the analysis, with verification and retrieval. |
+| Does the summary match the supplied records? | Compare Promptfoo declared counts with rows. Separately account for DeepEval scored rows and evaluator errors, or Langfuse score associations; their aggregate summaries are not assumed checked. |
+| What is still unknown? | See when planned cases are unknown or source claims are unverified; unknown is not counted as zero. |
+| Can this evidence support a measurement? | Use the separate native binary-event path with a declared event and policy; external scores are not a universal quality verdict. |
+| Can I revisit the conclusion? | Save selected input bytes and the analysis in a private record, then verify and retrieve them later. |
 
 ## How it works
 
-```mermaid
-flowchart LR
-    A[Supported local eval file] --> B[Select exact profile]
-    B --> C[Check supplied records and missingness]
-    C --> D[Typed JSON: finding, identity, limits]
-    D --> E[Agent or person gathers next evidence]
-    C --> F[Optional private record]
-    F --> G[Verify and retrieve]
-    H[Native event evidence + policy] --> I[Measure]
-    I --> D
-```
+- **Evaluation tool:** runs the evaluation and exports result files.
+- **Underwrite:** checks the supplied results, returns JSON with findings and
+  unanswered questions, and can save selected original files with the result.
+- **You or your agent:** check the missing evidence and decide what to do next.
 
-The command checks only what its selected profile supports. The calling agent
-interprets the JSON and can pursue the next evidence task; underwrite does not
-apply a proposed change or grant merge authority. Local records keep selected
-inputs and results for later review.
+Each command checks only its selected input profile. Source verdicts remain
+source claims; Underwrite does not apply changes or grant merge authority. Its
+separate native binary-event workflow measures only a declared event under an
+explicit policy, not arbitrary external scores.
 
 ## Agent use
 
-Give your coding agent the installed CLI and a completed local export. It can
-discover the available routes, execute them, and use the JSON in its response:
-
-```sh
-underwrite --help
-underwrite capabilities --json
-```
+Give your coding agent a completed local export and your chosen entry path.
+Have it inspect `capabilities --json` and the command's `--help` using that same
+executable: `underwrite` for the published tool, or
+`uv run --frozen --no-sync underwrite` from the checkout. Package version alone
+does not identify the available workflows.
 
 Python callers can use
-`underwrite.instrument.ingest.accounting.audit_promptfoo_file(Path(...))` for
-the same result as a dictionary. Select an exact supported profile before
-interpreting any producer-specific field.
+`underwrite.instrument.ingest.accounting.audit_promptfoo_file(Path(...))` in
+the chosen environment. Automatic intake selects a supported reader from the
+input shape without guessing a producer release. Use explicit historical selectors
+when reproducing an older contract, as described in the migration guide.
 
 Example task for an agent with terminal access:
 
-> Review `/absolute/path/to/completed-promptfoo-export.json` with the installed
-> `underwrite` 0.1.1 CLI as a Promptfoo 0.123.0 export. Use `capabilities --json`
-> and `audit-promptfoo --version 0.123.0`.
-> Report `declared_relation`, `producer_stats`, `row_tallies`, `raw_hash`,
-> `limitations`, and the next useful action. Do not rerun the producer or treat
-> exit `0` as agreement or approval.
+> Review `/absolute/path/to/completed-promptfoo-export.json` using our selected
+> Underwrite entry path. Inspect its capabilities and help, then use the
+> supported accounting route. Use automatic intake when advertised; otherwise
+> require evidence of a supported published profile rather than guessing a version.
+> Report count differences, input identity, missing evidence, interpretation
+> limits, and the next useful check. Do not rerun the producer or treat exit `0`
+> as agreement or approval.
 
 The optional [underwrite-review skill](https://github.com/ntts9990/underwrite/blob/main/skills/underwrite-review/SKILL.md) provides
 reusable guidance for Codex and Claude Code. [Setup and usage](https://github.com/ntts9990/underwrite/blob/main/AGENT_USAGE.md#optional-artifact-review-skill)
@@ -210,67 +224,76 @@ The same CLI and importable Python APIs are available to your own automation.
 
 ## Supported formats
 
-Support is for the **specific local payload profiles below**, not every API,
-export, or version offered by each producer. Select the version explicitly.
+Support covers selected local payloads, not every producer API, export, or
+version. Use capabilities from your chosen executable and the linked workflows
+for exact input requirements.
+
+### Supported profiles · 0.2.0
 
 | Your input | Supported profile | Start here |
 | --- | --- | --- |
-| **goppi** | Completed baseline exchange manifest v2; separate paired-handoff route | [`audit-baseline`](https://github.com/ntts9990/underwrite/blob/main/AGENT_USAGE.md#audit-a-completed-goppi-baseline-as-common-evidence) for descriptive common JSON · [`project-baseline`](https://github.com/ntts9990/underwrite/blob/main/AGENT_USAGE.md#project-a-completed-goppi-baseline-into-event-observations) for native measurement · [`review-handoff`](https://github.com/ntts9990/underwrite/blob/main/AGENT_USAGE.md#review-a-completed-paired-handoff-in-one-call) |
-| **Langfuse** | `4.35.0` server blob exports: observations-v2 and scores JSON arrays | [`audit-langfuse`](https://github.com/ntts9990/underwrite/blob/main/AGENT_USAGE.md#account-for-langfuse-score-kinds-and-associations), with an optional content-minimized row index |
-| **DeepEval** | Ordinary TestRun JSON, `4.1.1` or `4.2.8` | [`audit-deepeval`](https://github.com/ntts9990/underwrite/blob/main/AGENT_USAGE.md#account-for-deepeval-scores-and-evaluator-errors) |
-| **Promptfoo** | Eval output JSON, `0.123.0` or `0.124.1` | [`audit-promptfoo`](https://github.com/ntts9990/underwrite/blob/main/AGENT_USAGE.md#source-checkout-pilot-audit-promptfoo-counts) |
-| **External common result** | `evidence_result.v1` JSON from a producer | [`inspect-result`](https://github.com/ntts9990/underwrite/blob/main/AGENT_USAGE.md#inspect-an-external-common-result) for contract screening and availability counts, with optional evidence-item `next_action` and declared metric-binding counts |
+| **Goppi** | Completed baseline exchange manifest v2; P7 handoff; adopted paired trajectory | [`audit-baseline`](https://github.com/ntts9990/underwrite/blob/main/AGENT_USAGE.md#audit-a-completed-goppi-baseline-as-common-evidence) · [`project-baseline`](https://github.com/ntts9990/underwrite/blob/main/AGENT_USAGE.md#project-a-completed-goppi-baseline-into-event-observations) · [`review-handoff`](https://github.com/ntts9990/underwrite/blob/main/AGENT_USAGE.md#review-a-completed-paired-handoff-in-one-call) · [`audit-trajectory`](https://github.com/ntts9990/underwrite/blob/main/AGENT_USAGE.md#compare-a-goppi-paired-trajectory) |
+| **Langfuse** | Compatible blob arrays or official-CLI list captures; automatic pair selection | [`audit-langfuse`](https://github.com/ntts9990/underwrite/blob/main/AGENT_USAGE.md#account-for-langfuse-score-kinds-and-associations) |
+| **DeepEval** | Compatible TestRun; automatic accounting, optional trace view and meaning bindings | [`audit-deepeval`](https://github.com/ntts9990/underwrite/blob/main/AGENT_USAGE.md#account-for-deepeval-scores-and-evaluator-errors) |
+| **Promptfoo** | SummaryV3 eval output; automatic intake, historical selectors retained | [`audit-promptfoo`](https://github.com/ntts9990/underwrite/blob/main/AGENT_USAGE.md#audit-promptfoo-counts) |
+| **External common result** | `evidence_result.v1` or `evidence_result.v2` | [`inspect-result`](https://github.com/ntts9990/underwrite/blob/main/AGENT_USAGE.md#inspect-an-external-common-result) |
 | **Native evidence** | `underwrite.evidence-bundle` / `v1` | `ingest` → `measure` → `accept` |
 | **Inspect AI** | `inspect.eval-log` / `0.3.263` | `ingest` |
 | **OpenInference** | `openinference.traces` / `0.1.38` | `ingest` |
 | **OTLP JSON** | `otlp-json.traces` / `0.160.0` | `ingest` |
 
-For completed exports already on your machine, the installed CLI accepts them
-directly; select the exact producer profile you have:
+### Included in 0.2.0
+
+- **Automatic intake:** compatible Promptfoo SummaryV3, DeepEval TestRun, and
+  Langfuse blob arrays or [official-CLI list captures](https://github.com/ntts9990/underwrite/blob/main/AGENT_USAGE.md#read-official-langfuse-cli-captures-offline)
+  without selecting a producer version/profile. Actual producer release stays
+  unknown when the payload does not establish it; explicit selectors remain for
+  reproducing older contracts.
+- **Focused views and storage:** selected DeepEval trace structure, version-neutral
+  `deepeval_metric_bindings.v2` packs, and Langfuse row-index recording. Follow the
+  linked producer workflows above for their separate contracts and limits.
+- **Common results:** `inspect-result` also accepts `evidence_result.v2`.
+- **Goppi steps:** [`audit-trajectory`](https://github.com/ntts9990/underwrite/blob/main/AGENT_USAGE.md#compare-a-goppi-paired-trajectory)
+  compares recorded tool states and evaluation results from a paired+trajectory
+  export, including runs that stopped early. This optional route requires installed
+  Goppi for offline verification; it does not run providers, establish causality,
+  or measure retry effects. [`records audit-trajectory`](https://github.com/ntts9990/underwrite/blob/main/STORAGE.md#retain-a-goppi-paired-trajectory)
+  retains the same inputs and result; `records read-trajectory` reopens them
+  without Goppi or the original export.
 
-```sh
-underwrite audit-promptfoo /path/to/promptfoo-output.json --version 0.124.1 --json
-underwrite audit-deepeval /path/to/deepeval-test-run.json --version 4.2.8 --json
-underwrite audit-langfuse --observations /path/to/observations.json \
-  --scores /path/to/scores.json --json
-underwrite audit-baseline --exchange /path/to/goppi-baseline-exchange --json
-```
-
-DeepEval accounting defaults to `4.1.1`; select `--version 4.2.8` for that
-profile. For a reusable owner-asserted metric-name pack and common descriptive
-JSON, see the [DeepEval binding workflow](https://github.com/ntts9990/underwrite/blob/main/AGENT_USAGE.md#account-for-deepeval-scores-and-evaluator-errors).
-Promptfoo accounting defaults to `0.123.0`; select `--version 0.124.1`
-for that profile. Langfuse's version identifies the server export, not its SDK.
 See [artifact requirements](https://github.com/ntts9990/underwrite/blob/main/AGENT_USAGE.md#get-the-right-producer-artifact) and
-[producer checks](https://github.com/ntts9990/underwrite/blob/main/EVIDENCE_REVIEW.md) for the tested scope and fixture origins.
-
-Generic `ingest` / `project` normalizes supported exports to an observation;
-external observations do not enter the current `measure` path. goppi uses its
-explicit exchange adapters: `audit-baseline` produces descriptive
-`evidence_result.v1` without a policy or directional verdict, while
-`project-baseline` can produce native event observations. `prepare-event-policy`
-binds a consumer configuration while leaving statistical assumptions unknown.
-For an already produced `evidence_result.v1` file, `inspect-result` checks the
-installed contract and item counts without verifying the producer's source or
-bundle, or admitting that result to measurement or acceptance.
-Its optional action view counts recorded next actions for evidence remediation,
-not executed tool calls or an agent trajectory.
+[producer checks](https://github.com/ntts9990/underwrite/blob/main/EVIDENCE_REVIEW.md)
+for fixture origins and tested scope. A controlled fixture does not prove
+live-server interoperability or export completeness.
+
+Moving from published 0.1.1? See the [migration guide](https://github.com/ntts9990/underwrite/blob/main/MIGRATION.md)
+for changed default JSON contracts, historical selectors, and existing records.
+
+Generic `ingest` / `project` normalizes supported exports; external observations
+do not enter the current `measure` path. Goppi `audit-baseline` produces
+descriptive common evidence, while `project-baseline` can produce native event
+observations. `inspect-result` screens the installed common-result contract and
+counts items without verifying source truth or admitting them to measurement
+or acceptance. Its action view counts recorded next checks, not executed tools.
 
 ## Keep results you can return to
 
 Use `records` when you want the analysis and its selected source bytes retained
-together. For a completed local Promptfoo export:
+together. This example uses the **published package** with a completed local
+Promptfoo export:
 
 ```sh
 underwrite records audit-promptfoo /path/to/promptfoo-output.json \
-  --version 0.123.0 --root ./review-store --id review-001 --json
+  --root ./review-store --id review-001 --json
 
 underwrite records read-json \
   --root ./review-store --id review-001 \
   --name analysis/accounting.json --json
 ```
 
-Use a fresh ID for each capture; existing records are never overwritten.
+Automatic intake needs no producer version flag. In a checkout, prefix both
+commands with `uv run --frozen --no-sync`. Use a fresh ID for each capture;
+existing records are never overwritten.
 `records verify` checks stored integrity. `records measure` captures a native
 measurement, and `records replay-measure` recalculates it from verified saved
 inputs using the current engine, without executing the original producer.
@@ -304,7 +327,7 @@ Install the versioned app; its dependency resolves the compatible core. Use
 profiles:
 
 ```sh
-uv tool install 'underwrite==0.1.1'
+uv tool install 'underwrite==0.2.0'
 underwrite --help
 underwrite capabilities --json
 ```
@@ -317,12 +340,12 @@ For the importable Python API, install into a Python 3.12 environment instead:
 
 ```sh
 uv venv --python 3.12 .venv
-uv pip install --python .venv/bin/python 'underwrite==0.1.1'
+uv pip install --python .venv/bin/python 'underwrite==0.2.0'
 .venv/bin/python - <<'PY'
 from pathlib import Path
 from underwrite.instrument.ingest.accounting import audit_promptfoo_file
 
-result = audit_promptfoo_file(Path("/path/to/promptfoo-output.json"), version="0.123.0")
+result = audit_promptfoo_file(Path("/path/to/promptfoo-output.json"))
 print(result["declared_relation"])
 PY
 ```
@@ -358,46 +381,8 @@ a manifest with an expected hash, `check` examines release evidence linkage,
 vocabulary, and `drift check` / `pins refresh` work with supplied pin registries.
 [JSON contracts](https://github.com/ntts9990/underwrite/tree/main/contracts/) define each command family's results and errors.
 
-Legacy `absence` and `drift check` exemption files and `boundary scan` allowlists
-are bounded to 1 MiB, 64 JSON container levels, and 1024 policy entries each.
-`boundary scan` reads at most 4 MiB per selected JSON or JSONL file and 32 MiB
-of captured bytes across the command, including its allowlist. It admits up to
-4096 selected files, 100000 visited directory entries, 100000 physical JSONL
-lines and 1 MiB per raw line (including its delimiter), and 4096 leaks including
-allowed rows. Its selected JSON or human output is capped at 1 MiB including
-the final newline. Duplicate keys and nonfinite numbers are invalid; supplied
-`--now` and policy expiry dates must be real ASCII `YYYY-MM-DD` dates. Admission
-failures return a typed `UNCONFIGURED` result with exit 2. An absent `--now`
-still yields `NOW_REQUIRED` only when the semantic check needs a clock.
-
-`absence` retains `Path.glob` matching and refuses more than 4096 matching
-regular files; it does not bound directory traversal within `Path.glob` or
-suppressed internal filesystem errors. Boundary scans follow an explicitly
-selected directory link and regular file links, but do not descend into a child
-directory link. These selections do not establish path containment against a
-hostile filesystem.
-
-`drift check` admits up to 256 manifests and 4096 declared pin files while
-counting at most 100000 visited registry entries. Each manifest is limited to
-1 MiB and 64 JSON container levels; each selected source or pin copy is limited
-to 4 MiB. The 32 MiB command capture budget includes exemption bytes, manifests,
-and both copies. Read-only inspection follows selected directory and file links;
-it does not create an atomic filesystem snapshot or a hostile-path containment
-guarantee. Missing or nonregular selected copies are reported as DRIFT; malformed,
-unreadable, or excessive registry input returns a typed `UNCONFIGURED` result
-without fabricated population counts.
-
-`pins refresh` selects one registry repository and copies committed Git blobs.
-Refresh paths must be normalized relative `/`-separated components; empty, dot,
-parent, backslash, Unicode control/format, oversized, and colliding destinations
-are refused.
-The selected registry and its existing destinations are checked before mutation.
-Each pin is replaced with a new inode under its opened registry parent, and
-`PINS.json` is replaced last. Admission or Git-source failures leave the registry
-unchanged. A later filesystem failure reports `publication: may_be_partial`;
-refresh is not an all-files transaction or a durability guarantee.
-Refresh captures each committed Git blob within 4 MiB and the 32 MiB aggregate
-budget, and checks the fully serialized 1 MiB manifest before its first write.
+For scan and pin resource limits and filesystem-selection caveats, see
+[Scan and pin limits](https://github.com/ntts9990/underwrite/blob/main/AGENT_USAGE.md#scan-and-pin-limits).
 
 <a id="development-checkout-evidence-pilots"></a>
 
@@ -430,10 +415,13 @@ Before using OIDC publishing, create the GitHub environment `pypi`, restrict it
 `ntts9990`, repository `underwrite`, workflow `publish.yml`, and environment `pypi`.
 Once configured, run **Publish PyPI** manually from `main` in GitHub Actions.
 
-The workflow validates both packages, then publishes core before the application;
-only the separate publish job receives OIDC permission. No stored PyPI API token
-is required. Retry a partial upload with the same artifacts: existing registry
-files must match exactly, and changed artifacts require a new version.
+The workflow validates both packages and defaults to publishing only the app
+(`publish_core: false`), after testing it with the published compatible core. Select
+`publish_core: true` only for an explicitly approved core release; core upload must
+succeed before app upload. The unchanged core remains `0.1.1` for this app release.
+Only the publish job receives OIDC permission; no stored PyPI token is required.
+Retry partial uploads with identical artifacts. Existing registry files must match
+exactly; never re-upload a rebuilt, different archive under an existing version.
 
 See the official [uv publishing guide](https://docs.astral.sh/uv/guides/package/)
 and [PyPI Trusted Publisher guide](https://docs.pypi.org/trusted-publishers/using-a-publisher/).