wenay-react2 1.0.47 → 1.0.49

package/doc/progress/qa-stand-walkthrough-2026-07-12.md

@@ -0,0 +1,62 @@
+# QA stand walkthrough — 2026-07-12
+
+Полный автоматизированный проход всех 43 карточек стенда (28 active + 15 archive) в браузере
+после восстановления окружения с нуля. Итог: **все проверяемые контракты подтверждены,
+0 ошибок в консоли за весь проход**; найденные дефекты стенда исправлены (см. ниже).
+
+## Окружение (восстановлено с нуля)
+
+- `pnpm install` (pnpm 9, lockfile 9.0). **Важно:** установка должна идти под Node ≥22.12 —
+  под Node 21 pnpm молча пропускает `@rolldown/binding-win32-x64-msvc` (engines-фильтр),
+  и vite 8 не стартует («Cannot find native binding»).
+- Системный Node 21.6 (EOL) не подходит для Vite 8: портативный Node 22.23.1 лежит в
+  `~/.tools/node-v22.23.1-win-x64`, стенд запускается обёрткой `~/.tools/vite-node22.cmd`
+  (прописана в `.claude/launch.json`).
+- `typescript ^5` добавлен в devDependencies (раньше жил только глобально). TS 7 не брать:
+  ts-jest требует `<7`, tsconfig использует удалённый в TS7 `moduleResolution: node10` —
+  миграция записана как кандидат в breaking-проход.
+- Проверки: tsc qa-check ✅, Jest 23 suites / 78 tests ✅, build ✅.
+
+## Результаты по карточкам
+
+Автоматически подтверждены (клики/жесты синтетикой, чтение DOM/модели):
+1, 3, 4, 5, 7 (sync+t33), 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 2, 20 (поиск/RU-раскладка/
+двухступенчатый Escape/реестр), 21 (+F5-персист), 22, 23 (A–E), 24, 25 (+F5, reset), 26, 27,
+28 (двусторонний контракт), 29, 30 (presentGate 4 режима), 31, 32, 33, 34, 35, 40, 41, 42.
+Медиа 38/39/43/44/45: deny-путь чистый (idle→denied без крэша), звонок 45 без медиа проходит
+ringing→active→idle.
+
+## Чек-лист ручной приёмки (нужны глаза/устройства)
+
+- **6** — амплитуда LOD на зуме (визуально); **23/34** — плавность видео.
+- **19** — fixed-parent select при 150/240px (метки на RO+rAF пайплайне).
+- **20** — драг разделителя дерева, history-дропдаун; **25/30/31** — drag-reorder строк
+  настроек и HOLD-превью середины жеста; **26/27** — совпадение превью и коммита глазами.
+- **28** — драг заголовков ag-grid и resize (нативный dragService не берётся синтетикой).
+- **29/32** — live-замена поля при медленном драге точки + палец-лейбл.
+- **9** — всплывающая нотификация (~2 c) и её выключатель.
+- **38/39/43/44/45** — реальная камера/микрофон: живое видео на канвасе, эхо голоса,
+  заморозка счётчиков при ACL-revoke, hidden-tab.
+
+## Исправления по итогам прохода
+
+- qa.tsx: карточка 14 «click clear»→«reset via API»; карточка 29 — снят недостижимый
+  «Max 4 dots» (демо даёт max=8 на 8 колонок); карточка 38 — ожидание без фантомного
+  «requesting»; карточка 2 — `onCLickClose`→`onClickClose` (2 места) и обновлена note про
+  исторический xxx-спам.
+- demo/peerMedia.tsx (карточка 45): аудио теперь включается по документированным шагам —
+  намерение enable запоминается и применяется к плееру, создаваемому после accept.
+- logsController.ts: подписи `minVarLogs`/`minVarMessage` были перепутаны местами
+  (minVarLogs фильтрует таблицу — logs.tsx:149; minVarMessage гейтит нотификации —
+  logs.tsx:294). Поменяны только name-строки, ключи/семантика не тронуты.
+
+## Заметки для будущей автоматизации стенда
+
+- Панель Claude-браузера не рисует кадры: CSS-переходы замирают → визуальные позиции строк
+  ag-grid читать по `row-index`/`aria-rowcount`/inline transform, НЕ по getBoundingClientRect.
+- ag-grid v35: клик по ячейке требует pointer-событий; заголовки/колонки виртуализуются
+  горизонтально (скроллить вьюпорт перед чтением).
+- ColumnDots: синтетические PointerEvent работают после no-op патча
+  `Element.prototype.setPointerCapture`.
+- useDraggable/useReorder: после mousedown дать тик (~50 мс) на подписку document-слушателей,
+  mousemove слать с `buttons:1`.

