agentpack-cli 0.3.21__tar.gz → 0.3.23__tar.gz

{agentpack_cli-0.3.21 → agentpack_cli-0.3.23}/PKG-INFO

@@ -1,10 +1,15 @@
 Metadata-Version: 2.4
 Name: agentpack-cli
-Version: 0.3.21
-Summary: Local MCP context router for Claude Code, Codex, Cursor, and AI coding agents.
+Version: 0.3.23
+Summary: Local context engine for AI coding agents that ranks relevant repo files and builds compact task-focused context packs for Claude Code, Codex, Cursor, Windsurf, MCP, and CI workflows.
+Project-URL: Homepage, https://github.com/vishal2612200/agentpack
+Project-URL: Documentation, https://vishal2612200.github.io/agentpack/
+Project-URL: Repository, https://github.com/vishal2612200/agentpack
+Project-URL: Issues, https://github.com/vishal2612200/agentpack/issues
+Project-URL: Changelog, https://github.com/vishal2612200/agentpack/blob/main/CHANGELOG.md
 License: MIT
 License-File: LICENSE
-Keywords: ai,ai-agent,ai-coding-agents,antigravity,ci,claude-code,codex,coding-agent,context,context-engine,context-packing,context-router,cursor,developer-tools,llm,mcp,mcp-context-engine,packing,prompt-context,reduce-token-usage,repo-analysis,repo-context,windsurf
+Keywords: ai,ai-agent,ai-coding-agents,antigravity,ci,claude-code,codex,coding-agent,context,context-engine,context-packing,context-router,cursor,developer-tools,llm,local-first,mcp,mcp-context-engine,packing,prompt-context,reduce-token-usage,repo-analysis,repo-context,repo-map,task-focused-context,windsurf
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
@@ -12,6 +17,7 @@ Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Software Development :: Build Tools
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: >=3.10
@@ -49,9 +55,13 @@ 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)
 
-**Local context router for AI coding agents.**
+**Local context engine for AI coding agents.**
 
-AgentPack gives Claude Code, Codex, Cursor, and other coding agents a ranked starting map before they burn tool calls rediscovering your repo.
+AgentPack ranks relevant repository files and builds compact task-focused context packs for Claude Code, Codex, Cursor, Windsurf, Antigravity, MCP tools, CI jobs, and markdown-based LLM workflows.
+
+It runs local/offline repo analysis, compresses selected files into a token budget, and keeps context fresh through CLI commands, MCP tools, hooks, and agent integrations. Use it when an AI coding agent needs a ranked starting map instead of burning tool calls rediscovering your repo.
+
+AgentPack is a context preparation tool, not a coding agent.
 
 One workflow matters:
 
@@ -67,19 +77,20 @@ pipx run --spec agentpack-cli agentpack route --task "fix auth token expiry"
 
 ![AgentPack route demo](docs/assets/agentpack-route-demo.svg)
 
-> **Status: alpha (v0.3.21).** Works, tested, and used in real sessions. Python and JavaScript/TypeScript are the best-supported languages. Current benchmarks are useful regression checks, not broad proof that AgentPack improves coding-agent success. API may change before 1.0.
+> **Status: alpha (v0.3.23).** Works, tested, and used in real sessions. Python and JavaScript/TypeScript are the best-supported languages. Current benchmarks are useful regression checks, not broad proof that AgentPack improves coding-agent success. API may change before 1.0.
 >
 > **Platform note:** macOS, Linux, and Windows are supported. Windows support targets PowerShell plus Git for Windows. `cmd.exe` and bare Git setups are not a supported path yet.
 >
 > **Name note:** PyPI package is `agentpack-cli`, npm package is `@vishal2612200/agentpack`, and the command is `agentpack`. This project is unrelated to AgentPack dataset papers or other repos with the same name.
 
-## What's New in 0.3.21
+## What's New in 0.3.23
 
