feat(project-bootstrap): canonical template + Step 5.6 add session-handoff trigger [v1.12.0]

CLAUDE.md.template gains `session handoff: read on start, write on end`
between `pull remote before work` and `follow project discipline`
(session-lifecycle clustering). Step 5.6 trigger->fulfiller table gains
the corresponding row (template ↔ table source-of-truth invariant).

Greenfield-bootstrap'ed projects now ship handoff trigger из коробки.
Existing projects unaffected — CLAUDE.md merge in Step 5 is idempotent
and respects user removals.

Bump 1.11.0 -> 1.12.0 MINOR (new canonical trigger = new capability,
backward-compatible). dist/project-bootstrap.skill rebuilt.

Closes [session-handoff-bootstrap-template-extend].
Unblocks [session-handoff-existing-projects-upgrade] Path B.

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

.tasks/STATUS.md

@@ -1,5 +1,5 @@
 # Task Board
-_Updated: 2026-05-22 (interns-grep-audit-skill-updates closed 🟢 — using-interns v0.2.2→0.3.0 with 3 routing rows for `grep_audit` deterministic intern plus consistency adds; unblocks half of `[interns-grep-audit-review]`.)_
+_Updated: 2026-05-24 (session-handoff кластер: install + bootstrap-template-extend 🟢; project-bootstrap 1.11→1.12.)_
 
 <!--
   Canonical layout. One block per task. Per-task deep context lives in