package/doc/progress/stand-as-examples-audit.md

@@ -1,22 +1,22 @@
-# Stand as examples — audit
-
-## Current shape
-
-- `src/common/testUseReact/qa.tsx` owns 44 hand-written cards and the component implementations are mostly in the same file.
-- The board has only Active/Archive separation. It does not declare whether a card is canonical consumer guidance or internal regression/compat coverage.
-- `doc/examples/peer-call-media.tsx` is shipped, but card 41–44 currently use a parallel implementation.
-
-## Decision
-
-Turn the stand into a renderer/acceptance layer over a small set of canonical demo modules. Ship those modules in `demo/`; keep isolated repros and compat examples in QA/regression only. Use a manifest per card to link source demo, automated test and manual verification.
-
-## First migration
-
-Extract Media/Peer calls, presence, camera relay and microphone relay. The QA cards must import the same component that is shipped in the package. No new transport/ACL code belongs in React.
-## Batch 1 complete — Media/Peer
-
-- Extracted cards 41–44 into `src/common/demo/peerMedia.tsx`.
-- QA imports those exact components; package exports `wenay-react2/demo/peer-media`.
-- `doc/examples/peer-call-media.tsx` re-exports the public demo entrypoint.
+# Stand as examples — audit
+
+## Current shape
+
+- `src/common/testUseReact/qa.tsx` owns 44 hand-written cards and the component implementations are mostly in the same file.
+- The board has only Active/Archive separation. It does not declare whether a card is canonical consumer guidance or internal regression/compat coverage.
+- `doc/examples/peer-call-media.tsx` is shipped, but card 41–44 currently use a parallel implementation.
+
+## Decision
+
+Turn the stand into a renderer/acceptance layer over a small set of canonical demo modules. Ship those modules in `demo/`; keep isolated repros and compat examples in QA/regression only. Use a manifest per card to link source demo, automated test and manual verification.
+
+## First migration
+
+Extract Media/Peer calls, presence, camera relay and microphone relay. The QA cards must import the same component that is shipped in the package. No new transport/ACL code belongs in React.
+## Batch 1 complete — Media/Peer
+
+- Extracted cards 41–44 into `src/common/demo/peerMedia.tsx`.
+- QA imports those exact components; package exports `wenay-react2/demo/peer-media`.
+- `doc/examples/peer-call-media.tsx` re-exports the public demo entrypoint.
 - Remaining batches: Replay, then toolbar/columnState/grid; archive stays internal.
 - Verification: qa-check TypeScript, full Jest (21 suites / 71 tests), package build and Vite stand cards 41–44 all pass. The package is browser-oriented; direct Node require is not a supported validation surface for its extensionless ESM build.

package/doc/progress/style-system-normalization.md

