agentpack-cli 0.1.24__tar.gz → 0.1.26__tar.gz

agentpack_cli-0.1.26/.gitignore

@@ -0,0 +1,33 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+
+.venv/
+venv/
+env/
+
+# agentpack:start
+# AgentPack generated context/cache (safe to ignore)
+.agentpack/cache/
+.agentpack/snapshots/
+.agentpack/context*
+.agentpack/metrics.jsonl
+.agentpack/pack_metadata.json
+.agentpack/activity.log
+.agentpack/.gitignore
+.agentpack/.mcp_reminded
+.agentpack/session.json
+.agentpack/task.md
+.agentpack/benchmark_results.jsonl
+.agent/skills/agentpack/
+# agentpack:end
+
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+*.dist-info/

{agentpack_cli-0.1.24 → agentpack_cli-0.1.26}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentpack-cli
-Version: 0.1.24
+Version: 0.1.26
 Summary: Task-aware context packing for AI coding agents — Claude, Cursor, Windsurf, Codex, and Antigravity
 License: MIT
 License-File: LICENSE
@@ -44,7 +44,7 @@ Description-Content-Type: text/markdown
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![CI](https://github.com/vishal2612200/agentpack/actions/workflows/ci.yml/badge.svg)](https://github.com/vishal2612200/agentpack/actions/workflows/ci.yml)
 
-> **Status: alpha (v0.1.24).** Works, tested, used in real sessions. Python and JavaScript/TypeScript are the best-supported languages. Not yet validated across a wide range of repos. API may change before 1.0.
+> **Status: alpha (v0.1.25).** Works, tested, used in real sessions. Python and JavaScript/TypeScript are the best-supported languages. Not yet validated across a wide range of repos. API may change before 1.0.
 >
 > **Platform note:** macOS and Linux are fully supported. Windows support is not yet implemented (git hooks use POSIX shell; the Claude Code session hooks use `python3`/`rm -f`). Contributions welcome.
 
@@ -377,7 +377,7 @@ Configures:
 - `CLAUDE.md` — tells Claude to read the context pack before each task
 - `.claude/settings.json` — two hooks:
   - `SessionStart`: clears injection sentinel so first prompt gets context
-  - `UserPromptSubmit`: runs `agentpack hook` — detects repo changes via `root_hash`, triggers background repack using your prompt as task. With MCP: emits Option-B hint (~100 tokens, task + top files). Without MCP: emits capped fallback (top 8 files, ≤3k chars)
+  - `UserPromptSubmit`: runs `agentpack hook` — detects repo changes via `root_hash`, detects clear task switches, updates `.agentpack/task.md`, and triggers background repack using your prompt as task. With MCP: emits Option-B hint (~100 tokens, task + top files). Without MCP: emits capped fallback (top 8 files, ≤3k chars)
 
 After this, context is injected automatically into every Claude Code session. No `/agentpack` command needed — it just happens.
 
@@ -388,7 +388,7 @@ agentpack install --agent cursor
 ```
 
 Configures:
-- `.cursorrules` — rule: read `.agentpack/context.md` before every conversation
+- `.cursorrules` — rule: write current task, run `agentpack pack --task auto`, then read `.agentpack/context.md`
 - `.cursor/rules/agentpack.mdc` — `alwaysApply: true` rule (Cursor v0.43+)
 - `.git/hooks/post-commit`, `post-merge`, `post-checkout` — background repack on tree change
 - `.vscode/tasks.json` — "AgentPack: Repack context" in Command Palette + `runOn: folderOpen`
@@ -400,7 +400,7 @@ agentpack install --agent windsurf
 ```
 
 Configures:
-- `.windsurfrules` — rule: read `.agentpack/context.md` before every conversation
+- `.windsurfrules` — rule: write current task, run `agentpack pack --task auto`, then read `.agentpack/context.md`
 - `.git/hooks/post-commit`, `post-merge`, `post-checkout` — background repack on tree change
 - `.vscode/tasks.json` — "AgentPack: Repack context" in Command Palette + `runOn: folderOpen`
 
@@ -411,7 +411,7 @@ agentpack install --agent codex
 ```
 
 Configures:
-- `AGENTS.md` — tells Codex to read the context pack before each task
+- `AGENTS.md` — tells Codex to write current task, repack, and read the context pack before each task
 - `.git/hooks/post-commit`, `post-merge`, `post-checkout` — background repack on tree change
 
 ### Antigravity
@@ -422,7 +422,7 @@ agentpack install --agent antigravity
 
 Configures:
 - `.agent/skills/agentpack/SKILL.md` — AgentPack context as a Skill; Antigravity activates it automatically for coding tasks
-- `GEMINI.md` — registers the agentpack skill reference
+- `GEMINI.md` — registers the agentpack skill reference and task-switch protocol
 - `.git/hooks/post-commit`, `post-merge`, `post-checkout` — background repack on tree change
 - `.vscode/tasks.json` — "AgentPack: Repack context" in Command Palette + `runOn: folderOpen`
 
@@ -642,6 +642,7 @@ agentpack init --share-cache    # commit cache/ to git for team sharing
 
 Creates:
 ```
+.gitignore                # patched idempotently with AgentPack generated artifacts
 .agentignore              # gitignore-style file exclusion rules
 .agentpack/
   config.toml             # configuration (safe to commit)
@@ -1062,6 +1063,10 @@ include_tests = true
 include_configs = true
 include_receipts = true
 
+[hooks]
+task_switch_detection = true
+task_switch_min_terms = 1
+
 [agents.claude]
 output = ".agentpack/context.claude.md"
 patch_claude_md = true
@@ -1114,8 +1119,11 @@ Works like `.gitignore`. Default rules exclude:
 .agentignore              ✓ commit
 .agentpack/config.toml    ✓ commit
 .agentpack/cache/         ✓ commit if --share-cache (recommended for teams)
+.agentpack/.gitignore     ✗ gitignored
 .agentpack/snapshots/     ✗ gitignored
 .agentpack/context.*      ✗ gitignored
+.agentpack/task.md        ✗ gitignored (local current task)
+.agent/skills/agentpack/  ✗ gitignored (generated Antigravity context)
 ```
 
 ---

{agentpack_cli-0.1.24 → agentpack_cli-0.1.26}/README.md

@@ -5,7 +5,7 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![CI](https://github.com/vishal2612200/agentpack/actions/workflows/ci.yml/badge.svg)](https://github.com/vishal2612200/agentpack/actions/workflows/ci.yml)
 
-> **Status: alpha (v0.1.24).** Works, tested, used in real sessions. Python and JavaScript/TypeScript are the best-supported languages. Not yet validated across a wide range of repos. API may change before 1.0.
+> **Status: alpha (v0.1.25).** Works, tested, used in real sessions. Python and JavaScript/TypeScript are the best-supported languages. Not yet validated across a wide range of repos. API may change before 1.0.
 >
 > **Platform note:** macOS and Linux are fully supported. Windows support is not yet implemented (git hooks use POSIX shell; the Claude Code session hooks use `python3`/`rm -f`). Contributions welcome.
 
@@ -338,7 +338,7 @@ Configures:
 - `CLAUDE.md` — tells Claude to read the context pack before each task
 - `.claude/settings.json` — two hooks:
   - `SessionStart`: clears injection sentinel so first prompt gets context
-  - `UserPromptSubmit`: runs `agentpack hook` — detects repo changes via `root_hash`, triggers background repack using your prompt as task. With MCP: emits Option-B hint (~100 tokens, task + top files). Without MCP: emits capped fallback (top 8 files, ≤3k chars)
+  - `UserPromptSubmit`: runs `agentpack hook` — detects repo changes via `root_hash`, detects clear task switches, updates `.agentpack/task.md`, and triggers background repack using your prompt as task. With MCP: emits Option-B hint (~100 tokens, task + top files). Without MCP: emits capped fallback (top 8 files, ≤3k chars)
 
 After this, context is injected automatically into every Claude Code session. No `/agentpack` command needed — it just happens.
 
@@ -349,7 +349,7 @@ agentpack install --agent cursor
 ```
 
 Configures:
-- `.cursorrules` — rule: read `.agentpack/context.md` before every conversation
+- `.cursorrules` — rule: write current task, run `agentpack pack --task auto`, then read `.agentpack/context.md`
 - `.cursor/rules/agentpack.mdc` — `alwaysApply: true` rule (Cursor v0.43+)
 - `.git/hooks/post-commit`, `post-merge`, `post-checkout` — background repack on tree change
 - `.vscode/tasks.json` — "AgentPack: Repack context" in Command Palette + `runOn: folderOpen`
@@ -361,7 +361,7 @@ agentpack install --agent windsurf
 ```
 
 Configures:
-- `.windsurfrules` — rule: read `.agentpack/context.md` before every conversation
+- `.windsurfrules` — rule: write current task, run `agentpack pack --task auto`, then read `.agentpack/context.md`
 - `.git/hooks/post-commit`, `post-merge`, `post-checkout` — background repack on tree change
 - `.vscode/tasks.json` — "AgentPack: Repack context" in Command Palette + `runOn: folderOpen`
 
@@ -372,7 +372,7 @@ agentpack install --agent codex
 ```
 
 Configures:
-- `AGENTS.md` — tells Codex to read the context pack before each task
+- `AGENTS.md` — tells Codex to write current task, repack, and read the context pack before each task
 - `.git/hooks/post-commit`, `post-merge`, `post-checkout` — background repack on tree change
 
 ### Antigravity
@@ -383,7 +383,7 @@ agentpack install --agent antigravity
 
 Configures:
 - `.agent/skills/agentpack/SKILL.md` — AgentPack context as a Skill; Antigravity activates it automatically for coding tasks
-- `GEMINI.md` — registers the agentpack skill reference
+- `GEMINI.md` — registers the agentpack skill reference and task-switch protocol
 - `.git/hooks/post-commit`, `post-merge`, `post-checkout` — background repack on tree change
 - `.vscode/tasks.json` — "AgentPack: Repack context" in Command Palette + `runOn: folderOpen`
 
@@ -603,6 +603,7 @@ agentpack init --share-cache    # commit cache/ to git for team sharing
 
 Creates:
 ```
+.gitignore                # patched idempotently with AgentPack generated artifacts
 .agentignore              # gitignore-style file exclusion rules
 .agentpack/
   config.toml             # configuration (safe to commit)
@@ -1023,6 +1024,10 @@ include_tests = true
 include_configs = true
 include_receipts = true
 
+[hooks]
+task_switch_detection = true
+task_switch_min_terms = 1
+
 [agents.claude]
 output = ".agentpack/context.claude.md"
 patch_claude_md = true
@@ -1075,8 +1080,11 @@ Works like `.gitignore`. Default rules exclude:
 .agentignore              ✓ commit
 .agentpack/config.toml    ✓ commit
 .agentpack/cache/         ✓ commit if --share-cache (recommended for teams)
+.agentpack/.gitignore     ✗ gitignored
 .agentpack/snapshots/     ✗ gitignored
 .agentpack/context.*      ✗ gitignored
+.agentpack/task.md        ✗ gitignored (local current task)
+.agent/skills/agentpack/  ✗ gitignored (generated Antigravity context)
 ```
 
 ---

{agentpack_cli-0.1.24 → agentpack_cli-0.1.26}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "agentpack-cli"
-version = "0.1.24"
+version = "0.1.26"
 description = "Task-aware context packing for AI coding agents — Claude, Cursor, Windsurf, Codex, and Antigravity"
 readme = "README.md"
 requires-python = ">=3.10"

{agentpack_cli-0.1.24 → agentpack_cli-0.1.26}/src/agentpack/__init__.py

@@ -1,3 +1,3 @@
 """AgentPack — task-aware context packing for AI coding agents."""
 
-__version__ = "0.1.24"
+__version__ = "0.1.26"

{agentpack_cli-0.1.24 → agentpack_cli-0.1.26}/src/agentpack/application/pack_service.py

@@ -16,6 +16,7 @@ from agentpack.core import git
 from agentpack.core.context_pack import select_files, save_pack_metadata
 from agentpack.core.models import ContextPack, DependencyGraph, FileInfo, ScanResult, SelectedFile, Receipt
 from agentpack.core.token_estimator import estimate_tokens
+from agentpack.renderers.markdown import render_generic
 from agentpack.analysis.ranking import (
     score_files,
     extract_keyword_weights,
@@ -193,6 +194,7 @@ class PackPlanner:
             previous_snapshot=previous_snap,
             include_globs=cfg.project.include_globs or None,
             exclude_globs=cfg.project.exclude_globs or None,
+            always_skip_paths=AdapterRegistry.generated_output_paths(root, cfg),
         )
         phase_times["scan"] = time.perf_counter() - t0
 
@@ -255,7 +257,7 @@ class AdapterRegistry:
     """Maps agent names to adapter instances; extensible without touching PackService."""
 
     @staticmethod
-    def get(agent: str, cfg: Any) -> Any:
+    def _factories(cfg: Any) -> dict[str, Any]:
         from agentpack.adapters.antigravity import AntigravityAdapter
         from agentpack.adapters.claude import ClaudeAdapter
         from agentpack.adapters.codex import CodexAdapter
@@ -263,15 +265,33 @@ class AdapterRegistry:
         from agentpack.adapters.windsurf import WindsurfAdapter
         from agentpack.adapters.generic import GenericAdapter
 
-        adapters = {
+        return {
             "antigravity": lambda: AntigravityAdapter(),
             "claude": lambda: ClaudeAdapter(cfg.agents.claude.output),
             "cursor": lambda: CursorAdapter(cfg.agents.generic.output),
             "windsurf": lambda: WindsurfAdapter(cfg.agents.generic.output),
             "codex": lambda: CodexAdapter(cfg.agents.generic.output),
+            "generic": lambda: GenericAdapter(cfg.agents.generic.output),
         }
+
+    @staticmethod
+    def get(agent: str, cfg: Any) -> Any:
+        from agentpack.adapters.generic import GenericAdapter
+
+        adapters = AdapterRegistry._factories(cfg)
         return adapters.get(agent, lambda: GenericAdapter(cfg.agents.generic.output))()
 
+    @staticmethod
+    def generated_output_paths(root: Path, cfg: Any) -> set[str]:
+        paths: set[str] = set()
+        for factory in AdapterRegistry._factories(cfg).values():
+            try:
+                out_path = factory().output_path(root)
+                paths.add(str(out_path.relative_to(root)).replace("\\", "/"))
+            except (OSError, ValueError):
+                continue
+        return paths
+
 
 class PackService:
     """Materializes a plan from PackPlanner into a written context file."""
@@ -319,6 +339,7 @@ class PackService:
 
         t0 = time.perf_counter()
         out_path = adapter.write(pack_obj, root)
+        _write_canonical_context(pack_obj, root, out_path)
         plan.phase_times["render"] = time.perf_counter() - t0
 
         save_snapshot(plan.current_snap, root)
@@ -333,6 +354,7 @@ class PackService:
             token_estimate=packed_tokens,
             freshness=freshness,
             freshness_warnings=freshness_warnings,
+            selected_files=_selected_file_metadata(plan.selected),
         )
         excluded_receipts = [r for r in plan.receipts if r.action == "excluded"]
         # Budget-cut: files that scored OK but didn't fit — more useful signal than "score too low"
@@ -368,6 +390,33 @@ class PackService:
         )
 
 
