ctx-packr 0.1.1__tar.gz

ctx_packr-0.1.1/.gitignore

@@ -0,0 +1,18 @@
+__pycache__/
+*.pyc
+
+# Packaging build artifacts
+build/
+dist/
+*.egg-info/
+
+# Virtual environments
+.venv/
+
+# uv's resolved environment lock. Not committed: this is a library, so users
+# resolve their own versions. Delete this line if you ever want it pinned.
+uv.lock
+
+# Local run output
+bundle*.md
+manifest.json

ctx_packr-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Muhammad Shaheer
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ctx_packr-0.1.1/PKG-INFO

@@ -0,0 +1,166 @@
+Metadata-Version: 2.5
+Name: ctx-packr
+Version: 0.1.1
+Summary: A stdlib-only CLI that packs the most relevant files of a codebase into a token-budgeted markdown bundle
+Project-URL: Homepage, https://github.com/shaheersaifi07-prog/ctxpack
+Project-URL: Repository, https://github.com/shaheersaifi07-prog/ctxpack
+Project-URL: Issues, https://github.com/shaheersaifi07-prog/ctxpack/issues
+Author: shaheersaifi07-prog
+License-Expression: MIT
+License-File: LICENSE
+Keywords: cli,codebase,context,llm,packing,tokens
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+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 :: Pre-processors
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# `ctx-packr`
+
+A stdlib-only Python CLI that selects the most relevant files from a codebase for a given task and packs them into a token-budgeted markdown bundle.
+
+## Why `ctx-packr`?
+
+Several tools occupy nearby space. The difference is not quality — it is which part of
+the problem each one solves.
+
+| Tool | Approach | What it lacks vs `ctx-packr` |
+|---|---|---|
+| `ctxpack` | Config-driven file selection, with `init` and `watch` commands | No relevance ranking against a stated task |
+| `context-packer` | Smart filtering of build artifacts and binaries, plus a visual project tree | No relevance ranking against a stated task |
+| `llm-ctxpack` | Priority-based packing into a token budget | Does not walk a codebase; the caller supplies the chunks |
+| `contextcram` | Priority-based packing into a token budget | Does not walk a codebase; the caller supplies the chunks |
+| `ctx-pack` (Rust) | Versioned bidirectional patch/replace | Solves a different problem — not context packing |
+
+`ctx-packr` combines four things that otherwise appear separately: it walks a real
+codebase, ranks what it finds against a specific stated task, enforces a hard token
+budget, and has zero runtime dependencies. Ranking uses camelCase-aware keyword
+scoring, with bonuses for entry-point filenames and for files whose `def`/`class` names
+match the task, offset by a penalty for directory depth. When the budget is too small
+for the full bundle, the output degrades step by step — dropping the contents table,
+then the summary header — rather than failing.
+
+*Comparison reflects these projects as of September 2026.*
+
+## Requirements
+
+- Python 3.10+
+- No third-party packages — `ctx-packr` has zero runtime dependencies
+
+## Install
+
+```bash
+pip install ctx-packr
+```
+
+That puts a `ctx-packr` command on your PATH:
+
+```bash
+ctx-packr --path sample --task "understand the auth flow" --budget 2000 --out bundle.md --manifest manifest.json
+```
+
+> **Note on naming.** You install `ctx-packr`, but the importable module is `ctxpack`:
+>
+> ```python
+> import ctxpack
+> ```
+>
+> The two differ because a hyphen is not legal in a Python identifier. This is the
+> same split used by `beautifulsoup4` → `bs4` and `python-dateutil` → `dateutil`.
+
+## Quick Start (from a clone, no install)
+
+```bash
+git clone https://github.com/shaheersaifi07-prog/ctxpack.git
+cd ctxpack
+
+# Run straight from the source tree
+python -m ctxpack --path sample --task "understand the auth flow" --budget 2000 --out bundle.md --manifest manifest.json
+
+# View results
+cat bundle.md
+cat manifest.json
+```
+
+The source lives in `src/`, so running from a clone needs that directory importable — either `pip install -e .` once, or prefix the command with `PYTHONPATH=src` (`$env:PYTHONPATH="src"` in PowerShell).
+
+If `--out` is omitted, the bundle prints to stdout. If `--manifest` is omitted, a one-line summary like `used 521/2000 tokens, 5 included, 0 excluded` goes to stderr.
+
+## CLI Usage
+
+```
+ctx-packr --path <folder> --task "<desc>" --budget <int> [--out <file>] [--manifest <file>]
+```
+
+| Flag | Required | Description |
+|---|---|---|
+| `--path` | Yes | Target folder (must exist and be readable) |
+| `--task` | Yes | Free-text description of what you're looking for |
+| `--budget` | Yes | Max tokens for the entire rendered bundle (integer > 0) |
+| `--out` | No | Write bundle to this file; omitted = stdout |
+| `--manifest` | No | Write JSON manifest; omitted = one-line stderr |
+
+**Exit codes:** `0` success, `1` invalid args, `2` bad path. Errors are a single human-readable line on stderr — no tracebacks.
+
+## Example
+
+```bash
+ctx-packr --path sample --task "auth and api" --budget 2000
+```
+
+Produces a markdown bundle like this (truncated for display):
+
+````
+## src/auth.py
+```
+def login(username: str, password: str) -> bool:
+    if not username or not password:
+        return False
+    return _verify_credentials(username, password)
+```
+````
+
+And if `--manifest` is given, a JSON file:
+
+```json
+{
+  "budget": 2000,
+  "used": 521,
+  "included": [
+    {"path": "tests/test_auth.py", "tokens": 69, "reason": "fits within budget"},
+    {"path": "src/auth.py", "tokens": 104, "reason": "fits within budget"},
+    {"path": "src/api.py", "tokens": 111, "reason": "fits within budget"}
+  ],
+  "excluded": [
+    {"path": "package-lock.json", "reason": "lockfile shape detected"}
+  ]
+}
+```
+
+Every file under `--path` appears exactly once — included with reason and token count, or excluded with reason.
+
+## How It Works
+
+1. **Walk** — recursive directory walk with 4 structural noise detectors (binary content, lockfile shape, dependency trees, build artifacts). No name blacklists.
+2. **Rank** — tokenizes the task (camelCase-aware), scores files by keyword overlap with path and content, applies an entrypoint bonus and a depth penalty.
+3. **Pack** — greedily fills the token budget. Files that don't fully fit get a 70/30 head-and-tail truncation with a marker line; files that can't be meaningfully truncated (<200 tokens) are excluded cleanly.
+4. **Render** — assembles markdown sections. Optionally includes a project tree overview for folders with 15+ relevant files (capped at 5% of budget).
+5. **Manifest** — JSON accounting for every file. `used` is the exact token count of the rendered bundle, verified by re-tokenizing before writing.
+
+See [SPEC.md](SPEC.md) for the full spec, [CLARIFY.md](.specify/memory/clarify.md) for design decisions, and [PLAN.md](.specify/memory/plan.md) for the implementation plan.
+
+## Known Limitations
+
+- **No semantic understanding.** Matching is keyword-based with camelCase splitting — a task about "authentication" won't match a file about "login" unless the words overlap. This is an accepted tradeoff for an offline, stdlib-only, deterministic tool.
+- **No language-aware parsing.** No import graphs, AST analysis, or per-language heuristics. Path and content keyword overlap is the only signal.
+- **No incremental runs.** Every invocation does a fresh walk from scratch — no caching between runs.
+- **No `.gitignore` support.** Hidden test folders may contain files a developer would typically exclude. The tool treats all readable files equally; structural noise is caught by content-shape detection, not ignore files.
+
+This is a **Spec-Driven Development** project. The spec was written before any code, and all decisions are documented in the spec chain under `.specify/memory/`.

