heyspex 0.2.5 → 0.2.7

package/dist/cli-templates/customer-vault/specs/protocols/destructive-action-checklist.md

@@ -1,122 +1,122 @@
----
-id: HS-PROTO-destructive-action-checklist
-name: Destructive Action Checklist (UI + API gate)
-type: protocol
-scope: agent-workflow
-version: 1.0
-status: open
-priority: 0
-owner: TODO — your name/handle
-created: 2026-05-22
-updated: 2026-08-25
-tags:
-  - "protocol"
-  - "ui"
-  - "ux"
-  - "data-loss"
-  - "destructive"
-  - "console"
-triggers:
-  - destructive_action
-summary: |
-  Walk before merging any code that can destroy user data: explicit danger-styled button, soft-delete to .trash/ instead of permanent deletion, and a real Undo notification with a time-limited commit. Close is not the same as destroy.
-
----
-
-# Destructive Action Checklist
-
-**Scope note:** this checklist covers screen actions — UI + API surfaces that can destroy
-user data (delete spec, archive, discard buffer). Git tree actions on a shared checkout
-(stash, `reset --hard`, `clean -f`, `checkout .`, `restore`, `rebase`, `push --force`,
-`branch -D`, `commit --amend`) are gated in protected-shared-actions-gate — don't
-duplicate that ground here.
-
-**Run this before merging any PR that adds, changes, or routes an action
-that can destroy user data** (delete spec, archive, unpin, discard buffer,
-hard-revert, etc.). Pinning, hiding, or marking "closed" are non-destructive
-and do not require this checklist.
-
-Acceptance: every box ticked, or an inline `dismissed because <reason>`
-note for any box that genuinely does not apply.
-
-## Why this exists
-
-A past idea-discard data-loss incident showed that strong UX *principles*
-(recoverable destructive actions, reversible user actions) are not
-enough — they only prevent data loss if recalled and applied during
-implementation. This protocol turns the principles into an enforceable
-checklist that lives in the PR template / `npm run validate:*` and that
-agents must walk before claiming a destructive-action task done.
-
-## Memory recall (before writing code)
-
-- [ ] `heyspex_recall_memories({ tags: ["destructive"] })`
-- [ ] `heyspex_recall_memories({ tags: ["ux", "ux-principle"] })`
-- [ ] Read any vault memories on destructive-action recovery and Undo.
-
-## UI affordances
-
-- [ ] **Explicit Discard / Delete / Archive button** — labeled with the
-      action verb, styled with `var(--danger)`, positioned away from the
-      primary CTA.
-- [ ] **Close ≠ Destroy.** Backdrop click, Esc, header X, "Close", and
-      "Cancel" all just dismiss the surface. None of them route into a
-      confirmation flow whose primary button is destructive.
-- [ ] **Confirm dialog has a safe default.** The cancel/keep-editing button
-      is default-focused, visually primary, and is not the same control
-      that would also destroy on a second press.
-- [ ] **Confirm copy says what happens and where it goes.** Mentions the
-      trash location and the Undo affordance ("recoverable from the Undo
-      toast that follows").
-- [ ] **Unsaved-changes warning** when closing a dirty editor — separate
-      flow from discard. (Not covered here.)
-
-## API + filesystem
-
-- [ ] **Soft-delete only.** Server moves bytes to
-      `<folder>/.trash/<iso-stamp>-<basename>.<ext>` via `fs.rename`.
-      No `fs.unlink`, `fs.rm`, or equivalent on user data from a request
-      handler.
-- [ ] **DELETE response includes restore info** — `{ trashPath,
-      originalRelPath }` (or analogous fields) so the UI can wire Undo.
-- [ ] **Restore endpoint exists** — POST/PUT that validates both paths
-      resolve inside the vault root, refuses to overwrite an existing
-      file, and `fs.rename`s back.
-- [ ] **Index ignores trash.** Confirm `walkMarkdown` (or equivalent
-      indexer) skips `.trash/` so trashed files don't reappear as ghosts.
-
-## Undo path
-
-- [ ] **Undo toast** with a labeled action button (not just a "Deleted"
-      confirmation), held ≥ 8 seconds.
-- [ ] **Undo actually calls restore endpoint** — wired end-to-end, tested
-      manually at least once.
-- [ ] **Restore dispatches the same `heyspex:spec-updated` event** that
-      external watchers listen for, so list views refresh.
-
-## Tests / verification
-
-- [ ] Manual: open the surface, perform the destructive action, click
-      Undo in the toast, confirm the file is back at its original path.
-- [ ] Manual: open the surface, click backdrop / Esc / Close / Cancel —
-      confirm none of these prompt for or perform deletion.
-- [ ] Optional unit test if the project has them: assert `deleteSpec`
-      moves to `.trash/` and `restoreSpecFromTrash` round-trips.
-
-## After merge
-
-- [ ] Capture any new gotchas as a `memory-lesson` linked to this
-      protocol.
-- [ ] If a *new* destructive surface is introduced, record it in a vault memory.
-
-## How this gate gets enforced
-
-Today: agents must
-walk it before marking the spec `in_review`. The reviewer ticks each box
-in the spec's `.review.md`.
-
-Future automation candidates:
-
-- ESLint rule banning `fs.unlink`/`fs.rm` in `src/app/api/**`.
-- PR template line: "Destructive action? Walk
-  [[destructive-action-checklist]] before requesting review."
+---
+id: HS-PROTO-destructive-action-checklist
+name: Destructive Action Checklist (UI + API gate)
+type: protocol
+scope: agent-workflow
+version: 1.0
+status: open
+priority: 0
+owner: TODO — your name/handle
+created: 2026-05-22
+updated: 2026-08-25
+tags:
+  - "protocol"
+  - "ui"
+  - "ux"
+  - "data-loss"
+  - "destructive"
+  - "console"
+triggers:
+  - destructive_action
+summary: |
+  Walk before merging any code that can destroy user data: explicit danger-styled button, soft-delete to .trash/ instead of permanent deletion, and a real Undo notification with a time-limited commit. Close is not the same as destroy.
+
+---
+
+# Destructive Action Checklist
+
+**Scope note:** this checklist covers screen actions — UI + API surfaces that can destroy
+user data (delete spec, archive, discard buffer). Git tree actions on a shared checkout
+(stash, `reset --hard`, `clean -f`, `checkout .`, `restore`, `rebase`, `push --force`,
+`branch -D`, `commit --amend`) are gated in protected-shared-actions-gate — don't
+duplicate that ground here.
+
+**Run this before merging any PR that adds, changes, or routes an action
+that can destroy user data** (delete spec, archive, unpin, discard buffer,
+hard-revert, etc.). Pinning, hiding, or marking "closed" are non-destructive
+and do not require this checklist.
+
+Acceptance: every box ticked, or an inline `dismissed because <reason>`
+note for any box that genuinely does not apply.
+
+## Why this exists
+
+A past idea-discard data-loss incident showed that strong UX *principles*
+(recoverable destructive actions, reversible user actions) are not
+enough — they only prevent data loss if recalled and applied during
+implementation. This protocol turns the principles into an enforceable
+checklist that lives in the PR template / `npm run validate:*` and that
+agents must walk before claiming a destructive-action task done.
+
+## Memory recall (before writing code)
+
+- [ ] `heyspex_recall_memories({ tags: ["destructive"] })`
+- [ ] `heyspex_recall_memories({ tags: ["ux", "ux-principle"] })`
+- [ ] Read any vault memories on destructive-action recovery and Undo.
+
+## UI affordances
+
+- [ ] **Explicit Discard / Delete / Archive button** — labeled with the
+      action verb, styled with `var(--danger)`, positioned away from the
+      primary CTA.
+- [ ] **Close ≠ Destroy.** Backdrop click, Esc, header X, "Close", and
+      "Cancel" all just dismiss the surface. None of them route into a
+      confirmation flow whose primary button is destructive.
+- [ ] **Confirm dialog has a safe default.** The cancel/keep-editing button
+      is default-focused, visually primary, and is not the same control
+      that would also destroy on a second press.
+- [ ] **Confirm copy says what happens and where it goes.** Mentions the
+      trash location and the Undo affordance ("recoverable from the Undo
+      toast that follows").
+- [ ] **Unsaved-changes warning** when closing a dirty editor — separate
+      flow from discard. (Not covered here.)
+
+## API + filesystem
+
+- [ ] **Soft-delete only.** Server moves bytes to
+      `<folder>/.trash/<iso-stamp>-<basename>.<ext>` via `fs.rename`.
+      No `fs.unlink`, `fs.rm`, or equivalent on user data from a request
+      handler.
+- [ ] **DELETE response includes restore info** — `{ trashPath,
+      originalRelPath }` (or analogous fields) so the UI can wire Undo.
+- [ ] **Restore endpoint exists** — POST/PUT that validates both paths
+      resolve inside the vault root, refuses to overwrite an existing
+      file, and `fs.rename`s back.
+- [ ] **Index ignores trash.** Confirm `walkMarkdown` (or equivalent
+      indexer) skips `.trash/` so trashed files don't reappear as ghosts.
+
+## Undo path
+
+- [ ] **Undo toast** with a labeled action button (not just a "Deleted"
+      confirmation), held ≥ 8 seconds.
+- [ ] **Undo actually calls restore endpoint** — wired end-to-end, tested
+      manually at least once.
+- [ ] **Restore dispatches the same `heyspex:spec-updated` event** that
+      external watchers listen for, so list views refresh.
+
+## Tests / verification
+
+- [ ] Manual: open the surface, perform the destructive action, click
+      Undo in the toast, confirm the file is back at its original path.
+- [ ] Manual: open the surface, click backdrop / Esc / Close / Cancel —
+      confirm none of these prompt for or perform deletion.
+- [ ] Optional unit test if the project has them: assert `deleteSpec`
+      moves to `.trash/` and `restoreSpecFromTrash` round-trips.
+
+## After merge
+
+- [ ] Capture any new gotchas as a `memory-lesson` linked to this
+      protocol.
+- [ ] If a *new* destructive surface is introduced, record it in a vault memory.
+
+## How this gate gets enforced
+
+Today: agents must
+walk it before marking the spec `in_review`. The reviewer ticks each box
+in the spec's `.review.md`.
+
+Future automation candidates:
+
+- ESLint rule banning `fs.unlink`/`fs.rm` in `src/app/api/**`.
+- PR template line: "Destructive action? Walk
+  [[destructive-action-checklist]] before requesting review."

package/dist/cli-templates/customer-vault/specs/protocols/memory-protocol.md

@@ -1,46 +1,46 @@
----
-id: HS-PROTO-memory-protocol
-name: Memory Protocol
-type: protocol
-status: open
-priority: 1
-owner: TODO — your name/handle
-created: '2026-05-14T22:47:28-05:00'
-updated: '2026-05-18T19:49:25-05:00'
-scope: vault
-legacy_bd_key: memory-protocol
-tags:
-  - bd-migrated
-  - memory
-  - lessons
-  - decisions
-  - references
-triggers:
-  - memory_creation
-  - close_session
-summary: |
-  Defines the four vault memory subsections (lessons, decisions, references, ui-patterns) and their folder layout. Authoritative rule on when to capture institutional knowledge and how to link it back to the specs it bears on.
----
-
-# Memory Protocol
-
-HeySpex Memory layer (see memory-protocols-subsection-of-memory):
-
-| Subsection | Entity type | Folder |
-| --- | --- | --- |
-| Lessons | `memory-lesson` | `specs/memory/lessons/` |
-| Decisions | `memory-decision` | `specs/memory/decisions/` |
-| References | `memory-reference` | `specs/memory/references/` |
-| Protocols | `protocol` | `specs/protocols/` |
-
-Legacy bd v1 also used `goals/<scope>` — migrated to `memory-reference` where appropriate. Epics/tasks that *create* protocols are not `type: protocol`.
-
-Historical bd commands (`bd-lesson`, `bd-decision`, …) are retired; use vault files + `hs remember` / `hs prime` per HS-DOC-architecture-foundations.
-
-## Change log
-
-| Date | Author | Change |
-| --- | --- | --- |
-| 2026-05-14 | pwher (migrator) | Migrated from bd memory `memory-protocol`. |
-| 2026-05-14 | pwher (with claude opus 4.7) | Backfilled true date (2026-05-10) for created from `.beads/issues.jsonl` git history; previously the migration-date placeholder. |
-| 2026-05-18 | pwher (with claude) | Body updated for HeySpex four Memory subsections including protocols (memory-protocols-subsection-of-memory). |
+---
+id: HS-PROTO-memory-protocol
+name: Memory Protocol
+type: protocol
+status: open
+priority: 1
+owner: TODO — your name/handle
+created: '2026-05-14T22:47:28-05:00'
+updated: '2026-05-18T19:49:25-05:00'
+scope: vault
+legacy_bd_key: memory-protocol
+tags:
+  - bd-migrated
+  - memory
+  - lessons
+  - decisions
+  - references
+triggers:
+  - memory_creation
+  - close_session
+summary: |
+  Defines the four vault memory subsections (lessons, decisions, references, ui-patterns) and their folder layout. Authoritative rule on when to capture institutional knowledge and how to link it back to the specs it bears on.
+---
+
+# Memory Protocol
+
+HeySpex Memory layer (see memory-protocols-subsection-of-memory):
+
+| Subsection | Entity type | Folder |
+| --- | --- | --- |
+| Lessons | `memory-lesson` | `specs/memory/lessons/` |
+| Decisions | `memory-decision` | `specs/memory/decisions/` |
+| References | `memory-reference` | `specs/memory/references/` |
+| Protocols | `protocol` | `specs/protocols/` |
+
+Legacy bd v1 also used `goals/<scope>` — migrated to `memory-reference` where appropriate. Epics/tasks that *create* protocols are not `type: protocol`.
+
+Historical bd commands (`bd-lesson`, `bd-decision`, …) are retired; use vault files + `hs remember` / `hs prime` per HS-DOC-architecture-foundations.
+
+## Change log
+
+| Date | Author | Change |
+| --- | --- | --- |
+| 2026-05-14 | pwher (migrator) | Migrated from bd memory `memory-protocol`. |
+| 2026-05-14 | pwher (with claude opus 4.7) | Backfilled true date (2026-05-10) for created from `.beads/issues.jsonl` git history; previously the migration-date placeholder. |
+| 2026-05-18 | pwher (with claude) | Body updated for HeySpex four Memory subsections including protocols (memory-protocols-subsection-of-memory). |