From 75611a973f17101132b54fee492a400d367fd778 Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 15 May 2026 13:03:26 +0000 Subject: [PATCH] docs: v2.1 soak triage (2026-05-15) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Two-week soak review of v2.1.0. Summarises 50 post-ship commits across v2.2–v2.5 and portable transport, friction signals from live dogfooding (export evidence loss, silent workspace fork, memory leaks, doc drift), and open items (PR #10, missing release tags). https://claude.ai/code/session_01SPtzM4oevrtxB7GoBz9uVT --- docs/reviews/v2.1-soak-2026-05-15.md | 142 +++++++++++++++++++++++++++ 1 file changed, 142 insertions(+) create mode 100644 docs/reviews/v2.1-soak-2026-05-15.md diff --git a/docs/reviews/v2.1-soak-2026-05-15.md b/docs/reviews/v2.1-soak-2026-05-15.md new file mode 100644 index 0000000..cac4d70 --- /dev/null +++ b/docs/reviews/v2.1-soak-2026-05-15.md @@ -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.