sourcecode 5.8.30__tar.gz → 5.8.31__tar.gz

sourcecode-5.8.31/.github/workflows/build-windows.yml

@@ -0,0 +1,78 @@
+name: Build Windows EXE
+
+on:
+  workflow_dispatch:
+
+jobs:
+  build-windows:
+    runs-on: windows-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install build
+          pip install nuitka
+
+      - name: Build wheel artifact
+        run: python -m build --wheel --outdir build/wheel
+
+      - name: Install wheel artifact
+        run: pip install build/wheel/*.whl
+
+      - name: Build EXE
+        run: |
+          python -m nuitka ^
+            --onefile ^
+            --standalone ^
+            --follow-imports ^
+            --assume-yes-for-downloads ^
+            --output-dir=build ^
+            run_cli.py
+        shell: cmd
+
+      - name: Verify detached worker from installed artifact
+        shell: pwsh
+        run: |
+          $root = Join-Path $env:RUNNER_TEMP "ask-detached-repo"
+          $output = Join-Path $env:RUNNER_TEMP "ask-detached.json"
+          New-Item -ItemType Directory -Force (Join-Path $root "src/main/java/com/acme") | Out-Null
+          Set-Content -Path (Join-Path $root "pom.xml") -Value '<project><modelVersion>4.0.0</modelVersion><groupId>com.acme</groupId><artifactId>app</artifactId><version>1</version></project>'
+          Set-Content -Path (Join-Path $root "src/main/java/com/acme/App.java") -Value 'package com.acme; public class App {}'
+          python -m sourcecode spring-audit $root --output $output --detach
+          for ($i = 0; $i -lt 60 -and -not (Test-Path $output); $i++) { Start-Sleep -Seconds 1 }
+          if (-not (Test-Path $output)) { throw "Detached worker did not write its artifact" }
+          $payload = Get-Content $output -Raw | ConvertFrom-Json
+          if (-not $payload) { throw "Detached artifact is not valid JSON" }
+
+      - name: Verify pack fixes from installed artifact
+        shell: pwsh
+        run: |
+          $root = Join-Path $env:RUNNER_TEMP "ask-pack-repo"
+          New-Item -ItemType Directory -Force (Join-Path $root "src/main/java/com/acme") | Out-Null
+          New-Item -ItemType Directory -Force (Join-Path $root "src/test/java/com/acme") | Out-Null
+          Set-Content -Path (Join-Path $root "pom.xml") -Value '<project><modelVersion>4.0.0</modelVersion><groupId>com.acme</groupId><artifactId>app</artifactId><version>1</version></project>'
+          Set-Content -Path (Join-Path $root "src/main/java/com/acme/App.java") -Value 'package com.acme; public class App {}'
+          Set-Content -Path (Join-Path $root "src/test/java/com/acme/AppTest.java") -Value 'package com.acme; public class AppTest {}'
+          git -C $root init --quiet
+          git -C $root config user.email ci@example.invalid
+          git -C $root config user.name ASK-CI
+          git -C $root add .
+          git -C $root commit --quiet -m baseline
+          Add-Content -Path (Join-Path $root "src/test/java/com/acme/AppTest.java") -Value '// test-only change'
+          python -m sourcecode pack gate $root --since HEAD --format json --output-dir (Join-Path $env:RUNNER_TEMP "ask-gate")
+          python -m sourcecode pack assessment $root --only posture,risk --compact --progress stderr
+
+      - name: Upload artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: sourcecode-windows
+          path: build/**/*.exe

{sourcecode-5.8.30 → sourcecode-5.8.31}/.github/workflows/windows-battery.yml

@@ -17,8 +17,6 @@ jobs:
   battery:
     runs-on: windows-latest
     env:
-      NO_COLOR: "1"
-      TERM: "dumb"
       # CLI payloads and diagnostics are UTF-8 contracts. Without this Windows
       # decodes child-process output with the active code page, turning a valid
       # JSON answer containing source text into an empty/failed test response.