+def _write_canonical_context(pack: ContextPack, root: Path, out_path: Path) -> None:
+    """Keep .agentpack/context.md fresh even when the target agent writes elsewhere."""
+    canonical_path = root / ".agentpack" / "context.md"
+    try:
+        if out_path.resolve() == canonical_path.resolve():
+            return
+    except OSError:
+        if out_path == canonical_path:
+            return
+    canonical_path.parent.mkdir(parents=True, exist_ok=True)
+    canonical_path.write_text(render_generic(pack), encoding="utf-8")
+
+
+def _selected_file_metadata(selected: list[SelectedFile]) -> list[dict[str, Any]]:
+    return [
+        {
+            "path": sf.path,
+            "mode": sf.include_mode,
+            "score": round(sf.score, 1),
+            "why": sf.reasons[0] if sf.reasons else "",
+            "reasons": sf.reasons,
+            "tokens": _sf_tokens(sf),
+        }
+        for sf in selected
+    ]
+
+
 def _sf_tokens(sf: SelectedFile) -> int:
     if sf.content:
         return estimate_tokens(sf.content)

{agentpack_cli-0.1.24 → agentpack_cli-0.1.26}/src/agentpack/commands/claude_cmd.py

@@ -30,6 +30,7 @@ def register(app: typer.Typer) -> None:
             state.last_refresh_at = _now_iso()
             state.refresh_count += 1
             state.last_task_hash = _file_hash(root / TASK_FILE)
