From 19e1b89bc69c97a5affa007826f0ecff499dfec1 Mon Sep 17 00:00:00 2001 From: Enrico Piovesan Date: Sat, 5 Sep 2026 22:07:12 -0600 Subject: [PATCH] docs: apply blocked-tickets brainstorm board hygiene Record ownership decisions and align AGENTS/plan/contract docs with Project 2: Mode B Future, cutover absorbed, lifecycle Ready (fixture DoD), Mode A still Blocked on Traverse #1241. Co-authored-by: Cursor --- AGENTS.md | 8 +- apps/llm-mcp-reference/README.md | 2 +- docs/adr/0006-two-app-reuse-contract.md | 2 +- docs/decision-log.md | 124 ++++++++++++++++++++++++ docs/llm-reference-apps-plan.md | 6 +- docs/two-app-reuse-contract.md | 6 +- 6 files changed, 137 insertions(+), 11 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index ee54fc7..5f518d4 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -32,20 +32,20 @@ gh project item-list 2 --owner traverse-framework --format json --limit 300 \ | `new-app-author-e2e` | **Done** (#275) | CLI `app new` → App-Refs layout + Web host rewrite | | `fix-nightly-native-macos-windows` | **Done** (#277) | Swift 6 Sendable mappers + WinUI test compile of PresentationMapper | | `llm-mcp-mode-a-spec119-scaffold` | **Done** (#271) | Spec 119 consumer scaffold (fail-closed); live kit execute stays `llm-mcp-traverse-starter-catalog` | -| `llm-mcp-traverse-starter-catalog` | **Blocked** | Live kit execute blocked on Traverse [#1241](https://github.com/traverse-framework/Traverse/issues/1241) (Spec 119 Mode A implement) | +| `llm-mcp-traverse-starter-catalog` | **Blocked** | Live kit execute blocked on Traverse [#1241](https://github.com/traverse-framework/Traverse/issues/1241) (Spec 119 Mode A); absorbed Mode A cutover from `llm-mcp-0-10-live-cutover` | | `loop-wf1-registry-deps` | **Done** (#263) | Digest inventory in `docs/loop-registry-deps.md` | | `loop-wf1-multi-os` | **Done** (#265) | `apps/loop/` WF1 × 7 OS; compose via `registry_ref` | | `retire-registry-ref-materialize` | **Done** (#267) | Phase A gate; host cutover → Future `retire-registry-ref-materialize-hosts` | | `retire-registry-ref-materialize-hosts` | **Future** | Full materialize delete after BundleEmbedder + Spec 107 | | `meeting-notes-remaining-natives` | **Done** (#236) | Shipped via `meeting-notes-wave2-os-ports` | -| `llm-mcp-embedded-host` | **Blocked** | Scaffold Done (#268); live Mode B blocked on Traverse [#1242](https://github.com/traverse-framework/Traverse/issues/1242) | +| `llm-mcp-embedded-host` | **Future** | Scaffold Done (#268); Mode B host CLI on Traverse [#1242](https://github.com/traverse-framework/Traverse/issues/1242) — not active until Mode A unlock progresses | | `two-app-reuse-contract` | **Done** (#285) | Pin `meeting-notes.process` 1.3.2 for meeting-notes + loop | | `two-app-reuse-execute` | **Done** (#286) | Align pins + wasmtime evidence | | `two-app-reuse-execute-ci` | **Done** (#287) | Fixture-only evidence (no Traverse core examples) | | `pin-ci-traverse-0-10` | **Done** (#292) | CI / embedder / runtime.wasm → Traverse v0.10.0 | -| `llm-mcp-0-10-live-cutover` | **Blocked** | v0.10.0 Mode A still expedition-only — Traverse [#1241](https://github.com/traverse-framework/Traverse/issues/1241); Mode B host [#1242](https://github.com/traverse-framework/Traverse/issues/1242) | +| `llm-mcp-0-10-live-cutover` | **Done** (absorbed) | Mode A → `llm-mcp-traverse-starter-catalog`; Mode B → `llm-mcp-embedded-host` Future; pin already #292 | | `two-app-reuse-host-execute` | **Blocked** | Traverse [#1240](https://github.com/traverse-framework/traverse/issues/1240) — BundleEmbedder still fails WASI `proc_exit(0)` on 1.3.2 | -| `two-app-reuse-lifecycle` | **Blocked** | After `#282` — upgrade/deprecation outcomes | +| `two-app-reuse-lifecycle` | **Ready** | Fixture pin-flip + documented deprecation for meeting-notes + loop (not BundleEmbedder; not production release-train) | Full gap table + wave notes: [`docs/production-reference-plan.md`](docs/production-reference-plan.md). diff --git a/apps/llm-mcp-reference/README.md b/apps/llm-mcp-reference/README.md index 3b9d43f..d8c9efb 100644 --- a/apps/llm-mcp-reference/README.md +++ b/apps/llm-mcp-reference/README.md @@ -51,7 +51,7 @@ Stronger isolation path: prepare registry deps into a **host-owned verified cach See [`mode-b/README.md`](mode-b/README.md), [`mode-b/mcp.json.example`](mode-b/mcp.json.example), and fail-closed [`mode-b/serve.sh`](mode-b/serve.sh). -**Honest status:** Spec 520 library APIs shipped in Traverse (#860). The Mode B MCP host CLI is **not** shipped (Traverse [#1242](https://github.com/traverse-framework/Traverse/issues/1242)). Expedition Mode A remains the only runnable LLM path on v0.10.0; Mode B launcher exits non-zero until that host exists. +**Honest status:** Spec 520 library APIs shipped in Traverse (#860). The Mode B MCP host CLI is **not** shipped (Traverse [#1242](https://github.com/traverse-framework/Traverse/issues/1242)). App-Refs ticket `llm-mcp-embedded-host` is **Future** (Mode A kit path is the active unlock). Expedition Mode A remains the only runnable LLM path on v0.10.0; Mode B launcher exits non-zero until that host exists. Optional bearer token (execution commands): diff --git a/docs/adr/0006-two-app-reuse-contract.md b/docs/adr/0006-two-app-reuse-contract.md index a0b1b12..ab5644a 100644 --- a/docs/adr/0006-two-app-reuse-contract.md +++ b/docs/adr/0006-two-app-reuse-contract.md @@ -13,7 +13,7 @@ Traverse #1168 requires proof that a published capability is a reusable platform Pin **both** `meeting-notes` and `loop` to public `meeting-notes.process` **1.3.2** (`registry_ref.version_range` exactly `1.3.2`, artifact digest `sha256:ec192a0c2104b08bee76418c5c6d44358036568d655d8465e506858d1aaadbf2`). Full pin, host routes, and current drift: [`../two-app-reuse-contract.md`](../two-app-reuse-contract.md). -This ADR does not implement alignment or execution. `#282` applies the pin and produces evidence. `#283` covers upgrade/deprecation. +This ADR does not implement alignment or execution. `#286` applies the pin and produces evidence. `#283` (`two-app-reuse-lifecycle`) covers fixture-level upgrade/deprecation outcomes (Ready — see decision-log 2026-09-05). ## Consequences diff --git a/docs/decision-log.md b/docs/decision-log.md index 5146c84..56e952b 100644 --- a/docs/decision-log.md +++ b/docs/decision-log.md @@ -384,3 +384,127 @@ Append-only record of design decisions for App-References. Newest sessions at th **Decision:** Exact pin `1.3.2` / digest `sha256:ec192a0c…` for both apps. Record in [`two-app-reuse-contract.md`](two-app-reuse-contract.md) and ADR [`0006`](adr/0006-two-app-reuse-contract.md). No manifest alignment in this ticket. **Why:** Same capability already sits on two `app_id` boundaries with different user-facing purposes. Floating `^` ranges are exactly what #1168 forbids. + +--- + +## 2026-09-05 — Blocked tickets ownership walk + +**Context:** Brainstorm over Project 2 Blocked tickets to classify ownership (on user vs Traverse vs defer) and decide board hygiene vs upstream push order. Live board query was intermittently rate-limited; inventory from `AGENTS.md` + open Traverse issues #1240/#1241/#1242. + +### Brainstorm goal + +**Question:** What should this brainstorm decide? + +**Options considered:** +- Prioritize which Traverse blocker to push next — pros: focuses unlock; cons: skips hygiene +- Decide App-Refs interim workarounds while Traverse is blocked — pros: keeps shipping; cons: fake-runtime risk +- Board hygiene only (keep / Future / narrow DoD) — pros: cleans false urgency; cons: no upstream move +- Walk every blocked ticket and classify ownership — pros: full map; collapses shared root causes; cons: longer + +**Recommendation:** Ownership walk first. + +**Decision:** Walk every blocked ticket and classify (on you / on Traverse / defer). + +**Why:** Three of five share two Traverse issues; a pass usually collapses the set before picking priority or workarounds. + +### LLM MCP cluster + +**Question:** How to classify `llm-mcp-traverse-starter-catalog`, `llm-mcp-embedded-host`, and `llm-mcp-0-10-live-cutover`? + +**Options considered:** +- On Traverse only; leave all Blocked — pros: honest; cons: no prioritization signal +- On user to prioritize/assign Traverse #1241/#1242 — pros: names unlock; cons: needs Traverse ownership +- Defer whole cluster to Future — pros: less Blocked noise; cons: hides Approved Spec 119 wait +- Split: Mode A (#1241) active Blocked; Mode B (#1242) → Future — pros: Mode A unblocks kit path first; cons: cutover umbrella spans both + +**Recommendation:** Split Mode A / Mode B. + +**Decision:** Mode A stays active Blocked on Traverse [#1241](https://github.com/traverse-framework/Traverse/issues/1241); Mode B (`llm-mcp-embedded-host`) → Future on [#1242](https://github.com/traverse-framework/Traverse/issues/1242). + +**Why:** Mode A is the Cursor/Claude kit path; Mode B is a separate host product. + +### Cutover umbrella + +**Question:** What happens to `llm-mcp-0-10-live-cutover` after the Mode A/B split? + +**Options considered:** +- Narrow DoD to Mode A only; stay Blocked — pros: simple; cons: Mode B cutover needs a home +- Split into Mode A + Mode B cutover tickets — pros: clean; cons: overlaps live tickets +- Keep umbrella Blocked on both — pros: no rewrite; cons: Mode B blocks Mode A Done +- Cancel/absorb into `llm-mcp-traverse-starter-catalog` + `llm-mcp-embedded-host` — pros: fewest tickets; cons: lose explicit post-pin checklist unless folded into those DoDs + +**Recommendation:** Absorb/cancel umbrella. + +**Decision:** Cancel/absorb `llm-mcp-0-10-live-cutover` into the Mode A catalog and Mode B embedded-host tickets (pin already Done via `pin-ci-traverse-0-10`). + +**Why:** After the pin, the umbrella duplicates the two live tickets. + +### Two-app host execute + +**Question:** How to classify `two-app-reuse-host-execute` (Traverse [#1240](https://github.com/traverse-framework/Traverse/issues/1240))? + +**Options considered:** +- On Traverse only; leave Blocked — pros: no fake host path; cons: public BundleEmbedder proof incomplete +- On user to prioritize #1240 — pros: names unlock; cons: needs Traverse triage ownership +- Downgrade to Future with materialize-retire wave — pros: less noise; cons: understates open bug +- Accept wasmtime-only as Done; Future/Cancel host-execute — pros: paper-unblocks reuse; cons: weakens public-host proof + +**Recommendation:** Stay honestly Blocked on #1240. + +**Decision:** Leave `two-app-reuse-host-execute` Blocked on Traverse #1240; do not redefine Done around wasmtime alone. + +**Why:** Ticket exists for public BundleEmbedder proof; App-Refs must not invent substitute WASM. + +### Lifecycle predecessor + +**Question:** What to do with `two-app-reuse-lifecycle` (board note still “After `#282`”)? + +**Options considered:** +- Move toward Ready (execute Done is enough) — pros: clears false Blocked; cons: may need registry behaviors +- Retarget Blocked to host-execute / #1240 — pros: if DoD needs BundleEmbedder; cons: couples unrelated concerns +- Future until a real published upgrade/deprecation — pros: live release train; cons: long wait +- Blocked on user for Spec/DoD rewrite first — pros: avoids wrong proof; cons: design beat before Ready + +**Recommendation:** Ready path if DoD is pin/upgrade semantics without BundleEmbedder. + +**Decision:** Not blocked on `#282` (execute already Done as #286) or on #1240; proceed to Ready after DoD is made checkable. + +**Why:** Written scope is upgrade/deprecation outcomes for the shared pin pair; no BundleEmbedder requirement in the contract table. + +### Lifecycle Spec/DoD shape + +**Question:** Before Ready, how to make lifecycle DoD claimable? + +**Options considered:** +- Ready as-is; flesh DoD in implementing PR — pros: fastest; cons: weak claim gate +- Full Spec/DoD rewrite brainstorm first — pros: strongest gate; cons: extra design pass +- Future until registry publishes next `meeting-notes.process` — pros: real train; cons: App-Refs can’t drive calendar +- Fixture-only pin flip + documented deprecation handling (no new registry release) — pros: claimable soon; honest; cons: weaker than production upgrade proof + +**Recommendation:** Fixture-level DoD, then Ready. + +**Decision:** Define DoD around fixture-only pin flip + documented deprecation handling (explicit non-claim of production release-train proof), then set status Ready. + +**Why:** Keeps the ticket honest and claimable without waiting on a registry publish or BundleEmbedder. + +### Next action order + +**Question:** With two honest Blocked tickets left, what to push first? + +**Options considered:** +- Prioritize Traverse #1241 (Mode A kit MCP) — pros: live kit façades; cons: host-execute stays stuck +- Prioritize Traverse #1240 (BundleEmbedder) — pros: completes #1168 host proof; cons: MCP stays expedition-only +- App-Refs board hygiene first; Traverse priority later — pros: lifecycle becomes claimable now; cons: upstream idle briefly +- Parallel triage of #1241 + #1240 plus hygiene — pros: no false sequencing; cons: split attention + +**Recommendation:** Hygiene first, then #1241. + +**Decision:** Apply App-Refs board hygiene first (Mode B → Future; cancel cutover umbrella; Ready lifecycle with fixture DoD; refresh `AGENTS.md` / README blockers). Then push Traverse [#1241](https://github.com/traverse-framework/Traverse/issues/1241) as the higher-leverage remaining Blocked unlock. Leave #1240 Blocked without redefining it. + +**Why:** Hygiene unlocks Ready work without waiting on Traverse; Mode A MCP is the stronger demo unlock of the two remaining upstream bugs. + +### What was explicitly deferred + +- Assigning/staffing Traverse #1240 vs #1241 beyond “#1241 after hygiene” +- Any App-Refs interim workaround that fakes kit MCP or BundleEmbedder success +- Production registry release-train proof for lifecycle (fixture-only by design) diff --git a/docs/llm-reference-apps-plan.md b/docs/llm-reference-apps-plan.md index 1cf47c9..41625c3 100644 --- a/docs/llm-reference-apps-plan.md +++ b/docs/llm-reference-apps-plan.md @@ -76,7 +76,7 @@ Shared: | Mode | When | Notes | |---|---|---| | **A. MCP stdio → local Traverse** (v1 default) | Developer laptop / agent IDE | Expedition bootstrap only on Traverse **v0.10.0** (`cargo run -p traverse-mcp -- stdio`). Spec 119 public-registry host: **scaffolded** under `apps/llm-mcp-reference/mode-a/` (fail-closed). Live kit discover/execute blocked on Traverse [#1241](https://github.com/traverse-framework/Traverse/issues/1241) | -| **B. MCP → embedded host in a sidecar process** | Stronger product isolation | **Scaffolded** under `apps/llm-mcp-reference/mode-b/` (Spec 520 prepare/cache docs + fail-closed launcher). Mode B host CLI **not shipped** — Traverse [#1242](https://github.com/traverse-framework/Traverse/issues/1242) | +| **B. MCP → embedded host in a sidecar process** | Stronger product isolation | **Scaffolded** under `apps/llm-mcp-reference/mode-b/` (Spec 520 prepare/cache docs + fail-closed launcher). Mode B host CLI **not shipped** — Traverse [#1242](https://github.com/traverse-framework/Traverse/issues/1242). App-Refs ticket `llm-mcp-embedded-host` is **Future** (Mode A is the active unlock) | | **C. Remote MCP gateway** | Multi-tenant SaaS | Future; needs auth/tenancy — not this slice | v1 documents **Mode A** only. Do not revive HTTP `traverse-cli serve` as the production architecture for primary OS shells; MCP stdio is a **separate agent façade**, not a replacement for embedded Web/iOS/Android clients. @@ -93,8 +93,8 @@ v1 documents **Mode A** only. Do not revive HTTP `traverse-cli serve` as the pro | `llm-mcp-grok-adapter` | Grok tool-calling mapping | Future / Ready when API stable | | `llm-mcp-mode-a-spec119-scaffold` | Spec 119 Mode A consumer (fail-closed serve + prepare + MCP example) | Done (#271) | | `llm-mcp-traverse-starter-catalog` | Discover/execute kit capabilities (`traverse-starter.*` / meeting-notes) via Mode A public registry discovery | Blocked — Spec [`119-verified-registry-mcp-mode-a`](https://github.com/traverse-framework/Traverse/blob/main/specs/119-verified-registry-mcp-mode-a/spec.md) **Approved**; implement Traverse [#1241](https://github.com/traverse-framework/Traverse/issues/1241). v0.10.0 remains expedition-only. First release has no kit content groups (FR-007). Registry [#99](https://github.com/traverse-framework/registry/issues/99) closed | -| `llm-mcp-embedded-host` | Mode B embedded prepare/cache for MCP host | Scaffold Done (#268); live Mode B host blocked on Traverse [#1242](https://github.com/traverse-framework/Traverse/issues/1242) (Spec 520 host CLI; Mode B out of Mode A spec #1125) | -| `llm-mcp-0-10-live-cutover` | Re-verify Mode A kit execute + Mode B host after Traverse v0.10.0 pin | **Blocked** — pin Done (#292); Mode A kit execute missing on tag → [#1241](https://github.com/traverse-framework/Traverse/issues/1241); Mode B host → [#1242](https://github.com/traverse-framework/Traverse/issues/1242) | +| `llm-mcp-embedded-host` | Mode B embedded prepare/cache for MCP host | Scaffold Done (#268); **Future** until Traverse [#1242](https://github.com/traverse-framework/Traverse/issues/1242) (Spec 520 host CLI). Absorbed Mode B slice of cancelled umbrella `llm-mcp-0-10-live-cutover` | +| `llm-mcp-0-10-live-cutover` | Re-verify Mode A kit execute + Mode B host after Traverse v0.10.0 pin | **Done (absorbed)** — Mode A live proof stays on `llm-mcp-traverse-starter-catalog` (#1241); Mode B on `llm-mcp-embedded-host` Future (#1242); pin Done (#292) | ## Success criteria (plan slice) diff --git a/docs/two-app-reuse-contract.md b/docs/two-app-reuse-contract.md index 0e0aa79..6837544 100644 --- a/docs/two-app-reuse-contract.md +++ b/docs/two-app-reuse-contract.md @@ -97,8 +97,10 @@ Host CLI execute via public `BundleEmbedder` (`meeting-notes-cli` / `loop-cli`) | Ticket | Role | |---|---| -| `#282` `two-app-reuse-execute` | Align meeting-notes pin; execute both apps; publish digest-equal evidence | -| `#283` `two-app-reuse-lifecycle` | Compatible upgrade + deprecation outcomes for the same pair | +| `#286` `two-app-reuse-execute` | Align meeting-notes pin; execute both apps; publish digest-equal evidence (Done) | +| `#287` `two-app-reuse-execute-ci` | Fixture-only CI evidence (Done) | +| `two-app-reuse-host-execute` | Public BundleEmbedder CLI execute — Blocked on Traverse #1240 | +| `#283` `two-app-reuse-lifecycle` | **Ready** — fixture pin-flip + documented deprecation for the same pair (not BundleEmbedder; not production release-train). See `docs/decision-log.md` 2026-09-05 | ## Re-verification