agentpack-cli 0.2.0__tar.gz → 0.2.2__tar.gz

{agentpack_cli-0.2.0 → agentpack_cli-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentpack-cli
-Version: 0.2.0
+Version: 0.2.2
 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.2.0).** 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.2.1).** 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.
 
@@ -100,7 +100,8 @@ The npm package is a Node launcher around the Python implementation. It installs
 ```bash
 cd your-project
 agentpack init --agent codex       # or claude, cursor, windsurf, antigravity
-agentpack pack --task "fix auth token expiry"
+printf '%s\n' "fix auth token expiry" > .agentpack/task.md
+agentpack pack
 ```
 
 This creates `.agentpack/` state, installs the requested agent integration, generates a ranked context pack, and writes the adapter output for that agent. For active local work, keep context fresh with:
@@ -150,10 +151,19 @@ Use real repo evals instead of trusting compression numbers:
 ```bash
 agentpack benchmark --init
 # add historical tasks and files actually changed
-agentpack benchmark --compare --misses
+agentpack benchmark --compare --misses --public-table
+agentpack benchmark --public-repos --prove-targets --misses --public-table
 agentpack benchmark --results-template
 ```
 
+For public proof, use several real repositories or anonymized historical task
+sets and publish the generated table from `benchmarks/results/*-public.md`.
+This repo includes a curated public smoke suite in
+`benchmarks/public-repos.toml`; it evaluates real commits from Pallets Click,
+ItsDangerous, and MarkupSafe by checking out each commit's parent and scoring
+against files actually changed by the commit. Synthetic fixtures are useful
+regression tests, but should not be presented as market proof.
+
 ## Debugging Selection
 
 When AgentPack misses a file, the next command should explain the miss:
@@ -169,6 +179,41 @@ agentpack explain --task "fix billing webhook" --budget-plan
 
 This is the core reliability loop: pack, measure recall, inspect misses, then tune task wording, `.agentignore`, or scoring weights.
 
+## MCP-First Workflow
+
+For MCP-capable agents, the preferred workflow is pull-based:
+
+1. Call `start_task(task)` when a new task begins. AgentPack writes `.agentpack/task.md`, packs context, and returns ranked markdown.
+2. Call `get_context()` when you need the latest cached pack; it tells you if the pack is stale.
+3. Call `get_delta_context()` after edits or hook hints to see what changed without loading the full pack.
+4. Call `explain_file(path)` or `get_related_files(path)` when a file looks relevant or suspicious.
+
+The CLI remains the setup/debug/release path. MCP is the best interactive path because the agent can ask for only the context it needs instead of relying on one static startup blob.
+
+## Before / After Agent Behavior
+
+Without AgentPack:
+
+```text
+User: fix auth token expiry
+Agent: rg "auth"; opens router; opens middleware; opens tests; opens config;
+       asks for more files; eventually finds token/session code.
+Cost: repeated repo exploration and many unrelated file reads.
+```
+
+With AgentPack:
+
+```text
+User: fix auth token expiry
+Agent: calls start_task("fix auth token expiry")
+AgentPack: returns ranked files with reasons:
+  1. src/auth/token.py — filename/content match, changed dependency
+  2. src/auth/session.py — related implementation
+  3. tests/test_auth.py — paired test
+Agent: verifies those files, edits, runs tests, checks misses if needed.
+Cost: starts from a measured map, then still verifies source normally.
+```
+
 ## When it helps
 
 | Workflow | Value |
@@ -437,7 +482,8 @@ Most users only need four commands:
 
 ```bash
 agentpack init --agent codex
-agentpack pack --task "describe the change"
+printf '%s\n' "describe the change" > .agentpack/task.md
+agentpack pack
 agentpack watch
 agentpack doctor --agent all
 ```
@@ -640,18 +686,21 @@ Summaries are built with parallel AST/regex analysis — no network, no tokens s
 
 ### `agentpack pack`
 
-Generate a context pack.
+Generate a context pack. Task text lives in `.agentpack/task.md`; inline task strings are no longer supported on `pack`. `--task auto` remains for old hooks and scripts, and is the default when the flag is omitted.
 
 ```bash
-agentpack pack --task "fix auth session bug"        # auto-detects your IDE
-agentpack pack --agent claude --task "fix auth bug" # explicit agent
-agentpack pack --workspace apps/web --task "fix web auth"
+printf '%s\n' "fix auth session bug" > .agentpack/task.md
+agentpack pack                                # auto-detects your IDE
+agentpack pack --agent claude                 # explicit agent
+agentpack pack --workspace apps/web
 
 # Only include changes since a git ref
-agentpack pack --task "review these changes" --since main
+printf '%s\n' "review these changes" > .agentpack/task.md
+agentpack pack --since main
 
 # Watch mode — re-packs on every file change
-agentpack pack --task "refactor auth" --session
+printf '%s\n' "refactor auth" > .agentpack/task.md
+agentpack pack --session
 ```
 
 Options:
