chore: M012 release bookkeeping (v0.1.5) + reserve M014

Mark M012 done+released across STATE/ROADMAP; add M012 gotchas to KNOWLEDGE (literal-fence crash, session_id-on-stdin, cache-vs-source, slice-detector, worktree number collision); note reassess-roadmap backlog-sweep in QUICKSTART; reserve M014 for the vendor-symlink work to resolve the M012 numbering collision.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: lx-0

.ytstack/KNOWLEDGE.md

@@ -61,6 +61,12 @@ Patterns, rules, and lessons learned while building ytstack. This file is read b
 
 - **`RemotePluginSync` (Claude Desktop + SSH) refuses ANY symlink in a plugin directory and aborts the whole sync.** Reported failure: `RemotePluginSync: refusing symlink in plugin directory: vendor/gstack/bin/gstack-brain-reader`. Sources of symlinks in this repo: vendored upstream symlinks (e.g. `vendor/gstack/connect-chrome`, `vendor/gstack/bin/gstack-brain-reader`, `vendor/superpowers/AGENTS.md -> CLAUDE.md`) AND, since 2026-05-31, our own repo-root `CLAUDE.md -> AGENTS.md` shim. Native install on the remote host is unaffected; only Desktop+SSH-sync trips it. UNVERIFIED for the new root symlink -- verification path: install via a Desktop SSH session against a remote host and watch for the `refusing symlink` error. Mitigation sketch (from an old, superseded draft in the `claude/thirsty-bhabha-a03490` worktree): dereference symlinks in `sync-upstream.sh` after each subtree pull (`find vendor -type l | ... rm + cp -R`), idempotent. Not yet planned as a milestone.
 