-`0.3.21` is a benchmark trust release. It keeps the current honest expanded
-public-suite baseline at **57.0% recall / 50.6% token precision**, removes the
-legacy minimal-mode surface in favor of `balanced`, improves benchmark
-diagnostics and public-suite methodology, and documents the next release target:
-**65%+ recall while holding 50%+ token precision**.
+`0.3.23` is a guarded-loop hardening release. It keeps AgentPack's core promise
+focused on local context and workflow evidence while making `agentpack work --run`
+an optional proof harness around existing agents. The loop now has known runner
+adapters, smoke checks, phase/diff/risk/acceptance artifacts, rollback patches,
+metrics, and stricter finish gates. The prior expanded public-suite baseline
+remains **66.0% recall / 51.1% token precision** across 108 scored public cases.
 
 ## Core Workflow
 
@@ -128,23 +139,21 @@ ranked but cut by budget, or absent from scan.
 
 ## Benchmark Proof
 
-Latest published v0.3.20 release table: 8 pinned public commits from Pallets
-Click, ItsDangerous, and MarkupSafe, scored against files actually changed by
-each commit. The public manifest now also supports 100+ sampled historical
-commits across Python, TypeScript, Go, Java, and monorepo repos for broader
-release runs.
+Current local release-candidate table: expanded public-suite historical commits
+across Python, TypeScript, Go, Java, and monorepo repos, scored against files
+actually changed by each commit.
 
 | Metric | Result |
 |---|---:|
-| Avg recall | 79.2% |
-| Avg token precision | 51.2% |
-| Pack p50 | 1,450 tokens |
-| Pack p95 | 3,805 tokens |
-
-Full v0.3.20 table: [`benchmarks/results/2026-06-11-public.md`](benchmarks/results/2026-06-11-public.md). This is scoped benchmark evidence, not a universal quality claim.
-The expanded 109-case public suite is the current optimization baseline:
-**57.0% recall / 50.6% token precision**. It is broader and harder than the
-8-case published table, and recall remains the active improvement target.
+| Scored cases | 108 |
+| Avg recall | 66.0% |
+| Avg token precision | 51.1% |
+| Pack p50 | 315 tokens |
+| Pack p95 | 1,150 tokens |
+
+Full local table: [`benchmarks/results/2026-06-13-public.md`](benchmarks/results/2026-06-13-public.md). This is scoped benchmark evidence, not a universal quality claim.
+The latest published v0.3.20 table remains available at
+[`benchmarks/results/2026-06-11-public.md`](benchmarks/results/2026-06-11-public.md).
 Reproduce the expanded public suite:
 
 ```bash
@@ -153,20 +162,19 @@ agentpack benchmark --public-suite --reproduce v0.3.20
 
 Benchmark methodology lives under [`benchmarks/results/v0.3.20/`](benchmarks/results/v0.3.20/methodology.md).
 
-### Next Release Benchmark Target
+### Release Benchmark Gate
 
-The next benchmark release target is to raise the expanded public suite from the
-current **57.0% recall / 50.6% token precision** baseline to **65%+ recall**
-while keeping token precision at **50%+**. The target should be measured on the
+The current local release-candidate result clears the target: **66.0% recall**
+and **51.1% token precision**. The target should continue to be measured on the
 same 100+ public historical-commit suite, with per-language slices published so
-precision gains are not hiding TypeScript, Go, Java, or monorepo regressions.
+aggregate gains are not hiding TypeScript, Go, Java, or monorepo regressions.
 
 Decision gate for the next public table:
 
 - full-suite recall is at least 65.0%
-- full-suite token precision is at least 50.0%
+- full-suite token precision is at least 51.0%
 - no major language or task slice loses more than 2 recall points
-- Vite/TypeScript, Gin/Go, and NestJS monorepo misses are reported separately
+- Vite/TypeScript, Gin/Go, Click/Python, and NestJS monorepo misses are reported separately
 - any AgentPack-vs-no-AgentPack A/B claim includes task success, tool calls,
   token cost, and time-to-first-correct-file
 
@@ -182,7 +190,7 @@ and [`docs/data-flow.md`](docs/data-flow.md).
 Start with the [docs index](docs/index.md), or jump to guides for
 [Claude Code](docs/claude-code-context-engine.md), [MCP](docs/mcp-context-engine.md),
 [Cursor](docs/cursor-context-packing.md), [token usage](docs/reduce-claude-code-token-usage.md),
-and [how AgentPack works](docs/how-agentpack-works.md).
+[AI coding agent context](docs/ai-coding-agent-context.md), and [how AgentPack works](docs/how-agentpack-works.md).
 
 ## Install
 
@@ -191,7 +199,7 @@ pipx install agentpack-cli
 agentpack --version
 ```
 