@@ -1338,21 +1338,18 @@ Findings — отдельные follow-up tasks (`using-vds-ops-<gap>-fix` ил
 
 ---
 
-## ⚪ [session-handoff-install] — Установить скил session-handoff в активный CC: запустить install.sh из ~/projects/claude-skills/, выполнить /reload-plugins, убедиться что скил активируется в новой сессии.
+## 🟢 [session-handoff-install] — Установить скил session-handoff в активный CC: запустить install.sh из ~/projects/claude-skills/, выполнить /reload-plugins, убедиться что скил активируется в новой сессии.
 
 **Источник дизайна:** ~/projects/.workshop/.archive/2026-05-24-session-handoff-skill.md (Round 1 + Round 2 resolved Q1-Q10).
 
-**SKILL.md status:** v0.1.0, только skeleton (header + 6 empty sections). Тело каркаса дописывается отдельно (второй проход workshop-promote-brainstorm, source — архивный буфер). Install активирует скил даже с пустым каркасом — триггерится по description.
+**SKILL.md status:** v0.2.1 (body full + YAML-fix). Install активирует скил по description.
 
-**Status:** ready
+**Status:** done
-**Where I stopped:** (not started)
+**Where I stopped:** done
-**Next action:** 1. cd ~/projects/claude-skills
+**Closed by:** install прошёл (`scripts\install.ps1 -Names session-handoff` → `~/.claude/skills/session-handoff/`); harness auto-discovered (без `/reload-plugins`) — listing рендерит полный description. **Bug найден и пофикшен**: исходный description (v0.2.0) содержал `: ` (colon-space) внутри bare-scalar YAML (`Триггер-строка CLAUDE.md \`session handoff: read on start, write on end\``) → strict YAML parser ломался → harness fallback на H1 (`- session-handoff: session-handoff` в листинге). Fix: wrap description в `"..."` double-quotes + shrink с 650→462 chars (865→555 bytes) убирая technical detail который уже в Steps body. Все 6 session-end triggers + 4 skip-phrases + trigger-line сохранены 1-в-1. Bump 0.2.0 → 0.2.1 PATCH (wording-only, поведение то же). Findings saved в memory: `feedback_skill_description_yaml_colon_gotcha.md` (новый entry), `feedback_skill_description_length_limit.md` (cross-ref добавлен). Acceptance step 5 (CLAUDE.md trigger-line activation smoke в новой сессии) — это работа `[session-handoff-test-trigger]`, не блокер этой таски.
-2. Запустить install.sh (PowerShell-эквивалент на Windows если нужно).
+**Branch:** master
-3. /reload-plugins в активной сессии.
-4. Открыть новую CC сессию → /skills → убедиться что session-handoff listed.
-5. Smoke: вставить в CLAUDE.md тестового проекта строку `session handoff: read on start, write on end` → перезапустить сессию → убедиться что скил активируется через trigger-line.
-**Branch:** n/a
 <!-- created-by: OpeItcLoc03@DESKTOP-NSEF0UK / from: OpeItcLoc03/workshop / 2026-05-24T18:20:25.525Z -->
+<!-- closed-by: vitya@DESKTOP-NSEF0UK / 2026-05-24 / install pipeline ✓; description rendering ✓ (YAML `: ` fix); test-trigger acceptance отдельной таской -->
 
 ---
 
@@ -1406,21 +1403,18 @@ Substantive-commit hook тест:
 
 ---
 
-## ⚪ [session-handoff-bootstrap-template-extend] — Расширить project-bootstrap canonical CLAUDE.md template новой trigger-строкой: `session handoff: read on start, write on end`. Чтобы новые проекты, инициализированные через `project-bootstrap`, автоматически включали handoff из коробки.
+## 🟢 [session-handoff-bootstrap-template-extend] — Расширить project-bootstrap canonical CLAUDE.md template новой trigger-строкой: `session handoff: read on start, write on end`. Чтобы новые проекты, инициализированные через `project-bootstrap`, автоматически включали handoff из коробки.
 
 **Прецедент:** project-bootstrap v1.4.0+ уже добавляет строку `pull remote before work` в canonical CLAUDE.md template — для активации `pulling-before-work` скила. Новая строка — аналогично.
 
 **User'ское напоминание:** явно зафиксировано в финальной реплике перед промоушеном 2026-05-24, «не забудь, что нужно будет обновить project bootstrap».
 
-**Status:** ready
+**Status:** done
-**Where I stopped:** (not started)
+**Where I stopped:** done
-**Next action:** 1. Открыть ~/projects/claude-skills/skills/project-bootstrap/SKILL.md → найти секцию canonical CLAUDE.md template.
+**Closed by:** Trigger-строка `session handoff: read on start, write on end` добавлена в `assets/CLAUDE.md.template:10` между `pull remote before work` и `follow project discipline` (session-lifecycle clustering). Соответствующий row в Step 5.6 trigger→fulfiller table at `SKILL.md:492` (source-of-truth invariant template ↔ table сохранён). Bump `version: 1.11.0` → `1.12.0` MINOR (new capability for greenfield bootstrap'а, backward-compatible). Rebuilt `dist/project-bootstrap.skill` через `scripts/build.ps1 -Names project-bootstrap`. Reinstalled в `~/.claude/skills/project-bootstrap/` через `scripts/install.ps1 -Names project-bootstrap` — verified frontmatter v1.12.0 + template + table row on disk. Step 5 (no install/push в этой таске) переинтерпретирован: rebuild+install — это deploy локальной копии, не push в remote; push — отдельный gate.
-2. Добавить строку `session handoff: read on start, write on end` рядом с `pull remote before work` и другими trigger-строками.
+**Branch:** master
-3. Bump project-bootstrap MINOR (canonical template extended — новая функциональность для greenfield bootstrap'а, backward-compatible с существующими проектами).
-4. Закоммитить с semver-bump в commit message (per project-discipline rule 3).
-5. Не делать install / push в этой таске — это работа отдельная.
-**Branch:** n/a
 <!-- created-by: OpeItcLoc03@DESKTOP-NSEF0UK / from: OpeItcLoc03/workshop / 2026-05-24T18:20:48.752Z -->
+<!-- closed-by: vitya@DESKTOP-NSEF0UK / 2026-05-24 / acceptance: template+table+bump ✓; rebuild ✓; install ✓; unblocks existing-projects-upgrade Path B -->
 
 ---
 

.tasks/session-handoff-bootstrap-template-extend.md

@@ -0,0 +1,34 @@
+# session-handoff-bootstrap-template-extend
+
+## Goal
+Расширить canonical CLAUDE.md template в `project-bootstrap` новой trigger-строкой `session handoff: read on start, write on end` — чтобы greenfield-bootstrap'ed проекты получали handoff из коробки. Также добавить соответствующий row в Step 5.6 trigger→fulfiller table (source-of-truth invariant: template ↔ table в одном commit'е). Bump project-bootstrap MINOR (new template entry = new capability, backward-compatible).
+
+## Key files
+- `skills/project-bootstrap/assets/CLAUDE.md.template:10` — добавлен `session handoff: read on start, write on end` между `pull remote before work` и `follow project discipline` (session-lifecycle clustering)
+- `skills/project-bootstrap/SKILL.md:3` — bump `version: 1.11.0` → `1.12.0`
+- `skills/project-bootstrap/SKILL.md:492` — новый row в Step 5.6 trigger→fulfiller table
+
+## Decisions log
+- 2026-05-24: позиция trigger-строки — после `pull remote before work` (тоже session-start hook), перед `follow project discipline`. Session-lifecycle triggers группируются вместе.
+- 2026-05-24: bump MINOR (1.11.0 → 1.12.0) — добавление trigger-строки в canonical template = новая capability для greenfield bootstrap'а, существующие проекты не ломаются (CLAUDE.md merge — idempotent + respects user removals per Step 5.6 Algorithm).
+- 2026-05-24: rebuild `dist/project-bootstrap.skill` через `scripts/build.ps1 -Names project-bootstrap` — обязательно, иначе deploy на других машинах через `.skill` archive получит stale template.
+- 2026-05-24: reinstall в `~/.claude/skills/project-bootstrap/` через `scripts/install.ps1 -Names project-bootstrap`.
+
+## Open questions
+- [ ] нет
+
+## Completed steps
+- [x] edit `assets/CLAUDE.md.template` — insert trigger line
+- [x] edit `SKILL.md` frontmatter — bump 1.11.0 → 1.12.0
+- [x] edit `SKILL.md` Step 5.6 — add row to trigger→fulfiller table
+- [x] `scripts\build.ps1 -Names project-bootstrap` → `dist/project-bootstrap.skill` rebuilt
+- [x] `scripts\install.ps1 -Names project-bootstrap`
+- [x] verify `~/.claude/skills/project-bootstrap/SKILL.md` v1.12.0 on disk
+- [x] verify template contains новой строки + table row at SKILL.md:492
+- [x] STATUS.md → 🟢
+- [ ] commit (next)
+
+## Notes
+Unblocks `[session-handoff-existing-projects-upgrade]` Path B (project-bootstrap в upgrade-режиме теперь видит handoff trigger как canonical).
+
+Этот edit — следствие user'ского напоминания из брейнсторма 2026-05-24 «не забудь, что нужно будет обновить project bootstrap».

.tasks/session-handoff-install.md

@@ -0,0 +1,34 @@
+# session-handoff-install
+
+## Goal
+Установить скил `session-handoff` в `~/.claude/skills/session-handoff/` через `scripts/install.ps1 -Names session-handoff` и убедиться что harness видит его + рендерит description в листинге. Анлокает `[session-handoff-test-trigger]` (нужен установленный + работающий скил для trigger smoke).
+
+## Key files
+- `scripts/install.ps1` — копирует `skills/<name>/` → `~/.claude/skills/<name>/` (replace mode)
+- `skills/session-handoff/SKILL.md:1-5` — frontmatter (`version: 0.2.1`, double-quoted description)
+- `~/.claude/skills/session-handoff/SKILL.md` — установленная копия
+
+## Decisions log
+- 2026-05-24: исходный description v0.2.0 (650 chars / 865 bytes) renderился как `- session-handoff: session-handoff` (harness fallback к H1). Сначала подозревал byte-overflow (memory `feedback_skill_description_length_limit` — лимит ~1024). Прокачав через PowerShell + Python YAML parser, root cause найден: `: ` (colon-space) внутри bare-scalar — конкретно `Триггер-строка CLAUDE.md \`session handoff: read on start, write on end\`` — YAML parser в strict mode принимал `session handoff:` за nested mapping key. Backticks не спасают, YAML их не интерпретирует.
+- 2026-05-24: fix = wrap description в double-quotes (`"..."`). Альтернатива (rephrase to remove `: `) — слабее, потому что trigger-line literal содержит `: ` by design (это user-facing trigger phrase в формате CLAUDE.md).
+- 2026-05-24: бонусом shrink с 650→462 chars (убрал substantive-commit heuristic, sliding-overwrite detail, project-scope clause — всё уже в body Steps/Side effects/Failure modes). Triggers + skip phrases сохранены 1-в-1.
+- 2026-05-24: bump 0.2.0 → 0.2.1 PATCH (wording-only frontmatter edit, поведение скила не меняется).
+- 2026-05-24: harness auto-discovered после `Copy-Item` (replace mode install) — `/reload-plugins` не понадобился, listing внутри текущей сессии обновился. Это противоречит формулировке task'и («Открыть новую CC сессию → /skills»). На этой версии CC re-scan SKILL.md происходит при следующем skill-listing вызове.
+
+## Open questions
+- [ ] (нет — атомарная install-таска)
+
+## Completed steps
+- [x] edit STATUS.md → 🔴 active
+- [x] run `pwsh scripts\install.ps1 -Names session-handoff` (через PowerShell tool, bash не видит pwsh)
+- [x] verify `~/.claude/skills/session-handoff/SKILL.md` v0.2.0 on disk
+- [x] discover description-rendering bug в листинге (fallback к H1)
+- [x] root-cause: YAML `: ` ambiguity внутри bare scalar (не byte-overflow)
+- [x] fix: wrap description в double-quotes + bump 0.2.0 → 0.2.1
+- [x] reinstall
+- [x] verify listing рендерит полный description
+- [x] save memory: `feedback_skill_description_yaml_colon_gotcha.md` (new) + cross-ref в `feedback_skill_description_length_limit.md`
+- [x] close 🟢
+
+## Notes
+Step «открыть новую CC сессию → /skills» из исходного next_action был safety-net на случай если harness не подхватит auto. Auto-pickup сработал — verified в эту же сессию через системный skill-listing.

skills/project-bootstrap/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: project-bootstrap
-version: 1.11.0
+version: 1.12.0
 description: >
   Initializes or upgrades a project in the current folder: git, .gitignore, README.md,
   .wiki/ using Karpathy's method, .tasks/ for task tracking, CLAUDE.md with skill triggers.
@@ -489,6 +489,7 @@ Mismatch between template and map → silent gaps in the recommendation.
 | `use task management system` | `using-tasks` | skill | `~/.claude/skills/using-tasks/SKILL.md` | `bash scripts/install.sh using-tasks` |
 | `check across all projects` | `using-projects-meta` | skill | `~/.claude/skills/using-projects-meta/SKILL.md` | `bash scripts/install.sh using-projects-meta` |
 | `pull remote before work` | `pulling-before-work` | skill | `~/.claude/skills/pulling-before-work/SKILL.md` | `bash scripts/install.sh pulling-before-work` |
+| `session handoff: read on start, write on end` | `session-handoff` | skill | `~/.claude/skills/session-handoff/SKILL.md` | `bash scripts/install.sh session-handoff` |
 | `follow project discipline` | `project-discipline` | skill | `~/.claude/skills/project-discipline/SKILL.md` | `bash scripts/install.sh project-discipline` |
 | `follow tdd-criteria` | `tdd-criteria` | skill | `~/.claude/skills/tdd-criteria/SKILL.md` | `bash scripts/install.sh tdd-criteria` |
 | `delegate to interns when allowed` | `using-interns` | skill | `~/.claude/skills/using-interns/SKILL.md` | `bash scripts/install.sh using-interns` |

skills/project-bootstrap/assets/CLAUDE.md.template

@@ -7,6 +7,7 @@ use project wiki
 use task management system
 check across all projects
 pull remote before work
+session handoff: read on start, write on end
 follow project discipline
 follow tdd-criteria
 delegate to interns when allowed

skills/session-handoff/SKILL.md

@@ -0,0 +1,134 @@
+---
+name: session-handoff
+version: 0.2.1
+description: "Sliding handoff between CC sessions via .tasks/NEXT_SESSION.md. Read on session start: orient agent, ask user before action. Write on session-end phrase or substantive commit. Session-end phrases: «завершаем сессию», «сворачиваемся», «закругляемся», «wrap up session», «end session», «we're done for now». Trigger-line in CLAUDE.md: `session handoff: read on start, write on end`. Skip task-zone phrases: «закрываем эту таску», «pause», «отбой», «разбегаемся»."
+---
+
+# session-handoff
+
+Sliding handoff prompt между CC сессиями. На старте — читает `.tasks/NEXT_SESSION.md`, ориентирует агента и спрашивает user'а перед действиями. При substantive commit'е или session-end фразе — перезаписывает handoff для следующей сессии. Sliding overwrite: один файл, история — через `git log -p .tasks/NEXT_SESSION.md`.
+
+Forward-looking, не timeline: handoff = связка новых вещей конкретно для следующего разворота, не overview всего проекта. STATUS.md / MEMORY.md / `.wiki/log.md` остаются авторитетными для своего scope'а.
+
+Дизайн-источник: `~/projects/.workshop/.archive/2026-05-24-session-handoff-skill.md` (Round 1 design + Round 2 resolved Q1–Q10).
+
+## When to use
+
+**Read mode (session start):**
+- CLAUDE.md проекта содержит trigger-строку `session handoff: read on start, write on end`.
+- Файл `.tasks/NEXT_SESSION.md` существует.
+
+**Write mode (session end / substantive commit):**
+- User'ская фраза из whitelist:
+  - русский: «завершаем сессию», «сворачиваемся», «закругляемся»
+  - английский: «wrap up session», «end session», «we're done for now»
+- ИЛИ — agent только что сделал substantive commit. Эвристика:
+  - prefix НЕ в (`meta:`|`docs:`|`style:`|`chore:`|`fix typo`)
+  - AND (body length > 200 символов OR files changed > 3)
+- Плюс: **первый** non-trivial commit сессии — всегда триггерит, даже если ниже порога (старт работы = context shift).
+
+**Skip (false-positive guards):**
+- «закрываем эту таску» — task close, не session. Это zone `using-tasks`.
+- «pause», «приостанови» — task-pause, не session-end.
+- «отбой», «разбегаемся» — слишком broad, может относиться к другому контексту.
+- «сейчас завершу одну задачу и тогда поговорим» — частичное завершение.
+- Не-git папка, или `.tasks/` отсутствует — silent exit.
+- CLAUDE.md проекта НЕ содержит trigger-строку — silent exit.
+
+При неоднозначности — **ASK**, не угадывать: «закрываем сессию или таску?»
+
+## Inputs
+
+**Read mode:**
+- `.tasks/NEXT_SESSION.md` — sliding handoff, должен существовать.
+- Текущая дата (для staleness check против `_last_updated_`).
+
+**Write mode:**
+- `git log --oneline -5` — последние commits сессии.
+- `.tasks/STATUS.md` — open треки + 🔴 active task'и (для mid-task capture).
+- Контекст сессии — pending user-decisions, waiting permissions, memory updates, preemptive guards.
+
+## Steps
+
+### Read mode
+
+1. **Detect.** Проверить что `.tasks/NEXT_SESSION.md` существует. Нет — silent exit.
+2. **Staleness check.** Прочитать frontmatter `_last_updated_`. Возраст > 7 дней → отметить user'у:
+   ```
+   handoff от <date> (N дней назад) — возможно устарел.
+   Оверrайдить или продолжить?
+   ```
+   Дождаться ответа перед продолжением.
+3. **Summarize.** Прочитать тело handoff'а — 5 секций (recent commits / open треки / спроси user'а / не делать / memory updates).
+4. **Orient.** Пересказать user'у одним блоком: «прошлая сессия предложила X (open треки + ask-items + don't-items + memory updates). Делаем?»
+5. **Wait.** Не делать никаких действий до подтверждения user'ом. Default = orient + ask, **никакого auto-execute**.
+
+### Write mode
+
+1. **Scope check.** Это текущий проект (cwd с `.tasks/`). Никаких global мутаций, никаких других проектов.
+2. **Mid-task capture.** Если в `.tasks/STATUS.md` есть 🔴 active task — захватить:
+   ```
+   left mid-task: <slug>
+   where_stopped: <текст из STATUS.md>
+   ```
+3. **Compose content.** Собрать `.tasks/NEXT_SESSION.md`:
+   ```markdown
+   ---
+   _last_updated_: <ISO 8601 timestamp>
+   session_id: <hash или дата>
+   ---
+
+   # Next session handoff
+
+   ## Recent commits
+   - <slug>: <subject>  (3–5 последних)
+   ...
+
+   ## Open треки
+   | Трек | Готовность | Entry-point |
+   |---|---|---|
+   | ... | ... | ... |
+
+   ## Спроси user'а
+   - <pending decision 1>
+   - <waiting permission 2>
+
+   ## Не делать (preemptive guards)
+   - <guard 1>
+   - <guard 2>
+
+   ## Memory updates за сессию
+   - <что нового сохранилось / обновилось>
+   ```
+   Пустую секцию — оставить заголовок + пометка `(нет на этом раунде)`. Чтобы next агент видел: не забыто, а пусто.
+4. **Sliding overwrite.** `Write` поверх `.tasks/NEXT_SESSION.md` (предыдущее содержимое НЕ архивируется в `.archive/handoff-*.md` — sliding contract). История восстанавливается через `git log -p .tasks/NEXT_SESSION.md`.
+5. **Stage.** `git add .tasks/NEXT_SESSION.md` — попадает в следующий commit сессии (или в текущий, если запись была вызвана session-end фразой).
+
+## Failure modes
+
+- **CLAUDE.md без trigger-строки** → silent exit, не вмешиваться. Скил project-opt-in.
+- **Не git-repo / `.tasks/` отсутствует** → silent exit. Скил требует обоих условий.
+- **`.tasks/NEXT_SESSION.md` отсутствует** в read mode → silent exit (первая сессия проекта, нечего читать).
+- **Неоднозначная фраза** («закругляемся» в контексте отдельной таски, а не сессии) → ASK user'а «закрываем сессию или таску?», не угадывать.
+- **Secret detected.** Содержимое handoff'а матчит паттерны секретов (`AKIA...`, `sk-...`, `ghp_...`, `ssh-rsa`, `BEGIN PRIVATE KEY`, JWT в обычном виде, `password=`/`token=` без obfuscation) → **abort write**, не записывать. Файл идёт в git — не место для credentials. Сообщить user'у с указанием подозрительной строки, дать дочистить контекст руками.
+- **Stale handoff (> 7 дней)** в read mode → не silent, **спросить** user'а оверrайдить или продолжить (Q9 resolved 2026-05-24).
+- **Mid-task без STATUS.md entry** в write mode → записать handoff без mid-task секции, не блокировать.
+
+## Side effects
+
+- Записывает / перезаписывает `.tasks/NEXT_SESSION.md` (project-scope only).
+- Файл git-tracked, попадает в commit (либо вместе с session work, либо отдельным commit'ом).
+- Никаких других файлов: `.archive/` не плодим (sliding), `.wiki/log.md` не дёргаем (это не promoted event), `STATUS.md` не правим.
+- Никаких global мутаций, никаких других проектов, никаких user-level config writes.
+
+## What NOT to do
+
+- **Не auto-execute** действия из read handoff'а. Default = orient + ask. Прошлая сессия могла ошибиться; user agency сохраняем.
+- **Не append-with-archive.** Sliding only. `.archive/handoff-<date>.md` создавать не нужно — это создавало бы N artefact'ов, которые user не хочет. История — через git log.
+- **Не триггерить на task-zone phrases** («закрываем эту таску», «pause»), broad farewells («отбой», «разбегаемся»), partial completions («сейчас завершу одну задачу и тогда поговорим»).
+- **Не писать секреты** в handoff. Если контент матчит secret-patterns — abort, попросить user'а вычистить контекст.
+- **Не на каждом commit'е.** Только substantive (см. эвристика в When to use). Trivial `chore: bump dep` или `docs: typo` НЕ триггерят, иначе handoff'ы шумят.
+- **Не дублировать STATUS.md / MEMORY.md.** Handoff = **forward-looking связка** новых вещей для следующего разворота, не overview всего проекта. Open треки — да, но как мостик «вот где остановились», не как replica STATUS.md.
+- **Не cross-project.** Per-project scope. «Завершаем сессию» в `.workshop/` не трогает `.admin/` и наоборот.
+- **Не зависеть от harness `SessionEnd` hook** — такого hook'а в Claude Code нет (есть только `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `Stop`, `Notification`). Триггер — фраза или substantive-commit detection в самом agent flow.
+- **Не считать handoff авторитетным** на стороне читателя. Это рекомендация прошлой сессии, не директива. User может override любую её часть.