novomodelo-bridge 0.18.0__tar.gz

novomodelo_bridge-0.18.0/.claude/rules/bridge.md

@@ -0,0 +1,97 @@
+---
+paths:
+  - "src/novomodelo_bridge/**/*.py"
+---
+
+# Novomodelo-Bridge Conversion & CLI Contracts
+
+Repo-specific architectural contracts. Each is a contract, not a style
+preference — a plausible deviation ships wrong numbers, silent divergence
+between the two conversion tracks, or messages a pip-installed user cannot act
+on. The known standing architectural violations have been catalogued and
+remediated; do not introduce new ones.
+
+## 1. Twin-track symmetry (the central contract)
+
+The NEWAVE track (`newave/`, spine + `newave/converters/` +
+`newave/pipeline.py`) and the DECOMP track (`decomp/`, spine +
+`decomp/converters/` + `decomp/pipeline.py`) must honour the **same
+contracts** for the same operations:
+
+- A behaviour added to one track — a CLI flag, an exit-code rule, an emission
+  self-check, a `--force`/rollback rule, a verdict field, a preflight policy —
+  lands on **both tracks in the same change**, or the asymmetry is recorded as
+  a finding in the audit registry. Silent one-track divergence is the repo's
+  #1 recorded debt source; never extend it.
+- **Never import an underscore-private name across the `newave/` ↔ `decomp/`
+  track boundary.** When both tracks need it, promote it to `core/` (the
+  shared foundation both tracks may import) — enforced by
+  `tests/test_package_boundaries.py` (Rule B,
+  `test_no_private_cross_package_imports`) — the way `decomp/preflight.py`
+  reuses the public `CheckItem`/`PreflightResult`.
+- Physics and calendar math (cota polynomials, productivity, stage/block
+  weighting) live in **one** shared implementation (in `core/`). Two
+  implementations that "agree except at the edges" is exactly the bug class
+  `compare` exists to detect — in our own tool.
+
+## 2. TRACKED NOVOMODELO-GAP workarounds
+
+Never silently adopt a bridge-side workaround for a novomodelo limitation:
+
+1. Emit a log/diagnostic at the workaround site.
+2. Mark the site with a `TRACKED NOVOMODELO-GAP (Cn)` comment.
+3. Register the gap with its **removal condition** in novomodelo's
+   `conversion-found-improvements` registry (in the novomodelo repo).
+
+These comments are **protected contracts** (`.claude/rules/comments.md` §4):
+never delete or reword one away in a cleanup pass. When the gap closes in
+novomodelo, the workaround and its comment leave together. Reference the registry
+by name, never by a machine-local path.
+
+## 3. Source-model prose
+
+Comments, docstrings, and test names say **"the source model"** — not
+NEWAVE/CEPEL — when describing the (single) source format being converted.
+The model names stay in identifiers (`NewaveCase`), CLI/display labels, and
+file names (`dger.dat`). Carve-out: comparator/report code whose *subject* is
+the difference between the two models may name both ("NEWAVE uses full
+submarket names; DECOMP abbreviates") — a contrastive statement cannot be
+written generically.
+
+## 4. User-facing message hygiene
+
+CLI messages, diagnostics, and remediation hints must be **self-contained**:
+no repo docs paths, ticket codes, branch names, build tooling, or private
+symbols — pip-installed users have no repo checkout. Breadcrumbs for
+maintainers go in comments, not in the message. Guard new remediation strings
+with a no-leak test (the `test_remediation_has_no_repo_internal_references`
+pattern).
+
+## 5. Presentation and I/O boundaries
+
+- **Rich lives only in `ui/`.** No other module constructs a Console or
+  imports Rich (TYPE_CHECKING imports excepted). Library code never calls
+  `print()`/`sys.stdout.write` — user-facing rendering goes through
+  `novomodelo_bridge.ui.console`.
+- **Converters emit structured `Diagnostic` objects** (`diagnostics.emit()`),
+  never pre-formatted warning strings — the Diagnostic keeps the entity names,
+  stages, and values that the rendering layer turns into detail tables.
+- **Case-file writes go through the pipeline's write funnel** (the
+  `_write_json`/`_write_parquet` gate that owns `dry_run`/`would_write`) —
+  never a bare `json.dump`/`write_text` into the case dir that bypasses the
+  dry-run contract.
+- **Reads of novomodelo output route through `novomodelo_readers`/`novomodelo_io`** — do not
+  re-open `stages.json`/`lines.json`/parquet partitions with ad-hoc path
+  logic; per-block quantities are always weighted by `stages.json`
+  `blocks[].hours` through the shared weighting kernels.
+
+## 6. Exit codes and the `--json` envelope
+
+- `status == "error"` and a non-zero exit code travel together — a command
+  must never print an ERROR verdict and exit 0.
+- Every failure path under `--json` emits exactly one
+  `{schema_version, command, status, summary, diagnostics}` envelope on
+  stdout via `verdict.build_verdict` — including early CLI-level failures.
+- Diagnostics produced during a command run inside a `diagnostics.collect()`
+  sink and land in the envelope's `diagnostics` array — an emit with no sink
+  is a bug, not a fallback.

