[randomm]

Fixes #223

Summary

• Documents the library surface and its versioning policy in docs/architecture.md.
• Records the breaking library signature changes since v0.9.0, so the next release is versioned 0.10.0 and not 0.9.1.

Why: release-plz proposed 0.9.1 with "API compatible", although exec::run and learn::run_background (both non-hidden) changed parameter types. The semver check it runs does not flag changed parameter types and does not consider doc(hidden) items. The 0.7 -> 0.8 -> 0.9 releases set the precedent for treating such changes as minor-version bumps.

Verification

• Every statement in the new section was verified against the v0.9.0 and main source by two adversarial reviews and a developer.
• Docs-only change (docs/architecture.md).
• CI green: Test, MSRV, Vipune feature, Release.

Disclosures

• The 0.10.0 bump depends on release-plz treating the ! marker and the BREAKING CHANGE: footer as breaking. This is verified on the regenerated release PR after merge, not assumed.
• Two lens review rounds gave contradictory guidance on the hidden-items sentence. Resolved as: hidden items are part of the surface and follow the same minor-version rule.
• Accepted notes (tracked as follow-ups, not blocking):
  • Whether argv and commands should remain public at all is a design question for a separate ticket.
  • Full signatures appear in a few places in the doc (module table, key functions, change list).
  • The process sentence about commit marking duplicates release policy.
  • Behavioral (non-signature) changes, such as Vipune store error semantics, are not listed.

[randomm]

Six-pass review — residual findings (round disclosure)

The lens review verdict is ISSUES_FOUND; nothing listed here has been fixed.
None is CRITICAL and the adversarial gate passed the diff, so a round-capped
review may carry these forward — but they are recorded here so a merge is never
silent about them. Decide them before merging.

• [MEDIUM] docs/architecture.md:0 — Point-in-time changelog table embedded in design doc (ARCHITECTURE)
• [MEDIUM] docs/architecture.md:0 — Library boundary described inconsistently with lib.rs and enforced by doc(hidden) (ARCHITECTURE)
• [LOW] docs/architecture.md:249 — Historical v0.9.0 signature table will go stale in architecture doc (SIMPLICITY)

[randomm]

Six-pass review — residual findings (round disclosure)

The lens review verdict is ISSUES_FOUND; nothing listed here has been fixed.
None is CRITICAL and the adversarial gate passed the diff, so a round-capped
review may carry these forward — but they are recorded here so a merge is never
silent about them. Decide them before merging.

• [MEDIUM] docs/architecture.md:251 — Library "public surface" boundary is ambiguous (ARCHITECTURE)
• [LOW] docs/architecture.md:0 — Point-in-time changelog embedded in architecture doc will go stale (SIMPLICITY)
• [LOW] docs/architecture.md:255 — Point-in-time changelog embedded in standing design doc (ARCHITECTURE)

[randomm]

⏸ Cap hit — needs human attention

Cap: lens-fix-reposition
Tokens: · 5.9M tokens
Rounds: 2 of 3 review rounds
Branch: feature/issue-223-chore-document-the-library-api-stability
Issues: #223
State file: .pi/work-state/223.json

What this cap means

the lens-fix reposition guard could not establish the correct base for the next round: diverged: worktree has diverged from the branch tip 09bef3d — the tree holds commits the branch does not: 3c1cdcbfd75a6630943d0fef95159d7be67b7c2b, 658f532674dd7b41a4b6fdf52f06b5b1d50595d0 (backed up to refs/pi-rukas/lens-fix-backup/issue-223-chore-document-the-library-api-stability/2026-10-13T14-42-53). The worktree inspected was /Users/janni/projects/oo/.worktrees/issue-223-default (git -C /Users/janni/projects/oo/.worktrees/issue-223-default status). The backup ref refs/pi-rukas/lens-fix-backup/issue-223-chore-document-the-library-api-stability/2026-10-13T14-42-53 points at the worktree's pre-move HEAD (taken before the move / failed checkout) — restoring it (git checkout refs/pi-rukas/lens-fix-backup/issue-223-chore-document-the-library-api-stability/2026-10-13T14-42-53) returns the tree to the exact state the guard refused to discard, so nothing was lost to the park. Before re-running, inspect the evidence above and decide whether to restore from the backup, commit the unlanded work onto the branch, or clean the tree. The cycle halted rather than dispatching a fix onto a stale or diverged worktree, because a fix built there would not integrate cleanly (the #978 shape: round 2 built on the old base while the branch advanced by round 1). Inspect the worktree and the evidence above — commit or clean uncommitted work, land the missing commit on the branch, or restore from the backup ref — then re-run the cycle

What was attempted

• explore 26.4s · explore
• plan 19.7s · plan
• branch 2.6s · driver:branch
• develop 55.0s · developer
• adversarial 27.7s · adversarial_loop
• commit-pr 6.4s · driver:commit-pr
• lens-review 38.8s · lens-review×6 (round 1)
• lens-fix 58.0s · developer:lens-fix-1
• adversarial 1m44s · adversarial_loop
• lens-review 32.6s · lens-review×6 (round 2)

