Deployed .gitignore omits __pycache__/ and *.pyc, so the framework's own tools dirty the adopter's tree

[KbWen]

Summary

The .gitignore block that deploy.sh writes into a downstream project omits __pycache__/ and *.pyc. The framework's own Python tools generate bytecode into the adopter's tree, and the deploy banner's own "Finish setup" instructions then stage it.

The source repo protects itself (.gitignore:50-51) — that protection just isn't in what gets deployed.

Reproduce

mkdir -p /tmp/acx-demo/app && cd /tmp/acx-demo/app
git init -q . && echo x > readme.txt && git add -A && git commit -qm init

bash /path/to/agentic-os/.agentcortex/bin/deploy.sh .

# 1. the deployed ignore block has no bytecode rule
grep -nE '__pycache__|\*\.pyc' .gitignore          # -> no match

# 2. the source repo's own ignore file does
grep -nE '__pycache__|\*\.pyc' /path/to/agentic-os/.gitignore   # -> 50,51

# 3. running the framework's documented self-check creates bytecode
bash .agentcortex/bin/validate.sh >/dev/null 2>&1
find . -name '*.pyc' -not -path './.git/*'
# -> .agentcortex/tools/__pycache__/guard_context_write.cpython-314.pyc
# -> .agentcortex/tools/__pycache__/_yaml_loader.cpython-314.pyc

Verified 2026-09-05 on Windows 11 / Git Bash / Python 3.14.3.

Why it matters

The failure needs no unusual behaviour from the adopter — following the deploy banner's own printed steps in the printed order is enough:

1. The banner tells the adopter to run the self-check (.agentcortex/bin/validate.sh), which writes the .pyc files.
2. The banner's "Finish setup" line is git add .agentcortex-manifest AGENTS.md CLAUDE.md GEMINI.md .agent/ .agents/ .agentcortex/ ... — the .agentcortex/ entry stages __pycache__/ along with everything else.

So the adopter's first framework commit contains Python bytecode, which then churns on every subsequent run under a different interpreter version.

Proposed fix

Additive and self-contained:

1. Add __pycache__/ and *.pyc to the downstream ignore-defaults block in .agentcortex/bin/deploy.sh (and keep the PowerShell path in parity).
2. Extend the existing deploy-tiering test that pins the ignore block so the two patterns are asserted, preventing regression.

No design question attached — this is why it was picked as the one issue-worthy item out of the current audit batch. The other findings from the same pass are tracked in docs/specs/_product-backlog.md (#188–#193) because they need scope decisions first.

Context

Found during a downstream-adopter simulation pass (greenfield / brownfield / upgrade / zero-Python / Windows-path / capability-seam targets). Backlog row: #191.