heyspex 0.1.0 → 0.2.0

package/dist/cli-templates/customer-vault/specs/protocols/canonical-frontmatter-templates.md

@@ -5,11 +5,9 @@ type: protocol
 status: open
 priority: 1
 scope: vault
-owner: pwher
-assisted_by:
-  - Claude Code
-created: "2026-06-13"
-updated: "2026-06-13"
+owner: TODO — your name/handle
+created: '2026-06-13'
+updated: '2026-06-13'
 tags:
   - protocol
   - spec-filing
@@ -21,29 +19,26 @@ triggers:
   - file_epic
   - file_task
 related:
-  - "HS-PROTO-spec-hierarchy"
-  - "[[entity-model]]"
-  - "HS-YXBD-1EM0-EPIC-canonical-spec-filing-surface-templates"
-  - "HS-OFUB-CVOB-EPIC-saas-customer-vault-onboarding"
+  - '[[entity-model]]'
 templates:
   milestone:
     folder: milestones/
-    id_format: "HS-MIL-<4+ random alphanumeric>"
+    id_format: 'HS-MIL-<4+ random alphanumeric>'
     parent_kinds: []
     required_fields: [id, name, summary, type, status, owner, created, updated, epics, target_date]
     optional_fields: [informed_by, tags, related, what_matters, blast_radius]
-    schema_source: "specs/entity-model.md §milestone (lines 497–519)"
+    schema_source: 'specs/entity-model.md §milestone (lines 497–519)'
     frontmatter:
-      id: "{{ID}}"
-      name: "{{NAME}}"
-      summary: ""
+      id: '{{ID}}'
+      name: '{{NAME}}'
+      summary: ''
       type: milestone
       status: open
-      owner: "{{OWNER}}"
-      created: "{{TODAY}}"
-      updated: "{{TODAY}}"
+      owner: '{{OWNER}}'
+      created: '{{TODAY}}'
+      updated: '{{TODAY}}'
       epics: []
-      target_date: ""
+      target_date: ''
       tags:
         - milestone
     body_skeleton: |
@@ -69,38 +64,23 @@ templates:
       <!-- Cross-epic seams at milestone altitude — author at plan ingest ([[spec-hierarchy]] §Expected Breakage). Auto-embedded after H1 by createSpec when omitted; listed here for template parity. -->
   epic:
     folder: epics/
-    id_format: "HS-EPIC-<4+ random alphanumeric>"
+    id_format: 'HS-EPIC-<4+ random alphanumeric>'
     parent_kinds: [milestone]
-    required_fields:
-      [id, name, summary, type, status, owner, created, updated, kind, effort, milestone, pillar]
-    optional_fields:
-      [
-        research,
-        planning_flow,
-        secondary_pillars,
-        depends_on,
-        children,
-        related,
-        tags,
-        requires_user_testing,
-        derived_from,
-        alignment_rationale,
-        affects_paths,
-        blast_radius,
-      ]
-    schema_source: "specs/entity-model.md §epic (lines 455–494; shares the §task base at 392–453)"
+    required_fields: [id, name, summary, type, status, owner, created, updated, kind, effort, milestone, pillar]
+    optional_fields: [research, planning_flow, secondary_pillars, depends_on, children, related, tags, requires_user_testing, derived_from, alignment_rationale, affects_paths, blast_radius]
+    schema_source: 'specs/entity-model.md §epic (lines 455–494; shares the §task base at 392–453)'
     frontmatter:
-      id: "{{ID}}"
-      name: "{{NAME}}"
-      summary: ""
+      id: '{{ID}}'
+      name: '{{NAME}}'
+      summary: ''
       type: epic
       status: open
       kind: feature
       effort: 3
-      owner: "{{OWNER}}"
-      created: "{{TODAY}}"
-      updated: "{{TODAY}}"
-      milestone: "{{PARENT_ID}}"
+      owner: '{{OWNER}}'
+      created: '{{TODAY}}'
+      updated: '{{TODAY}}'
+      milestone: '{{PARENT_ID}}'
       children: []
       tags: []
     body_skeleton: |
@@ -133,42 +113,23 @@ templates:
       ## Change log
   task:
     folder: tasks/