@@ -659,7 +708,7 @@ Options:
 | Flag | Default | Description |
 |------|---------|-------------|
 | `--agent` | `auto` | Target agent (`auto` \| `claude` \| `cursor` \| `windsurf` \| `codex` \| `antigravity` \| `generic`). `auto` detects the active IDE from env and project files. |
-| `--task` | `auto` | Task description, or `auto` to infer from git |
+| `--task` | `auto` | Backward-compatible task source. Only `auto` is supported; write task text to `.agentpack/task.md`. |
 | `--mode` | `balanced` | Budget mode: `minimal`, `balanced`, `deep` |
 | `--budget` | 0 (uses config default 25000) | Token budget |
 | `--workspace` | — | Restrict packing to a monorepo workspace and write `.agentpack/workspaces/<workspace>/context.md` |
@@ -761,7 +810,8 @@ Register in Claude Code settings (`~/.claude/settings.json`):
 
 | Tool | Description |
 |---|---|
-| `pack_context(task, mode, budget, max_tokens)` | Generate a ranked context pack for a task. Returns packed markdown, truncated to `max_tokens` (default 20,000). |
+| `start_task(task, mode, budget, max_tokens)` | Recommended MCP-first entry point. Writes `.agentpack/task.md`, generates a ranked pack, and returns packed markdown. |
+| `pack_context(task, mode, budget, max_tokens)` | Generate a ranked context pack. If `task` is provided, writes it to `.agentpack/task.md`; if omitted, reads `task.md` or infers from git. |
 | `get_context()` | Return the latest pre-built pack instantly (no repack). Prepends a freshness/staleness header so you know if it's stale. |
 | `refresh()` | Refresh using the current `task.md` or git-inferred task. |
 | `explain_file(path, task)` | Show score, inclusion mode, reasons, symbols, imports, and importers for one file. |
@@ -774,7 +824,7 @@ Register in Claude Code settings (`~/.claude/settings.json`):
 > **Stale context** — repo changed since last pack (generated: ...). Run pack_context() to refresh.
 ```
 
-**Smart truncation:** `pack_context()` keeps headers intact and trims file content blocks to fit the token budget, appending a note about how many files were omitted.
+**Smart truncation:** `start_task()` and `pack_context()` keep headers intact and trim file content blocks to fit the token budget, appending a note about how many files were omitted.
 
 Zero API calls — all analysis is offline. Summary cache keyed by file hash: cold run parallelises AST parsing across CPU cores; warm cache hits are instant.
 
@@ -826,8 +876,10 @@ agentpack benchmark --init                                 # scaffold .agentpack
 agentpack benchmark --results-template                     # scaffold publishable results note
 agentpack benchmark                                        # run all cases in benchmark.toml
 agentpack benchmark --sample-fixtures                      # source checkout demo evals
+agentpack benchmark --public-repos                         # real public commit evals
 agentpack benchmark --misses                               # explain expected-file misses
 agentpack benchmark --prove-targets                        # fail if recall/token precision targets miss
+agentpack benchmark --public-table                         # write benchmarks/results/*-public.md
 ```
 
 Output per case:
@@ -884,6 +936,15 @@ Use `--misses` when recall is low. It prints each expected file that was not sel
 
 Use `--prove-targets` in CI or release prep when benchmark cases have `expected_files`. By default it requires average recall >=60% and token precision >=50%; tune with `--min-recall` and `--min-token-precision`.
 
+Use `--public-repos` from an AgentPack source checkout to run the committed
+real-repo smoke suite:
+
+```bash
+agentpack benchmark --public-repos --prove-targets --misses --public-table
+```
+
+Use `--public-table` after adding real historical tasks to write a publishable Markdown table with per-repo/task recall, token precision, rank@K, pack size, and miss count. This is the recommended artifact for README claims, release notes, and external benchmarks.
+
 Add `task_type` to group results by workflow area. Benchmark summaries report average precision, recall, F1, and token noise by type, so a repo can show "backend-api is good, frontend-web is noisy" instead of hiding that under one aggregate.
 
 ---
