sourcecode 5.8.1__py3-none-any.whl → 5.8.2__py3-none-any.whl

sourcecode/__init__.py

@@ -4,4 +4,4 @@ ASK Engine is the product. ``ask`` is the canonical CLI command; ``sourcecode``
 the legacy compatibility alias and the Python/PyPI package name. See
 docs/PRODUCT_IDENTITY.md (normative)."""
 
-__version__ = "5.8.1"
+__version__ = "5.8.2"

sourcecode/_docs/DEFECT-LEDGER.md

@@ -45,6 +45,11 @@ The facts these rows are keyed to are published: `ask schema facts-v1` prints th
 | ASK-12 | **A field describing an exclusion named three production trees as excluded.** `spring-audit spring-boot` published `patterns_matched: [… "core/", "module/", "cli/" …]` — 4 254 + 1 625 + 76 production files. Read literally, whole modules had left the audit population; measured, the exclusion was *conservative* (3 650 excluded against 4 214 files actually under a test root). The auditor filed an over-exclusion false positive on the strength of the field and then withdrew it. Cause: the constructor's fallback named `parts[0]`, the first path segment, when no source-root marker matched — and the same published field had **two constructors** with different shapes and different `basis` strings (`cli.py` for `spring-audit`, `repository_ir.py` for `endpoints`) over the one authority both already shared. | 5.7.2 audits | Low — a reporting defect, not an exclusion one, which is why it cost an auditor a round instead of costing a finding | **closed 5.8.1** — one producer, `repository_ir.excluded_test_source_detail`, beside `is_test_source_file`, which is the authority that decides the fact. `patterns_matched` can now only hold a **declared test root** — a directory whose files are excluded in their entirety — and everything else is published as a `rules_matched` census with a `rules_meaning` sentence per rule, so a per-file rule can no longer be read as a whole-directory claim. A surface counting something other than files says so (`unit`, `files_matched`), because `endpoints` counts route annotations. Regression `tests/test_test_source_exclusion_one_producer_ask12.py`, 14 assertions, two of them structural: `cli.py` may not compose the key at all, and exactly one function in `repository_ir.py` may (AST-checked). |
 | B14 | **`--compact` made the answer smaller by making it unattributable.** `cold-start --compact` took 1 968 807 characters to 16 452 (−99,2 %) and removed **11 of 19 keys** on the way — `schema_version`, `repo_id`, `current_git_head` and the 331-character `hotspots` among them — in a document whose weight was **97,7 % `endpoints`**, and cut the endpoint list to 30 with no `*_cap`. The view an agent is told to inject could not say which repository, which commit or which schema it described. | 5.6.1 audit; AS-15 closed the root `--compact` half in 5.7.0, this is the `cold-start` half, re-reported against 5.8.0 | High | **closed 5.8.1** — three rules, in the shared bound rather than invented per command. `COMPACT_IMMUTABLE_KEYS` is the minimum no `--compact` may remove (provenance is contract, not content). Every collection that was cut declares `{total, shown, omitted}` with the registered effect — measured on BroadleafCommerce, `endpoints_cap` now publishes `total: 272, shown: 30, omitted: 242` where the cut was silent. And trimming goes by **weight**: a section already under 2 KB is kept rather than dropped by a fixed list, which is what recovers `hotspots`; everything actually removed is named with its size in `compact_omitted`. Regression `tests/test_compact_keeps_identity_b14.py`, 12 assertions, including that nothing removed claims nothing. |
 | B2 | **A risk band and a rule severity share a vocabulary and measure different things.** They disagreed on **34 of 50 rows (68 %)** — 5 defects rated `medium` band as `critical`, 29 rated `high` band as `medium` — and both numbers were right: severity is what the rule says about the defect, the band is what the composition says about it in *this* repository (reach, access, write effect). One surface on, the collision became a contradiction a reader could not resolve: `audit-report` announced **14 critical** over bands while `--min-severity critical` filtered severities and returned **0**. | 5.6.1 audit, reproduced through 5.8.0 | Medium | **closed 5.8.1** — the band now also has a name that cannot be mistaken for a severity: `risk_tier: R1…R5`, published **beside** `band` and never instead of it, so no consumer loses a field it reads. One mapping (`risk_model.tier`), one sentence (`TIER_CROSSWALK_NOTE`) travelling with every count — it names both axes, states that they disagree by construction, gives the crosswalk, and points at `--min-band` as the flag that filters tiers rather than `--min-severity`. `risk` publishes `by_tier` beside `by_band`; `audit-report` leads with tiers, keeps bands under the legacy spelling, renders the note, and derives tiers from bands when it is handed an older bundle. Regression `tests/test_risk_tier_is_not_a_severity_b2.py`, 12 assertions, including that no tier shares a spelling with any severity and that a summary with no census still says *not measured* rather than zero. ⚠ The row's `reach`/`access`/`score_raw` per row was already shipped (`factors`, `endpoints_reached`, `reach_scope`); `--min-band` already existed on `risk` and `enrich`. |
+| B11 | **A boolean about the working tree was published without the unit it was measured in.** The field read `has_uncommitted_changes: false` in the same terminal where `git status --porcelain` had just printed `?? .claude/settings.json`, with no `_basis` and no unit beside it. The rule is right and stays: C1-27 decided that a change under an editor or agent state directory is not a change to the code, because no analyser opens those files, and counting it reported STALE on a snapshot that described the tree exactly with `Delta: 0` next to it. What the payload could not do was *say* it — with no basis, "no changes" and "changes I did not count" are the same three characters, and the only way to tell them apart was to read the source. | 5.6.1 audit, inherited | Low — a disclosure defect over a correct rule, which is why it cost a reader's trust rather than a wrong answer | **closed 5.8.1** — the boolean now travels with the census that explains it. One producer, `baseline_autocapture.worktree_dirty_detail`: one `git status --porcelain -uall`, every path it prints classified once by `dirty_exclusion_reason`, and `{dirty, counted, excluded, excluded_by, basis}` out. `worktree_dirty` is that dict read as a boolean and `counts_as_dirty` is the same rule read as a predicate, so the three cannot drift — the C1-44 shape, kept. The `basis` names the command a reader can check it against and reconciles with it: `counted + excluded` is exactly what `git status` printed (asserted), and each exclusion carries its sentence from `EXCLUSION_REASONS` rather than a bare key. **`false` and "not checked" stopped being the same answer**: a non-git directory publishes *"not a git worktree: the working tree could not be compared to HEAD"* instead of a confident `false`, and a run whose own scan measured the dirtiness says which source answered. Published as `has_uncommitted_changes_basis` at every site that prints the boolean — `cold-start` and its `_cache` block (both CLI paths through `_cache_meta_block`, plus the RIS bootstrap), and the MCP `check_freshness` tool with its docstring corrected. Regression `tests/test_uncommitted_changes_basis_b11.py`, 14 assertions, including the reported pair end-to-end and the reconciliation against `git status`. |
+| P1 / F-BR | **Every comparison the release gate made was a ratio, and a cost that was always too high never regresses.** `validation` went 13,8 → 34,1 → 39,5 s across three releases with no single step over the 20 % threshold, so the gate was green at every step and the product shipped a staircase. The row also carried two prescribed cache-reuse assertions that the field **refuted with its own measurements** before either was implemented: `samples[0]/samples[-1] > 1,5` reads only the ends of the series and passes 5.6.1, and `median(samples)/min(samples) < 1,5` scores shape rather than cost and therefore awards **5.5.5, the worst release of the six, a perfect mark** — flat-and-slow (nothing cached, 80 s) and flat-and-fast (everything cached, 30 s) are the same ratio. | 5.7.2 audits (`P1`, `B7`), with the third formulation validated by the field against six measured releases | Medium — the detector gap that let a ×15,7 regression ship (C3-120), compounded by a documented instruction to build the wrong detector | **closed 5.8.1** — a second axis, `perf.absolute_cost_report`, published under `absolute_cost` in the gate report and able to turn the verdict red on its own. Two assertions: a **declared ceiling per command** (`RELEASE_GATE_ABSOLUTE_WARM_MS`, each published beside the mark it was calibrated against at 5.7.2, because a limit nobody can audit against a measurement is just a number), and the **anchored** one the field validated — `max(sample) < 8 × posture_warm`, with the anchor measured *in the same run* so a slower runner moves the limit with it and the number stays a claim about the product rather than about the machine CI allocated. Scope is enforced rather than assumed: a ceiling calibrated on ~3 300 files takes no part on another corpus, and cold cells still do not decide (C3-108). **The two refuted formulations are carried in the source** (`REFUTED_REUSE_FORMULATIONS`) with the counter-example that killed each, and the battery replays both refutations plus the six-release validation table (`ANCHOR_MULTIPLE_VALIDATION`), so a later change to the multiple cannot quietly stop discriminating — the multiple is asserted to sit between the worst pass (6,2×) and the best fail (8,5×). `--self-test` gained two reds, because a green gate is evidence only when a red one is reachable on the same constants. Regression `tests/test_absolute_cost_gate_p1.py`, 25 assertions, including the staircase end-to-end: ratio axis green, release red. ⚠ The rest of F-BR — a synthetic ~200 KB / ~5 000-call fixture timing `build_sql_taint`, and warm cells for the composition family in the gate baseline — is **not** in this row and stays open; and C3-113 still applies, since the gate's release path is triggered by a tag and no release since `v5.2.0` carries one. |
+| ASK-11 | **A correct decision announced only by the error message of the run it broke.** The unified output ceiling turned `exit 0` into `exit 1` for invocations that returned data one minor earlier — `endpoints tutorials` (987 141 B ≈ 247 K tokens), `endpoints thingsboard` (318 380 B), `posture spring-boot` (355 032 B on 8 667 files). The decision is not in dispute and is not being revisited: 247 K tokens printed into an agent's context window was worse than a refusal. The defect is the **mode of disclosure** — the trigger is repository size rather than a flag, so an invocation that fits today stops fitting on a bigger repository or after a release that detects more, and the failure lands as `exit 1`, which stops a CI build. | 5.7.2 audits — filed by the field as *"cambio incompatible, no defecto"* | Medium — a release-policy defect: nothing was wrong with the run, only with what could be known before it | **closed 5.8.1** — treated as the policy it is, not as a changelog line. `sourcecode.breaking_changes` declares the change with what a reader planning an upgrade actually needs: the exit code on both sides, the trigger, the **compatibility route** (`ASK_MAX_OUTPUT_TOKENS=0`, which restores pre-5.7.0 behaviour exactly, for the pipeline that is red right now) and the **remedy** (a bounding flag, or `--output FILE`, for when there is time) — in that order, because an upgrade note offering only the principled fix is one a reader skips. "A large repository" is given its sizes: the three field invocations are carried with their measured bytes. Three surfaces, all derived from that one declaration: `ask schema breaking-changes-v1` prints it, a `## Upgrading` section sits above the release history in the CHANGELOG, and **every affected command names the ceiling in its `--help`** — the population derived from the CLI registry (all commands minus `COMMANDS_WITHOUT_COPY`, the existing authority for "stdout is a confirmation, not an answer"; a confirmation cannot reach a 50K-token ceiling), never a hand-written list, since the list is exactly what a reader is told to trust. The battery enforces the **policy**: a declared change must move an exit code, carry both routes, name its invocations with measurements, and reach the changelog. Regression `tests/test_breaking_change_disclosure_ask11.py`, 95 assertions (one per affected command, parametrised from the live registry). ⚠ Found and fixed on the way: `version` published `registries: ["facts-v1"]` as a literal while `schema` derived its list, under a comment promising the two could not disagree — the second registry made them disagree. Both read `published_registries()` now. |
+| ASK-13 | **A floor that could be anything, in the sentence whose job is to size the work.** `cache warm tutorials` reported *"This repository: at least 8 418 Java files, cache warm"* about a repository holding **24 073** — a third of the truth — and *"at least 8 401"* on `spring-boot` against 8 667. The two land near each other for one reason: the walk stops after 25 000 **directory entries**, not after 25 000 Java files, so a tree with ordinary amounts of non-Java content exhausts the budget at roughly the same place however much Java it holds. `at least` was honest about the direction of the error and silent about its size, which is exactly what made it useless here. | 5.7.2 audits | Low — the count is a floor and says so; what it could not say was how far a floor it is | **closed 5.8.1** — the second of the two outcomes the acceptance allows: the cap stays (this count runs while somebody waits for `--help` to render) and **names itself**. The message now reads *"at least 8 418 Java files (the scan stopped at 25 000 directory entries, so the repository holds more)"*, with the unit named, because "entries" and "Java files" being different units is the whole reason the number saturates where it does. A cap that did **not** bind is not mentioned at all — it is not part of that count's basis, and naming it would suggest it was. ⚠ **A second half that is not a message, found while measuring the first**: `Scope.large` answered `False` from a saturated count, so a repository whose first 25 000 entries held few sources was advised as *small* — and the class had already written the correct rule in prose (*"a capped count below it is not [enough]"*) while the code ignored it. `size_decided` now separates the two cases a floor supports: above the threshold a capped count still decides (more files only make `large` more true), below it decides nothing, and the cost verdict answers `unknown` with its reason rather than guessing the cheap regime. Also fixed on the way: `count_java_files` takes its cap as a **default argument**, bound at definition time, so `measure_scope` now passes it explicitly — otherwise the cap that bound the walk and the cap the message names could drift into a published falsehood. Regression `tests/test_scan_cap_names_itself_ask13.py`, 13 assertions, including a tree shaped like the field's (many entries, few sources). |
+| B6 | **Fourteen `schema_version` values in payloads and not one of them resolvable.** `ask schema verify-v1` answered *invalid* about a string this tool had just printed; `endpoints` emitted no version at all; and the spellings did not agree — `<domain>-v1` beside a bare `1.0`, a `1.1`, a `1.2`, a `1.0.0`, a `2.1` and a `0.1-experimental`. A version identifier a consumer cannot look up is a string, not a contract. | 5.6.1 audits, inherited | Medium — every consumer that pins a shape pins it on one of these | **closed 5.8.1** — `sourcecode.schema_registry` names **every** `schema_version` this release can emit (50 entries over 44 distinct identifiers, 13 of them non-conforming) with what it versions, which module defines it, which commands carry it, and whether a JSON Schema document exists behind it. `ask schema <value>` resolves all of them: a documented identifier still prints its schema, and one without a document resolves to its entry rather than to a rejection — which is what it honestly is, a named versioned shape with no formal document yet, said plainly instead of implied away. `endpoints` gained `endpoints-v1`, the version it never had. **The population is checked against the source, not maintained by hand**: the battery walks `src/sourcecode` by AST and fails when a `schema_version` literal or a `*SCHEMA*` constant is not named by the registry, and it also verifies the registry's own claims — the module and constant each entry cites must really hold that value (this caught one wrong `source` while it was being written). **The finding the field could not have made from outside**: `1.0` is not a schema. **Seven** unrelated shapes spell their version that way — the root analysis, `impact-chain`, `pr-impact`, migration blast, Spring impact, event topology and test-gap ranking — so `resolve()` returns all seven and publishes the identifier as ambiguous rather than picking one, and every ambiguous entry must offer a canonical name to pin instead (asserted). **The `<domain>-v<N>` migration is declared, not applied**: renaming an emitted `schema_version` changes a payload consumers pin on, which is precisely the incompatible change `breaking-changes-v1` exists to stop us making in silence, so each non-conforming identifier carries the name it should become and the battery asserts none of them was quietly renamed in this release. `schema --help` documents the mapping and the `1.0` trap. Regression `tests/test_schema_registry_resolves_b6.py`, 66 assertions. ⚠ Writing the 40-odd JSON Schema documents themselves is **not** in this row and stays open; what closed is resolvability, which is what the row was filed for. |
 
 ---
 

sourcecode/_docs/USER_GUIDE.md

@@ -136,7 +136,7 @@ pipx install sourcecode   # isolated install, no venv needed
 
 # Verify
 ask version
-# ask 5.8.1
+# ask 5.8.2
 ```
 
 Requires Python 3.9+.

sourcecode/baseline_autocapture.py

@@ -36,7 +36,7 @@ import os
 import subprocess
 from dataclasses import dataclass
 from pathlib import Path
-from typing import TYPE_CHECKING, Iterable, Optional
+from typing import TYPE_CHECKING, Any, Iterable, Optional
 
 if TYPE_CHECKING:  # pragma: no cover - typing only
     from sourcecode.canonical_ir import CanonicalRepositoryIR
@@ -198,6 +198,62 @@ def worktree_dirty(
 
     Nothing else is excused, because everything else is what the baseline measures.
     """
