sourcecode 5.9.7__tar.gz → 5.9.8__tar.gz

{sourcecode-5.9.7 → sourcecode-5.9.8}/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## [5.9.8] — 2026-08-27
+
+*Audit correction and contract-alignment patch release.*
+
+**Fixed**
+
+- Standardizes `review-pr` and `activate` failures on structured stderr envelopes.
+- Distinguishes command typos from implicit repository paths and suggests commands.
+- Rejects raw unified diffs passed to `--files -`; the option now accepts path lists only.
+- Streams child progress from `pack gate` without contaminating aggregate stdout.
+- Adds per-row timeout control to `selftest` and removes the fixed-size `cold-start` warning.
+
+**Documentation and validation**
+
+- Reconciles CLI/MCP population documentation and `rename-class` migration guidance.
+- Updates README, English and Spanish guides, roadmap, ledger and CLI version output.
+- Validated with dedicated regressions against `/Users/user/Documents/workspace/testing/teavm`.
+
 ## [5.9.6] — 2026-08-27
 
 *Roadmap correction and release-alignment patch release.*

{sourcecode-5.9.7 → sourcecode-5.9.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sourcecode
-Version: 5.9.7
+Version: 5.9.8
 Summary: Persistent structural context and ultra-fast repeated analysis for AI coding agents
 Project-URL: Homepage, https://github.com/HarounDominique/sourcecode
 Project-URL: Repository, https://github.com/HarounDominique/sourcecode
@@ -59,7 +59,7 @@ Description-Content-Type: text/markdown
 > question. All analysis is local and deterministic; see [Privacy](#configuration--privacy)
 > before inspecting a repository whose telemetry policy you need to control.
 
-![Version](https://img.shields.io/badge/version-5.9.7-blue)
+![Version](https://img.shields.io/badge/version-5.9.8-blue)
 ![Python](https://img.shields.io/badge/python-3.9%2B-green)
 
 Copyright (c) 2026 Dominique Haroun. All rights reserved. ASK Engine 5.7.0 and
@@ -196,7 +196,7 @@ set `ASK_MAX_RSS_MB=<megabytes>`; if the process exceeds it, ASK refuses the
 answer with `MEMORY_TOO_LARGE`, including the observed peak and limit. Leave it
 unset, or set it to `0`, to disable the ceiling explicitly.
 
-**Current performance status.** Release 5.9.7 retains the shared Canonical IR
+**Current performance status.** Release 5.9.8 retains the shared Canonical IR
 path used by `validation` and now passes that same CIR into labelled `data-exposure`
 runs; the no-label path remains parse-free. These are implementation properties,
 not duration promises. A controlled external warm-path audit has opened performance
@@ -218,7 +218,7 @@ in `overlapping_paths`; a missing or non-directory path is rejected as structure
 invalid input rather than treated as an empty repository. This prevents silent
 entitlement errors in CI and does not change per-repository gates or billing.
 
-Release 5.9.7 also hardens the boundary contracts: missing consumer repositories,
+Release 5.9.8 also hardens the boundary contracts: missing consumer repositories,
 malformed CVE feeds and unresolved `pack gate --since` refs fail as structured
 input errors; duplicate same-commit baselines are never overwritten. `posture
 --diff` validates unknown profiles when the repository declares profiles. In
@@ -251,7 +251,7 @@ brew tap haroundominique/sourcecode && brew install sourcecode
 # pip / pipx
 pipx install sourcecode        # or: pip install sourcecode
 
-ask version                    # ask 5.9.7 — and, on a build that has aged,
+ask version                    # ask 5.9.8 — and, on a build that has aged,
                                # how many releases have probably shipped since
 ```
 
@@ -501,6 +501,10 @@ The everyday loop: diff-based PR review, symptom-driven bug triage, and delta co
 
 ### 7 · Utilities
 `ask rename-class` (word-boundary Java rename) · `ask chunk-file` (split large files for agents) · `ask cache` (status / warm / model / clear / freshness) · `ask self-audit` (does the installed build's own registry agree with itself?)
+
+`rename-class` migration note: current releases require the explicit form
+`ask rename-class <repo> --from OldName --to NewName`. Older positional forms are
+not accepted; use `--dry-run` first when migrating scripts.
 → [reference](docs/USER_GUIDE.md)
 
 ---

{sourcecode-5.9.7 → sourcecode-5.9.8}/README.md

@@ -10,7 +10,7 @@
 > question. All analysis is local and deterministic; see [Privacy](#configuration--privacy)
 > before inspecting a repository whose telemetry policy you need to control.
 
-![Version](https://img.shields.io/badge/version-5.9.7-blue)
+![Version](https://img.shields.io/badge/version-5.9.8-blue)
 ![Python](https://img.shields.io/badge/python-3.9%2B-green)
 
 Copyright (c) 2026 Dominique Haroun. All rights reserved. ASK Engine 5.7.0 and
@@ -147,7 +147,7 @@ set `ASK_MAX_RSS_MB=<megabytes>`; if the process exceeds it, ASK refuses the
 answer with `MEMORY_TOO_LARGE`, including the observed peak and limit. Leave it
 unset, or set it to `0`, to disable the ceiling explicitly.
 
-**Current performance status.** Release 5.9.7 retains the shared Canonical IR
+**Current performance status.** Release 5.9.8 retains the shared Canonical IR
 path used by `validation` and now passes that same CIR into labelled `data-exposure`
 runs; the no-label path remains parse-free. These are implementation properties,
 not duration promises. A controlled external warm-path audit has opened performance
@@ -169,7 +169,7 @@ in `overlapping_paths`; a missing or non-directory path is rejected as structure
 invalid input rather than treated as an empty repository. This prevents silent
 entitlement errors in CI and does not change per-repository gates or billing.
 
-Release 5.9.7 also hardens the boundary contracts: missing consumer repositories,
+Release 5.9.8 also hardens the boundary contracts: missing consumer repositories,
 malformed CVE feeds and unresolved `pack gate --since` refs fail as structured
 input errors; duplicate same-commit baselines are never overwritten. `posture
 --diff` validates unknown profiles when the repository declares profiles. In
@@ -202,7 +202,7 @@ brew tap haroundominique/sourcecode && brew install sourcecode
 # pip / pipx
 pipx install sourcecode        # or: pip install sourcecode
 
-ask version                    # ask 5.9.7 — and, on a build that has aged,
+ask version                    # ask 5.9.8 — and, on a build that has aged,
                                # how many releases have probably shipped since
 ```
 
@@ -452,6 +452,10 @@ The everyday loop: diff-based PR review, symptom-driven bug triage, and delta co
 
 ### 7 · Utilities
 `ask rename-class` (word-boundary Java rename) · `ask chunk-file` (split large files for agents) · `ask cache` (status / warm / model / clear / freshness) · `ask self-audit` (does the installed build's own registry agree with itself?)
+
+`rename-class` migration note: current releases require the explicit form
+`ask rename-class <repo> --from OldName --to NewName`. Older positional forms are
+not accepted; use `--dry-run` first when migrating scripts.
 → [reference](docs/USER_GUIDE.md)
 
 ---

{sourcecode-5.9.7 → sourcecode-5.9.8}/docs/DEFECT-LEDGER.md

@@ -71,6 +71,35 @@ Commercially, the audit supports normal repositories up to several thousand
 files and keeps a provisional $35-50/developer/month range, but B01/B02 block
 annual-grade reliability and enterprise-scale positioning until resolved.
 
+**External audit intake `AUD-612`, re-audit of release 5.9.7 — 2026-08-27.**
+The external scope covered roughly 130 new invocations across three forks and direct
+retests of all AUD-611 items. It reports five clean forks, no target writes, commits
+or task-kills, and a score of **7.8/10**. It confirms B05, B06, B08, B09, B10 and B11,
+and reports B01 fixed in its own matrix; B01 remains release-artifact verification
+because the prior external round reproduced it. The new queue is:
+
+| ID | Severity | Status | Evidence / closure boundary |
+|---|---:|---|---|
+| AUD-612-B02 | Critical | open | `tutorials` root compact still timed out after 300-311s with zero stdout; warning proves activity, not completion. Define scale, deadline and partial-diagnostic contracts. |
+| AUD-612-B03 | High | closed | YAML cache-hit delivery now publishes `_cache.cache_source` and `timing_ms.served_from_cache` consistently; TeaVM YAML smoke plus the direct cache-hit seam regression pass. A real L2 benchmark remains follow-up because this environment rebuilt both runs. |
+| AUD-612-B04 | High | partial | Each `selftest` row now has configurable 120 s default timeout and structured timeout diagnostics/code 75; valid-row scale latency remains open for profiling. Dedicated TeaVM timeout contract regression passes. |
+| AUD-612-B07 | Medium | closed | `pr-impact --since` now resolves refs through the shared authority and publishes `GIT_REF_NOT_FOUND`; dedicated TeaVM and existing Git-ref regressions pass. |
+| AUD-612-B13 | Medium | closed/no-repro | Controlled TeaVM campaign: 30/30 `retrieve endpoint-security --endpoint /` executions completed with exit 0, valid JSON, no errors and stable content identity after cache warm-up. Reopen on a new correlated failure. |
+| AUD-612-L | High | open | `audit-report --format markdown` timed out at 420s/500s, 2/2, after ~228s in 5.9.6. Performance regression remains open; the one-shot heartbeat sub-issue is mitigated by repeated warnings. |
+| AUD-612-K | Medium | closed | Pack orchestration now streams child stderr, forwarding inherited `ASK_PROGRESS=1` progress while preserving aggregate stdout JSON. Dedicated TeaVM gate regression passes. |
+| AUD-612-M | Medium | closed | `explain` missing-class failures now use structured `INVALID_INPUT` stderr and `exit 1`; dedicated TeaVM regression passes. |
+| AUD-612-E | Medium | closed | The events branch now applies `_exit_on_unresolved_target`; missing event symbols return `not_found` with `exit 1`. TeaVM regression passes. |
+| AUD-612-G | Medium | closed | `review-pr` runtime failures and `activate` failures now publish the shared `error.code` envelope on stderr; stdout remains reserved for valid results. `no_diff` remains the intentional successful `no_changes` result. Dedicated TeaVM and contract tests pass. |
+| AUD-612-I | Medium | closed | Removed the residual `~10K` wording from the large-output warning; help, runtime warning and compact payload consistently describe a snapshot-dependent subset with explicit `full_available` metadata. Dedicated TeaVM regression passes. |
+| AUD-612-07 | Low | closed | Missing single tokens close to a registered command now use command admission with a nearest-command suggestion; existing paths retain implicit root-scan behavior. Dedicated TeaVM regression passes. |
+| AUD-612-09 | Medium | closed | `--files -` is documented and enforced as a newline-delimited changed-path list; raw unified diffs fail with an `--name-only` conversion hint. Dedicated TeaVM regressions pass. |
+| AUD-612-14 | Medium | closed | The current population is 104 CLI leaves versus 110 MCP tools, explicitly decomposed as 101 runtime-derived plus 9 native orchestration tools; `mcp list-tools --json` matches and the relationship is published. Existing TeaVM-backed population regression passes. |
+| AUD-612-R | Medium | closed | README, English guide and Spanish manual document that `rename-class` requires `--from/--to`, the old positional syntax is unsupported, and `--dry-run` is the migration safety step. TeaVM dry-run verification passes. |
+
+Commercially, normal repositories up to about 4,000 files remain viable at a provisional
+$40-55/developer/month. B02, B04 and L block annual CI-gating and extreme-monorepo claims;
+B03, K, M and G weaken machine-consumable evidence.
+
 **External audit intake `AUD-610`, release 5.9.3 — 2026-08-27.** The attached
 report scored the build **7.2/10** after five parallel batches and approximately
 120 invocations. It verified a clean target repository, no Java-file changes,

{sourcecode-5.9.7 → sourcecode-5.9.8}/docs/DEVELOPMENT-ROADMAP.md

@@ -3,7 +3,10 @@
 *Chief-engineer development record. This is the internal, dev-facing counterpart to the
 customer-facing `docs/EXECUTIVE-ROADMAP.md`.*
 
-> **CURRENT QUEUE — release `5.9.7`; external reconciliation `AUD-611` adds the next correction queue.**
+> **CURRENT QUEUE — release `5.9.8`; external reconciliation `AUD-612` is partially closed, with scale blockers retained.**
+> The latest re-audit confirms the main B05-B11 corrections but adds a confirmed
+> `audit-report` performance regression, a YAML cache-hit disclosure defect and
+> several contract-parity gaps. `AUD-611` remains the preceding audit record.
 > The 2026-08-27 external review adds `AUD-610-B01` through `AUD-610-B10`, led by
 > silent `selftest` nondeterminism, silent root/audit-report failures, a legal-zero
 > `risk --limit 0` crash, an unvalidated consumer path and contradictory Spring
@@ -211,6 +214,41 @@ findings block an annual-grade reliability claim. Pricing and enterprise
 positioning remain hypotheses until AUD-611-B01 and AUD-611-B02 are closed and
 the latency contract is explicit.
 
+### External Audit Intake — `AUD-612` re-audit, release 5.9.7
+
+The external re-audit covered repositories under `Documents/workspace/testing/` and
+ran approximately 130 new invocations across three forks, plus direct retests of all
+13 `AUD-611` items. It reports five clean forks, no target-repository changes, no
+commits and no task-kill intervention. The score is **7.8/10**, up from the recorded
+`AUD-611` score of 7.4/10. It confirms complete closure of B05, B06, B08, B09, B10
+and B11, confirms the endpoint compact disclosure improvement, and reports B01 as
+fixed in its own 13-run matrix. Because the preceding external round reproduced B01,
+that result remains release-artifact verification rather than erased history.
+
+| ID | Severity | Finding | Required future closure |
+|---|---:|---|---|
+| AUD-612-B02 | Critical | Cold root `ask . --compact` on `tutorials` (24,073 Java files) still timed out after 300-311 seconds with zero stdout; the 60-second warning proves activity but does not deliver a result. | Define and enforce a scale contract, bound or accelerate the root scan, and preserve structured partial/deadline diagnostics. |
+| AUD-612-B03 | High | **Closed in this fix.** The YAML cache-hit delivery branch now injects `_cache.cache_source` and refreshes `timing_ms.served_from_cache` from the same authoritative hit state as JSON. | Keep the YAML cache seam regression and a real cold/warm multi-process benchmark green; the current TeaVM environment did not generate an L2 hit spontaneously. |
+| AUD-612-B04 | High | **Partially closed in this fix.** `selftest` now bounds every ledger child with configurable `--timeout` (120 s default) and preserves structured timeout diagnostics/code 75. Valid-row scale latency remains open for profiling. TeaVM timeout contract regression passes. | Add phase/correlation IDs and profile slow valid rows; do not raise the default without evidence. |
+| AUD-612-B07 | Medium | **Closed in this fix.** `pr-impact --since` now resolves refs through the shared Git authority and publishes `GIT_REF_NOT_FOUND`, matching posture and timeline. | Keep the complete ref-consumer matrix green. |
+| AUD-612-B13 | Medium / investigation | **Closed as not reproduced in this investigation.** A controlled 30-run TeaVM campaign with an isolated cache completed 30/30 with exit 0, valid JSON, 0 errors and one stable content identity after warm-up. Reopen on any new failure with per-run correlation data. | Keep repeated/concurrent retrieval coverage in release audits. |
+| AUD-612-L | High / regression | `audit-report . --format markdown` timed out at 420s with contention and 500s in isolation, 2/2, after completing in about 228s in 5.9.6. The heartbeat-only sub-issue is now mitigated: warnings repeat at the configured interval. | Reproduce with a 900s diagnostic window, identify the performance regression and add a bounded failure envelope. |
+| AUD-612-K | Medium | **Closed in this fix.** Pack orchestration now forwards child stderr while each component runs, so inherited `ASK_PROGRESS=1` heartbeats reach the operator without contaminating the aggregate stdout JSON. TeaVM gate regression passes. | Keep nested progress and stdout purity tests green. |
+| AUD-612-M | Medium | **Closed in this fix.** `explain <nonexistent-class>` now emits `INVALID_INPUT` as structured stderr with `exit 1`; the internal explanation API remains unchanged. | Keep class-not-found and no-diff contract tests green for the remaining public commands. |
+| AUD-612-E | Medium | **Closed in this fix.** `impact-chain --type events` now applies the shared not-found exit policy after emitting its result, returning `exit 1` for unresolved symbols. | Keep every impact type on the shared CLI exit-policy test. |
+| AUD-612-G | Medium | **Closed in this fix.** `review-pr` runtime failures and `activate` failures now publish the shared `error.code` envelope on stderr, with stdout reserved for valid results. The intentional `review-pr` `no_diff` result remains `exit 0` / `no_changes`. TeaVM and contract regressions pass. | Keep public failure paths on the shared envelope and preserve the no-diff success semantics. |
+| AUD-612-I | Medium | **Closed in this fix.** The remaining `~10K` promise in the large-output warning is removed; help, runtime warning and compact payload now consistently describe a snapshot-dependent orientation subset with explicit `full_available` metadata. TeaVM compact regression passes. | Keep compact-size wording derived from the actual snapshot contract. |
+| AUD-612-07 | Low / UX | **Closed in this fix.** A missing single token close to a registered command is now rejected as an unknown command with nearest-command suggestions; existing paths retain implicit root-scan behavior. TeaVM path and typo regressions pass. | Keep command admission and implicit-path differential tests green. |
+| AUD-612-09 | Medium / docs | **Closed in this fix.** Help now describes `--files -` as a newline-delimited changed-path list. Raw unified diffs are rejected early with an `--name-only` conversion hint instead of being interpreted as file paths. TeaVM list and rejection regressions pass. | Keep the stdin grammar and raw-diff rejection tests green. |
+| AUD-612-14 | Medium / governance | **Closed in this reconciliation.** Current `self-audit` publishes 104 registered CLI leaves and 110 served MCP tools, decomposed as 101 runtime-derived plus 9 native orchestration tools; `mcp list-tools --json` matches 110. The payload states that the populations are intentionally different and gives the formula. Existing TeaVM-backed population regression passes. | Keep the population formula and parity regression generated from the live registries. |
+| AUD-612-R | Medium / migration | **Closed in this fix.** The explicit `--from/--to` contract is now documented in README, English guide and Spanish manual; the old positional syntax is explicitly marked unsupported and `--dry-run` is recommended for script migration. TeaVM dry-run verification passes. | Keep migration guidance aligned with the live command signature. |
+
+**Commercial interpretation.** Normal repositories up to roughly 4,000 files remain a
+credible adoption target, with the external estimate at **$40-55/developer/month**.
+The product is not yet suitable for annual CI-gating commitments or extreme monorepos:
+B02, B04 and regression L leave the system without a reliable completion contract,
+while K and the remaining performance rows weaken machine-consumable evidence and completion confidence.
+
 ### External Audit Intake — `AUD-610` detail, release 5.9.3
 
 The attached external report audited ASK `5.9.3` in five parallel batches

{sourcecode-5.9.7 → sourcecode-5.9.8}/docs/EXECUTIVE-ROADMAP.md

@@ -5,7 +5,7 @@
 > `pack assessment` and `pack gate`, and make evidence and safe change the
 > product surface. This roadmap must not introduce a competing product thesis.
 
-> **CURRENT UPDATE — release `5.9.7`, following the external `5.9.3` reconciliation.**
+> **CURRENT UPDATE — release `5.9.8`, following the external `5.9.3` reconciliation.**
 > The commercial increment adds stateless context budgets, a reproducible context-cost harness,
 > source-level migration SARIF and an opt-in workspace entitlement pilot. Advisory behaviour remains
 > the default; named-buyer validation is still required before broad enforcement.
@@ -19,6 +19,17 @@
 > non-reproduction did not cover the payload shape now identified. Details are
 > in [`AUDIT-2026-08-26-EXTERNAL-5.9.0.md`](AUDIT-2026-08-26-EXTERNAL-5.9.0.md).
 
+> **RE-AUDIT — 5.9.7, received 2026-08-27.** Three independent forks added roughly
+> 130 invocations and retested the AUD-611 queue. The score rose to **7.8/10** and
+> confirmed the help, stdin, Git-ref, intent, impact-score and progress corrections.
+> It also found a high-severity `audit-report --format markdown` performance regression
+> (420-500s without completion), a YAML cache-hit disclosure defect, missing progress
+> propagation in `pack gate`, and inconsistent error envelopes in `explain`, `review-pr`
+> and `activate`. B02/B04 and the new regression remain blockers for annual CI-gating
+> or extreme-monorepo positioning. Normal repositories around 4,000 files remain the
+> viable commercial segment at a provisional `$40-55/developer/month`. Full detail is
+> recorded as `AUD-612` in the development roadmap and defect ledger.
+
 > **RE-AUDIT — 5.9.6, received 2026-08-27.** Seven independent forks exercised
 > approximately 250 invocations across the testing corpus with no target-repository
 > mutation or regression in the three latest fixes. The final score is **7.4/10**.

{sourcecode-5.9.7 → sourcecode-5.9.8}/docs/MANUAL-USUARIO.md

@@ -1,6 +1,6 @@
 # Manual de usuario — ASK Engine
 
-> Versión de la herramienta: **5.9.7**  ·  El comando que se ejecuta es `ask`.
+> Versión de la herramienta: **5.9.8**  ·  El comando que se ejecuta es `ask`.
 > (`sourcecode` sigue funcionando como alias en desactivación y reenvía a `ask`.)
 > Público: personas que van a usar `ask` por primera vez, sin conocimiento previo.
 
@@ -8,7 +8,7 @@
 
 ## 1. ¿Qué es ASK Engine?
 
-### Contratos de fiabilidad de la versión 5.9.7
+### Contratos de fiabilidad de la versión 5.9.8
 
 Las entradas inválidas se rechazan antes del análisis costoso mediante el
 envelope estructurado `INVALID_INPUT`: un `--consumer` inexistente, un feed CVE
@@ -955,6 +955,11 @@ ask rename-class . --from OldName --to NewName --output rename-audit.json
 **Opciones:**
 - `--from` (**obligatorio**): nombre actual de la clase (PascalCase, p. ej. `ServiceA`).
 - `--to` / `-t` (**obligatorio**): nombre nuevo (PascalCase, p. ej. `ServiceB`).
+
+**Nota de migracion:** las versiones actuales exigen la forma explicita
+`ask rename-class <repo> --from NombreAntiguo --to NombreNuevo`. La sintaxis
+posicional antigua ya no se acepta. Al actualizar scripts, anade `--dry-run`
+para revisar primero el plan de cambios.
 - `--dry-run`: calcula los cambios pero **no escribe ni renombra** nada en disco.
 - `--no-tests`: excluye los ficheros de test del rename (solo `src/main`).
 - `--format`: `json` (por defecto) o `yaml`.

{sourcecode-5.9.7 → sourcecode-5.9.8}/docs/USER_GUIDE.md

@@ -46,16 +46,16 @@ CLI commands        — impact, endpoints, spring-audit, explain, … each a pro
 The key idea: the extraction is **content-addressed**. Commands reuse the parse cache and,
 where their analysed scope matches, the shared Canonical IR; `ask cache model` names what a
 warm buys for each command rather than implying that every projection costs the same. In
-5.9.7, `validation` enters through that shared CIR and `data-exposure` reuses one semantic
+5.9.8, `validation` enters through that shared CIR and `data-exposure` reuses one semantic
 model across all declared label seeds. (The extraction and consumption contract is fixed in
 the architecture ADRs 0001–0004 under `docs/architecture/`.)
 
 The current external pack audit intake is tracked in
 [`AUDIT-2026-08-26-EXTERNAL-5.8.28-PACK.md`](AUDIT-2026-08-26-EXTERNAL-5.8.28-PACK.md);
-the two pack fixes are included in release 5.9.7, with release-artifact verification
+the two pack fixes are included in release 5.9.8, with release-artifact verification
 remaining for detached execution and pack evidence.
 
-### Reliability contracts in 5.9.7
+### Reliability contracts in 5.9.8
 
 Invalid analysis inputs fail before expensive work and use the structured
 `INVALID_INPUT` envelope: a missing `--consumer` repository, a malformed CVE
@@ -236,7 +236,7 @@ pipx install sourcecode   # isolated install, no venv needed
 
 # Verify
 ask version
-# ask 5.9.7
+# ask 5.9.8
 ```
 
 Requires Python 3.9+.
@@ -1381,6 +1381,10 @@ explaining. The rest do one thing; `ask <command> --help` is the whole story.
 | `ask chunk-file <file>` | supported | Split a large Java file into semantic chunks an agent can consume |
 | `ask intent "<question>"` | supported | Resolve a plain-language question to the typed `retrieve` query that answers it (scored lexical match against a declared vocabulary — no model, no generation). Prints the query; `--run` executes it. A question fitting two intents too closely is refused with both named. |
 | `ask rename-class` | supported | Word-boundary Java rename across the repository |
+
+**Migration note:** `rename-class` requires the explicit `--from OldName --to NewName`
+options. Older positional name syntax is no longer accepted. Add `--dry-run` when
+updating an existing script so the planned file changes can be reviewed first.
 | `ask schema <name>` | supported | Print a published JSON Schema for this tool's output |
 | `ask self-audit` | supported | Check the SHIPPED build's own coherence — cache model, format contract, schema registry and output affordances. Declares explicitly that the semantic engine does not apply to this product's own source (ASK analyses Java; this build is Python), rather than reporting zeros. `ask selftest` is the different question: the defect ledger run against a real repository. |
 | `ask auth workspace <repo>...` | supported | Aggregate workspace entitlement preview. `--enforce` opts into the named-buyer pilot that reuses the existing Pro gate when the organization-sized threshold is crossed; advisory mode remains the default and the CLI does not bill. |

{sourcecode-5.9.7 → sourcecode-5.9.8}/pyproject.toml

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

{sourcecode-5.9.7 → sourcecode-5.9.8}/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__ = "5.9.7"
+__version__ = "5.9.8"

{sourcecode-5.9.7 → sourcecode-5.9.8}/src/sourcecode/cli.py

@@ -900,8 +900,8 @@ scope matches; `ask cache model` says exactly what a warm buys per command.
 [bold]Change and risk:[/bold]
   impact-chain <Class> .       [dim]# blast radius; TX/SEC findings opt-in[/dim]
   impact <Class> .             [dim]# reverse deps → endpoints reached[/dim]
-  pr-impact . --files -        [dim]# same, scoped to a diff on stdin; gating codes[/dim]
-  pr-risk . --files -          [dim]# one verdict for THIS diff; UNKNOWN fails the gate[/dim]
+  pr-impact . --files -        [dim]# changed-file list on stdin; gating codes[/dim]
+  pr-risk . --files -          [dim]# changed-file list on stdin; UNKNOWN fails the gate[/dim]
   posture . --since main       [dim]# did this branch open an endpoint? (exp.)[/dim]
   drift . --profile prod       [dim]# what opened up since the last capture[/dim]
   audit-report . --format markdown [dim]# signed human evidence bundle (exp.)[/dim]
@@ -1299,6 +1299,15 @@ def _preprocess_args(args: list[str]) -> list[str]:
         # got wrong instead of swallowing it and erroring on the next one.
         if _has_trailing_nonsubcommand_positional(result, i):
             _reject_unknown_command(arg)
+        # A single missing token that is very close to a command is a command
+        # typo, not a repository path. Existing directories retain the implicit
+        # `ask <path>` grammar, including names that resemble commands.
+        if not Path(arg).exists():
+            _command_matches = difflib.get_close_matches(
+                arg, sorted(_SUBCOMMANDS), n=3, cutoff=0.6
+            )
+            if _command_matches:
+                _reject_unknown_command(arg)
         _set_detected_path(arg)
         _path_index = i
     if _path_index >= 0:
@@ -1455,6 +1464,56 @@ def _inject_cache_meta(raw: str, meta: dict) -> str:
     return raw
 
 
+def _inject_cache_meta_yaml(raw: str, meta: dict) -> str:
+    """Inject the same cache provenance into a YAML answer as into JSON."""
+    try:
+        from io import StringIO
+        from ruamel.yaml import YAML as _YAML
+
+        yaml = _YAML()
+        obj = yaml.load(raw)
+        if isinstance(obj, dict):
+            obj["_cache"] = meta
+            if "cache_source" in meta:
+                obj["cache_source"] = meta["cache_source"]
+            out = StringIO()
+            yaml.dump(obj, out)
+            return out.getvalue()
+    except Exception:
+        pass
+    return raw
+
+
+def _refresh_delivery_timing_yaml(raw: str, *, served_from_cache: bool, elapsed_ms: float) -> str:
+    """Refresh cache timing in YAML without routing the machine answer through JSON."""
+    try:
+        from io import StringIO
+        from ruamel.yaml import YAML as _YAML
+
+        yaml = _YAML()
+        obj = yaml.load(raw)
+        if not isinstance(obj, dict):
+            return raw
+        meta = obj.setdefault("_meta", {})
+        if not isinstance(meta, dict):
+            return raw
+        timing = meta.setdefault("timing_ms", {})
+        if not isinstance(timing, dict):
+            timing = {}
+            meta["timing_ms"] = timing
+        timing["total_ms"] = round(elapsed_ms, 2)
+        timing["served_from_cache"] = served_from_cache
+        timing["timing_basis"] = "served_from_snapshot" if served_from_cache else "computed"
+        if served_from_cache:
+            timing["phase_timing_basis"] = "snapshot_build"
+        out = StringIO()
+        yaml.dump(obj, out)
+        return out.getvalue()
+    except Exception:
+        pass
+    return raw
+
+
 def _refresh_delivery_timing(
     raw: str,
     *,
@@ -3557,7 +3616,17 @@ def _resolve_files_option(
                 ),
             )
             raise typer.Exit(code=1)
-        return _text_input.parse_path_lines(_text_input.read_stdin_text()), "stdin"
+        stdin_text = _text_input.read_stdin_text()
+        if "diff --git " in stdin_text or "\n@@ " in stdin_text:
+            _emit_error_json(
+                INVALID_INPUT_CODE,
+                "--files - expects a list of changed paths, not a raw unified diff.",
+                hint=f"Pipe paths with: git diff --name-only REF | ask {command} . --files -",
+                expected="One repository-relative file path per line.",
+                reason="raw_diff_on_stdin",
+            )
+            raise typer.Exit(code=1)
+        return _text_input.parse_path_lines(stdin_text), "stdin"
     as_path = Path(raw)
     if as_path.is_file():
         return (
@@ -3587,6 +3656,20 @@ def _resolve_files_option(
 def _git_changed_files(root: Path, since: Optional[str]) -> "tuple[list[str], str]":
     """Resolve a local Git diff without network access or repository mutation."""
     if since:
+        # Resolve the ref through the shared authority before asking Git for the
+        # diff, so every consumer publishes the canonical ref error code.
+        from sourcecode.git_checkout import RefError, resolve_ref
+
+        try:
+            resolve_ref(root, since)
+        except RefError as exc:
+            _emit_error_json(
+                exc.code,
+                exc.message,
+                hint="Check the repository and ref, or pass --files explicitly.",
+                ref=since,
+            )
+            raise typer.Exit(code=1)
         command = ["git", "diff", "--name-only", since, "HEAD"]
         description = f"git diff {since} HEAD"
     else:
@@ -6054,6 +6137,26 @@ def main(
                             )
                     except Exception:
                         pass  # stale value better than crash
+            else:
+                _cache_hit_content = _inject_cache_meta_yaml(
+                    _cache_hit_content,
+                    _cache_meta_block(
+                        cache_source=_hit_source,
+                        git_head_at_generation=_git_sha,
+                        current_git_head=_git_sha,
+                        has_uncommitted_changes=False,
+                        has_uncommitted_changes_basis="YAML cache delivery",
+                        generated_at=None,
+                        data_scope=("COMPACT" if compact else ("AGENT" if agent else "FULL")),
+                        target=target,
+                        with_ris_fact=True,
+                    ),
+                )
+                _cache_hit_content = _refresh_delivery_timing_yaml(
+                    _cache_hit_content,
+                    served_from_cache=True,
+                    elapsed_ms=(time.monotonic() - _t0) * 1000,
+                )
             # C1: token economy on the agent-facing views (cache-hit path).
             if format == "json" and (compact or agent):
                 from sourcecode.token_estimate import inject_token_economy as _inj_te
@@ -7828,31 +7931,33 @@ def prepare_context_cmd(
     # review-pr specific fields
     if task == "review-pr":
         if output.error_code:
-            _err_out: dict[str, Any] = {
-                "task": output.task,
-                "ci_decision": output.ci_decision or "error",
-                "error": output.error_code,
-                "message": output.error_message,
-            }
-            if output.since:
-                _err_out["since"] = output.since
-            if output.error_hints:
-                _err_out["hint"] = output.error_hints
-            # AUD-598-B01: an early return is still this run's whole answer, so
-            # it carries the same identity as the long one.
-            _err_json = _stamp_envelope(
-                json.dumps(_err_out, indent=2, ensure_ascii=_json_ensure_ascii())
+            if output.error_code == "no_diff":
+                _no_diff_out = {
+                    "task": output.task,
+                    "ci_decision": "no_changes",
+                    "summary": "No changes detected",
+                }
+                _no_diff_json = _stamp_envelope(
+                    json.dumps(_no_diff_out, indent=2, ensure_ascii=_json_ensure_ascii())
+                )
+                if output_path is not None:
+                    _safe_write_file(output_path, _no_diff_json)
+                else:
+                    sys.stdout.buffer.write(_no_diff_json.encode("utf-8"))
+                    sys.stdout.buffer.write(b"\n")
+                    sys.stdout.buffer.flush()
+                raise typer.Exit()
+            _error_hint = " ".join(str(h) for h in (output.error_hints or []))
+            _emit_error_json(
+                output.error_code,
+                output.error_message or "review-pr could not complete.",
+                command="review-pr",
+                ci_decision=output.ci_decision or "error",
+                since=output.since or None,
+                hint=_error_hint or None,
+                hints=output.error_hints or None,
             )
-            if output_path is not None:
-                _safe_write_file(output_path, _err_json)
-            else:
-                sys.stdout.buffer.write(_err_json.encode("utf-8"))
-                sys.stdout.buffer.write(b"\n")
-                sys.stdout.buffer.flush()
-            # FIX: no_diff (no PR changes) is not an error — exit 0, consistent
-            # with delta's no_changes handling. Only true errors exit non-zero.
-            _review_pr_exit = 0 if output.error_code == "no_diff" else 1
-            raise typer.Exit(code=_review_pr_exit)
+            raise typer.Exit(code=1)
         out["review_type"] = "pull_request"
         if output.ci_decision:
             out["ci_decision"] = output.ci_decision
@@ -15675,6 +15780,7 @@ def impact_chain_cmd(
                 f"{evt_result.metadata.get('consumer_count', 0)} consumers)"
             ),
         )
+        _exit_on_unresolved_target(evt_result.resolution)
         return
 
     result = run_impact_chain(
@@ -16051,6 +16157,15 @@ def explain_cmd(
     else:
         output = explanation.render_text()
 
+    if not explanation.found:
+        _emit_error_json(
+            INVALID_INPUT_CODE,
+            f"Class '{class_name}' was not found in repository symbols.",
+            hint="Pass an existing class name or FQN; use `ask repo-ir` for the symbol list.",
+            expected="A class present in the analyzed repository.",
+        )
+        raise typer.Exit(code=1)
+
     _emit_command_output(output, output_path, copy,
                          success_msg=f"Explanation written to {output_path}")
 
@@ -18059,6 +18174,10 @@ def selftest_cmd(
              "checkout's runner). Published with every verdict — the difference "
              "ASK-09 hid in was the entry point, not the repository.",
     ),
+    timeout: int = typer.Option(
+        120, "--timeout", min=1,
+        help="Maximum seconds allowed for each ledger row (default: 120).",
+    ),
     output_path: Optional[Path] = typer.Option(
         None, "--output", "-o", help="Write the verdicts to a file instead of stdout.",
     ),
@@ -18111,7 +18230,9 @@ def selftest_cmd(
     _prog = Progress()
     _prog.start("running the ledger against this repository")
     try:
-        data = run_selftest(target, rows=selected, entry_point=entry_point)
+        data = run_selftest(
+            target, rows=selected, entry_point=entry_point, timeout=timeout
+        )
     finally:
         _prog.stop()
 
@@ -19413,7 +19534,7 @@ def cold_start_cmd(
         _notice(
             f"WARNING: Output is ~{_tokens // 1000}K tokens. This exceeds the context window of "
             "most LLMs (GPT-4o: 128K, Claude Sonnet: 200K). "
-            "Use --compact for a ~10K token subset, or --output FILE to save."
+            "Use --compact for a snapshot-dependent orientation subset, or --output FILE to save."
         )
     # AUD-596-D01: this payload builds its own `_meta` above (estimated tokens,
     # token economy) and used to skip the envelope for that reason — so the one

{sourcecode-5.9.7 → sourcecode-5.9.8}/src/sourcecode/license.py

@@ -715,8 +715,8 @@ def require_pro(feature_name: str) -> None:
 def activate_license(license_key: str) -> None:
     """Validate license_key via Edge Function, write ~/.sourcecode/license.json.
 
-    Outputs JSON to stdout; exits 0 on success, 1 on any failure.
-    Never raises — all error paths emit JSON and call sys.exit(1).
+    Outputs JSON to stdout on success; exits 0 on success, 1 on any failure.
+    Errors use the CLI JSON envelope on stderr so stdout remains machine-safe.
     """
     if not _LICENSE_KEY_RE.match(license_key):
         _fail("invalid_license", "License key format is invalid.")
@@ -760,8 +760,10 @@ def activate_license(license_key: str) -> None:
 # ---------------------------------------------------------------------------
 
 def _fail(error: str, message: str) -> None:
-    """Emit JSON error to stdout and exit 1. Never returns."""
-    payload = {"error": error, "message": message}
-    sys.stdout.write(json.dumps(payload, ensure_ascii=False) + "\n")
-    sys.stdout.flush()
+    """Emit the shared structured error envelope to stderr and exit 1."""
+    from sourcecode.error_schema import build_error_envelope
+
+    payload = build_error_envelope(error, message, command="activate")
+    sys.stderr.write(json.dumps(payload, ensure_ascii=False) + "\n")
+    sys.stderr.flush()
     sys.exit(1)