sourcecode 2.5.19__tar.gz → 2.5.20__tar.gz

{sourcecode-2.5.19 → sourcecode-2.5.20}/CHANGELOG.md

@@ -1,5 +1,33 @@
 # Changelog
 
+## [2.5.20] — 2026-07-21
+
+**Engineering Decision Support — Part A, F3: JAX-RS composed-path canonicalization.**
+Composed `@Path` templates built on a constant whose own value is a concatenation
+(`ROOT_PATH = "/{" + DB_PATH_PARAM_NAME + "}/query/v2"`) produced malformed endpoint
+paths — the class prefix collapsed to `/{`, yielding `/{`, `/{/tx`, `/{/tx/{txId}`.
+Correct endpoint identity is the key of every impact / blast-radius / delta decision,
+so a malformed path corrupts each of them. A pure extraction-correctness fix (no new
+inference). Full suite (3545 passed, 5 skipped) with zero control-repo drift.
+
+### Fixed
+
+- **F3 — `_collect_file_constants` now folds concat / constant-ref constant values.**
+  The collector captured only the FIRST string literal of a `static final String`
+  declaration (`_STATIC_FINAL_STR_RE`), so a constant defined as an expression
+  (`"/{" + DB_PATH_PARAM_NAME + "}/query/v2"`) was stored truncated as `/{`. Every
+  `@Path(SomeResource.ROOT_PATH)` class prefix built on it then collapsed, and each
+  composed method path inherited the collapse. The collector now captures the full
+  right-hand side (`_STATIC_FINAL_STR_DECL_RE`, up to `;`) and resolves it through
+  the existing `_resolve_const_concat`, iterating to a fixpoint so a constant defined
+  in terms of another (in either declaration order) resolves. Inline method-level
+  concat (`@Path("tx/{" + TX_ID_PATH_PARAM_NAME + "}")`) already resolved via
+  `_resolve_ann_path_expr`; this was the one remaining gap. Measured on neo4j
+  (`QueryResource`): 8 malformed paths → canonical (`/{databaseName}/query/v2`,
+  `/{databaseName}/query/v2/tx/{txId}/commit`). Fleet A/B: neo4j corrected, the other
+  7 control repos byte-identical — the fix only ever *completes* a truncated value,
+  never rewrites a literal one.
+
 ## [2.5.19] — 2026-07-20
 
 **Engineering Decision Support — Part A, F2: manual validation (guard clauses) is

{sourcecode-2.5.19 → sourcecode-2.5.20}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sourcecode
-Version: 2.5.19
+Version: 2.5.20
 Summary: Persistent structural context and ultra-fast repeated analysis for AI coding agents
 License-File: LICENSE
 Keywords: agents,ai,codebase,context,developer-tools,llm

{sourcecode-2.5.19 → sourcecode-2.5.20}/pyproject.toml

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

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

sourcecode-2.5.20/src/sourcecode/architectural_delta.py