@@ -1,121 +1,121 @@
-# Style system normalization
-
-Status: done/released (v1.0.38, v1.0.39, v1.0.41); default inventory and column-state scoped token fixes implemented and shipped.
-
-## Source
-
-User clarification: compatibility can be an aggressive migration when it is
-clearly recorded in changelog, but default styles are dangerous to remove.
-If default styles disappear, the project can become visually broken even when
-the TypeScript/API migration is understandable.
-
-## Standard
-
-- Shared primitives must keep a usable default visual style.
-- A default style may be changed, but not silently removed.
-- Removing/replacing a default class requires a replacement class/token path,
-  changelog entry, and migration note.
-- New shared visual rules should use CSS custom properties first.
-- Runtime geometry may stay inline when it is state-derived, but color, spacing,
-  border, shadow, font, and hover/active states should move to classes/tokens.
-- Apps may override variables; primitives should not require apps to copy a full
-  CSS block to remain usable.
-
-## Token direction
-
-Current prefixes are a good start:
-
-- `--color-*`
-- `--menu-*`
-- `--wnd-*`
-- `--dlg-*`
-- `--tb-*`
-- `--logs-*`
-- `--cols-menu-*` for compact `ColumnsMenu/MenuStrip` visuals.
-- `--cols-dots-*` for `ColumnDots` visuals.
-- `--cols-card-*` for `CardList` visuals.
-
-Likely next prefixes:
-
-- `--cols-*` remains a family prefix; concrete prefixes now use `--cols-menu-*`, `--cols-dots-*`, and `--cols-card-*`.
-- `--input-*` for generic input/panel defaults if they stay public.
-- `--param-*` for `ParamsEditor` if it remains a shared primitive.
-
-## First audit candidates
-
-- `src/style/style.css`: old button/menu classes, `FloatingWindow`, `SettingsDialog`, `Toolbar`, `ColumnDots/CardList`, and raw hover colors.
-- `src/style/menuRight.css`: right-menu visual contract and default state styles.
-- `src/common/src/grid/columnState/*`: finish deciding whether mobile/card
-  visuals need `--cols-*` tokens.
-- `src/common/src/components/ParamsEditor.tsx`: move reusable editor visuals
-  out of component-owned inline styles if the API remains public.
-- `src/common/src/components/Input.tsx`: decide whether old input panels are
-  compatibility-only or need a proper tokenized default.
-
-## Acceptance
-
-- Default visual contract documented per public primitive group.
-- Token prefixes chosen before broad style rewrites.
-- No removal of default classes without replacement and changelog.
-- Scoped visual QA cards checked before and after style migration.
-## 2026-07-09 default style contract inventory
-
-Source of truth:
-
-- CSS tokens: `src/style/tokens.css`.
-- TS mirror for inline styles/theme builders: `src/common/src/styles/tokens.ts`.
-- Shared runtime CSS: `src/style/style.css` and `src/style/menuRight.css`.
-- Generated `dist/lib/style/*` is build output, not the edit target.
-
-Public/default visual contracts:
-
-- `Menu` / `MenuR` / mouse context menu: legacy `.MenuR`, `.toButton`, `.toButtonA` classes remain; colors/shadow/borders are already routed through `--menu-*` tokens. Keep the old class names as compatibility surface.
-- `RightMenu`: default classes `.menu-container`, `.menu-button`, `.dropdown-content`, `.menu-item`, `.submenu`, `.draggable-div` live in `src/style/menuRight.css` and already consume `--menu-*` / `--menu-outline-color`.
-- `FloatingWindow`: `.wenayWnd*` and `.wenayCloseBtn` live in `src/style/style.css`; defaults intentionally preserve the old transparent/striped window while allowing `--wnd-*` theme overrides.
-- `SettingsDialog`: `.wenayDlg*` classes live in `src/style/style.css`; default look is dark and tokenized through `--dlg-*` plus selected `--wnd-*` bridge variables on `.wenayDlgWindow`.
-- `Toolbar` / `createToolbar`: `.wenayTb*` classes live in `src/style/style.css`; defaults consume `--tb-*`; stand-specific skins should override through wrapper classes, not by changing shared defaults.
-- `Logs`: `src/common/src/logs/logStyles.ts` maps inline logger chrome to `--logs-*`; this is an accepted transitional contract while old logger JSX stays inline-heavy.
-- `ColumnDots` / `CardList`: `.wenayColDots*` and `.wenayCardList*` classes live in `src/style/style.css`; restored card-29 defaults are now tokenized through `--cols-dots-*` / `--cols-card-*` with the same fallback values.
-- `ColumnsMenu` / `MenuStrip`: behavior is already headless/presentation split. Visual button/container/divider states now use `.wenayColsMenu*` classes and `--cols-menu-*` tokens with the exact previous GitHub-like defaults; runtime reorder transform stays inline.
-- `ParamsEditor`: public and still mostly old class + inline style based (`toIndicatorMenuButton`, `miniEl`, `toButtonEasy`, `inputCan`). Do not token-migrate broadly until hook/API direction is decided; candidate prefix `--param-*`.
-- `Input` modal helpers: public compatibility helpers over `FloatingWindow`, `.msTradeAlt`, `.msTradeActive`, `.inputCan`, inline panel spacing. Candidate prefix `--input-*`, but may remain compatibility-only if newer app surfaces replace them.
-
-Done scoped fix:
-
-- `ColumnsMenu/MenuStrip` visual button/container/divider styles moved to classes/tokens; runtime reorder transform/drag geometry remains inline.
-
-Done scoped fixes:
-
-- `ColumnsMenu/MenuStrip` visual button/container/divider styles moved to classes/tokens; runtime reorder transform/drag geometry remains inline.
-- `ColumnDots/CardList` restored card-29 defaults moved to `--cols-dots-*` / `--cols-card-*` variables with unchanged fallback values.
-
-Next scoped candidate:
-
-- Leave `ParamsEditor` / `Input` broad visual migration until the hook-first/API direction is clearer; only do bug-level style fixes there.
-## 2026-07-09 scoped fix - ColumnsMenu/MenuStrip tokens
-
-Implemented the compact column menu style contract:
-
-- Added `--cols-menu-*` defaults to `src/style/tokens.css` and the TS mirror in `src/common/src/styles/tokens.ts`.
-- Added `.wenayColsMenu*` classes in `src/style/style.css` for container/list/button states, fixed/drag shadow, text abbreviation, marks, and divider.
-- Updated `src/common/src/grid/columnState/ColumnsMenu.tsx` so visual state uses classes; only consumer `style` and `useReorder` runtime transform remain inline.
-
-Verification: `npx tsc -p tsconfig.qa-check.json --noEmit`; `npm run testjest -- --runInBand`; `npm run build`; `git diff --check`.
-## 2026-07-09 scoped fix - ColumnDots/CardList tokens
-
-Implemented the mobile/card column-state style contract:
-
-- Added `--cols-dots-*` and `--cols-card-*` defaults to `src/style/tokens.css` and the TS mirror in `src/common/src/styles/tokens.ts`.
-- Rewrote `.wenayColDots*` and `.wenayCardList*` values in `src/style/style.css` to use variables with the exact previous fallbacks.
-- Kept component code unchanged; `ColumnDots` runtime geometry (`left`, drag transform) remains inline in the component where it belongs.
-
-Verification: `npx tsc -p tsconfig.qa-check.json --noEmit`; `npm run testjest -- --runInBand`; `npm run build`; `git diff --check`.
-## 2026-07-09 — Menu default contrast restore
-
-Сделано:
-- `--menu-bg-color` возвращён к непрозрачному dark fallback `#0c0c0c`, `--menu-blur` по умолчанию `0px`;
-- добавлены `--menu-item-active-*` и `--menu-item-pressed-*` tokens, старый `--menu-active-background` оставлен alias/fallback;
-- `MenuR` / mouse context menu and `RightMenu` CSS получили hard fallbacks: default dark background, white text, hover white with dark text, pressed yellow-ish contrast state;
-- причина: рабочие проекты могут ещё не переопределять новые CSS variables, поэтому дефолт не должен становиться glass/transparent.
-
-Проверка: CSS-only visual contract; прогнать `tsc`/`build`, card 4 вручную открыть правой кнопкой.
+# Style system normalization
+
+Status: done/released (v1.0.38, v1.0.39, v1.0.41); default inventory and column-state scoped token fixes implemented and shipped.
+
+## Source
+
+User clarification: compatibility can be an aggressive migration when it is
+clearly recorded in changelog, but default styles are dangerous to remove.
+If default styles disappear, the project can become visually broken even when
+the TypeScript/API migration is understandable.
+
+## Standard
+
+- Shared primitives must keep a usable default visual style.
+- A default style may be changed, but not silently removed.
+- Removing/replacing a default class requires a replacement class/token path,
+  changelog entry, and migration note.
+- New shared visual rules should use CSS custom properties first.
+- Runtime geometry may stay inline when it is state-derived, but color, spacing,
+  border, shadow, font, and hover/active states should move to classes/tokens.
+- Apps may override variables; primitives should not require apps to copy a full
+  CSS block to remain usable.
+
+## Token direction
+
+Current prefixes are a good start:
+
+- `--color-*`
+- `--menu-*`
+- `--wnd-*`
+- `--dlg-*`
+- `--tb-*`
+- `--logs-*`
+- `--cols-menu-*` for compact `ColumnsMenu/MenuStrip` visuals.
+- `--cols-dots-*` for `ColumnDots` visuals.
+- `--cols-card-*` for `CardList` visuals.
+
+Likely next prefixes:
+
+- `--cols-*` remains a family prefix; concrete prefixes now use `--cols-menu-*`, `--cols-dots-*`, and `--cols-card-*`.
+- `--input-*` for generic input/panel defaults if they stay public.
+- `--param-*` for `ParamsEditor` if it remains a shared primitive.
+
+## First audit candidates
+
+- `src/style/style.css`: old button/menu classes, `FloatingWindow`, `SettingsDialog`, `Toolbar`, `ColumnDots/CardList`, and raw hover colors.
+- `src/style/menuRight.css`: right-menu visual contract and default state styles.
+- `src/common/src/grid/columnState/*`: finish deciding whether mobile/card
+  visuals need `--cols-*` tokens.
+- `src/common/src/components/ParamsEditor.tsx`: move reusable editor visuals
+  out of component-owned inline styles if the API remains public.
+- `src/common/src/components/Input.tsx`: decide whether old input panels are
+  compatibility-only or need a proper tokenized default.
+
+## Acceptance
+
+- Default visual contract documented per public primitive group.
+- Token prefixes chosen before broad style rewrites.
+- No removal of default classes without replacement and changelog.
+- Scoped visual QA cards checked before and after style migration.
+## 2026-07-09 default style contract inventory
+
+Source of truth:
+
+- CSS tokens: `src/style/tokens.css`.
+- TS mirror for inline styles/theme builders: `src/common/src/styles/tokens.ts`.
+- Shared runtime CSS: `src/style/style.css` and `src/style/menuRight.css`.
+- Generated `dist/lib/style/*` is build output, not the edit target.
+
+Public/default visual contracts:
+
+- `Menu` / `MenuR` / mouse context menu: legacy `.MenuR`, `.toButton`, `.toButtonA` classes remain; colors/shadow/borders are already routed through `--menu-*` tokens. Keep the old class names as compatibility surface.
+- `RightMenu`: default classes `.menu-container`, `.menu-button`, `.dropdown-content`, `.menu-item`, `.submenu`, `.draggable-div` live in `src/style/menuRight.css` and already consume `--menu-*` / `--menu-outline-color`.
+- `FloatingWindow`: `.wenayWnd*` and `.wenayCloseBtn` live in `src/style/style.css`; defaults intentionally preserve the old transparent/striped window while allowing `--wnd-*` theme overrides.
+- `SettingsDialog`: `.wenayDlg*` classes live in `src/style/style.css`; default look is dark and tokenized through `--dlg-*` plus selected `--wnd-*` bridge variables on `.wenayDlgWindow`.
+- `Toolbar` / `createToolbar`: `.wenayTb*` classes live in `src/style/style.css`; defaults consume `--tb-*`; stand-specific skins should override through wrapper classes, not by changing shared defaults.
+- `Logs`: `src/common/src/logs/logStyles.ts` maps inline logger chrome to `--logs-*`; this is an accepted transitional contract while old logger JSX stays inline-heavy.
+- `ColumnDots` / `CardList`: `.wenayColDots*` and `.wenayCardList*` classes live in `src/style/style.css`; restored card-29 defaults are now tokenized through `--cols-dots-*` / `--cols-card-*` with the same fallback values.
+- `ColumnsMenu` / `MenuStrip`: behavior is already headless/presentation split. Visual button/container/divider states now use `.wenayColsMenu*` classes and `--cols-menu-*` tokens with the exact previous GitHub-like defaults; runtime reorder transform stays inline.
+- `ParamsEditor`: public and still mostly old class + inline style based (`toIndicatorMenuButton`, `miniEl`, `toButtonEasy`, `inputCan`). Do not token-migrate broadly until hook/API direction is decided; candidate prefix `--param-*`.
+- `Input` modal helpers: public compatibility helpers over `FloatingWindow`, `.msTradeAlt`, `.msTradeActive`, `.inputCan`, inline panel spacing. Candidate prefix `--input-*`, but may remain compatibility-only if newer app surfaces replace them.
+
+Done scoped fix:
+
+- `ColumnsMenu/MenuStrip` visual button/container/divider styles moved to classes/tokens; runtime reorder transform/drag geometry remains inline.
+
+Done scoped fixes:
+
+- `ColumnsMenu/MenuStrip` visual button/container/divider styles moved to classes/tokens; runtime reorder transform/drag geometry remains inline.
+- `ColumnDots/CardList` restored card-29 defaults moved to `--cols-dots-*` / `--cols-card-*` variables with unchanged fallback values.
+
+Next scoped candidate:
+
+- Leave `ParamsEditor` / `Input` broad visual migration until the hook-first/API direction is clearer; only do bug-level style fixes there.
+## 2026-07-09 scoped fix - ColumnsMenu/MenuStrip tokens
+
+Implemented the compact column menu style contract:
+
+- Added `--cols-menu-*` defaults to `src/style/tokens.css` and the TS mirror in `src/common/src/styles/tokens.ts`.
+- Added `.wenayColsMenu*` classes in `src/style/style.css` for container/list/button states, fixed/drag shadow, text abbreviation, marks, and divider.
+- Updated `src/common/src/grid/columnState/ColumnsMenu.tsx` so visual state uses classes; only consumer `style` and `useReorder` runtime transform remain inline.
+
+Verification: `npx tsc -p tsconfig.qa-check.json --noEmit`; `npm run testjest -- --runInBand`; `npm run build`; `git diff --check`.
+## 2026-07-09 scoped fix - ColumnDots/CardList tokens
+
+Implemented the mobile/card column-state style contract:
+
+- Added `--cols-dots-*` and `--cols-card-*` defaults to `src/style/tokens.css` and the TS mirror in `src/common/src/styles/tokens.ts`.
+- Rewrote `.wenayColDots*` and `.wenayCardList*` values in `src/style/style.css` to use variables with the exact previous fallbacks.
+- Kept component code unchanged; `ColumnDots` runtime geometry (`left`, drag transform) remains inline in the component where it belongs.
+
+Verification: `npx tsc -p tsconfig.qa-check.json --noEmit`; `npm run testjest -- --runInBand`; `npm run build`; `git diff --check`.
+## 2026-07-09 — Menu default contrast restore
+
+Сделано:
+- `--menu-bg-color` возвращён к непрозрачному dark fallback `#0c0c0c`, `--menu-blur` по умолчанию `0px`;
+- добавлены `--menu-item-active-*` и `--menu-item-pressed-*` tokens, старый `--menu-active-background` оставлен alias/fallback;
+- `MenuR` / mouse context menu and `RightMenu` CSS получили hard fallbacks: default dark background, white text, hover white with dark text, pressed yellow-ish contrast state;
+- причина: рабочие проекты могут ещё не переопределять новые CSS variables, поэтому дефолт не должен становиться glass/transparent.
+
+Проверка: CSS-only visual contract; прогнать `tsc`/`build`, card 4 вручную открыть правой кнопкой.