+            state.last_resolved_agent = state.agent
             save_session(root, state)
             log_activity(root, f"claude cmd — {result['files']} files, {result['tokens']:,} tokens")
         else:

{agentpack_cli-0.1.24 → agentpack_cli-0.1.26}/src/agentpack/commands/diff.py

@@ -8,6 +8,7 @@ from agentpack.core.ignore import load_spec
 from agentpack.core.scanner import scan
 from agentpack.core.snapshot import build_snapshot, load_snapshot
 from agentpack.core.diff import diff_snapshots
+from agentpack.application.pack_service import AdapterRegistry
 from agentpack.commands._shared import console, _root
 
 
@@ -19,7 +20,12 @@ def register(app: typer.Typer) -> None:
         cfg = load_config(root)
         ignore_spec = load_spec(root / cfg.project.ignore_file)
 
-        scan_result = scan(root, ignore_spec, cfg.context.max_file_tokens)
+        scan_result = scan(
+            root,
+            ignore_spec,
+            cfg.context.max_file_tokens,
+            always_skip_paths=AdapterRegistry.generated_output_paths(root, cfg),
+        )
         current = build_snapshot(scan_result.packable)
         previous = load_snapshot(root)
         result = diff_snapshots(previous, current)

{agentpack_cli-0.1.24 → agentpack_cli-0.1.26}/src/agentpack/commands/doctor.py