@@ -1313,7 +1374,7 @@ src/agentpack/
     compact.py                 # compact protocol format for session context files
     receipts.py                # context receipt formatter
 
-  mcp_server.py                # MCP tools: pack_context, get_context, explain, related, stats, delta
+  mcp_server.py                # MCP tools: start_task, pack_context, get_context, explain, related, stats, delta
 
   session/
     state.py                   # SessionState dataclass + load/save/create/stop helpers
@@ -1351,6 +1412,7 @@ src/agentpack/
 - **Repo maps are first-class context**: `analysis/repo_map.py` builds a compact semantic map before file context, and its token cost is reserved before file selection.
 - **Metrics feed history learning**: selection accuracy records hit/noise paths, token precision, mode counts, and mode tokens. Later packs gently penalize repeated noisy paths unless they are currently changed.
 - **Git history feeds recall**: files that historically changed in the same commits as live changed files receive a small boost, helping related tests, schemas, services, and configs surface without forcing full-content inclusion.
+- **Second-pass expansion is guarded**: after first scoring, strong seeds can lift two-hop import, reverse-import, config, and related-test neighbours only when they share task or domain signal.
 - **Co-change is guarded by precision history**: one-off co-change neighbors are ignored, and paths repeatedly measured as noise do not get revived by history boosts.
 - **Precision guardrails adapt to bad history**: when summary token precision stays near zero, later packs raise the summary score floor, cap summaries more aggressively, and suppress summaries entirely for no-live-change packs. Weak filename-only matches are also damped unless other signals confirm them.
 - **`AdapterRegistry` maps agent → adapter**: adding a new agent output format requires one entry in `AdapterRegistry.get()`, not changes to `PackService`.
@@ -1359,7 +1421,7 @@ src/agentpack/
 - **`integrations/` vs `core/`**: git hooks, shell rc patching, and VS Code tasks are infrastructure concerns — they live in `integrations/`, not `core/`. `core/` is pure domain logic.
 - **Adapters render; installers configure**: `adapters/` knows how to write a context file for an agent. `installers/` knows how to configure the agent's tool (CLAUDE.md, .cursorrules, settings.json). They are separate concerns and separate classes.
 - **Agent integration contract is shared**: `integrations/agents.py` defines install, audit, and repair behavior for Claude, Cursor, Windsurf, Codex, Antigravity, and Generic. `install`, `repair`, `doctor --agent all`, and release verification use the same contract.
-- **MCP and hooks use deltas when possible**: MCP exposes `get_delta_context()`, and prompt hooks can emit task/top-file/delta hints instead of injecting the full context every time.
+- **MCP is the interactive path**: `start_task()` writes task state and returns a fresh pack, while `get_context()`, `get_delta_context()`, `explain_file()`, and `get_related_files()` let agents pull follow-up context on demand.
 
 ---
 
@@ -1378,7 +1440,7 @@ src/agentpack/
 
 - **Windows**: not supported. Git hooks use POSIX shell (`#!/bin/sh`, `>/dev/null 2>&1 &`). The Claude Code session hooks use `python3` and `rm -f`. Contributions welcome.
 - **Monorepos**: workspace-aware ranking supports npm/pnpm, Cargo, and `go.work` layouts. `--workspace` creates filtered per-workspace outputs. Package dependency hints currently come from npm/pnpm `package.json`; Cargo/Go workspace membership is detected, but package-manager dependency edges for Cargo/Go are not yet modeled.
-- **Public benchmark proof**: source-checkout fixture results are useful regressions, not market proof. Use `agentpack benchmark --results-template` to publish real historical task results.
+- **Public benchmark proof**: `benchmarks/public-repos.toml` is a curated smoke suite over real public commits, and `benchmarks/results/2026-05-15-public.md` records the current proof run. Treat it as a floor, not a leaderboard; expand cases before broad external claims.
 - **Symbol extraction**: Python (AST, full) and JavaScript/TypeScript (regex, arrow functions + classes) are well-supported. Go, Rust, Java, Kotlin have import graph traversal but no symbol extraction — they fall back to file-level summaries.
 - **Selection recall**: ranking is heuristic. It can miss files when task language differs from code language, when repos have unusual architecture, or when important files are only connected at runtime.
 - **Secret redaction**: covers AWS keys, GitHub tokens, OpenAI/Anthropic keys, JWTs, and private key blocks. Not a substitute for a dedicated secrets scanner on sensitive repos.