Worktree state at handoff

• HEAD: 09bef3d
• branch exists locally: yes
• branch pushed to origin: yes
• uncommitted: 0 files (0 staged, 0 unstaged)
• committed work on detached-HEAD worktrees (the porcelain counts above are blind to this):
  • /Users/janni/projects/oo/.worktrees/issue-223-default — HEAD 658f5326, 3 commit(s) ahead of base (workstream: default)

Review findings — 1 MEDIUM, 2 LOW (verdict: ISSUES_FOUND)

• MEDIUM ARCHITECTURE — docs/architecture.md:251 — Library "public surface" boundary is ambiguous
• LOW SIMPLICITY — docs/architecture.md — Point-in-time changelog embedded in architecture doc will go stale
• LOW ARCHITECTURE — docs/architecture.md:255 — Point-in-time changelog embedded in standing design doc

Patterns to look for:

• Same lens flagging the same shape across rounds → spec-level problem (MAST 41.77%)
• Orthogonal local bugs → genuine work remains, not a doctrine failure

Concrete recovery commands

Pick one:

# The driver could not consolidate the work (no local branch, or a cherry-pick conflict).
# (repoRoot restore not recorded)

# 1. The work lives in these worktrees (detached HEADs, commits ahead of the base):
git -C /Users/janni/projects/oo/.worktrees/issue-223-default log --oneline -5   # HEAD 658f5326 · 3 commit(s) ahead

# 2. Cherry-pick each worktree's commits onto the feature branch (run from the main checkout):
git checkout feature/issue-223-chore-document-the-library-api-stability
git cherry-pick 658f532674dd7b41a4b6fdf52f06b5b1d50595d0   # worktree: /Users/janni/projects/oo/.worktrees/issue-223-default (HEAD 658f5326)

# 3. Push the branch:
git push -u origin feature/issue-223-chore-document-the-library-api-stability

# 4. Or abandon the cycle and start over (the worktrees are preserved):
rm .pi/work-state/223.json
/work 223 --restart

Transcripts (last 5)

• adversarial_loop — /Users/janni/.pi/agent/ensemble-runs/2026-10-13/mv6sfxer-supgv9-adversarial-developer-round2-review.json
• developer:lens-fix-1 — /Users/janni/.pi/agent/ensemble-runs/2026-10-13/mv6seolj-t8kktl-developer.json
• adversarial_loop — /Users/janni/.pi/agent/ensemble-runs/2026-10-13/mv6sd1ex-94pg2d-adversarial-developer-round1-review.json
• developer — /Users/janni/.pi/agent/ensemble-runs/2026-10-13/mv6sbudh-soszj6-developer.json
• plan — /Users/janni/.pi/agent/ensemble-runs/2026-10-13/mv6sbd5w-baa8bs-explore.json

Inspect further

• Rich state + full event log: .pi/work-state/223.json
• Per-subagent transcripts (preserved on handoff): tmp/issue-223/
• This body file: tmp/issue-223/handoff-comment.md

[randomm]

Six-pass review — residual findings (round disclosure)

The lens review verdict is ISSUES_FOUND; nothing listed here has been fixed.
None is CRITICAL and the adversarial gate passed the diff, so a round-capped
review may carry these forward — but they are recorded here so a merge is never
silent about them. Decide them before merging.

• [MEDIUM] docs/architecture.md:0 — Hidden items "may change in any release" contradicts minor-version policy (ARCHITECTURE)

[randomm]

Six-pass review — residual findings (round disclosure)

The lens review verdict is ISSUES_FOUND; nothing listed here has been fixed.
None is CRITICAL and the adversarial gate passed the diff, so a round-capped
review may carry these forward — but they are recorded here so a merge is never
silent about them. Decide them before merging.

• [MEDIUM] docs/architecture.md:254 — Doc ratifies internal CLI modules as semver-bound public API (ARCHITECTURE)
• [LOW] docs/architecture.md:47 — Full signatures duplicated in two places, adding upkeep (SIMPLICITY)
• [LOW] docs/architecture.md:253 — Process guidance in the architecture doc duplicates commit policy (SIMPLICITY)
• [LOW] docs/architecture.md:254 — Mixed signals on whether hidden items are supported (ARCHITECTURE)

[randomm]

Follow-ups from PR #224:

• Design question: should the argv and commands modules be pub(crate), or should the library expose a documented facade instead of hidden pub modules? Whether they stay public at all needs a separate ticket.
• Full signatures appear in a few places in docs/architecture.md (module table, key functions, change list). Consider linking to rustdoc instead so they cannot drift.
• The process sentence about commit marking duplicates release policy; consolidate to one location.
• Behavioral (non-signature) changes, such as Vipune store error semantics, are not listed in the breaking-changes record. Decide whether the record should cover them.