{sourcecode-5.8.30 → sourcecode-5.8.31}/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## [5.8.31] — 2026-08-26
+
+*Windows portability and release-evidence remediation. Cache and licensing test
+isolation now honours explicit `HOME` overrides, warm workers use the active
+interpreter, migration and identity paths remain portable, and the Windows CI
+battery no longer disables the rendered help contract. Unix-only permission probes
+are skipped on Windows. Local full-suite verification is green; native Windows
+release-artifact verification remains the CI acceptance step.*
+
 ## [5.8.30] — 2026-08-26
 
 *Pack audit remediation release. Unresolved test-only Java files no longer broaden

{sourcecode-5.8.30 → sourcecode-5.8.31}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sourcecode
-Version: 5.8.30
+Version: 5.8.31
 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.8.30-blue)
+![Version](https://img.shields.io/badge/version-5.8.31-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
@@ -177,7 +177,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.8.30 retains the shared Canonical IR
+**Current performance status.** Release 5.8.31 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
@@ -210,7 +210,7 @@ brew tap haroundominique/sourcecode && brew install sourcecode
 # pip / pipx
 pipx install sourcecode        # or: pip install sourcecode
 
-ask version                    # ask 5.8.30 — and, on a build that has aged,
+ask version                    # ask 5.8.31 — and, on a build that has aged,
                                # how many releases have probably shipped since
 ```
 

{sourcecode-5.8.30 → sourcecode-5.8.31}/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.8.30-blue)
+![Version](https://img.shields.io/badge/version-5.8.31-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
@@ -128,7 +128,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.8.30 retains the shared Canonical IR
+**Current performance status.** Release 5.8.31 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
@@ -161,7 +161,7 @@ brew tap haroundominique/sourcecode && brew install sourcecode
 # pip / pipx
 pipx install sourcecode        # or: pip install sourcecode
 
-ask version                    # ask 5.8.30 — and, on a build that has aged,
+ask version                    # ask 5.8.31 — and, on a build that has aged,
                                # how many releases have probably shipped since
 ```
 

{sourcecode-5.8.30 → sourcecode-5.8.31}/docs/DEFECT-LEDGER.md

@@ -25,7 +25,7 @@ checkout by `52bcc36` and `f89ae18`, with focused regression batteries passing;
 artefact verification remains pending. The pack's `--since` timing is additional evidence
 for `AUD-604-P01`, not a duplicate performance finding.
 
-**Current `5.8.30` queue:** artefact verification for `AUD-604-R01`; the two `AUD-605`
+**Current `5.8.31` queue:** artefact verification for `AUD-604-R01`; the two `AUD-605`
 fixes are included in this release and await release-artefact verification.
 
 **External `5.8.28` audit received, 2026-08-26 - `AUD-604`.**

{sourcecode-5.8.30 → sourcecode-5.8.31}/docs/DEVELOPMENT-ROADMAP.md

@@ -3,7 +3,7 @@
 *Chief-engineer development record. This is the internal, dev-facing counterpart to the
 customer-facing `docs/EXECUTIVE-ROADMAP.md`.*
 
-> **CURRENT QUEUE — release `5.8.30`, following the external pack audit of `5.8.28`, received 2026-08-26.** `AUD-605-G01` (P2,
+> **CURRENT QUEUE — release `5.8.31`, following the external pack audit of `5.8.28`, received 2026-08-26.** `AUD-605-G01` (P2,
 > unresolved test files broadened pack-gate uncertainty to unrelated endpoints) and `AUD-605-U01` (P2, pack assessment did not
 > forward foreground progress) are implemented in the current checkout in commits `52bcc36` and `f89ae18`; focused batteries pass.
 > The pack audit adds evidence to `AUD-604-P01`, but does not open a duplicate performance row.
@@ -16,6 +16,49 @@ customer-facing `docs/EXECUTIVE-ROADMAP.md`.*
 > Pack evidence is in [`AUDIT-2026-08-26-EXTERNAL-5.8.28-PACK.md`](AUDIT-2026-08-26-EXTERNAL-5.8.28-PACK.md). Release-artifact
 > verification of the two pack fixes remains after `AUD-604-R01`.
 
+## Current Product Direction
+
+This is the adopted interpretation of the external strategy report. It supersedes
+the report's broader or duplicate proposals while retaining the historical queues
+below as evidence. The governing product boundary remains the deterministic,
+source-backed Java/Spring evidence layer in [`PRODUCT-ROUTE.md`](PRODUCT-ROUTE.md).
+
+### Fixes
+
+| ID | Priority | Scope | Acceptance criteria | Status/order |
+|---|---:|---|---|---|
+| `DIR-F01` | P1 | Replace pattern-only security decisions with shared semantic authorities. Distinguish definitions from invocations and production code from tests, examples and library code. | Each affected rule has a named population, source-backed reason and `non_coverage`; false-positive fixtures cover the reported `SEC-004` / `DEAD-001` shapes. | **Implemented:** current security scans exclude platform definitions, imports, Javadoc and live controls; future rules must use the same authority. |
+| `DIR-F02` | P1 | Extend safe guardrails to genuinely heavy commands and compositions. | A bounded run stops the phase doing the work, publishes partial counts and confidence reduction, preserves completed evidence, and never presents an advisory-only command as enforceable. | **Implemented:** `BUDGETED_ANALYSIS_COMMANDS`, `PhasedRun` and partial-answer contracts bind the current heavy population. New heavy commands must join this registry. |
+| `DIR-F03` | P1 | Finish CI gate ergonomics without weakening its evidence contract. | Verify the `5.8.31` pack fixes in release artefacts, then add only evidence-backed improvements such as PR-native change resolution and selective component control. `AUD-605-G01` is already fixed; test-only unresolved files must not return as a roadmap item. | **Implemented in `4d87532`:** `pack gate --pr` uses GitHub changed files and requires the exact local base SHA. Release-artifact verification remains. |
+| `DIR-F04` | P2 | Consolidate reusable semantic predicates used by security and dead-code rules. | One authority is consumed by all relevant rules; population and parity tests prevent a rule from silently reverting to textual matching. This is an implementation constraint, not a new user-facing command. | **Implemented for current rules:** `source_text` owns comment/Javadoc views and security scans consume them. Future rules remain bound to this constraint. |
+| `DIR-F05` | P2 | Continue operational observability for cost and confidence. | Timed answers publish cache state, phase/component progress, coverage, confidence and attributable run conditions; no cross-repository SLA or single-machine duration promise is published. | **Implemented for current timed surfaces;** continuous admission rule for new ones. |
+
+### Features
+
+| ID | Priority | Feature | Boundary and acceptance criteria | Status/order |
+|---|---:|---|---|---|
+| `DIR-X01` | P1 | Narrow Spring data-flow analysis. | Start with HTTP inputs, SQL/command/network/template sinks and explicit sanitizers. Publish confirmed paths, confidence and non-coverage; do not claim CodeQL-equivalent coverage. Design only after `DIR-F01` and `DIR-F02` are stable. | Conditional medium-term bet |
+| `DIR-X02` | P2 | CI and developer-surface integrations. | Prefer a thin GitHub Action and existing SARIF/CI renderers over another analyzer. A future IDE integration must consume ASK JSON/MCP evidence, preserve attribution and add no second semantic model. | **Implemented baseline:** MCP, SARIF and GitHub/GitLab renderers ship. A distributable Action or IDE surface needs named-buyer validation. |
+| `DIR-X03` | P2 | Selective and reusable pack execution. | `pack assessment` may select or reuse declared components only when tree state, inputs and fingerprints prove reuse; the manifest must say what ran and what was reused. This extends existing `S-24`, not a new pack architecture. | **Selection implemented in `9f4c0e1`:** `--only` runs declared components and publishes omissions. Artifact reuse remains evidence-gated. |
+| `DIR-X04` | P3 | Targeted Spring ecosystem coverage. | Admit Spring Cloud, GraphQL or another adjacent surface only when a named buyer supplies a reproducible gap and the new parser/rule set preserves the same evidence contract. | Evidence-gated |
+
+### Explicitly Rejected
+
+These are not roadmap work: `--format` and `--compact` remain separate contracts;
+`ask defects` is not a product priority; broad .NET/Node/TypeScript expansion is
+deferred; ML-based prioritisation and automatic refactoring stay outside ASK's
+deterministic core; SBOM/dashboard/hosted-agent scope is outside the product route;
+and competitor accuracy claims require a reproducible benchmark before they can be
+documented as facts.
+
+### Decision Order
+
+1. Verify the `5.8.31` release artefacts, especially Windows detached execution and packs.
+2. Keep `DIR-F01`, `DIR-F02`, `DIR-F04` and `DIR-F05` as admission constraints for every new rule or heavy command.
+3. Validate `DIR-F03` and `DIR-X03` on named CI repositories before adding artifact reuse or a packaged Action.
+4. Design `DIR-X01` only after a source/sink/sanitizer corpus establishes its coverage contract; admit `DIR-X04` only from buyer evidence.
+5. Keep all rejected items out of active planning unless the product route is explicitly revised.
+
 > **Previous queue — external audit of `5.8.27`, received 2026-08-26.** `AUD-603-R01` (P1,
 > detached worker exits because the module entry point is not invoked) -> `AUD-603-S01`
 > (P1, DEAD-001 comment-prose false positive) -> `AUD-603-O01` (P2, posture diff compact

{sourcecode-5.8.30 → sourcecode-5.8.31}/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 STATUS — release `5.8.30`, following the `5.8.28` external audit intake, 2026-08-26.** The semantic
+> **CURRENT STATUS — release `5.8.31`, following the `5.8.28` external audit intake, 2026-08-26.** The semantic
 > regression matrix remains green: detached execution, DEAD-001 comment handling,
 > Boot 3 applicability, non-interactive selftest scope communication, nested diff
 > bounding and help timing guidance are confirmed fixed. The reported cold-cost signal
@@ -28,6 +28,30 @@
 > not a separate regression claim. Details are in
 > [`AUDIT-2026-08-26-EXTERNAL-5.8.28-PACK.md`](AUDIT-2026-08-26-EXTERNAL-5.8.28-PACK.md).
 
+> **ADOPTED DIRECTION — strategy review, 2026-08-26.** ASK will deepen its existing
+> moat instead of becoming a general SAST or AI platform. Semantic security accuracy,
+> safe guardrails and honest operational metrics are now implementation constraints;
+> CI gate ergonomics and selective pack execution are implemented in `4d87532` and
+> `9f4c0e1`. The remaining strategic candidates are a narrowly scoped Spring data-flow
+> prototype and evidence-led coverage of adjacent Spring surfaces.
+
+> **What this means in practice.** Every fix must name its analysed population, source
+> authority, confidence and non-coverage, and ship with a regression fixture. Every new
+> feature must reuse the shared semantic model, preserve deterministic evidence and have
+> a named buyer or reproducible user gap. `AUD-605-G01` is already fixed in 5.8.31; it is
+> not reopened as a future feature merely because the report described the old behaviour.
+
+> **Explicitly out of scope.** `--format` and `--compact` remain separate contracts;
+> a defect-ledger command, broad .NET/Node/TypeScript support, ML prioritisation,
+> automatic refactoring, generic SBOM/dashboard management and a hosted coding agent
+> are rejected for this route. Competitor accuracy figures are not roadmap evidence
+> without a reproducible benchmark.
+
+> **Order:** verify the 5.8.31 artefacts; validate the new CI/pack paths with named buyers;
+> then admit data-flow only with a source/sink/sanitizer corpus and ecosystem work only with
+> buyer evidence. Detailed IDs, boundaries and acceptance criteria are in
+> [`DEVELOPMENT-ROADMAP.md`](DEVELOPMENT-ROADMAP.md) under *Current Product Direction*.
+
 > **CURRENT STATUS — `5.8.26` external audit intake, 2026-08-23.** The active engineering
 > queue is `impact-chain` bounded-output regression, `posture --diff --compact` usability,
 > deterministic root fingerprints, sustained warm-path performance and closure-provenance

{sourcecode-5.8.30 → sourcecode-5.8.31}/docs/USER_GUIDE.md

@@ -46,13 +46,13 @@ 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.8.30, `validation` enters through that shared CIR and `data-exposure` reuses one semantic
+5.8.31, `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.8.30, with release-artifact verification
+the two pack fixes are included in release 5.8.31, with release-artifact verification
 remaining for detached execution and pack evidence.
 
 ---
@@ -183,7 +183,7 @@ pipx install sourcecode   # isolated install, no venv needed
 
 # Verify
 ask version
-# ask 5.8.30
+# ask 5.8.31
 ```
 
 Requires Python 3.9+.

{sourcecode-5.8.30 → sourcecode-5.8.31}/pyproject.toml

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

{sourcecode-5.8.30 → sourcecode-5.8.31}/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.8.30"
+__version__ = "5.8.31"

{sourcecode-5.8.30 → sourcecode-5.8.31}/src/sourcecode/cache.py

@@ -82,6 +82,12 @@ CORE_SCHEMA_VERSION: str = "1"
 ANALYZER_CACHE_VERSION: str = "1"
 
 
+def _user_home() -> Path:
+    """Honor an explicit HOME override before Windows' USERPROFILE fallback."""
+    configured = os.environ.get("HOME")
+    return Path(configured) if configured else Path.home()
+
+
 def analyzer_fingerprint() -> str:
     """Content hash of the analysis code, memoised for the process.
 
@@ -325,7 +331,7 @@ def cache_dir(repo_root: Path) -> Path:
     Override the base via ``SOURCECODE_CACHE_DIR``.
     """
     env_base = os.environ.get("SOURCECODE_CACHE_DIR", "")
-    base: Path = Path(env_base) if env_base else Path.home() / ".sourcecode" / "cache"
+    base: Path = Path(env_base) if env_base else _user_home() / ".sourcecode" / "cache"
     return base / repo_id(repo_root)
 
 

{sourcecode-5.8.30 → sourcecode-5.8.31}/src/sourcecode/cli.py

@@ -3415,7 +3415,6 @@ COMMANDS_WITHOUT_PROGRESS: "frozenset[str]" = frozenset({
     "baseline trend",   # same command under the group name
     "regress",          # reads two named JSON files; analyses no repository
     "pack list",        # fixed local catalog
-    "pack assessment",  # child progress is captured for aggregate JSON
     "pack gate",        # child progress is captured for aggregate JSON
 })
 
@@ -4332,6 +4331,11 @@ def pack_assessment_cmd(
         help="Deployment artefact for posture evidence (repeatable: k8s, Compose, Dockerfile, WebLogic, dotenv or launch script).",
     ),
     compact: bool = typer.Option(False, "--compact", help="Keep component reports bounded where supported."),
+    only: Optional[str] = typer.Option(
+        None,
+        "--only",
+        help="Comma-separated assessment components to run; audit-report requires risk.",
+    ),
     output_dir: Optional[Path] = typer.Option(
         None,
         "--output-dir",
@@ -4340,13 +4344,14 @@ def pack_assessment_cmd(
     format: str = _format_option(help="Output format: json, yaml or markdown."),
     copy: bool = _copy_option(),
     output_path: Optional[Path] = _output_option(),
+    progress_mode: Optional[str] = _progress_option(),
 ) -> None:
     """Modernization and Risk Assessment pack.
 
     Composes existing commands into one consumable report. Individual commands
     remain available and are the source of truth for every artifact.
     """
-    from sourcecode.packs import render_assessment_markdown, run_assessment
+    from sourcecode.packs import assessment_components, render_assessment_markdown, run_assessment
 
     root = _admit_path(path)
     if profile and deployment:
@@ -4357,10 +4362,16 @@ def pack_assessment_cmd(
         )
         raise typer.Exit(code=2)
     _enforce_format("pack-assessment", format)
+    try:
+        selected_components = assessment_components(only.split(",") if only is not None else None)
+    except ValueError as exc:
+        _emit_error_json(INVALID_INPUT_CODE, str(exc))
+        raise typer.Exit(code=2)
     _progress = Progress().start("pack assessment")
     try:
         data = run_assessment(
             root, profile=profile, deployment=deployment, compact=compact, output_dir=output_dir,
+            selected_components=selected_components,
             progress=lambda done, total, component: _progress.work(
                 done, total, stage=f"pack assessment: {component}",
                 unit="components", estimate=False,
@@ -4390,7 +4401,12 @@ def pack_assessment_cmd(
 @pack_app.command("gate")
 def pack_gate_cmd(
     path: Path = typer.Argument(Path("."), help="Repository path (default: current directory)."),
-    since: str = typer.Option(..., "--since", help="Git ref used as the comparison base."),
+    since: Optional[str] = typer.Option(None, "--since", help="Local Git ref used as the comparison base."),
+    pr: Optional[int] = typer.Option(
+        None,
+        "--pr",
+        help="GitHub pull request number; resolves changed files and requires its base commit locally.",
+    ),
     profile: Optional[str] = typer.Option(None, "--profile", help="Profile set used for posture evidence."),
     compact: bool = typer.Option(False, "--compact", help="Omit component payload bodies from the aggregate."),
     allow_unverified: bool = typer.Option(False, "--allow-unverified", help="Allow an unverified component to exit 0."),
@@ -4416,7 +4432,37 @@ def pack_gate_cmd(
     from sourcecode.packs import run_gate
 
     root = _admit_path(path, exit_code=2)
-    data = run_gate(root, since=since, profile=profile, allow_unverified=allow_unverified, compact=compact, output_dir=output_dir)
+    if since is not None and pr is not None:
+        _emit_error_json(
+            INVALID_INPUT_CODE,
+            "--since and --pr describe mutually exclusive comparison bases.",
+            hint="Use --since REF for a local comparison or --pr NUMBER for GitHub pull-request mode.",
+        )
+        raise typer.Exit(code=2)
+    if since is None and pr is None:
+        _emit_error_json(
+            INVALID_INPUT_CODE,
+            "pack gate requires --since REF or --pr NUMBER.",
+            hint="Use --since origin/main, or --pr 123 when the GitHub base commit is available locally.",
+        )
+        raise typer.Exit(code=2)
+    comparison_ref = since
+    if pr is not None:
+        try:
+            from sourcecode.github_diff import pull_request_base_ref
+
+            comparison_ref, _description = pull_request_base_ref(root, pr)
+        except Exception as exc:
+            from sourcecode.github_diff import GitHubDiffError
+
+            if isinstance(exc, GitHubDiffError):
+                _emit_error_json(INVALID_INPUT_CODE, str(exc), pr=pr)
+                raise typer.Exit(code=2)
+            raise
+    data = run_gate(
+        root, since=comparison_ref or "", pr=pr, profile=profile,
+        allow_unverified=allow_unverified, compact=compact, output_dir=output_dir,
+    )
     if format in {"github-actions", "gitlab"}:
         from sourcecode.ci_output import render_pack_gate_github_actions, render_pack_gate_gitlab
         output = (render_pack_gate_github_actions(data)
@@ -18682,7 +18728,6 @@ def cache_warm_cmd(
     this command reports. Cache ~/.sourcecode/cache and ~/.sourcecode between jobs,
     or budget the cold run explicitly.
     """
-    import shutil as _shutil
     import subprocess as _sub
     import time as _warm_time
     # Warm exactly the path given. Resolving up to the enclosing git root warmed
@@ -18714,7 +18759,11 @@ def cache_warm_cmd(
             f"(scoped to {target}; the enclosing git repository is {_git_root} — "
             "git-derived signals are computed within the scope above)"
         )
-    _sc_bin = _shutil.which("sourcecode") or sys.argv[0]
+    # Launch the worker through this interpreter rather than resolving a second
+    # console script from PATH. A stale global script can otherwise warm one
+    # package installation while the caller reads another one, leaving a view
+    # apparently fresh even though its cache entry was never written.
+    _sc_bin = [sys.executable, "-m", "sourcecode"]
 
     # AUD-600-R01: which views a warm builds is `cache_model`'s fact, not a pair
     # of literals here. The warm used to run one child with `--compact` and an
@@ -18763,7 +18812,7 @@ def cache_warm_cmd(
     # stderr: the line above says it started, the spinner says it is still going.
     _warmed_ids: list[str] = []
     for _view in _selected:
-        cmd = [_sc_bin, str(target), *_warm_view_flags(_view.id)]
+        cmd = [*_sc_bin, str(target), *_warm_view_flags(_view.id)]
         _prog = Progress()
         _prog.start(f"running full analysis ({_view.id} view)")
         try:

{sourcecode-5.8.30 → sourcecode-5.8.31}/src/sourcecode/envelope.py

@@ -81,7 +81,7 @@ def _tree_state(target: Path) -> "tuple[str, str, str]":
         return "", "", ""
     # Git for Windows emits forward slashes while Path resolves to native
     # separators. Restore the platform-native spelling for this path contract.
-    root = str(Path(root))
+    root = portable_path(Path(root))
     prefix = _git(["rev-parse", "--show-prefix"], target)
     head = _git(["rev-parse", "HEAD"], target) or "no-commit"
     dirty = _git(["status", "--porcelain"], target)

sourcecode-5.8.31/src/sourcecode/github_diff.py

@@ -0,0 +1,85 @@
+"""Optional GitHub CLI adapter for obtaining a pull-request file list."""
+from __future__ import annotations
+
+import json
+import subprocess
+from pathlib import Path
+
+
+class GitHubDiffError(RuntimeError):
+    """The optional ``gh`` adapter could not provide a PR diff."""
+
+
+def pull_request_files(root: Path, number: int) -> tuple[list[str], str]:
+    """Read changed paths through local ``gh`` auth, without fetching or writing."""
+    if number < 1:
+        raise GitHubDiffError("pull request number must be a positive integer")
+    command = ["gh", "pr", "diff", str(number), "--name-only"]
+    try:
+        result = subprocess.run(
+            command, cwd=root, capture_output=True, text=True, check=False,
+        )
+    except FileNotFoundError as exc:
+        raise GitHubDiffError(
+            "GitHub PR mode requires the `gh` CLI; install it or use --since/--files"
+        ) from exc
+    except OSError as exc:
+        raise GitHubDiffError(f"could not start `gh`: {exc}") from exc
+    if result.returncode != 0:
+        detail = result.stderr.strip() or "GitHub CLI returned a non-zero status"
+        raise GitHubDiffError(
+            f"could not read pull request #{number}: {detail}. "
+            "Check `gh auth status` and the repository remote."
+        )
+    paths = [line.strip() for line in result.stdout.splitlines() if line.strip()]
+    return paths, f"gh pr diff {number} --name-only"
+
+
+def pull_request_base_ref(root: Path, number: int) -> tuple[str, str]:
+    """Return the exact local comparison commit for a GitHub pull request.
+
+    The gate's posture component compares two repository states, unlike
+    `pr-impact`, which only needs GitHub's changed-file list. Resolve the base
+    SHA through `gh`, then require that the checkout actually has that object;
+    a missing base is an actionable CI checkout problem, not a reason to compare
+    against an arbitrary branch name.
+    """
+    if number < 1:
+        raise GitHubDiffError("pull request number must be a positive integer")
+    command = ["gh", "pr", "view", str(number), "--json", "baseRefName,baseRefOid"]
+    try:
+        result = subprocess.run(
+            command, cwd=root, capture_output=True, text=True, check=False,
+        )
+    except FileNotFoundError as exc:
+        raise GitHubDiffError(
+            "GitHub PR mode requires the `gh` CLI; install it or use --since"
+        ) from exc
+    except OSError as exc:
+        raise GitHubDiffError(f"could not start `gh`: {exc}") from exc
+    if result.returncode != 0:
+        detail = result.stderr.strip() or "GitHub CLI returned a non-zero status"
+        raise GitHubDiffError(
+            f"could not read pull request #{number}: {detail}. "
+            "Check `gh auth status` and the repository remote."
+        )
+    try:
+        payload = json.loads(result.stdout)
+    except json.JSONDecodeError as exc:
+        raise GitHubDiffError("GitHub CLI returned invalid pull-request metadata") from exc
+    base_oid = payload.get("baseRefOid")
+    base_name = payload.get("baseRefName")
+    if not isinstance(base_oid, str) or not base_oid:
+        raise GitHubDiffError("GitHub pull-request metadata did not include baseRefOid")
+    check = subprocess.run(
+        ["git", "cat-file", "-e", f"{base_oid}^{{commit}}"],
+        cwd=root, capture_output=True, text=True, check=False,
+    )
+    if check.returncode != 0:
+        label = base_name if isinstance(base_name, str) and base_name else base_oid
+        raise GitHubDiffError(
+            f"pull request #{number} base {label} ({base_oid}) is not present in this checkout. "
+            "Fetch the base commit first (for GitHub Actions, use actions/checkout with fetch-depth: 0), "
+            "or use --since with an available local ref."
+        )
+    return base_oid, f"gh pr view {number} base {base_name or base_oid} ({base_oid})"

{sourcecode-5.8.30 → sourcecode-5.8.31}/src/sourcecode/license.py

@@ -89,11 +89,20 @@ if _SUPABASE_URL != _DEFAULT_SUPABASE_URL:
 # which case prompts point to the documented Pro plans instead of a placeholder link.
 _PURCHASE_URL: str = os.environ.get("SOURCECODE_PURCHASE_URL", "").strip()
 
+
+def _user_home() -> Path:
+    """Honor HOME overrides used by isolated subprocesses on every host."""
+    configured = os.environ.get("HOME") or os.environ.get("USERPROFILE")
+    if configured:
+        return Path(configured)
+    return Path.home()
+
+
 # Config home: ~/.ask is canonical (product = ASK Engine). The legacy ~/.sourcecode
 # stays READABLE so no existing user loses their license — reads prefer ~/.ask and
 # fall back to ~/.sourcecode; writes always land in ~/.ask. Backward-compatible.
-_LICENSE_DIR: Path = Path.home() / ".ask"
-_LEGACY_LICENSE_DIR: Path = Path.home() / ".sourcecode"
+_LICENSE_DIR: Path = _user_home() / ".ask"
+_LEGACY_LICENSE_DIR: Path = _user_home() / ".sourcecode"
 _LICENSE_FILE: Path = _LICENSE_DIR / "license.json"
 _DELTA_RUNS_FILE: Path = _LICENSE_DIR / "delta_runs.json"
 

{sourcecode-5.8.30 → sourcecode-5.8.31}/src/sourcecode/mcp_nudge.py

@@ -18,11 +18,21 @@ Exit code of the calling command is unaffected.
 """
 from __future__ import annotations
 
+import os
 import sys
 from pathlib import Path
 
+
+def _home_dir() -> Path:
+    """Resolve the configured home even in minimal Windows subprocess envs."""
+    configured = os.environ.get("HOME") or os.environ.get("USERPROFILE")
+    if configured:
+        return Path(configured)
+    return Path.home()
+
+
 # Stable path used as a session-level "already shown" sentinel.
-_FLAG: Path = Path.home() / ".sourcecode" / "nudge_shown"
+_FLAG: Path = _home_dir() / ".sourcecode" / "nudge_shown"
 
 _MSG = (
     "→ Claude Desktop detected. "

{sourcecode-5.8.30 → sourcecode-5.8.31}/src/sourcecode/migrate_check.py

@@ -3008,6 +3008,10 @@ def _scan_file(
     *,
     declared_types: "Optional[frozenset[str]]" = None,
 ) -> list[MigrationFinding]:
+    # Findings are a portable payload contract. Callers may have obtained the
+    # relative path with ``str(Path)`` on Windows, but the same repository file
+    # must retain one identity across hosts and subprocess boundaries.
+    rel_path = rel_path.replace("\\", "/")
     findings: list[MigrationFinding] = []
     type_deprecated = _primary_type_is_deprecated(source)