@@ -1389,12 +1451,12 @@ src/agentpack/
 
 ## Roadmap
 
-Next release target: **0.2.0 = benchmark + recall release**.
+Next release target: **0.3.0 = public proof + npm publish hardening**.
 
-- Expand public source-checkout fixtures and publish reproducible `benchmark --sample-fixtures --compare --misses` output.
-- Raise recall on real historical tasks while keeping token precision healthy; target 60%+ recall, 50%+ token precision, and balanced packs under 25k tokens.
-- Improve second-pass expansion beyond current imports, reverse imports, related tests, historical co-change, and workspace hints with framework route/service/schema pairs.
-- Make MCP pull flows more prominent so agents can ask for `explain_file`, `get_related_files`, and `get_delta_context` instead of relying only on a static startup pack.
+- Expand the public real-repo suite beyond the current curated Pallets smoke set.
+- Keep recall gains measured with `--prove-targets`; target 60%+ recall, 50%+ token precision, and task packs under 25k tokens.
+- Extend second-pass expansion with framework route/service/schema pairs once benchmark misses prove the pattern.
+- Make npm publishing reliable by adding `NPM_TOKEN` and rerunning the npm release workflow.
 - Keep integration contracts stable across Claude, Cursor, Windsurf, Codex, Antigravity, and Generic before any 1.0 work.
 
 ---

{agentpack_cli-0.2.0 → agentpack_cli-0.2.2}/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.2.0).** 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.2.1).** 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.
 
@@ -61,7 +61,8 @@ The npm package is a Node launcher around the Python implementation. It installs
 ```bash
 cd your-project
 agentpack init --agent codex       # or claude, cursor, windsurf, antigravity
-agentpack pack --task "fix auth token expiry"
+printf '%s\n' "fix auth token expiry" > .agentpack/task.md
+agentpack pack
 ```
 
 This creates `.agentpack/` state, installs the requested agent integration, generates a ranked context pack, and writes the adapter output for that agent. For active local work, keep context fresh with:
@@ -111,10 +112,19 @@ Use real repo evals instead of trusting compression numbers:
 ```bash
 agentpack benchmark --init
 # add historical tasks and files actually changed
-agentpack benchmark --compare --misses
+agentpack benchmark --compare --misses --public-table
+agentpack benchmark --public-repos --prove-targets --misses --public-table
 agentpack benchmark --results-template
 ```
 
+For public proof, use several real repositories or anonymized historical task
+sets and publish the generated table from `benchmarks/results/*-public.md`.
+This repo includes a curated public smoke suite in
+`benchmarks/public-repos.toml`; it evaluates real commits from Pallets Click,
+ItsDangerous, and MarkupSafe by checking out each commit's parent and scoring
+against files actually changed by the commit. Synthetic fixtures are useful
+regression tests, but should not be presented as market proof.
+
 ## Debugging Selection
 
 When AgentPack misses a file, the next command should explain the miss:
@@ -130,6 +140,41 @@ agentpack explain --task "fix billing webhook" --budget-plan
 
 This is the core reliability loop: pack, measure recall, inspect misses, then tune task wording, `.agentignore`, or scoring weights.
 
+## MCP-First Workflow
+
+For MCP-capable agents, the preferred workflow is pull-based:
+
+1. Call `start_task(task)` when a new task begins. AgentPack writes `.agentpack/task.md`, packs context, and returns ranked markdown.
+2. Call `get_context()` when you need the latest cached pack; it tells you if the pack is stale.
+3. Call `get_delta_context()` after edits or hook hints to see what changed without loading the full pack.
+4. Call `explain_file(path)` or `get_related_files(path)` when a file looks relevant or suspicious.
+
+The CLI remains the setup/debug/release path. MCP is the best interactive path because the agent can ask for only the context it needs instead of relying on one static startup blob.
+
+## Before / After Agent Behavior
+
+Without AgentPack:
+
+```text
+User: fix auth token expiry
+Agent: rg "auth"; opens router; opens middleware; opens tests; opens config;
+       asks for more files; eventually finds token/session code.
+Cost: repeated repo exploration and many unrelated file reads.
+```
+
+With AgentPack:
+
+```text
+User: fix auth token expiry
+Agent: calls start_task("fix auth token expiry")
+AgentPack: returns ranked files with reasons:
+  1. src/auth/token.py — filename/content match, changed dependency
+  2. src/auth/session.py — related implementation
+  3. tests/test_auth.py — paired test
+Agent: verifies those files, edits, runs tests, checks misses if needed.
+Cost: starts from a measured map, then still verifies source normally.
+```
+
 ## When it helps
 
 | Workflow | Value |
