# T-1321: Vendored .agentic-framework/ tracks Python __pycache__ files

**Source:** termlink T-1130 pickup (P-038)
**Status:** GO — build sibling T-1323
**Date:** 2026-04-18

## Bug

Consumer projects vendor the framework into `.agentic-framework/` (T-909). When Watchtower (or any `python3 web/...` invocation) runs from the vendored tree, `__pycache__/*.pyc` files appear under `.agentic-framework/web/**/`. Without a `.gitignore` inside the vendored directory, the consumer's git tracks them. Every session leaves 5–15 dirty files; "Uncommitted changes present" becomes the #1 audit trend (23 repeats reported on `/opt/termlink`).

## Root Cause

Two-part:
1. `do_vendor` (`bin/fw:181-202`) excludes `__pycache__` and `*.pyc` from the **copy** step (correct), but doesn't write a `.gitignore` into the vendored directory to handle **runtime-generated** files.
2. The consumer's project root `.gitignore` (if any) doesn't typically cover `.agentic-framework/**/__pycache__/`.

The framework repo's own `.gitignore` line 1 is `__pycache__/` — the vendored copy needs the same protection.

## Fix

In `do_vendor`, after copying files, write a small `.gitignore` to `$dest`:

```bash
cat > "$dest/.gitignore" <<'GITIGNORE'
# Vendored Agentic Engineering Framework — runtime artifacts
# Generated by `fw vendor` / `fw upgrade`. Do not edit by hand.
__pycache__/
*.pyc
*.pyo
.DS_Store
GITIGNORE
```

For consumers who already have tracked pyc files, `fw upgrade` should detect this and emit a one-line cleanup hint:

```
WARN  Vendored framework has N tracked __pycache__ files.
      Run: git rm -r --cached '.agentic-framework/**/__pycache__'
```

Don't auto-`git rm` (that would silently mutate the consumer's git index without an explicit commit). Just inform.

## Why GO

- Concrete bug with reproducible repro from termlink (45 tracked .pyc files, 9 dirty)
- Fix is mechanical, scoped, additive (`.gitignore`) + advisory (hint)
- Risk near zero — `.gitignore` semantics are universal
- Closes a measurable audit-noise loop (#1 trend, 23×)

## Build Plan

Build task **T-1323** ships:
1. `.gitignore` write inside `do_vendor` (bin/fw)
2. Stale-pycache detection + advisory hint inside `lib/upgrade.sh`
3. Bats regression: vendor a stub framework into a temp dir; assert `.gitignore` exists with the expected entries

## Decision Trail

- Source pickup: `.context/pickup/processed/P-038-bug-report.yaml`
- Inception: `.tasks/completed/T-1321-pickup-vendored-agentic-framework-tracks.md`
- Build sibling: T-1323
- Recommendation: GO