-Requires Python 3.10+. The PyPI package is `agentpack-cli`; the command is `agentpack`. Use `pipx` for normal installs because many macOS/Linux Python distributions block global `pip install` with PEP 668's `externally-managed-environment` error. If you prefer `pip`, install inside a virtual environment.
+Requires Python 3.10+ and is tested on Python 3.10-3.14. The PyPI package is `agentpack-cli`; the command is `agentpack`. Use `pipx` for normal installs because many macOS/Linux Python distributions block global `pip install` with PEP 668's `externally-managed-environment` error. If you prefer `pip`, install inside a virtual environment.
 
 Install `pipx` first if needed:
 
@@ -238,7 +246,7 @@ agentpack status
 agentpack finish --since main
 ```
 
-Use `agentpack quickstart --task "..." --write` when you want AgentPack to print the next commands and write the task file for you. Use `agentpack start "..." --pack-only` when you want only a fresh pack and not the guard path.
+Use `agentpack quickstart --task "..." --write` when you want AgentPack to print the next commands and write the task file for you. Use `agentpack start "..." --pack-only` when you want only a fresh pack and not the guard path. Optional guardrail: `agentpack work --run` is a proof harness around existing agents, not AgentPack's default workflow or an autonomous coding agent.
 
 ### Learn from AI-assisted work
 

{agentpack_cli-0.3.21 → agentpack_cli-0.3.23}/README.md

@@ -8,9 +8,13 @@
 [![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)
 
-**Local context router for AI coding agents.**
+**Local context engine for AI coding agents.**
 
-AgentPack gives Claude Code, Codex, Cursor, and other coding agents a ranked starting map before they burn tool calls rediscovering your repo.
+AgentPack ranks relevant repository files and builds compact task-focused context packs for Claude Code, Codex, Cursor, Windsurf, Antigravity, MCP tools, CI jobs, and markdown-based LLM workflows.
+
+It runs local/offline repo analysis, compresses selected files into a token budget, and keeps context fresh through CLI commands, MCP tools, hooks, and agent integrations. Use it when an AI coding agent needs a ranked starting map instead of burning tool calls rediscovering your repo.
+
+AgentPack is a context preparation tool, not a coding agent.
 
 One workflow matters:
 
@@ -26,19 +30,20 @@ pipx run --spec agentpack-cli agentpack route --task "fix auth token expiry"
 
 ![AgentPack route demo](docs/assets/agentpack-route-demo.svg)
 
-> **Status: alpha (v0.3.21).** Works, tested, and used in real sessions. Python and JavaScript/TypeScript are the best-supported languages. Current benchmarks are useful regression checks, not broad proof that AgentPack improves coding-agent success. API may change before 1.0.
+> **Status: alpha (v0.3.23).** Works, tested, and used in real sessions. Python and JavaScript/TypeScript are the best-supported languages. Current benchmarks are useful regression checks, not broad proof that AgentPack improves coding-agent success. API may change before 1.0.
 >
 > **Platform note:** macOS, Linux, and Windows are supported. Windows support targets PowerShell plus Git for Windows. `cmd.exe` and bare Git setups are not a supported path yet.
 >
 > **Name note:** PyPI package is `agentpack-cli`, npm package is `@vishal2612200/agentpack`, and the command is `agentpack`. This project is unrelated to AgentPack dataset papers or other repos with the same name.
 
-## What's New in 0.3.21
+## What's New in 0.3.23
 
-`0.3.21` is a benchmark trust release. It keeps the current honest expanded
-public-suite baseline at **57.0% recall / 50.6% token precision**, removes the
-legacy minimal-mode surface in favor of `balanced`, improves benchmark
-diagnostics and public-suite methodology, and documents the next release target:
-**65%+ recall while holding 50%+ token precision**.
+`0.3.23` is a guarded-loop hardening release. It keeps AgentPack's core promise
+focused on local context and workflow evidence while making `agentpack work --run`
+an optional proof harness around existing agents. The loop now has known runner
+adapters, smoke checks, phase/diff/risk/acceptance artifacts, rollback patches,
+metrics, and stricter finish gates. The prior expanded public-suite baseline
+remains **66.0% recall / 51.1% token precision** across 108 scored public cases.
 
 ## Core Workflow
 
@@ -87,23 +92,21 @@ ranked but cut by budget, or absent from scan.
 
 ## Benchmark Proof
 
-Latest published v0.3.20 release table: 8 pinned public commits from Pallets
-Click, ItsDangerous, and MarkupSafe, scored against files actually changed by
-each commit. The public manifest now also supports 100+ sampled historical
-commits across Python, TypeScript, Go, Java, and monorepo repos for broader
-release runs.
+Current local release-candidate table: expanded public-suite historical commits
+across Python, TypeScript, Go, Java, and monorepo repos, scored against files
+actually changed by each commit.
 
 | Metric | Result |
 |---|---:|
-| Avg recall | 79.2% |
-| Avg token precision | 51.2% |
-| Pack p50 | 1,450 tokens |
-| Pack p95 | 3,805 tokens |
-
-Full v0.3.20 table: [`benchmarks/results/2026-06-11-public.md`](benchmarks/results/2026-06-11-public.md). This is scoped benchmark evidence, not a universal quality claim.
-The expanded 109-case public suite is the current optimization baseline:
-**57.0% recall / 50.6% token precision**. It is broader and harder than the
-8-case published table, and recall remains the active improvement target.
+| Scored cases | 108 |
+| Avg recall | 66.0% |
+| Avg token precision | 51.1% |
+| Pack p50 | 315 tokens |
+| Pack p95 | 1,150 tokens |
+
+Full local table: [`benchmarks/results/2026-06-13-public.md`](benchmarks/results/2026-06-13-public.md). This is scoped benchmark evidence, not a universal quality claim.
+The latest published v0.3.20 table remains available at
+[`benchmarks/results/2026-06-11-public.md`](benchmarks/results/2026-06-11-public.md).
 Reproduce the expanded public suite:
 
 ```bash
