sourcecode 4.11.0__py3-none-any.whl → 4.12.0__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__ = "4.11.0"
+__version__ = "4.12.0"

sourcecode/architectural_baseline.py

@@ -30,6 +30,7 @@ the perf baselines do.
 from __future__ import annotations
 
 import json
+import os
 import subprocess
 from datetime import datetime, timezone
 from pathlib import Path
@@ -365,21 +366,40 @@ def _baseline_filename(baseline: dict) -> str:
 #: a 14 587-entry structural inventory of the code. A self-confined
 #: `.ask/.gitignore` is the honest form: it never touches the user's own
 #: `.gitignore`, and it stops applying the moment they delete the directory.
+#: C3-74 corrected the last line. It used to read *"Delete this file to version
+#: them deliberately"*, and deleting it is the one action that would commit a
+#: baseline carrying `env.hostname_hash`, `cpu` and `cores` — an invitation to do
+#: the thing the file exists to prevent. It now states the consequence instead.
 _ASK_DIR_GITIGNORE = (
     "# Written by `ask` the first time it created this directory.\n"
     "# These are local analysis artefacts: a structural inventory of your code\n"
     "# and, if you asked for it, the machine that measured it. Nothing here\n"
-    "# belongs in a commit. Delete this file to version them deliberately.\n"
+    "# belongs in a commit.\n"
+    "#\n"
+    "# Removing this file makes everything here committable, including any\n"
+    "# recorded machine fingerprint (`--record-env`: hostname hash, CPU, cores).\n"
+    "# Version these deliberately only if you intend to publish that.\n"
     "*\n"
 )
 
 
-def protect_ask_dir(out_dir: Path) -> None:
+def protect_ask_dir(out_dir: Path, *, announce: bool = True) -> None:
     """Give a freshly created `.ask/` its own `.gitignore` (C3-68).
 
     Best-effort and never overwriting: a user who edited it decided something,
     and a tool that re-imposes its default on every run is worse than one that
     never wrote it.
+
+    **Call this where the write happens, never where the path is computed.** This
+    function *creates* the directory in order to protect it, so calling it
+    speculatively is a write — which is how `migrate-check` came to leave a
+    `.ask/.gitignore` inside a repository it had only read (C3-74).
+
+    `announce` puts one line on stderr the first time the directory is created,
+    with its path. A side effect inside somebody else's repository is exactly what
+    I-8 says must be declared, and this one hides from the check an auditor makes:
+    `git status --porcelain` is clean because the ignore file ignores itself, and
+    only `--ignored` reveals `!! <scope>/.ask/`.
     """
     try:
         ask_dir = Path(out_dir)
@@ -391,12 +411,35 @@ def protect_ask_dir(out_dir: Path) -> None:
             return
         marker = ask_dir / ".gitignore"
         if not marker.exists():
+            created = not ask_dir.exists()
             ask_dir.mkdir(parents=True, exist_ok=True)
             marker.write_text(_ASK_DIR_GITIGNORE, encoding="utf-8")
+            if announce and created:
+                _announce_ask_dir(ask_dir)
     except OSError:
         return
 
 
+def _announce_ask_dir(ask_dir: Path) -> None:
+    """One line, on stderr, naming what was created and how to move it (C3-74)."""
+    import sys
+
+    try:
+        # No flag is named here on purpose: the commands that write under `.ask/`
+        # spell the override differently (`baseline capture --dir`,
+        # `migrate-check --history-dir`), and a message that names the wrong one
+        # is the class of defect this ledger is about.
+        sys.stderr.write(
+            f"[ask] created {ask_dir}{os.sep} for this run's local artefacts — "
+            f"git-ignored by its own .gitignore, so `git status` will not show it "
+            f"(`git status --ignored` will). The command's directory option takes a "
+            f"path outside the repository if you want them elsewhere.\n"
+        )
+        sys.stderr.flush()
+    except Exception:
+        pass
+
+
 def write_baseline(baseline: dict, out_dir: Path) -> Path:
     """Write `baseline` as deterministic JSON under `out_dir`; return the file path."""
     out_dir.mkdir(parents=True, exist_ok=True)

sourcecode/cache_model.py

