docs(plans): implementation plans for issues #117, #118, #119, #121

plans/20260810-docs-truth-gate-audit/ISSUE-COMMENT.md

@@ -0,0 +1,64 @@
+## Issue-to-Plan Handoff — #117
+
+Plan: `plans/20260810-docs-truth-gate-audit/plan.md` (5 phases, docs + CI-posture
+only). Validate: **PASS**. Red-team: **5 findings, all applied**.
+
+### Phases
+
+| # | Title | Effort | Depends on | DoD |
+| - | ----- | ------ | ---------- | --- |
+| 01 | `STATE.md` truth refresh + anti-drift rule | M | — | 1, 2 |
+| 02 | PR #112 reconciliation against the north star | S | — | 3 |
+| 03 | Gate / E2E-shard evidence audit (read-only) | M | — | 4 (evidence) |
+| 04 | Founder decision: smoke shards required or advisory | S | 03 (+ #114 triage, soft) | 4 (decision) |
+| 05 | Worktree hygiene with an unmerged-work safety gate | S | — | 5 |
+
+01–03 are independent and touch disjoint files. All 5 DoD checkboxes are mapped.
+
+### Key design decisions
+
+- **Item 3 is already answered by the code — no investigation phase needed.** The
+  Gate genuinely ignores the smoke shards, on purpose: `nuncio-crew-ci.yml:258`
+  sets `continue-on-error: true`, `:320` omits the job from `gate.needs`, and
+  `nuncio-crew-ci-contract.test.mjs:150` *asserts* that omission. The in-line
+  comment at `:248-251` names #36/#37. So PR #114's SUCCESS-over-red-shards is
+  designed behavior, not a mis-reported run. The real defect is that
+  `docs/crew/CI.md:15-23` never mentions the smoke job, so a green gate reads as
+  "E2E passed". Phase 03 documents it; Phase 04 asks whether to change it.
+- **Recommendation: keep the shards advisory until #109 and #110 close.** Making
+  a known-broken lane required red-walls every desktop PR without fixing a test.
+  The founder decides; the plan does not flip the gate.
+- **Item 4's premise is wrong and the plan corrects it.**
+  `.worktrees/bring-hermes-chat-into-crew` is *not* merged residue: its branch has
+  6 commits not on `main` and not on PR #114's head. `git cherry` is unusable here
+  (squash-merge rewrites patch-ids, so it flags even the commit that merged as
+  #113). Phase 05 splits into a safe `git worktree prune` of the 24 prunable
+  `buzz-ae-e2e-*` entries, and a **gated** removal that defaults to no action.
+- **Scope kept honest:** Phase 01 also fixes stale claims the issue did not list —
+  the Buzz pin at `STATE.md:94-95` says `0.5.3` while `upstream-buzz.json` says
+  `0.5.7`, and `:72` claims Settings shows `v0.5.3` while the app is `0.5.7`.
+- **PR #112: recommend close-with-reason**, after copying its #110 root-cause
+  bisect onto issue #110 so the evidence survives.
+
+### Seams (all Crew-owned — 0 upstream lines expected)
+
+- Gate aggregation: `.github/workflows/nuncio-crew-ci.yml:317` / `:320`
+- Gate pass/fail rule: `desktop/scripts/check-nuncio-crew-ci-results.mjs:6`
+- RED contract seam: `desktop/src/testing/nuncio-crew-ci-contract.test.mjs:130-156`
+- Agent obligations: `docs/crew/AGENT-WORKING-AGREEMENT.md:81`
+- Merge-contract doc: `docs/crew/CI.md:15-23`
+- Temp-worktree source: `desktop/tests/e2e/helpers/twoRelayHarness.ts:36` (read-only)
+
+Upstream's `.github/workflows/ci.yml:295` *does* aggregate smoke — inherited,
+read-only, not Crew's to change. All PRs target `Nuncio-hq/crew` (D-020).
+D-025 generic-ACP check: **N/A, explicitly** — no wire contract, event kind, or
+engine-specific behavior is introduced.
+
+### Open questions
+
+1. Should the anti-drift rule get a CI guard, or stay review-visible prose only?
+   (Issue asks for a rule; plan ships prose + a decision entry.)
+2. The `buzz-ae-e2e-*` leak recurs from the e2e harness. Prune only, or file a
+   separate issue to fix the harness cleanup?
+3. Confirm PR #112 should be closed rather than revised — it belongs to another
+   session's branch.

plans/20260810-docs-truth-gate-audit/phase-01-state-truth-and-anti-drift-rule.md

@@ -0,0 +1,103 @@
+---
+phase: 01
+title: STATE.md truth refresh + anti-drift rule
+status: pending
+priority: high
+effort: M
+dependencies: []
+---
+
+# Phase 01 — `STATE.md` truth refresh + anti-drift rule
+
+- **Issue:** #117 — problem item 1; DoD checkboxes 1 and 2
+- **PR scope:** docs only. No code, no CI config, no runtime behavior.
+- **Files:** `docs/crew/STATE.md`, `docs/crew/AGENT-WORKING-AGREEMENT.md`,
+  `docs/crew/DECISIONS.md`
+- **Upstream files touched:** none (all three verified absent from `upstream/main`)
+
+## Context
+
+`docs/crew/STATE.md:16` claims the implementation slices below it "remain the
+code truth for what is built today", and `IDENTITY.md:39` sends every agent there
+for current fork state. The file is wrong in at least six places, so agents
+sequence work off false state. This has recurred with no rule preventing it.
+
+## Stale-claim inventory (verified 2026-08-10)
+
+| `STATE.md` | Claims | Observable reality | Source |
+| ---------- | ------ | ------------------ | ------ |
+| `:180-182` ("Current gate") | the `0.0.6` branch "is not merged", `crew-v0.0.6` "is not published", `0.0.5 → 0.0.6` updater relaunch pending | `crew-v0.0.6` published 2026-08-01; `crew-v0.0.9` is **Latest** since 2026-08-07 | `gh release list --repo Nuncio-hq/crew` |
+| `:222` | "No `crew-v0.0.6` tag or public `0.0.6` artifact has been created" | same as above — four releases past it | `gh release list` |
+| `:94-95` | Buzz source pin `0.5.3` at `3a96acea09b4…` | `0.5.7` at `f167818d25dd…` | `docs/crew/upstream-buzz.json` |
+| `:72` | Settings displays `v0.5.3 · Local` | version is `0.5.7` | `desktop/package.json:4`, `desktop/src-tauri/tauri.conf.json:4` |
+| attention/recovery line | absent | shipped through #108 (`6793c86da`) and #113 (`304173e42`); #114 open | `git log --oneline origin/main` |
+| roles track | absent | issue #116 is the head; PR #120 open | `gh issue list`, `gh pr list` |
+| Hermes track `:255-257` | "Next gates: Slice 2 …" | still accurate — Slice 2 not merged | verified, leave as-is |
+
+## Steps
+
+1. Rewrite `## Current gate` (`STATE.md:177-185`) to state the real release
+   position: releases published through `crew-v0.0.9` (2026-08-07), the
+   thread-worktree `0.0.6` line merged and released, and whatever updater
+   verification genuinely remains — do **not** carry the `0.0.5 → 0.0.6` phrasing
+   forward if the newer releases superseded it. If the updater relaunch was never
+   verified on any pair, say that plainly instead of dropping the obligation.
+2. Fix `:222` in `## Current test gate` the same way.
+3. Correct the Buzz source pin (`:94-95`) and the Settings version string (`:72`)
+   to match `upstream-buzz.json` and `desktop/package.json`. Prefer pointing at
+   `upstream-buzz.json` as the machine-readable source over restating the numbers,
+   so this line cannot drift again.
+4. Add an attention/recovery line to the implementation record: merged through
+   #113; **PR #114 open as a follow-up at time of writing** (name it as in-flight,
+   not as shipped — see `AGENT-WORKING-AGREEMENT.md:40` on not hiding open work).
+5. Add the Hermes track's current position (Slice 0–1 complete, Slice 2 next —
+   already at `:255-257`, verify rather than duplicate) and reference issue #116
+   as the roles track head with PR #120 in flight.
+6. Stamp `Last updated:` with the real merge-day date.
+7. Add the anti-drift rule to the **implementation checklist** at
+   `AGENT-WORKING-AGREEMENT.md:81-87`, as a new checkbox in the existing list
+   style:
+   > - [ ] Shipped state changed (release published, slice merged, gate changed)
+   >   → update [`STATE.md`](STATE.md) in the **same** PR
+8. Append the rule to `docs/crew/DECISIONS.md` as the next free ID (**D-028** as
+   of 2026-08-10 — re-check the tail before writing, PR #120 may land one first).
+   Per `AGENT-WORKING-AGREEMENT.md:87`, a new sticky choice gets a decision entry.
+   Status Accepted, dated, linking the working agreement.
+
+## Contracts
+
+| Scenario | Expected result | Forbidden |
+| -------- | --------------- | --------- |
+| Agent reads `STATE.md` to sequence work | every release/version/merge claim matches live repo state on the merge date | inventing a release, slice, or verification that did not happen |
+| Agent opens a PR that publishes a release or changes the gate | checklist tells them to update `STATE.md` in that PR | rule living only in a plan file or PR description |
+| In-flight work (#114, #120) | named as open, with its state | described as shipped |
+
+## Validation
+
+Spot-check every assertion in the refreshed file against live state on the PR's
+head — this is the issue's own verification bar ("no claim in the refreshed file
+contradicts observable repo state"):
+
+```bash
+gh release list --repo Nuncio-hq/crew --limit 10
+git log --oneline origin/main -10
+gh pr list --repo Nuncio-hq/crew --state open
+cat docs/crew/upstream-buzz.json
+grep -n '"version"' desktop/package.json
+```
+
+Then `just ci` on the branch. Docs-only paths mean the desktop jobs skip and
+`NuncioCrew Gate` accepts the deliberate skips (`docs/crew/CI.md:11-13`).
+
+**This PR must itself satisfy DoD checkbox 1** — it changes `STATE.md`, so it is
+trivially compliant with the rule it introduces; state that in the PR body.
+
+## Risk and rollback
+
+- **Risk:** the file is re-stale by merge time (PRs #114/#120 in flight).
+  Mitigation: write state as-of a named date with open PRs listed as open; re-run
+  the spot-check on the exact merge head.
+- **Risk:** over-editing turns a state record into a changelog. Mitigation: keep
+  the existing section structure; change claims, not organization.
+- **Rollback:** docs-only single PR — `git revert` restores prior text with no
+  runtime effect.

plans/20260810-docs-truth-gate-audit/phase-02-pr-112-north-star-reconciliation.md

@@ -0,0 +1,92 @@
+---
+phase: 02
+title: PR #112 reconciliation against the north star
+status: pending
+priority: high
+effort: S
+dependencies: []
+---
+
+# Phase 02 — PR #112 reconciliation against the north star
+
+- **Issue:** #117 — problem item 2; DoD checkbox 3
+- **PR scope:** either a revision commit on `docs/plans-open-issues`, or a close
+  with a recorded reason. No code either way.
+- **Target repo:** `Nuncio-hq/crew` only (D-020).
+
+## Context
+
+PR [#112](https://github.com/Nuncio-hq/crew/pull/112) "docs(plans): execution
+plans for the six open issues" was opened 2026-08-09T03:59Z. It adds seven
+docs-only files:
+
+```
+plans/20260809-0355-open-issues-sequencing/plan.md      (index, 78 lines)
+plans/20260809-0400-e2e-shard4-revival/plan.md          (#109)
+plans/20260809-0405-channel-question-card/plan.md       (#110)
+plans/20260809-0410-file-size-ratchet-upstream-files/plan.md (#111)
+plans/20260809-0415-channel-first-missions/plan.md      (#102)
+plans/20260809-0420-hermes-first-class-operations/plan.md (#104)
+plans/20260809-0425-agent-attention-recovery/plan.md    (#105)
+```
+
+It predates the north star: `FOUNDER-PRODUCT.md` and D-025/D-026/D-027 landed
+2026-08-10 via #115 (`06107122b`), and issue #116 (agent roles) did not exist when
+#112 was written. Its sequencing index is the risk — merging a *sequencing
+authority* that predates the locked product direction commits Crew to an ordering
+nobody re-checked.
+
+Note what #112 already got right and do not discard it: it carries a real bisect
+for #110 (`AppShell.tsx` → `useLiveHomeFeedActions` subscription races the test's
+readiness gate) and corrects the issue's own stated cause. That evidence is
+worth keeping wherever it ends up.
+
+## The decision
+
+Two options. **Recommended: B.**
+
+| | A — revise and merge | B — close with recorded reason |
+| - | -------------------- | ------------------------------ |
+| Work | push a revision commit reconciling the index with `FOUNDER-PRODUCT.md`, D-025–D-027, and #116/#120 | comment on #112 linking the superseding issues, close, keep nothing on disk |
+| Pro | preserves the #110 bisect and the per-issue plans in-tree | no stale sequencing authority; each issue keeps its own plan as it is planned |
+| Con | requires pushing to a branch this session does not own; the index needs re-deciding against a product direction that changed under it; #105 and #108 have since merged, so parts are already historical | loses the #110 bisect unless it is copied into #110 first |
+| Thin-fork / drift | a sequencing index is a stateful record, not evergreen authority (`documentation-management` rule) — keeping it invites future agents to treat it as law | matches how the other five issues are being planned today (one plan dir per issue, at planning time) |
+
+**Recommendation rationale:** #112's own body says #102/#104/#105 keep their specs
+in the issue bodies and the plan files add only status, coupling, and ordering.
+Ordering is exactly the part the north star and #116 invalidated, and status is
+already stale (#105/PR #108 merged, #113 merged). What survives is the #110
+bisect — which belongs on #110 regardless.
+
+## Steps
+
+1. Re-read #112's index (`plans/20260809-0355-open-issues-sequencing/plan.md`)
+   against `docs/crew/FOUNDER-PRODUCT.md`, D-025/D-026/D-027, and issues
+   #116/#121. Write down each ordering claim that the north star changed.
+2. **Before touching the branch**, confirm ownership — #112 was authored by a
+   different session. If it has a live owner, hand them this phase's finding
+   rather than pushing.
+3. If B: copy the #110 root-cause bisect table into a comment on issue #110 so the
+   evidence survives, then close #112 with a comment naming the superseding
+   issues (#116, #117, #121) and stating the reason: *sequencing index predates
+   the locked founder product direction; per-issue plans are being produced at
+   planning time instead*.
+4. If A: push one revision commit that rewrites the index against the north star
+   and drops the already-shipped entries (#105/#108, #113), then merge through
+   `NuncioCrew Gate`.
+5. Record which option happened, and where, in this phase file's status line.
+
+## Validation
+
+- The resolution is **visible on the PR itself** (issue #117's stated bar): either
+  a merge commit, or a closing comment that names the superseding issues.
+- If B: the #110 bisect is present on issue #110 before #112 closes.
+- No product-code change in either option; no `block/buzz` PR (D-020).
+
+## Risk and rollback
+
+- **Risk:** pushing to a branch owned by another session mid-flight. Mitigation:
+  step 2's ownership check is a hard gate.
+- **Risk:** closing loses evidence. Mitigation: step 3 preserves the bisect first.
+- **Rollback:** a closed PR can be reopened; a revision commit can be reverted on
+  the branch before merge.