@@ -398,7 +443,8 @@ Most users only need four commands:
 
 ```bash
 agentpack init --agent codex
-agentpack pack --task "describe the change"
+printf '%s\n' "describe the change" > .agentpack/task.md
+agentpack pack
 agentpack watch
 agentpack doctor --agent all
 ```
@@ -601,18 +647,21 @@ Summaries are built with parallel AST/regex analysis — no network, no tokens s
 
 ### `agentpack pack`
 
-Generate a context pack.
+Generate a context pack. Task text lives in `.agentpack/task.md`; inline task strings are no longer supported on `pack`. `--task auto` remains for old hooks and scripts, and is the default when the flag is omitted.
 
 ```bash
-agentpack pack --task "fix auth session bug"        # auto-detects your IDE
-agentpack pack --agent claude --task "fix auth bug" # explicit agent
-agentpack pack --workspace apps/web --task "fix web auth"
+printf '%s\n' "fix auth session bug" > .agentpack/task.md
+agentpack pack                                # auto-detects your IDE
+agentpack pack --agent claude                 # explicit agent
+agentpack pack --workspace apps/web
 
 # Only include changes since a git ref
-agentpack pack --task "review these changes" --since main
+printf '%s\n' "review these changes" > .agentpack/task.md
+agentpack pack --since main
 
 # Watch mode — re-packs on every file change
-agentpack pack --task "refactor auth" --session
+printf '%s\n' "refactor auth" > .agentpack/task.md
+agentpack pack --session
 ```
 
 Options:
@@ -620,7 +669,7 @@ Options:
 | Flag | Default | Description |
 |------|---------|-------------|
 | `--agent` | `auto` | Target agent (`auto` \| `claude` \| `cursor` \| `windsurf` \| `codex` \| `antigravity` \| `generic`). `auto` detects the active IDE from env and project files. |
-| `--task` | `auto` | Task description, or `auto` to infer from git |
+| `--task` | `auto` | Backward-compatible task source. Only `auto` is supported; write task text to `.agentpack/task.md`. |
 | `--mode` | `balanced` | Budget mode: `minimal`, `balanced`, `deep` |
 | `--budget` | 0 (uses config default 25000) | Token budget |
 | `--workspace` | — | Restrict packing to a monorepo workspace and write `.agentpack/workspaces/<workspace>/context.md` |
@@ -722,7 +771,8 @@ Register in Claude Code settings (`~/.claude/settings.json`):
 
 | Tool | Description |
 |---|---|
-| `pack_context(task, mode, budget, max_tokens)` | Generate a ranked context pack for a task. Returns packed markdown, truncated to `max_tokens` (default 20,000). |
+| `start_task(task, mode, budget, max_tokens)` | Recommended MCP-first entry point. Writes `.agentpack/task.md`, generates a ranked pack, and returns packed markdown. |
+| `pack_context(task, mode, budget, max_tokens)` | Generate a ranked context pack. If `task` is provided, writes it to `.agentpack/task.md`; if omitted, reads `task.md` or infers from git. |
 | `get_context()` | Return the latest pre-built pack instantly (no repack). Prepends a freshness/staleness header so you know if it's stale. |
 | `refresh()` | Refresh using the current `task.md` or git-inferred task. |
 | `explain_file(path, task)` | Show score, inclusion mode, reasons, symbols, imports, and importers for one file. |
@@ -735,7 +785,7 @@ Register in Claude Code settings (`~/.claude/settings.json`):
 > **Stale context** — repo changed since last pack (generated: ...). Run pack_context() to refresh.
 ```
 
-**Smart truncation:** `pack_context()` keeps headers intact and trims file content blocks to fit the token budget, appending a note about how many files were omitted.
+**Smart truncation:** `start_task()` and `pack_context()` keep headers intact and trim file content blocks to fit the token budget, appending a note about how many files were omitted.
 
 Zero API calls — all analysis is offline. Summary cache keyed by file hash: cold run parallelises AST parsing across CPU cores; warm cache hits are instant.
 
@@ -787,8 +837,10 @@ agentpack benchmark --init                                 # scaffold .agentpack
 agentpack benchmark --results-template                     # scaffold publishable results note
 agentpack benchmark                                        # run all cases in benchmark.toml
 agentpack benchmark --sample-fixtures                      # source checkout demo evals
+agentpack benchmark --public-repos                         # real public commit evals
 agentpack benchmark --misses                               # explain expected-file misses
 agentpack benchmark --prove-targets                        # fail if recall/token precision targets miss
+agentpack benchmark --public-table                         # write benchmarks/results/*-public.md
 ```
 
 Output per case:
@@ -845,6 +897,15 @@ Use `--misses` when recall is low. It prints each expected file that was not sel
 
 Use `--prove-targets` in CI or release prep when benchmark cases have `expected_files`. By default it requires average recall >=60% and token precision >=50%; tune with `--min-recall` and `--min-token-precision`.
 
+Use `--public-repos` from an AgentPack source checkout to run the committed
+real-repo smoke suite:
+
+```bash
+agentpack benchmark --public-repos --prove-targets --misses --public-table
+```
+
+Use `--public-table` after adding real historical tasks to write a publishable Markdown table with per-repo/task recall, token precision, rank@K, pack size, and miss count. This is the recommended artifact for README claims, release notes, and external benchmarks.
+
 Add `task_type` to group results by workflow area. Benchmark summaries report average precision, recall, F1, and token noise by type, so a repo can show "backend-api is good, frontend-web is noisy" instead of hiding that under one aggregate.
 
 ---
@@ -1274,7 +1335,7 @@ src/agentpack/
     compact.py                 # compact protocol format for session context files
     receipts.py                # context receipt formatter
 
-  mcp_server.py                # MCP tools: pack_context, get_context, explain, related, stats, delta
+  mcp_server.py                # MCP tools: start_task, pack_context, get_context, explain, related, stats, delta
 
   session/
     state.py                   # SessionState dataclass + load/save/create/stop helpers
@@ -1312,6 +1373,7 @@ src/agentpack/
 - **Repo maps are first-class context**: `analysis/repo_map.py` builds a compact semantic map before file context, and its token cost is reserved before file selection.
 - **Metrics feed history learning**: selection accuracy records hit/noise paths, token precision, mode counts, and mode tokens. Later packs gently penalize repeated noisy paths unless they are currently changed.
 - **Git history feeds recall**: files that historically changed in the same commits as live changed files receive a small boost, helping related tests, schemas, services, and configs surface without forcing full-content inclusion.
+- **Second-pass expansion is guarded**: after first scoring, strong seeds can lift two-hop import, reverse-import, config, and related-test neighbours only when they share task or domain signal.
 - **Co-change is guarded by precision history**: one-off co-change neighbors are ignored, and paths repeatedly measured as noise do not get revived by history boosts.
 - **Precision guardrails adapt to bad history**: when summary token precision stays near zero, later packs raise the summary score floor, cap summaries more aggressively, and suppress summaries entirely for no-live-change packs. Weak filename-only matches are also damped unless other signals confirm them.
 - **`AdapterRegistry` maps agent → adapter**: adding a new agent output format requires one entry in `AdapterRegistry.get()`, not changes to `PackService`.
@@ -1320,7 +1382,7 @@ src/agentpack/
 - **`integrations/` vs `core/`**: git hooks, shell rc patching, and VS Code tasks are infrastructure concerns — they live in `integrations/`, not `core/`. `core/` is pure domain logic.
 - **Adapters render; installers configure**: `adapters/` knows how to write a context file for an agent. `installers/` knows how to configure the agent's tool (CLAUDE.md, .cursorrules, settings.json). They are separate concerns and separate classes.
 - **Agent integration contract is shared**: `integrations/agents.py` defines install, audit, and repair behavior for Claude, Cursor, Windsurf, Codex, Antigravity, and Generic. `install`, `repair`, `doctor --agent all`, and release verification use the same contract.
-- **MCP and hooks use deltas when possible**: MCP exposes `get_delta_context()`, and prompt hooks can emit task/top-file/delta hints instead of injecting the full context every time.
+- **MCP is the interactive path**: `start_task()` writes task state and returns a fresh pack, while `get_context()`, `get_delta_context()`, `explain_file()`, and `get_related_files()` let agents pull follow-up context on demand.
 
 ---
 