@@ -75,10 +75,17 @@ class CommandCache:
     warm_seconds: "Optional[float]" = None
     #: The other measured point: this command on the field repository
     #: (3 342 Java files, Windows 11 / PowerShell 5.1 / pipx, cold), from field
-    #: evaluations #13 and #14. Seconds where a run finished; `field_blocked`
+    #: evaluations #13, #14 and #16. Seconds where a run finished; `field_blocked`
     #: where it did not — the harness promoted the process and the session died,
     #: which is a measurement of a different kind and is never written as a
     #: duration. Rows with neither were not attempted there.
+    #:
+    #: C3-72: where two evaluations of the same command at this size disagree, the
+    #: figure here is the **most recent** one, because it describes the build a
+    #: reader is about to run — and the previous figure is kept in the comment
+    #: beside it rather than dropped, since a cost that moved by 5,8× between two
+    #: releases (spring-audit, 408 s in #13 against 2 351 s in #16) is itself the
+    #: measurement C3-76 exists for.
     field_seconds: "Optional[float]" = None
     field_blocked: bool = False
 
@@ -93,19 +100,26 @@ REFERENCE_REPOSITORY = (
 REFERENCE_JAVA_FILES = 2000
 
 #: The other end of the measured range, and the reason this module publishes a
-#: *class* rather than a projected duration (C4-19). Field evaluation #13, on
+#: *class* rather than a projected duration (C4-19). Field evaluation #16, on
 #: Windows 11 / PowerShell 5.1 / pipx / Python 3.10: `spring-audit` on a
-#: 3 342-file repository ran **408 s** — 46× the 8.8 s the same command takes on
-#: the 2 000-file reference. Cost does not scale with file count in any way this
-#: product has measured, so a projected "~15 s on your repository" would be a
-#: confident falsehood of exactly the kind the ledger exists to prevent. What can
-#: be said honestly is the class, the two measured anchors, and how to run it.
+#: 3 342-file repository ran **2 351 s** — 267× the 8.8 s the same command takes
+#: on the 2 000-file reference, for a repository 1,7× the size. Cost does not
+#: scale with file count in any way this product has measured, so a projected
+#: "~15 s on your repository" would be a confident falsehood of exactly the kind
+#: the ledger exists to prevent. What can be said honestly is the class, the two
+#: measured anchors, and how to run it.
+#:
+#: C3-72 replaced evaluation #13's 408 s with #16's 2 351 s here: the same command
+#: on the same repository at the same commit, measured three releases later
+#: (2 557 s in 4.10.6, 2 398 s in 4.10.7, 2 351 s in 4.11.0). The older figure was
+#: the one a budget message quoted as "~600s" for three releases while the
+#: measurement stood four times higher.
 FIELD_ANCHOR = (
-    "field evaluation #13: spring-audit on 3 342 Java files took 408 s "
-    "(Windows, pipx, cold) against 8.8 s on the 2 000-file reference"
+    "field evaluation #16: spring-audit on 3 342 Java files took 2 351 s "
+    "(Windows, pipx, warm cache) against 8.8 s on the 2 000-file reference"
 )
 FIELD_ANCHOR_JAVA_FILES = 3342
-FIELD_ANCHOR_SECONDS = 408.0
+FIELD_ANCHOR_SECONDS = 2351.4
 
 
 #: Every layer keys on `cache.worktree_signature` — the exact tree state (C1-9).
@@ -176,14 +190,15 @@ COMMANDS: tuple[CommandCache, ...] = (
                  "Resolves the conditional bean graph on every run, over the shared CIR a warm "
                  "builds — the parse it used to repeat for itself. `--diff` compares two profile "
                  "sets over that one IR, so the second side costs the resolution only.",
-                 "10.1 s → 1.6 s", analysis_class="repo-wide", cold_seconds=10.1, warm_seconds=1.6, field_blocked=True),
+                 "10.1 s → 1.6 s", analysis_class="repo-wide", cold_seconds=10.1, warm_seconds=1.6, field_seconds=38.0),
     CommandCache("risk", ("cir", "parse"), "shared", False,
                  "Composes what the audit, impact-chain and the posture already answer, so it "
                  "pays each of their costs once over the shared CIR a warm builds — one parse "
                  "for the whole composition, and the reachability query is cached per symbol "
                  "within the run.",
                  "not measured on the battery yet — the composition is bounded by the "
-                 "`spring-audit` + `impact-chain` costs listed here, not by new analysis", analysis_class="deep"),
+                 "`spring-audit` + `impact-chain` costs listed here, not by new analysis",
+                 analysis_class="deep", field_seconds=3232.2),
     CommandCache("enrich", ("cir", "parse"), "shared", False,
                  "Runs the same composition as `risk` over the repository, then joins a SARIF "
                  "log to it. Reading the log is negligible; everything a warm helps with is the "
@@ -213,14 +228,14 @@ COMMANDS: tuple[CommandCache, ...] = (
                  "Recomputes the endpoint surface on every run, over a parse a warm has already "
                  "paid for. Until 3.7.0 the extractor parsed every file itself instead of reading "
                  "the shared parse cache, and a warm measurably bought it nothing (C3-6).",
-                 "3.3 s → 1.4 s (re-measured on 3.7.0; was 2.8 s → 2.9 s)", analysis_class="repo-wide", cold_seconds=3.3, warm_seconds=1.4, field_seconds=4.2),
+                 "3.3 s → 1.4 s (re-measured on 3.7.0; was 2.8 s → 2.9 s)", analysis_class="repo-wide", cold_seconds=3.3, warm_seconds=1.4, field_seconds=5.0),
     CommandCache("spring-audit", ("ris", "parse"), "shared", False,
                  "Recomputes every run, but over a parse a warm has already paid for.",
-                 "8.8 s → 3.7 s", analysis_class="repo-wide", cold_seconds=8.8, warm_seconds=3.7, field_seconds=408.0),
+                 "8.8 s → 3.7 s", analysis_class="repo-wide", cold_seconds=8.8, warm_seconds=3.7, field_seconds=2351.4),
     CommandCache("migrate-check", ("cir",), "none", False,
                  "Computes its own inventory and shares nothing a warm builds. Only `--blast-radius` "
                  "reuses the shared CIR.",
-                 "4.8 s → 4.8 s", analysis_class="repo-wide", cold_seconds=4.8, warm_seconds=4.8, field_blocked=True),
+                 "4.8 s → 4.8 s", analysis_class="repo-wide", cold_seconds=4.8, warm_seconds=4.8, field_seconds=26.7),
     CommandCache("impact-chain", ("cir", "parse"), "shared", False,
                  "The CIR is the expensive half — this is where a warm pays most.",
                  "9.9 s → 1.7 s", analysis_class="core", cold_seconds=9.9, warm_seconds=1.7),