+- **A literal triple-backtick inside a `` ```! `` executable block crashes the preamble for every user.** (M012 / issue #20) The harness extracts the executable block by scanning for the next fence; a literal triple-backtick in a `sed`/`awk` pattern (e.g. `sed -n '/^```/,...'`) terminates the extraction early, so the captured bash is truncated and fails with `unmatched '` / `parse error`. Environment-independent. Fix: generate the fence at runtime with `_FENCE=$(printf '\140\140\140')` and match fences by PREFIX (`index($0,f)==1`, handles language-tagged opening fences like `` ```bash ``); never write a literal triple-backtick inside the block. This crashed `verification-before-completion` AND, on spawn, the `ytstack:implementer` / `ytstack:verifier` subagent types -- they run a skill preamble at startup, so a broken preamble takes the agent down before it does any work.
+- **Hooks receive `session_id` on stdin JSON, not from an env var.** (M012 / issue #21-RC2) There is no `CLAUDE_SESSION_ID` env var; reading it always yields the fallback, so `session-end` recorded `session_id:"unknown"` on every entry. Fix: capture stdin once near the top (`INPUT=$(cat)`) and parse `printf '%s' "$INPUT" | jq -r '.session_id // "unknown"'`. Available hook env vars are `CLAUDE_PROJECT_DIR`, `CLAUDE_PLUGIN_ROOT`, `CLAUDE_PLUGIN_DATA`, `CLAUDE_ENV_FILE`, `CLAUDE_EFFORT`, `CLAUDE_CODE_REMOTE` -- none carry the session id.
+- **Subagents load skills/hooks from the installed plugin CACHE, not your working tree.** A fix committed to the repo is INERT in the running session until a version bump + release + `/plugin update`. Corollary: a bug in a published skill (e.g. #20) keeps reproducing in-session and crashes ytstack subagent types even after you have committed the fix. Dev workaround when a ytstack skill is broken: dispatch `general-purpose` agents with self-contained prompts (they do not auto-run the broken ytstack preamble) instead of the `ytstack:*` agent types.
+- **`slice-milestone` detects unplanned slices only by the literal string "(to be planned)".** (M012) If `plan-milestone` pre-fills the slice goals in the roadmap, the detector finds zero unplanned slices and short-circuits even though no `M###-S##-PLAN.md` files exist yet. More robust signal: presence of the per-slice PLAN files, not the placeholder text.
+- **Uncommitted milestone planning in a stale worktree causes number collisions.** (M012) A prior session left an uncommitted "M012 = vendor symlink dereferencing" plan in the `claude/thirsty-bhabha-a03490` worktree; because it never reached `main`, a later session reused M012 for the swarm fix-pack. Lesson: reserve milestone numbers in the committed `ROADMAP.md` table, never only in an uncommitted worktree. The vendor-symlink work is reserved as M014.
+
 ## Terminology
 
 - **Milestone (M###):** a shippable chunk of the roadmap. 1-7 slices per milestone.

.ytstack/ROADMAP.md

@@ -29,8 +29,9 @@ Progress legend: `[ ]` todo, `[~]` in progress, `[x]` done, `[-]` skipped.
 | M009 | Docs & Community | **done** | 4 | 4 |
 | M010 | Workflow Reorder + Brownfield-Without-.ytstack | planned | TBD | 0 |
 | M011 | Post-Summarize Lifecycle (5-skill cherry-pick: ship + closure + PR-review + document-release) | planned | TBD | 0 |
-| M012 | Swarm Fix-Pack (issues #16/#19/#20/#21: verification crash, advisory-hook exit, slice/task SSOT, session_id, backlog-sweep) | **done** (landed on main, not yet released) | 11 | 11 |
+| M012 | Swarm Fix-Pack (issues #16/#19/#20/#21: verification crash, advisory-hook exit, slice/task SSOT, session_id, backlog-sweep) | **done** (released v0.1.5) | 11 | 11 |
 | M013 | spawn-milestone-team worktree mode (default-on worktree-per-teammate for parallel slices + merge step + shared-tree opt-out; per DECISIONS 2026-05-31 "ytstack encourages git worktree isolation") | planned | TBD | 0 |
+| M014 | Vendor symlink dereferencing for RemotePluginSync compatibility (number reserved 2026-05-31 to resolve the M012 collision; uncommitted draft + README "Desktop + SSH" workaround in the `claude/thirsty-bhabha-a03490` worktree -- salvage/re-plan separately) | planned | TBD | 0 |
 
 **Total:** 39 tasks across M001-M009, 37 done (95%). 2 deferred to user action (git init + push, GitHub repo creation). M010 + M011 task counts pending milestone planning.
 

.ytstack/STATE.md

@@ -1,15 +1,15 @@
 ---
 project: ytstack
 slug: ytstack
-last_updated: 2026-05-31T09:30:00Z
+last_updated: 2026-05-31T10:10:00Z
 current_milestone: M012
 active_slice: none
 active_task: none
 ---
 
 # State
 
-**Status:** M012 DONE -- all 4 slices landed on `main` (not yet released). Executed via worktree-isolated swarm (3 general-purpose teammates in `Agent(isolation:'worktree')` + 1 verifier; the ytstack:implementer/verifier agent types crashed on spawn ON issue #20 itself -- live proof it was P0). Commits: `015f988` #19, `da41845` #20, `b7a5695` #21-RC1+#16, `2af326e` #21-RC2. plan-eng-review (2026-05-31) locked 3 decisions: active_slice plan-task-owned + team-member-guarded; swarm commit discipline; ytstack encourages git worktree isolation for parallel swarms (-> M013). **CACHE CAVEAT:** the fixes are in source on main but NOT live this session -- ytstack skills/hooks run from installed plugin cache 0.1.4; they activate only after a version bump + release + `/plugin update`. So #20's crash still reproduces if a ytstack skill with the buggy preamble is invoked in THIS session. Not pushed. M010/M011/M013 still queued. See `M012-ROADMAP.md` + DECISIONS.md (3 new entries 2026-05-31).
+**Status:** M012 DONE + RELEASED as **v0.1.5** (tagged + pushed). All 4 slices landed on `main` and pushed to origin. Executed via worktree-isolated swarm (3 general-purpose teammates in `Agent(isolation:'worktree')` + 1 verifier; the ytstack:implementer/verifier agent types crashed on spawn ON issue #20 itself -- live proof it was P0). Commits: `015f988` #19, `da41845` #20, `b7a5695` #21-RC1+#16, `2af326e` #21-RC2. Independently re-verified 2026-05-31: #19/#20/#21-RC2 behavior-tested; #21-RC1 bash+guard verified (frontmatter-write is prose, exercised only when the skill runs live). plan-eng-review locked 3 decisions: active_slice plan-task-owned + team-member-guarded; swarm commit discipline; ytstack encourages git worktree isolation (-> M013). **CACHE CAVEAT:** fixes go live for users after `/plugin update` to 0.1.5; in THIS session the cached 0.1.4 is still active (so #20 still reproduces here). **M012 numbering collision:** a prior uncommitted plan in the `claude/thirsty-bhabha-a03490` worktree had named the vendor-symlink work "M012" -- reserved as **M014** (separate, to be planned). Queued: M010, M011, M013, M014. See `M012-ROADMAP.md` + DECISIONS.md.
 
 **Prior status (full build cycle):** Full build cycle complete + post-M009 patches landing + plugin landscape architecture locked. 38/39 roadmap tasks done; 1 deferred (v0.1.0 tag + push -- user action). End-of-cycle review in progress. First interactive smoke-test of `init-project` done 2026-04-24 (partial; surfaced multiple items -- see REVIEW-NOTES). Three workflow infographics now in README as visual reference for upcoming brownfield + debug live-tests. Sibling-plugin landscape (`ystacks` catalog + `yastack` public + `ydstack` / `yastack-internal` subdirs) shipped 2026-04-25 (afternoon).
 
@@ -77,11 +77,11 @@ M009 Docs & Community            [####]   4/4  DONE
 
 ## Next action
 
-**M012 landed on main; decide release + closure.** Open items:
-1. **Push** `main` (4 M012 commits + the planning/#19 commits) when ready -- not pushed yet.
-2. **Version bump + release** (e.g. 0.1.5) so the fixes go live -- they are inert in the cached 0.1.4 plugin until released + `/plugin update`. `.claude-plugin/plugin.json` is already dirty (user edit) -- coordinate the version bump with that.
-3. **Formal milestone closure** via `ytstack:reassess-roadmap` (also dogfoods the new backlog-sweep) -- but note the cached 0.1.4 reassess-roadmap lacks our changes, so it would run the OLD behavior until release. Per-task SUMMARY files via `summarize-task` optional.
-4. Then the queued work: M010 (brownfield = issue #18), M011 (post-summarize lifecycle), M013 (spawn-milestone-team worktree mode), agentic-foundation migration.
+**M012 shipped (v0.1.5, pushed). Issues #16/#19/#20/#21 closed.** Remaining / queued:
+1. **`/plugin update`** to 0.1.5 in any active session to make the fixes live (cached 0.1.4 still active here).
+2. **Cross-repo marketplace sync** (NOT done -- needs separate authorization): the `ystacks-internal` catalog lists ytstack; confirm it picks up v0.1.5 (per the "Plugin-Marketplace-Aenderung = README-Update" rule). Out of this repo's scope.
+3. **M014 -- vendor symlink dereferencing for RemotePluginSync** (separate): uncommitted draft + README "Desktop + SSH" workaround live in the `claude/thirsty-bhabha-a03490` worktree; salvage or re-plan separately. Worktree intentionally left in place (holds the only copy).
+4. Queued milestones: M010 (brownfield = issue #18), M011 (post-summarize lifecycle), M013 (spawn-milestone-team worktree mode), M014 (vendor symlink). Plus agentic-foundation migration.
 
 ---
 

QUICKSTART.md

@@ -128,7 +128,7 @@ You don't orchestrate the transitions -- the agent does, based on each skill's T
 
 ### 9. "Reassess between slices"
 
-At the end of each slice, say: "Does the roadmap still fit reality?" -> `ytstack:reassess-roadmap` reads recent summaries, surfaces deviations, prompts for roadmap changes (add / split / reorder / remove slices).
+At the end of each slice, say: "Does the roadmap still fit reality?" -> `ytstack:reassess-roadmap` reads recent summaries, surfaces deviations, prompts for roadmap changes (add / split / reorder / remove slices). At milestone close it also sweeps the backlog items that were folded into the milestone, prompting per item to keep, trim, or drop.
 
 ### 10. Close the milestone