-    id_format: "HS-TASK-<4+ random alphanumeric>"
+    id_format: 'HS-TASK-<4+ random alphanumeric>'
     parent_kinds: [epic, task]
     required_fields: [id, name, summary, type, status, owner, created, updated, kind, effort]
-    optional_fields:
-      [
-        parent,
-        depends_on,
-        blocks,
-        related,
-        children,
-        tags,
-        requires_user_testing,
-        assignee,
-        affects_paths,
-        target,
-        test,
-        suggested_model,
-        suggested_machine,
-        recommended_num_ctx,
-        estimated_context_tokens,
-        context_files,
-        fit_assessment,
-      ]
-    schema_source: "specs/entity-model.md §task (lines 392–453)"
+    optional_fields: [parent, depends_on, blocks, related, children, tags, requires_user_testing, assignee, affects_paths, target, test, suggested_model, suggested_machine, recommended_num_ctx, estimated_context_tokens, context_files, fit_assessment]
+    schema_source: 'specs/entity-model.md §task (lines 392–453)'
     frontmatter:
-      id: "{{ID}}"
-      name: "{{NAME}}"
-      summary: ""
+      id: '{{ID}}'
+      name: '{{NAME}}'
+      summary: ''
       type: task
       status: open
       kind: feature
       effort: 3
-      owner: "{{OWNER}}"
-      created: "{{TODAY}}"
-      updated: "{{TODAY}}"
-      parent: "{{PARENT_ID}}"
+      owner: '{{OWNER}}'
+      created: '{{TODAY}}'
+      updated: '{{TODAY}}'
+      parent: '{{PARENT_ID}}'
       tags:
         - near-term
     body_skeleton: |
@@ -203,31 +164,19 @@ templates:
       ## References
   research:
     folder: research/
-    id_format: "HS-RES-<NNN> (zero-padded numeric, server auto-increments)"
+    id_format: 'HS-RES-<NNN> (zero-padded numeric, server auto-increments)'
     parent_kinds: []
     required_fields: [id, name, type, status, owner, created, updated]
-    optional_fields:
-      [
-        enhances,
-        sources_captures,
-        spawned_epics,
-        enhances_epics,
-        split_into,
-        split_from,
-        planning_flow,
-        bound_epic,
-        tags,
-        related,
-      ]
-    schema_source: "specs/entity-model.md §research (lines 761–793)"
+    optional_fields: [enhances, sources_captures, spawned_epics, enhances_epics, split_into, split_from, planning_flow, bound_epic, tags, related]
+    schema_source: 'specs/entity-model.md §research (lines 761–793)'
     frontmatter:
-      id: "{{ID}}"
-      name: "{{NAME}}"
+      id: '{{ID}}'
+      name: '{{NAME}}'
       type: research
       status: open
-      owner: "{{OWNER}}"
-      created: "{{TODAY}}"
-      updated: "{{TODAY}}"
+      owner: '{{OWNER}}'
+      created: '{{TODAY}}'
+      updated: '{{TODAY}}'
       tags:
         - research
     body_skeleton: |
@@ -247,21 +196,21 @@ templates:
       ## Sources
   memory-lesson:
     folder: memory/lessons/
-    id_format: "HS-LES-<slug>"
+    id_format: 'HS-LES-<slug>'
     parent_kinds: []
     required_fields: [id, name, type, status, owner, created, updated, topic, observed]
     optional_fields: [related, evidence, tags]
-    schema_source: "specs/entity-model.md §memory-lesson (lines 604–615)"
+    schema_source: 'specs/entity-model.md §memory-lesson (lines 604–615)'
     frontmatter:
-      id: "{{ID}}"
-      name: "{{NAME}}"
+      id: '{{ID}}'
+      name: '{{NAME}}'
       type: memory-lesson
       status: open
-      owner: "{{OWNER}}"
-      created: "{{TODAY}}"
-      updated: "{{TODAY}}"
-      topic: "{{SLUG}}"
-      observed: "{{TODAY}}"
+      owner: '{{OWNER}}'
+      created: '{{TODAY}}'
+      updated: '{{TODAY}}'
+      topic: '{{SLUG}}'
+      observed: '{{TODAY}}'
     body_skeleton: |
       # {{NAME}}
 