sourcecode/cli.py

@@ -1232,7 +1232,32 @@ def _analysis_budget(command: str) -> dict[str, Any]:
     }
 
 
-def _enforce_analysis_budget(command: str, budget: dict[str, Any]) -> None:
+def _budget_evidence(command: str, path: "Optional[Path]") -> "tuple[Optional[str], Optional[str]]":
+    """(measured anchors for this command, size of this repository) — or Nones.
+
+    C3-72: both halves already exist and neither reached the one message an
+    operator reads before deciding to wait. `execution_plan` owns the formatting
+    of the anchors (the same string `--help` and the remedies print) and the
+    cheap, capped scope measurement, so nothing new is computed or claimed here.
+    """
+    anchors: Optional[str] = None
+    scope: Optional[str] = None
+    try:
+        from sourcecode import execution_plan as _plan
+
+        anchors = _plan._reference(_plan.cost_row(command))
+        if path is not None:
+            measured = _plan.scope_for(Path(path))
+            if measured is not None and measured.measured:
+                scope = measured.describe()
+    except Exception:
+        pass  # a message about cost must never be the reason a run fails
+    return anchors, scope
+
+
+def _enforce_analysis_budget(
+    command: str, budget: dict[str, Any], path: "Optional[Path]" = None
+) -> None:
     """Warn when the operator's budget is under the class floor — never refuse.
 
     C3-55: below the floor was rejected and above it admitted a run that killed
@@ -1254,11 +1279,13 @@ def _enforce_analysis_budget(command: str, budget: dict[str, Any]) -> None:
         return
     from sourcecode.phased_run import budget_warning
 
+    _anchors, _scope = _budget_evidence(command, path)
     try:
         sys.stderr.write(
             budget_warning(
                 command, str(budget.get("class") or "repo-wide"),
                 float(configured), recommended,
+                anchors=_anchors, scope=_scope,
             )
         )
         sys.stderr.flush()
@@ -1352,7 +1379,7 @@ def _expensive_analysis_scope(command: str, path: Path, phase: str):
     lock_path = _analysis_lock_path(path)
     _emit_analysis_contention_warning(command, path, phase)
     budget = _analysis_budget(command)
-    _enforce_analysis_budget(command, budget)
+    _enforce_analysis_budget(command, budget, path)
     run_record = RunRecord.start(path, command, phase, budget=budget)
     run_token = set_active_run(run_record)
     token = f"{os.getpid()}:{time.time_ns()}"
@@ -1418,6 +1445,53 @@ def _work_sink(prog: Any) -> Any:
     return sink
 
 
+def _rule_pass_progress(
+    prog: Any,
+    stage: str,
+    unit: str = "rule families",
+    *,
+    stop_when: Any = None,
+) -> Any:
+    """The rule-pass observer an auditor reports through, or None (C3-73).
+
+    The per-file passes are counted (C3-56) and the rule pass — which is most of a
+    repository-wide audit's wall time — was not, so the field watched one
+    unchanging line for 39 minutes at exactly the moment the question is *"is this
+    working, or is it hung?"*. The rule families are the population this loop
+    walks, so they are what it counts.
+
+    `estimate=False`: the families are not comparable units. One walks every symbol
+    in the repository, the next reads one annotation, so a rate over the first four
+    says nothing about the fifth. The count answers *"is it moving"*, which is the
+    question; an ETA here would be a number rather than an estimate, and this line
+    exists to be trusted.
+
+    `stop_when` is the operator's budget (C3-71), and it is the reason this returns
+    an observer even when nothing is watching: the heartbeat is disabled off a TTY
+    and in CI, which is **precisely** where a budget matters, so gating the observer
+    on the spinner would have honoured the budget only on a developer's terminal.
+    No heartbeat and no budget is the only case that returns None, and then the
+    loops run exactly as they did before.
+    """
+    from sourcecode.rule_pass import RulePassProgress
+
+    watching = prog is not None and getattr(prog, "enabled", False)
+    if not watching and stop_when is None:
+        return None
+
+    def sink(done: int, total: int, rule_id: str) -> None:
+        prog.work(
+            done, total,
+            stage=f"{stage} ({rule_id})",
+            unit=unit,
+            estimate=False,
+        )
+
+    return RulePassProgress(
+        sink=sink if watching else None, stop_when=stop_when
+    )
+
+
 def _reserialize_as_yaml(content: str) -> str:
     """JSON document → YAML, or the content unchanged when it is not one.
 