@@ -0,0 +1,147 @@
+"""architectural_delta.py — D1 Architectural Delta (before/after outcome measurement).
+
+Engineering Decision Support, Part B / D1. ASK measures repository *state*; this
+module measures the *engineering outcome* of a change by diffing two already-built
+canonical IR snapshots and reporting the DELTAS — files, symbols, endpoints,
+dependency edges, HTTP-surface set changes, and per-symbol fan-in shifts.
+
+Discipline (moat line): every number here is MEASURED and derived from the CIR
+alone. This layer computes deltas and stops — it never opines "better/worse",
+never assigns ROI, and never classifies a change as breaking/non-breaking (that is
+D2's contract-diff, a distinct axis). A reviewer reads the deltas and decides.
+
+Determinism: `extract_metrics` reads only the CIR; `diff_metrics` is a pure
+function of two metric snapshots. Same two snapshots → byte-identical delta.
+
+Increment scope (D1-a): counts + HTTP-surface set delta + fan-in shifts. Import
+cycles and blast-radius deltas are deferred to a later increment (heavier compute,
+own metric extractor) — omitted here rather than approximated.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from sourcecode.canonical_ir import CanonicalRepositoryIR
+
+# Frozen schema tag — versioned like perf-baseline-v1 so consumers can pin it.
+ARCH_DELTA_SCHEMA: str = "architectural-delta-v1"
+
+# Cap on the length of any per-item list in the payload (added/removed endpoints,
+# fan-in shifts). The counts are always exact; the lists are a bounded sample.
+_LIST_CAP: int = 50
+
+# reverse_graph edge types that are NOT a dependency. `contained_in` is pure
+# structural membership (a class "contains" its own methods/ctor) — counting it
+# would make every class report a fan-in equal to its own member count (a
+# controller nobody calls would read as fan-in 2). Every other type
+# (calls/injects/extends/implements/imports/returns/instantiates/references) is a
+# genuine reverse dependency and IS counted.
+_FAN_IN_EXCLUDE_EDGE_TYPES: frozenset[str] = frozenset({"contained_in"})
+
+
+def _fan_in_map(cir: "CanonicalRepositoryIR") -> dict[str, int]:
+    """symbol FQN → distinct reverse-dependant count, from the reverse graph.
+
+    reverse_graph is target → {edge_type → [dependant_fqn, ...]}. Fan-in is the
+    number of unique dependants across all DEPENDENCY edge types (a dependant that
+    both calls and injects a target counts once); structural containment is
+    excluded (see `_FAN_IN_EXCLUDE_EDGE_TYPES`)."""
+    out: dict[str, int] = {}
+    for target, by_type in (cir.reverse_graph or {}).items():
+        deps: set[str] = set()
+        for edge_type, dep_list in (by_type or {}).items():
+            if edge_type in _FAN_IN_EXCLUDE_EDGE_TYPES:
+                continue
+            deps.update(dep_list or ())
+        out[target] = len(deps)
+    return out
+
+
+@dataclass(frozen=True)
+class ArchMetrics:
+    """A deterministic architectural snapshot extracted from one CIR."""
+
+    cir_hash: str
+    file_count: int
+    symbol_count: int
+    endpoint_count: int
+    dependency_edge_count: int
+    endpoints: frozenset[tuple[str, str]]   # (METHOD, path) — the HTTP contract surface
+    fan_in: dict[str, int]                   # symbol FQN → distinct caller count
+
+
+def extract_metrics(cir: "CanonicalRepositoryIR") -> ArchMetrics:
+    """Project a CIR into its measured architectural metrics. Reads the CIR only."""
+    endpoints = frozenset(
+        (str(ep.method).upper(), str(ep.path)) for ep in (cir.endpoints or [])
+    )
+    return ArchMetrics(
+        cir_hash=cir.cir_hash,
+        file_count=len(cir.files or []),
+        symbol_count=len(cir.symbols or []),
+        endpoint_count=len(cir.endpoints or []),
+        dependency_edge_count=len(cir.dependencies or []),
+        endpoints=endpoints,
+        fan_in=_fan_in_map(cir),
+    )
+
+
+def _count_block(base: int, head: int) -> dict:
+    return {"base": base, "head": head, "delta": head - base}
+
+
+def diff_metrics(base: ArchMetrics, head: ArchMetrics) -> dict:
+    """Pure diff of two snapshots → the frozen architectural-delta-v1 payload.
+
+    Deterministic: added/removed endpoints are sorted; fan-in shifts are ranked by
+    magnitude then symbol name. Lists are capped; counts are exact."""
+    added = sorted(f"{m} {p}" for (m, p) in (head.endpoints - base.endpoints))
+    removed = sorted(f"{m} {p}" for (m, p) in (base.endpoints - head.endpoints))
+
+    # Fan-in shifts: any symbol whose distinct-caller count changed (present in
+    # either snapshot; absent = 0). Ranked by |delta| desc, then FQN asc.
+    shifts: list[dict] = []
+    for sym in set(base.fan_in) | set(head.fan_in):
+        b = base.fan_in.get(sym, 0)
+        h = head.fan_in.get(sym, 0)
+        if b != h:
+            shifts.append({"symbol": sym, "base": b, "head": h, "delta": h - b})
+    shifts.sort(key=lambda s: (-abs(s["delta"]), s["symbol"]))
+
+    return {
+        "schema": ARCH_DELTA_SCHEMA,
+        "base_cir_hash": base.cir_hash,
+        "head_cir_hash": head.cir_hash,
+        "totals": {
+            "files": _count_block(base.file_count, head.file_count),
+            "symbols": _count_block(base.symbol_count, head.symbol_count),
+            "endpoints": _count_block(base.endpoint_count, head.endpoint_count),
+            "dependency_edges": _count_block(
+                base.dependency_edge_count, head.dependency_edge_count
+            ),
+        },
+        "endpoint_surface": {
+            "added_count": len(added),
+            "removed_count": len(removed),
+            "added": added[:_LIST_CAP],
+            "removed": removed[:_LIST_CAP],
+        },
+        "fan_in_shifts": {
+            "changed_count": len(shifts),
+            "shifts": shifts[:_LIST_CAP],
+        },
+        "provenance": (
+            "architectural_delta (D1): measured deltas derived from the CIR of two "
+            "snapshots. No breaking/non-breaking classification (D2), no verdict, "
+            "no ROI — the reviewer weighs the numbers."
+        ),
+    }
+
+
+def architectural_delta(
+    base_cir: "CanonicalRepositoryIR", head_cir: "CanonicalRepositoryIR"
+) -> dict:
+    """Convenience: extract both snapshots and diff them."""
+    return diff_metrics(extract_metrics(base_cir), extract_metrics(head_cir))

sourcecode-2.5.20/src/sourcecode/change_plan.py

@@ -0,0 +1,195 @@
+"""change_plan.py — D3 Architectural planning artifact (no code generation).
+
+Engineering Decision Support, Part B / D3. Given a change target, emits a
+deterministic, code-free PLAN: what a change to that symbol touches — the affected
+components (reverse-dependency closure), the tests that cover them, the endpoints
+whose contract is in scope, the rollback surface (files involved), and a review
+checklist. All of it is a PROJECTION of the graph + endpoint surface + test-path
+membership.
+
+Moat boundary (roadmap): this lists what to REVIEW; it emits no code, no
+implementation sequence beyond dependency depth, and no recommendation. Every item
+is a deterministic consequence of the model — "these components depend on X", not
+"you should change X this way". The engineer/agent decides and writes.
+
+Determinism: reads the CIR only; a bounded reverse-BFS with a fixed node cap and a
+stable ordering → same repo + same target → same plan.
+
+Reuse: target resolution + the endpoint blast come from `project_blast_radius`
+(the same machinery `impact-chain`/`pr-impact` use, so the plan is consistent with
+them). The affected-component / test / rollback views are derived from an uncapped
+(node-bounded) reverse-dependency closure over the SAME reverse graph, using the
+canonical `_all_callers_from_rg` traversal (skips structural containment + imports,
+normalizes DI-injection owners).
+"""
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from sourcecode.canonical_ir import project_blast_radius
+from sourcecode.repository_ir import _all_callers_from_rg
+from sourcecode.security_posture import _graph_nodes
+from sourcecode.path_filters import is_test_path
+
+if TYPE_CHECKING:
+    from sourcecode.canonical_ir import CanonicalRepositoryIR
+
+CHANGE_PLAN_SCHEMA: str = "change-plan-v1"
+
+_LIST_CAP: int = 100
+# Safety bound on the reverse closure so a hub target cannot blow up the traversal.
+_NODE_CAP: int = 4000
+
+
+def _dependents_closure(
+    reverse_graph: dict, seeds: list[str], max_depth: int, node_cap: int
+) -> dict[str, int]:
+    """Bounded reverse-dependency closure: dependant FQN → shallowest depth.
+
+    BFS over the reverse graph via the canonical `_all_callers_from_rg` traversal
+    (so containment/imports are excluded and DI owners normalized, exactly as
+    blast-radius/impact-chain compute reach). Seeds themselves are removed."""
+    affected: dict[str, int] = {}
+    seen: set[str] = set(seeds)
+    queue: list[tuple[str, int]] = [(s, 0) for s in seeds]
+    while queue and len(affected) < node_cap:
+        fqn, depth = queue.pop(0)
+        if depth >= max_depth:
+            continue
+        for dep in _all_callers_from_rg(fqn, reverse_graph):
+            if dep not in seen:
+                seen.add(dep)
+                affected[dep] = depth + 1
+                queue.append((dep, depth + 1))
+    for s in seeds:
+        affected.pop(s, None)
+    return affected
+
+
+def _node_meta(cir: "CanonicalRepositoryIR") -> dict[str, dict]:
+    """fqn → {file, role, kind} for every graph node."""
+    out: dict[str, dict] = {}
+    for n in _graph_nodes(cir):
+        fqn = n.get("fqn")
+        if fqn:
+            out[str(fqn)] = {
+                "file": str(n.get("source_file") or ""),
+                "role": str(n.get("role") or "other"),
+                "kind": str(n.get("symbol_kind") or n.get("type") or ""),
+            }
+    return out
+
+
+def build_change_plan(
+    cir: "CanonicalRepositoryIR", target: str, *, max_depth: int = 4
+) -> dict:
+    """Build the deterministic change plan for `target` over `cir`."""
+    blast = project_blast_radius(cir, target, max_depth=max_depth)
+    resolution = blast.get("resolution", "not_found")
+
+    # Unresolvable target → return a plan-shaped resolution notice (never crash).
+    if resolution in ("not_found", "ambiguous_path") or not blast.get("matched_fqns"):
+        return {
+            "schema": CHANGE_PLAN_SCHEMA,
+            "target": target,
+            "resolution": resolution,
+            "message": blast.get("message", f"Target {target!r} not found."),
+            "candidates": blast.get("candidates", []),
+            "affected_components": {"count": 0, "components": []},
+            "covering_tests": {"count": 0, "tests": []},
+            "affected_endpoints": {"count": 0, "endpoints": []},
+            "rollback_surface": {"file_count": 0, "files": []},
+            "review_checklist": [],
+        }
+
+    seeds = list(blast["matched_fqns"])
+    meta = _node_meta(cir)
+    affected = _dependents_closure(cir.reverse_graph or {}, seeds, max_depth, _NODE_CAP)
+
+    prod: list[dict] = []
+    tests: list[dict] = []
+    files: set[str] = set()
+    for fqn, depth in affected.items():
+        m = meta.get(fqn, {})
+        f = m.get("file", "")
+        files.add(f)
+        entry = {"symbol": fqn, "role": m.get("role", "other"),
+                 "file": f, "depth": depth}
+        if is_test_path(f):
+            tests.append({"symbol": fqn, "file": f})
+        else:
+            prod.append(entry)
+    # Seed files are part of the rollback surface too (the target is being changed).
+    for s in seeds:
+        files.add(meta.get(s, {}).get("file", ""))
+    files.discard("")
+
+    prod.sort(key=lambda e: (e["depth"], e["symbol"]))
+    tests.sort(key=lambda e: e["symbol"])
+
+    endpoints_affected = blast.get("endpoints_affected", []) or []
+    ep_strings = sorted(
+        f"{e.get('method', '')} {e.get('path', '')}".strip()
+        for e in endpoints_affected if isinstance(e, dict)
+    )
+
+    rollback_files = sorted(files)
+
+    # Review checklist — structural facts phrased as review items, never advice.
+    checklist: list[str] = []
+    checklist.append(
+        f"Review {len(prod)} affected production component(s) reachable from the change."
+    )
+    if ep_strings:
+        checklist.append(
+            f"Re-verify the contract of {len(ep_strings)} endpoint(s) in the blast radius."
+        )
+    if tests:
+        checklist.append(
+            f"Run {len(tests)} covering test symbol(s) that reach the change."
+        )
+    else:
+        checklist.append(
+            "No covering tests reach the change — no existing test exercises this blast radius."
+        )
+    checklist.append(f"Rollback touches {len(rollback_files)} file(s).")
+    modules = blast.get("cross_module_impact") or []
+    if modules:
+        checklist.append(f"Change spans {len(modules)} module/subsystem(s).")
+    sec = blast.get("security_surface_affected") or []
+    if sec:
+        checklist.append(
+            f"{len(sec)} secured endpoint(s) in scope — re-check authorization."
+        )
+    txn = blast.get("transactional_boundaries_touched") or []
+    if txn:
+        checklist.append(f"{len(txn)} transactional boundary/boundaries in scope.")
+
+    return {
+        "schema": CHANGE_PLAN_SCHEMA,
+        "target": target,
+        "resolution": resolution,
+        "matched_symbols": sorted(seeds),
+        "affected_components": {
+            "count": len(prod),
+            "components": prod[:_LIST_CAP],
+        },
+        "covering_tests": {
+            "count": len(tests),
+            "tests": tests[:_LIST_CAP],
+        },
+        "affected_endpoints": {
+            "count": len(ep_strings),
+            "endpoints": ep_strings[:_LIST_CAP],
+        },
+        "rollback_surface": {
+            "file_count": len(rollback_files),
+            "files": rollback_files[:_LIST_CAP],
+        },
+        "review_checklist": checklist,
+        "provenance": (
+            "change_plan (D3): deterministic projection of the reverse-dependency "
+            "graph + endpoint surface + test-path membership. Lists what to review; "
+            "emits no code, no sequence beyond dependency depth, no recommendation."
+        ),
+    }

{sourcecode-2.5.19 → sourcecode-2.5.20}/src/sourcecode/cli.py

@@ -235,6 +235,10 @@ _SUBCOMMANDS: frozenset[str] = frozenset(
         "spring-audit",
         # Request-body validation surface
         "validation",
+        # D1 architectural delta (before/after outcome measurement)
+        "delta",
+        # D2 contract-break detection
+        "contract-diff",
         # Spring impact chain
         "impact-chain",
         # PR blast-radius report
@@ -4620,6 +4624,263 @@ def validation_cmd(
     _nudge()
 
 
+# ── D1 Architectural Delta ────────────────────────────────────────────────────
+
+
+@app.command("delta")
+def delta_cmd(
+    base: Path = typer.Argument(
+        ...,
+        help="Repository checkout of the BEFORE state (base).",
+    ),
+    head: Path = typer.Argument(
+        ...,
+        help="Repository checkout of the AFTER state (head).",
+    ),
+    output_path: Optional[Path] = typer.Option(
+        None, "--output", "-o",
+        help="Write output to a file instead of stdout.",
+    ),
+    format: str = typer.Option(
+        "json", "--format", "-f",
+        help="Output format: json (default) or yaml.",
+        show_default=True,
+    ),
+    copy: bool = typer.Option(
+        False, "--copy", "-c",
+        help="Copy output to system clipboard after a successful run.",
+    ),
+) -> None:
+    """Measure the architectural OUTCOME of a change: diff two checkouts.
+
+    \b
+    Builds the canonical IR for each checkout and reports the measured DELTAS —
+    files, symbols, endpoints, dependency edges, the HTTP-surface set change
+    (added/removed routes), and per-symbol fan-in shifts (e.g. "fan-in on
+    QueryController 14→3").
+
+    \b
+    This layer measures and stops. It emits no verdict, no ROI, and no
+    breaking/non-breaking classification (that is a separate contract-diff) — a
+    reviewer weighs the numbers. Deterministic: same two checkouts → same delta.
+
+    \b
+    Examples:
+      ask delta ./before ./after
+      ask delta /tmp/base-worktree /tmp/head-worktree -o delta.json
+    """
+    _enforce_format("delta", format)
+
+    for label, target in (("base", base), ("head", head)):
+        if not target.exists() or not target.is_dir():
+            _emit_error_json(
+                INVALID_INPUT_CODE,
+                f"'{target}' ({label}) is not a valid directory.",
+                path=str(target),
+                hint="Pass two existing repository checkouts: ask delta <base> <head>.",
+                expected="A directory path for each of base and head.",
+            )
+            raise typer.Exit(code=1)
+
+    from sourcecode.context_graph import ContextGraph
+    from sourcecode.architectural_delta import architectural_delta
+
+    _prog = Progress()
+    _prog.start("building base IR")
+    _base_cir = ContextGraph.build_from_root(base.resolve()).cir
+    _prog.update("building head IR")
+    _head_cir = ContextGraph.build_from_root(head.resolve()).cir
+    _prog.update("diffing snapshots")
+    data = architectural_delta(_base_cir, _head_cir)
+    _prog.finish()
+
+    _t = data["totals"]
+    output = _serialize_dict(data, format)
+    _emit_command_output(
+        output, output_path, copy,
+        success_msg=(
+            f"Architectural delta written to {output_path} "
+            f"(Δfiles {_t['files']['delta']:+d}, Δsymbols {_t['symbols']['delta']:+d}, "
+            f"Δendpoints {_t['endpoints']['delta']:+d}, "
+            f"{data['fan_in_shifts']['changed_count']} fan-in shifts)"
+        ),
+    )
+
+
+# ── D2 Contract-Break Detection ───────────────────────────────────────────────
+
+
+@app.command("contract-diff")
+def contract_diff_cmd(
+    base: Path = typer.Argument(
+        ...,
+        help="Repository checkout of the BEFORE state (base).",
+    ),
+    head: Path = typer.Argument(
+        ...,
+        help="Repository checkout of the AFTER state (head).",
+    ),
+    output_path: Optional[Path] = typer.Option(
+        None, "--output", "-o",
+        help="Write output to a file instead of stdout.",
+    ),
+    format: str = typer.Option(
+        "json", "--format", "-f",
+        help="Output format: json (default) or yaml.",
+        show_default=True,
+    ),
+    copy: bool = typer.Option(
+        False, "--copy", "-c",
+        help="Copy output to system clipboard after a successful run.",
+    ),
+) -> None:
+    """Did this change break the public contract? Diff two checkouts.
+
+    \b
+    Projects the public contract (HTTP endpoints + public method signatures) for
+    each checkout and classifies every structural delta:
+      * breaking    — a removed endpoint/method, or a changed signature
+      * additive    — a new endpoint/method (backward compatible)
+      * non_breaking — reserved for constraint-loosening analysis (not yet emitted)
+
+    \b
+    Structural only: a changed signature is flagged breaking because the shape
+    differs — behavioural equivalence is NOT claimed. No ROI, no quality verdict.
+    Deterministic: same two checkouts → same result.
+
+    \b
+    Examples:
+      ask contract-diff ./before ./after
+      ask contract-diff /tmp/base-worktree /tmp/head-worktree -o contract.json
+    """
+    _enforce_format("contract-diff", format)
+
+    for label, target in (("base", base), ("head", head)):
+        if not target.exists() or not target.is_dir():
+            _emit_error_json(
+                INVALID_INPUT_CODE,
+                f"'{target}' ({label}) is not a valid directory.",
+                path=str(target),
+                hint="Pass two existing repository checkouts: ask contract-diff <base> <head>.",
+                expected="A directory path for each of base and head.",
+            )
+            raise typer.Exit(code=1)
+
+    from sourcecode.context_graph import ContextGraph
+    from sourcecode.contract_diff import contract_diff as _contract_diff
+
+    _prog = Progress()
+    _prog.start("building base IR")
+    _base_cir = ContextGraph.build_from_root(base.resolve()).cir
+    _prog.update("building head IR")
+    _head_cir = ContextGraph.build_from_root(head.resolve()).cir
+    _prog.update("diffing contracts")
+    data = _contract_diff(_base_cir, _head_cir)
+    _prog.finish()
+
+    _s = data["summary"]
+    output = _serialize_dict(data, format)
+    _emit_command_output(
+        output, output_path, copy,
+        success_msg=(
+            f"Contract diff written to {output_path} "
+            f"(status: {data['contract_status']}; "
+            f"{_s['breaking']} breaking, {_s['additive']} additive)"
+        ),
+    )
+
+
+# ── D3 Change Plan ────────────────────────────────────────────────────────────
+
+
+@app.command("plan")
+def plan_cmd(
+    target: str = typer.Argument(
+        ...,
+        help="Change target: class name (simple or FQN) or file path. "
+             "Examples: UserService, org.example.UserService, UserService.java",
+    ),
+    path: Path = typer.Argument(
+        Path("."),
+        help="Repository root to analyze (default: current directory).",
+    ),
+    depth: int = typer.Option(
+        4, "--depth",
+        help="Reverse-dependency BFS depth (default: 4).",
+        min=1, max=8,
+    ),
+    output_path: Optional[Path] = typer.Option(
+        None, "--output", "-o",
+        help="Write output to a file instead of stdout.",
+    ),
+    format: str = typer.Option(
+        "json", "--format", "-f",
+        help="Output format: json (default) or yaml.",
+        show_default=True,
+    ),
+    copy: bool = typer.Option(
+        False, "--copy", "-c",
+        help="Copy output to system clipboard after a successful run.",
+    ),
+) -> None:
+    """Plan a change: what to review to implement a change to a target (no code).
+
+    \b
+    Projects a deterministic, code-free plan from the dependency graph:
+      * affected components — the reverse-dependency closure of the target
+      * covering tests      — existing tests that reach the change
+      * affected endpoints  — routes whose contract is in the blast radius
+      * rollback surface    — the files a change/rollback touches
+      * review checklist     — structural review items (facts, not advice)
+
+    \b
+    Emits no code and no implementation sequence beyond dependency depth. Every
+    item is a deterministic consequence of the model. Deterministic: same repo +
+    target → same plan.
+
+    \b
+    Examples:
+      ask plan UserService .
+      ask plan org.example.OrderService ./repo --depth 3
+    """
+    _enforce_format("plan", format)
+
+    target_dir = path.resolve()
+    if not target_dir.exists() or not target_dir.is_dir():
+        _emit_error_json(
+            INVALID_INPUT_CODE,
+            f"'{target_dir}' is not a valid directory.",
+            path=str(target_dir),
+            hint="Pass an existing repository directory: ask plan <target> <path>.",
+            expected="A directory path.",
+        )
+        raise typer.Exit(code=1)
+
+    from sourcecode.context_graph import ContextGraph
+    from sourcecode.change_plan import build_change_plan
+
+    _prog = Progress()
+    _prog.start("building IR")
+    _cir = ContextGraph.build_from_root(target_dir).cir
+    _prog.update("planning change")
+    data = build_change_plan(_cir, target, max_depth=depth)
+    _prog.finish()
+
+    if data.get("resolution") in ("not_found", "ambiguous_path"):
+        typer.echo(f"Note: {data.get('message', 'target not resolved')}", err=True)
+
+    output = _serialize_dict(data, format)
+    _emit_command_output(
+        output, output_path, copy,
+        success_msg=(
+            f"Change plan written to {output_path} "
+            f"({data['affected_components']['count']} components, "
+            f"{data['covering_tests']['count']} covering tests, "
+            f"{data['affected_endpoints']['count']} endpoints)"
+        ),
+    )
+
+
 # ── Spring Semantic Audit ─────────────────────────────────────────────────────