agentpack-cli 0.3.4__tar.gz → 0.3.8__tar.gz

agentpack_cli-0.3.4/README.md → agentpack_cli-0.3.8/PKG-INFO

@@ -1,3 +1,42 @@
+Metadata-Version: 2.4
+Name: agentpack-cli
+Version: 0.3.8
+Summary: Local context engine for AI coding agents that ranks relevant files and builds task-focused context packs.
+License: MIT
+License-File: LICENSE
+Keywords: ai,ai-coding-agents,antigravity,ci,codex,context,context-engine,context-packing,cursor,developer-tools,llm,mcp,packing,prompt-context,repo-analysis,windsurf
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+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: Topic :: Software Development :: Build Tools
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: pathspec>=0.12.1
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: tiktoken>=0.7.0
+Requires-Dist: tomli-w>=1.0.0
+Requires-Dist: tomli>=2.0.0; python_version < '3.11'
+Requires-Dist: typer>=0.12.0
+Provides-Extra: all
+Requires-Dist: mcp>=1.0.0; extra == 'all'
+Requires-Dist: watchdog>=4.0.0; extra == 'all'
+Provides-Extra: dev
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Requires-Dist: tomli>=2.0.0; (python_version < '3.11') and extra == 'dev'
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.0.0; extra == 'mcp'
+Provides-Extra: watch
+Requires-Dist: watchdog>=4.0.0; extra == 'watch'
+Description-Content-Type: text/markdown
+
 # AgentPack
 
 [![PyPI version](https://img.shields.io/pypi/v/agentpack-cli.svg)](https://pypi.org/project/agentpack-cli/)
@@ -7,7 +46,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.3.4).** Works, tested, used in real sessions. Python and JavaScript/TypeScript are the best-supported languages. Public benchmark proof exists for the current suite, but broader repo coverage is still growing. API may change before 1.0.
+> **Status: alpha (v0.3.8).** Works, tested, used in real sessions. Python and JavaScript/TypeScript are the best-supported languages. Public benchmark proof exists for the current suite, but broader repo coverage is still growing. 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.
 
@@ -38,7 +77,7 @@ Use AgentPack when a repo is too large to paste and you want faster, more consis
 - **Budget-aware compression**: emits `full`, `diff`, `symbols`, `skeleton`, or `summary` views instead of all-or-nothing file dumps.
 - **Local code intelligence**: extracts roles, domains, entrypoints, definitions, dependencies, env reads, side effects, and external systems using static analysis.
 - **Semantic repo map**: adds a compact module-level map before file context so agents orient faster.
-- **Freshness and deltas**: records task source, git state, snapshot hashes, selected-file deltas, and stale-context warnings.
+- **Freshness and deltas**: records task source, git state, snapshot hashes, selected-file deltas, stale-context warnings, MCP auto-refresh signals, and a machine-readable `agentpack:freshness` block in markdown fallback artifacts.
 - **Agent integrations**: installs Claude Code, Cursor, Windsurf, Codex, Antigravity, VS Code tasks, git hooks, and MCP configuration.
 - **Local and measurable**: no API calls for scan, summarize, rank, pack, stats, or benchmark; quality is measured with expected-file evals.
 
@@ -109,7 +148,19 @@ 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:
+This creates `.agentpack/` state, installs the requested agent integration, seeds `.agentignore` with safe defaults, imports obvious generated/noisy rules from git ignore sources, generates a ranked context pack, and writes the adapter output for that agent.
+
+Task text matters. Good task text names the concrete feature, route, service, or file you are about to change. Bad task text uses repo-meta words like `improve context`, `pack quality`, `stats`, or `ignore`, which can pull README or tool internals by keyword.
+
+```bash
+# good
+printf '%s\n' "fix billing webhook retry handling in app/api/billing/route.ts" > .agentpack/task.md
+
+# too broad
+printf '%s\n' "improve context pack quality from stats" > .agentpack/task.md
+```
+
+For active local work, keep context fresh with:
 
 ```bash
 agentpack watch
@@ -149,7 +200,7 @@ AgentPack is best treated as a **ranked starting map**. It should reduce repeate
 | Pack time | Seconds on a warm cache; first summarize pass is slower |
 | Recall | Expected files appear near the top; validate with `agentpack benchmark --misses` |
 | Precision | Good enough to reduce exploration; summaries and repo maps may still include noise |
-| Freshness | Stale packs are clearly marked by task, git, and snapshot checks |
+| Freshness | Task or repo-stale MCP reads auto-refresh; static packs are clearly marked by task, git, and snapshot checks |
 
 Use real repo evals instead of trusting compression numbers:
 
@@ -202,17 +253,44 @@ 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.
 
+If top includes look noisy:
+
+1. Rewrite `.agentpack/task.md` with concrete domain nouns, entrypoints, or filenames.
+2. Re-pack and re-check `agentpack stats`.
+3. If generated output still dominates, add that path to `.agentignore` or run `agentpack ignore sync`.
+4. Use `agentpack explain --file <path>` on repeat offenders before changing scoring.
+
+`.agentignore` is for AgentPack ranking noise, not general git hygiene. `agentpack init` seeds it with safe defaults and imports obvious generated/noisy entries from the root `.gitignore`, nested `.gitignore` files, `.git/info/exclude`, and your global git ignore when they look safe to carry over. You should still add repo-specific outputs such as deploy artifacts, exports, or generated SDK folders when they are not useful context.
+
+When ignore sources change later, re-sync with:
+
+```bash
+agentpack ignore sync
+agentpack ignore sync --dry-run
+agentpack ignore sync --check
+```
+
 ## 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.
+2. Call `get_context()` when you need the latest pack. It blocks for one refresh if `.agentpack/task.md` or the repo snapshot changed since the last pack, and otherwise prepends a freshness header.
 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.
 
+Markdown context files are fallback artifacts for CI, logs, manual review, and non-MCP agents. Every rendered pack includes a machine-readable `agentpack:freshness` comment; agents should treat `active_context: mcp` as the preferred path and refresh before using markdown when `refresh_required: true`.
+
+For non-MCP agents, use the executable guard before editing:
+
+```bash
+agentpack guard --agent auto --repair-stale --refresh-context
+```
+
+`guard` checks pack freshness, task freshness, repo snapshot freshness, and installed agent rules/hooks. With `--repair-stale --refresh-context`, it repairs stale AgentPack rule files and refreshes missing or stale context before returning success. `agentpack pack` also self-heals stale AgentPack rule blocks for the active agent, so older installs that still run `pack` get upgraded opportunistically.
+
 ## Before / After Agent Behavior
 
 Without AgentPack:
@@ -326,7 +404,7 @@ _*`--agent generic` outputs standard markdown. Claude adapter has richer instruc
 
 - AgentPack cannot intercept prompts inside IDEs — Cursor/Windsurf rely on rules being followed.
 - Claude wrapper (`agentpack claude`) is the most deterministic integration.
-- If the task changes drastically mid-session, context needs one refresh cycle.
+- If the task changes drastically mid-session, Claude hooks update `.agentpack/task.md` and block once for fresh hints; plain repo edits still use background repack to keep prompts fast.
 - AgentPack-selected files are ranked starting points, not absolute truth.
 
 ---
@@ -694,6 +772,36 @@ agentpack repair --agent all     # repair every supported integration
 
 ---
 
+### `agentpack guard`
+
+Run the pre-edit safety gate an agent can execute instead of only reading instructions.
+
+```bash
+agentpack guard                                      # check current agent + context
+agentpack guard --refresh-context                   # refresh stale/missing context
+agentpack guard --agent codex --repair-stale        # repair stale Codex rules/hooks
+agentpack guard --agent auto --repair-stale --refresh-context
+```
+
+This is the strongest non-native enforcement AgentPack can provide: tools that run commands get a failing exit code when context is unsafe, and an automatic repair/refresh path when allowed.
+
+---
+
+### `agentpack migrate`
+
+Repair stale AgentPack integrations across existing repos after upgrading.
+
+```bash
+agentpack migrate --path . --agent auto
+agentpack migrate --path ~/src --discover --agent all
+agentpack migrate --path ~/src --discover --agent codex --refresh-context
+agentpack migrate --path ~/src --discover --dry-run
+```
+
+Use this when older repos still have stale `.cursorrules`, `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `.windsurfrules`, VS Code tasks, or hook files. `--discover` scans nested repo folders, `--dry-run` reports without writing, and `--refresh-context` regenerates packs after repair.
+
+---
+
 ### `agentpack summarize`
 
 Build or refresh the offline summary cache. **No API calls, ever.**
@@ -777,6 +885,20 @@ agentpack quickstart --task "fix auth token expiry" --write
 
 ---
 
+### `agentpack ignore sync`
+
+Refresh imported generated/noisy rules inside `.agentignore` without touching your manual entries.
+
+```bash
+agentpack ignore sync
+agentpack ignore sync --dry-run
+agentpack ignore sync --check
+```
+
+Use this after editing `.gitignore`, nested workspace ignores, or `.git/info/exclude`. `doctor` also warns when the imported `.agentignore` block is stale.
+
+---
+
 ### `agentpack watch`
 
 Watch for file and task changes, refresh context automatically.
@@ -842,18 +964,38 @@ Register in Claude Code settings (`~/.claude/settings.json`):
 |---|---|
 | `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. |
+| `get_context()` | Return the latest pack. If `.agentpack/task.md` or the repo snapshot differs from the packed metadata, it auto-refreshes before returning; otherwise it prepends a freshness header. |
 | `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. |
 | `get_related_files(path, depth)` | Return import-graph neighbours and related tests for a file. |
 | `get_delta_context(max_files)` | Return the latest selected-file delta plus top current selected files. Useful for cheap prompt-time refresh checks. |
 | `get_stats()` | Return latest pack stats, savings, selection quality, excluded files, and benchmark-style signals. |
 
-**Staleness detection:** `get_context()` compares the snapshot hash from when the pack was built against the current repo snapshot. If files changed since last pack, it prepends:
+**Staleness detection:** `get_context()` compares the current task file, snapshot hash, and git state against the latest pack metadata. If `.agentpack/task.md` or the repo snapshot changed, it blocks for a fresh pack and prepends:
+
 ```
-> **Stale context** — repo changed since last pack (generated: ...). Run pack_context() to refresh.
+> Context auto-refreshed because .agentpack/task.md differs from the packed task ...
 ```
 
+If auto-refresh fails, it falls back to the cached context with a loud stale warning and asks the agent to call `pack_context()` again.
+
+Static markdown cannot refresh itself, so rendered packs include a machine-readable fallback header:
+
+```text
+<!-- agentpack:freshness
+{
+  "active_context": "mcp",
+  "fallback_context": "markdown",
+  "refresh_required": false,
+  "mcp_refresh_tool": "agentpack_get_context",
+  "cli_refresh_command": "agentpack pack --task auto",
+  "guard_command": "agentpack guard --agent auto --repair-stale --refresh-context"
+}
+-->
+```
+
+Claude prompt hooks also block once on clear task switches so first-turn hints are fresh. Non-MCP rule files and VS Code folder-open tasks use `agentpack guard --repair-stale --refresh-context` as the executable fallback. To prefer lower latency over first-turn freshness, set `blocking_task_refresh = false` under `[hooks]` in `.agentpack/config.toml`.
+
 **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.
@@ -1405,6 +1547,13 @@ src/agentpack/
     vscode_tasks.py            # install/remove .vscode/tasks.json entries
     global_install.py          # global: git template hooks + shell rc hook
 
+  ../native-integrations/       # tracked native-enforcement skeletons and blocked-status stubs
+    status.json                 # machine-readable native host enforcement status
+    cursor-extension/           # VS Code-style Cursor guard skeleton
+    windsurf-extension/         # VS Code-style Windsurf guard skeleton
+    claude-native/              # blocked native stub pending mandatory host API
+    codex-native/               # blocked native stub pending mandatory host API
+
   renderers/
     markdown.py                # renders pre-redacted ContextPack to markdown, including freshness/map/delta
     compact.py                 # compact protocol format for session context files
@@ -1457,7 +1606,8 @@ 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 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.
+- **MCP is the interactive path**: `start_task()` writes task state and returns a fresh pack, while `get_context()` auto-refreshes stale task or repo-snapshot context and `get_delta_context()`, `explain_file()`, and `get_related_files()` let agents pull follow-up context on demand.
+- **Native enforcement status is explicit**: `native-integrations/status.json` tracks host skeletons and blockers. Entries stay `guarded`, not `enforced`, until a host exposes mandatory pre-edit/pre-tool hooks that can block failed guard checks.
 
 ---
 
@@ -1482,6 +1632,7 @@ src/agentpack/
 - **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.
 - **Token estimates**: uses tiktoken `cl100k_base` — approximate, not exact for Claude's billing.
 - **Large repos (>5k files)**: global auto-bootstrap is skipped for repos over 5,000 files to avoid hangs. Run `agentpack init` explicitly in large codebases.
+- **Native hard enforcement**: tracked skeletons exist under `native-integrations/`, but all hosts remain `guarded` until their native APIs can guarantee mandatory pre-edit/pre-tool execution and block failed guard checks.
 
 ---
 

agentpack_cli-0.3.4/PKG-INFO → agentpack_cli-0.3.8/README.md

@@ -1,42 +1,3 @@
-Metadata-Version: 2.4
-Name: agentpack-cli
-Version: 0.3.4
-Summary: Local context engine for AI coding agents that ranks relevant files and builds task-focused context packs.
-License: MIT
-License-File: LICENSE
-Keywords: ai,ai-coding-agents,antigravity,ci,claude,claude-code,codex,context,context-engine,context-packing,cursor,developer-tools,llm,mcp,packing,prompt-context,repo-analysis,windsurf
-Classifier: Development Status :: 3 - Alpha
-Classifier: Intended Audience :: Developers
-Classifier: License :: OSI Approved :: MIT License
-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: Topic :: Software Development :: Build Tools
-Classifier: Topic :: Software Development :: Libraries :: Python Modules
-Requires-Python: >=3.10
-Requires-Dist: pathspec>=0.12.1
-Requires-Dist: pydantic>=2.0.0
-Requires-Dist: rich>=13.0.0
-Requires-Dist: tiktoken>=0.7.0
-Requires-Dist: tomli-w>=1.0.0
-Requires-Dist: tomli>=2.0.0; python_version < '3.11'
-Requires-Dist: typer>=0.12.0
-Provides-Extra: all
-Requires-Dist: mcp>=1.0.0; extra == 'all'
-Requires-Dist: watchdog>=4.0.0; extra == 'all'
-Provides-Extra: dev
-Requires-Dist: mypy; extra == 'dev'
-Requires-Dist: pytest; extra == 'dev'
-Requires-Dist: pytest-cov; extra == 'dev'
-Requires-Dist: ruff; extra == 'dev'
-Requires-Dist: tomli>=2.0.0; (python_version < '3.11') and extra == 'dev'
-Provides-Extra: mcp
-Requires-Dist: mcp>=1.0.0; extra == 'mcp'
-Provides-Extra: watch
-Requires-Dist: watchdog>=4.0.0; extra == 'watch'
-Description-Content-Type: text/markdown
-
 # AgentPack
 
 [![PyPI version](https://img.shields.io/pypi/v/agentpack-cli.svg)](https://pypi.org/project/agentpack-cli/)
@@ -46,7 +7,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.3.4).** Works, tested, used in real sessions. Python and JavaScript/TypeScript are the best-supported languages. Public benchmark proof exists for the current suite, but broader repo coverage is still growing. API may change before 1.0.
+> **Status: alpha (v0.3.8).** Works, tested, used in real sessions. Python and JavaScript/TypeScript are the best-supported languages. Public benchmark proof exists for the current suite, but broader repo coverage is still growing. 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.
 
@@ -77,7 +38,7 @@ Use AgentPack when a repo is too large to paste and you want faster, more consis
 - **Budget-aware compression**: emits `full`, `diff`, `symbols`, `skeleton`, or `summary` views instead of all-or-nothing file dumps.
 - **Local code intelligence**: extracts roles, domains, entrypoints, definitions, dependencies, env reads, side effects, and external systems using static analysis.
 - **Semantic repo map**: adds a compact module-level map before file context so agents orient faster.
-- **Freshness and deltas**: records task source, git state, snapshot hashes, selected-file deltas, and stale-context warnings.
+- **Freshness and deltas**: records task source, git state, snapshot hashes, selected-file deltas, stale-context warnings, MCP auto-refresh signals, and a machine-readable `agentpack:freshness` block in markdown fallback artifacts.
 - **Agent integrations**: installs Claude Code, Cursor, Windsurf, Codex, Antigravity, VS Code tasks, git hooks, and MCP configuration.
 - **Local and measurable**: no API calls for scan, summarize, rank, pack, stats, or benchmark; quality is measured with expected-file evals.
 
@@ -148,7 +109,19 @@ 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:
+This creates `.agentpack/` state, installs the requested agent integration, seeds `.agentignore` with safe defaults, imports obvious generated/noisy rules from git ignore sources, generates a ranked context pack, and writes the adapter output for that agent.
+
+Task text matters. Good task text names the concrete feature, route, service, or file you are about to change. Bad task text uses repo-meta words like `improve context`, `pack quality`, `stats`, or `ignore`, which can pull README or tool internals by keyword.
+
+```bash
+# good
+printf '%s\n' "fix billing webhook retry handling in app/api/billing/route.ts" > .agentpack/task.md
+
+# too broad
+printf '%s\n' "improve context pack quality from stats" > .agentpack/task.md
+```
+
+For active local work, keep context fresh with:
 
 ```bash
 agentpack watch
@@ -188,7 +161,7 @@ AgentPack is best treated as a **ranked starting map**. It should reduce repeate
 | Pack time | Seconds on a warm cache; first summarize pass is slower |
 | Recall | Expected files appear near the top; validate with `agentpack benchmark --misses` |
 | Precision | Good enough to reduce exploration; summaries and repo maps may still include noise |
-| Freshness | Stale packs are clearly marked by task, git, and snapshot checks |
+| Freshness | Task or repo-stale MCP reads auto-refresh; static packs are clearly marked by task, git, and snapshot checks |
 
 Use real repo evals instead of trusting compression numbers:
 
@@ -241,17 +214,44 @@ 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.
 
+If top includes look noisy:
+
+1. Rewrite `.agentpack/task.md` with concrete domain nouns, entrypoints, or filenames.
+2. Re-pack and re-check `agentpack stats`.
+3. If generated output still dominates, add that path to `.agentignore` or run `agentpack ignore sync`.
+4. Use `agentpack explain --file <path>` on repeat offenders before changing scoring.
+
+`.agentignore` is for AgentPack ranking noise, not general git hygiene. `agentpack init` seeds it with safe defaults and imports obvious generated/noisy entries from the root `.gitignore`, nested `.gitignore` files, `.git/info/exclude`, and your global git ignore when they look safe to carry over. You should still add repo-specific outputs such as deploy artifacts, exports, or generated SDK folders when they are not useful context.
+
+When ignore sources change later, re-sync with:
+
+```bash
+agentpack ignore sync
+agentpack ignore sync --dry-run
+agentpack ignore sync --check
+```
+
 ## 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.
+2. Call `get_context()` when you need the latest pack. It blocks for one refresh if `.agentpack/task.md` or the repo snapshot changed since the last pack, and otherwise prepends a freshness header.
 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.
 
+Markdown context files are fallback artifacts for CI, logs, manual review, and non-MCP agents. Every rendered pack includes a machine-readable `agentpack:freshness` comment; agents should treat `active_context: mcp` as the preferred path and refresh before using markdown when `refresh_required: true`.
+
+For non-MCP agents, use the executable guard before editing:
+
+```bash
+agentpack guard --agent auto --repair-stale --refresh-context
+```
+
+`guard` checks pack freshness, task freshness, repo snapshot freshness, and installed agent rules/hooks. With `--repair-stale --refresh-context`, it repairs stale AgentPack rule files and refreshes missing or stale context before returning success. `agentpack pack` also self-heals stale AgentPack rule blocks for the active agent, so older installs that still run `pack` get upgraded opportunistically.
+
 ## Before / After Agent Behavior
 
 Without AgentPack:
@@ -365,7 +365,7 @@ _*`--agent generic` outputs standard markdown. Claude adapter has richer instruc
 
 - AgentPack cannot intercept prompts inside IDEs — Cursor/Windsurf rely on rules being followed.
 - Claude wrapper (`agentpack claude`) is the most deterministic integration.
-- If the task changes drastically mid-session, context needs one refresh cycle.
+- If the task changes drastically mid-session, Claude hooks update `.agentpack/task.md` and block once for fresh hints; plain repo edits still use background repack to keep prompts fast.
 - AgentPack-selected files are ranked starting points, not absolute truth.
 
 ---
@@ -733,6 +733,36 @@ agentpack repair --agent all     # repair every supported integration
 
 ---
 
+### `agentpack guard`
+
+Run the pre-edit safety gate an agent can execute instead of only reading instructions.
+
+```bash
+agentpack guard                                      # check current agent + context
+agentpack guard --refresh-context                   # refresh stale/missing context
+agentpack guard --agent codex --repair-stale        # repair stale Codex rules/hooks
+agentpack guard --agent auto --repair-stale --refresh-context
+```
+
+This is the strongest non-native enforcement AgentPack can provide: tools that run commands get a failing exit code when context is unsafe, and an automatic repair/refresh path when allowed.
+
+---
+
+### `agentpack migrate`
+
+Repair stale AgentPack integrations across existing repos after upgrading.
+
+```bash
+agentpack migrate --path . --agent auto
+agentpack migrate --path ~/src --discover --agent all
+agentpack migrate --path ~/src --discover --agent codex --refresh-context
+agentpack migrate --path ~/src --discover --dry-run
+```
+
+Use this when older repos still have stale `.cursorrules`, `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `.windsurfrules`, VS Code tasks, or hook files. `--discover` scans nested repo folders, `--dry-run` reports without writing, and `--refresh-context` regenerates packs after repair.
+
+---
+
 ### `agentpack summarize`
 
 Build or refresh the offline summary cache. **No API calls, ever.**
@@ -816,6 +846,20 @@ agentpack quickstart --task "fix auth token expiry" --write
 
 ---
 
+### `agentpack ignore sync`
+
+Refresh imported generated/noisy rules inside `.agentignore` without touching your manual entries.
+
+```bash
+agentpack ignore sync
+agentpack ignore sync --dry-run
+agentpack ignore sync --check
+```
+
+Use this after editing `.gitignore`, nested workspace ignores, or `.git/info/exclude`. `doctor` also warns when the imported `.agentignore` block is stale.
+
+---
+
 ### `agentpack watch`
 
 Watch for file and task changes, refresh context automatically.
@@ -881,18 +925,38 @@ Register in Claude Code settings (`~/.claude/settings.json`):
 |---|---|
 | `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. |
+| `get_context()` | Return the latest pack. If `.agentpack/task.md` or the repo snapshot differs from the packed metadata, it auto-refreshes before returning; otherwise it prepends a freshness header. |
 | `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. |
 | `get_related_files(path, depth)` | Return import-graph neighbours and related tests for a file. |
 | `get_delta_context(max_files)` | Return the latest selected-file delta plus top current selected files. Useful for cheap prompt-time refresh checks. |
 | `get_stats()` | Return latest pack stats, savings, selection quality, excluded files, and benchmark-style signals. |
 
-**Staleness detection:** `get_context()` compares the snapshot hash from when the pack was built against the current repo snapshot. If files changed since last pack, it prepends:
+**Staleness detection:** `get_context()` compares the current task file, snapshot hash, and git state against the latest pack metadata. If `.agentpack/task.md` or the repo snapshot changed, it blocks for a fresh pack and prepends:
+
 ```
-> **Stale context** — repo changed since last pack (generated: ...). Run pack_context() to refresh.
+> Context auto-refreshed because .agentpack/task.md differs from the packed task ...
 ```
 
+If auto-refresh fails, it falls back to the cached context with a loud stale warning and asks the agent to call `pack_context()` again.
+
+Static markdown cannot refresh itself, so rendered packs include a machine-readable fallback header:
+
+```text
+<!-- agentpack:freshness
+{
+  "active_context": "mcp",
+  "fallback_context": "markdown",
+  "refresh_required": false,
+  "mcp_refresh_tool": "agentpack_get_context",
+  "cli_refresh_command": "agentpack pack --task auto",
+  "guard_command": "agentpack guard --agent auto --repair-stale --refresh-context"
+}
+-->
+```
+
+Claude prompt hooks also block once on clear task switches so first-turn hints are fresh. Non-MCP rule files and VS Code folder-open tasks use `agentpack guard --repair-stale --refresh-context` as the executable fallback. To prefer lower latency over first-turn freshness, set `blocking_task_refresh = false` under `[hooks]` in `.agentpack/config.toml`.
+
 **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.
@@ -1444,6 +1508,13 @@ src/agentpack/
     vscode_tasks.py            # install/remove .vscode/tasks.json entries
     global_install.py          # global: git template hooks + shell rc hook
 
+  ../native-integrations/       # tracked native-enforcement skeletons and blocked-status stubs
+    status.json                 # machine-readable native host enforcement status
+    cursor-extension/           # VS Code-style Cursor guard skeleton
+    windsurf-extension/         # VS Code-style Windsurf guard skeleton
+    claude-native/              # blocked native stub pending mandatory host API
+    codex-native/               # blocked native stub pending mandatory host API
+
   renderers/
     markdown.py                # renders pre-redacted ContextPack to markdown, including freshness/map/delta
     compact.py                 # compact protocol format for session context files
@@ -1496,7 +1567,8 @@ 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 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.
+- **MCP is the interactive path**: `start_task()` writes task state and returns a fresh pack, while `get_context()` auto-refreshes stale task or repo-snapshot context and `get_delta_context()`, `explain_file()`, and `get_related_files()` let agents pull follow-up context on demand.
+- **Native enforcement status is explicit**: `native-integrations/status.json` tracks host skeletons and blockers. Entries stay `guarded`, not `enforced`, until a host exposes mandatory pre-edit/pre-tool hooks that can block failed guard checks.
 
 ---
 
@@ -1521,6 +1593,7 @@ src/agentpack/
 - **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.
 - **Token estimates**: uses tiktoken `cl100k_base` — approximate, not exact for Claude's billing.
 - **Large repos (>5k files)**: global auto-bootstrap is skipped for repos over 5,000 files to avoid hangs. Run `agentpack init` explicitly in large codebases.
+- **Native hard enforcement**: tracked skeletons exist under `native-integrations/`, but all hosts remain `guarded` until their native APIs can guarantee mandatory pre-edit/pre-tool execution and block failed guard checks.
 
 ---
 

{agentpack_cli-0.3.4 → agentpack_cli-0.3.8}/pyproject.toml

@@ -1,11 +1,11 @@
 [project]
 name = "agentpack-cli"
-version = "0.3.4"
+version = "0.3.8"
 description = "Local context engine for AI coding agents that ranks relevant files and builds task-focused context packs."
 readme = "README.md"
 requires-python = ">=3.10"
 license = {text = "MIT"}
-keywords = ["ai-coding-agents", "developer-tools", "repo-analysis", "context-engine", "context-packing", "prompt-context", "mcp", "ci", "claude-code", "codex", "cursor", "windsurf", "antigravity", "ai", "llm", "context", "packing", "claude"]
+keywords = ["ai-coding-agents", "developer-tools", "repo-analysis", "context-engine", "context-packing", "prompt-context", "mcp", "ci", "codex", "cursor", "windsurf", "antigravity", "ai", "llm", "context", "packing"]
 classifiers = [
   "Development Status :: 3 - Alpha",
   "Intended Audience :: Developers",

{agentpack_cli-0.3.4 → agentpack_cli-0.3.8}/src/agentpack/__init__.py

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

{agentpack_cli-0.3.4 → agentpack_cli-0.3.8}/src/agentpack/analysis/ranking.py

@@ -21,10 +21,12 @@ _GENERIC_TASK_TERMS = {
     "add", "added", "change", "changed", "changes", "clean", "cleanup",
     "code", "commit", "context", "debug", "dev", "development", "doc",
     "docs", "eval", "evals", "feature", "fix", "freshness", "general",
-    "impl", "implement", "implementation", "improve", "issue", "metric", "metrics",
-    "noise", "noisy", "package", "pack", "packs", "release", "repo",
-    "source", "sync", "task", "tasks", "test", "tests", "update", "use",
-    "useful", "usefulness", "version", "workflow", "workflows",
+    "gap", "gaps", "generic", "impl", "implement", "implementation", "improve",
+    "issue", "metric", "metrics", "noise", "noisy", "package", "pack", "packs",
+    "quality", "release", "remaining", "repo", "root", "rule", "rules",
+    "source", "stat", "stats", "sync", "task", "tasks", "test", "tests",
+    "text", "update", "use", "useful", "usefulness", "version", "visibility",
+    "workflow", "workflows", "wording",
 }
 
 _CONCEPT_MAP: dict[str, frozenset[str]] = {