@@ -112,20 +115,19 @@ agentpack benchmark --public-suite --reproduce v0.3.20
 
 Benchmark methodology lives under [`benchmarks/results/v0.3.20/`](benchmarks/results/v0.3.20/methodology.md).
 
-### Next Release Benchmark Target
+### Release Benchmark Gate
 
-The next benchmark release target is to raise the expanded public suite from the
-current **57.0% recall / 50.6% token precision** baseline to **65%+ recall**
-while keeping token precision at **50%+**. The target should be measured on the
+The current local release-candidate result clears the target: **66.0% recall**
+and **51.1% token precision**. The target should continue to be measured on the
 same 100+ public historical-commit suite, with per-language slices published so
-precision gains are not hiding TypeScript, Go, Java, or monorepo regressions.
+aggregate gains are not hiding TypeScript, Go, Java, or monorepo regressions.
 
 Decision gate for the next public table:
 
 - full-suite recall is at least 65.0%
-- full-suite token precision is at least 50.0%
+- full-suite token precision is at least 51.0%
 - no major language or task slice loses more than 2 recall points
-- Vite/TypeScript, Gin/Go, and NestJS monorepo misses are reported separately
+- Vite/TypeScript, Gin/Go, Click/Python, and NestJS monorepo misses are reported separately
 - any AgentPack-vs-no-AgentPack A/B claim includes task success, tool calls,
   token cost, and time-to-first-correct-file
 