novomodelo_bridge-0.18.0/.claude/rules/comments.md

@@ -0,0 +1,194 @@
+---
+paths:
+  - "**/*.py"
+---
+
+# Novomodelo-Bridge Comment & Docstring Rules
+
+Governs every `#` comment and docstring in any `.py` file in this repo.
+Python adaptation of novomodelo's comment discipline (`~/git/novomodelo/.claude/rules/comments.md`);
+the Deletion Test and the Four Voices are identical, the directive set is adapted
+to Python and to this repo's domain (file-format conversion with unit traps).
+
+**Default is silence.** A comment is a liability — it costs reader attention and
+it can rot away from the code it describes. The job of this rule is to keep the
+small set of comments that prevent real bugs and delete everything else.
+
+---
+
+## 0. The Default-Off Discipline
+
+You are writing code with **no comments** until a specific comment earns its
+place against §1. In order, before any comment exists:
+
+1. **Refactor first.** Rename → extract a well-named function/constant →
+   introduce a dataclass/enum/NewType. A comment that a better name would carry
+   is a refactor you skipped.
+2. **Relocate.** The why of a _change_ goes in the commit message; a durable
+   cross-cutting contract goes in `.claude/rules/*.md` or a module docstring; a
+   behavioural fact goes in a **test name**. Inline comments are the residual:
+   the line-local trap none of those can carry.
+3. **Hoist.** A fact repeated across siblings (dataclass fields, dict keys,
+   match arms, call sites) is stated **once** at the enclosing scope.
+4. **Only then comment** — the shortest form that survives the Deletion Test,
+   referencing owning symbols instead of copying their formulas or numbers.
+
+### The docstring floor (terse, not absent)
+
+Public modules, classes, and functions carry a docstring (the global Python
+rules mandate this). Pay that floor with **one terse purpose line** plus only
+the sections that carry a nugget (`Args:` entries with a unit/shape/ordering
+contract, `Raises:` that callers must handle). Never a blow-by-blow narration
+of the body, and never the same clause restated across sibling functions —
+hoist shared context to the module docstring.
+
+---
+
+## 1. The Deletion Test (the one gate)
+
+> **Delete the comment.** Now — reading only the code, would a competent
+> engineer (a) introduce a bug, (b) "simplify" something correct into something
+> wrong, or (c) be unable to recover a fact that lives **outside this file**?
+> **If none → leave it deleted. If any → restore it, cut to the single clause
+> that triggers the "yes".**
+
+| If, with the comment deleted, the code…                         | Verdict                                  |
+| --------------------------------------------------------------- | ---------------------------------------- |
+| would be mis-edited into a bug (wrong-but-running alternative)  | **KEEP** — Contract (Voice 1), 1 clause  |
+| would be "simplified" by removing a load-bearing choice         | **KEEP** — Rationale (Voice 2), 1 clause |
+| loses a fact that lives outside this file (spec, sibling, test) | **KEEP** — pointer by symbol             |
+| reads exactly the same to a competent engineer                  | **DELETE**                               |
+| would be clearer with a better name / type / extracted fn       | **REFACTOR**, don't comment              |
+| loses only "how it got here" / what the next line does          | **DELETE** (→ git / a test name)         |
+
+The test applies to **every** comment site — module docstrings, function
+docstrings, function bodies, call sites, dataclass fields. The common bloat
+shapes, all DELETE:
+
+- A docstring that narrates its own body ("then for each stage: reads X,
+  computes Y, writes Z").
+- A call-site comment naming the function it precedes. If the call is not
+  self-documenting, **rename the function**.
+- Pipeline labels (`# Step 1`, `# Phase 3`) — the function names carry the phases.
+- An "explains why this is long" note with no suppression directive attached.
+- The same clause repeated down a function — state it once, delete the echoes.
+- An `Args:` list restating each parameter's name and type — keep only the
+  entries carrying a nugget (a unit, an ordering contract, a shape).
+
+When in doubt, **delete** and put the thought in the commit message.
+
+---
+
+## 2. The Four Voices — the only comments that survive §1
+
+- **Voice 1 — Contract.** A present-tense invariant **+ the wrong-but-running
+  alternative it forbids +** the owning symbol. _Exemplar (this repo):_ "must
+  stay pandas, never polars — handing `line_bounds` a polars frame makes the
+  bounds overlay silently disappear (`line_summary_chart` iterates
+  `.iterrows()`)."
+- **Voice 2 — Rationale.** Why a non-obvious choice was made; kept only while
+  the wrong simplification is still plausible. _Exemplar:_ "probability-weighted
+  mean, not `.mean()` — uniform averaging is wrong on a skewed scenario fan."
+- **Voice 3 — ~~Narrator~~ (NOT ALLOWED).** What the next line does; how it
+  used to work; which ticket changed it; project dates. Belongs in names, git,
+  or test names — never a shipped comment.
+- **Voice 4 — Intent/Seam.** Why a currently-unused item exists and what
+  activates it — pinned to the suppression or guard that anchors it (an unused
+  parameter kept for a wired-later caller must say so, or be deleted).
+
+---
+
+## 3. Directives
+
+### DO
+
+- **D1 — Contracts.** When the obvious alternative is wrong, say so: invariant +
+  forbidden alternative + owning symbol. One clause.
+- **D2 — Units and conventions.** Annotate values carrying physical units or a
+  convention trap — this repo is made of them: `m³/s` vs `hm³`, MW vs MWmes/MWh,
+  k$ vs R$ (×1000), per-block vs per-stage vs hours-weighted aggregation,
+  1-based source-model ids vs 0-based novomodelo ids, calendar vs stage indexing.
+  This is the one comment a good name usually cannot carry, and the direction
+  of the conversion ("divide by stage hours, not multiply") is the load-bearing
+  clause.
+- **D3 — Rationale above suppression.** Every `# noqa: CODE`,
+  `# type: ignore[code]`, `pytest.mark.xfail`, and every deliberate
+  `except`-and-degrade carries a reason on the same line or the line above:
+  why the fix the diagnostic asks for is inappropriate here. Blanket
+  suppressions without a code are banned outright (ruff `PGH` enforces this).
+- **D4 — Data-format traps.** Fixed-width column positions, sentinel values
+  (`-1` block ids, `1e31`-style infinities), case-insensitive filename
+  resolution, and record-layout quirks of the source-model files are
+  out-of-file facts — one clause naming the trap and the format that owns it.
+
+### DON'T
+
+- **N1 — No what-narration.** Rename instead.
+- **N2 — No history narration.** No `replaces`/`formerly`, no project-event
+  dates, no plan tokens (see N4). Keep the present-tense fact. Carve-outs:
+  bibliographic years, calendar/data-coverage years, a deck revision name
+  (`mar-26-rv2`) naming a still-existing fixture that pins a contract.
+- **N3 — No drift-prone refs.** Never a source-file line reference — this
+  repo's `file.py:NNN` or novomodelo's `file.rs:NNN` / `file.rs ~NN` alike (they
+  drift on every edit above the line) — nor commit hashes, `MEMORY.md`,
+  `.claude/` paths other than `.claude/rules/*`, machine-local paths
+  (`~/git/...`), paths into gitignored dirs (`plans/`), repo-relative paths
+  into the novomodelo source tree (`crates/...`, `novomodelo-io/src/...`), or a bare
+  internal design-doc section pointer (`design §5`, whose doc lives in
+  `plans/`). A pip-installed reader can resolve none of them. Reference by
+  symbol, by named test, or by a stable external anchor — the novomodelo book, a
+  schema name, a published reference `manual §`, or a novomodelo `file.rs::symbol`
+  (all durable, all allowed). For a symbol+line hybrid, keep the symbol, strip
+  the line. Gate: `scripts/ci/check_comment_refs.py` (every class hard).
+- **N4 — No plan/workstream leakage** in `src/`, `README.md`, `CHANGELOG.md`,
+  or `docs/`. No `epic`/`ticket`/`sprint` vocabulary, no `ticket-NNN`/`epic-NN`
+  ids, no acceptance-criteria tags. When a banned token is a trailing tag on a
+  contract line, amputate the tag, keep the invariant. Plan refs in **test
+  names** stay allowed (identifiers join with `_`, which the gate's word
+  boundaries respect). Gate: `scripts/ci/check_no_plan_leaks.py`.
+- **N5 — No banners fencing groups inside one long function** — extract a
+  function. Dividers between top-level sections of a large module are fine.
+- **N6 — No duplicated source-of-truth in prose** — a mirror restates the
+  _shape_ and references the owner by symbol; it never copies a magic number
+  or formula. A drifted mirror is a lie.
+
+### TODO/FIXME
+
+A shipped `TODO` carries a durable behavioural tag
+(`TODO(post-study-withdrawal)`) and names the guard or test enforcing the
+current limitation. Never a plan token. Bare ownerless `TODO`s are discouraged.
+
+---
+
+## 4. Protected Contracts (never delete — always considered)
+
+A blunt minimization pass that deletes one of these is worse than the bloat it
+removes:
+
+- **`TRACKED NOVOMODELO-GAP (Cn)` comments.** Each marks a deliberate workaround for
+  a novomodelo limitation, with its removal condition registered in novomodelo's
+  `conversion-found-improvements` registry. Never delete or reword one away;
+  when the gap closes, the workaround and its comment leave together
+  (see `.claude/rules/bridge.md`).
+- **Unit/weighting/direction contracts (D2).** "Weight by block hours",
+  "k$ → R$ ×1000", "divide, not multiply" clauses are the difference between
+  right and wrong numbers that still render.
+- **Silent-failure warnings (Voice 1)** naming a wrong-but-running alternative
+  whose failure mode is invisible (blank chart, empty overlay, zero-vs-zero
+  match).
+
+Tighten these to one clause + owning symbol; never lose the invariant.
+
+---
+
+## 5. Tooling
+
+- `scripts/ci/check_comment_refs.py` — hard gate on N3 (rot-refs), every
+  class enforced in `src/` (the pre-existing debt was burned down to zero).
+- `scripts/ci/check_no_plan_leaks.py` — hard gate on N4 in both shipped docs
+  and `src/` (the `src/` burndown is complete, so the scope is now enforced,
+  not advisory).
+- `scripts/ci/check_comment_bloat.py` — advisory: long comment blocks and
+  repeated clauses, candidates for a comment-skeptic pass.
+- `scripts/ci/quality_report.py` — advisory hotspot ranking (churn × size ×
+  long functions × suppressions × plan tokens).

novomodelo_bridge-0.18.0/.claude/rules/doc-integrity.md

@@ -0,0 +1,88 @@
+---
+paths:
+  - "*.md"
+  - "docs/**/*.md"
+  - ".claude/rules/*.md"
+---
+
+# Novomodelo-Bridge Prose Documentation Integrity Rules
+
+Governs every Markdown file that serves as a user-facing or agent-facing
+artifact: `CLAUDE.md`, `README.md`, `CONTRIBUTING.md`, `CHANGELOG.md`,
+`docs/**`, and `.claude/rules/*`. Port of novomodelo's doc-integrity rule; the code-comment
+counterpart is `.claude/rules/comments.md`.
+
+## 1. Reader per doc
+
+- **CLAUDE.md / `.claude/rules/*`** — an agent that acts on assertions.
+  Durability and anti-drift dominate; a stale claim here is executed, not read.
+- **CHANGELOG.md** — release history. Provenance is *inverted* (history is the
+  job); plan-leakage still applies (no epic/ticket tokens in released entries).
+- **README.md / docs/** — newcomers and users, most with **no repo checkout**
+  (pip install). Teaching voice is the job; promotional voice is not (§4).
+  README.md doubles as the PyPI description, so it links to `docs/` by
+  absolute URL.
+- **CONTRIBUTING.md** — a contributor with a checkout. Repo paths are fine;
+  every other rule here (durability, voice, plan-leakage) applies unchanged.
+- **`docs/*-data-map.md`** — NEWAVE/DECOMP modellers, in pt-BR. Generated
+  from `docs/lineage/*.toml`; the voice and durability rules apply to the TOML
+  prose, and the page is never edited by hand.
+
+## 2. The one adaptation that does the heavy lifting
+
+> **Name the external contract (filename / flag / config field / path), but
+> never freeze a COUNT, VERSION, ENUMERATION, or run-snapshot NUMBER. Pin any
+> literal that must appear with a guard, not by hand — otherwise state the
+> invariant instead of the number.**
+
+Bridge guards that pin literals so prose doesn't have to:
+
+- `docs/cli.md` is generated (`scripts/gen-cli-docs.sh`) and content-guarded by
+  `tests/test_docs.py` — never hand-edit it.
+- `docs/newave-data-map.md` and `docs/decomp-data-map.md` are generated by
+  `scripts/gen-lineage-docs.py` from `docs/lineage/` and gated by
+  `tests/test_lineage.py` (freshness, emission coverage against the mini
+  decks, cited files and registers exist, code trace). The TOML is the one
+  place a converted field's origin is stated; other docs point to the page.
+- `tests/test_packaging.py` holds the `pyproject.toml` `novomodelo-python` pin
+  equal to `MIN_NOVOMODELO_VERSION` — prose states the *rule* ("bridge X.Y.Z pairs
+  novomodelo X.Y.Z"), never a hand-copied version.
+- Where no guard exists, state the invariant: "every command accepts `--json`"
+  (a rule a test can enforce), not "all 7 commands" (a snapshot that rots).
+
+## 3. Failure modes to check on every doc edit
+
+1. **Single-source fan-out.** One fact cached into N docs drifts. One owner per
+   fact; other docs carry a shape-only pointer or a guard-pinned literal.
+2. **Stale current-state snapshots.** A census or completeness claim with no
+   adjacent diff to force an edit. State the durable invariant, not the count.
+3. **Audience-bleed.** Internal symbols/finding-IDs on a user page; repo-only
+   paths shown to pip users. Match content to the doc's reader.
+4. **Unresolvable claims.** Every cited repo-relative path, command, and flag
+   must resolve against the live tree (`scripts/ci/check_doc_paths.py` gates
+   README/CONTRIBUTING/docs). Never cite gitignored dirs (`plans/`, `example/` decks) or
+   machine-local paths (`~/git/...`) in *shipped* docs — the reader cannot
+   resolve them. (`example/` is allowed in CLAUDE.md, which documents the
+   local-deck convention for this checkout.)
+5. **Self-executable instructions.** A command a doc tells the reader to run
+   must itself succeed — verify by running it.
+6. **False-confidence guards.** A passing guard is evidence only for the
+   fact-class it parses; audit guard *coverage*, not just pass/fail (the
+   `uv.lock`-drift-beside-a-green-`test_packaging` incident is the house
+   example).
+
+## 4. Voice register — sober reference, not marketing
+
+Docs teach; they do not sell. Banned: hype adjectives ("powerful", "robust",
+"seamless", "production-grade"), contrasting-affirmatives ("not just X, it's
+Y"), reader-minimizers ("simply", "just", "easily", "obviously"), and
+unsubstantiated quality claims. The deletion test for voice: delete the
+adjective — if the sentence still states a true, checkable fact, the deletion
+was correct; if it only lost enthusiasm, it was hype.
+
+## 5. Plan-structure leakage
+
+No `epic`/`ticket`/`sprint` vocabulary or plan ids in shipped docs — plans live
+in `plans/` (gitignored); public artifacts describe behavior, not how the work
+was organized. Gate: `scripts/ci/check_no_plan_leaks.py`. Commit messages may
+reference plan structure — they target git-log readers.

novomodelo_bridge-0.18.0/.claude/rules/testing.md

@@ -0,0 +1,70 @@
+---
+paths:
+  - "tests/**/*.py"
+---
+
+# Novomodelo-Bridge Testing Rules
+
+The standing contract for how this repo is tested. Generic Python testing
+style lives in the global Python rules; these are the bridge-specific rules.
+
+## The 2-tier convention (load-bearing — CI depends on it)
+
+- **Tier 1 — pure Python.** Imports no `novomodelo`. Runs on every CI job. No
+  module at any tier may `import novomodelo` at module scope — the suite must
+  *collect* cleanly in a novomodelo-free environment.
+- **Tier 2 — needs `novomodelo-python`** (a required runtime dep) but no solver
+  binary. Guarded by `tests.conftest.requires_novomodelo_python`
+  (`find_spec`-based) and, where relevant, `requires_writer_binding`; any
+  `import novomodelo` lives inside the guarded test/helper body.
+
+## Local-data policy (enforced by `tests/test_local_data_policy.py`)
+
+Every test runs from the repository alone:
+
+- **No test builds a path into the gitignored `example/` tree, and none
+  resolves a path through `Path.home()`.** A test that runs on one developer's
+  machine only is a snapshot, not a guard, and its permanent skip elsewhere
+  reads as coverage. There is no tier 3.
+- **Real-format inputs are committed as small excerpts** under
+  `tests/fixtures/` (result-file heads, a schema, one example case — a few KB
+  each); synthetic decks live under `tests/decks/`. Name the excerpt's origin
+  in the module docstring.
+- **A check that genuinely needs a whole deck, a solved novomodelo case, or the
+  solver binary** is written up in `docs/real-deck-checks.md` (what it
+  verified, what it needs) instead of being kept as a skipped test.
+
+## Test architecture
+
+- **Mock discipline: patch public entry points only.** Patching an
+  underscore-private symbol couples the test to an implementation detail;
+  the repo's baseline is ~5 private patches out of ~300 — keep it there.
+  Pipeline tests mock converter entry points; CLI error-path tests run as
+  subprocess to verify real exit codes.
+- **One home per source module.** New converter/comparator tests go in a
+  `test_<module>.py` named for the source module — do not grow the mega-files
+  (`test_entity_conversion.py`, `test_decomp_results_compare.py`, `test_cli.py`
+  are legacy exceptions scheduled for splitting, not a pattern to extend).
+- **Shared case builders live in `tests/conftest.py`** (or a shared fixtures
+  module) — never re-defined per file.
+- **Test output goes to `tmp_path`.** No test writes into the repo tree;
+  generated artifacts self-delete.
+- **Golden files** (`tests/golden/`) pin rendered HTML/dataset shapes. A
+  deliberate rendering change regenerates them via the documented regeneration
+  path — never hand-edit a golden file, and never loosen an assertion to avoid
+  regenerating.
+- **CliRunner + Rich:** Typer help/rendering tests run under a dumb terminal
+  (`TERM=dumb` fixture) — Rich box-drawing output differs across CI terminals
+  and versions.
+- **Logger state:** an autouse fixture snapshots/restores the `novomodelo_bridge`
+  logger so a CliRunner invocation cannot leak logging state into a later
+  `caplog` test — new tests that reconfigure logging must go through it.
+
+## What a new feature must ship with
+
+- A tier-1 test for the pure conversion/analysis logic (synthetic inputs).
+- For a new CLI flag or exit-code path: a CliRunner or subprocess test
+  asserting the exit code and, when `--json` is involved, the verdict envelope.
+- For a new output artifact: an emission-shape test (schema/columns), mirrored
+  on **both** tracks when the artifact exists on both (see
+  `.claude/rules/bridge.md` — twin-track symmetry).

novomodelo_bridge-0.18.0/.git-blame-ignore-revs

@@ -0,0 +1,2 @@
+# The mechanical rename (rebrand.py tokens, ruff format, import order).
+3b9c531fd2ec0c0dabd748fb8f0c721bd37abc84

novomodelo_bridge-0.18.0/.github/workflows/ci.yml

@@ -0,0 +1,61 @@
+name: CI
+
+on:
+  push:
+    branches: ["main", "develop"]
+  pull_request:
+    branches: ["main", "develop"]
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    name: ruff + quality gates
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      # The ruff uv.lock pins, which the pre-commit hook runs from .venv;
+      # tests/test_packaging.py fails if the two differ.
+      - run: pip install "ruff==0.16.9"
+      - run: ruff check .
+      - run: ruff format --check .
+      # Drift/rot gates — conventions in .claude/rules/, docs in scripts/README.md
+      - run: python3 scripts/ci/check_no_plan_leaks.py
+      - run: python3 scripts/ci/check_comment_refs.py
+      - run: python3 scripts/ci/check_doc_paths.py
+
+  test:
+    name: pytest (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    strategy:
+      matrix:
+        python-version: ["3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      # novomodelo-python is a core runtime dependency, so `.[dev]` pulls it on
+      # every Python in the matrix — the tier-2 (`requires_novomodelo_python`)
+      # boundary-FCF tests now run on all jobs, not just the primary one.
+      - run: pip install -e ".[dev]"
+      - run: pytest --tb=short
+
+  coverage:
+    name: coverage (reader/align layer floor)
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - run: pip install -e ".[dev]"
+      - run: pytest --cov --cov-report=term-missing

novomodelo_bridge-0.18.0/.github/workflows/release.yml

@@ -0,0 +1,55 @@
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+
+concurrency:
+  group: release-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  build:
+    name: Build package
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - run: pip install build
+      - run: python -m build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  test:
+    name: pytest (release gate)
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - run: pip install -e ".[dev]"
+      - run: pytest --tb=short
+
+  publish:
+    name: Publish to PyPI
+    needs: [build, test]
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    permissions:
+      id-token: write
+    environment:
+      name: pypi
+      url: https://pypi.org/p/novomodelo-bridge
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

novomodelo_bridge-0.18.0/.gitignore

@@ -0,0 +1,39 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+*.egg
+*.egg-info/
+dist/
+build/
+.eggs/
+.env
+.venv
+env/
+venv/
+
+# pytest
+.pytest_cache/
+.coverage
+htmlcov/
+
+# ruff
+.ruff_cache/
+
+# editors
+.idea/
+.vscode/
+*.swp
+
+# examples
+example/
+
+# Local .claude config is ignored, except the path-scoped quality rules,
+# which are tracked and shared with the team.
+.claude/*
+!.claude/rules/
+
+plans/
+CLAUDE.md.tmp
+.mypy_cache/