package/doc/target/README.md

@@ -1,33 +1,33 @@
-# Target Backlog Rules
-
-`doc/target` is the durable task backlog for dictated or imported work. It is not a scratchpad and it is not a changelog.
-
-## Files
-
-- `doc/target/my.md` is the user-owned inbox/queue for dictated tasks. Keep it clean and actionable.
-- `target/*.md` are source prompt files imported into this repo. Treat them as task specs; do not edit or delete them just to mark progress unless the user asks for that exact cleanup.
-- `doc/progress/*.md` are temporary working notes for an active task. They may be deleted when the task is finished, so they must never be the only place where queue status lives.
-- `doc/changes/vX.Y.Z.md` records durable completed changes when code, public docs, theme contracts, dependencies, or policy changed.
-
-## Workflow
-
-1. When the user says to start from `target`, read this README first, then `doc/target/my.md`, then relevant files under `target/`.
-2. Before coding, normalize dictated text into concrete tasks in `doc/target/my.md`: a short title, current status, source note, and acceptance checks if they are known.
-3. When taking a task, move it to `In Progress` in `doc/target/my.md` and point to the progress file if one is created.
-4. Use `doc/progress/<task>.md` only for checkpoints, decisions, blockers, and verification while work is active.
-5. When implementation is believed complete, move the task to `Verify` in `doc/target/my.md` with the concrete checks that prove it: commands, QA stand checks, screenshots, or manual acceptance points.
-6. Remove a task from `doc/target/my.md` only after `Verify` checks pass and the durable result exists: code/docs are updated, verification is recorded, and changelog is updated when required.
-7. If the task is paused or blocked, leave it in `doc/target/my.md` under `In Progress` or `Blocked` with the next concrete action. Do not delete the progress file in that case.
-8. If a task from `target/*.md` is found already implemented, move it to `Verify` first and check its acceptance criteria before removing it. Do not rely on a deleted progress file as proof.
-
-## Status Sections For `my.md`
-
-Use these sections:
-
-- `Inbox` - raw or lightly cleaned tasks not yet triaged.
-- `Ready` - concrete tasks that can be started.
-- `In Progress` - the task currently being worked on, with a progress-file link when applicable.
-- `Verify` - implementation is believed complete, but acceptance checks still need to be run or reviewed.
-- `Blocked` - tasks waiting for user input, another repository, credentials, or an external change.
-
+# Target Backlog Rules
+
+`doc/target` is the durable task backlog for dictated or imported work. It is not a scratchpad and it is not a changelog.
+
+## Files
+
+- `doc/target/my.md` is the user-owned inbox/queue for dictated tasks. Keep it clean and actionable.
+- `target/*.md` are source prompt files imported into this repo. Treat them as task specs; do not edit or delete them just to mark progress unless the user asks for that exact cleanup.
+- `doc/progress/*.md` are temporary working notes for an active task. They may be deleted when the task is finished, so they must never be the only place where queue status lives.
+- `doc/changes/vX.Y.Z.md` records durable completed changes when code, public docs, theme contracts, dependencies, or policy changed.
+
+## Workflow
+
+1. When the user says to start from `target`, read this README first, then `doc/target/my.md`, then relevant files under `target/`.
+2. Before coding, normalize dictated text into concrete tasks in `doc/target/my.md`: a short title, current status, source note, and acceptance checks if they are known.
+3. When taking a task, move it to `In Progress` in `doc/target/my.md` and point to the progress file if one is created.
+4. Use `doc/progress/<task>.md` only for checkpoints, decisions, blockers, and verification while work is active.
+5. When implementation is believed complete, move the task to `Verify` in `doc/target/my.md` with the concrete checks that prove it: commands, QA stand checks, screenshots, or manual acceptance points.
+6. Remove a task from `doc/target/my.md` only after `Verify` checks pass and the durable result exists: code/docs are updated, verification is recorded, and changelog is updated when required.
+7. If the task is paused or blocked, leave it in `doc/target/my.md` under `In Progress` or `Blocked` with the next concrete action. Do not delete the progress file in that case.
+8. If a task from `target/*.md` is found already implemented, move it to `Verify` first and check its acceptance criteria before removing it. Do not rely on a deleted progress file as proof.
+
+## Status Sections For `my.md`
+
+Use these sections:
+
+- `Inbox` - raw or lightly cleaned tasks not yet triaged.
+- `Ready` - concrete tasks that can be started.
+- `In Progress` - the task currently being worked on, with a progress-file link when applicable.
+- `Verify` - implementation is believed complete, but acceptance checks still need to be run or reviewed.
+- `Blocked` - tasks waiting for user input, another repository, credentials, or an external change.
+
 Completed tasks are normally removed from `my.md`; the final response, commit message, and changelog carry the durable completion record.