@@ -270,23 +219,23 @@ templates:
       ## Fix
   memory-decision:
     folder: memory/decisions/
-    id_format: "HS-DEC-<slug>"
+    id_format: 'HS-DEC-<slug>'
     parent_kinds: []
     required_fields: [id, name, type, status, owner, created, updated, topic, decided, deciders]
     optional_fields: [supersedes, evidence, related, tags]
-    schema_source: "specs/entity-model.md §memory-decision (lines 617–629)"
+    schema_source: 'specs/entity-model.md §memory-decision (lines 617–629)'
     frontmatter:
-      id: "{{ID}}"
-      name: "{{NAME}}"
+      id: '{{ID}}'
+      name: '{{NAME}}'
       type: memory-decision
       status: open
-      owner: "{{OWNER}}"
-      created: "{{TODAY}}"
-      updated: "{{TODAY}}"
-      topic: "{{SLUG}}"
-      decided: "{{TODAY}}"
+      owner: '{{OWNER}}'
+      created: '{{TODAY}}'
+      updated: '{{TODAY}}'
+      topic: '{{SLUG}}'
+      decided: '{{TODAY}}'
       deciders:
-        - "{{OWNER}}"
+        - '{{OWNER}}'
     body_skeleton: |
       # {{NAME}}
 
@@ -295,41 +244,41 @@ templates:
       ## Rationale
   memory-reference:
     folder: memory/references/
-    id_format: "HS-REF-<slug>"
+    id_format: 'HS-REF-<slug>'
     parent_kinds: []
     required_fields: [id, name, type, status, owner, created, updated, topic]
     optional_fields: [url, evidence, related, tags]
-    schema_source: "specs/entity-model.md §memory-reference (lines 631–641)"
+    schema_source: 'specs/entity-model.md §memory-reference (lines 631–641)'
     frontmatter:
-      id: "{{ID}}"
-      name: "{{NAME}}"
+      id: '{{ID}}'
+      name: '{{NAME}}'
       type: memory-reference
       status: open
-      owner: "{{OWNER}}"
-      created: "{{TODAY}}"
-      updated: "{{TODAY}}"
-      topic: "{{SLUG}}"
+      owner: '{{OWNER}}'
+      created: '{{TODAY}}'
+      updated: '{{TODAY}}'
+      topic: '{{SLUG}}'
     body_skeleton: |
       # {{NAME}}
 
       Brief context for why this reference matters.
   memory-ui-pattern:
     folder: memory/ui-patterns/
-    id_format: "HS-UIP-<slug>"
+    id_format: 'HS-UIP-<slug>'
     parent_kinds: []
     required_fields: [id, name, type, status, owner, created, updated, topic, documented]
     optional_fields: [related, evidence, tags]
-    schema_source: "specs/entity-model.md §memory-ui-pattern (lines 643–653)"
+    schema_source: 'specs/entity-model.md §memory-ui-pattern (lines 643–653)'
     frontmatter:
-      id: "{{ID}}"
-      name: "{{NAME}}"
+      id: '{{ID}}'
+      name: '{{NAME}}'
       type: memory-ui-pattern
       status: open
-      owner: "{{OWNER}}"
-      created: "{{TODAY}}"
-      updated: "{{TODAY}}"
-      topic: "{{SLUG}}"
-      documented: "{{TODAY}}"
+      owner: '{{OWNER}}'
+      created: '{{TODAY}}'
+      updated: '{{TODAY}}'
+      topic: '{{SLUG}}'
+      documented: '{{TODAY}}'
     body_skeleton: |
       # {{NAME}}
 
@@ -342,21 +291,21 @@ templates:
       ## Implementation
   review:
     folder: reviews/
-    id_format: "HS-REV-<parent-suffix> (suffix = parent id segment [2]; slug rides only in the filename)"
+    id_format: 'HS-REV-<parent-suffix> (suffix = parent id segment [2]; slug rides only in the filename)'
     parent_kinds: [task, epic, milestone]
     required_fields: [id, name, type, status, owner, created, updated, parent]
     optional_fields: [reviews, deliberation_record]
-    schema_source: "specs/entity-model.md §review (lines 679–705)"
+    schema_source: 'specs/entity-model.md §review (lines 679–705)'
     frontmatter:
-      id: "{{ID}}"
-      name: "{{NAME}}"
+      id: '{{ID}}'
+      name: '{{NAME}}'
       type: review
       status: open
-      owner: "{{OWNER}}"
-      created: "{{TODAY}}"
-      updated: "{{TODAY}}"
-      parent: "{{PARENT_ID}}"
-      reviews: "{{PARENT_ID}}"
+      owner: '{{OWNER}}'
+      created: '{{TODAY}}'
+      updated: '{{TODAY}}'
+      parent: '{{PARENT_ID}}'
+      reviews: '{{PARENT_ID}}'
     body_skeleton: |
       # Review — {{NAME}}
 
@@ -372,37 +321,20 @@ templates:
       ## Decision: close or reopen
   agent:
     folder: agents/
-    id_format: "HS-AGENT-<4+ random alphanumeric>"
+    id_format: 'HS-AGENT-<4+ random alphanumeric>'
     parent_kinds: []
     required_fields: [id, name, type, status, owner, created, updated, role]
-    optional_fields:
-      [
-        description,
-        goal,
-        model,
-        allowed_tools,
-        disallowed_tools,
-        procedures,
-        handoffs,
-        guardrails,
-        lane,
-        isolation,
-        color,
-        owned_paths,
-        source_attribution,
-        related,
-        tags,
-      ]
-    schema_source: "specs/entity-model.md §agent"
+    optional_fields: [description, goal, model, allowed_tools, disallowed_tools, procedures, handoffs, guardrails, lane, isolation, color, owned_paths, source_attribution, related, tags]
+    schema_source: 'specs/entity-model.md §agent'
     frontmatter:
-      id: "{{ID}}"
-      name: "{{NAME}}"
+      id: '{{ID}}'
+      name: '{{NAME}}'
       type: agent
       status: open
-      owner: "{{OWNER}}"
-      role: "{{NAME}}"
-      created: "{{TODAY}}"
-      updated: "{{TODAY}}"
+      owner: '{{OWNER}}'
+      role: '{{NAME}}'
+      created: '{{TODAY}}'
+      updated: '{{TODAY}}'
       owned_paths: []
       tags:
         - agent
@@ -420,19 +352,19 @@ templates:
       ## Guardrails
   pillar:
     folder: pillars/
-    id_format: "HS-PILR-<slug> (slug-only; owner-curated canonical pillars share id == basename)"
+    id_format: 'HS-PILR-<slug> (slug-only; owner-curated canonical pillars share id == basename)'
     parent_kinds: []
     required_fields: [id, name, type, status, owner, created, updated, canonical, secondary_pillars]
     optional_fields: [library_tier, version, last_edited_at, related, tags]
-    schema_source: "specs/entity-model.md §pillar"
+    schema_source: 'specs/entity-model.md §pillar'
     frontmatter:
-      id: "{{ID}}"
-      name: "{{NAME}}"
+      id: '{{ID}}'
+      name: '{{NAME}}'
       type: pillar
       status: perpetual
-      owner: "{{OWNER}}"
-      created: "{{TODAY}}"
-      updated: "{{TODAY}}"
+      owner: '{{OWNER}}'
+      created: '{{TODAY}}'
+      updated: '{{TODAY}}'
       canonical: true
       secondary_pillars: []
       tags:
@@ -449,6 +381,7 @@ templates:
       ## Through-line across milestones
 summary: |
   Canonical copy-paste frontmatter templates for every vault entity kind (milestone, epic, task, review) with required fields, optional fields, and body skeletons; the source of truth for heyspex_file_spec and POST /api/specs.
+
 ---
 
 # Canonical frontmatter templates per entity kind
@@ -515,7 +448,7 @@ Slug id (`HS-UIP-<slug>`). Required: `topic` + `documented`. Reusable console in
 ## Out of scope
 
 - **Captures (`type: capture`).** Session-based — driven by `heyspex_active_capture` / `heyspex_update_capture` with `content_buffer` patching, focus pinning, and multi-message accumulation, none of which a single template stamp can represent. `POST /api/specs` rejects `type: capture` with a 400 pointing at the capture flow (user-memory `feedback_capture_workflow_for_captures`).