ctx_packr-0.1.1/README.md

@@ -0,0 +1,142 @@
+# `ctx-packr`
+
+A stdlib-only Python CLI that selects the most relevant files from a codebase for a given task and packs them into a token-budgeted markdown bundle.
+
+## Why `ctx-packr`?
+
+Several tools occupy nearby space. The difference is not quality — it is which part of
+the problem each one solves.
+
+| Tool | Approach | What it lacks vs `ctx-packr` |
+|---|---|---|
+| `ctxpack` | Config-driven file selection, with `init` and `watch` commands | No relevance ranking against a stated task |
+| `context-packer` | Smart filtering of build artifacts and binaries, plus a visual project tree | No relevance ranking against a stated task |
+| `llm-ctxpack` | Priority-based packing into a token budget | Does not walk a codebase; the caller supplies the chunks |
+| `contextcram` | Priority-based packing into a token budget | Does not walk a codebase; the caller supplies the chunks |
+| `ctx-pack` (Rust) | Versioned bidirectional patch/replace | Solves a different problem — not context packing |
+
+`ctx-packr` combines four things that otherwise appear separately: it walks a real
+codebase, ranks what it finds against a specific stated task, enforces a hard token
+budget, and has zero runtime dependencies. Ranking uses camelCase-aware keyword
+scoring, with bonuses for entry-point filenames and for files whose `def`/`class` names
+match the task, offset by a penalty for directory depth. When the budget is too small
+for the full bundle, the output degrades step by step — dropping the contents table,
+then the summary header — rather than failing.
+
+*Comparison reflects these projects as of September 2026.*
+
+## Requirements
+
+- Python 3.10+
+- No third-party packages — `ctx-packr` has zero runtime dependencies
+
+## Install
+
+```bash
+pip install ctx-packr
+```
+
+That puts a `ctx-packr` command on your PATH:
+
+```bash
+ctx-packr --path sample --task "understand the auth flow" --budget 2000 --out bundle.md --manifest manifest.json
+```
+
+> **Note on naming.** You install `ctx-packr`, but the importable module is `ctxpack`:
+>
+> ```python
+> import ctxpack
+> ```
+>
+> The two differ because a hyphen is not legal in a Python identifier. This is the
+> same split used by `beautifulsoup4` → `bs4` and `python-dateutil` → `dateutil`.
+
+## Quick Start (from a clone, no install)
+
+```bash
+git clone https://github.com/shaheersaifi07-prog/ctxpack.git
+cd ctxpack
+
+# Run straight from the source tree
+python -m ctxpack --path sample --task "understand the auth flow" --budget 2000 --out bundle.md --manifest manifest.json
+
+# View results
+cat bundle.md
+cat manifest.json
+```
+
+The source lives in `src/`, so running from a clone needs that directory importable — either `pip install -e .` once, or prefix the command with `PYTHONPATH=src` (`$env:PYTHONPATH="src"` in PowerShell).
+
+If `--out` is omitted, the bundle prints to stdout. If `--manifest` is omitted, a one-line summary like `used 521/2000 tokens, 5 included, 0 excluded` goes to stderr.
+
+## CLI Usage
+
+```
+ctx-packr --path <folder> --task "<desc>" --budget <int> [--out <file>] [--manifest <file>]
+```
+
+| Flag | Required | Description |
+|---|---|---|
+| `--path` | Yes | Target folder (must exist and be readable) |
+| `--task` | Yes | Free-text description of what you're looking for |
+| `--budget` | Yes | Max tokens for the entire rendered bundle (integer > 0) |
+| `--out` | No | Write bundle to this file; omitted = stdout |
+| `--manifest` | No | Write JSON manifest; omitted = one-line stderr |
+
+**Exit codes:** `0` success, `1` invalid args, `2` bad path. Errors are a single human-readable line on stderr — no tracebacks.
+
+## Example
+
+```bash
+ctx-packr --path sample --task "auth and api" --budget 2000
+```
+
+Produces a markdown bundle like this (truncated for display):
+
+````
+## src/auth.py
+```
+def login(username: str, password: str) -> bool:
+    if not username or not password:
+        return False
+    return _verify_credentials(username, password)
+```
+````
+
+And if `--manifest` is given, a JSON file:
+
+```json
+{
+  "budget": 2000,
+  "used": 521,
+  "included": [
+    {"path": "tests/test_auth.py", "tokens": 69, "reason": "fits within budget"},
+    {"path": "src/auth.py", "tokens": 104, "reason": "fits within budget"},
+    {"path": "src/api.py", "tokens": 111, "reason": "fits within budget"}
+  ],
+  "excluded": [
+    {"path": "package-lock.json", "reason": "lockfile shape detected"}
+  ]
+}
+```
+
+Every file under `--path` appears exactly once — included with reason and token count, or excluded with reason.
+
+## How It Works
+
+1. **Walk** — recursive directory walk with 4 structural noise detectors (binary content, lockfile shape, dependency trees, build artifacts). No name blacklists.
+2. **Rank** — tokenizes the task (camelCase-aware), scores files by keyword overlap with path and content, applies an entrypoint bonus and a depth penalty.
+3. **Pack** — greedily fills the token budget. Files that don't fully fit get a 70/30 head-and-tail truncation with a marker line; files that can't be meaningfully truncated (<200 tokens) are excluded cleanly.
+4. **Render** — assembles markdown sections. Optionally includes a project tree overview for folders with 15+ relevant files (capped at 5% of budget).
+5. **Manifest** — JSON accounting for every file. `used` is the exact token count of the rendered bundle, verified by re-tokenizing before writing.
+
+See [SPEC.md](SPEC.md) for the full spec, [CLARIFY.md](.specify/memory/clarify.md) for design decisions, and [PLAN.md](.specify/memory/plan.md) for the implementation plan.
+
+## Known Limitations
+
+- **No semantic understanding.** Matching is keyword-based with camelCase splitting — a task about "authentication" won't match a file about "login" unless the words overlap. This is an accepted tradeoff for an offline, stdlib-only, deterministic tool.
+- **No language-aware parsing.** No import graphs, AST analysis, or per-language heuristics. Path and content keyword overlap is the only signal.
+- **No incremental runs.** Every invocation does a fresh walk from scratch — no caching between runs.
+- **No `.gitignore` support.** Hidden test folders may contain files a developer would typically exclude. The tool treats all readable files equally; structural noise is caught by content-shape detection, not ignore files.
+
+This is a **Spec-Driven Development** project. The spec was written before any code, and all decisions are documented in the spec chain under `.specify/memory/`.

