Skip to content

docs: v2.1 soak triage (2026-05-15) #11

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
LanderXT wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: v2.1 soak triage (2026-05-15) #11

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
142 changes: 142 additions & 0 deletions docs/reviews/v2.1-soak-2026-05-15.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,142 @@
# v2.1 Soak Triage — 2026-05-15

Soak window: 2026-05-01 (v2.1.0 tag) → 2026-05-15 (2 weeks). Triage based on git log, GitHub PRs #1–#10, and `.pman/exports/` plan snapshots.

---

## Summary

The soak window was extremely active — the project shipped four major follow-on versions (v2.2–v2.5) plus encrypted portable transport in 7 days. Multiple real dogfooding bugs were found and fixed (export evidence loss, silent workspace fork, memory leaks, doc drift). One PR (#10: init gitignore protection) remains open. No git release tags exist after v2.1.0.

---

## Post-ship commits since v2.1.0

> `v2.1.0` is the last tag; all 50 commits below are dated 2026-05-01 or later.

### Bugfixes

- `bbebccc` Fix plan.export evidence loss and broken doc examples _(closure evidence fields silently dropped; plan.* doc examples used banned `code` selector)_
- `fb54b59` fix(main): plug cJSON leaks on --close early-exit paths
- `410824f` fix(agent_docs): plug content leak on realloc failure in artifact_add
- `c7ff968` fix(agent_docs): include workspace entity in by-entity index _(workspace ops invisible in by-entity index)_
- `420ff89` fix(agent_docs): drop parent_child from task-relation enum doc _(never accepted at runtime)_
- `db2c6e3` fix(mcp): bump README envelope example from protocol_version 1 to 2 _(copy-paste would hit invalid_request)_
- `769fd1b` fix(v2.4.1): list attic_full in envelope doc error code enumeration
- `9b8d0b0` fix(v2.4 phase 23): tighten slugify table size and invalid-byte test
- `ed161e3` fix(v2.4 phase 23): code quality polish from review
- `3e5eb0e` feat(v2.4.3): migration safety net + v3→v4 upgrade unblock _(live migration path broke)_

### Features (v2.2 ergonomics, 2026-05-01)

- `740435e` Tip on parse-level errors: nudge users toward --usage / --next (F2)
- `e16fae7` Lead the discovery surface with CLI, not JSON wire (F3)
- `f888631` Add --close-phase and --cancel-phase CLI verbs (F4)
- `9e29dfa` Add --summary-only and --limit flags to ipman -LG (F5)
- `66ccc9c` Decide against cursor-implicit `ipman note` (F6, docs-only decision)

### Features (v2.3 project entity, 2026-05-03)

- `fdded85` chore(v2.2.x): tighten selectors, mcp schema tests, op example coverage
- `0b3f791` feat(v2.3): project entity + tools and env_vars registry
- `df28f1e` feat(v2.3.1): project-scoped instructions surfaced in context.project
- `9845e91` feat(v2.3.2): close v2.3 ergonomic gaps (init, --next, workspace.export)

### Features (v2.4 slugs + import, 2026-05-04–05)

- `1079bc1` feat(v2.4/phase-23): fix UTF-8 slug generation with Latin transliteration
- `53cf147` refactor(usage): embed --usage text via byte array (C99 string-literal size risk)
- `331b2ed` feat(v2.4/phase-26): --import-plan CLI shortcut with saga rollback
- `e2a3cc3` feat(v2.4.1): evict stale agent-docs to .attic with refuse-on-limit
- `f076d0c` feat(v2.4.2): walk upward to find repo root, refuse init from subdir _(silent workspace fork fix)_

### Features (v2.5 branch-aware context, 2026-05-06)

- `ad7f39a` feat(migration): add branch_contexts table for per-branch plan binding
- `f7e49e5` feat: add git_helpers for reading current branch from .git/HEAD
- `f64f22a` feat: plan.activate registers git branch → plan binding in branch_contexts
- `a0c490a` feat: workspace.context_get uses branch-specific active plan when bound
- `6497eab` feat: add workspace.list_branch_bindings and workspace.unbind_branch ops
- `b23cfa1` feat: register workspace.list_branch_bindings + workspace.unbind_branch ops
- `f6a26ed` feat: -N handoff view shows current git branch and binding status
- `8fc8f01` chore: bump to v2.5.0 — branch-aware workspace context

### Features (portable encrypted transport, 2026-05-07)

- `45194c5` feat: add ipman_key_derive_passphrase for portable transport keys
- `4234aaa` feat: add ipman_read_passphrase (termios + IPMAN_PASSPHRASE env)
- `4c0291e` feat: add ipman_export_portable (passphrase-encrypted bundle)
- `8af1868` feat: add ipman_import_portable (bundle → machine-keyed workspace)
- `382374d` feat: wire export-portable / import-portable CLI subcommands
- `00ce78a` test(integration): portable export/import round-trip

### Docs / infra

- `03c81ea` docs(cli): rename "human surface" to shortcuts/views/admin taxonomy
- `0a9b87c` docs(v2.4/phase-25): surface hidden features
- `a8f86e4` docs(v2.4/phase-27): punt sub-tasks — parent_task_id already covers the use case
- `af225bf` docs(v2.4.1): release polish — version bump, per-release docs, README
- `72ec8a1` docs(v2.4.2): consistency follow-up — guide caveat, README count, cross-links
- `189ddb3` test(parity): convert two doc-drift WARN-comments into machine checks
- `ca0d6dd` docs(readme): correct op count and add v2.2 verbs to Human CLI ref
- `4d34bfd` docs(skill): cover v2.1/v2.2 CLI ergonomics in SKILL.md
- `c150299` refactor(log): drop dead LEVEL_DEBUG enum and env-var entry
- `dbf83e0` test(log): match new IPMAN_LOG=debug contract
- `ea10fc0` test(unit): add test_git_helpers for branch detection
- `973b8db` test(integration): branch-aware context — activate, switch, unbind

---

## GitHub issues/PRs since 2026-05-01

No issues filed. 10 PRs total (9 merged, 1 open):

| # | Title | State |
|---|---|---|
| #1 | Fix plan.export evidence loss and broken doc examples | merged 2026-05-04 |
| #2 | v2.1 polish + v2.2 ergonomics (F1–F6) | merged 2026-05-01 |
| #3 | v2.1+v2.2 audit cleanup: docs drift, doc-gen bugs, C leaks, dead enum | merged 2026-05-01 |
| #4 | v2.4.1: evict stale agent-docs to .attic with refuse-on-limit | merged 2026-05-05 |
| #5 | v2.4.1.1: list attic_full in envelope doc error code enumeration | merged 2026-05-05 |
| #6 | v2.4.1 release polish: version bump, per-release docs, README | merged 2026-05-05 |
| #7 | v2.4.2: walk upward to find repo root, refuse init from subdir | merged 2026-05-05 |
| #8 | v2.4.2 doc consistency follow-up | merged 2026-05-05 |
| #9 | test(parity): error-code and README op-count drift detection | merged 2026-05-05 |
| #10 | feat: auto-protect sensitive workspace files on init | **open** (2026-05-08) |

---

## Friction observed

Real-use dogfooding surfaced several issues within hours of v2.1 shipping:

1. **plan.export evidence loss** (`bbebccc`, PR #1): The export SELECT predated migrations 0002/0003 and silently dropped all v2.1 closure evidence fields. Found immediately during live use. Functional data loss in the canonical archival snapshot.

2. **Doc examples using banned selectors** (`bbebccc`, PR #1): Seven auto-generated `plan.*` examples used `code` as a selector after v2.0 narrowed allowlists to `id`-only. Any agent following official examples hit `validation_failed`. A v2.0-era drift that made it through v2.1.

3. **Silent workspace fork on subdir init** (PR #7, `f076d0c`): A Superpowers subagent dispatched into a git worktree triggered init in a stray path divorced from the real workspace. Real-agent dogfood failure. Required a new upward-walk resolver and explicit refusal of `init` from subdirs.

4. **Memory leaks** (PR #3, `fb54b59`, `410824f`): Five `--close` early-exit paths leaked cJSON objects; one realloc-failure path leaked artifact content. Found via `-fsanitize=address,leak` during audit.

5. **agent_docs index gap** (`c7ff968`): `workspace` entity missing from by-entity index — workspace ops were silently dropped, making them undiscoverable to agents using the index.

6. **Migration upgrade broken** (`3e5eb0e`): v3→v4 migration had a safety-net gap that blocked schema upgrades in the field. Found during v2.4 rollout.

7. **No git release tags after v2.1.0**: v2.2–v2.5 and portable transport all shipped without tags. PR #6 acknowledged this and promised `gh release create` follow-ups that have not happened. Makes `git log v2.2.0..HEAD` impossible and complicates bisect.

---

## Candidates for a v2.2 plan

The project already shipped through v2.5 and portable transport during the soak — there is no meaningful "v2.2 scope" left to plan. Items warranting a next plan:

- **Tag releases** (v2.2–v2.5 + portable transport): PR #6 promised this; still unresolved. Low effort, unblocks any future bisect or changelog workflow.
- **Merge PR #10** (init gitignore + CLAUDE.md injection): Open since 2026-05-08, last updated 2026-05-12. Tightens a real init safety gap.
- **Docs for portable transport**: `docs/v2.5.0-branch-aware-context.md` exists but no equivalent for the 2026-05-07 encrypted export/import feature.

---

## Items that look urgent

- **PR #10 is stalled open** (11 days, last touch 2026-05-12). It blocks the init gitignore protection from shipping. Not a regression but the gap it closes (secrets leaking into git history via `.ipman/ipman.db`) is user-visible and real.
- **Missing release tags**: v2.2–v2.5 are untagged on GitHub. Not blocking anything today but the longer this persists the more friction for anyone trying to correlate versions.