@@ -141,7 +143,7 @@ and [`docs/data-flow.md`](docs/data-flow.md).
 Start with the [docs index](docs/index.md), or jump to guides for
 [Claude Code](docs/claude-code-context-engine.md), [MCP](docs/mcp-context-engine.md),
 [Cursor](docs/cursor-context-packing.md), [token usage](docs/reduce-claude-code-token-usage.md),
-and [how AgentPack works](docs/how-agentpack-works.md).
+[AI coding agent context](docs/ai-coding-agent-context.md), and [how AgentPack works](docs/how-agentpack-works.md).
 
 ## Install
 
@@ -150,7 +152,7 @@ pipx install agentpack-cli
 agentpack --version
 ```
 
-Requires Python 3.10+. The PyPI package is `agentpack-cli`; the command is `agentpack`. Use `pipx` for normal installs because many macOS/Linux Python distributions block global `pip install` with PEP 668's `externally-managed-environment` error. If you prefer `pip`, install inside a virtual environment.
+Requires Python 3.10+ and is tested on Python 3.10-3.14. The PyPI package is `agentpack-cli`; the command is `agentpack`. Use `pipx` for normal installs because many macOS/Linux Python distributions block global `pip install` with PEP 668's `externally-managed-environment` error. If you prefer `pip`, install inside a virtual environment.
 
 Install `pipx` first if needed:
 
@@ -197,7 +199,7 @@ agentpack status
 agentpack finish --since main
 ```
 
-Use `agentpack quickstart --task "..." --write` when you want AgentPack to print the next commands and write the task file for you. Use `agentpack start "..." --pack-only` when you want only a fresh pack and not the guard path.
+Use `agentpack quickstart --task "..." --write` when you want AgentPack to print the next commands and write the task file for you. Use `agentpack start "..." --pack-only` when you want only a fresh pack and not the guard path. Optional guardrail: `agentpack work --run` is a proof harness around existing agents, not AgentPack's default workflow or an autonomous coding agent.
 
 ### Learn from AI-assisted work
 

{agentpack_cli-0.3.21 → agentpack_cli-0.3.23}/pyproject.toml

@@ -1,11 +1,11 @@
 [project]
 name = "agentpack-cli"
-version = "0.3.21"
-description = "Local MCP context router for Claude Code, Codex, Cursor, and AI coding agents."
+version = "0.3.23"
+description = "Local context engine for AI coding agents that ranks relevant repo files and builds compact task-focused context packs for Claude Code, Codex, Cursor, Windsurf, MCP, and CI workflows."
 readme = "README.md"
 requires-python = ">=3.10"
 license = {text = "MIT"}
