sourcecode 4.11.0__tar.gz → 4.14.0__tar.gz

sourcecode-4.14.0/.github/workflows/perf-gate.yml

@@ -0,0 +1,109 @@
+name: Performance regression gate
+
+# F-AP. Field evaluation #16 measured seven commands 2-3.4x slower on a minor
+# release while every payload stayed byte-identical, and named the cause:
+# "no es que haya regresiones - es que no hay nada que las detecte".
+# This is the detector. The threshold, the repository and the gated command
+# population are declared in `sourcecode.perf` and documented in
+# `docs/perf/REGRESSION-GATE.md`; nothing here carries a number of its own.
+
+on:
+  schedule:
+    # Nightly, after the day's merges have settled.
+    - cron: "0 3 * * *"
+  workflow_dispatch:
+    inputs:
+      baseline_ref:
+        description: "Baseline directory under docs/perf/baselines (default: gate-latest)"
+        required: false
+        default: "gate-latest"
+
+concurrency:
+  group: perf-gate
+  cancel-in-progress: false
+
+jobs:
+  gate:
+    runs-on: ubuntu-latest
+    timeout-minutes: 120
+    env:
+      # Declares the host class so nightly runs on ephemeral runners are
+      # comparable at all. Recorded in every artifact as `env.host_id_declared`,
+      # so the declaration is visible rather than silent.
+      SOURCECODE_PERF_HOST_ID: github-ubuntu-latest
+      BASELINE_DIR: docs/perf/baselines/${{ github.event.inputs.baseline_ref || 'gate-latest' }}
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          pip install .
+
+      - name: Prove the gate is armed
+        # A green gate is evidence only when a red one is reachable in the same
+        # job with the same constants. This step fails if a synthetic 3x-slower
+        # cell would have passed.
+        run: python3 scripts/perf_gate.py --self-test
+
+      - name: Read the declared gate configuration
+        id: cfg
+        run: |
+          python3 scripts/perf_gate.py --print-config | tee gate-config.json
+          echo "repo_url=$(python3 -c "import json;print(json.load(open('gate-config.json'))['repository_url'])")" >> "$GITHUB_OUTPUT"
+          echo "repo=$(python3 -c "import json;print(json.load(open('gate-config.json'))['repository'])")" >> "$GITHUB_OUTPUT"
+          echo "mode=$(python3 -c "import json;print(json.load(open('gate-config.json'))['mode'])")" >> "$GITHUB_OUTPUT"
+          echo "runs=$(python3 -c "import json;print(json.load(open('gate-config.json'))['min_runs'])")" >> "$GITHUB_OUTPUT"
+          echo "commands=$(python3 -c "import json;print(' '.join(repr(c) for c in json.load(open('gate-config.json'))['commands']))")" >> "$GITHUB_OUTPUT"
+
+      - name: Clone the gate repository
+        run: |
+          mkdir -p fleet
+          git clone --depth 1 "${{ steps.cfg.outputs.repo_url }}" "fleet/${{ steps.cfg.outputs.repo }}"
+
+      - name: Measure
+        env:
+          PERF_FLEET_ROOT: fleet
+        run: |
+          python3 scripts/perf_harness.py \
+            --repos "${{ steps.cfg.outputs.repo }}" \
+            --commands ${{ steps.cfg.outputs.commands }} \
+            --modes "${{ steps.cfg.outputs.mode }}" \
+            --runs "${{ steps.cfg.outputs.runs }}" \
+            --fleet-root fleet \
+            --out perf-run
+
+      - name: Gate
+        run: |
+          python3 scripts/perf_gate.py \
+            --baseline "$BASELINE_DIR" \
+            --current perf-run \
+            --report perf-run/gate.json \
+            --table perf-run/RELEASE-TABLE.md
+
+      - name: Publish the measured table
+        if: always()
+        run: |
+          if [ -f perf-run/RELEASE-TABLE.md ]; then
+            {
+              echo "## Measured wall time per command"
+              echo
+              cat perf-run/RELEASE-TABLE.md
+            } >> "$GITHUB_STEP_SUMMARY"
+          fi
+
+      - name: Upload artifacts
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: perf-gate-${{ github.run_number }}
+          path: |
+            perf-run/**
+            gate-config.json

{sourcecode-4.11.0 → sourcecode-4.14.0}/CHANGELOG.md

@@ -2,6 +2,195 @@
 
 ## [Unreleased]
 
+## [4.14.0] — 2026-08-09
+
+**The Part 1 queue of Amendment N — the four rows field evaluation #17 opened,
+one commit each.** The fourth measurement of the same repository at the same
+commit scored **7,5/10**, the highest of the series, and verified six of the
+previous release's fixes from the outside. Both rows it opened are in the fields
+that describe ASK's *own* reliability, which is where this product can least
+afford to be wrong.
+
+**Fixed in this release:**
+
+- **A truncated answer no longer raises its own confidence (C2-31).** Three
+  complete runs published 395 findings / 98 defects at `confidence_level:
+  medium`; the run the budget cut published 289 / 15 at **`high`**, because the
+  level is derived from the confidence of the high/critical findings *that
+  exist* and the family contributing the medium-confidence ones is the family
+  that did not run. `SpringAuditResult.partial` is now one flag — set by the
+  scopes, by the CLI for a phase that never started, and carried through
+  `merge` — and a partial answer is capped at `low` with `confidence_basis`
+  saying the cut is the reason. `summary` gains `partial`, `counts_are_floor`
+  and `counts_basis`, so the mark lives where the numbers a consumer reads are,
+  not only in `_partial` at the root. The cap is a ceiling and never a floor: a
+  complete run keeps its level and gains no fields.
+- **The rule inventory names rules, and both scopes' (C1-42).** `rules_run`
+  listed four SEC ids in a payload whose findings carried DEAD-001, SEC-008,
+  TX-006, TX-001, SEC-005 and SEC-006, and `rules_not_run` said `[GATE-001]`
+  where the arithmetic proves GATE-004 did not run either. The lists were keyed
+  on the pattern *object's* identity, so a family emitting six rules stood for
+  itself, and `merge` overwrote the TX scope's inventory with the security
+  scope's. `rule_pass.rule_ids_of()` is the one authority, the two lists are
+  unioned across scopes, and `rules_run_count` / `rules_total` sit beside them.
+  Three invariants are asserted over a real audit: every rule that fired is in
+  `rules_run`, the lists never overlap, and a complete `--scope all` run
+  inventories exactly `rule_catalog.ids()`.
+- **The heartbeat is emitted by the work, not only by a thread (C3-80).** Four
+  versions with the same shape: one line at `elapsed=20.1s`, 39 minutes of
+  nothing, then the same stage text seconds before the end. A line-mode
+  heartbeat printed only by a daemon thread depends on that thread being
+  scheduled during exactly the CPU-bound stretch the operator is asking about.
+  `Progress._emit()` is now one seam with one throttle and two callers — the
+  loop on its timer and the analysis in-band — sharing one `_last_emit` stamp,
+  so the line rate is unchanged and a running analysis is always heard from.
+- **The budget cuts inside a rule family (C3-79).** Budget 420 s, elapsed
+  2 376 s: `exhausted()` was asked on a whole-family boundary and one family
+  lasts 39 minutes. `RulePassProgress.tick()` reports counted work and answers
+  *"is the time spent"* in one call, sampling the clock once per 64 units; five
+  families that walk a population take a `FamilyBudget` and stop on a batch
+  boundary. A family cut in flight is in neither list — it is
+  `rules_partially_run` with the count it reached, and the findings it produced
+  are kept, because they were measured. Measured on BroadleafCommerce: a 4,5 s
+  budget stops at 1 408 of 2 766 Java files and ends at 5,1 s.
+
+**Verified in the field, not changed here:** `verify` exiting 2 without contracts
+is C3-75's deliberate half (the waiver `--allow-unverified` and the named
+`unverified_reason` are the fix; a distinct code is a contract change, F-AV), and
+the 4.10.7 performance that never came back is C3-76, which does not reproduce on
+this platform and waits on the Windows runner (F-AW).
+
+Suite 7 787.
+
+## [4.13.0] — 2026-08-08
+
+**The capability queue of Amendment M — the four features field evaluation #16
+asked for, one commit each, after Part 1 closed in 4.12.0.** The evaluation's
+verdict on engineering was *"no es que haya regresiones — es que no hay nada que
+las detecte"*, and its "if you could only do two things" was F-AP and F-AQ, in
+that order. Both ship here, with F-AR and F-AS beside them.
+
+**New in this release:**
+
+- **A release performance gate (F-AP).** `perf.gate_report()` turns a whole run
+  into one verdict against a whole baseline, and three of its four outcomes are
+  not a pass: a cell over the threshold **fails**, a baselined cell this run did
+  not measure **fails** (silence is how "nothing detects a regression" happens),
+  and a cell under the ADR-0006 sample floor **fails**. `scripts/perf_gate.py
+  --self-test` proves the gate is armed by failing a synthetic 3×-slower cell —
+  CI runs it *before* it runs the measurement, because a green gate is evidence
+  only when a red one is reachable on the same constants. Threshold **20 %**,
+  warm mode, one ~3 000-file repository, six repository-wide commands, and the
+  three exclusions published with every verdict. All of it lives in
+  `sourcecode.perf`; `docs/perf/REGRESSION-GATE.md` embeds `--print-config`'s
+  output verbatim and a test asserts they are the same bytes.
+- **The measured times are published, generated (F-AP, second rider).**
+  `perf.release_table()` builds the per-command / per-repository-scale table a
+  release note carries, from the run's own artifacts. An axis that was not
+  measured prints `unknown`, never `0`. And `cache model`'s figures now name the
+  build they were measured on (3.2.2) beside the build you are running, so a
+  table nine releases old cannot read as this build's measurement.
+- **`--jobs N` / `-j` / `ASK_JOBS` (F-AQ)**, default `cpu_count() - 1`. The
+  fourth consecutive evaluation to ask for parallelism was the first to sample
+  it: `threads=1`, `CPU/wall = 0,92…0,95`, 54 minutes, 20 cores. Worker
+  processes now parse files into the *same* content-addressed cache the IR loop
+  is about to read, so the loop is untouched and **byte-identity is structural,
+  not inspected** — no worker output reaches the payload by any route. Measured
+  on 2 766 Java files, both sides parse-cold with their own cache root: 5,36 s →
+  3,46 s (**1,55×**), CPU/wall 2,07, IR hash identical. Every failure mode — no
+  pool, a faulting worker, a frozen build, a disabled cache, a repository under
+  the 200-file floor — degrades to today's sequential parse and returns a receipt
+  naming the reason.
+- **`ASK_PARSE_CACHE_MAX_MB` (F-AR)**, default **512 MB**, least-recently-used,
+  enforced on write and published in `cache status` beside the size it bounds.
+  C3-70 retires the generation that can never be read again — an exact rule, and
+  exact rules only cover what they can foresee. This bounds what they cannot:
+  many repositories, many branches, one machine, and an owner who never runs
+  `ask cache clear`. Reads refresh recency (hourly granularity, so a hit is not a
+  disk write), an entry and its body-fact blob are evicted together, and
+  `ASK_PARSE_CACHE_MAX_MB=0` turns the guard off deliberately and says so.
+- **`--no-write` / `ASK_READONLY=1` (F-AS)** — nothing is created inside the
+  analysed repository, and a command that cannot answer without writing says so
+  instead of writing, in the same error envelope every other refusal uses.
+  Accepted by **every** command (consumed before the parser, the `--detach`
+  precedent), because a mode five commands accept and seventy-nine reject is a
+  mode whose one refusing run is the run that writes. Each refusal is announced
+  once on stderr with its path. Shared caches outside the repository are
+  untouched — an auditor is protecting a checkout, not a home directory.
+- **`ask --help` names every command that writes into the repository**, with the
+  condition beside it ("only with `--snapshot`"), generated from one authority.
+
+**Measured, not fixed, and said so:** the second half of F-AQ — *"one audit per
+run, shared by the compositions"* — was measured before being touched.
+Instrumenting `build_risk` on a real repository counts `run_tx_audit` **1×** and
+`run_security_audit` **1×**: `risk` already hands its findings to every impact
+chain it composes (C3-42-b), so the duplication the field named is between two
+*processes*, not inside one. That needs a persisted audit keyed on the worktree
+signature, and it is not in this release. What ships is the regression test that
+keeps the in-run property true.
+
+## [4.12.0] — 2026-08-08
+
+**Field evaluation #16 — the third round on the same repository and commit, and the
+first A/B/C of three of our own releases (4.10.6 → 4.10.7 → 4.11.0, 7,0 → 7,0 →
+6,5).** The three value axes did not move: correctness 9,5, unique value 9,0,
+epistemic honesty 10, with `endpoints.json`, `servlets.json` and `validation.json`
+**byte-identical across all three builds**. What fell is engineering, and the
+sentence is about us: *"no es que haya regresiones — es que no hay nada que las
+detecte."* Nine rows close here, one commit each.
+
+**Behaviour changes to read before upgrading a pipeline:**
+
+- **`risk_score` and `risk_score_raw` are `null`, not `0.0`, when the container
+  invokes the queried component** (`@Configuration`, `@Aspect`, a registered
+  filter). The band already said `high` for these while the number said `0.0` — the
+  worst possible value for the most critical symbol in a system, from the same
+  object. `risk_score_basis` says why and names the surfaces that do measure such a
+  component. Affects `impact-chain`, `impact`, `plan` and `compare`; a consumer
+  reading the field with a `0.0` default now sees `null`.
+- **`ASK_MAX_ANALYSIS_SECONDS` actually stops a `spring-audit` rule pass.** It was
+  only ever checked between the three phases, and the last one holds ~85 % of the
+  time, so a 420 s budget produced a 2 351 s run and no `partial` anywhere. A cut
+  run now publishes `metadata.rules_not_run`, a `PARTIAL:` limitation, and
+  `_partial.phases_stopped_inside`. `metadata.rules_run` is present on every run.
+- **`migrate-check` no longer creates `<scope>/.ask/` unless you pass `--snapshot`.**
+  A read-only run left a git-ignored directory in the audited repository — invisible
+  to `git status`, visible only to `git status --ignored`.
+- **`verify` gains `--allow-unverified`** (exit 0 while the verdict stays
+  `unverified`) and publishes `unverified_reason`: `no_contracts_declared` or
+  `gate_could_not_run`. Exit codes are unchanged; the remedy is now the first reason.
+- **The parse cache retires generations.** Entries live under the producing
+  analyzer's fingerprint, and a run purges the generations that can never be read
+  again — the field measured +142,53 MB per release, three copies of one repository,
+  427,59 MB after three runs. `cache status` publishes the composition.
+
+**Also in this release:**
+
+- The rule pass reports the family it is on, counted against the total, and names
+  the two stages that have no population (`spring-audit` and `risk`). The ETA is
+  withheld there on purpose: rule families are not comparable units.
+- `risk` checkpoints — after the audit and every 25 composed rows — with the partial
+  file built by the same assembler as the answer, so it is the same document over
+  fewer rows.
+- The budget message stops quoting a class constant in the grammar of a
+  measurement. It carries this command's measured anchors and the size of the
+  repository in hand, and says plainly that no projection is offered. Anchors
+  recalibrated: `spring-audit` 408 s → 2 351 s at 3 342 files, `endpoints` 4,2 → 5,0,
+  `migrate-check --compact` 26,7 and `posture` 38,0 (both previously recorded as not
+  finishing), `risk` 3 232.
+- The MCP stack's incomplete-model warning no longer reaches stderr, and the models
+  it complains about are rebuilt rather than only muted.
+- A 772-line temp file (`cache.tmp_new`) was shipping inside the wheel; removed, and
+  the package contents are now asserted by allow-list.
+
+**Measured and not fixed, deliberately:** the block performance regression the
+evaluation reports (seven commands 2–3,4× slower on a minor) **does not reproduce
+here** — the A/B of 4.10.7 against 4.11.0 on a 2 985-file repository lands within
+1 % on six commands, with `posture --resolve-environments` byte-identical, and
+`risk` could not be A/B'd because the *4.10.7* side alone passed 61 minutes. Its
+cost is structural, not new. The numbers are in the ledger; the row waits on a
+Windows runner rather than on a guess.
+
 ## [4.11.0] — 2026-08-07
 
 **The queue behind Tier D: five ledger rows, and three batteries that were red in

{sourcecode-4.11.0 → sourcecode-4.14.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sourcecode
-Version: 4.11.0
+Version: 4.14.0
 Summary: Persistent structural context and ultra-fast repeated analysis for AI coding agents
 License-File: LICENSE
 Keywords: agents,ai,codebase,context,developer-tools,llm
@@ -42,7 +42,7 @@ Description-Content-Type: text/markdown
 
 **Context · Impact · Migration · Architecture · Review — everything from one structural model.**
 
-![Version](https://img.shields.io/badge/version-4.11.0-blue)
+![Version](https://img.shields.io/badge/version-4.14.0-blue)
 ![Python](https://img.shields.io/badge/python-3.9%2B-green)
 
 > **ASK Engine** is the product. The CLI command is **`ask`**. The legacy **`sourcecode`**
@@ -108,7 +108,7 @@ brew tap haroundominique/sourcecode && brew install sourcecode
 # pip / pipx
 pipx install sourcecode        # or: pip install sourcecode
 
-ask version                    # ask 4.11.0 — and, on a build that has aged,
+ask version                    # ask 4.14.0 — and, on a build that has aged,
                                # how many releases have probably shipped since
 ```
 

{sourcecode-4.11.0 → sourcecode-4.14.0}/README.md

@@ -4,7 +4,7 @@
 
 **Context · Impact · Migration · Architecture · Review — everything from one structural model.**
 
-![Version](https://img.shields.io/badge/version-4.11.0-blue)
+![Version](https://img.shields.io/badge/version-4.14.0-blue)
 ![Python](https://img.shields.io/badge/python-3.9%2B-green)
 
 > **ASK Engine** is the product. The CLI command is **`ask`**. The legacy **`sourcecode`**
@@ -70,7 +70,7 @@ brew tap haroundominique/sourcecode && brew install sourcecode
 # pip / pipx
 pipx install sourcecode        # or: pip install sourcecode
 
-ask version                    # ask 4.11.0 — and, on a build that has aged,
+ask version                    # ask 4.14.0 — and, on a build that has aged,
                                # how many releases have probably shipped since
 ```
 

{sourcecode-4.11.0 → sourcecode-4.14.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "sourcecode"
-version = "4.11.0"
+version = "4.14.0"
 description = "Persistent structural context and ultra-fast repeated analysis for AI coding agents"
 readme = "README.md"
 requires-python = ">=3.9"

sourcecode-4.14.0/scripts/perf_gate.py

@@ -0,0 +1,176 @@
+#!/usr/bin/env python3
+"""Release performance gate (F-AP) — compare a run against a baseline, one verdict.
+
+`scripts/perf_harness.py` measures; this decides. It reads two directories of
+`perf-baseline-v1` cells, gates every cell it can match, and exits non-zero when
+any of them regressed beyond the declared threshold, when a baselined cell was not
+measured at all, or when a cell's sample is under the ADR-0006 floor.
+
+The threshold, the repository, the mode and the excluded commands are constants in
+`sourcecode.perf` — this script never carries a number of its own, and
+`docs/perf/REGRESSION-GATE.md` is generated from the same constants.
+
+Usage:
+    # gate a fresh run against the last release's baseline
+    python3 scripts/perf_gate.py \
+        --baseline docs/perf/baselines/4.12.0 \
+        --current  docs/perf/baselines/4.13.0 \
+        --report   gate.json --table RELEASE-TABLE.md
+
+    # prove the gate is armed: a synthetic 3x-slower cell must fail it
+    python3 scripts/perf_gate.py --self-test
+
+    # print the declared configuration (what the doc renders from)
+    python3 scripts/perf_gate.py --print-config
+"""
+
+from __future__ import annotations
+
+import argparse
+import copy
+import json
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent / "src"))
+from sourcecode import perf  # noqa: E402
+
+
+def load_cells(directory: Path) -> dict[str, dict]:
+    """Every `perf-baseline-v1` cell in *directory*, keyed by `<repo>__<cmd>__<mode>`.
+
+    Gate artifacts (`*.gate.json`) and anything that is not a cell are skipped
+    rather than mis-read: a directory that also holds a report must not turn the
+    report into a measurement.
+    """
+    cells: dict[str, dict] = {}
+    if not directory.is_dir():
+        return cells
+    for path in sorted(directory.glob("*.json")):
+        if path.name.endswith(".gate.json"):
+            continue
+        try:
+            cell = json.loads(path.read_text(encoding="utf-8"))
+        except (OSError, ValueError):
+            continue
+        if not isinstance(cell, dict) or cell.get("schema_version") != perf.SCHEMA_VERSION:
+            continue
+        cells[perf.cell_id(cell)] = cell
+    return cells
+
+
+def _self_test() -> int:
+    """A deliberately slowed command must fail the gate. Run in CI before the gate.
+
+    This is the exit criterion stated as an executable check: it is not enough for
+    the gate to exist and be green — a green gate is only evidence when a red one
+    is reachable on the same machine, in the same job, with the same constants.
+    """
+    base = perf.build_baseline_cell(
+        tool_version="self-test",
+        command="spring-audit",
+        repo={"name": perf.RELEASE_GATE_REPO, "commit": "self-test", "files": 3000},
+        mode=perf.RELEASE_GATE_MODE,
+        wall_ms_runs=[1000.0] * perf.RELEASE_GATE_MIN_RUNS,
+        rss_bytes_runs=[1.0] * perf.RELEASE_GATE_MIN_RUNS,
+    )
+    slowed = copy.deepcopy(base)
+    slowed["wall_ms"] = {k: v * 3.0 for k, v in base["wall_ms"].items()}
+
+    cid = perf.cell_id(base)
+    red = perf.gate_report({cid: base}, {cid: slowed})
+    green = perf.gate_report({cid: base}, {cid: base})
+    dropped = perf.gate_report({cid: base}, {})
+
+    ok = (not red["passed"]) and green["passed"] and (not dropped["passed"])
+    print(f"self-test: 3x slower -> {'FAIL (correct)' if not red['passed'] else 'PASS (BROKEN)'}")
+    print(f"self-test: unchanged -> {'PASS (correct)' if green['passed'] else 'FAIL (BROKEN)'}")
+    print(f"self-test: cell gone -> {'FAIL (correct)' if not dropped['passed'] else 'PASS (BROKEN)'}")
+    if not ok:
+        print("perf gate self-test FAILED: the gate would not catch a regression.",
+              file=sys.stderr)
+    return 0 if ok else 1
+
+
+def _print_config() -> int:
+    print(json.dumps({
+        "schema_version": perf.GATE_SCHEMA_VERSION,
+        "threshold": perf.RELEASE_GATE_THRESHOLD,
+        "repository": perf.RELEASE_GATE_REPO,
+        "repository_url": perf.RELEASE_GATE_REPO_URL,
+        "repository_scale": perf.RELEASE_GATE_REPO_SCALE,
+        "mode": perf.RELEASE_GATE_MODE,
+        "min_runs": perf.RELEASE_GATE_MIN_RUNS,
+        "commands": list(perf.RELEASE_GATE_COMMANDS),
+        "exclusions": [
+            {"command": c, "reason": r} for c, r in perf.RELEASE_GATE_EXCLUSIONS
+        ],
+    }, indent=2))
+    return 0
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(
+        description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter
+    )
+    ap.add_argument("--baseline", type=Path, help="Directory of the release being compared against.")
+    ap.add_argument("--current", type=Path, help="Directory of this run's cells.")
+    ap.add_argument("--threshold", type=float, default=perf.RELEASE_GATE_THRESHOLD,
+                    help=f"Max allowed regression ratio (declared default: "
+                         f"{perf.RELEASE_GATE_THRESHOLD}).")
+    ap.add_argument("--min-runs", type=int, default=perf.RELEASE_GATE_MIN_RUNS)
+    ap.add_argument("--allow-incomparable", action="store_true",
+                    help="Do not fail cells whose env/host differ. Off by default: "
+                         "an incomparable cell is an unmeasured one.")
+    ap.add_argument("--report", type=Path, help="Write the perf-gate-v1 report here.")
+    ap.add_argument("--table", type=Path, help="Write the release-notes markdown table here.")
+    ap.add_argument("--self-test", action="store_true",
+                    help="Prove the gate is armed; measures nothing.")
+    ap.add_argument("--print-config", action="store_true",
+                    help="Print the declared gate configuration as JSON.")
+    args = ap.parse_args()
+
+    if args.self_test:
+        return _self_test()
+    if args.print_config:
+        return _print_config()
+    if not args.current:
+        ap.error("--current is required (or use --self-test / --print-config)")
+
+    current = load_cells(args.current)
+    if not current:
+        print(f"no perf cells in {args.current} — nothing was measured, "
+              f"which the gate reads as a failure, not a pass.", file=sys.stderr)
+        return 1
+    baseline = load_cells(args.baseline) if args.baseline else {}
+
+    report = perf.gate_report(
+        baseline, current,
+        max_regression=args.threshold,
+        allow_incomparable=args.allow_incomparable,
+        require_min_runs=args.min_runs,
+    )
+    table = perf.release_table(list(current.values()), gate=report)
+
+    if args.report:
+        args.report.parent.mkdir(parents=True, exist_ok=True)
+        args.report.write_text(json.dumps(report, indent=2) + "\n", encoding="utf-8")
+    if args.table:
+        args.table.parent.mkdir(parents=True, exist_ok=True)
+        args.table.write_text(table, encoding="utf-8")
+
+    print(table)
+    if not baseline:
+        print("no baseline directory — cells recorded, nothing compared.", file=sys.stderr)
+    for cid in report["regressions"]:
+        print(f"REGRESSION: {cid}", file=sys.stderr)
+    for cid in report["missing_cells"]:
+        print(f"NOT MEASURED (baselined): {cid}", file=sys.stderr)
+    for cid in report["under_sampled_cells"]:
+        print(f"UNDER-SAMPLED: {cid}", file=sys.stderr)
+
+    return 0 if report["passed"] else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

{sourcecode-4.11.0 → sourcecode-4.14.0}/src/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.14.0"

{sourcecode-4.11.0 → sourcecode-4.14.0}/src/sourcecode/architectural_baseline.py

@@ -30,12 +30,14 @@ the perf baselines do.
 from __future__ import annotations
 
 import json
+import os
 import subprocess
 from datetime import datetime, timezone
 from pathlib import Path
 from typing import TYPE_CHECKING, Any
 
 from sourcecode import __version__ as TOOL_VERSION
+from sourcecode import readonly as _readonly
 from sourcecode.architectural_delta import ArchMetrics, diff_metrics, extract_metrics
 from sourcecode.perf import collect_env
 
@@ -365,21 +367,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,14 +412,41 @@ def protect_ask_dir(out_dir: Path) -> None:
             return
         marker = ask_dir / ".gitignore"
         if not marker.exists():
+            created = not ask_dir.exists()
+            # F-AS: the guard raises an OSError, which the `except OSError` below
+            # turns into "did not write" — the mode's promise, no new branch.
+            _readonly.guard(ask_dir, what="this tool's own directory")
             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."""
+    _readonly.guard(out_dir, what="baseline history directory")
     out_dir.mkdir(parents=True, exist_ok=True)
     protect_ask_dir(out_dir)
     path = out_dir / _baseline_filename(baseline)