@@ -1339,7 +1401,7 @@ src/agentpack/
 
 - **Windows**: not supported. Git hooks use POSIX shell (`#!/bin/sh`, `>/dev/null 2>&1 &`). The Claude Code session hooks use `python3` and `rm -f`. Contributions welcome.
 - **Monorepos**: workspace-aware ranking supports npm/pnpm, Cargo, and `go.work` layouts. `--workspace` creates filtered per-workspace outputs. Package dependency hints currently come from npm/pnpm `package.json`; Cargo/Go workspace membership is detected, but package-manager dependency edges for Cargo/Go are not yet modeled.
-- **Public benchmark proof**: source-checkout fixture results are useful regressions, not market proof. Use `agentpack benchmark --results-template` to publish real historical task results.
+- **Public benchmark proof**: `benchmarks/public-repos.toml` is a curated smoke suite over real public commits, and `benchmarks/results/2026-05-15-public.md` records the current proof run. Treat it as a floor, not a leaderboard; expand cases before broad external claims.
 - **Symbol extraction**: Python (AST, full) and JavaScript/TypeScript (regex, arrow functions + classes) are well-supported. Go, Rust, Java, Kotlin have import graph traversal but no symbol extraction — they fall back to file-level summaries.
 - **Selection recall**: ranking is heuristic. It can miss files when task language differs from code language, when repos have unusual architecture, or when important files are only connected at runtime.
 - **Secret redaction**: covers AWS keys, GitHub tokens, OpenAI/Anthropic keys, JWTs, and private key blocks. Not a substitute for a dedicated secrets scanner on sensitive repos.
@@ -1350,12 +1412,12 @@ src/agentpack/
 
 ## Roadmap
 
-Next release target: **0.2.0 = benchmark + recall release**.
+Next release target: **0.3.0 = public proof + npm publish hardening**.
 
-- Expand public source-checkout fixtures and publish reproducible `benchmark --sample-fixtures --compare --misses` output.
-- Raise recall on real historical tasks while keeping token precision healthy; target 60%+ recall, 50%+ token precision, and balanced packs under 25k tokens.
-- Improve second-pass expansion beyond current imports, reverse imports, related tests, historical co-change, and workspace hints with framework route/service/schema pairs.
-- Make MCP pull flows more prominent so agents can ask for `explain_file`, `get_related_files`, and `get_delta_context` instead of relying only on a static startup pack.
+- Expand the public real-repo suite beyond the current curated Pallets smoke set.
+- Keep recall gains measured with `--prove-targets`; target 60%+ recall, 50%+ token precision, and task packs under 25k tokens.
+- Extend second-pass expansion with framework route/service/schema pairs once benchmark misses prove the pattern.
+- Make npm publishing reliable by adding `NPM_TOKEN` and rerunning the npm release workflow.
 - Keep integration contracts stable across Claude, Cursor, Windsurf, Codex, Antigravity, and Generic before any 1.0 work.
 
 ---

{agentpack_cli-0.2.0 → agentpack_cli-0.2.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "agentpack-cli"
-version = "0.2.0"
+version = "0.2.2"
 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.2.0 → agentpack_cli-0.2.2}/src/agentpack/__init__.py

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

{agentpack_cli-0.2.0 → agentpack_cli-0.2.2}/src/agentpack/analysis/dependency_graph.py

