chore: pre-release maintenance checklist (#223)

## Summary

- **cargo-vet**: Add exemption for `pyo3-build-config:0.28.2` (new
transitive dep)
- **Threat model**: Sync public doc with spec — add Python (TM-PY-*)
threat table, Git (TM-GIT-*) security section, and git test references
- **Orphaned TODOs**: Rename `TODO:` headings to `Known` sections in
`compatibility.md`, `004-testing.md`, `009-implementation-status.md`

## Maintenance Checklist Results

| Section | Status |
|---------|--------|
| 1. Dependencies | `cargo update` ✓, `cargo audit` ✓ (3 warnings, 0
vulns), `cargo deny` ✓, `cargo vet` ✓ |
| 2. Security | Threat model reviewed, public doc synced with spec |
| 3. Tests | `just test` ✓ — all unit + failpoint tests pass |
| 4. Documentation | `cargo doc` clean (0 warnings), CHANGELOG current |
| 5. Examples | All 15 Rust examples + feature-gated (python, git) pass
|
| 6. Specs | Status fields accurate, TODO comments cleaned up |
| 7. Code Quality | `cargo fmt` ✓, `cargo clippy` ✓, no stale TODOs in
src |
| 8. Agent Config | AGENTS.md accurate, spec table complete |

## Test plan

- [x] `cargo fmt --check`
- [x] `cargo clippy --all-targets --all-features -- -D warnings`
- [x] `cargo test --all-features`
- [x] `cargo vet`
- [x] `cargo doc --all-features --no-deps` (0 warnings)

https://claude.ai/code/session_012Au6KZ2BqLnfn7Kk5tb5Gz

Co-authored-by: Claude <noreply@anthropic.com>

Author: chaliy

crates/bashkit/docs/compatibility.md

@@ -424,7 +424,7 @@ cargo test --test spec_tests -- bash_comparison_tests --ignored
 - [x] Array indices `${!arr[@]}`
 - [x] `/dev/null` support (interpreter-level, cannot be bypassed by custom fs)
 
-### TODO: LLM Compatibility Gaps
+### Known LLM Compatibility Gaps
 
 Identified from eval analysis — features frequently used by LLM-generated scripts:
 

crates/bashkit/docs/threat-model.md

@@ -314,12 +314,62 @@ attacks:
 5. **Parser fuel** (`max_parser_operations`, default 100K): Independent of depth,
    limits total parser work to prevent CPU exhaustion.
 
-## Python Direct Integration
+### Python / Monty Security (TM-PY-*)
+
+The `python`/`python3` builtins embed the Monty Python interpreter with VFS bridging.
+Python `pathlib.Path` operations are bridged to Bashkit's virtual filesystem.
+
+| Threat | Attack Example | Mitigation |
+|--------|---------------|------------|
+| Infinite loop (TM-PY-001) | `while True: pass` | Monty time limit (30s) + allocation cap |
+| Memory exhaustion (TM-PY-002) | Large allocation | Monty max_memory (64MB) + max_allocations (1M) |
+| Stack overflow (TM-PY-003) | Deep recursion | Monty max_recursion (200) |
+| Shell escape (TM-PY-004) | `os.system()` | Monty has no os.system/subprocess |
+| Real FS access (TM-PY-005) | `open()` | Monty has no open() builtin |
+| Real FS read (TM-PY-015) | `Path.read_text()` | VFS bridge reads only from BashKit VFS |
+| Real FS write (TM-PY-016) | `Path.write_text()` | VFS bridge writes only to BashKit VFS |
+| Path traversal (TM-PY-017) | `../../etc/passwd` | VFS path normalization |
+| Network access (TM-PY-020) | Socket/HTTP | Monty has no socket/network module |
+| VM crash (TM-PY-022) | Malformed input | Parser depth limit + resource limits |
+
+**Architecture:**
+
+```text
+Python code → Monty VM → OsCall pause → BashKit VFS bridge → resume
+```
 
 Monty runs directly in the host process. Resource limits (memory, allocations,
 time, recursion) are enforced by Monty's own runtime. All VFS operations are
 bridged through the host process — Python code never touches the real filesystem.
 
+### Git Security (TM-GIT-*)
+
+Optional virtual git operations via the `git` feature. All operations are confined
+to the virtual filesystem.
+
+| Threat | Attack Example | Mitigation | Status |
+|--------|---------------|------------|--------|
+| Host identity leak (TM-GIT-002) | Commit reveals real name/email | Configurable virtual identity | MITIGATED |
+| Host git config (TM-GIT-003) | Read ~/.gitconfig | No host filesystem access | MITIGATED |
+| Credential theft (TM-GIT-004) | Access credential store | No host filesystem access | MITIGATED |
+| Repository escape (TM-GIT-005) | Clone outside VFS | All paths in VFS | MITIGATED |
+| Many git objects (TM-GIT-007) | Millions of objects | `max_file_count` FS limit | MITIGATED |
+| Deep history (TM-GIT-008) | Very long commit log | Log limit parameter | MITIGATED |
+| Large pack files (TM-GIT-009) | Huge .git/objects/pack | `max_file_size` FS limit | MITIGATED |
+| Unauthorized clone (TM-GIT-001) | `git clone evil.com` | Remote URL allowlist | PLANNED (Phase 2) |
+| Push to unauthorized (TM-GIT-010) | `git push evil.com` | Remote URL allowlist | PLANNED (Phase 2) |
+
+**Virtual Identity:**
+
+```rust,ignore
+use bashkit::Bash;
+
+let bash = Bash::builder()
+    .git_author("sandbox", "sandbox@example.com")
+    .build();
+// Commits use virtual identity, never host ~/.gitconfig
+```
+
 ## Security Testing
 
 Bashkit includes comprehensive security tests:
@@ -331,6 +381,7 @@ Bashkit includes comprehensive security tests:
 - **Network Security**: [`tests/network_security_tests.rs`][network_tests] - 53 tests
 - **Builtin Error Security**: `tests/builtin_error_security_tests.rs` - 39 tests
 - **Logging Security**: `tests/logging_security_tests.rs` - 26 tests
+- **Git Security**: `tests/git_security_tests.rs` + `tests/git_remote_security_tests.rs`
 - **Fuzz Testing**: [`fuzz/`][fuzz] - Parser and lexer fuzzing
 
 ## Reporting Security Issues
@@ -352,6 +403,7 @@ All threats use stable IDs in the format `TM-<CATEGORY>-<NUMBER>`:
 | TM-ISO | Multi-Tenant Isolation |
 | TM-INT | Internal Error Handling |
 | TM-LOG | Logging Security |
+| TM-GIT | Git Security |
 | TM-PY | Python/Monty Security |
 
 Full threat analysis: [`specs/006-threat-model.md`][spec]

specs/004-testing.md

@@ -156,14 +156,17 @@ to Codecov and available as CI artifacts.
 - Text processing tools: 73% pass rate (234/319 running, 85 skipped)
 - Core bash specs: 78% pass rate (367/471 running, 104 skipped)
 
-## TODO: Testing Gaps
+## Known Testing Gaps
 
-The following items need attention:
+Completed:
+
+- [x] Enable bash_spec_tests in CI — 330/435 tests running
+- [x] Add bash_comparison_tests to CI — 309 tests compared against real bash
+- [x] Fix control-flow.test.sh — 31 tests now running
+- [x] Add coverage tooling — cargo-tarpaulin + Codecov via `.github/workflows/coverage.yml`
+
+Outstanding:
 
-- [x] **Enable bash_spec_tests in CI** - Done! 330/435 tests running
-- [x] **Add bash_comparison_tests to CI** - Done! 309 tests compared against real bash
-- [x] **Fix control-flow.test.sh** - Enabled! 31 tests now running
-- [x] **Add coverage tooling** - cargo-tarpaulin + Codecov via `.github/workflows/coverage.yml`
 - [ ] **Fix skipped spec tests** (189 total):
   - Bash: 104 skipped (various implementation gaps)
   - AWK: 41 skipped (operators, control flow, functions)

specs/009-implementation-status.md

@@ -247,7 +247,7 @@ Features that may be added in the future (not intentionally excluded):
 - Field assignment `$2 = "X"`
 - `next` statement
 
-<!-- TODO: AWK remaining gaps for LLM compatibility -->
+<!-- Known AWK gaps for LLM compatibility (tracked in docs/compatibility.md) -->
 <!-- - Power operators (^ and **) - used in math scripts -->
 <!-- - printf %x/%o/%c formats - used in hex/octal output -->
 <!-- - match()/gensub() functions - used in text extraction -->
@@ -278,7 +278,7 @@ Features that may be added in the future (not intentionally excluded):
 - Numeric-regex range: `N,/pattern/`
 - Extended regex (`-E`), nth occurrence, address negation (`!`)
 
-<!-- TODO: SED remaining gaps for LLM compatibility -->
+<!-- Known SED gaps for LLM compatibility (tracked in docs/compatibility.md) -->
 <!-- - Ampersand (&) in replacement - very commonly used by LLMs -->
 <!-- - \n literal newline in replacement - used in line splitting -->
 <!-- - Grouped commands {cmd1;cmd2} - used in complex transforms -->

supply-chain/config.toml

@@ -830,6 +830,10 @@ criteria = "safe-to-deploy"
 version = "0.24.2"
 criteria = "safe-to-deploy"
 
+[[exemptions.pyo3-build-config]]
+version = "0.28.2"
+criteria = "safe-to-deploy"
+
 [[exemptions.pyo3-ffi]]
 version = "0.24.2"
 criteria = "safe-to-deploy"