+    detail = worktree_dirty_detail(root, ignore=ignore)
+    return None if detail is None else detail["dirty"]
+
+
+#: The reason a path git reports as changed does not make the tree dirty. Keys are
+#: stable (they are published); the sentences are what a reader is owed.
+EXCLUSION_REASONS: "dict[str, str]" = {
+    "tool-state-directory": (
+        "under an editor or agent state directory (.claude/, .idea/, .vscode/, …) "
+        "that no analyser opens"
+    ),
+    "own-footprint": "this tool's own output, which the run wrote itself",
+}
+
+
+def dirty_exclusion_reason(
+    path: str, *, own_prefixes: "Iterable[str]" = ()
+) -> "Optional[str]":
+    """Why *path* does not count as a modification, or None when it does count.
+
+    The one place the rule lives. `counts_as_dirty` is this predicate read as a
+    boolean, and `worktree_dirty_detail` is it read as a census — B11 was filed
+    because the boolean was published with neither its unit nor this reason, so
+    `has_uncommitted_changes: false` sat beside a `?? .claude/settings.json` that
+    `git status` had just printed and the payload could not explain the pair.
+    """
+    from sourcecode.path_filters import analysis_reads
+
+    if not analysis_reads(path):
+        return "tool-state-directory"
+    probe = str(path).replace("\\", "/").rstrip("/") + "/"
+    if any(probe.startswith(prefix) for prefix in own_prefixes):
+        return "own-footprint"
+    return None
+
+
+def worktree_dirty_detail(
+    root: Path, ignore: "Optional[Path | Iterable[Path]]" = None
+) -> "Optional[dict[str, Any]]":
+    """The boolean `worktree_dirty` publishes, with the census that explains it.
+
+    One `git status` call, every path it prints classified once. Returns None when
+    the state could not be determined, which is the same contract as the boolean.
+
+    C1-27. "Dirty" means the tree *the analysis reads* differs from HEAD. A change
+    under an editor or agent state directory is not one — no analyser opens those
+    files — and counting it reported STALE on a snapshot that described the tree
+    exactly, with `Delta: 0` beside it. One authority answers which paths qualify
+    (`path_filters.analysis_reads`) and its default is inclusive: anything not
+    named there still counts, because a missed change is a false *fresh* and a
+    spurious one only costs a rebuild.
+
+    B11: that rule is right and was invisible. The `excluded` census and `basis`
+    below are what makes `false` checkable against the reader's own `git status`
+    without running the analyser — the count is named, and so is the reason.
+    """
     try:
         out = subprocess.run(
             # `-uall` because git collapses an untracked directory to one entry
@@ -210,13 +266,6 @@ def worktree_dirty(
         return None
     if out.returncode != 0:
         return None
-    # C1-27. "Dirty" means the tree *the analysis reads* differs from HEAD. A
-    # change under an editor or agent state directory is not one — no analyser
-    # opens those files — and counting it reported STALE on a snapshot that
-    # described the tree exactly, with `Delta: 0` beside it. One authority answers
-    # which paths qualify (`path_filters.analysis_reads`) and its default is
-    # inclusive: anything not named there still counts, because a missed change
-    # is a false *fresh* and a spurious one only costs a rebuild.
     prefixes: list[str] = []
     if ignore is not None:
         candidates = [ignore] if isinstance(ignore, (str, Path)) else list(ignore)
@@ -229,10 +278,45 @@ def worktree_dirty(
             except ValueError:  # outside the repo (`--dir`): nothing of it to drop
                 continue
             prefixes.append(rel.rstrip("/") + "/")
-    return any(
-        counts_as_dirty(_porcelain_path(ln), own_prefixes=prefixes)
-        for ln in out.stdout.splitlines() if ln.strip()
+
+    counted = 0
+    excluded_by: "dict[str, int]" = {}
+    for line in out.stdout.splitlines():
+        if not line.strip():
+            continue
+        reason = dirty_exclusion_reason(_porcelain_path(line), own_prefixes=prefixes)
+        if reason is None:
+            counted += 1
+        else:
+            excluded_by[reason] = excluded_by.get(reason, 0) + 1
+
+    excluded = sum(excluded_by.values())
+    return {
+        "dirty": counted > 0,
+        "counted": counted,
+        "excluded": excluded,
+        "excluded_by": excluded_by,
+        "basis": _dirty_basis(counted, excluded_by),
+    }
+
+
+def _dirty_basis(counted: int, excluded_by: "dict[str, int]") -> str:
+    """The sentence that names the unit of the boolean, and the paths it dropped.
+
+    Always names the unit, because "0 excluded" and "the field means every path
+    git prints" are different claims and only one of them is true.
+    """
+    unit = (
+        f"{counted} of {counted + sum(excluded_by.values())} path(s) reported by "
+        "`git status --porcelain -uall` are changes the analysis reads"
+    )
+    if not excluded_by:
+        return unit + "; none were excluded."
+    dropped = "; ".join(
+        f"{n} {EXCLUSION_REASONS.get(reason, reason)}"
+        for reason, n in sorted(excluded_by.items())
     )
+    return f"{unit}. Excluded: {dropped}."
 
 
 def counts_as_dirty(path: str, *, own_prefixes: "Iterable[str]" = ()) -> bool:
@@ -248,12 +332,7 @@ def counts_as_dirty(path: str, *, own_prefixes: "Iterable[str]" = ()) -> bool:
 
     `own_prefixes` are repository-relative directory prefixes ending in `/`.
     """
-    from sourcecode.path_filters import analysis_reads
-
-    if not analysis_reads(path):
-        return False
-    probe = str(path).replace("\\", "/").rstrip("/") + "/"
-    return not any(probe.startswith(prefix) for prefix in own_prefixes)
+    return dirty_exclusion_reason(path, own_prefixes=own_prefixes) is None
 
 
 def own_footprint_prefixes(root: Path) -> "list[str]":

sourcecode/breaking_changes.py

@@ -0,0 +1,163 @@
+"""Changes that turn `exit 0` into `exit 1`, declared where a reader can find them.
+
+ASK-11. The unified output ceiling was the right call — 247 K tokens of silence
+was worse than a refusal — but it changed the exit code of invocations that had
+returned data one minor earlier, and `exit 1` in CI stops a build. A correct
+decision announced only in a changelog line is still a script that breaks at 3am
+on somebody else's pipeline.
+
+The rule this module exists to enforce is a policy, not a fix:
+
+    a change that turns `exit 0` into `exit 1` is a **breaking change**, and it
+    is discoverable *before* it fires — from `--help`, from a command, and from
+    the release notes — never only from the error message of the run it broke.
+
+That is why the population is derived rather than listed. A hand-written
+catalogue of affected commands beside a registry drifts the moment a command is
+added, and a reader who trusts it is worse off than one who trusts nothing.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass(frozen=True)
+class BreakingChange:
+    """One change in behaviour a caller can be broken by, and the way out.
+
+    `compatibility` is the switch that restores the old behaviour *now*, for
+    somebody whose pipeline is red while they read this. `remedy` is what to do
+    instead, once there is time to do it properly. Both, in that order: an
+    upgrade note that only offers the principled fix is one a reader skips.
+    """
+
+    id: str
+    released_in: str
+    title: str
+    what_changed: str
+    exit_code_before: int
+    exit_code_after: int
+    trigger: str
+    compatibility: str
+    remedy: str
+    #: What the field actually measured, so "large repository" has a size.
+    observed: tuple[tuple[str, str], ...] = field(default_factory=tuple)
+
+    def as_payload(self) -> "dict[str, object]":
+        return {
+            "id": self.id,
+            "released_in": self.released_in,
+            "title": self.title,
+            "what_changed": self.what_changed,
+            "exit_code_before": self.exit_code_before,
+            "exit_code_after": self.exit_code_after,
+            "trigger": self.trigger,
+            "compatibility": self.compatibility,
+            "remedy": self.remedy,
+            "observed": [
+                {"invocation": inv, "measured": measured}
+                for inv, measured in self.observed
+            ],
+        }
+
+
+#: The output ceiling. Filed by the field as ASK-11 against 5.7.0, which is the
+#: release that unified the guard; the report upgraded from 5.6.1, where these
+#: three invocations returned their payload with `exit 0`.
+OUTPUT_CEILING = BreakingChange(
+    id="BC-001",
+    released_in="5.7.0",
+    title="stdout over the output ceiling exits 1 instead of printing",
+    what_changed=(
+        "Before 5.7.0 the ~50K-token ceiling existed on `migrate-check` and "
+        "`repo-ir` only, so the same size was refused by one command and printed "
+        "in silence by another (AS-09). The guard is now one policy applied at "
+        "the single emit seam, which is the correct behaviour and a different "
+        "one: an answer that does not fit is refused with a hint instead of "
+        "flooding the caller."
+    ),
+    exit_code_before=0,
+    exit_code_after=1,
+    trigger=(
+        "any command whose stdout payload exceeds the ceiling — reached by "
+        "repository size, not by a flag, so the same command that fits today "
+        "can stop fitting on a larger repository or after a release that "
+        "detects more"
+    ),
+    compatibility=(
+        "ASK_MAX_OUTPUT_TOKENS=0 (or --max-output-tokens 0) restores the "
+        "pre-5.7.0 behaviour exactly: the guard is off and the whole payload is "
+        "printed. Set it in the pipeline that broke, then take the remedy at "
+        "leisure. Any other value moves the ceiling rather than removing it."
+    ),
+    remedy=(
+        "a bounding flag keeps the answer where the reader is — `--compact`, "
+        "`--limit N`, `--top-n N` or `--min-severity`, whichever the command "
+        "declares; `--output FILE` writes the whole payload to disk and is not "
+        "subject to the stdout ceiling at all. The error message names the ones "
+        "this invocation has not already used."
+    ),
+    observed=(
+        ("endpoints tutorials", "987 141 B — ~247 K estimated tokens"),
+        ("endpoints thingsboard", "318 380 B"),
+        ("posture spring-boot", "355 032 B on 8 667 Java files"),
+    ),
+)
+
+#: Every declared breaking change, newest first. A release that turns `exit 0`
+#: into `exit 1` and does not add a row here fails `tests/test_breaking_change_
+#: disclosure_ask11.py` — the policy is enforced, not remembered.
+BREAKING_CHANGES: tuple[BreakingChange, ...] = (OUTPUT_CEILING,)
+
+
+def help_note(change: BreakingChange = OUTPUT_CEILING) -> str:
+    """The `--help` line for a command the change can fire on.
+
+    Short on purpose: a help epilog that explains the whole policy is one nobody
+    reads. It names the limit, the exit code and the switch — the three facts
+    somebody scanning `--help` before writing a pipeline needs — and points at
+    the command that prints the rest.
+    """
+    from sourcecode.output_ceiling import DEFAULT_CEILING_TOKENS, ENV_CEILING
+
+    return (
+        f"Output ceiling: a stdout answer over ~{DEFAULT_CEILING_TOKENS // 1000}K "
+        f"estimated tokens exits {change.exit_code_after} with a hint instead of "
+        f"printing (changed in {change.released_in}). {ENV_CEILING}=0 restores "
+        f"the old behaviour; `ask schema breaking-changes-v1` explains it."
+    )
+
+
+def affected_commands(
+    all_commands: "set[str]", not_an_answer: "set[str]"
+) -> "list[str]":
+    """The commands the output ceiling can fire on, derived rather than listed.
+
+    `not_an_answer` is the population whose stdout is a confirmation that an
+    effect happened rather than an answer worth keeping — the same authority
+    `--copy` is decided by. A confirmation cannot reach a 50K-token ceiling, and
+    everything else can, because the guard sits at the one emit seam they all
+    pass through.
+
+    Deriving it is the point. A hand-written list of affected commands beside
+    the registry drifts on the next command added, and this list is what a
+    reader is told to trust.
+    """
+    return sorted(all_commands - not_an_answer)
+
+
+def as_payload(changes: "tuple[BreakingChange, ...]" = BREAKING_CHANGES) -> dict:
+    """The machine-readable form, for the CLI surface and for an agent."""
+    return {
+        "schema_version": "breaking-changes-v1",
+        "policy": (
+            "A change that turns `exit 0` into `exit 1` is a breaking change. It "
+            "is declared here, named in the `--help` of every command it can fire "
+            "on, and carried in the release notes with the invocations that "
+            "change and the size at which they change — so an upgrade can be "
+            "planned rather than discovered by a red pipeline."
+        ),
+        "count": len(changes),
+        "changes": [c.as_payload() for c in changes],
+    }