@@ -16,6 +16,7 @@ from agentpack.integrations.global_install import (
     _detect_rc_file,
 )
 from agentpack.commands._shared import console, _root
+from agentpack.core.context_pack import load_pack_metadata
 
 
 def register(app: typer.Typer) -> None:
@@ -104,11 +105,11 @@ def register(app: typer.Typer) -> None:
             return
 
         config_path = root / ".agentpack" / "config.toml"
-        context_path = root / ".agentpack" / "context.claude.md"
         if not config_path.exists():
             console.print(f"  [yellow]![/] Not initialized in {root} — run: agentpack init")
         else:
             console.print("  [green]✓[/] .agentpack/config.toml present")
+            context_path = _latest_context_path(root)
             if context_path.exists():
                 import time
                 age = time.time() - context_path.stat().st_mtime
@@ -216,6 +217,16 @@ def register(app: typer.Typer) -> None:
         if not _local_has_mcp and not _global_has_mcp:
             console.print("  [yellow]![/] MCP server not registered — mcp__agentpack__* tools unavailable")
 
+        # --- Release hygiene ---
+        console.print("\n[bold]Release hygiene[/]")
+        findings = _release_hygiene_findings(root)
+        if findings:
+            for finding in findings:
+                console.print(f"  [yellow]![/] {finding}")
+            ok = False
+        else:
+            console.print("  [green]✓[/] no generated release-noise files staged or untracked")
+
         # --- Slash command ---
         console.print("\n[bold]Slash command (/agentpack)[/]")
         local_cmd = root / ".claude" / "commands" / "agentpack.md"