@@ -7995,29 +8069,64 @@ def spring_audit_cmd(
             _model = SpringSemanticModel.build(cir)
             _run.checkpoint("ir")
             # The IR is built; the rule passes are the work now, and they are not
-            # counted per file. Saying so drops the denominator rather than
-            # leaving `2766/2766` frozen on the line while they run (C3-56).
+            # counted per file. Saying so drops the per-file denominator rather
+            # than leaving `2766/2766` frozen on the line while they run (C3-56)
+            # — and C3-73 gives the pass the denominator it does have: the rule
+            # families it evaluates, counted as it walks them.
             _prog.update(f"applying {scope} rules over {len(file_list)} Java files")
 
             results: list[SpringAuditResult] = []
+            # C3-71: the budget reaches the loop that spends the time. Checking it
+            # only between the three phases meant it could be observed at two
+            # instants in a 39-minute run, and the phase holding ~85 % of the time
+            # was never interrupted — so `ASK_MAX_ANALYSIS_SECONDS=420` produced a
+            # 2 351 s run, exit 0, and no `partial` anywhere. `PhasedRun.exhausted`
+            # stays the one authority on whether the time is spent; what is new is
+            # that the rule pass asks it.
+            _rules_cut: list[str] = []
+            _phases_cut: list[str] = []
             if scope in ("all", "tx"):
                 if _run.exhausted():
                     _stopped_early = _WHY_BUDGET
                 else:
-                    results.append(run_tx_audit(cir, root=target, min_severity=min_severity, model=_model))
-                    _run.checkpoint(
-                        "tx_audit",
-                        SpringAuditResult.merge(list(results), scope=scope).to_compact_dict(),
+                    _tx_watch = _rule_pass_progress(
+                        _prog, "transaction rules", stop_when=_run.exhausted
                     )
+                    results.append(run_tx_audit(
+                        cir, root=target, min_severity=min_severity, model=_model,
+                        progress=_tx_watch,
+                    ))
+                    _cut = list(getattr(_tx_watch, "not_run", []) or [])
+                    _rules_cut.extend(_cut)
+                    if _cut:
+                        _stopped_early = _WHY_BUDGET
+                        _phases_cut.append("tx_audit")
+                    else:
+                        _run.checkpoint(
+                            "tx_audit",
+                            SpringAuditResult.merge(list(results), scope=scope).to_compact_dict(),
+                        )
             if scope in ("all", "security"):
                 if _run.exhausted():
                     _stopped_early = _WHY_BUDGET
                 else:
-                    results.append(run_security_audit(cir, root=target, min_severity=min_severity, model=_model))
-                    _run.checkpoint(
-                        "security_audit",
-                        SpringAuditResult.merge(list(results), scope=scope).to_compact_dict(),
+                    _sec_watch = _rule_pass_progress(
+                        _prog, "security rules", stop_when=_run.exhausted
                     )
+                    results.append(run_security_audit(
+                        cir, root=target, min_severity=min_severity, model=_model,
+                        progress=_sec_watch,
+                    ))
+                    _cut = list(getattr(_sec_watch, "not_run", []) or [])
+                    _rules_cut.extend(_cut)
+                    if _cut:
+                        _stopped_early = _WHY_BUDGET
+                        _phases_cut.append("security_audit")
+                    else:
+                        _run.checkpoint(
+                            "security_audit",
+                            SpringAuditResult.merge(list(results), scope=scope).to_compact_dict(),
+                        )
 
             combined = SpringAuditResult.merge(results, scope=scope)
 
@@ -8040,17 +8149,43 @@ def spring_audit_cmd(
                 # The answer is a floor over the phases that ran. It says so in
                 # the payload rather than in prose nobody parses, and in the
                 # limitation list the reader already consults.
-                combined.limitations.append(
-                    "Partial answer: the analysis budget ran out after "
-                    f"{', '.join(_run.completed)}; "
-                    f"{', '.join(_run.pending())} did not run. Counts are a floor "
-                    "over the completed phases — absence of a finding from a "
-                    "phase that never ran is not evidence there is none."
-                )
+                if _rules_cut:
+                    # C3-71: the phase was stopped *inside*, so saying it "did not
+                    # run" would be false — four of its five families answered.
+                    # Name what did not run, at the granularity it was cut on.
+                    combined.limitations.append(
+                        "Partial answer: the analysis budget ran out during the "
+                        f"rule pass, after {', '.join(_run.completed)}. The rule "
+                        f"families that did not run: {', '.join(_rules_cut)}. Counts "
+                        "are a floor over what did run — absence of a finding from a "
+                        "family that never ran is not evidence there is none."
+                    )
+                else:
+                    combined.limitations.append(
+                        "Partial answer: the analysis budget ran out after "
+                        f"{', '.join(_run.completed)}; "
+                        f"{', '.join(_run.pending())} did not run. Counts are a floor "
+                        "over the completed phases — absence of a finding from a "
+                        "phase that never ran is not evidence there is none."
+                    )
 
             data = combined.to_compact_dict() if compact else combined.to_dict()
             if _stopped_early:
                 data["_partial"] = _run.status(_stopped_early)
+                if _rules_cut:
+                    # C3-71: a phase stopped *inside* is neither completed nor
+                    # pending, and calling it either would misreport the run. The
+                    # families it did not reach are named instead.
+                    data["_partial"]["rules_not_run"] = _rules_cut
+                    # A phase that was stopped inside is in neither list, and
+                    # putting it in `phases_pending` alone would claim none of it
+                    # ran when most of it did.
+                    data["_partial"]["phases_stopped_inside"] = _phases_cut
+                    data["_partial"]["how_to_read"] += (
+                        " The rule pass was stopped between families: "
+                        f"{', '.join(_rules_cut)} did not run, so every count here "
+                        "is a floor over the families that did."
+                    )
 
             # Non-fatal RIS side-effect — persist summary only (not full findings).
             try:
@@ -8275,6 +8410,15 @@ def verify_cmd(
         "--ci/--no-ci",
         help="Exit non-zero on a failing/unverified report (default on — for pipelines).",
     ),
+    allow_unverified: bool = typer.Option(
+        False,
+        "--allow-unverified",
+        help=(
+            "Exit 0 when nothing could be verified (no contracts declared yet, or "
+            "the gate could not run). The verdict stays `unverified` in the payload "
+            "— this is the declared form of `|| true`, and violations still block."
+        ),
+    ),
     copy: bool = _copy_option(),
     progress_mode: Optional[str] = _progress_option(),
 ) -> None:
@@ -8301,6 +8445,14 @@ def verify_cmd(
     repository could not be analysed — never a silent pass). Same codes as
     `verify-edit`.
 
+    \b
+    Adopting the gate (C3-75): the payload names which unverified state it is —
+    `unverified_reason: no_contracts_declared` (this repository has not adopted
+    contracts) or `gate_could_not_run`. A pipeline added before the contracts exist
+    can pass `--allow-unverified` to exit 0 while the verdict stays `unverified`;
+    violations still block. That is the declared version of `|| true`, which is what
+    teams actually reach for and which then hides a real failure forever.
+
     \b
     Where the repository already keeps an architectural history (`.ask/baselines`),
     this run adds the current commit to it and reports what it did under
@@ -8419,7 +8571,8 @@ def verify_cmd(
         _prog.start("verifying contracts")
         try:
             report = _vr.verify_repo(
-                path, fail_on=fail_on, baseline_path=baseline, on_cir=_capture
+                path, fail_on=fail_on, baseline_path=baseline, on_cir=_capture,
+                allow_unverified=allow_unverified,
             )
         except _vr.VerifyError as exc:
             _prog.stop()
@@ -8571,11 +8724,34 @@ def risk_cmd(
     # without a single byte on stderr while it ran.
     phase = "composing risk factors"
     risk_limit = 100000 if table and (rule_filter or band_filter or top_n) else limit
+    # C3-77: 3 232 s in the field, all-or-nothing, while `spring-audit` beside it
+    # already kept what it measured (C3-54 part 3). The phases are declared here so
+    # a run that is killed — by an agent harness, a CI timeout, a closed laptop —
+    # leaves the composition it already paid for, with `partial: true` and the
+    # phase it reached. Same mechanism, same durable write (fsync + atomic rename),
+    # same invariant: never a document that looks complete.
+    _run = PhasedRun(
+        command="risk",
+        root=path,
+        phases=["audit", "compose"],
+        output_path=output_path,
+        budget_seconds=_analysis_budget("risk").get("configured_max_seconds"),
+        writer=_safe_write_file,
+    )
     with _expensive_analysis_scope("risk", path, phase):
         _prog = Progress()
         _prog.start(phase)
         try:
-            data = build_risk(path, limit=risk_limit, min_band=min_band, profiles=_profile_set(profile))
+            data = build_risk(
+                path, limit=risk_limit, min_band=min_band,
+                profiles=_profile_set(profile),
+                # C3-73: 54 minutes with one line on stderr in the field. The
+                # factory hands the composer an observer per counted stage.
+                progress=lambda stage, unit="rule families": _rule_pass_progress(
+                    _prog, stage, unit
+                ),
+                checkpoint=_run.checkpoint,
+            )
         finally:
             _prog.stop()
     if table:
@@ -8593,6 +8769,9 @@ def risk_cmd(
             f"{data['total_defects']} defects composed)"
         ),
     )
+    # The complete answer is on disk; the checkpoint that stood in for it is not
+    # needed and must not outlive it (C3-54 part 3's invariant, C3-77's reuse).
+    _run.discard_checkpoint()
 
 
 @app.command("enrich")
@@ -9657,6 +9836,14 @@ def migrate_check_cmd(
       first→last movement — no improving/degrading label, and readiness_score is
       flagged not-comparable when the applicable dimension set changed.
 
+    \b
+    What this command writes (C3-74):
+      Nothing, unless you pass --snapshot. Then, and only then, it creates
+      <repo>/.ask/readiness-history (or --history-dir), announces the directory on
+      stderr the first time, and protects it with its own .gitignore. Point
+      --history-dir outside the repository for a read-only checkout or an audit
+      where the tree must not change.
+
     \b
     Java LTS/licensing inventory:
       The JSON report includes java_lts_inventory: Java 8/11/17/21/25 evidence
@@ -9691,12 +9878,12 @@ def migrate_check_cmd(
         raise typer.Exit(code=1)
 
     _history_dir = history_dir.resolve() if history_dir else (target / ".ask" / "readiness-history")
-    # C3-68: same protection wherever `.ask/` is created inside a work tree.
-    try:
-        from sourcecode.architectural_baseline import protect_ask_dir as _protect_ask_dir
-        _protect_ask_dir(_history_dir)
-    except Exception:
-        pass
+    # C3-74: the protection belongs at the write, not at the argument parse.
+    # `protect_ask_dir` *creates* `.ask/` so it can drop its ignore file in it, and
+    # calling it here ran it on every invocation — so a read-only question left a
+    # 283-byte artefact inside the audited repository, and the field bisected
+    # eleven commands to find that this was the only one doing it. The write path
+    # (`--snapshot`) calls it below, where something is actually being written.
 
     # --trend reads the stored series and reports movement over time; it does not scan.
     if trend:
@@ -12798,6 +12985,17 @@ def cache_status_cmd(
             _answer.say(
                 f"{_label + ':':<13}{_store.get('entries', 0)} entries, {_mb} MB{_scope}"
             )
+            # C3-70: one total hid three copies of the same repository, one per
+            # release, for three releases. The composition is printed where the
+            # total is, because that is where it was read.
+            _stale_entries = _store.get("stale_entries")
+            if _stale_entries:
+                _stale_mb = round(int(_store.get("stale_bytes") or 0) / (1024 * 1024), 2)
+                _answer.say(
+                    f"{'':<13}of which {_stale_entries} entries ({_stale_mb} MB) were "
+                    "written by another build and can never be read again — the next "
+                    "analysis retires them"
+                )
         # RIS section
         if stats.get("ris_exists"):
             _stale_tag = " [STALE]" if stats.get("ris_is_stale") else ""

sourcecode/container_wiring.py

@@ -306,6 +306,27 @@ def warning_line(wired: list[ContainerWiring], measured_fan_in: Optional[int] =
     )
 
 
+#: Why the numeric score is `null` rather than `0.0` on this population (C1-41).
+#:
+#: The level is floored here because a fan-in-derived band cannot describe a
+#: component the framework invokes. The *number* was left on that same arithmetic
+#: for two releases, so the field measured `risk_level=high` beside
+#: `risk_score=0.0` on the aspect gating 76 % of a repository's handlers — the
+#: worst possible value for its most critical symbol, from the same object whose
+#: band said `high`. `0.0` is a measurement claim; what was not measured is `null`
+#: (C1-39, I-3). One authority for the sentence, because both blast-radius
+#: derivations publish it: `spring_impact` (impact-chain) and `repository_ir`
+#: (impact / plan / compare).
+SCORE_NULL_NOTE = (
+    "null, not 0: the container invokes this component, so its call-graph fan-in "
+    "is ~0 by construction and the weighted score derived from it is not a "
+    "measurement of this symbol (blind_spots=container_wired, NC-010). "
+    "`risk_level` is a floor established without it; rank this symbol by the "
+    "surfaces that do measure it — `ask endpoints`, `ask explain <symbol>`, "
+    "`ask posture` — not by a number the graph could not produce."
+)
+
+
 def risk_floor_reason(wired: list[ContainerWiring]) -> str:
     """The `risk_reason` that replaces a fan-in verdict on this population."""
     kinds = sorted({k for w in wired for k in w.kinds})