katalyst-forge 5.2.1__tar.gz → 5.4.0__tar.gz

{katalyst_forge-5.2.1 → katalyst_forge-5.4.0}/CHANGELOG.md

@@ -16,6 +16,51 @@ PyPI package version. A breaking node-type/model change bumps `schema_version`.
 
 ---
 
+## [5.4.0] -- 2026-08-09
+
+### Added
+
+- **Per-dispatch model tier routing** (RIC-1580). A Forge dispatch can name the model tier it wants, and the orchestrator honours it through SDK child sessions rather than running every stage on the orchestrator model. Ships per-stage model and token telemetry alongside it, plus a containment and portability gate (`scripts/dispatch/check-dispatch.ts`) that reds on committed vendor model ids so a routing target cannot be hardcoded into the taxonomy.
+- **`quantity_kind` on every cost metric definition** (RIC-1645). The audited catalogue now declares what each figure IS (`spend`, `saving`, `counterfactual`, `ratio`), not only which catalogue priced it. Read by both renderers so presentation cannot disagree with the document the figure was computed from.
+
+### Fixed
+
+- **The run report no longer presents savings as money that was billed** (RIC-1645). Every USD metric was captioned `Metered spend` and charted under "Metered spend per metric, in dollars actually billed", including three that the report itself described as savings: `cache-savings` ("Net spend avoided"), `routing-headroom` ("not yet captured this run") and `routing-savings-realized` ("Saving actually captured"). One figure put $14.17 of bars on an axis labelled dollars actually billed for a run that billed $1.66. `BillingMode` answers which catalogue priced a figure, not whether it was billed; for `agent-run-cost` and `cost-per-stage` the two coincide, which is why rendering the basis tag as the label read correctly and the conflation survived the whole RIC-1615..1629 series. Billed spend now has an axis of its own, savings and modelled figures have theirs, and neither is scaled against or totalled with the other.
+- **The run report survives an unreadable message list instead of writing nothing** (RIC-1634). The cost path read each session's messages through an unguarded fetch while run health read the same endpoint through a degrading reader, so a persistent 500 on one session killed the whole report at the same moment run health was recording that session as degraded. Both halves now read through one path: the session degrades to its provider rollup, the run still reports, and the degraded-session panel names it. A transport failure is named (`ProviderTransportError` carries the endpoint) rather than surfacing as a traceback ending in a bare status code, and deliberately is not a `MetricsAdapterError`, so a host-level failure cannot be downgraded into a quietly missing source.
+- **A rate no longer borrows an endpoint it never reached** (RIC-1635). A 99.998% cache hit rate rendered as `100.00%`, which reads as every token served from cache. A rate strictly inside its range keeps a comparator, and the denominator it is computed over is stated in the metric definition the report renders.
+- **An absent measurement states itself** (RIC-1636). An unmeasured metric rendered as a numbered card with an empty body, which reads as a render bug, while `$0.00` would have read as measured and zero. It now carries the same explicit "not measured" marker the tiles use, and a billing-mode caption only ever appears under a money value, never under a ratio.
+- **The report self-identifies** (RIC-1637). It carries a UTC generation timestamp, the installed generator version, and the pricing catalogue the figures were priced against, the last only once a price was actually looked up.
+- **Rollup spend from a session that named no model is stated rather than left to vanish** (RIC-1638). It still gets no per-model row, because a fabricated model beside measured ones is worse than a gap, but the total is carried and both the tile and the detail note say so out loud.
+- **Money-mixing guards hardened** (RIC-1639). The billing-mode tag used to fall away the moment a value left `MetricResult`, so a one-line sum over `items()` produced exactly the cross-mode total the type exists to prevent. Values now leave tagged and refuse addition, `combine()` refuses to merge a result with itself, and a threshold band judges one billing mode instead of any figure that happens to share its unit.
+- **Message truncation is detected rather than silently shortening a run** (RIC-1631), and the RIC-1624 feature files are committed.
+- **`opencode.json` points at agents that exist** (RIC-1643). Every agent prompt referenced `./.opencode/agents/<name>.md`, but nothing is tracked under `.opencode/` and all 40 agents live in `agents/`. OpenCode validates `{file:...}` references when it loads a config, so it refused to start from the repo root and the repository was unusable as an OpenCode working directory. `scripts/validate.sh` had been checking that each declared agent KEY had a matching file, never the prompt reference OpenCode actually resolves, so it stayed green throughout; it now resolves every `{file:...}` reference.
+- **`kata-tax-validator-fixer` uses real kata commands** (RIC-1567). It invoked `kata tax json` and a `--path` flag, neither of which exists.
+- **The practice resolver probe fails loud** (#41). A failed probe returned the same empty result as a genuine zero, so a gate whose probe never ran reported a clean pass.
+
+### Changed
+
+- Minor rather than patch: RIC-1580 is additive and RIC-1645 adds a metric-definition field with a backward-compatible default. No node-type or model contract broke, so the bundle `schema_version` is unchanged.
+
+---
+
+## [5.3.0] -- 2026-08-08
+
+### Added
+
+- **The governance half of the Forge run report, as a tile dashboard** (RIC-1624). The pre-RIC-1590 report was described by its own commit as cost *and governance* observability; only the cost half survived the move into the metrics wing. Restored as six tiles, each summarising one concern and linking to a detail view: run spend, rollup agreement, stage coverage, degraded sessions, unpriced models, and spend per model. Adds `metrics/run_health.py` (a pure core computing the session tree, stage attribution, rollup drift, degradation and pricing coverage), `metrics/measurement.py` (a figure that was measured, or an explicit absence, which refuses addition and float coercion), `metrics/tiles.py`, and `metrics/forge_stages.py` (the eleven stage names, previously spelled out in two places). None of it enters `metric_definitions`: a new `opencode-run-health` signal source declares `signal_type: run_health` with no `billing_mode` and no `metric_ref`, and both pipelines filter on `signal_type`.
+- **`optional_fields` awareness for provider-synthesized values**, already shipped in 5.2.0, is now exercised by the run-health source.
+
+### Fixed
+
+- **Bundle content installed into a project is now discoverable** (RIC-1629). The only fallback understood the katalyst-forge working-copy layout, resolving through `__file__.parents[3]`, which inside `site-packages` points at the Python installation rather than at any project. So an installed package could never find content a project had installed correctly, and every invocation needed `FORGE_COST_CONTENT_DIR` set by hand. Resolution order is now explicit argument, environment override, the project's installed taxonomy, then the working-copy layout.
+- **Five dashboard alignment defects** (RIC-1632). A CSS class collision on `.figure` stacked every tile label above its value, because the pre-existing SVG figure rule sets `flex-direction: column` and the tile rule never overrode it. Six tiles rendered as five across plus one orphan of a different height. Sublines floated at five different heights within a row. Numeric table columns sat right-aligned under left-aligned headers. And a drift of `-2E-16` rendered as `$-0.00`, now fixed at `dashboard.to_cents`, the single rounding point, so the text renderer and percentage formatter benefit too; a sign still survives wherever there is a magnitude to describe.
+- **The `kata-tax-writer` Kind Mapping matches the registry** (RIC-1625). Every row paired a CamelCase kind with a `katalyst.taxonomy.plugins.*/v1alpha` apiVersion, and neither is recognised: loaders match lowercase kinds exactly and the parser skips an unknown apiVersion before a loader sees the document. Since the writer is the single writer, every artifact other agents create flowed through it. `plugin-stage` needed `cicd_stage`, the job and workflow templates needed the `cicd_` prefix, and `taxonomy-node` named a kind no creation template emits. Four artifact types were not mis-mapped but unsupported: bounded contexts, aggregates, domain events and glossary terms are fields on a single `business_domain_model` document, which the shared `BDM-` id prefix already implied.
+- **The llm-gateway mapping declares itself unverified** (RIC-1622). Its eight field paths were written by analogy to the OpenCode source rather than read from live gateway output. A `verified_against_provider: false` flag now pairs with a test asserting the provider still raises while it is false, so an unverified mapping cannot quietly begin producing figures.
+
+### Changed
+
+- **Scaffold drift between the authoritative agents and the bundled copies is gated, and the existing drift is resolved** (RIC-1626). Every agent and skill exists twice, and 19 of 52 pairs had diverged with neither copy signposted as authoritative. All twelve substantive divergences turned out to be the scaffold being stale: five carried Stellite guidance, including an instruction to run `kata tax stellite validate`, a command that exists nowhere, and the rest carried the abandoned user-story vocabulary. Three scaffold-only orphans were also removed, among them a whole agent for the deleted Stellite subsystem, which the original pair-based gate could not see.
+
 ## [5.2.1] -- 2026-08-08
 
 ### Fixed

{katalyst_forge-5.2.1 → katalyst_forge-5.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: katalyst-forge
-Version: 5.2.1
+Version: 5.4.0
 Summary: Katalyst Forge: the delivery-lifecycle bundle (node kinds, wings, agents, templates, schemas)
 Author: eSimplicity
 License: Proprietary

{katalyst_forge-5.2.1 → katalyst_forge-5.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "katalyst-forge"
-version = "5.2.1"
+version = "5.4.0"
 description = "Katalyst Forge: the delivery-lifecycle bundle (node kinds, wings, agents, templates, schemas)"
 license = { text = "Proprietary" }
 requires-python = ">=3.12"

{katalyst_forge-5.2.1 → katalyst_forge-5.4.0}/src/katalyst_forge/metrics/core.py

@@ -31,6 +31,44 @@ from katalyst_forge.metrics.protocols import (
 )
 
 
+class ModeTaggedMoney(Decimal):
+    """A figure that remembers the billing mode it came from, and refuses addition.
+
+    MetricResult refuses to total across modes, but the tag used to disappear the
+    moment a value left it, so a plain `sum()` over `items()` produced exactly the
+    cross-mode total the class exists to prevent. Tagging the leaf keeps the
+    guarantee where the numbers actually travel.
+
+    Only addition is blocked. Comparison, division, quantizing and formatting all
+    still work, because addition is the single operation that silently merges two
+    quantities into a third one that describes neither.
+    """
+
+    __slots__ = ("billing_mode",)
+
+    def __new__(cls, value: Decimal, mode: BillingMode) -> ModeTaggedMoney:
+        instance = super().__new__(cls, value)
+        instance.billing_mode = mode
+        return instance
+
+    def _refuse(self, other: object) -> ModeTaggedMoney:
+        other_mode = getattr(other, "billing_mode", None)
+        detail = (
+            f"{self.billing_mode.value} + {other_mode.value}"
+            if isinstance(other_mode, BillingMode)
+            else f"a {self.billing_mode.value} figure with {type(other).__name__}"
+        )
+        raise CrossBillingModeError(
+            f"cannot add {detail}; read one mode at a time, or combine() within a mode"
+        )
+
+    def __add__(self, other: object) -> ModeTaggedMoney:
+        return self._refuse(other)
+
+    def __radd__(self, other: object) -> ModeTaggedMoney:
+        return self._refuse(other)
+
+
 class MetricResult:
     """An immutable, mode-partitioned metric value. No cross-mode total exists."""
 
@@ -38,16 +76,21 @@ class MetricResult:
 
     def __init__(self, metric_name: str, by_mode: Mapping[BillingMode, Decimal]) -> None:
         self.metric_name = metric_name
-        self._by_mode: Mapping[BillingMode, Decimal] = MappingProxyType(dict(by_mode))
+        # Stored untagged so internal within-mode arithmetic (combine) stays
+        # ordinary; the tag is applied on the way out, where values escape.
+        self._by_mode: Mapping[BillingMode, Decimal] = MappingProxyType(
+            {mode: Decimal(value) for mode, value in by_mode.items()}
+        )
 
     def modes(self) -> tuple[BillingMode, ...]:
         return tuple(self._by_mode.keys())
 
-    def for_mode(self, mode: BillingMode) -> Decimal | None:
-        return self._by_mode.get(mode)
+    def for_mode(self, mode: BillingMode) -> ModeTaggedMoney | None:
+        value = self._by_mode.get(mode)
+        return None if value is None else ModeTaggedMoney(value, mode)
 
-    def items(self) -> tuple[tuple[BillingMode, Decimal], ...]:
-        return tuple(self._by_mode.items())
+    def items(self) -> tuple[tuple[BillingMode, ModeTaggedMoney], ...]:
+        return tuple((mode, ModeTaggedMoney(value, mode)) for mode, value in self._by_mode.items())
 
     def combine(self, other: MetricResult) -> MetricResult:
         """Merge two results of the same metric, within each billing mode only."""
@@ -55,6 +98,14 @@ class MetricResult:
             raise CrossBillingModeError(
                 f"cannot combine different metrics {self.metric_name!r} and {other.metric_name!r}"
             )
+        if self is other:
+            # Merging a result with itself doubles the run inside each mode, which
+            # is the same double count the cross-mode guard blocks, just wearing a
+            # different hat. Nothing legitimate combines a figure with itself.
+            raise CrossBillingModeError(
+                f"cannot combine metric {self.metric_name!r} with itself; "
+                "that would count the same spend twice"
+            )
         merged: dict[BillingMode, Decimal] = dict(self._by_mode)
         for mode, value in other._by_mode.items():  # noqa: SLF001 - same class
             merged[mode] = merged.get(mode, ZERO_USD) + value

{katalyst_forge-5.2.1 → katalyst_forge-5.4.0}/src/katalyst_forge/metrics/dashboard.py

@@ -16,10 +16,12 @@ from collections.abc import Mapping, Sequence
 from decimal import ROUND_HALF_UP, Decimal
 from typing import Final, cast
 
-from katalyst_forge.metrics.billing import BillingMode
+from katalyst_forge.metrics.billing import BillingMode, parse_billing_mode
 from katalyst_forge.metrics.core import MetricResult
 
 CENTS: Final[Decimal] = Decimal("0.01")
+ZERO_PERCENTAGE: Final[Decimal] = Decimal("0")
+FULL_PERCENTAGE: Final[Decimal] = Decimal("100")
 
 METERED_LABEL: Final[str] = "Metered spend"
 NOTIONAL_LABEL: Final[str] = "Subscription notional (not money spent)"
@@ -29,16 +31,77 @@ _MODE_LABELS: Final[Mapping[BillingMode, str]] = {
     BillingMode.SUBSCRIPTION_NOTIONAL: NOTIONAL_LABEL,
 }
 
+# What a figure IS, as distinct from the price basis it was computed on
+# (RIC-1645). BillingMode answers "which catalogue priced this"; it does not
+# answer "was this money billed". For a spend metric the two coincide, so the
+# basis label reads correctly. For a saving it does not: cache-savings is spend
+# avoided and routing-headroom was never incurred at all, yet both were captioned
+# "Metered spend" and charted under "dollars actually billed".
+QUANTITY_SPEND: Final[str] = "spend"
+QUANTITY_SAVING: Final[str] = "saving"
+QUANTITY_COUNTERFACTUAL: Final[str] = "counterfactual"
+QUANTITY_RATIO: Final[str] = "ratio"
+
+# An undeclared metric keeps the old caption, so a third-party bundle does not
+# silently change meaning on upgrade. The shipped catalogue cannot rely on that:
+# a test asserts every metric it ships declares a kind.
+DEFAULT_QUANTITY_KIND: Final[str] = QUANTITY_SPEND
+
+QUANTITIES_NOT_BILLED: Final[frozenset[str]] = frozenset({QUANTITY_SAVING, QUANTITY_COUNTERFACTUAL})
+
+_QUANTITY_LABELS: Final[Mapping[tuple[str, BillingMode], str]] = {
+    (QUANTITY_SPEND, BillingMode.METERED): METERED_LABEL,
+    (QUANTITY_SPEND, BillingMode.SUBSCRIPTION_NOTIONAL): NOTIONAL_LABEL,
+    (QUANTITY_SAVING, BillingMode.METERED): "Metered basis, spend avoided (not billed)",
+    (QUANTITY_SAVING, BillingMode.SUBSCRIPTION_NOTIONAL): (
+        "Notional basis, allocation avoided (not money spent)"
+    ),
+    (QUANTITY_COUNTERFACTUAL, BillingMode.METERED): (
+        "Metered basis, modelled and not captured (not billed)"
+    ),
+    (QUANTITY_COUNTERFACTUAL, BillingMode.SUBSCRIPTION_NOTIONAL): (
+        "Notional basis, modelled and not captured (not money spent)"
+    ),
+}
+
+
+def is_billed(quantity_kind: str | None) -> bool:
+    """Whether a figure of this kind is money that actually left the account."""
+    return (quantity_kind or DEFAULT_QUANTITY_KIND) not in QUANTITIES_NOT_BILLED
+
+
+def mode_label(mode: BillingMode, quantity_kind: str | None = None) -> str:
+    """Label a figure by what it is, not only by the catalogue that priced it.
+
+    Falls back to the bare basis label for any mode/kind pair not enumerated, so
+    a new billing mode degrades to naming its basis rather than asserting spend.
+    """
+    kind = quantity_kind or DEFAULT_QUANTITY_KIND
+    fallback = _MODE_LABELS.get(mode, str(mode))
+    return _QUANTITY_LABELS.get((kind, mode), fallback)
+
+
 _OPERATORS: Final[Mapping[str, str]] = {"<": "<", "<=": "<=", ">": ">", ">=": ">="}
 
+# A band with no declared mode is a spend threshold, because that is the only
+# quantity a dollar ceiling can sensibly police.
+_DEFAULT_BAND_MODE: Final[BillingMode] = BillingMode.METERED
+
 
 UNIT_USD: Final[str] = "usd"
 UNIT_PERCENTAGE: Final[str] = "percentage"
 
 
 def to_cents(value: Decimal) -> Decimal:
-    """Round to the cent, once, at the point of display."""
-    return value.quantize(CENTS, rounding=ROUND_HALF_UP)
+    """Round to the cent, once, at the point of display.
+
+    A value that rounds away to nothing is returned unsigned. Without this, a
+    drift of -2E-16 formats as "-0.00" and a dashboard shows "$-0.00", which reads
+    as a broken report rather than as two figures agreeing. The sign only survives
+    when there is a magnitude for it to describe.
+    """
+    cents = value.quantize(CENTS, rounding=ROUND_HALF_UP)
+    return abs(cents) if cents == 0 else cents
 
 
 def format_usd(value: Decimal) -> str:
@@ -46,7 +109,20 @@ def format_usd(value: Decimal) -> str:
 
 
 def format_percentage(value: Decimal) -> str:
-    return f"{to_cents(value)}%"
+    """Render a rate without letting rounding claim an endpoint it never reached.
+
+    A 99.998% cache hit rate quantizes to 100.00, which reads as "every billable
+    input token came from cache". The gap between nearly all and all is the whole
+    reason the rate is reported, so a value strictly inside the range keeps a
+    comparator instead of borrowing the endpoint. An exact 0 or 100 still prints
+    as itself.
+    """
+    rounded = to_cents(value)
+    if rounded >= FULL_PERCENTAGE > value:
+        return f">{FULL_PERCENTAGE - CENTS}%"
+    if rounded <= ZERO_PERCENTAGE < value:
+        return f"<{CENTS}%"
+    return f"{rounded}%"
 
 
 def format_value(value: Decimal, unit: str | None) -> str:
@@ -111,11 +187,27 @@ def _as_sequence(value: object) -> Sequence[object]:
     return ()
 
 
+def _entry_judges_mode(entry: Mapping[str, object], billing_mode: BillingMode | None) -> bool:
+    """A band judges one billing mode, and by default that mode is real money.
+
+    A threshold written for dollars actually billed must not stamp a verdict on a
+    subscription-notional allocation, which is a different quantity that happens
+    to share a unit. A caller that does not say which mode it is judging is not
+    filtered, so text callers keep their existing behaviour.
+    """
+    if billing_mode is None:
+        return True
+    declared = entry.get("billing_mode")
+    expected = parse_billing_mode(declared) if isinstance(declared, str) else _DEFAULT_BAND_MODE
+    return expected is billing_mode
+
+
 def evaluate_band(
     *,
     metric_name: str,
     value: Decimal,
     threshold_profile_doc: Mapping[str, object],
+    billing_mode: BillingMode | None = None,
     breach_bands: frozenset[str] = frozenset({"amber", "red"}),
 ) -> BandVerdict:
     """Find the band a value falls in and flag a breach (AC5).
@@ -130,6 +222,8 @@ def evaluate_band(
         entry_mapping = _as_mapping(entry)
         if entry_mapping.get("metric") != metric_name:
             continue
+        if not _entry_judges_mode(entry_mapping, billing_mode):
+            continue
         for band in _as_sequence(entry_mapping.get("bands")):
             band_mapping = _as_mapping(band)
             operator = band_mapping.get("operator")
@@ -153,7 +247,11 @@ def evaluate_band(
     )
 
 
-def render_savings_panel(result: MetricResult, unit: str | None = UNIT_USD) -> tuple[str, ...]:
+def render_savings_panel(
+    result: MetricResult,
+    unit: str | None = UNIT_USD,
+    quantity_kind: str | None = None,
+) -> tuple[str, ...]:
     """Render one line per billing mode, never a combined figure (AC10).
 
     Returns a line per mode rather than a total. There is deliberately no
@@ -162,7 +260,7 @@ def render_savings_panel(result: MetricResult, unit: str | None = UNIT_USD) -> t
     """
     lines: list[str] = []
     for mode, value in result.items():
-        label = _MODE_LABELS.get(mode, str(mode))
+        label = mode_label(mode, quantity_kind)
         lines.append(f"{label}: {format_value(value, unit)}")
     return tuple(lines)
 
@@ -173,24 +271,29 @@ def render_dashboard(
     results: Sequence[MetricResult],
     threshold_profile_doc: Mapping[str, object],
     units: Mapping[str, str] | None = None,
+    quantity_kinds: Mapping[str, str] | None = None,
 ) -> str:
     """Render the whole dashboard as text, per metric and per billing mode.
 
     `units` maps a metric name to its declared unit so a ratio is never
-    rendered with a dollar sign.
+    rendered with a dollar sign. `quantity_kinds` maps a metric name to what its
+    figure is, so a saving is not captioned as spend.
     """
     unit_by_metric = units or {}
+    kind_by_metric = quantity_kinds or {}
     lines: list[str] = [f"Run: {run_id}", ""]
 
     for result in results:
         unit = unit_by_metric.get(result.metric_name, UNIT_USD)
+        kind = kind_by_metric.get(result.metric_name)
         lines.append(result.metric_name)
         for mode, value in result.items():
-            label = _MODE_LABELS.get(mode, str(mode))
+            label = mode_label(mode, kind)
             verdict = evaluate_band(
                 metric_name=result.metric_name,
                 value=value,
                 threshold_profile_doc=threshold_profile_doc,
+                billing_mode=mode,
             )
             suffix = ""
             if verdict.band_name is not None:
@@ -212,3 +315,21 @@ def units_from_metric_definitions(
         if isinstance(unit, str):
             units[name] = unit
     return units
+
+
+def quantity_kinds_from_metric_definitions(
+    metric_definitions: Mapping[str, Mapping[str, object]],
+) -> dict[str, str]:
+    """Read each metric's declared quantity kind from the audited catalogue.
+
+    Kept in the definitions rather than the renderer for the same reason units
+    are: whether a figure is spend or a saving is a property of the metric, and a
+    renderer that decided it locally could disagree with the document the figure
+    was computed from.
+    """
+    kinds: dict[str, str] = {}
+    for name, doc in metric_definitions.items():
+        kind = _as_mapping(doc.get("spec")).get("quantity_kind")
+        if isinstance(kind, str):
+            kinds[name] = kind
+    return kinds

{katalyst_forge-5.2.1 → katalyst_forge-5.4.0}/src/katalyst_forge/metrics/errors.py

@@ -120,3 +120,23 @@ class ProviderPayloadError(MetricsAdapterError):
 
     def __init__(self, *, field: str, value: object) -> None:
         super().__init__(f"unparseable provider payload for {field!r}: {redact(value)}")
+
+
+class ProviderTransportError(Exception):
+    """Raised when a provider request fails before any payload exists.
+
+    Deliberately NOT a MetricsAdapterError. The per-source and per-metric
+    handlers skip a MetricsAdapterError and carry on, which is right for a
+    source that cannot be computed but wrong for a host that cannot be reached:
+    that leaves a hole of unknown size, so it has to stay a hard failure and
+    reach the entry point.
+
+    Carries the endpoint rather than a bare status line, because an operator
+    reading the failure needs to know which request died. Only the URL and the
+    exception type are used; no response body reaches the message.
+    """
+
+    def __init__(self, *, url: str, detail: str) -> None:
+        self.url = url
+        self.detail = detail
+        super().__init__(f"request to {url} failed: {detail}")

katalyst_forge-5.4.0/src/katalyst_forge/metrics/forge_stages.py

@@ -0,0 +1,61 @@
+"""The canonical Forge lifecycle stages, defined once.
+
+The eleven names were spelled out in the OpenCode stage-matching pattern and
+again in the run report that preceded this module, which is how a stage list
+drifts. Everything that needs them now reads them from here.
+
+The distinction between attributed and executed matters and is kept in the
+vocabulary: a stage is ATTRIBUTED when a session's agent name or title implies
+it. That is a heuristic over names, not evidence that a gate ran, so nothing here
+claims an unobserved stage did not happen.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Final
+
+__all__ = ("FORGE_STAGES", "STAGE_PATTERN", "infer_stage_from_text")
+
+FORGE_STAGES: Final[tuple[str, ...]] = (
+    "design",
+    "orchestrate",
+    "review",
+    "implement",
+    "qa",
+    "commit",
+    "deploy",
+    "verify",
+    "release",
+    "operate",
+    "feedback",
+)
+
+# The agent form is matched first and separately from the bare word. A session
+# titled "review the PR" is a much weaker signal than an agent literally named
+# kata-forge-review, and the caller is told which one matched so the report can
+# say so instead of presenting both as equal evidence.
+_AGENT_FORM: Final[str] = r"\bkata-forge-([a-z-]+)\b"
+_BARE_WORD: Final[str] = r"\b(" + "|".join(FORGE_STAGES) + r")\b"
+
+STAGE_PATTERN: Final[re.Pattern[str]] = re.compile(f"{_AGENT_FORM}|{_BARE_WORD}", re.IGNORECASE)
+
+
+def infer_stage_from_text(text: str) -> tuple[str | None, bool]:
+    """Return (stage, matched_agent_form).
+
+    matched_agent_form is what lets the report distinguish a stage read off an
+    agent name from one guessed out of prose.
+    """
+    found = STAGE_PATTERN.search(text)
+    if found is None:
+        return None, False
+    agent_form = found.group(1)
+    if agent_form:
+        stage = agent_form.lower()
+        # kata-forge-qa-lead implies the qa stage; keep the longest known prefix.
+        for candidate in FORGE_STAGES:
+            if stage == candidate or stage.startswith(f"{candidate}-"):
+                return candidate, True
+        return None, True
+    return found.group(2).lower(), False