-- **L1 / ADR / planning-flow / branch-brief / business-\* kinds.** Filed through their own dedicated flows; their schemas live in [[entity-model]] but are not part of the universal filing surface this protocol backs. (Pillars are now part of this surface — see the `pillar` template above.)
+- **L1 / ADR / planning-flow / branch-brief / business-* kinds.** Filed through their own dedicated flows; their schemas live in [[entity-model]] but are not part of the universal filing surface this protocol backs. (Pillars are now part of this surface — see the `pillar` template above.)
 
 ## Drift gate
 
@@ -523,9 +456,9 @@ Adding or removing a kind here changes the file, so `npm run build:procedure-cat
 
 ## Change log
 
-| Date       | Author                                              | Change                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
-| ---------- | --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| 2026-06-13 | pwher (with Claude Opus 4.8)                        | Filed as the canonical, fetchable home for per-kind frontmatter templates.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
-| 2026-06-21 | Claude Code · claude-sonnet-4-6 (with pwher)        | Moved `summary` from `optional_fields` into `required_fields` and added `summary: ''` to the frontmatter stamp for milestone, epic, and task. Root cause: the stamp for these three kinds did not include a `summary:` placeholder, so agents and automated flows (e.g. promote-research) that stamp from the template produced specs with no summary field and no visible prompt to fill one in. Matching the spec-summary-authoring policy that summary is an authoring step of filing, not an optional afterthought.                                                                                                                                                                                                                                                                                             |
-| 2026-06-23 | Cursor · session `local`                            | Added `agent` template with `owned_paths:`; `affects_paths` on epic/task optional_fields. Per HS-ZMAQ-M15C-TASK-declare-owned-path-globs-on-agent-identi.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| Date | Author | Change |
+|---|---|---|
+| 2026-06-13 | pwher (with Claude Opus 4.8) | Filed as the canonical, fetchable home for per-kind frontmatter templates. |
+| 2026-06-21 | Claude Code · claude-sonnet-4-6 (with pwher) | Moved `summary` from `optional_fields` into `required_fields` and added `summary: ''` to the frontmatter stamp for milestone, epic, and task. Root cause: the stamp for these three kinds did not include a `summary:` placeholder, so agents and automated flows (e.g. promote-research) that stamp from the template produced specs with no summary field and no visible prompt to fill one in. Matching the [[spec-summary-authoring]] policy that summary is an authoring step of filing, not an optional afterthought. |
+| 2026-06-23 | Cursor · session `local` | Added `agent` template with `owned_paths:`; `affects_paths` on epic/task optional_fields. Per HS-ZMAQ-M15C-TASK-declare-owned-path-globs-on-agent-identi. |
 | 2026-06-25 | Claude Opus 4.8 [1m] · session `local` (with pwher) | Added the **intended-outcome cascade** section to the `body_skeleton` of research (`## Conclusion & intended outcome`), milestone, epic, and task (`## Intended outcome`). Each level **re-derives** the parent's outcome (translate, don't copy) and names its **mechanism of contribution** + an explicit ↑ link; the task-level outcome is expressed as monitorable+controllable conditions that seed `## Acceptance criteria`. Grounded in HS-K4D4-2I29-RES-outcome-cascade-through-a-requirements-h (GORE/KAOS HOW-down/WHY-up refinement + OKR translation-not-cascade). Companion edits: `research-capture-protocol`, `spec-hierarchy`, `plan-ingest-agent-workflow`, and the `promote-capture.mjs` / `promote-research.mjs` / task materializers. Owner-directed. Re-run `npm run build:procedure-catalog`. |

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

@@ -0,0 +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."

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

@@ -4,9 +4,9 @@ name: Memory Protocol
 type: protocol
 status: open
 priority: 1
-owner: pwher
-created: "2026-05-14T22:47:28-05:00"
-updated: "2026-05-18T19:49:25-05:00"
+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:
@@ -20,29 +20,27 @@ triggers:
   - 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.
-related:
-  - "HS-T4P3-7VZH-RES-governing-an-unmanaged-891-file-memory"
 ---
 
 # 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/`  |
+| 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/`         |
+| 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`.
+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`.                                                                                       |
+| 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).                    |
+| 2026-05-18 | pwher (with claude) | Body updated for HeySpex four Memory subsections including protocols (memory-protocols-subsection-of-memory). |