-keywords = ["ai-coding-agents", "coding-agent", "ai-agent", "claude-code", "developer-tools", "repo-analysis", "repo-context", "context-engine", "mcp-context-engine", "context-router", "context-packing", "prompt-context", "reduce-token-usage", "mcp", "ci", "codex", "cursor", "windsurf", "antigravity", "ai", "llm", "context", "packing"]
+keywords = ["ai-coding-agents", "coding-agent", "ai-agent", "claude-code", "developer-tools", "repo-analysis", "repo-context", "context-engine", "mcp-context-engine", "context-router", "context-packing", "prompt-context", "task-focused-context", "reduce-token-usage", "local-first", "repo-map", "mcp", "ci", "codex", "cursor", "windsurf", "antigravity", "ai", "llm", "context", "packing"]
 classifiers = [
   "Development Status :: 3 - Alpha",
   "Intended Audience :: Developers",
@@ -14,6 +14,7 @@ classifiers = [
   "Programming Language :: Python :: 3.11",
   "Programming Language :: Python :: 3.12",
   "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
   "Topic :: Software Development :: Libraries :: Python Modules",
   "Topic :: Software Development :: Build Tools",
 ]
@@ -28,6 +29,13 @@ dependencies = [
   "tomli>=2.0.0; python_version < '3.11'"
 ]
 
+[project.urls]
+Homepage = "https://github.com/vishal2612200/agentpack"
+Documentation = "https://vishal2612200.github.io/agentpack/"
+Repository = "https://github.com/vishal2612200/agentpack"
+Issues = "https://github.com/vishal2612200/agentpack/issues"
+Changelog = "https://github.com/vishal2612200/agentpack/blob/main/CHANGELOG.md"
+
 [project.scripts]
 agentpack = "agentpack.cli:app"
 

{agentpack_cli-0.3.21 → agentpack_cli-0.3.23}/src/agentpack/__init__.py

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

{agentpack_cli-0.3.21 → agentpack_cli-0.3.23}/src/agentpack/analysis/ranking.py

@@ -1160,6 +1160,149 @@ def _domain_tokens(path: str) -> set[str]:
     return {tok for tok in _path_tokens(path) if len(tok) >= 3 and tok not in _PATH_NOISE_TOKENS}
 
 
+def _api_route_terms(path: str) -> tuple[str, ...]:
+    parts = [part.lower() for part in Path(path).parts]
+    if "api" not in parts:
+        return ()
+    api_index = parts.index("api")
+    suffix = parts[api_index + 1:]
+    if not suffix:
+        return ()
+    route_file_names = {
+        "route.ts", "route.tsx", "route.js", "route.jsx",
+        "routes.py", "urls.py", "views.py", "controller.ts", "controller.js",
+    }
+    if suffix[-1] in route_file_names or Path(suffix[-1]).stem.lower() in {"route", "routes", "urls", "views", "controller"}:
+        suffix = suffix[:-1]
+    terms: list[str] = []
+    for part in suffix:
+        clean = part.strip("[](){}")
+        if not clean or clean.startswith("_"):
+            continue
+        terms.extend(token for token in _ordered_tokens(clean) if token and token not in _PATH_NOISE_TOKENS)
+    return tuple(dict.fromkeys(terms))
+
+
+def _is_api_route_path(path: str) -> bool:
+    return bool(_api_route_terms(path))
+
+
+def _api_route_label(path: str) -> str:
+    terms = _api_route_terms(path)
+    return "/api/" + "/".join(terms) if terms else path
+
+
+def _normalize_api_path(value: str) -> str | None:
+    match = re.search(r"/api/[A-Za-z0-9_./${}\[\]-]+", value)
+    if not match:
+        return None
+    path = match.group(0).split("?", 1)[0].split("#", 1)[0].split("${", 1)[0]
+    path = re.sub(r"/\[[^\]]+\]", "", path)
+    path = path.rstrip("/,;)")
+    return path.rstrip("/") or "/api"
+
+
+def _api_paths_from_summary(summary_data: object | None) -> set[str]:
+    paths: set[str] = set()
+    if summary_data is None:
+        return paths
+    for summary_field in ("calls", "entrypoints", "public_api"):
+        for value in _summary_values(summary_data, summary_field):
+            normalized = _normalize_api_path(value)
+            if normalized:
+                paths.add(normalized)
+    return paths
+
+
+def _api_path_terms(api_path: str) -> set[str]:
+    return {
+        token
+        for token in _ordered_tokens(api_path.removeprefix("/api/"))
+        if token and token not in _PATH_NOISE_TOKENS
+    }
+
+
+def _api_route_path(path: str, summary_data: object | None = None) -> str | None:
+    for value in _summary_values(summary_data, "entrypoints"):
+        normalized = _normalize_api_path(value)
+        if normalized:
+            return normalized
+    terms = _api_route_terms(path)
+    if terms:
+        return "/api/" + "/".join(terms)
+    return None
+
+
+def _looks_like_frontend_consumer(path: str, summary_data: object | None) -> bool:
+    suffix = Path(path).suffix.lower()
+    if suffix in {".tsx", ".jsx"}:
+        return True
+    path_terms = _path_tokens(path)
+    if path_terms & {"component", "components", "page", "pages", "client", "dashboard"}:
+        return True
+    return any(
+        value.startswith(("React page:", "React layout:", "React component:"))
+        for value in _summary_values(summary_data, "entrypoints")
+    )
+
+
+def _has_strong_structural_reason(reasons: list[str]) -> bool:
+    return any(
+        reason.startswith((
+            "API endpoint pair",
+            "API route owner match",
+            "direct content evidence",
+            "direct dependency",
+            "historically co-changed",
+            "keyword phrase match:",
+            "literal definition match:",
+            "matched call:",
+            "matched define:",
+            "matched entrypoint:",
+            "multi-token",
+            "quoted literal match:",
+            "recall neighbor",
+            "reverse dependency",
+            "test for",
+            "workspace match",
+        ))
+        or reason in {
+            "build/dependency metadata",
+            "config file",
+            "has related tests",
+            "knowledge/architecture doc",
+            "release/version metadata",
+        }
+        for reason in reasons
+    )
+
+
+def _keyword_only_false_positive(path: str, reasons: list[str], content_hits: int) -> bool:
+    if _is_test_file(path):
+        return False
+    if _has_strong_structural_reason(reasons):
+        return False
+    keyword_reasons = [
+        reason for reason in reasons
+        if reason == "filename keyword match"
+        or reason == "symbol keyword match"
+        or reason.startswith((
+            "content keyword match",
+            "matched domain:",
+            "matched naming keyword:",
+            "matched ranking keyword:",
+            "matched role keyword:",
+        ))
+    ]
+    if len(keyword_reasons) < 2:
+        return False
+    if _is_api_route_path(path):
+        return False
+    if content_hits >= 4 and "symbol keyword match" in reasons:
+        return False
+    return True
+
+
 def score_files(
     files: list[FileInfo],
     changed_paths: set[str],
@@ -1296,6 +1439,12 @@ def score_files(
                 score += min(-6.0, w.weak_filename_match_penalty / 2)
                 reasons.append(f"generic public API penalty: {generic_public_names[0]}")
 
+        api_route_terms = set(_api_route_terms(fi.path))
+        api_route_matches = api_route_terms & (set(_keyword_token_weights(keywords, path=fi.path)) - _PATH_NOISE_TOKENS)
+        if api_route_matches:
+            score += 170.0 + (35.0 * min(2, len(api_route_matches) - 1))
+            reasons.append(f"API route owner match: {_api_route_label(fi.path)}")
+
         content_hits = 0
         searchable_text = ""
         if fi.content is not None:
@@ -1368,6 +1517,8 @@ def score_files(
         if matched_task_signal and _has_role(fi.path, _IMPLEMENTATION_ROLE_TOKENS):
             score += w.implementation_role
             reasons.append("implementation role match")
+        elif fi.path in changed_paths:
+            reasons.append("modified workspace context only")
 
         if explicit_test_task:
             if _is_test_file(fi.path):
@@ -1397,6 +1548,8 @@ def score_files(
             if tests and any(t in all_paths for t in tests):
                 score += w.related_test
                 reasons.append("has related tests")
+            elif _is_api_route_path(fi.path):
+                reasons.append("no direct tests found for endpoint")
 
             if _is_test_file(fi.path):
                 for src_path in changed_paths:
@@ -1460,6 +1613,10 @@ def score_files(
             score += w.large_unrelated_penalty
             reasons.append("large unrelated file")
 
+        if _keyword_only_false_positive(fi.path, reasons, content_hits):
+            score = max(0.0, score * 0.72)
+            reasons.append("likely false positive: keyword-only match")
+
         results.append((fi, score, reasons))
 
     return results
@@ -1507,6 +1664,107 @@ def boost_cross_layer_related(
     return result
 
 
+def boost_api_endpoint_pairs(
+    scored: list[tuple[FileInfo, float, list[str]]],
+    keywords: set[str] | dict[str, float] | KeywordPlan,
+    weights: ScoringWeights | None = None,
+) -> list[tuple[FileInfo, float, list[str]]]:
+    """Boost sibling API endpoints once one endpoint in the family is a strong task match."""
+    w = weights or _DEFAULT_WEIGHTS
+    keyword_tokens = set(_keyword_token_weights(keywords)) - _PATH_NOISE_TOKENS
+    api_rows: list[tuple[FileInfo, float, list[str], tuple[str, ...]]] = []
+    for fi, score, reasons in scored:
+        terms = _api_route_terms(fi.path)
+        if terms and not fi.ignored and not fi.binary:
+            api_rows.append((fi, score, reasons, terms))
+    if len(api_rows) < 2:
+        return scored
+
+    seeds: dict[str, tuple[str, float]] = {}
+    for fi, score, reasons, terms in api_rows:
+        if not terms:
+            continue
+        family = terms[0]
+        direct_owner = any(reason.startswith("API route owner match:") for reason in reasons)
+        endpoint_matches_task = bool(set(terms) & keyword_tokens)
+        if score < 90 and not direct_owner:
+            continue
+        if not (direct_owner or endpoint_matches_task):
+            continue
+        current = seeds.get(family)
+        if current is None or score > current[1]:
+            seeds[family] = (fi.path, score)
+    if not seeds:
+        return scored
+
+    result: list[tuple[FileInfo, float, list[str]]] = []
+    for fi, score, reasons in scored:
+        terms = _api_route_terms(fi.path)
+        if terms:
+            family = terms[0]
+            seed = seeds.get(family)
+            if seed and seed[0] != fi.path and not any(reason.startswith("API endpoint pair") for reason in reasons):
+                seed_path, _seed_score = seed
+                amount = min(85.0, w.cross_layer_related + 15.0)
+                if set(terms) & keyword_tokens:
+                    amount += 25.0
+                score += amount
+                reasons = reasons + [f"API endpoint pair with {_api_route_label(seed_path)}"]
+        result.append((fi, score, reasons))
+    return result
+
+
+def boost_frontend_api_consumers(
+    scored: list[tuple[FileInfo, float, list[str]]],
+    summaries: dict[str, Any] | None,
+    keywords: set[str] | dict[str, float] | KeywordPlan,
+    weights: ScoringWeights | None = None,
+) -> list[tuple[FileInfo, float, list[str]]]:
+    """Boost API route files consumed by scored frontend/client files."""
+    if not summaries:
+        return scored
+    w = weights or _DEFAULT_WEIGHTS
+    keyword_tokens = set(_keyword_token_weights(keywords)) - _PATH_NOISE_TOKENS
+    endpoint_by_api_path: dict[str, str] = {}
+    for fi, _score, _reasons in scored:
+        api_path = _api_route_path(fi.path, summaries.get(fi.path))
+        if api_path:
+            endpoint_by_api_path[api_path] = fi.path
+    if not endpoint_by_api_path:
+        return scored
+
+    boosts: dict[str, tuple[float, str, str]] = {}
+    for consumer, consumer_score, _consumer_reasons in scored:
+        summary_data = summaries.get(consumer.path)
+        consumed_paths = _api_paths_from_summary(summary_data)
+        if not consumed_paths or consumer_score <= 0:
+            continue
+        if not _looks_like_frontend_consumer(consumer.path, summary_data):
+            continue
+        for api_path in consumed_paths:
+            endpoint_path = endpoint_by_api_path.get(api_path)
+            if not endpoint_path or endpoint_path == consumer.path:
+                continue
+            amount = min(150.0, 90.0 + (w.cross_layer_related * 0.6))
+            if _api_path_terms(api_path) & keyword_tokens:
+                amount += 45.0
+            current = boosts.get(endpoint_path)
+            if current is None or amount > current[0]:
+                boosts[endpoint_path] = (amount, api_path, consumer.path)
+
+    if not boosts:
+        return scored
+    result: list[tuple[FileInfo, float, list[str]]] = []
+    for fi, score, reasons in scored:
+        boost = boosts.get(fi.path)
+        if boost:
+            amount, api_path, consumer_path = boost
+            score += amount
+            reasons = reasons + [f"API producer for frontend call {api_path} from {consumer_path}"]
+        result.append((fi, score, reasons))
+    return result
+
+
 def boost_paired_tests(
     scored: list[tuple[FileInfo, float, list[str]]],
     weights: ScoringWeights | None = None,