@@ -244,6 +255,23 @@ def _check_agent_file(root: Path, filename: str, agent: str) -> None:
         console.print(f"  [dim]-[/] {filename} not present (optional)")
 
 
+def _latest_context_path(root: Path) -> Path:
+    meta = load_pack_metadata(root)
+    if meta and meta.get("context_path"):
+        candidate = root / str(meta["context_path"])
+        if candidate.exists():
+            return candidate
+    for rel in (
+        ".agentpack/context.md",
+        ".agentpack/context.claude.md",
+        ".agent/skills/agentpack/SKILL.md",
+    ):
+        candidate = root / rel
+        if candidate.exists():
+            return candidate
+    return root / ".agentpack" / "context.md"
+
+
 def _source_checkout_warning(
     root: Path,
     package_file: Path,
@@ -268,6 +296,51 @@ def _source_checkout_warning(
     )
 
 
+_RELEASE_NOISE_PREFIXES = (
+    ".agent/",
+    ".agentpack/",
+    ".claude/worktrees/",
+    ".codex/",
+    ".cursor/",
+    ".vscode/",
+)
+_RELEASE_NOISE_FILES = {".coverage"}
+
+
+def _release_hygiene_findings(root: Path) -> list[str]:
+    """Flag local generated artifacts that should not be staged or released."""
+    try:
+        result = subprocess.run(
+            ["git", "status", "--short"],
+            cwd=root,
+            capture_output=True,
+            text=True,
+            timeout=5,
+        )
+    except (OSError, subprocess.TimeoutExpired):
+        return ["could not inspect git status for release hygiene"]
+    if result.returncode != 0:
+        return []
+
+    noisy: list[str] = []
+    for raw in result.stdout.splitlines():
+        if not raw.strip():
+            continue
+        status = raw[:2].strip() or "modified"
+        path = raw[3:].strip()
+        if " -> " in path:
+            path = path.rsplit(" -> ", 1)[1]
+        norm = path.replace("\\", "/")
+        if norm in _RELEASE_NOISE_FILES or any(norm.startswith(prefix) for prefix in _RELEASE_NOISE_PREFIXES):
+            noisy.append(f"{status} {norm}")
+
+    if not noisy:
+        return []
+    sample = ", ".join(noisy[:8])
+    extra = f", ... {len(noisy) - 8} more" if len(noisy) > 8 else ""
+    return [f"generated/local artifacts present: {sample}{extra}"]
+
+
 def _print_summary(ok: bool) -> None:
     console.print("")
     if ok:

{agentpack_cli-0.1.24 → agentpack_cli-0.1.26}/src/agentpack/commands/explain.py

@@ -10,6 +10,7 @@ from agentpack.core.context_pack import select_files
 from agentpack.commands._shared import console, _root
 from agentpack.commands.pack import _resolve_task
 from agentpack.core.config import load_config, ScoringWeights
+from agentpack.analysis.ranking import extract_keyword_weights, generic_task_term_ratio, _GENERIC_TASK_TERMS
 
 
 def _resolve_signal_weight(reason: str, weights: ScoringWeights) -> float:
@@ -111,6 +112,50 @@ def _print_file_detail(
     console.print()
 
 
+def _noise_report(task: str, plan: object) -> list[str]:
+    keyword_weights = extract_keyword_weights(task)
+    generic_terms = sorted(term for term in keyword_weights if term in _GENERIC_TASK_TERMS)
+    specific_terms = sorted(term for term in keyword_weights if term not in _GENERIC_TASK_TERMS)
+    selected = list(plan.selected)  # type: ignore[attr-defined]
+    summary_count = sum(1 for sf in selected if sf.include_mode == "summary")
+    filename_count = sum(1 for sf in selected if "filename keyword match" in sf.reasons)
+    symbol_count = sum(1 for sf in selected if "symbol keyword match" in sf.reasons)
+    excluded = [r for r in plan.receipts if r.action == "excluded"]  # type: ignore[attr-defined]
+    summary_cap = sum(1 for r in excluded if r.reason == "summary cap reached")
+    score_floor = sum(1 for r in excluded if r.reason == "summary score below floor")
+
+    lines = [
+        "## Pack noise report",
+        "",
+        f"- generic task ratio: {generic_task_term_ratio(task):.0%}",
+        f"- generic terms: {', '.join(generic_terms) if generic_terms else '(none)'}",
+        f"- specific terms: {', '.join(specific_terms) if specific_terms else '(none)'}",
+        f"- selected summaries: {summary_count}/{len(selected)}",
+        f"- filename-match selections: {filename_count}/{len(selected)}",
+        f"- symbol-match selections: {symbol_count}/{len(selected)}",
+        f"- excluded by summary cap: {summary_cap}",
+        f"- excluded by weak summary score: {score_floor}",
+        "",
+        "### Sharpen task wording",
+        "",
+    ]
+    if generic_terms:
+        lines.append("- Replace broad terms with subsystem, file, or symptom words.")
+        lines.append(f"- Broad terms driving matches: {', '.join(generic_terms[:8])}.")
+    else:
+        lines.append("- Task terms are already specific; inspect changed files or score weights next.")
+    if summary_count and selected and summary_count / len(selected) >= 0.7:
+        lines.append("- Try `--mode minimal` for edit work, or add exact module/file names.")
+    if filename_count and selected and filename_count / len(selected) >= 0.6:
+        lines.append("- Filename matches dominate; add behavior words that appear inside target files.")
+    return lines
+
+
+def _print_noise_report(task: str, plan: object) -> None:
+    for line in _noise_report(task, plan):
+        console.print(line)
+
+
 def register(app: typer.Typer) -> None:
     @app.command()
     def explain(
@@ -120,6 +165,7 @@ def register(app: typer.Typer) -> None:
         since: Optional[str] = typer.Option(None, "--since", help="Git ref to compare against (e.g. HEAD~1, main)."),
         file: Optional[str] = typer.Option(None, "--file", help="Show detailed score breakdown for a specific file."),
         omitted: bool = typer.Option(False, "--omitted", is_flag=True, help="Show top-10 excluded files and why."),
+        why_noisy: bool = typer.Option(False, "--why-noisy", is_flag=True, help="Explain broad task terms and noisy selection signals."),
     ) -> None:
         """Explain which files would be selected and why, without writing a context file."""
         if mode not in ("minimal", "balanced", "deep"):
@@ -199,6 +245,12 @@ def register(app: typer.Typer) -> None:
             console.print()
             return
 
+        if why_noisy:
+            console.print(f"\n[bold]Task:[/] [cyan]{resolved_task}[/]  [dim]mode={mode}  budget={plan.budget:,}[/]\n")
+            _print_noise_report(resolved_task, plan)
+            console.print()
+            return
+
         console.print(f"\n[bold]Task:[/] [cyan]{resolved_task}[/]  [dim]mode={mode}  budget={plan.budget:,}[/]\n")
 
         console.print("[bold]Top selected files (ranked):[/]")