@@ -37,8 +37,9 @@ def build(
         if summaries and fi.path in summaries:
             cached_imports = summaries[fi.path].get("imports", [])
             if cached_imports:
-                graph.nodes[fi.path].imports = cached_imports
-                for dep in cached_imports:
+                resolved_cached = _resolve_imports(fi.path, fi.language, cached_imports, root, path_set)
+                graph.nodes[fi.path].imports = resolved_cached
+                for dep in resolved_cached:
                     if dep in graph:
                         graph.nodes[dep].imported_by.append(fi.path)
                 continue
@@ -58,19 +59,7 @@ def build(
         elif lang in ("java", "kotlin"):
             raw_imports = java_imports(fi.abs_path, cached)
 
-        resolved: list[str] = []
-        for imp in raw_imports:
-            if imp.startswith("."):
-                if lang == "python":
-                    r = py_resolve(fi.path, imp, root)
-                elif lang in ("javascript", "typescript"):
-                    r = js_resolve(fi.path, imp, root)
-                else:
-                    r = None
-                if r and r in path_set:
-                    resolved.append(r)
-            else:
-                resolved.append(imp)
+        resolved = _resolve_imports(fi.path, lang, raw_imports, root, path_set)
 
         graph.nodes[fi.path].imports = resolved
         for dep in resolved:
@@ -78,3 +67,26 @@ def build(
                 graph.nodes[dep].imported_by.append(fi.path)
 
     return graph
+
+
+def _resolve_imports(
+    importer: str,
+    language: str | None,
+    imports: list[str],
+    root: Path,
+    path_set: set[str],
+) -> list[str]:
+    resolved: list[str] = []
+    for imp in imports:
+        if imp.startswith("."):
+            if language == "python":
+                r = py_resolve(importer, imp, root)
+            elif language in ("javascript", "typescript"):
+                r = js_resolve(importer, imp, root)
+            else:
+                r = None
+            if r and r in path_set:
+                resolved.append(r)
+        else:
+            resolved.append(imp)
+    return resolved

{agentpack_cli-0.2.0 → agentpack_cli-0.2.2}/src/agentpack/analysis/ranking.py

@@ -695,6 +695,96 @@ def boost_recall_neighbors(
     return result
 
 
+def boost_second_pass_expansion(
+    scored: list[tuple[FileInfo, float, list[str]]],
+    dep_graph: DependencyGraph,
+    keywords: set[str] | dict[str, float],
+    weights: ScoringWeights | None = None,
+    *,
+    seed_limit: int = 10,
+    max_boosts: int = 32,
+) -> list[tuple[FileInfo, float, list[str]]]:
+    """Boost guarded two-hop neighbours around strong first-pass seeds.
+
+    This is deliberately conservative: it only boosts files that are close to a
+    strong seed and share task/domain signal, are paired tests, or are config
+    files. That raises recall for adjacent implementation files without turning
+    broad task wording into repo-wide expansion.
+    """
+    if not scored:
+        return scored
+    w = weights or _DEFAULT_WEIGHTS
+    path_map = {fi.path: (fi, score, reasons) for fi, score, reasons in scored}
+    keyword_tokens = set(_keyword_token_weights(keywords)) - _PATH_NOISE_TOKENS
+
+    seed_paths = [
+        fi.path
+        for fi, score, reasons in sorted(scored, key=lambda row: row[1], reverse=True)
+        if score >= 100
+        or any(
+            reason.startswith((
+                "modified",
+                "staged",
+                "workspace match",
+                "cross-layer related",
+                "recall neighbor",
+                "historically co-changed",
+            ))
+            for reason in reasons
+        )
+    ][:seed_limit]
+    if not seed_paths:
+        return scored
+
+    boosts: dict[str, tuple[float, str, str]] = {}
+
+    def neighbours(path: str) -> set[str]:
+        node = dep_graph.get(path)
+        return {p for p in (*node.imports, *node.imported_by, *node.tests) if p in path_map and p != path}
+
+    for seed in seed_paths:
+        seed_domains = _domain_tokens(seed) | keyword_tokens
+        first_hop = neighbours(seed)
+        second_hop = {candidate for hop in first_hop for candidate in neighbours(hop)}
+        for candidate in sorted(second_hop - {seed} - first_hop):
+            fi, _score, _reasons = path_map[candidate]
+            if fi.ignored or fi.binary:
+                continue
+            candidate_domains = _domain_tokens(candidate)
+            is_test_pair = _is_test_file(candidate) and (
+                any(_test_matches_source(candidate, hop) for hop in first_hop | {seed})
+                or any(_test_matches_source(candidate, hop) for hop in seed_domains)
+            )
+            has_domain_signal = bool(candidate_domains & seed_domains)
+            has_config_signal = _is_config_file(candidate) and bool(seed_domains)
+            if not (is_test_pair or has_domain_signal or has_config_signal):
+                continue
+            amount = w.recall_neighbor * 0.5
+            label = "second-pass related test" if is_test_pair else "second-pass recall neighbor"
+            if has_domain_signal:
+                amount += 4
+            current = boosts.get(candidate)
+            if current is None or amount > current[0]:
+                boosts[candidate] = (amount, seed, label)
+
+    if not boosts:
+        return scored
+    keep = {
+        path: value
+        for path, value in sorted(boosts.items(), key=lambda item: item[1][0], reverse=True)[:max_boosts]
+    }
+
+    result: list[tuple[FileInfo, float, list[str]]] = []
+    for fi, score, reasons in scored:
+        boost = keep.get(fi.path)
+        if boost:
+            amount, seed, label = boost
+            score += amount
+            reasons = reasons + [f"{label} of {seed}"]
+        result.append((fi, score, reasons))
+    return result
+
+
 def boost_monorepo_workspaces(
     scored: list[tuple[FileInfo, float, list[str]]],
     *,