ctx_packr-0.1.1/SPEC.md

@@ -0,0 +1,158 @@
+# specify.md — `ctxpack`
+
+**Written before implementation. Governed by CONSTITUTION.md. This is a graded deliverable, not documentation written after the fact.**
+
+---
+
+## 1. CLI Contract
+
+```
+ctxpack --path <folder> --task "<task description>" --budget <int> [--out <file>] [--manifest <file>]
+```
+
+| Flag | Required | Behavior |
+|---|---|---|
+| `--path` | Yes | Folder to pack. Must exist and be readable. |
+| `--task` | Yes | Free-text description of developer intent. Used for ranking. |
+| `--budget` | Yes | Max tokens for the **entire rendered bundle**, integer > 0. |
+| `--out` | No | Write bundle here. Omitted → stdout. |
+| `--manifest` | No | Write manifest JSON here. Omitted → one-line summary to stderr. |
+
+### Exit Codes
+
+| Code | Meaning |
+|---|---|
+| `0` | Success. Bundle produced within budget. |
+| `1` | Invalid arguments — missing required flag, non-integer/non-positive `--budget`, malformed `--task`. |
+| `2` | `--path` does not exist, is not a directory, or is unreadable (permissions). |
+
+Errors print a single human-readable line to stderr. No tracebacks, per Constitution Principle IV.
+
+### Argument Validation Order
+1. Parse flags → missing required flag = exit 1 immediately, before touching the filesystem.
+2. Validate `--budget` is a positive integer → exit 1 if not.
+3. Validate `--path` exists and is a readable directory → exit 2 if not.
+4. Only then begin the walk.
+
+This order matters: a bad `--budget` should never be masked by a slower path-not-found check.
+
+---
+
+## 2. Token Counting
+
+```python
+tokens = math.ceil(len(text) / 4)
+```
+
+Applied to:
+- Each individual file's content (for ranking/truncation decisions)
+- The **fully rendered bundle** — headers, file path labels, separators, the optional tree diagram, everything that reaches `--out` or stdout
+
+The budget check happens against the final rendered string, not against a running sum of file contents. This catches the case where formatting overhead itself would push the bundle over budget.
+
+---
+
+## 3. Ranking Strategy — Weighted Keyword Overlap
+
+**Decision:** Rank files by a weighted score combining (a) keyword overlap between `--task` and file content/path, (b) a small structural prior, and (c) a path-depth penalty.
+
+```
+score(file) = 3 × path_match_count
+            + 1 × content_match_count (capped at 20)
+            + 2 × (file is entrypoint-like: main.py, index.js, __init__.py, README)
+            - 0.5 × directory_depth
+```
+
+- `--task` is lowercased, split on non-alphanumeric characters, stopwords removed (a small hardcoded stopword list of ~30 English function words — this is not "noise detection," it's tokenization hygiene, and is documented as such).
+- `path_match_count`: task keywords found in the file's path/filename (case-insensitive substring match).
+- `content_match_count`: task keywords found in file content, capped so one keyword-stuffed file can't dominate purely on repetition.
+- Entrypoint bonus: files conventionally likely to explain "what this project does" get a small nudge, because task descriptions are often about behavior, and behavior is usually reachable from an entrypoint.
+- Depth penalty: deeply nested files are slightly deprioritized, since top-level and near-top-level files are more often architecturally central.
+
+**Why this over the alternatives considered:**
+
+| Alternative | Why rejected |
+|---|---|
+| Import graph analysis | Requires language-aware parsing per file type (Python imports ≠ JS imports ≠ Go imports). Violates stdlib-only cleanly only for Python; brief implies mixed-language repos. Too much complexity for the time budget, and it silently fails on non-code files (README, config, docs) that are often exactly what's relevant to a task like "understand the auth flow." |
+| Pure filename matching | Too brittle — a file named `utils.py` could be the single most task-relevant file and would never surface. |
+| File recency (mtime) | Recency correlates with "recently touched," not "relevant to this task." A judge's test folder is likely a static snapshot with meaningless or identical mtimes — this signal would be near-random noise on the actual test set. |
+| Pure content keyword count, no path weighting | Rewards keyword-stuffed files (tests, changelogs, generated docs) over structurally central ones. Path weighting is a cheap, dependency-free proxy for "this file is what it says it is." |
+
+**Known weakness, stated up front:** this method has no semantic understanding — a task about "authentication" won't match a file about "login" unless the words overlap. This is an accepted tradeoff for a stdlib-only, offline, deterministic tool. It is not treated as a hidden flaw to discover later; it is the stated boundary of the approach.
+
+---
+
+## 4. Truncation Policy — Smart Head-and-Tail Slice
+
+**Decision:** When a file doesn't fit in the remaining budget, `ctxpack` does not skip it outright and does not blindly take the head. It takes a **head + tail slice** sized to the remaining budget, with a visible truncation marker, provided the file scored high enough to be worth partial inclusion (see threshold below).
+
+- Take roughly 70% of the available token allowance from the start of the file, 30% from the end, joined by a marker line: `... [truncated: N tokens omitted] ...`
+- Rationale: file heads usually carry imports, class/function signatures, and top-of-file docstrings; tails often carry `main()` blocks, exports, or closing logic. A pure head-slice biases against exactly the code that shows what a file *does* at runtime.
+- **Threshold:** partial inclusion is only attempted if the remaining budget can fit at least 200 tokens of a truncated file. Below that, a partial slice is judgment-free noise (a few import lines and a truncation marker convey nothing) — the file is excluded instead, with reason `"insufficient remaining budget for meaningful partial inclusion (needed ≥200 tokens, had N)"`.
+
+**Why this over the alternatives considered:**
+
+| Alternative | Why rejected |
+|---|---|
+| Always exclude if it doesn't fully fit | Throws away a highly relevant large file entirely in favor of lower-ranked small files, which can produce a worse bundle for the stated task even though it "used the budget efficiently." |
+| Always take the head | Cheap and deterministic, but systematically biased against seeing how a file's logic concludes — a real cost for exactly the kind of "understand what this does" tasks the tool exists for. |
+| Summarize the file (extractive/heuristic) | Non-trivial to make deterministic and language-agnostic without third-party NLP tooling; risks misrepresenting the file's actual content, which conflicts with Constitution Principle II (silence/misrepresentation is a bug). |
+
+---
+
+## 5. Noise Detection — Structural Heuristics, Not a Name Blacklist
+
+**Decision:** Noise is detected by structural signal, not a hardcoded list of filenames, so the approach generalizes beyond `node_modules`/`.git` to noise `ctxpack` has never seen named before.
+
+A file/directory is flagged as noise if **any** of:
+1. **Path contains a VCS or dependency directory marker**: detected by checking for a small set of *structural* markers — a directory containing a `.git` HEAD-like structure, or a directory whose immediate contents look like an installed package tree (a `package.json`-sibling `node_modules`-shaped nesting, i.e., a directory containing hundreds of subdirectories each containing their own manifest-like file). This is a structural detector, not a name check — `node_modules` is caught because of what's inside it, not because of its name (a differently-named vendor directory with the same shape is caught too).
+2. **File is a lockfile by content shape**: single-file, machine-generated JSON/text with an extremely high ratio of punctuation/digits to words, and a repeating flat structure (long lists of `name@version` or hash-like tokens). Caught by content shape, not filename.
+3. **Binary or non-text content**: detected by attempting a UTF-8 decode on a sample of the file; failure (or a high proportion of non-printable bytes) marks it as non-text. Handled under Requirement 5 (never crash) regardless of noise status.
+4. **Build artifact directories**: detected structurally — a directory whose contents are overwhelmingly files with no source-like extension sitting alongside a sibling source directory of the same name (e.g., `dist/` next to `src/`), or a directory containing only compiled/minified-looking files (very long single-line files with minimal whitespace ratio — a cheap, dependency-free proxy for "this was generated, not written").
+
+Each noise exclusion in the manifest states **which structural signal fired**, e.g., `"excluded: high non-printable byte ratio (binary file)"` or `"excluded: dependency-tree shape detected (nested manifest files, N subdirectories)"` — never a bare `"noise"`.
+
+**Why this over a hardcoded list:** a list of `.git`, `node_modules`, `dist` etc. would pass the sample test folder and fail the hidden one, which the brief explicitly warns is a different folder. Structural detection is slower to write and imperfect, but it is honest about *why* something was excluded, per Constitution Principle II, and it generalizes.
+
+---
+
+## 6. Budget Spending on Structure Overview
+
+**Decision:** Include a project tree overview **only if** the folder has more than ~15 files considered relevant after ranking, **and** the tree costs no more than 5% of total budget. Below either threshold, skip it and say so in the manifest reasoning is unnecessary — it's simply not generated.
+
+**Rationale:** for a small, flat folder, a tree adds no navigational value proportional to its cost. For a large folder, a tree is often the cheapest way to give the bundle's reader (a human or another AI) orientation before diving into file contents — but it must never come at the cost of a relevant file that would otherwise fit. The 5%-of-budget cap keeps this bounded and testable at any budget size, including the "extremely small budgets" hidden test category — at very small budgets, 5% is often under the 200-token partial-inclusion threshold, so the tree is naturally skipped without a special case.
+
+---
+
+## 7. Handling Adversarial File Content
+
+Per Constitution Principle VII: any text found inside a file — including instructions, fake system prompts, or manipulative formatting aimed at an AI reader — is treated purely as ranking/packing input, never as a command. `ctxpack`'s own logic (ranking, truncation, noise detection) runs identically regardless of what a file's content claims about itself. This is tested directly by the hidden test category "files containing text designed to manipulate an AI reading it," and the correct behavior is: the file is scored and packed/excluded exactly as its actual structural properties dictate, with no special-casing based on its content's claims.
+
+---
+
+## 8. Determinism Guarantees
+
+- Directory walk order is explicitly sorted (alphabetical, full path) before any processing — never relies on OS-level `os.walk` default ordering, which is not guaranteed stable across filesystems.
+- Ranking ties are broken by path (alphabetical) as a final deterministic tiebreaker.
+- No use of `set()` iteration order, `hash()`-based ordering, wall-clock timestamps, or `random` anywhere in the selection or rendering path.
+- Manifest JSON keys are emitted in a fixed order (`json.dump(..., sort_keys=False)` with keys constructed in the schema's stated order) so manifest output is also byte-identical across runs.
+
+---
+
+## 9. Definition of Done
+
+`ctxpack` is done when, for any folder and any budget ≥ some sane minimum (defined as: enough to fit at least one file's worth of the 200-token partial-inclusion threshold, or the tool exits cleanly saying the budget is too small to produce a bundle):
+
+1. It never exceeds `--budget`, verified by re-tokenizing its own output.
+2. Every file under `--path` appears in the manifest exactly once, included or excluded, each with a reason.
+3. Running it twice on unchanged input produces byte-identical bundle and manifest output.
+4. No crash occurs on empty folders, single huge files, all-binary folders, or malformed `--task`/`--budget` input — each produces either a valid (possibly empty) bundle or a clean exit-1/exit-2 error.
+5. Every team member can explain, unprompted, why a specific file was included or excluded in a given run.
+
+---
+
+## 10. Explicit Non-Goals
+
+- No semantic/embedding-based relevance (would require a model, violating offline/stdlib constraints).
+- No language-aware parsing (import graphs, AST analysis) — rejected in Section 3, consistent across the spec.
+- No caching or incremental re-runs between invocations — every run is a fresh, from-scratch walk, to keep the determinism guarantee simple to verify.